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

[Kasper Daniel Hansen]

Well, I think it would be a headache, and suboptimal, to require vignettes
to be renderable as text.  There are several issues including that not all
vignettes have an included "source" file; there are packages with important
vignettes which are only available as PDFs (or HTML).  Also math and plot
rendering.  I don't think this is what Martin was alluding to.

But being able to link between the help files and the vignettes would be
great.  In Bioconductor we have been using vignettes for ages and they
contain a lot of extremely useful information, to the extent that I would
always first look at the vignette and only look at the Rd file for
technical details.

Best,
Kasper



On Fri, Jul 15, 2016 at 1:23 PM, Boylan, Ross <Ross.Boylan at ucsf.edu> wrote:

> One issue with integrating vignettes into the help system is that
> vignettes are
> more likely to have material (figures, math) that renders poorly or not at
> all as text.
> I also mostly use ESS on terminal rather than graphical interface, and so
> like the  plain text version of things.  OTOH, I used Sweave specifically
> so
> I could put math in the vignette.
>
> Does anyone have any thoughts about the substantive division of info
> between help files and
> vignettes?
> Ross
> ________________________________________
> From: Martin Maechler [maechler at stat.math.ethz.ch]
> Sent: Friday, July 15, 2016 5:32 AM
> To: Duncan Murdoch
> Cc: Enrico Schumann; Boylan, Ross; r-package-devel at r-project.org
> Subject: Re: [R-pkg-devel] relation between vignettes and help files
>
> ......
> 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 at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]