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

[Martin Maechler]

>>>>> 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 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