[Rd] Documentation suggestions for vignettes

[Simon Urbanek]

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
>
>