%Usage: library(tools);Sweave('sol2.nw'); pdflatex sol2
% or  : Sweave sol2; pdflatex sol2 (from Linux prompt)
\documentclass{article}
\bibliographystyle{plain}
\usepackage{setspace,relsize}   % needed for latex(describe()), \code
\usepackage{moreverb}           % for verbatimtabinput
\usepackage[pdftex]{lscape}   % allows tables to be landscape when
\usepackage{longtable}
\usepackage{url}
\newcommand{\code}[1]{\texttt{\smaller #1}}

\title{How to incorporate the proper R citation into you
\texttt{Sweave} documents}
\author{Theresa A Scott, MS}

\begin{document}
% \SweaveOpts{prefix.string=pspdf/foo}
% \setkeys{Gin}{width=1.0\textwidth} % default is 0.8
\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview of Making Bibliographies in \LaTeX{}}
According to Antoni Diller's \emph{\LaTeX{}  Line by Line} (2nd
edition; a book I highly recommend), BibTeX is a widely available
system used for producing bibliographies in conjunction with \LaTeX{}
(see Chapter 6).\\

\noindent In order to use it you first have to create a file with
extension \texttt{.bib} containing a sequence of entries and then in
your \LaTeX{} input file it is necessary to include
\texttt{$\backslash$cite} commands and some additional commands
peculiar to BibTeX which tell it how to format the bibliography it
produces and what the names of the \texttt{.bib} files containing
database entries are that it should use.\\

\noindent The \texttt{citation} and \texttt{toBibtex} functions in R
produce the entry output that you need to place (and modify slightly)
in the \texttt{.bib} file:

<<>>=
citation()
toBibtex(citation())
@

\noindent Copy and paste the \texttt{toBibtex(citation(())} output to
a file.  For this demonstration, I copied and pasted the output to
\texttt{Rbiblioref.bib} and saved the file in my home directory
(\texttt{/home/scottt}).  If you plan to reference the R citation in
many of your Sweave documents, I would recommend saving the
\texttt{.bib} file that you create in your home directory so you can
reference the file from any of your project directories.\\

\noindent  A \texttt{.bib} file contains one or more entries which
look something like the R citation you copied and pasted.  The
general form of such an entry is \emph{publication-type\{key,
field-list\}}.  Chapter 6 of Diller's book cover the available
possibilities for \emph{publication-type} in great detail.  For the R
citation, the \emph{publication-type} is \texttt{@manual}, which is
used for manuals and similar kinds of technical
documentation.\\

\noindent What we need to modify in the R citation entry in the
\texttt{.bib} file is the \emph{key}, which is what will appear in
any \texttt{$\backslash$cite} commands that you use to refer to the
publication in question.  The \emph{key} is made up of letters,
numerals and punctuation other than the comma.  For this
demonstration, I modified the blank key produced by
\texttt{toBibtex(citation())} to \texttt{rdct:r} in the
\texttt{Rbiblioref.bib} file.  Therefore, when we want to cite the R
reference in our Sweave file, we will use
\texttt{$\backslash$cite\{rdct:r\}}.  Section 4.9 of Diller covers the
\texttt{$\backslash$cite} command and the alternative
\texttt{thebibliography} environment in \LaTeX{} in much greater
detail.
\\

\noindent After this change, your \texttt{.bib} file should look
something like this:\\
\texttt{@Manual\{rdct:r,\\
  title = \{R: A Language and Environment for Statistical
Computing\},\\
  author = \{\{R Development Core Team\}\},\\
  organization = \{R Foundation for Statistical Computing\},\\
  address = \{Vienna, Austria\},\\
  year = \{2006\},\\
  note = \{\{ISBN\} 3-900051-07-0\},\\
  url = \{http://www.R-project.org\},\\
\}}\\

\noindent Now we need to discuss how to get BibTeX to produce a
bibliography for you.  In order to do so, it is necessary to include
a \texttt{$\backslash$bibliographystyle} and a
\texttt{$\backslash$bibliography} command inside the
\texttt{document} environment of your Sweave (i.e., input) file.  The
\texttt{$\backslash$bibliographystyle} command usually comes
immediately after the \texttt{$\backslash$begin\{document\}} command,
but it has to come before any \texttt{$\backslash$cite} commands; and
the \texttt{$\backslash$bibliography} command usually comes close to
the end of the \texttt{document} environment in the place where you
want the bibliography produced to occur.\\

\noindent The general style of the
\texttt{$\backslash$bibliographystyle} command is
\texttt{$\backslash$bibliographystyle\{\emph{bib-style}\}}, where
\emph{bib-style} can be \texttt{plain}, \texttt{unsrt},
\texttt{abbrv}, or \texttt{alpha}.  For this demonstration, I used
\texttt{$\backslash$bibliographystyle\{plain\}}, which will produce
``regular" bibliography in which the entries are sorted automatically
by BibTeX.\\

\noindent The general format of the \texttt{$\backslash$bibliography}
command is \texttt{$\backslash$bibliography\{\emph{bib-file-list}\}},
where \emph{bib-file-list} is a list of the first or base names of one
or more \texttt{.bib} files.  Note, if the list contains more than one
member, then they should be separated by commas.  For this
demonstration, I specified
\texttt{$\backslash$bibliography\{$\backslash$home$\backslash$
scottt$\backslash$Rbiblioref.bib\}} one line above the
\texttt{$\backslash$end\{document\}} command.  Using the absolute
reference of \texttt{Rbiblioref. bib} (i.e.,
\texttt{$\backslash$home$\backslash$
scottt$\backslash$Rbiblioref.bib}) allows me to reference the file
from any project subdirectory.\\

\noindent Look at the \texttt{.nw} version of this file to make sure
you understand where to place the
\texttt{$\backslash$bibliographystyle} and
\texttt{$\backslash$bibliography} commands.\\

\noindent Once we have our \texttt{.bib} and Sweave files all set,
and we've referenced the R citation at least once using the
appropriate \texttt{$\backslash$cite} command, we need to run our
Sweave file through the proper sequence of programs in order for the
bibliography to be generated correctly.  We first need to run our
Sweave file through \texttt{Sweave} in order to generate the
\texttt{.tex} file.  We then need to run our \texttt{.tex} file
through \LaTeX{} (\texttt{latex}) at least twice in order to get the
cross-referencing information of our bibliography into our output --
the first time you run \LaTeX{} the information in the \texttt{.bib}
file is written to the \texttt{.aux} file and the next time you run
\LaTeX{} this information is used to generate the labels that appear
in your output.  After running \texttt{Sweave} and \texttt{latex}
twice, you need to run \texttt{bibtex} in order to process the input
file using BibTeX.  Laslty, we can run our file through
\texttt{pdflatex} (at least twice) to convert the \LaTeX{} output into
a \texttt{.pdf} file.\\

\noindent A shortcut to use from the console command line in order to
run our input file through all of these programs is the
\texttt{\&\&}:\\
\texttt{Sweave RCitation \&\& latex RCitation \&\& latex RCitation
\&\& \\ bibtex RCitation \&\& pdflatex RCitation \&\& pdflatex
RCitation}\\
where \texttt{RCitation} is the name of my \texttt{.nw} file.  
Placing \texttt{\&\&} in between each command allows you to run
several commands from the same command line, and the sequence of
commands will terminate wherever along the line an error occcurs.\\

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Citing R in your \texttt{Sweave} document}
In order to properly cite R and the packages you've used in your \texttt{Sweave}
document, my suggestion is to include the following sentence in your
\texttt{.nw} file:\\
\texttt{All analyses were performed using the R statistical software\\
$\backslash$Sexpr\{R.Version()\$version.string\}
$\backslash$cite\{rdct:r\}}. \\

\noindent \texttt{$\backslash$Sexpr\{R.Version()\$version.string\}}
will place the version of R you are currently using, which is
the output of running \texttt{R.Version()\$version.string} from the R
command line, into your sentence. 
\texttt{$\backslash$cite\{rdct:r\}} will properly insert a reference
to the R citation. \\

\noindent The finished output of the above sentence will look
something like the following, inserting the bibliography at the end
of the file:\\
All analyses were performed using the R statistical software
\Sexpr{R.Version()$version.string} \cite{rdct:r}.  Specific analyses were 
performed using the Hmisc \cite{fh:Hmisc}, Design \cite{fh:Design}, and maps \cite{maps:R} packages.


\bibliography{/home/scottt/Rbiblioref}
\end{document}