# Links to non-vignette documentation

22 messages
12
Open this post in threaded view
|

## Links to non-vignette documentation

 Section 1.4 of Writing R Extensions says: In addition to the help files in Rd format, R packages allow the inclusion of documents in arbitrary other formats. The standard location for these is subdirectory inst/doc of a source package, the contents will be copied to subdirectory doc when the package is installed. Pointers from package help indices to the installed documents are automatically created. Documents in inst/doc can be in arbitrary format, however we strongly recommend to provide them in PDF format, such that users on all platforms can easily read them. Where are these pointers created?  I have a package with a pdf file (introduction.pdf) in inst/doc but I can't find a link to it from the documentation (eg. from help.start() or help(package=...) Is there anyway to have my pdf documentation listed under vignettes other than making it a sweave file? Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 On 2/23/2006 11:53 AM, hadley wickham wrote: > Section 1.4 of Writing R Extensions says: > > In addition to the help files in Rd format, R packages allow the > inclusion of documents in arbitrary other formats. The standard > location for these is subdirectory inst/doc of a source package, the > contents will be copied to subdirectory doc when the package is > installed. Pointers from package help indices to the installed > documents are automatically created. Documents in inst/doc can be in > arbitrary format, however we strongly recommend to provide them in PDF > format, such that users on all platforms can easily read them. > > Where are these pointers created?  I have a package with a pdf file > (introduction.pdf) in inst/doc but I can't find a link to it from the > documentation (eg. from help.start() or help(package=...) > > Is there anyway to have my pdf documentation listed under vignettes > other than making it a sweave file? A manually written inst/doc/index.html file will be linked into the help system. I don't know if the sentence about pointers being created is true otherwise. Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 On Thu, 23 Feb 2006, Duncan Murdoch wrote: > On 2/23/2006 11:53 AM, hadley wickham wrote: >> Section 1.4 of Writing R Extensions says: >> >> In addition to the help files in Rd format, R packages allow the >> inclusion of documents in arbitrary other formats. The standard >> location for these is subdirectory inst/doc of a source package, the >> contents will be copied to subdirectory doc when the package is >> installed. Pointers from package help indices to the installed >> documents are automatically created. Documents in inst/doc can be in >> arbitrary format, however we strongly recommend to provide them in PDF >> format, such that users on all platforms can easily read them. >> >> Where are these pointers created?  I have a package with a pdf file >> (introduction.pdf) in inst/doc but I can't find a link to it from the >> documentation (eg. from help.start() or help(package=...) >> >> Is there anyway to have my pdf documentation listed under vignettes >> other than making it a sweave file? No, a vignette is regarded as an Sweave file. > A manually written inst/doc/index.html file will be linked into the help > system. .install_package_vignette_index does create an index, and info does get put on the packages html page. I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an pdf file but no .[RS]nw vignettes, the index is fairly useless but browsing is available. > I don't know if the sentence about pointers being created is true otherwise. It seems to be. -- Brian D. Ripley,                  [hidden email] Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/University of Oxford,             Tel:  +44 1865 272861 (self) 1 South Parks Road,                     +44 1865 272866 (PA) Oxford OX1 3TG, UK                Fax:  +44 1865 272595 ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 > >> Is there anyway to have my pdf documentation listed under vignettes > >> other than making it a sweave file? > > No, a vignette is regarded as an Sweave file. It would be useful if there was a mechanism to allow arbitrary pdf files to be included as vignettes.  There are many other ways to include R code/output in pdf files other than through Sweave. > I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an > pdf file but no .[RS]nw vignettes, the index is fairly useless but > browsing is available. > > > I don't know if the sentence about pointers being created is true otherwise. > > It seems to be. A link to the directory where the pdf is located, only available in the html version of help, rather stretches the definition of a pointer. Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 On Thu, 23 Feb 2006, hadley wickham wrote: >>>> Is there anyway to have my pdf documentation listed under vignettes >>>> other than making it a sweave file? >> >> No, a vignette is regarded as an Sweave file. > > It would be useful if there was a mechanism to allow arbitrary pdf > files to be included as vignettes.  There are many other ways to > include R code/output in pdf files other than through Sweave. I think you need to define vignette'.  I understand the usage to mean an Sweave file.  There are ways to include other PDF files, and you can write your own index file.  R can't do that for you as it cannot read PDF (it can read Sweave). >> I just tried this by adding inst/doc/foo.pdf to windlgs.  If there is an >> pdf file but no .[RS]nw vignettes, the index is fairly useless but >> browsing is available. >> >>> I don't know if the sentence about pointers being created is true otherwise. >> >> It seems to be. > > A link to the directory where the pdf is located, only available in > the html version of help, rather stretches the definition of a > pointer. What is a link if not a pointer?  What it actually says is     Pointers from package help indices to the installed     documents are automatically created. I am not aware of any other sort of package help index', although one could arge the toss about Compiled HTML. -- Brian D. Ripley,                  [hidden email] Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/University of Oxford,             Tel:  +44 1865 272861 (self) 1 South Parks Road,                     +44 1865 272866 (PA) Oxford OX1 3TG, UK                Fax:  +44 1865 272595 ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 > I think you need to define vignette'.  I understand the usage to mean an > Sweave file.  There are ways to include other PDF files, and you can write > your own index file.  R can't do that for you as it cannot read PDF (it > can read Sweave). How can I write an index file with a pointer to my pdf?  Should I provide a code snippet to run system(paste(getOption("pdfviewer"), system.file("doc/my.pdf", package="mypackage"), "&"))? Perhaps my problem is thinking of a vignette as a "A brief verbal description of a person, place, etc.; a short descriptive or evocative episode in a play, etc." rather than a Sweave document. > I am not aware of any other sort of package help index', although one > could arge the toss about Compiled HTML. What about (eg.) help(package=grid)?  This is where vignettes are listed by name (and location).  I would like to be able put my pdf into a similar list. Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 On Thu, 23 Feb 2006, hadley wickham wrote: >> I think you need to define vignette'.  I understand the usage to mean an >> Sweave file.  There are ways to include other PDF files, and you can write >> your own index file.  R can't do that for you as it cannot read PDF (it >> can read Sweave). > > How can I write an index file with a pointer to my pdf?  Should I > provide a code snippet to run system(paste(getOption("pdfviewer"), > system.file("doc/my.pdf", package="mypackage"), "&"))? Just add a hyperlink in inst/doc/index.html to foo.pdf and let the browser do the rest.  The grid/doc/index.html is a suitable template. > Perhaps my problem is thinking of a vignette as a "A brief verbal > description of a person, place, etc.; a short descriptive or evocative > episode in a play, etc." rather than a Sweave document. > >> I am not aware of any other sort of package help index', although one >> could arge the toss about Compiled HTML. > > What about (eg.) help(package=grid)?  This is where vignettes are > listed by name (and location).  I would like to be able put my pdf > into a similar list. Which is really library(help=grid).  Vignettes there are a recent addition, and we need the author to tell us.  It looks to me as if that means strict-sense vignettes (it gets the info from the vignette metadata).  If there were a mechanism for authors to list PDF docs and titles in a two-column format in some file in inst/docs, the installation tools could provide more support.  (I think this is Kurt's area.) [I am not arguing that this could not be better documented, but I think most things are possible by digging around.] -- Brian D. Ripley,                  [hidden email] Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/University of Oxford,             Tel:  +44 1865 272861 (self) 1 South Parks Road,                     +44 1865 272866 (PA) Oxford OX1 3TG, UK                Fax:  +44 1865 272595 ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by hadley wickham On 2/23/2006 4:23 PM, hadley wickham wrote: >> I think you need to define vignette'.  I understand the usage to mean an >> Sweave file.  There are ways to include other PDF files, and you can write >> your own index file.  R can't do that for you as it cannot read PDF (it >> can read Sweave). > > How can I write an index file with a pointer to my pdf?  Should I > provide a code snippet to run system(paste(getOption("pdfviewer"), > system.file("doc/my.pdf", package="mypackage"), "&"))? We were referring to an HTML index file.  If you want to have a reference from your package man page (foo-package.Rd) or some other man page, you can use \url{../doc/my.pdf} and the link will work in HTML versions of help, and won't be too misleading in other versions (especially if you explain how to use it). > Perhaps my problem is thinking of a vignette as a "A brief verbal > description of a person, place, etc.; a short descriptive or evocative > episode in a play, etc." rather than a Sweave document. > >> I am not aware of any other sort of package help index', although one >> could arge the toss about Compiled HTML. > > What about (eg.) help(package=grid)?  This is where vignettes are > listed by name (and location).  I would like to be able put my pdf > into a similar list. I don't think you can do that, but you should be using a package man page anyway. Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 > We were referring to an HTML index file.  If you want to have a > reference from your package man page (foo-package.Rd) or some other man > page, you can use \url{../doc/my.pdf} and the link will work in HTML > versions of help, and won't be too misleading in other versions > (especially if you explain how to use it). Ok, I'll give that a go. > I don't think you can do that, but you should be using a package man > page anyway. Can you suggest a good example of a package man page?  I've tried a few packages and haven't been able to find one.  The example generated by promptPackage suggests I need to duplicate the contents of DESCRIPTION and INDEX. Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by hadley wickham On 2/23/2006 5:49 PM, hadley wickham wrote: >> We were referring to an HTML index file.  If you want to have a >> reference from your package man page (foo-package.Rd) or some other man >> page, you can use \url{../doc/my.pdf} and the link will work in HTML >> versions of help, and won't be too misleading in other versions >> (especially if you explain how to use it). > > Ok, I'll give that a go. > >> I don't think you can do that, but you should be using a package man >> page anyway. > > Can you suggest a good example of a package man page?  I've tried a > few packages and haven't been able to find one.  The example generated > by promptPackage suggests I need to duplicate the contents of > DESCRIPTION and INDEX. All of the base packages have them; some contain more than others.  I don't know which ones I'd consider to be "good". They are meant to replace the INDEX, which you shouldn't need to create any more.  The DESCRIPTION file is still needed, but it contains more structured information meant for mechanical reading and processing; the package man page is meant to be the place to put things intended for people to read. Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 > They are meant to replace the INDEX, which you shouldn't need to create > any more.  The DESCRIPTION file is still needed, but it contains more > structured information meant for mechanical reading and processing; the > package man page is meant to be the place to put things intended for > people to read. Do I need to keep the list of functions on the package man page in sync myself, or will they be automatically rebuilt?  Is the intention to eventually change help(package=XXX) to point to the package man page? Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 I haven't followed this whole thread but note that if your package is called mypkg then you can create an .Rd file called mypkg-package.Rd which will be called up when the user issues: package?mypkg and that can contain links to whatever you are interested in. Try library(dyn) package?dyn for an example.  The R command, promptPackage, can be used to facilitate the creation of the -package.Rd file. On 2/23/06, hadley wickham <[hidden email]> wrote: > > They are meant to replace the INDEX, which you shouldn't need to create > > any more.  The DESCRIPTION file is still needed, but it contains more > > structured information meant for mechanical reading and processing; the > > package man page is meant to be the place to put things intended for > > people to read. > > Do I need to keep the list of functions on the package man page in > sync myself, or will they be automatically rebuilt?  Is the intention > to eventually change help(package=XXX) to point to the package man > page? > > Hadley > > ______________________________________________ > [hidden email] mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel> ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by hadley wickham On 2/23/2006 10:02 PM, hadley wickham wrote: >> They are meant to replace the INDEX, which you shouldn't need to create >> any more.  The DESCRIPTION file is still needed, but it contains more >> structured information meant for mechanical reading and processing; the >> package man page is meant to be the place to put things intended for >> people to read. > > Do I need to keep the list of functions on the package man page in > sync myself, or will they be automatically rebuilt?  Is the intention > to eventually change help(package=XXX) to point to the package man > page? No, there's no automatic building after the promptPackage call.  It's up to you to decide which functions need to be mentioned to users.  In large packages it usually doesn't make sense to list all the functions, so the package writer needs to use judgement here.  There are other mechanisms (e.g. ls("package:XXX") for a list of names, the help index generation for a list of names and titles) to get a list of everything. There aren't any immediate plans to change help(package=XXX), but I think in the long run, if package?XXX receives wider support than it has now, it would make sense to make that change. Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by Berwin A Turlach Le 24.02.2006 01:26, Berwin A Turlach a écrit : > G'day all, > > seems as if I must have slept through most of this most interesting > discussion. :) > >   >>>>>> "BR" == Prof Brian Ripley <[hidden email]> writes: >>>>>>             > >     BR> On Thu, 23 Feb 2006, hadley wickham wrote: >     >> How can I write an index file with a pointer to my pdf?  Should >     >> I provide a code snippet to run >     >> system(paste(getOption("pdfviewer"), system.file("doc/my.pdf", >     >> package="mypackage"), "&"))? >     BR> Just add a hyperlink in inst/doc/index.html to foo.pdf and let >     BR> the browser do the rest.  The grid/doc/index.html is a >     BR> suitable template. > Editing this file by hand is certainly an option, but one more think > to remember while maintaining a package.  Thus, I think it is > preferable to automate process as much as possible.  I ran into a > similar problem as Hadley with a package that I am currently developing > (since some time) and offer my solution below. > >   >>>>>> "DM" == Duncan Murdoch <[hidden email]> writes: >>>>>>             > >     DM> On 2/23/2006 4:23 PM, hadley wickham wrote: >     >> What about (eg.) help(package=grid)?  This is where vignettes >     >> are listed by name (and location).  I would like to be able put >     >> my pdf into a similar list. >     DM> I don't think you can do that, but you should be using a >     DM> package man page anyway. > I believe this can be done, albeit not directly. > > In my case, I wanted to include a PDF, whose source is not in Sweave > format, with the documentation of the package and have the links to > this documentation created automatically.  My solution, in the end was > to create a "dummy" Rnw vignette which has a link to the pdf file.  I > include that dummy vignette below.  Hence, in the directory inst/doc > of my package there are the following files: >     interface96.pdf             The PDF file I actually want to include >                                 as part of the documentation >     interface96-vignette.Rnw    The dummy vignette file > Using hyperref with a "file:" url, the dummy vignette file links to > the actual files. > > For the user, this means that she/he sees the dummy vignette and > access it first and then has to click once more on a link to get to > the actual document.  Slightly inconvenient for the user, but I > believe it is a fair price to pay to make my life as developer > easier. ;-)) > > If you want to distribute binary copies (e.g. for the various version > of Windows that exists) of your package, then you need of course all > the tools that are necessary to handle vignettes. > > Cheers, > >         Berwin > > ------------------------- Source of dummy vignette ------------------------- > \documentclass[a4paper]{article} > %\VignetteIndexEntry{Interface '96 paper by Marron et al. (1997)} > %\VignettePackage{clps} > > \usepackage{hyperref} > \usepackage{natbib} > > \title{Interface '96 paper by \cite{mar:tur:wan:96}} > \author{Berwin A Turlach} > \date{September 25, 2004} > > \begin{document} > \maketitle > > This is just a dummy vignette with a link to the > \href{file:interface96.pdf}{PDF file} of \cite{mar:tur:wan:96} which > is part of the \textit{CLPS} package.  The dummy vignette should > appear in the automatically generated index, but I did not succeed in > getting the actual paper to appear in that index. > > \bibliographystyle{dcunsp} > \bibliography{clps} > > \end{document} >   Hi, What about using the latex package pdfpages to copy the pages from your PDF file interface96.pdf to your Sweave file. (I don't know if it is compatible with Sweave). Not tested : \documentclass[a4paper]{article} %\VignetteIndexEntry{Interface '96 paper by Marron et al. (1997)} %\VignettePackage{clps} \usepackage{hyperref} \usepackage{natbib} \usepackage{pdfpages} \title{Interface '96 paper by \cite{mar:tur:wan:96}} \author{Berwin A Turlach} \date{September 25, 2004} \begin{document} \maketitle \newpage \includepdf{interface96.pdf} \bibliographystyle{dcunsp} \bibliography{clps} \end{document} Romain   -- visit the R Graph Gallery : http://addictedtor.free.fr/graphiquesDiscover the R Movies Gallery : http://addictedtor.free.fr/movies+---------------------------------------------------------------+ | Romain FRANCOIS - http://francoisromain.free.fr               | | Doctorant INRIA Futurs / EDF                                  | +---------------------------------------------------------------+ ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 On 2/24/2006 7:27 AM, Romain Francois wrote: > > What about using the latex package pdfpages to copy the pages from your > PDF file interface96.pdf to your Sweave file. (I don't know if it is > compatible with Sweave). > > Not tested : > > \documentclass[a4paper]{article} > %\VignetteIndexEntry{Interface '96 paper by Marron et al. (1997)} > %\VignettePackage{clps} > > \usepackage{hyperref} > \usepackage{natbib} > \usepackage{pdfpages} > > \title{Interface '96 paper by \cite{mar:tur:wan:96}} > \author{Berwin A Turlach} > \date{September 25, 2004} > > \begin{document} > \maketitle > > \newpage > > \includepdf{interface96.pdf} > > > \bibliographystyle{dcunsp} > \bibliography{clps} > > \end{document} That's a nice hack.  You probably want the "fitpaper" option on the \includepdf command, so that you don't get an extra border around the page.  For example, this file test.Rnw \documentclass{article} %\VignetteIndexEntry{test include of pdf} %\VignettePackage{ellipse} \usepackage{pdfpages} \begin{document} \includepdf[fitpaper=true]{response.pdf} \end{document} produces an output that looks pretty much exactly like the "response.pdf" file I used as test input in a viewer. The only disadvantages I see are that both the test.pdf and response.pdf files got built into the package (but only test.pdf shows up in the index), and that test.pdf is a lot larger than response.pdf.  (This may be because response.pdf was small; I haven't checked if the increase is additive or multiplicative). For a non-hack solution: A change to the R package build process would be to add support for a command like %\VignetteExists to the test.Rnw file, telling R not to bother trying to build the pdf, because it had already been built by other means.  Then I'd just have test.Rnw containing %\VignetteIndexEntry{test include of pdf} %\VignettePackage{ellipse} %\VignetteExists and solve both of the problems with Romain's workaround. Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by Duncan Murdoch > No, there's no automatic building after the promptPackage call.  It's up > to you to decide which functions need to be mentioned to users.  In > large packages it usually doesn't make sense to list all the functions, > so the package writer needs to use judgement here.  There are other > mechanisms (e.g. ls("package:XXX") for a list of names, the help index > generation for a list of names and titles) to get a list of everything. Ok, that seems reasonable, but perhaps promptPackage (or documentation) could make this more clear. > There aren't any immediate plans to change help(package=XXX), but I > think in the long run, if package?XXX receives wider support than it has > now, it would make sense to make that change. When was this form of package documentation created?  How are users supposed to know it exists?  I couldn't find any pointers to it from ?help, ?library or from help(package=XXX). Hadley ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by Duncan Murdoch Duncan Murdoch wrote: >>\usepackage{pdfpages} > That's a nice hack.  You probably want the "fitpaper" option on the > \includepdf command, so that you don't get an extra border around the > page.  For example, this file test.Rnw > The only disadvantages I see are that both the test.pdf and response.pdf > files got built into the package (but only test.pdf shows up in the > index), and that test.pdf is a lot larger than response.pdf.  (This may > be because response.pdf was small; I haven't checked if the increase is > additive or multiplicative). I like pdfpages and do use it from time to time (as frequently as every couple of weeks for filling expense/travel/claim forms) - but in fact it isn't shipped with tetex 1.0 and is not in the site-wise LaTeX installation in my work location. (and luckily I am not using the site-wise one...). I checked and pdfpages was added to tetex in Oct 2001 and is in tetex 2.0 which was released in feb 2003; but sites could be slow in upgrading... so such constructions would break on sites which hasn't upgraded their LaTeX installation in the last 3 years. HTL ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Open this post in threaded view
|

## Re: Links to non-vignette documentation

 In reply to this post by hadley wickham On 2/24/2006 9:29 AM, hadley wickham wrote: >> No, there's no automatic building after the promptPackage call.  It's up >> to you to decide which functions need to be mentioned to users.  In >> large packages it usually doesn't make sense to list all the functions, >> so the package writer needs to use judgement here.  There are other >> mechanisms (e.g. ls("package:XXX") for a list of names, the help index >> generation for a list of names and titles) to get a list of everything. > > Ok, that seems reasonable, but perhaps promptPackage (or > documentation) could make this more clear. > >> There aren't any immediate plans to change help(package=XXX), but I >> think in the long run, if package?XXX receives wider support than it has >> now, it would make sense to make that change. > > When was this form of package documentation created?  How are users > supposed to know it exists?  I couldn't find any pointers to it from > ?help, ?library or from help(package=XXX). It's described in the Writing R Extensions Manual, in Writing R Documentation Files, Rd Format, Documenting Packages (section 2.1.4 in the PDF). There probably should be more pointers to it... Duncan Murdoch ______________________________________________ [hidden email] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel