[Rd] Documentation suggestions for vignettes

[Gabor Grothendieck]

I find this very confusing too.

I would also sometimes like to include pdf's that were not generated from
Sweave and have them included in the package and listed in
library(help = mypackage) output as well as with clickable links
on the package's CRAN web page like vignettes are.


On Thu, Jan 15, 2009 at 1:27 PM, Simon Urbanek
<simon.urbanek at r-project.org> wrote:
>
> 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
>>
>>
>
>