R help - Feb 2008 - How to include the documentation of a function in a Sweave document?

Dear R-help,

I would like to include the documentation of an R function in an
*.rnw document processed by Sweave. Because I'm sharing my *.rnw
files with colleagues under Linux and Windows (I'm on Mac OS X),
I would like a pure R solution.

The naive approach doesn't work, because Sweaving this *.rnw
file:

-------- tmp.rnw --------
\documentclass{article}
\begin{document}
<<>>?plot
@
\end{document}
-------- tmp.rnw --------

yields the following LaTeX file on my platform (session info at the end):

-------- tmp.tex --------
\documentclass{article}
\usepackage{/Library/Frameworks/R.framework/Resources/share/texmf/Sweave}
\begin{document}
\begin{Schunk}
\begin{Sinput}
>  `?`(plot)
\end{Sinput}
\end{Schunk}
\end{document}
-------- tmp.tex --------

in which no Soutput has been generated. Is it possible to redirect the
help output, in a platform-independent way, so that it is included in
the Soutput environment of the LaTeX file?

Best,

Jean
>  sessionInfo()
R version 2.6.2 (2008-02-08)
i386-apple-darwin8.10.1

locale:
C

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

loaded via a namespace (and not attached):
[1] rcompgen_0.1-17

-- 
Jean R. Lobry            (lobry at biomserv.univ-lyon1.fr)
Laboratoire BBE-CNRS-UMR-5558, Univ. C. Bernard - LYON I,
43 Bd 11/11/1918, F-69622 VILLEURBANNE CEDEX, FRANCE
allo  : +33 472 43 27 56     fax    : +33 472 43 13 88
http://pbil.univ-lyon1.fr/members/lobry/

Jean lobry wrote:
> Dear R-help,
>
> I would like to include the documentation of an R function in an
> *.rnw document processed by Sweave. Because I'm sharing my *.rnw
> files with colleagues under Linux and Windows (I'm on Mac OS X),
> I would like a pure R solution.
>
> The naive approach doesn't work, because Sweaving this *.rnw
> file:
>
> -------- tmp.rnw --------
> \documentclass{article}
> \begin{document}
> <<>>> ?plot
> @
> \end{document}
> -------- tmp.rnw --------
>
> yields the following LaTeX file on my platform (session info at the end):
>
> -------- tmp.tex --------
> \documentclass{article}
> \usepackage{/Library/Frameworks/R.framework/Resources/share/texmf/Sweave}
> \begin{document}
> \begin{Schunk}
> \begin{Sinput}
>
>   
>>  `?`(plot)
>>     
> \end{Sinput}
> \end{Schunk}
> \end{document}
> -------- tmp.tex -------
> -
>
> in which no Soutput has been generated. Is it possible to redirect the
> help output, in a platform-independent way, so that it is included in
> the Soutput environment of the LaTeX file?
>
> Best,
>
> Jean
>
>   
>>  sessionInfo()
>>     
> R version 2.6.2 (2008-02-08)
> i386-apple-darwin8.10.1
>
> locale:
> C
>
> attached base packages:
> [1] stats     graphics  grDevices utils     datasets  methods   base
>
> loaded via a namespace (and not attached):
> [1] rcompgen_0.1-17
>
>   
Maybe a clue: we can use
cat(readLines(as.character(?plot)),sep="\n")

to display the help (here, of plot) directly to the screen. So we could
use something like:

<<echo=TRUE,print=FALSE,eval=FALSE>>?plot
@


<<echo=FALSE,print=TRUE,eval=TRUE>>cat(readLines(as.character(?plot)),sep="\n")
@

But this doesn't work (latex compilation error) as weird characters 
appear in the produced tex, at some places (tabulations?), like:

_T_h_e _D_e_f_a_

(not sure what it will look like in this email, but emacs reads things
like _^HT_^HH_^He...).

Maybe an encoding problem? I tried specifying different encoding to 
readLines, with no luck (latin1, UTF-8). Otherwise, the help appears in 
the .tex.

Cheers,

Thibaut.



 > sessionInfo()
R version 2.6.2 (2008-02-08)
i686-pc-linux-gnu

locale:
LC_CTYPE=en_US.UTF-8;LC_NUMERIC=C;LC_TIME=en_US.UTF-8;LC_COLLATE=en_US.UTF-8;LC_MONETARY=en_US.UTF-8;LC_MESSAGES=en_US.UTF-8;LC_PAPER=en_US.UTF-8;LC_NAME=C;LC_ADDRESS=C;LC_TELEPHONE=C;LC_MEASUREMENT=en_US.UTF-8;LC_IDENTIFICATION=C

attached base packages:
[1] datasets  utils     stats     graphics  grDevices methods   base

other attached packages:
[1] phylobase_0.3  nlme_3.1-87    ape_2.1-1      adegenet_1.1-0 
pixmap_0.4-7
[6] ade4_1.4-5     MASS_7.2-41

loaded via a namespace (and not attached):
[1] grid_2.6.2      lattice_0.17-6  rcompgen_0.1-17 tcltk_2.6.2
[5] tools_2.6.2


-- 
######################################
Thibaut JOMBART
CNRS UMR 5558 - Laboratoire de Biom?trie et Biologie Evolutive
Universite Lyon 1
43 bd du 11 novembre 1918
69622 Villeurbanne Cedex
T?l. : 04.72.43.29.35
Fax : 04.72.43.13.88
jombart at biomserv.univ-lyon1.fr
http://lbbe.univ-lyon1.fr/-Jombart-Thibaut-.html?lang=en
http://adegenet.r-forge.r-project.org/

You can use '\include' also:

\documentclass{article}
\begin{document}

\include{/usr/local/lib/R/library/graphics/latex/plot}
%file.path(system.file(package="graphics"), "latex",
"plot")

\end{document}

I don't know if there is a way of input file.path in include by Sweave.


On 25/02/2008, Jean lobry <lobry at biomserv.univ-lyon1.fr>
wrote:
> Dear R-help,
>
>  I would like to include the documentation of an R function in an
>  *.rnw document processed by Sweave. Because I'm sharing my *.rnw
>  files with colleagues under Linux and Windows (I'm on Mac OS X),
>  I would like a pure R solution.
>
>  The naive approach doesn't work, because Sweaving this *.rnw
>  file:
>
>  -------- tmp.rnw --------
>  \documentclass{article}
>  \begin{document}
>  <<>>>  ?plot
>  @
>  \end{document}
>  -------- tmp.rnw --------
>
>  yields the following LaTeX file on my platform (session info at the end):
>
>  -------- tmp.tex --------
>  \documentclass{article}
>  \usepackage{/Library/Frameworks/R.framework/Resources/share/texmf/Sweave}
>  \begin{document}
>  \begin{Schunk}
>  \begin{Sinput}
>  >  `?`(plot)
>  \end{Sinput}
>  \end{Schunk}
>  \end{document}
>  -------- tmp.tex --------
>
>  in which no Soutput has been generated. Is it possible to redirect the
>  help output, in a platform-independent way, so that it is included in
>  the Soutput environment of the LaTeX file?
>
>  Best,
>
>  Jean
>
>  >  sessionInfo()
>  R version 2.6.2 (2008-02-08)
>  i386-apple-darwin8.10.1
>
>  locale:
>  C
>
>  attached base packages:
>  [1] stats     graphics  grDevices utils     datasets  methods   base
>
>  loaded via a namespace (and not attached):
>  [1] rcompgen_0.1-17
>
>  --
>  Jean R. Lobry            (lobry at biomserv.univ-lyon1.fr)
>  Laboratoire BBE-CNRS-UMR-5558, Univ. C. Bernard - LYON I,
>  43 Bd 11/11/1918, F-69622 VILLEURBANNE CEDEX, FRANCE
>  allo  : +33 472 43 27 56     fax    : +33 472 43 13 88
>  http://pbil.univ-lyon1.fr/members/lobry/
>
>  ______________________________________________
>  R-help at r-project.org mailing list
>  https://stat.ethz.ch/mailman/listinfo/r-help
>  PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
>  and provide commented, minimal, self-contained, reproducible code.
>

-- 
Henrique Dallazuanna
Curitiba-Paran?-Brasil
25? 25' 40" S 49? 16' 22" O

Dear all,

thanks for your suggestions. I like the idea of including directly
the LaTeX file corresponding to the targeted topic, however, my
understanding from the reading of ?help is that these LaTeX files
are not always available, depending on the build of R.

I found a solution that works well enough for me by removing
the backslashes from the help file this way:

-------- tmp.rnw --------
\documentclass{article}
\begin{document}

<<mypager,echo=F,eval=T>>mypager <- function(..., header =
rep("", nfiles),
           title = "R Information", delete.file = FALSE){
   args <- list(...)
   sanitize <- function(strings){
     f <- function(x){
       x.raw <- charToRaw(x)
       backspaces <- which(x.raw == charToRaw('\b'))
       if(length(backspaces) > 0){
         x.raw <- x.raw[-c(backspaces, backspaces - 1)] # remove
"_\b"
       }
       rawToChar(x.raw[x.raw >= as.raw(20)]) # remove non-printable ASCII
     }
     res <- sapply(strings, f)
     names(res) <- NULL
     return(res)
   }
   help.out <- lapply(args[[1]], readLines)
   help.out <- lapply(help.out, sanitize)
   lapply(help.out, cat, sep = "\n")
}
@

<<echo=T,print=F,eval=F, keep.source=T>>?plot
@
<<echo=F,print=T,eval=T>>help("plot", chmhelp = FALSE,
htmlhelp = FALSE, pager = mypager)
@

\end{document}
-------- tmp.rnw --------

This works well for me when I'm Sweaving the file from an R
session in the CLI interface in a terminal, but not when I'm
Sweaving the file from the R GUI for the Mac (the function
mypager is not called despite pager = mypager when calling
the help function, don't understand why).

The PDF looks like this:
http://pbil.univ-lyon1.fr/members/lobry/tmp/tmp.pdf

Thanks again for your help,

Best,

Jean

-- 
Jean R. Lobry            (lobry at biomserv.univ-lyon1.fr)
Laboratoire BBE-CNRS-UMR-5558, Univ. C. Bernard - LYON I,
43 Bd 11/11/1918, F-69622 VILLEURBANNE CEDEX, FRANCE
allo  : +33 472 43 27 56     fax    : +33 472 43 13 88
http://pbil.univ-lyon1.fr/members/lobry/