>>>>> Duncan Murdoch <murdoch.dun...@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.boy...@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
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
