[Rd] improving ?RweaveLatex

[Martin Maechler]

>>>>> Marc Schwartz <marc_schwartz at me.com>
>>>>>     on Sat, 22 Aug 2009 16:51:31 -0500 writes:

    > <snip>
    > On Aug 22, 2009, at 4:30 PM, Marc Schwartz wrote:
    >> 
    >> I have some proposed modifications to RweaveLatex.Rd which I include  
    >> here as a patch against the R-devel version of the file from svn. I  
    >> have added comments about the issue that Liviu raised, the use of  
    >> the [nogin] option and while I was at it, the [noae] option as well.  
    >> There are added to the 'details' section of the file.

    > OK, once more....

    > I noted a typo and also neglected to add pointers to the Details  
    > section in the descriptions of the height and width options.

    > Here is a corrected version of the patch file.

Thank you very much, Marc.

I was going to commit a version of this
(using \samp{..} in a few places where you had \code{..}:
 Note that \code{..} is meant to be for  R - code only),

but then I started reading more carefully what you've proposed,
and I think it needs to be clarified even further
(see inline below):


    > --- RweaveLatexOld.Rd	2009-08-22 15:45:29.000000000 -0500
    > +++ RweaveLatex.Rd	2009-08-22 16:49:00.000000000 -0500
    > @@ -49,6 +49,30 @@
    > \env{SWEAVE_STYLEPATH_DEFAULT}, or is \code{FALSE} it that is unset or
    > empty.  If set, it should be exactly \code{TRUE} or \code{FALSE}: any
    > other values are taken as \code{FALSE}.
    > +
    > +  By default, \file{Sweave.sty} sets the width of all included graphics to:
    > +
    > +  \code{\\setkeys{Gin}{width=0.8\\textwidth}}
    > +
    > +  You can adjust this by including the above in your .Rnw file after the
    > +  \code{\\begin{document}} directive and adjust the \code{width}
    > +  parameter above accordingly. Note that this parameter determines the actual
    > +  graphic dimensions in your final document and therefore overrides the
    > +  \code{height} and \code{width} options that you may use in each
    > +  figure chunk or have set globally. The \code{height} and \code{width}
    > +  options will determine the dimensions of the runtime generated
    > +  PDF and EPS files created in this setting.

I  think the above is not entirely correct (or then, still
enough confusing to confuse me ;-) :

The 'Gin' setting is about how  LaTeX's \includegraphics{}
works and how that *scales* the  PDF and EPS files.
And as you say above, the  'height' and 'width' determine how
the PDF and EPS files are generated.

Consequently, I would not say that the 'Gin' ``overrides''  the 
(width, height) settings of the graphic file, but rather 
influences how these  (width, height) ranges are further
transformed into the final document.   But e.g. font and plot
symbol sizes are *scaled* dependent on both the (width/height)
and the 'Gin' setting.

In short,  Gin, width, height, are three related but different
"knobs" you can turn.

Marc, I'll send you my version of your improved Rweavelatex.Rd,
so if you want you can make it even better..

    > +  If you wish to override this default behavior, you can use
    > +  \code{\\usepackage[nogin]{Sweave}} in your preamble. In this case, the
    > +  \code{height} and \code{width} options will determine the runtime
    > +  generated graphic file sizes and the size of the graphics in your
    > +  final document.

I'd also change the above: Along the following point:

 In *any* case,  (height,width) determines the dimension of the
 graphic file.
 In the case of 'nogin', the graphic files are not scaled *any
 further* for latex inclusion.


Thanks a lot, to Marc, once again!
Martin

    > +  \file{Sweave.sty} also supports the \code{[noae]} option, which
    > +  suppresses the use of the \code{ae} package, the use of which may
    > +  interfere with certain encoding and typeface selections. If you have
    > +  problems in the rendering of certain character sets, try this option.  
    > }
    > \section{Supported Options}{
    > \code{RweaveLatex} supports the following options for code chunks (the values
    > @@ -101,8 +125,8 @@
    > generated. Ignored if \code{fig = FALSE}.}
    > \item{pdf.version, pdf.encoding:}{passed to \code{\link{pdf}} to set
    > the version and encoding.  Defaults taken from \code{pdf.options()}.}
    > -    \item{width:}{numeric (6), width of figures in inches.}
    > -    \item{height:}{numeric (6), height of figures in inches.}
    > +    \item{width:}{numeric (6), width of figures in inches. See \sQuote{Details}.}
    > +    \item{height:}{numeric (6), height of figures in inches. See \sQuote{Details}.}
    > \item{expand:}{logical (\code{TRUE}).  Expand references to other chunks
    > so that only R code appears in the output file.  If \code{FALSE}, the
    > chunk reference (e.g. \code{<<chunkname>>}) will appear.  The