[Rd] Indexing request

[Prof Brian Ripley]

On Fri, 7 Jan 2011, Duncan Murdoch wrote:

> On 11-01-07 5:52 AM, Prof Brian Ripley wrote:
>> On Fri, 7 Jan 2011, Duncan Murdoch wrote:
>> 
>>> On 11-01-07 12:08 AM, David Winsemius wrote:
>>>> 
>>>> I just tried ?Constants at the console and was disappointed that the
>>>> so-named base help page would not come up.
>>>>
>>>>    >   ?Constants
>>>> No documentation for 'Constants' in specified packages and libraries:
>>>> you could try '??Constants'
>>>> 
>>>> Seems like there should have been a match. I was looking for the month
>>>> abbreviations, failing to hit the right name 4 times and then failing
>>>> 3 more times on variations of what I remembered to be the name of that
>>>> page and finally ended up typing:
>>>> 
>>> 
>>> I do see that page as the first hit if I follow the advice and type
>>> ??Constants, though there seems to be a problem with the OSX help system 
>>> and
>>> that particular page.
>>> 
>>> But I agree with you, and will add Constants to the index.
>> 
>> I am not so sure: Constants seems rather to be a \concept entry, and
>> those are (deliberately) not searched by help()/?.  (There is also the
>> question of capitalization: help() looks for exact matches.)
>
> I think David's argument convinced me:  he had an imperfect memory of the 
> page, but it included the name (which is displayed prominently when you see 
> it).  Pages where the name is not an alias are so uncommon that most people 
> don't realize that the name is not searched by help().
>
>
>> 
>>> For future reference:  Every help page has:
>>> 
>>> - a name (in this case "Constants"), which is what is displayed at the top
>>> of the help page.  It also determines the order in which pages are 
>>> collated
>>> into the full manual, if you build one of those.
>>> - a title (which is a one-line explanation of the page); here it is
>>> "Built-in constants".  That is shown in the results from ??Constants.
>>> - a number of aliases, which are indexed.  Those are the things which work
>>> with a single ?.  In this case they are "LETTERS", "letters", "month.abb",
>>> "month.name", and "pi".
>>> - a filename (which you'll never see), in this case it's
>>> src/library/base/man/Constants.Rd.  That's the file to edit to make this
>>> change.
>>> 
>>> In most cases the name is repeated as an alias, but for some reason
>>> (flexibility?) that's not a requirement, and is not always the case, as 
>>> here.
>>> If I were designing the system I would say the name is automatically an
>>> alias, but perhaps there are cases where that would be undesirable.
>> 
>> That was the case a decade ago, and it was found to be undesirable for
>> various reasons (one was the restrictions on the value for \name,
>> which used to be more severe than they are now).  Another was that
>> where there were multiple matches the user was only offered one, so a
>> badly chosen \name in a contributed package could mask completely an
>> \alias in the standard system.
>
> The help system can now handle duplicates, can't it?  Check will warn about 
> duplicate aliases within a package, but alias conflicts across packages work 
> fine.

Yes, it now offers a menu of choices when there are multiple exact 
matches.  But AFAIR that was not the case when \name was removed as an 
automatic alias.

>
> Duncan
>
>> 
>>> I'll add it as an alias here.  I've passed on a message about the problem 
>>> on
>>> that page, and it should eventually be fixed.
>>> 
>>> Duncan Murdoch
>>> 
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> 
>> 
>

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595