[Rd] Documentation suggestions for vignettes

[Perry de Valpine]

Thanks for the helpful replies.

Regarding the source: I  see that in ..../grid/inst/doc there are no  
pdfs and no index.html, so that confirms that index.html is generated  
by the \VignetteIndexEntry method using Snw/Rnw when the grid package  
is built.  That is helpful for me but not the main point of my posting.

To zoom out: the goal of my posting was to suggest that the "Writing  
package vignettes" (section 1.4) documentation could be improved with  
a few small changes that might smooth the way for future new package  
developers, and it is clear I misunderstood some aspects of what it  
was trying to say because, well, it is not completely clear to  
someone who is not already familiar with the details.  I received an  
off-list message confirming similar bumps from someone else when they  
tried making a vignette for the first time.

Now I understand that the "pointers from packages" statements did not  
refer to vignettes; I guess my confusion on that was that it appears  
in the first paragraph of the "Writing package vignettes" section,  
but I see the next paragraph should have set me straight.  At the  
least the point that the %\VignetteIndexEntry comment in section 1.4  
is obtuse and does not provide the reader with sufficient information  
of how to do this still seems valid.  The successful creation of  
index.html appeared from my explorations to go hand-in-hand with  
successful recognition by R that the vignette exists, but I see that  
it is for the HTML system only, and, again, I was left with some  
guesswork after reading section 1.4.

The R manuals are amazing and I many others are indebted to those who  
wrote them.  I remember seeing a posting at some point about the  
value of finding documentation bugs as well as code bugs, so when I  
saw that section 1.4 falls short of explaining how to easily and  
successfully set up a vignette (or include a pdf directly, which I  
now see is not a vignette), I thought I would point it out (and  
volunteer to help if I could, with help from one of the experts).   
Undoubtedly the section makes perfect sense to someone who already  
knows all the details, so it may be hard to see it from a newcomer's  
view.  I also recognize that the documentation can only be helpful to  
a point and people need to spend their own time digging into things,  
but I thought the totally unexplained %\VignetteIndexEntry was an  
obvious case where very few additional words would be a huge help,  
and perhaps a few of the other points that have arisen could also be  
easily clarified.

Thanks again.
Perry





On Jan 15, 2009, at 10:34 AM, Gabor Grothendieck wrote:

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