[R] Sweave in packages

[Paul Gilbert]

"Vincent J. Carey, Jr." wrote:
> 
> as we build Sweave documents illustrating package functionalities
> it is sometimes desirable to attach a package "behind
> the scenes".  

Part of the response below is also related to the above.

Jari Oksanen wrote:
> 
> Dear R folks,
> 
> One of the fantastic new tools in R is `Sweave'. 

I agree.

>I have tested it so much that I
> know it works and produces fine documentation, and with (GNU) Emacs/ESS it is
> nice to work with, too. I started to have a look at including some Swoven (is
> that a strong verb?) documentation with my R package, but it seems that there is
> no model to copy among those packages that I have installed in my R. Has anybody
> used Sweave for package vignettes? I have run into some minor inconveniences,
> where I would appreciate hints:

This may be the blind leading the blind, but perhaps the real authority will
speak up when I really mess things up. Most of the information below has been
provided by Friedrich Leisch so I am repeating it in the hope he will not have
to, and can fix other problems I have being bugging him about :-). I have been
converting my Users's Guide from Framemaker to Latex and then using Sweave to
test/fill-in the examples. Sweave can use either tex or noweb style source, but
I know nothing about the latter, so everything below is the tex style.

I am not a hard core Latex user, so there is an extra wrinkle in that I would
often like to use Lyx (a WYSIWYG Latex editor) to edit my files. To do this I
keep my source in guidesrc/guide.tex (Lyx wants a .tex extension) and copy this
to inst/doc/guide.Stex, which Sweave wants as source. Sweave generates a file
guide.tex, so a bit of care is necessary to make sure this does not overwrite my
original source. I can completely remove inst/doc when I clean, so this would be
one way to deal with the extra files that are generated by Sweave. However, I
usually run Sweave in a different directory (tmp) so the extra files are there.

In my Users' Guide examples I typically show user input, but not system output.
Occassionally I change this to hide both (e.g. generating objects generated in
previous sections of the guide), or to show both, or to show generated graphics.
This is done by setting the default in the .Stex file with

\SweaveOpts{eval=TRUE,echo=TRUE,results=hide,fig=FALSE}

and then temporarily changing the default, for a single Scode segment, for
example:

\begin{Scode}{echo=FALSE,results=hide}
   code with neither input or output shown
\end{Scode}

or

\begin{Scode}{fig=TRUE, echo=FALSE}
  graphic is shown, but not input
\end{Scode}

Note that checkVignettes() actually runs all the code to check that it works. If
you want to show results, have results available for the next section of Scode,
or make a library available, then you must have eval=TRUE. This results in the
code being run twice, once for the check and once for making the results
available. (I think there is some possibility this will change in a future
release.)

> - I cannot find out in R-exts manual how to actually write \VignetteIndexEntry
> so that it would be incorporated into 00Index.dcf. Should you put the entry
> within braces (LaTeX way) or use colon or something before the entry
> (00Index.dcf instructions)? 

%\VignetteIndexEntry{Title you would like}

The % makes it a tex comment.

>Actually, I cannot get much of an 00Index.dcf: If I
> use --force to build the package, the 00Index.dcf will be replaced with an
> empty file (size 0 bytes). Further, I haven't figured out how to transfer the
> \VignetteIndexEntry to the ultimate pdf file. All my attempts to write the
> 00Index.dcf file manually have ended with R sarcastically saying to me that
> my index is not up-to-date and writing over my file with an empty file
> (obviously I should be more careful in my hand writing...).

I have not figured this out either, but the index is not much of a problem if
the \VignetteIndexEntry generates it. I am not certain of the relationship of
00Index.dcf  to the ultimate pdf file.

> - It seems that it is necessary to use Makefile because R CMD BUILD doesn't
> clean the inst/doc directory from the interim files Sweave produces to build the
> pdf (foo-???.eps, foo-???.pdf, LaTeX files like foo.blg, foo.bbl, foo.aux,
> foo.log, etc). Is there any other solution here?

I have been using Makefiles, so I haven't consider other solutions. I don't
believe R CMD build actually generates the files there, although I may be wrong
on this point. If they are already there from running checkVignettes(), then
build will copy them unless you indicate otherwise in .Rbuildignore (and have a
version of tar more recent than 1.13 - which is the most recent version on the
GNu site ;-) ).  

> - Is it indeed the purpose that the final document should be a pdf file even in
> source packages. The pdf files tend to become huge, and easily multiply the size
> of a source package. As I have a 56KB modem at home (working at ~5KB file
> transfer speed in practice) I am really concerned with this aspect as well (it
> doesn't concern me at all when at work). Is the assumption that users won't have
> tools to build a pdf from the Sweave source?

Well, I just asked this question yesterday (privately to Friedrich) and have not
yet heard back. My inclination is to distribute the .Stex files and a .pdf file,
so users can attempt to generate the guide, but will have it if they cannot. I
haven't looked at how big this will be. I suppose another option would be to put
the .pdf file on a web site.

Best,
Paul Gilbert

> cheers, jari oksanen
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._