Skip to content

Creating package Vignette

6 messages · Nipesh Bajaj, Ben Bolker, Melissa Jane Hubisz +2 more

Original
Nipesh Bajaj
# 
Hi all, I was trying to create some vignette files for my newly
developed package, however wondering whether there could be any
simpler way to do so. In writing R extension it is advised to go
through Sweave route, however I have already got a big pdf file and
want to use this as package vignette.

So far I have manually created the inst/doc folder in the main package
skeleton, and put that file into this, which is not working by calling
"vignette(file_name)" after I build  and load the package. I am
getting following error without opening that pdf file: "vignette
'file_name' *not* found"

So I like to know, is there any way to use any arbitrary pdf file as vignette?

Any suggestion is highly appreciated.

Thanks,
Brian Ripley
# 
It depends what you mean by 'vignette': the R docs have been unclear 
(but R >= 2.13.0 are more consistent).  In most cases a 'vignette' is 
an Sweave document, the vignette source being the .Rnw file, and the 
vignette PDF the processed .pdf file.

At present vignette() means Sweave documents, as only they have 
metadata like titles.  This is planned to be changed soon.
On Thu, 14 Jul 2011, Nipesh Bajaj wrote:

            

      
      
      
    

        
file_name is not an argument to vignette(): it is 'topic'.  And topics 
are normally file basenames (without any extension), not file names.

            

      
      
      
    

        
By definition, no.

            

      
      
      
    

        

      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Ben Bolker
    

    

      
      #
    

  


  

      
Prof Brian Ripley <ripley <at> stats.ox.ac.uk> writes:

            

      
      
      
    

        
One possibility: as a workaround, you could include your
own "xvignette" function in your package: see below.
It won't show you indices, but it will pick up any appropriately
named file that you include in the inst/doc directory of your
package ...

xvignette <- function(vname,pkg,ext="pdf") {
   vname <- paste(vname,ext,sep=".")
   fn <- system.file("doc",vname,package=pkg)
   if (nchar(fn)==0) stop("file not found")
   utils:::print.vignette(list(pdf=fn))
   invisible(fn)
 }

  You'll have to somehow alert your package users to the
fact that this alternative documentation exists -- perhaps in the help
package for the package itself.

  You might fill in the default value of "pkg" above with your
package name to make it easier on the user: I thought about
using some version of getPackageName(environment(xvignette))
to do it automatically, but that seems too complicated ...

  
  


  


      

    

    

      
      

        


  

        

      Melissa Jane Hubisz
    

    

      
      #
    

  


  

      
Another workaround is to create a "dummy" vignette which does nothing
but include the pdf file.  Something like this:
vignette.Rnw:

% \VignetteIndexEntry{vignette}
% \VignetteKeywords{keywords here}
% \VignettePackage{package name}

\documentclass[a4paper]{article}
\usepackage{hyperref}
\usepackage{pdfpages}
\begin{document}
\includepdf[fitpaper=true,pages=-]{vignette-source.pdf}
\end{document}

Not sure if this is totally kosher, but I did this for my package when
the vignette was too computationally intensive to be submitted to
CRAN.
-Melissa

        
On Thu, Jul 14, 2011 at 1:00 PM, Ben Bolker <bbolker at gmail.com> wrote:

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Brian Ripley
    

    

      
      #
    

  


  

      
On Thu, 14 Jul 2011, Melissa Jane Hubisz wrote:

        

            

      
      
      
    

        
That's fine (because a lot of not-very-necessary work has had to have 
been done to accept vignettes with no R code), but we are working on 
ways to avoid such subterfuges.

In particular, CRAN does accept packages with Sweave vignettes that 
take too long to check -- one takes ca 8 hours (or would if it worked, 
which it currently does not).  We just ask that we are told so on 
submission.