Re: [Rd] html help fails for named vector objects (PR#9927)

From: Prof Brian Ripley <ripley_at_stats.ox.ac.uk>
Date: Sun, 23 Sep 2007 12:15:31 +0100 (BST)

On Sun, 23 Sep 2007, P Ehlers wrote:

> There seems also to be a difference between the way 'help()' and '?'
> handle 'topic' in some cases.

Yes, that is intentional. I didn't mention it (after deliberation) as the bug report was about help(htmlhelp=TRUE) and not ?. I did mention clarifying the documentation, which in my draft says

    topic: usually, a name or character string specifying the topic for

           which help is sought.

           For 'help', if 'topic' is a length-one character vector, the
           topic is taken to be the value of the only element.

           For '?' the 'topic' argument may also be a function call, to
           ask for documentation on a corresponding method.  See the
           section on S4 method documentation.

but I am still tweaking.

> Consider:
> lm <- "aov"
>
> The following all bring up help for 'lm':
> ?lm
> ?"lm"
> help("lm")
>
> This opens help for 'aov':
> help(lm)
>
> It seems that "?" doesn't care about quoting, but "help" does.
> Did I miss something in the docs?

No, as it is not in the docs as yet. The help page described what happens for ?, not for help, e.g.

           The 'topic' argument may also be a function call, to ask for
           documentation on a corresponding method.  See the section on
           method documentation.

applies only to ? .

> (If it matters, I'm using options(chmhelp=TRUE).)

It will not if utils::help is being called.

>
>> sessionInfo()
> R version 2.6.0 beta (2007-09-18 r42895)
> i386-pc-mingw32
>
> locale:
> LC_COLLATE=English_Canada.1252; [snip]
>
> attached base packages:
> [1] stats graphics grDevices utils datasets methods base
>
> - Peter Ehlers
>
> Prof Brian Ripley wrote:
>> On a normal R help system any version of help(letters) tries to give you
>> help on a, b, etc. This is intentional (although the documentation is
>> unclearly worded), and has been the case since at least R 2.0.0.
>> Some versions of help will display only the first topic.
>>
>> If help(letters, htmlhelp=FALSE) does something else on your system, that
>> is a MacOS-specific bug since the topic selected should not depend on the
>> optional arguments.
>>
>> What is unclear from the documentation is what should happen with
>>
>> help(c("help", "help.search"))
>>
>> It seems that for text help you get the first, for htmlhelp both.
>>
>> There are two things we could do to help (apart from clarifying the
>> documentation):
>>
>> 1) If 'topic' is neither a name nor a character vector (e.g. an expression
>> like the last example) give an explicit error.
>>
>> 2) if topic is a character vector of length > 1, use the name.
>>
>>
>> On Sun, 23 Sep 2007, John.Maindonald_at_anu.edu.au wrote:
>>
>>> help(letters, htmlhelp=TRUE) fails.
>>>
>>> Under the Mac OSX gui, the message is 'Help for the topic "a" was not
>>> found.' Under the version documented below, and under Windows, the
>>> message is
>>>
>>> "No documentation for 'a' in specified packages and libraries:"
>>> repeated for all the elements of letters, then followed by
>>> "you could try 'help.search("a")'",
>>> again repeated for all elements of letters.
>>>
>>> The outcome seems similar for any character vector (including matrix)
>>> object, e.g. the matrix 'primateDNA' in the DAAGbio package.
>>>
>>> The following have the expected result
>>> help("letters", htmlhelp=TRUE)
>>> help(letters, htmlhelp=FALSE)
>>
>> But the documented and actual results are the same, and different in the
>> two cases.
>>
>>> The same result is obtained with R-2.5.1.
>>>
>>>
>>> --please do not edit the information below--
>>>
>>> Version:
>>> platform = i386-apple-darwin8.10.1
>>> arch = i386
>>> os = darwin8.10.1
>>> system = i386, darwin8.10.1
>>> status = beta
>>> major = 2
>>> minor = 6.0
>>> year = 2007
>>> month = 09
>>> day = 22
>>> svn rev = 42941
>>> language = R
>>> version.string = R version 2.6.0 beta (2007-09-22 r42941)
>>>
>>> Locale:
>>> C
>>>
>>> Search Path:
>>> .GlobalEnv, package:testpkg, package:stats, package:graphics,
>>> package:grDevices, package:utils, package:datasets, package:methods,
>>> Autoloads, package:base
>>>
>>> John Maindonald email: john.maindonald_at_anu.edu.au
>>> phone : +61 2 (6125)3473 fax : +61 2(6125)5549
>>> Centre for Mathematics & Its Applications, Room 1194,
>>> John Dedman Mathematical Sciences Building (Building 27)
>>> Australian National University, Canberra ACT 0200.
>>>
>>> ______________________________________________
>>> 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

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Sun 23 Sep 2007 - 11:18:51 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Mon 24 Sep 2007 - 14:41:14 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.