From murdoch.duncan at gmail.com  Fri Jan  7 13:41:42 2011
From: murdoch.duncan at gmail.com (Duncan Murdoch)
Date: Fri, 07 Jan 2011 07:41:42 -0500
Subject: [Rd] Indexing request
In-Reply-To: <alpine.LFD.2.00.1101071027310.23134@toucan.stats.ox.ac.uk>
References: <6A5820A7-03B1-4995-A8B7-846850319312@comcast.net>
	<4D26E66B.8020905@gmail.com>
	<alpine.LFD.2.00.1101071027310.23134@toucan.stats.ox.ac.uk>
Message-ID: <4D270A06.3020708@gmail.com>

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.

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
>>
>



[Rd] Indexing request
Duncan Murdoch