Suggested change to documentation

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

Brian D. Ripley,                  ripley@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 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

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

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

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