[Rd] why is \alias{anRpackage} not mandatory?

[Berwin A Turlach]

G'day Hadley,

On Mon, 6 Oct 2008 08:55:14 -0500
"hadley wickham" <h.wickham at gmail.com> wrote:

> >> The main problem with vignettes at the moment is that
> >> they must be sweave, a format which I don't really like.  I wish I
> >> could supply my own pdf + R code file produced using whatever
> >> tools I choose.
> >
> > I like Sweave, and it is also possible to include your own PDFs and
> > R files and then to reference them in anRpackage.Rd.
> 
> Yes, but they're not vignettes - which means they're not listed under
> vignette() and it's yet another place for people to look for
> documentation.

Well, there is a kind of subversive way of how do use the facilities
provided to vignettes for PDFs that were created by some other
mechanism.  That was discussed sometime ago on this list.  The idea was
to create an "empty" vignette that uses the LaTeX package pdfpages to
include the existing PDF into a vignette.

Since you ended up with essentially two copies of the same PDF file,
you can use .Rbuildignore to exclude the original PDF from the build
and only distribute the PDF created from the vignette.

This trick worked really well as long as "R CMD check" was not trying
to latex the .tex file produced from the vignette (apparently since R
2.6.0 the behaviour of "R CMD check" in this respect has changed,
though the "Writing R Extension" manual was not updated to reflect
this change; which reminds me that I promised Kurt Hornik to file a
bug report about this).  What makes things worse is that with the
current TeX installation on Debian based operating system, latex hangs
if a file, from which pdfpages wants to include some (or all) pages,
does not exist.  That is "R CMD check" on such a tar.gz file hangs and
doesn't stop with an error message.

The solution that I am using at the moment is shown in the attached
file which resides in inst/doc of the lasso2 package on my machine.  On
my machine, "R CMD build" and "R CMD check" will, of course, work.
Essentially, this vignette only creates the information needed to index
it and then includes the file Manual-wo-help.pdf (which is the old help
for the S-Plus version of that package; I should really update all
this). Manual-wo-help.pdf is excluded from lasso2_x.y-z.tar.gz via an
entry in .Rbuildignore but the vignette is distributed and listed under
vignette().  And "R CMD check" on works the .tar.gz file too.

Cheers,

	Berwin

=========================== Full address =============================
Berwin A Turlach                            Tel.: +65 6516 4416 (secr)
Dept of Statistics and Applied Probability        +65 6516 6650 (self)
Faculty of Science                          FAX : +65 6872 3919       
National University of Singapore     
6 Science Drive 2, Blk S16, Level 7          e-mail: statba at nus.edu.sg
Singapore 117546                    http://www.stat.nus.edu.sg/~statba
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: Manual-vignette.Rnw
URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20081007/11fbdfa9/attachment.pl>