rterface (21apr13)

git-svn-id: svn://tug.org/texlive/trunk@30084 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 231 insertions, 1 deletions

diff --git a/Master/texmf-dist/doc/latex/rterface/README b/Master/texmf-dist/doc/latex/rterface/README
new file mode 100644
index 00000000000..fb8b3ead74c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rterface/README
@@ -0,0 +1,5 @@
+rterface -- an interface to use R in LaTeX
+
+See the manual rterface.pdf for details.  This file is licensed under the LaTeX Public project license.
+
+To submit a bug report or to request new features, e-mail me at thomasbogue@gmail.com
diff --git a/Master/texmf-dist/doc/latex/rterface/rterface.pdf b/Master/texmf-dist/doc/latex/rterface/rterface.pdf
new file mode 100644
index 00000000000..4284b3e6981
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rterface/rterface.pdf
diff --git a/Master/texmf-dist/doc/latex/rterface/rterface.tex b/Master/texmf-dist/doc/latex/rterface/rterface.tex
new file mode 100644
index 00000000000..056b2a2c6c5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rterface/rterface.tex
@@ -0,0 +1,145 @@
+%  Copyright 2013 Thomas Bogue
+% 
+%  This work may be distributed and/or modified under the
+%  conditions of the LaTeX Project Public License, either version 1.3
+%  of this license or (at your option) any later version.
+%  The latest version of this license is in
+%    http://www.latex-project.org/lppl.txt
+%  and version 1.3 or later is part of all distributions of LaTeX
+%  version 2005/12/01 or later.
+% 
+%  This work has the LPPL maintenance status `maintained'.
+%  
+%  The Current Maintainer of this work is Tom Bogue
+% 
+%  This work consists of the files rterface.tex and r.sty
+%  and the derived file r.pdf.
+
+\documentclass{article}
+\usepackage{rterface}
+\usepackage{amsmath}
+\usepackage{hyperref}
+
+\newcommand{\DescribeMacro}[2]{\par\noindent\texttt{#1}\par\noindent#2}
+\newcommand{\oarg}[1]{[ \emph{#1} ]}
+\newcommand{\marg}[1]{\{ \emph{#1} \}}
+
+\title{rterface package documentation}
+\author{Tom Bogue \url{thomasbogue@gmail.com}}
+\begin{document}
+\maketitle
+
+\begin{abstract}
+This package allows the user to interface with R from the \LaTeX\ environment.  This allows the user to freely mix the reporting and typesetting capabilities of \LaTeX\ with the numerical abilities of R, for a form of literate analysis.
+\end{abstract}
+
+ \section{Usage}
+\subsection{compilation}
+\emph{This package requires modification of the commands used to compile a document.}  It requires an additional pass, and R must be invoked to process the numerical data.  Normally the sequence 
+\begin{verbatim}
+latex filename
+R --slave < filename.R > filename.R.out
+latex filename
+latex filename
+dvips filename.ps
+ps2pdf filename.pdf
+\end{verbatim}
+will serve.  This works in both Unix and Windows under the command line if necessary programs are on the path.
+
+To summarize, the following steps are necessary to use this package
+\begin{enumerate}
+\item run latex on the source file
+\item run the command \texttt{R --slave < filename.R > filename.R.out}
+\item process the source file as normal (i.e. run latex twice to ensure references are correct, and if necessary process the dvi to the necessary final file format)
+\end{enumerate}
+
+\DescribeMacro{\textbackslash{}Rvalue\oarg{significant figures}\marg{expression}}
+This command will instruct R to evaluate the expression, round the result to the specified number of significant figures (default is 4), and display the result inline in your document.
+
+Since this command rounds, the expression must evaluate to a number.  If your expression evaluates to a string, use \verb|\Rvalue*| instead.
+To execute R commands, use the \LaTeX\ command
+
+\DescribeMacro{\textbackslash{}Rvalue*\oarg{significant figures}\marg{expression}}
+This command functions like the unstarred version, but does not round the resulting value.  It can display string values.
+
+\DescribeMacro{\textbackslash{}Rcmd\marg{command}}
+This command will be passed to R to be executed.  Nothing is displayed in your document from this command, but it can affect variables which can later be displayed.
+
+The most common use for this function is to set a variable.
+
+\DescribeMacro{\textbackslash{}Rset\oarg{significant figures}\marg{variable}\marg{expression}}
+This command will set the specified variable equal to the specified expression.  It will also display the assignment and the result of the expression in the document.
+
+\DescribeMacro{\textbackslash{}Rset*\oarg{significant figures}\marg{variable}\marg{expression}}
+This is just like \texttt{Rset}, but will not display the expression, only the resulting value.
+
+\DescribeMacro{\textbackslash{}Rcode\marg{expression}}
+Like \texttt{\textbackslash{}Rcmd}, this will instruct R to evaluate the expression.  It will also display the expression in your document.
+
+\DescribeMacro{\textbackslash{}Rtable\marg{col1,col2,...}\marg{num rows}}
+This command produces the body of a \LaTeX\ formatted table using the given values.  Multiple columns can be listed by separating the columns with commas.  The number of rows must be specified separately as the second argument.
+
+The results here are not rounded, but may be strings.  To round values, use the R function \texttt{round} or \texttt{signif} on a column.
+
+\section{R definitions}
+A small number of R functions and variables are defined in addition to the \LaTeX\ macros.  The most important of these allows users to easily format numbers as percentages.
+\subsection{topercent(value,decimal places=0)}
+This function converts the specified value to a percentage with the specified number of decimal places.  Note that since the result is a string, it can only be displayed via the \verb|\Rvalue*| macro.
+\subsection{variables}
+\begin{tabular}{l r}
+name & value\\
+\hline
+backslash & "\textbackslash"\\
+percent & "\%"\\
+\end{tabular}
+
+\section{Examples}
+\subsection{Quadratic Formula}
+Consider solving a quadratic equation.  Using the code
+\begin{verbatim}
+\Rcmd{a<-3}
+\[ a = \Rvalue{a} \]
+\Rcmd{b<-4}
+\[ b = \Rvalue{b} \]
+\Rcmd{c<--2}
+\[ c = \Rvalue{c} \]
+
+\Rcmd{xm<-(b-sqrt(b^2-4*a*c))/(2*a)}
+\Rcmd{xp<-(b+sqrt(b^2-4*a*c))/(2*a)}
+\[ x = \frac{b \pm \sqrt{b^2-4 a c}}{2 a} = \Rvalue{xm},\Rvalue{xp}\]
+\end{verbatim}
+produces the output
+\Rcmd{a<-3}
+\[ a = \Rvalue{a} \]
+\Rcmd{b<-4}
+\[ b = \Rvalue{b} \]
+\Rcmd{c<--2}
+\[ c = \Rvalue{c} \]
+
+\Rcmd{xm<-(b-sqrt(b^2-4*a*c))/(2*a)}
+\Rcmd{xp<-(b+sqrt(b^2-4*a*c))/(2*a)}
+\[ x = \frac{b \pm \sqrt{b^2-4 a c}}{2 a} = \Rvalue{xm},\Rvalue{xp}\]
+
+\subsection{Table}
+If we wanted a table of perfect squares, we could use the code
+\begin{verbatim}
+\begin{tabular}{l r}
+$x$ & $x^2$\\
+\hline
+\Rtable{1:5,(1:5)^2}{5}
+\end{tabular}
+\end{verbatim}
+to produce the following output
+
+\begin{tabular}{l r}
+$x$ & $x^2$\\
+\hline
+\Rtable{1:5,(1:5)^2}{5}
+\end{tabular}
+
+\section{Troubleshooting}
+The first run-through of the document produces the R code which then can be used to create the data to be displayed.  Because of this, on the first pass \textbackslash{}Rvalue produces no output, and \textbackslash{}Rtable produces only \verb|0\\|.  This is usually harmless, but can cause \LaTeX\ to balk, especially if in a table which is formated in strange ways.  
+
+I'd prefer a more elegant solution, but normally hitting the enter key until \LaTeX\ finishes this first run will solve all issues.
+
+\end{document}
diff --git a/Master/texmf-dist/tex/latex/rterface/rterface.sty b/Master/texmf-dist/tex/latex/rterface/rterface.sty
new file mode 100644
index 00000000000..a578551d55a
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/rterface/rterface.sty
@@ -0,0 +1,79 @@
+%%
+%% Copyright (C) 2013 by Thomas Bogue
+%% This file may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either
+%% version 1.2 of this license or (at your option) any later
+%% version. The latest version of this license is in:
+%% 
+%% http://www.latex-project.org/lppl.txt
+%% 
+%% and version 1.2 or later is part of all distributions of
+%% LaTeX version 1999/12/01 or later.
+%% 
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{rterface}[2013/04/19 interface to the R computational program from within LaTeX]
+\RequirePackage{newfile}
+
+\newoutputstream{Routput}
+\openoutputfile{\jobname.R}{Routput}
+\newinputstream{Rinput}
+\IfFileExists{\jobname.R.out}{}{% if input file doesn't exist
+\PackageWarning{r}{the R output file \jobname.R.out doesn't exist -- create it by running R --slave < \jobname.R > \jobname.R.out}%
+\newoutputstream{Rtmp}% create it with no content
+\openoutputfile{\jobname.R.out}{Rtmp}%
+\addtostream{Rtmp}{0}%
+\closeoutputstream{Rtmp}%
+}
+\openinputfile{\jobname.R.out}{Rinput}
+\AtEndDocument{%
+\closeoutputstream{Routput}%
+\closeinputstream{Rinput}%
+}
+\begin{writeverbatim}{Routput}
+backslash<-"\\"
+percent<-"%"
+latex.table<-function(data,nrows) {
+tmp<-unlist(data);dim(tmp)<-c((nrows),length(tmp)/nrows);
+for (i in 1:dim(tmp)[1]) {
+  cat(tmp[i,1]);
+  for (j in 2:dim(tmp)[2]) {
+    cat(" &",tmp[i,j]);
+  };
+  cat("\\\\");
+};
+}
+topercent<-function(x,r=0){paste(round(x*100,r),"\\%",sep="")}
+\end{writeverbatim}
+\newcommand{\Rtilde}{\addtostream{Routput}{\noexpand~}}
+\def\Rcmd{\@Rbreakcodes\@Rcmdwitharg}
+\def\@Rcmdwitharg#1{\immediate\addtostream{Routput}{invisible({#1})}\@Rfixcodes}
+\newcommand{\Rvalue}{\@ifstar\@Rvaluestar\@Rvalue}
+\newcommand{\@Rvalue}[2][4]{\ensuremath{\textrm{\@Rvaluestar{signif(#2,#1)}}}}
+\newcommand{\@Rvaluestar}[1]{\addtostream{Routput}{cat(#1,"\@backslashchar n")}\readaline{Rinput}}
+
+\newcommand{\Rtable}[2]{%
+\ifeof\@nameuse{Rinputinstre@m}%
+\addtostream{Routput}{cat(latex.table(c(#1),#2),"\@backslashchar n")}%
+0\\%
+\else%
+\Rvalue*{latex.table(c(#1),#2)}%
+\fi%
+}
+
+\newcommand{\Rset}{\@Rbreakcodes\@ifstar\@Rsetstar\@Rset}
+\newcommand{\@Rset}[3][4]{\Rcmd{#2<-#3}\@Rcodeformat{#2 = #3 = \Rvalue[#1]{#3}}\@Rfixcodes}
+\newcommand{\@Rsetstar}[3][4]{\Rcmd{#2<-#3}\@Rcodeformat{#2 = \Rvalue[#1]{#3}}\@Rfixcodes}
+\newcommand{\Rcode}{\@Rbreakcodes\@Rcode}
+\newcommand{\@Rfixcodes}{\catcode`\%=14\catcode`\$=3\catcode`\^=7\catcode`\_=8\catcode`\&=4\catcode`~=13}
+\newcommand{\@Rbreakcodes}{\catcode`\$=11%
+\catcode`\^=11%
+\catcode`\_=11%
+\catcode`\&=11%
+\catcode`~=11%
+\catcode`~=11}
+\def\@Rcode#1{\Rcmd{#1}\@Rcodeformat{#1}\@Rfixcodes}
+%\newcommand{\@Rcodeformat}[1]{\noindent\obeyspaces\texttt{#1}\\\noindent}
+\newcommand{\@Rcodeformat}[1]{\par\noindent\obeyspaces\texttt{#1}\par\noindent}
+
+\newlength{\@Rtmplength}
+\settowidth{\@Rtmplength}{\Rvalue{0}}
diff --git a/Master/tlpkg/bin/tlpkg-ctan-check b/Master/tlpkg/bin/tlpkg-ctan-check
index f17df2f1a24..0c3bd0319ee 100755
--- a/Master/tlpkg/bin/tlpkg-ctan-check
+++ b/Master/tlpkg/bin/tlpkg-ctan-check
@@ -375,7 +375,7 @@ my @TLP_working = qw(
     robustcommand robustindex romanbar romande romanneg romannum romansh
     rotating rotfloat rotpages roundbox
     rrgtrees rsc rsfs rsfso
-    rtkinenc rtklage russ rviewport rvwrite ryethesis
+    rterface rtkinenc rtklage russ rviewport rvwrite ryethesis
   sa-tikz sageep sansmath sansmathaccent sapthesis sasnrdisplay sauerj
     sauterfonts savefnmark savesym savetrees
     scale scalebar scalerel schemabloc schemata schulschriften schwalbe-chess
diff --git a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
index da4d1474ef7..d718ed1a56f 100644
--- a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
+++ b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
@@ -671,6 +671,7 @@ depend romansh
 depend rotfloat
 depend rotpages
 depend roundbox
+depend rterface
 depend rtkinenc
 depend rvwrite
 depend sauerj
diff --git a/Master/tlpkg/tlpsrc/rterface.tlpsrc b/Master/tlpkg/tlpsrc/rterface.tlpsrc
new file mode 100644
index 00000000000..e69de29bb2d
--- /dev/null
+++ b/Master/tlpkg/tlpsrc/rterface.tlpsrc