> Duncan Murdoch wrote:
>> On 6/7/2005 11:12 AM, Robert Gentleman wrote:
>>
>>>
>>> Robin Hankin wrote:
>>>
>>>> My 0.02:
>>>>
>>>> I use Misc.Rd for the purpose that Duncan suggests. I put things
>>>> like details and rationale for package
>>>> organization, pointers to the most important function(s) in the
>>>> package, and perhaps function descriptors
>>>> for ubiquitous functions that don't warrant their own helppage, but
>>>> need documentation [in
>>>> the case of gsl, this would be strictify() and process.args(), which
>>>> every user needs to know].
>>>>
>>>> It would be *great* to be required to put in "package.gsl.R" (or
>>>> should that be "gsl.package.Rd"?)
>>>> for this purpose. Then maybe R CMD check could check for its
>>>> presence and throw a wobbly
>>>> if it isn't there.
>>>>
>>>
>>> Hi,
>>> Well, I pretty strenuously object. That is just what vignettes are
>>> for and the last thing I need is more wobbly's from R CMD check.
>>>
>>> Function documentation should document functions. If you want to
>>> document something more substantial then please use the tools already
>>> provided to do that - and if you don't want to, and you want to make
>>> use of the tools for function documentation in some other way please
>>> don't try to impose your version of what should happen on others.

>
> Best wishes,
> Robert
>
>
>> If we had a way to link vignettes into the help system, then I'd think
>> it would be perfectly acceptable for ?package to pop up a vignette for
>> the package. However, right now we have too many different types of
>> ways to display help, and not all of them are capable of displaying
>> vignettes.
>>
>> Duncan Murdoch
>>
>>

>>>
>>> Best wishes
>>> Robert
>>>
>>>> Some packages have so much material that it's difficult to know
>>>> where the "meat" of the functionality lies,
>>>> and Duncan's suggestion would help greatly in these circumstances.
>>>>
>>>> best wishes
>>>>
>>>> rksh
>>>>
>>>>
>>>> On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote:
>>>>
>>>>> Kurt Hornik wrote:
>>>>>
>>>>>>>>>>> Henrik Bengtsson writes:
>>>>>>>
>>>>>>>
>>>>>>> Hi,
>>>>>>> I would like to suggest a standard where all packages provide an
>>>>>>> Rd page with the same name (or aliased) as the name of package so
>>>>>>> that help(<package name>) or ?<package name> is always here. This
>>>>>>> especially of interest to large packages with a large package
>>>>>>> index. This page could explain the package in general and gives
>>>>>>> some hints on how to start - not like extensive vignettes, but
>>>>>>> just to get started, e.g. list the "most important" functions.
>>>>>>> This page could typically contain information that is in the
>>>>>>> DESCRIPTION file (which contains valuable information hardly every
>>>>>>> accessed by a general user), such as who is the maintainer, how to
>>>>>>> report bugs and so on.
>>>>>
>>>>>
>>>>>
>>>>> I think this is a good idea. One minor problem is that for some
>>>>> packages that topic name is already in use for a function (e.g.
>>>>> boot). For that reason, I'd suggest that there *also* be an alias
>>>>> called "package.<package name>", and the <package name> topic should
>>>>> link to it.
>>>>>
>>>>>> How would this be different from the results of
>>>>>> help(package = <package name>)
>>>>>> ?
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> 1. It would work with ?, like other help topics.
>>>>>
>>>>> 2. It would give an overview. It's possible to do that in
>>>>> DESCRIPTION or INDEX, but you don't get the same style as for other
>>>>> help files (e.g. no links to other topics, at least in Windows).
>>>>>
>>>>>
>>>>>
>>>>> We should work out what the topic headings should be and extend
>>>>> package.skeleton() and prompt() to write a bare-bones file that
>>>>> suggests the questions that need to be answered in the file. The
>>>>> headings I'd suggest are:
>>>>>
>>>>> \name
>>>>> \title
>>>>> \alias
>>>>> \description (longer than the typical entry in the DESCRIPTION file)
>>>>> \details (Should give a short guide to the main functions, should
>>>>> point out the existence of external documentation like vignettes, etc.)
>>>>> \author (could also describe maintainer, if different)
>>>>> \references
>>>>> \seealso (Should give references to related packages)
>>>>> \examples
>>>>> \keywords
>>>>>
>>>>> There is some duplication of material from DESCRIPTION, but usually
>>>>> this should be longer and more reader-friendly than that file.
>>>>>
>>>>> I'd be happy to write the description of this in R Extensions, and
>>>>> write the changes to prompt(), if we have agreement that this file
>>>>> should be mandatory in 2.2.x or 2.3.x, and you'll write the checks
>>>>> for it. (I think the check should just be for existence of aliases
>>>>> <package name> and package.<package name>, and could perhaps just
>>>>> give a warning in 2.2.x.)
>>>>>
>>>>> Duncan Murdoch
>>>>>
>>>>> ______________________________________________
>>>>> R-devel@stat.math.ethz.ch mailing list
>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel>>>>>
>>>>>
>>>> --
>>>> Robin Hankin
>>>> Uncertainty Analyst
>>>> National Oceanography Centre, Southampton
>>>> European Way, Southampton SO14 3ZH, UK
>>>> tel 023-8059-7743
>>>>
>>>> ______________________________________________
>>>> R-devel@stat.math.ethz.ch mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel>>>>