From claudia.beleites at ipht-jena.de  Tue Nov  8 17:09:23 2011
From: claudia.beleites at ipht-jena.de (Claudia Beleites)
Date: Tue, 8 Nov 2011 17:09:23 +0100
Subject: [Rd] CRAN: How to list a non-Sweave doc under "Vignettes:" on
 package page?
In-Reply-To: <CABdHhvFwtw+kwDe32FKi+sN8bCjP+uT-zVJtREEnw45mPNzAEg@mail.gmail.com>
References: <CAFDcVCRfVN6KnMDdN1Je49nCTPV3+xZUaWCBKbFpJmXRzZ2Qvw@mail.gmail.com>
	<CANROs4dEo_AHYtC68ruwSvzoskqwCy+KZVJH92R0Qe4fSafcqA@mail.gmail.com>
	<CAFDcVCSLe0vGfeQht_dt61RrhM-k2_MOHvL47aQfnhBbAkDXsg@mail.gmail.com>
	<CABdHhvFwtw+kwDe32FKi+sN8bCjP+uT-zVJtREEnw45mPNzAEg@mail.gmail.com>
Message-ID: <4EB95433.3090303@ipht-jena.de>

Hi,

here's what I do:

I have two vignettes that are actually proper .Rnw files but the size of 
the data used is not acceptable for CRAN nor polite to any unsuspecting 
user.

So
- (I provide the original .Rnw and the data for download at r-forge)
- produce a .pdf from there in a directory external to the package
- have a "fake" .Rnw in the vignettes directory (actually still 
inst/doc) that provides the keywords for the vignette listing:
--- beginning of chondro.Rnw ---
% for the real source, see http://hyperspec.r-forge.r-project.org/


% \VignetteIndexEntry{Vignette on the chondro data set. Shows common 
Preprocessing tasks for Raman spectra, principal component analysis 
(PCA), and hierarchical cluster analysis.}
% \VignetteKeywords{chondro, hyperSpec, cluster analysis, preprocessing, 
Raman, principal component analysis, PCA}
% \VignettePackage{hyperSpec}

--- end of chondro.Rnw ---

- and have a Makefile in the directory with the relevant parts:

chondro.pdf:
	rm -f chondro.tex

%.pdf: %.Rnw
	$(R_HOME)/bin/Rscript -e "library (tools); Sweave(\"$(<F)\"); 
texi2dvi(\"$(basename $(<F)).tex\", pdf = TRUE, clean = TRUE);"
	gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen 
-dAutoRotatePages=/None \
	-dDownsampleColorImages=false -dNOPAUSE -dQUIET -dBATCH 
-dDownsampleColorImages=false \
	-sOutputFile=tmp.pdf $@ && qpdf tmp.pdf $@
	rm tmp.pdf
	rm -rf fig
	rm -f $(basename $(<F)).tex
	rm -f Rplots.pdf

It is important that the .Rnw actually works - the Makefile is used only 
_after_ Sweaving. But the makefile ensures that the .pdf of 
corresponding name is not destroyed during the attempt to build it from 
the .Rnw.

You can find the complete directory at:
https://r-forge.r-project.org/scm/viewvc.php/src/hyperSpec/inst/doc/?root=hyperspec

This way the vignette is listed correctly and I ship the .pdf only once. 
So in priciple, everything that is a pdf is not far from being first 
class citizen. The second class solution for non-pdf documents would be 
a pdf containing the link to the actual file.

I don't remember where I got the idea, but I think it was one of Dirk 
Eddelb?ttel's packages. So: thanks, Dirk!


Best,

Claudia


Am 08.11.2011 05:23, schrieb Hadley Wickham:
>> How CRAN behaves and how the help package system behaves may be two
>> different problems.  My question is specifically on how CRAN works.
>>
>> To have inst/doc/ documents to be listed on the package's help page,
>> you can add an inst/doc/index.html file, cf. Section 'Writing package
>> vignettes' in 'Writing R Extensions'. You can use the following
>> index.html file as a template:
>
> But they still won't be listed under vignette() - I see this solution
> as a temporary hack until non-Sweave vignettes become first class
> citizens.
>
> Hadley
>


-- 
Claudia Beleites
Spectroscopy/Imaging
Institute of Photonic Technology
Albert-Einstein-Str. 9
07745 Jena
Germany

email: claudia.beleites at ipht-jena.de
phone: +49 3641 206-133
fax:   +49 2641 206-399



[Rd] CRAN: How to list a non-Sweave doc under "Vignettes:" on package page?
Claudia Beleites