[Rd] Documentation suggestions for vignettes

[Perry de Valpine]

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.

But before I did that I tried putting my Rnw file in inst/doc to see
if I could get it recognized if R CMD BUILD was generating the pdf
itself.  For this method, section 1.4 states the index information is
generated "from the \VignetteIndexEntry statements" but gives no
example of the syntax for this (it takes one argument in curly braces
giving a description of the vignette) or the associated commands
(e.g. \VignettePackage{} and \VignetteDepends{}, as I find from the
grid source, and perhaps others?).  This made the documentation read
as if it would only make sense to someone who is already a seasoned
package developer. How about giving an example? After again emulating
the grid package source, the build and install worked beautifully and
index.html was generated correctly.

Clearly my bumps were due to climbing the learning curve, but some
cursory Googling and R help searching for further information to see
if I had missed something obvious did not yield much.

In summary, stating that an index.html is necessary if a vignette is
provided as a pdf, giving an example of its format, and giving an
example of %\VignetteIndexEntry{description} etc. might be helpful.
If these points are not mistaken and the appropriate person wants to
contact me directly I would be happy to redraft this brief section.

Thanks.
Perry de Valpine
University of California, Berkeley
Department of Environmental Science, Policy and Management