[Rd] Documentation suggestions for vignettes

[Gabor Grothendieck]

The source tree is at:
    https://svn.r-project.org/R/trunk
and the src/library/grid subdirectory holds grid.
To check out a copy using svn see the "svn checkout ..."
command described here:
    http://developer.r-project.org/

On Thu, Jan 15, 2009 at 12:24 PM, Perry de Valpine
<pdevalpine at berkeley.edu> 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.  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
>