Documentation suggestions for vignettes
On Jan 15, 2009, at 12:24 , Perry de Valpine wrote:
I am looking at the 2.8.1 source code in R-2.8.1/src/library/grid/ inst/doc, where there is an index.html (I am not at daily syncing level and hope that is not an issue in this case). In this case the Snw files contain the %\VignetteIndexEntry and associated commands, so the index.html could have been generated by the package build (I see the pdfs, so I assume they were generated from the Snws by building the package. Should be I able to access a pre-build package source? That is not what is in R-2.8.1.tar.gz but may be what you have?). To clarify: if I attempt to include a vignette by putting a pdf directly in inst/doc, then R CMD BUILD does copy the pdf to the built package but generates an index.html that says there are no vignettes, so R is blind to the vignette.
That statement is wrong in the first place. R doesn't care about index.html when looking for package vignettes - it's generated for the HTML help system only (from vignettes, really). Please read "1.4 Writing package vignettes" in R-exts manual. Vignettes are only documents created with Sweave. Although you can add arbitrary documents to your package, those are not considered vignettes. If you have custom documents in inst/doc, you have to supply your own index.html (unless the default "look in ." makes you happy), because R creates an index file only for vignettes. To address your original post: "Pointers from package help indices to the installed documents are automatically created" has nothing to do with vignettes (note that it's talking about documents, not vignettes). However, AFAICT it's no longer true (at least 00Index.dcf seems to be ignored), so that may need some clarification. Cheers, Simon
After seeing a correctly built index.html, I made a leap to think that if I include/modify the index.html to treat the pdf as a vignette, that might make R see it. However, I did not test this, and instead moved on to the Rnw method with %\VignetteIndexEntry. For the direct pdf method, I don't know if R CMD BUILD is intended to generate an index.html that recognizes any pdfs present (i.e. the documentation is fine), or alternatively if the documentation should state more completely how to include a pdf directly as a vignette. The latter was the premise of my earlier post. Please let me know if that is confused or still not specific enough. Thanks. Perry On Jan 15, 2009, at 7:10 AM, Gabor Grothendieck wrote:
On Wed, Jan 14, 2009 at 2:53 PM, Perry de Valpine <pdevalpine at berkeley.edu> wrote:
Dear R-devel,
I am putting together a package vignette for the first time (R
2.8.1,
OS X) and had some bumps from section 1.4 ("Writing package
vignettes") of the "Writing R Extensions" document. Here are
suggestions to clean up a few small documentation bugs (I think) and
omissions. This is assuming that R is performing as intended and
the
only gaps are in the documentation, not vice-versa.
The statement "Pointers from package help indices to the installed
documents are automatically created" made me think I could put a pdf
in inst/doc and it would automatically be treated as a vignette.
When
I did R CMD BUILD and R CMD INSTALL, an index.html was created in
inst/doc (and my pdf was copied there) but it stated there are no
vignettes for this package, and R indeed could not find the
vignette.
How about stating that index.html is needed and sticking in an
example?
I eventually figured it out by looking at the grid package source.
Could you please clarify this comment. I could not find an index.html file in the grid package source (R revision 47606 synced today): C:\\R\src\library\grid>dir/s index.html File Not Found
[[alternative HTML version deleted]]
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel