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

2016-07-18 Thread Martin Maechler 
>>>>> Boylan, Ross <ross.boy...@ucsf.edu>
>>>>> on Fri, 15 Jul 2016 17:23:37 + writes:

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

Emacs has been rendering graphics and pdf  for several years
now, and there are also several web browsing modes that we (ESS
maintainers) have considered using in the past.

But really I'm not interested so much in the potential ESS
problems, which *are* solvable and as Duncan says correctly are
not R problems.

Rather I did want to get back to the original issue of
facilitating and officially supporting links in both directions 
 R (installed package) Help  <--> R (installed package) vignettes

which I think you also want to continue talking about:

> Does anyone have any thoughts about the substantive division of info 
between help files and
> vignettes?

> Ross
> 
> From: Martin Maechler [maech...@stat.math.ethz.ch]
> Sent: Friday, July 15, 2016 5:32 AM
> To: Duncan Murdoch
> Cc: Enrico Schumann; Boylan, Ross; r-package-devel@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-15 Thread Duncan Murdoch 

On 15/07/2016 3:02 PM, Tom Wainwright wrote:

From a user perspective, I think a distinction needs to be made between

three things: help files, demos, and vignettes. I expect the help file for
functions to explain the API and (briefly) the methods implemented (with
references) and to have a few terse but useful examples in the Examples
section that can at least help a user understand the basic calls and main
options. Vignettes and demos are aimed more at the package rather than
function level; personally, I find vignettes more useful than demos.
Vignettes should provide more extensive use-case instances with explanation
of how and why the package might be applied. Demos tend to provide more
extensive sets of examples; I use them mostly for complicated graphics
(images, plotmath, etc.) where I can scan through a set of demos and find
some code that is close to what I want.

As far as linking from help to vignettes, for CRAN packages all the
vignettes appear on the web, and I would think it would be easy and
reliable to include html links to the vignettes on CRAN (assuming CRAN
doesn't mess about with web file hierarchies). This has a couple minor
issues I can think of: It won't help those working without internet access,
and it would link to vignettes for the current package version, not the
installed version.


You can already link from help pages to vignettes, and the links don't 
rely on CRAN, they're all local. It's the links in the other direction 
that only work for particular kinds of vignettes (the ones rendered in 
HTML).


Duncan Murdoch


I suspect those problems are rare, and in those cases

users can poke around in the install directories to find what they need.
The reverse linking (vignettes to help) won't really work that way, as the
Reference Manuals on CRAN are in single PDF files not indexed by function,
but anyone clever enough to work through a vignette in R should already
know how to find their local help pages.

 Tom

On Fri, Jul 15, 2016 at 10:23 AM, Boylan, Ross <ross.boy...@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 [maech...@stat.math.ethz.ch]
Sent: Friday, July 15, 2016 5:32 AM
To: Duncan Murdoch
Cc: Enrico Schumann; Boylan, Ross; r-package-devel@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel



[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel



__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-15 Thread Tom Wainwright 
>From a user perspective, I think a distinction needs to be made between
three things: help files, demos, and vignettes. I expect the help file for
functions to explain the API and (briefly) the methods implemented (with
references) and to have a few terse but useful examples in the Examples
section that can at least help a user understand the basic calls and main
options. Vignettes and demos are aimed more at the package rather than
function level; personally, I find vignettes more useful than demos.
Vignettes should provide more extensive use-case instances with explanation
of how and why the package might be applied. Demos tend to provide more
extensive sets of examples; I use them mostly for complicated graphics
(images, plotmath, etc.) where I can scan through a set of demos and find
some code that is close to what I want.

As far as linking from help to vignettes, for CRAN packages all the
vignettes appear on the web, and I would think it would be easy and
reliable to include html links to the vignettes on CRAN (assuming CRAN
doesn't mess about with web file hierarchies). This has a couple minor
issues I can think of: It won't help those working without internet access,
and it would link to vignettes for the current package version, not the
installed version. I suspect those problems are rare, and in those cases
users can poke around in the install directories to find what they need.
The reverse linking (vignettes to help) won't really work that way, as the
Reference Manuals on CRAN are in single PDF files not indexed by function,
but anyone clever enough to work through a vignette in R should already
know how to find their local help pages.

 Tom

On Fri, Jul 15, 2016 at 10:23 AM, Boylan, Ross <ross.boy...@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 [maech...@stat.math.ethz.ch]
> Sent: Friday, July 15, 2016 5:32 AM
> To: Duncan Murdoch
> Cc: Enrico Schumann; Boylan, Ross; r-package-devel@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@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-15 Thread 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.boy...@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 [maech...@stat.math.ethz.ch]
> Sent: Friday, July 15, 2016 5:32 AM
> To: Duncan Murdoch
> Cc: Enrico Schumann; Boylan, Ross; r-package-devel@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@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

[[alternative HTML version deleted]]

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-15 Thread Boylan, Ross 
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 [maech...@stat.math.ethz.ch]
Sent: Friday, July 15, 2016 5:32 AM
To: Duncan Murdoch
Cc: Enrico Schumann; Boylan, Ross; r-package-devel@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-13 Thread Duncan Murdoch 

On 13/07/2016 4:04 PM, Enrico Schumann wrote:

On Wed, 13 Jul 2016, "Boylan, Ross"  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

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2016-07-13 Thread Enrico Schumann 
On Wed, 13 Jul 2016, "Boylan, Ross"  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


-- 
Enrico Schumann
Lucerne, Switzerland
http://enricoschumann.net

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel