Skip to content

author field in Rd files

2 messages · Tim Keitt, Martin Maechler

Original
Tim Keitt
# 
I noticed in the extension manual that the \author{} entry should refer
to the author of the Rd file and not the code documented. I had always
interpreted it as the author of the code, not the documentation. I
wonder if others also find this ambiguous. Its generally not an issue,
except when there is a third party writing documentation. It looks like
they wrote all the code. Would it make sense to have two entries, one
for the documentation author and one for the code author if different?

Tim
1 day later
Martin Maechler
# 
Since nobody else has reacted yet:
Timothy> I noticed in the extension manual that the
    Timothy> \author{} entry should refer to the author of the
    Timothy> Rd file and not the code documented. I had always
    Timothy> interpreted it as the author of the code, not the
    Timothy> documentation. I wonder if others also find this
    Timothy> ambiguous.

I tend to agree with you.  Very often the author means both the
author of the R object and the help page.
In the few other cases, for me, I was the help page author
(rather than the other way around) and I think I usually have
done what you suggest:  Showed the author of the code and
sometimes also mentioned myself (as docu-author), but typically
only if I had also improved on the code.

    Timothy> Its generally not an issue, except when there is a
    Timothy> third party writing documentation. It looks like
    Timothy> they wrote all the code. Would it make sense to
    Timothy> have two entries, one for the documentation author
    Timothy> and one for the code author if different?

I think in such a case \author{..} should contain both the code
and documentation authors.
In a package with many help pages, a possibility is also to
 specify  \author{..} and \references{....} in only a few help
pages and for the others, inside the   \seealso{...}   section
have a sentence pointing to the main help page(s), such as
\seealso{ 
	  ..............
	  For references etc, \code{\link{<mainpage>}}.
}


Regards,
Martin Maechler