From maechler at stat.math.ethz.ch  Fri Aug 27 22:54:19 2004
From: maechler at stat.math.ethz.ch (Martin Maechler)
Date: Fri Aug 27 22:54:23 2004
Subject: [Rd] author field in Rd files
In-Reply-To: <1093470818.15819.18.camel@workstation-3>
References: <1093470818.15819.18.camel@workstation-3>
Message-ID: <16687.40827.558208.989350@gargle.gargle.HOWL>

Since nobody else has reacted yet:

>>>>> "Timothy" == Timothy H Keitt <tkeitt@mail.utexas.edu>
>>>>>     on Wed, 25 Aug 2004 16:53:39 -0500 writes:

    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


[Rd] author field in Rd files
Martin Maechler