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

[Duncan Murdoch]

On 15/07/2016 8:32 AM, Martin Maechler wrote:
>>>>>> Duncan Murdoch <murdoch.duncan at gmail.com>
>>>>>>     on Wed, 13 Jul 2016 16:44:41 -0400 writes:
>
>     > 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.
>
> Yes, I think so too (and the above R-help thread ends up slightly wrongly).
>
> It is even worse, isn't it: Nowadays html help pages are (almost)
> always created *dynamically* via R's help() or help.start();
> For my setup of 1000s of packages in my libraries in .libPaths(),
> generating all the html pages is too costly
> [I think Rstudio is now smart and does this in the background
>  for its *own* package data base ?? -- I wish we would enable to
>  do this easily in base R !
>
> and I am using (ESS with) "text" help_type, and so these links
> to the url in doc/html  would not work for me.

I think this is an ESS problem, not an R problem.  If R is running, the 
relative links will work.  The help system is designed to be served by 
R, not served from static web pages.  There are ways to get the static 
pages to more or less work, but they'll never work as well as the real 
system.

Duncan Murdoch

>
> I wonder if we should not think harder about this, and provide a
> portable solution.
>
> I do agree that it should be very desirable to have links portably,
> in *both* directions between
>   our "reference manuals"  ( = the help pages)  and
>   our "user's manuals"     ( = the vignettes ).
>
> Martin
>