[Rd] Documentation suggestions for vignettes

[Perry de Valpine]

(Apologies for re-posting this from a few minutes ago.  My message  
was scrubbed and I hope I've done it right now...)

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