[Rd] Suggested change to documentation

[Timothy H. Keitt]

Actually, I noticed the latest version of prompt() nicely comments the 
keyword entry with "ONLY ONE KEYWORD PER ENTRY..." or something like 
that, so its probably not a big deal.  Just remember, we read these 
things at break-neck speed (at least I don't have time to carefully 
digest complicated documentation), so it has to be really simple.  I got 
tripped up with "keyword entry" thinking that there were multiple 
entries per \keyword{} section.  Perhaps "Each \keyword 
(section|stanza|clause|?) can contain one and only one keyword [from the 
database...].  Use multiple \keyword ?? if more than one keyword is 
desired."  Even better, put several keywords in one of the examples.

Tim

Prof Brian D Ripley wrote:

>On Tue, 28 Aug 2001, Timothy H. Keitt wrote:
>
>>Its not clear from the documentation whether one should do
>>
>>\keyword[key1, key2}
>>
>>or
>>
>>\keyword{key1}
>>\keyword{key2}
>>
>>in .Rd files.  I believe the latter is correct.  (At least 'R CMD check'
>>complains when given the first version.)  It would help to make this
>>explicit in the R extension writing docs.
>>
>
>The second is indeed correct.
>
>Where is this unclear in R-exts.texi?  That says
>
>@item \keyword@{@var{key}@}
>Each @code{\keyword} entry should specify one of the standard keywords
>(as listed in the file @file{$R_HOME/doc/KEYWORDS.db}).  There must be
>at least one @code{\keyword} entry, but can be more that one if the @R{}
>object being documented falls into more than one category.
>
>Note `one of'.  If you can point us at the problem, we can fix it in time
>for 1.3.1, but this has come up before and we've not located anything that
>might lead to the idea that the first is correct.  (It is \keyword{} not
>\keywords{}, too.)
>


-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._