[R-pkg-devel] relation between vignettes and help files

[Mark van der Loo]

Afaik the only way to link to a vignette from the help file is to instruct
the reader to do something like

vignette('intro','mypkg')

On the R command-line.

In general, the Rd files describe the public API of your pkg. Each exported
function should have a help file that ideally can be read and understood in
isolation. The vignettes can provide walk-throughs for tasks that require a
sequence of functions to be called. This helps the user to get around the
package by focusing on tasks.

Although you will probably duplicate a little information, try to focus  on
subject matter in the vignette, while focusing on the technical aspects in
the Rd files.

Hope that helps,
Mark

On Wed, Jul 13, 2016, 21:29 Boylan, Ross <Ross.Boylan at ucsf.edu> wrote:

> I have two questions, one substantive and one technical, about the
> relation between vignettes and help files.  By "help files" I mean the
> regular .Rd files.
>
> Substantively, to what extent should material be duplicated between the
> help files and the vignette?  For example, my vignette includes some output
> summarizing the analysis.  The output has many different kinds of
> information, and the details about what they mean are in the help for the
> function generating the output.  Any advice on how much of that information
> to put in the vignette?.  The vignette could, of course, say to see the
> help for the function for details.
>
> It seems natural to me  to have the information in both  places, except
> that doing so invites inconsistencies as the code changes, if not
> immediately.
>
> The leads to the the technical question: is there a way to provide links
> to the help from the vignette?  I'm using Sweave.  And, similarly, is there
> a way to reference the vignettes from the help?  In particular, it seems
> natural to reference the vignette from the package help.
>
> Thanks.
> Ross Boylan
> ______________________________________________
> R-package-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]