Re: [R-pkg-devel] relation between vignettes and help files
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, Rosswrote: 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
>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, Rosswrote: > 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
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, Rosswrote: > 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
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