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

[Duncan Murdoch]

On 13/07/2016 4:04 PM, Enrico Schumann wrote:
> On Wed, 13 Jul 2016, "Boylan, Ross" <Ross.Boylan at ucsf.edu> writes:
>
>> 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
>
>
> I think this was discussed very recently on R-help:
>
> https://stat.ethz.ch/pipermail/r-help/2016-June/439867.html

I seem to recall that links from PDF files into the help system don't 
work, because those *must* be relative links, and I think PDF files 
don't support relative links.  (It is possible to set up your system so 
you can use absolute links by always running the help system on the same 
port, but you can't count on your users to be doing that.)

So Ross is probably out of luck if he's using Sweave.

Duncan Murdoch