Skip to content

Documentation suggestions for vignettes

8 messages · Gabor Grothendieck, Perry de Valpine, Simon Urbanek

Original
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
Gabor Grothendieck
# 
On Wed, Jan 14, 2009 at 2:53 PM, Perry de Valpine
<pdevalpine at berkeley.edu> wrote:
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
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:

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Gabor Grothendieck
    

    

      
      #
    

  


  

      
The source tree is at:
    https://svn.r-project.org/R/trunk
and the src/library/grid subdirectory holds grid.
To check out a copy using svn see the "svn checkout ..."
command described here:
    http://developer.r-project.org/

On Thu, Jan 15, 2009 at 12:24 PM, Perry de Valpine

        
<pdevalpine at berkeley.edu> wrote:

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Simon Urbanek
    

    

      
      #
    

  


  

      
On Jan 15, 2009, at 12:24 , Perry de Valpine wrote:

        

            

      
      
      
    

        
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

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      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:

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      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: