tikzDevice.Rnw

% !TEX TS-program = Sweave

\documentclass{article}

% \VignetteIndexEntry{The tikzDevice Package}
% \VignetteDepends{tikzDevice}
% \usepackage{Sweave}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[scaled=.85]{inconsolata}
\usepackage[colorlinks]{hyperref}

% Extra text effects (strikethrough)
\usepackage{ulem}

% Various TeX logos---included in the Oberdiek bundle which contains hyperref,
% so there is a good chance it will be installed.
\usepackage{hologo}

% Sexyness
\usepackage{tikz}
\usetikzlibrary{calc,positioning}
\usetikzlibrary{shapes.multipart,shapes.geometric,shapes.symbols,shapes.arrows}
\usetikzlibrary{decorations.shapes,decorations.text,decorations.pathreplacing}

% Page layout
\usepackage[parfill]{parskip}
\usepackage[letterpaper,margin=1in]{geometry}
\usepackage{epigraph}
\usepackage{multicol}
\usepackage{pdflscape}

% Graphics control.
\usepackage{graphicx}
\usepackage{float}

% Bibliography
\usepackage{natbib}
\bibliographystyle{agufull04}

\usepackage[nogin,noae]{Sweave}
% Extra pretty pretty printing.
\usepackage{tikzCodeBlock}
\usepackage{sweavetolst}
% Macros created for this document. Make sure tikzCodeBlock is loaded first.
% For now.
\input{tikzDeviceMacros}


<<setup,echo=F,results=hide>>=

	if( !file.exists( 'figs' ) ) dir.create( 'figs' )
	require(tikzDevice)

  options(prompt = ' ', continue = ' ')

@


\title{The \pkg{tikzDevice} Package\\
	{\large\url{http://r-forge.r-project.org/projects/tikzdevice}}
}
\author{Charlie Sharpsteen and Cameron Bracken}
\date{Version
\Sexpr{tikzDevice:::getTikzDeviceVersion()}-{\bfseries\color{red}Beta}\qquad November, 2011}

\begin{document}
	
\SweaveOpts{echo=F,prefix.string=figs/fig}


%----------------------------  Cover Page -----------------------------------------------------------

\thispagestyle{empty}

% A more complex title page

% HAH! God bless the pgf manual- I've been trying to solve this for
% ever- \vfill has no effect unless you bracket your contents in empty
% \vboxes.
\vbox{}
\vspace{0.5\textheight}
\begin{tikzpicture}[remember picture,overlay]

	\node[anchor=west,scale=2, inner sep=0pt, outer sep=0pt] (title) at (-1cm,0) 
		{\LARGE\bfseries{\color{red}\TikZ}\thinspace\Huge Device};
	
	\draw[line width=5pt] ([yshift=-5pt]title.base west) -- ([yshift=-5pt]title.base east);	


	\coordinate (titleOut) at ($(title.north east) + (24pt,0pt)$);
	\coordinate (titleIn) at ($(title.base west) - (6pt,24pt)$);
		
	\node[color=black!80,below=24pt of title.base east,anchor=east] (sub)
		{\bfseries\itshape\Large \LaTeX{} Graphics for R};

\end{tikzpicture}
\vfill	
\vbox{}

\begin{tikzpicture}[remember picture,overlay,>=stealth]

	\node (R) at ($(current page.south west) + (18cm,2cm)$)
		{\scalebox{0.85}{\includegraphics[width=0.8\textwidth]{img/Rlogo}}};

	\tikzset{
		bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}},
		decoration={shape backgrounds,
			shape sep={.25cm, between borders},shape scaled,shape=circle}
	}
			
	\fill[decorate,bigger, blue!25] (R) to[out=190,in=240] (titleIn);	
	
\end{tikzpicture}

\begin{tikzpicture}[overlay,remember picture]

	% Low-level PGF voodoo
	% Something is seriously borked with current page.north east,
	% it's not where you would expect it to be :P
	\newdimen\overlayXoff
	\newdimen\overlayYoff
	\pgfextracty{\overlayXoff}{\pgfpointanchor{current page}{north east}}
	\pgfextracty{\overlayYoff}{\pgfpointanchor{current page}{north east}}
	
	\pgfmathparse{\overlayYoff - 4.5in}
	\overlayYoff = \pgfmathresult pt
	
	\pgfmathparse{\overlayXoff - 7in}
	\overlayXoff = \pgfmathresult pt
	
	
	\begin{scope}[x=1pt,y=1pt,yshift=\overlayYoff,xshift=\overlayXoff]

<<tikzTitlePlot,results=hide>>=

	tikz('figs/titlePlot.tex',bareBones=T,width=4,height=4)

	x <- seq(-4.5,4.5,length.out=100)
	y <- dnorm(x)

	xi <- seq(-2,2,length.out=30)
	yi <- dnorm(xi)

	plot(x,y,type='l',col='blue',ylab='$p(x)$',xlab='$x$')
	lines(xi,yi,type='s')
	lines(range(xi),c(0,0))
	lines(xi,yi,type='h')
	title(main="$p(x)=\\frac{1}{\\sqrt{2\\pi}}e^{-\\frac{x^2}{2}}$")
	int <- integrate(dnorm,min(xi),max(xi),subdivisions=length(xi))
	text(2.8,0.3,paste("\\small$\\displaystyle\\int_{",min(xi),"}^{",max(xi),"}p(x)dx\\approx",round(int[['value']],3),'$',sep=''))


	dev.off()
@

		\input{figs/titlePlot.tex}
		
		\coordinate (plotIn) at (2in,0.5in);


	\end{scope}

	\tikzset{
		bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}},
		decoration={shape backgrounds,
			shape sep={.25cm, between borders},shape scaled,shape=dart}
	}

	\fill[decorate,thick,bigger,color=black!25]
		(titleOut) to[out=20,in=260] (plotIn);

\end{tikzpicture}

\newpage

%----------------------------  Table of Contents -----------------------------------------------------------

\pagenumbering{roman}

\maketitle
\tableofcontents

\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Documentation starts here.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pagenumbering{arabic}

% A friendly reminder that this package is currently unstable.
\tikzDocDisclaim{Caveat Utilitor}
{
This is a friendly reminder that the \pkg{tikzDevice} package is currently considered by its designers to be a {\bfseries beta work}. The package will remain in Beta until the 1.0 release to allow the authors to consider design decisions underlying the package.  {\bfseries This means the authors are currently reserving the right to alter the package interface in ways that may break existing code that uses the package.}  Two open issues that may necessitate such a change are:

\vskip\baselineskip

\begin{itemize}

  \item{Handling of characters encoded using UTF8}
  
  \item{Compatibility with multiple \TeX\ dialects such as Con\TeX t or plain \TeX .}

\end{itemize}
  
\vskip\baselineskip

The stability of the package interface is a priority to us but currently we are allowing other concerns to outrank it.  When we commit to maintaining a given package structure, the beta flag will be removed and consistency of interface will become a top priority. \\[1em]

Thanks for giving our package a try!\\
\quad{\itshape --The tikzDevice Team}
}


\section{Introduction}

The \pkg{tikzDevice} package allows for R graphics output in a native \LaTeX{} format. That is, the \code{tikz()} function produces plain-text files that can be interpreted using \TikZ, a package for \LaTeX. These files can be directly included in \LaTeX{} documents by way of the \verb'\input{}' statement. Allowing \LaTeX{} to handle both typesetting and figure composition bestows the resulting document with a clean, unified look as there are no discontinuities in the size and selection of fonts used in the text and those used in the figures.

This document is divided into three parts. The first part describes the functions that the package makes available to the \lang{R} user and provides examples of their capabilities. Besides the \lang{R} environment, use of the \TikZ{} device device requires the user to have a working \LaTeX{} compiler along with an installed version of the \TikZ{} package-- version 2.00 or greater. The second part of this documentation offers suggestions on how to get these tools working properly.

The third part of the documentation is intended for those who are curious as to the details of how this package has been implemented. It attempts to explain how the \TikZ{} package does the things that it does and why it chooses to do them that way. The authors have attempted to write this part of the documentation in a way that is accessible to users as well as developers. This has been done in the hope that this project may serve as a case study in creating an \lang{R} graphics device. This part of the documentation may also help those considering undertaking the transition from casual package-building to full-on hacking of the \lang{R} internals.

\section{Acknowledgements}

This package would not have been possible without the hard work and ingenuity of many individuals. This package straddles the divide between two great open source communities-- the \lang{R} programming language and the \TeX{} typesetting system. It is our hope that this work will make it easier to leverage the strengths of both systems.

First off, we would like to thank the R Core Team for creating such a wonderful, open and flexible programming environment. Compared to other languages we have used, creating packages and extensions for \lang{R} has always been a liberating experience.

This package started as a fork of the Pic\TeX{} device, created by Valerio Aimale. Without access to such a concise, compact example of implementing a \lang{R} graphics device we likely would have abandoned the project in it's infancy. We would also like to thank Paul Murrel for all of his work on the \lang{R} graphics system and especially for his research and documentation concerning the differences between the font systems used by \TeX{} and \lang{R}.

This package also owes it's existence to Friedrich Leisch's work on the \code{Sweave} system and Roger D. Peng's \code{cacheSweave} extension. These two tools got us interested in the concept of Literate Programming and development of this package was driven by our desire to achieve a more seamless union between our reports and our code.

The performance of this package is also enhanced by the database capabilities provided by Roger D. Peng's \code{filehash} package. Without this package, the approach to calculating font metrics taken by the \code{tikzDevice} would be infeasible.

Last, but certainly not least, we would like to thank Till Tantau, Mark Wibrow and the rest of the PGF/\TikZ{} team for creating the \LaTeX{} graphics package that makes the output of this device meaningful. We would also like to express deep appreciation for the excellent documentation that has been created for the \TikZ{} system.

As always, there are many more who have contributed in ways too numerous to list.

Thank you!\\
\vbox{}{\quad\itshape --The tikzDevice Team}

\nocite{murrellTex}
\nocite{rintern2009}
\nocite{tantau2008}
\nocite{peng2006}

\part{Usage and Examples}
\label{part:one}

%----------------------------  Package Loading -----------------------------------------------------------

\section{Loading the Package}

The functions in the \pkg{tikzDevice} package are made accessible in the \lang{R} environment by using either the \code{library()} or \code{require()} functions like so:

\begin{Verbatim}[frame=single]
require(tikzDevice)
\end{Verbatim}

Upon loading, the package will search for a usable \LaTeX{} compiler. Access to \LaTeX{} is essential for the device to produce correct output as the compiler is queried for font metrics several times during device output. For more information on why communication between the device and \LaTeX{} is necessary, see \autoref{part:three}. If the search for a compiler is successful the package startup message should look similar to the following:

\begin{Verbatim}[frame=single]
filehash: Simple key-value database (2.0-1 2008-12-19)
tikzDevice: A Device for R Graphics Output in PGF/TikZ Format (v0.3.5)
Checking for a LaTeX compiler...

pdfTeX 3.1415926-1.40.9-2.2 (Web2C 7.5.7)
kpathsea version 3.5.7
...

A working LaTeX compiler was found in:
	The R environment variable R_LATEXCMD

Global option tikzLatex set to:
	/usr/texbin/latex
\end{Verbatim}

If a working \LaTeX{} compiler cannot be found, the \pkg{tikzDevice} package will fail to load and a warning message will be displayed:

\begin{Verbatim}[frame=single]
An appropriate LaTeX compiler could not be found.
Access to LaTeX is currently required in order for the
TikZ device to produce output.

The following places were tested for a valid LaTeX compiler:

	A pre-existing value of the global option tikzLatex
	The R environment variable R_LATEXCMD
	The R environment variable R_PDFLATEXCMD
	The global option latexcmd
	The PATH using the command latex
	The PATH using the command pdflatex
...

Error : .onLoad failed in 'loadNamespace' for 'tikzDevice'
Error: package/namespace load failed for 'tikzDevice'
\end{Verbatim}

In this case, \pkg{tikzDevice} has done it's very best to locate a working compiler and came up empty.  If you have a working \LaTeX{} compiler, the next section describes how to inform the \pkg{tikzDevice} package of its location.  For suggestions on how to obtain a \LaTeX{} compiler, see \autoref{part:two}.


\subsection{\lang{R} Options That Affect Package Behavior}\label{sec:options}
The \pkg{tikzDevice} package is  influenced by a number of options that may be set locally in your \lang{R} scripts or in the \lang{R} console or globally in a \code{.Rprofile} file.  All of the options can be set by using \code{options(<option> = <value>)}.  These options allow for the use of custom \code{documentclass} declarations, \LaTeX{} packages, and typesetting engines (e.g. XeLaTeX). The defaults , if are any for a given option, are shown below the description.   The global options are:


\begin{description}

% The additional indent added by the description will be picked up by the listings
% package and inserted into the code blocks. It is hard to detect in general when this
% happens- so we'll just temporarily shift the listing margin and shorten the max
% width of tikzCodeBlock node bodies. Since this is all done inside the description
% environment, the changes will disappear when the environment ends.
\lstset{xleftmargin=-\leftmargini}
\newlength\tikzShortenLine
\setlength\tikzShortenLine{\textwidth}
\addtolength\tikzShortenLine{-\leftmargini}
\tikzset{/tikzCode/defaults/code body/.append style={text width=\tikzShortenLine}}

  \item[\code{tikzDefaultEngine}] {
    Specifies which typesetting engine functions in the \pkg{tikzDevice}
    package will prefer. Current possible values are \hologo{pdfTeX} or
    \hologo{XeTeX} which will respectively trigger the use of the
    \hologo{pdfLaTeX} and \hologo{XeLaTeX} compilers.

\begin{tikzCodeBlock}[title={Choosing the \TeX\ engine},listing style=sweavechunk]
options(tikzDefaultEngine = 'pdftex')
# Or..
options(tikzDefaultEngine = 'xetex')
\end{tikzCodeBlock}
  }

  \item[\code{tikzLatex} and \code{tikzXelatex}] {
    Specifies the location of the \LaTeX{} and \hologo{XeLaTeX} compilers to be
    used by \pkg{tikzDevice}. Setting a default for this this option may help
    the package locate a missing compiler:

\begin{tikzCodeBlock}[title={Setting default compilers in \code{.Rprofile}},listing style=sweavechunk]
options(tikzLatex = '/path/to/latex/compiler')
options(tikzXelatex = '/path/to/xelatex/compiler')
\end{tikzCodeBlock}
  }

\item[\code{tikzMetricsDictionary}]{ When using the graphics device provided by \pkg{tikzDevice}, you may notice that \lang{R} appears to ``lag" or ``hang" when commands such as \code{plot()} are executed. This is because the device must query the \LaTeX{} compiler for string widths and font metrics. For a normal plot, this may happen dozens or hundreds of times- hence \lang{R} becomes unresponsive for a while. The good news is that the \code{tikz()} code is designed to cache the results of these computations so they need only be performed once for each string or character. By default, these values are stored in a temporary cache file which is deleted when \lang{R} is shut down. A location for a permanent cache file may be specified:

\begin{tikzCodeBlock}[title={Setting a location in \code{.Rprofile} for a permanent metrics dictionary},listing style=sweavechunk]
options( tikzMetricsDictionary = '/path/to/dictionary/location' )
\end{tikzCodeBlock}
}

\item[\code{tikzDocumentDeclaration}]{A string. The documentclass declaration when \code{standAlone == TRUE} as well as when font metrics are calculated}

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzDocumentDeclaration = "\\documentclass{article}" )
\end{tikzCodeBlock}

\item[\code{tikzFooter}]{A character vector. The footer to be used only when \code{standAlone==TRUE} }

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzFooter = c( "\\end{document}" ) )
\end{tikzCodeBlock} 

  \item[\code{tikzLatexPackages} and \code{tikzXelatexPackages}]{
    Character vectors. These are the packages which are included when using the
    \code{standAlone} option as well as when font metrics are calculated.  If you
    use additional packages that affect fonts, such as mathpazo which provides a
    Palatino-style font, these packages should be added to this list.

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzLatexPackages = c(
  "\\usepackage{tikz}",
  "\\usepackage[active,tightpage]{preview}",
  "\\PreviewEnvironment{pgfpicture}",
  "\\setlength\\PreviewBorder{0pt}")
)
\end{tikzCodeBlock}

\begin{tikzCodeBlock}[title={Adding a package that affects fonts},listing style=sweavechunk]
options( tikzLatexPackages = c(
  getOption( "tikzLatexPackages" ),
  "\\usepackage{mathpazo}"
))
\end{tikzCodeBlock}
  }

\item[\code{tikzMetricPackages} and \code{tikzUnicodeMetricPackages}] {
    Character vectors. These are the extra packages which are additionally
    loaded when doing font metric calculations.  As you see below, the font
    encoding is set to Type 1. This is very important so that character codes
    of \LaTeX{} and \lang{R} match up. The Unicode metric packages are used
    when a \hologo{XeTeX} engine is in use.

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzMetricPackages = c(
  "\\usepackage[utf8]{inputenc}",
  "\\usepackage[T1]{fontenc}",
  "\\usetikzlibrary{calc}")
)
\end{tikzCodeBlock}
  }


\item[\code{tikzSanitizeCharacters}]{A character vector of special latex characters to replace. These values should correspond to the replacement values from the \code{tikzReplacementCharacters} option.}

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzSanitizeCharacters = c('%','$','}','{','^') )
\end{tikzCodeBlock}

\item[\code{tikzReplacementCharacters}]{A character vector of replacements for special latex characters. These values should correspond to the values from the \code{tikzSanitizeCharacters} option.}

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options( tikzReplacementCharacters = c('\\%','\\$','\\','\\','\\^'))
\end{tikzCodeBlock}

  \item[\code{tikzRasterResolution}] {
    When \code{tikz} is requested to add a raster to a graphic, the
    raster is written to a PNG file which is then included into the LaTeX
    code. This option controls the resolution (dpi) at which the PNG files
    are created.

\begin{tikzCodeBlock}[title={Default},listing style=sweavechunk]
options(tikzRasterResolution = 300)
\end{tikzCodeBlock}
  }

  \item[\code{tikzPdftexWarnUTF}] {
    A \code{TRUE/FALSE} value that controls whether warnings are printed if
    Unicode characters are sent to a device using the \hologo{pdfTeX} engine.
  }
\end{description}

For convenience the function \code{setTikzDefaults()} is provided which sets all the global options back to their original values.

The proper placement of a \code{.Rprofile} file is explained in \code{?Startup}. For the details of why calling the \LaTeX{} compiler is necessary, see \autoref{part:three}.

\tikzDocDisclaim{A Word of Caution About Setting Options.}
{A lot of power is given to you through these global options, and with great power comes great responsibility.  For example, if you do not include the \TikZ{} package in the \code{tikzLatexPackages} option then all of the string metric calculations will fail. Or if you use a different font when compiling than you used for calculating metrics, strings may be placed incorrectly.  There are innumerable ways for packages to clash in \LaTeX{} so be aware. 
}


\label{cache:user}

%----------------------------  tikz() function documentation -------------------------------------------------

\section{The \code{tikz()} Function}

\subsection{Description}
The \code{tikz()} function provides most of the functionality of the \pkg{tikzDevice} package. This function is responsible for creating new \lang{R} graphics devices that translate the output of graphics functions to the \TikZ{} format. The device supports many levels of output that range from stand-alone \LaTeX{} documents that may be compiled directly to code chunks that must be incorporated into existing \LaTeX{} documents using the \verb`\include{}` function.

\subsection{Usage}

The \code{tikz()} function opens a new graphics device and may be called with the following arguments:

\begin{Verbatim}[frame=single]
tikz(file = "Rplots.tex", width = 7, height = 7,
  bg="transparent", fg="black", pointsize = 10, standAlone = FALSE,
  bareBones = FALSE, console = FALSE, sanitize = FALSE,
  engine = getOption("tikzDefaultEngine'),
  documentDeclaration = getOption("tikzDocumentDeclaration"),
  packages = getOption("tikzLatexPackages"),
  footer = getOption("tikzFooter"))
\end{Verbatim}

\begin{description}
\item[\code{file}]{ A character string indicating the desired path to the output file. It is recommended, but not required, that the filename end in \code{.tex}.}
\item[\code{width}]{ The width of the output figure, in {\bfseries inches}. }
\item[\code{height}]{ The height of the output figure, in {\bfseries inches}. }
\item[\code{bg}]{ The starting background color for the plot. }
\item[\code{fg}]{ The starting foreground color for the plot. }
\item[\code{pointsize}]{ Base pointsize used in the LaTeX document.  This option is only referenced if a valid pointsize cannot be extracted from the value of \code{getOption("tikzDocumentDeclaration")}.  See \autoref{subsec:fontCalc} for more details.}
\item[\code{standAlone}]{ A logical value indicating whether the resulting file should be suitable for direct processing by \LaTeX .}
\item[\code{bareBones}]{ A logical value indicating whether the resulting \TikZ{} code produced without being placed within a \LaTeX{} \code{tikzpicture} environment.}
\item[\code{console}]{Should the output of \code{tikz} be directed to the \lang{R} console (default FALSE). This is useful for dumping tikz output directly into a \LaTeX{} document via sink. If \code{TRUE}, the file argument is ignored. Setting \code{file=''} is equivalent to setting \code{console=TRUE}.}
\item[\code{sanitize}]{Should special latex characters be replaced (Default \code{FALSE}). See the section ``Options That Affect Package Behavior'' for which characters are replaced.}
\item[\code{engine}] {
  A string specifying which TeX engine to use. Possible values are 'pdftex' and
  'xetex'.
}
\item[\code{documentDeclaration}]{See Section \ref{sec:options}, ``Options That Affect Package Behavior.''}
\item[\code{packages}]{See Section \ref{sec:options}, ``Options That Affect Package Behavior.''}
\item[\code{footer}]{See Section \ref{sec:options}, ``Options That Affect Package Behavior.''}
\end{description}

The first five options should be familiar to anyone who has used the default
graphics devices shipped with \lang{R}. The options \code{file}, \code{width},
\code{height}, \code{bg} and \code{fg} represent the standard graphics
parameters currently implemented by \pkg{tikzDevice}. The last two options,
\code{standAlone} and \code{bareBones}, are specific to the \code{tikz()}
graphics device and affect the structure the output file. Using these options
\code{tikz()} supports three modes of output:

\begin{itemize}

	\item{Graphics production as complete \LaTeX{} files suitable for compilation.}
	
	\item{Graphics production as complete figures suitable for inclusion in \LaTeX{} files.}
	
	\item{Graphics production as raw figure code suitable for inclusion in an enclosing \code{tikzpicture} environment in a \LaTeX{} file.}

\end{itemize}

\subsection{Font Size Calculations}
\label{subsec:fontCalc}
The overarching goal of the `tikzDevice' is to provide seamless integration
between text in R graphics and the text of LaTeX documents that contain those
graphics.  In order to achieve this integration the device must translate font
sizes specified in R to corresponding font sizes in LaTeX.  The issue is that
font sizes in LaTeX are controlled by a ``base font size'' that is specified at
the beginning of the document- typically 10pt.  There is no easy way in LaTeX
to change the font size to a new numerical value, such as 16pt for a plot
title.  Fortunately, the TikZ graphics system allows text to be resized using a
scaling factor.  The \code{tikzDevice} calculates a scaling factor used to
approximate other font sizes using the following three inputs:

\begin{itemize}

  \item{The ``base font size'' specified when the graphics device is
          created.}

  \item{The ``character expansion factor'' parameter, specified using the `cex'
    argument to functions such as described in the documentation of the
    \lang{R} function \code{par()}.}
  
  \item{The ``font size'' parameter, specified using the `ps' argument to
    functions such as \code{par()} or the `fontsize' argument to functions such
    as \code{gpar()}.}

\end{itemize}

The calculation used is:

\[
\mbox{Scaling Factor} = \mbox{cex} \cdot \frac{\mbox{ps}}{\mbox{base font size}}
\]

The tricky bit is the specification of the ``base font size''.  By default the tikzDevice will attempt to determine this parameter by scanning the value of \code{options( "tikzDocumentDeclaration" )} using the regular expression \code{\textbackslash d+[pt]}.  With the default header:


\quad\code{\textbackslash documentclass[10pt]{article}}


This regular expression will return 10 as the base pointsize to be used by the device.  If the regular expression fails to produce a match, the value of the \code{pointsize} argument to the \code{tikz()} function will be used.


\subsection{UTF-8 Output}

Version 0.6.0 introduced support for (multibyte) Unicode characters in the text
of graphics.  There are a few important implications/limitations of this
feature:

\begin{description}

\item[System Requirements:]
  A working version of \hologo{XeLaTeX} along with the packages \code{fontspec}
  and \code{xunicode} are required for direct processing of Unicode input.  If
  \code{tikzDevice} cannot find \hologo{XeLaTeX} then Unicode support cannot be
  guaranteed.

\item[Encoding:] \code{tikzDevice} will try its best to convert characters from
  other encodings but do not count on it converting things correctly, best to
  do the conversion yourself beforehand to avoid unexpected output.

\item[Fonts:] Having a Unicode character actually show up in your \LaTeX{}
  document relies on the font you use having the glyph available. We leave it
  up to the user to know for themselves what is available.  Otherwise you will
  likely just get no output in place of where the character should be.

\item[plotmath:] There is specifically no support for input of plotmath
  characters as unicode since the user can simply input \LaTeX{} math directly.
  We strongly encourage the use of \LaTeX{} math over plotmath for style and
  consistency's sake.  A consequence of this is that most of the \lang{R}
  examples and demos of plotmath won't work without significant manipulation
  (your milage may vary but you may get anything from errors to warnings to
  documents that mysteriously won't compile).  That is not to say that the
  output could not be duplicated with \code{tikzDevice} but the examples will
  not work out of the box.

\item[Compiling:]
  A graphic that contains UTF-8 characters should be compiled with
  \hologo{XeLaTeX} (or possibly \hologo{LuaLaTeX}) with the \code{xunicode} and
  \code{fontspec} packages enabled.

\item[ASCII only:]
  Everything should be exactly the same as previous versions if only ASCII
  (single byte) characters are used (i.e. character codes less than 132).

\end{description}



\subsection{Examples}

% We will shift into the figs directory here so that we don't have
% to have separate Sweave code chunks with the 'figs/' path in
% them.
<<pathStepIn,results=hide>>=
	setwd('figs')
@
\subsubsection{Default Mode}

The most common use of the \code{tikz()} function is to produce a plot that will be included in another \LaTeX{} document, such as a report. Running the following example in \lang{R} will produce a very simple graphic using the \code{plot()} function.

<<simpleEx,echo=T,results=hide>>=
require(tikzDevice)
tikz('simpleEx.tex',width=3.5,height=3.5)
plot(1,main='Hello World!')
dev.off()
@

A simple \LaTeX{} document is then required to display the output of the basic \code{tikz()} command. This document must include the \TikZ{} as one of the packages that it loads. The \TikZ{} package provides several optional libraries that provide additional functionality, however none of these libraries are currently required to use the output of \code{tikz()}. Inside the \LaTeX{} document, the contents of the file \code{simpleEx.tex} are imported using the \verb`\include{}` command.

\begin{figure}[H]
	\centering

	\begin{minipage}{0.5\textwidth}

\begin{tikzCodeBlock}[title={Example \LaTeX{} Document},listing style=latexsource,code body/.append style={codebody color=white},no break=true]
\documentclass{article}

% All LaTeX documents including 
% tikz() output must use this 
% package!
\usepackage{tikz}

\begin{document}
  \begin{figure}[!h]
    \centering
   
    % The output from tikz()
    % is imported here.
    \input{simpleEx.tex}
      
    \caption{Simple Example}
  \end{figure}
\end{document}
\end{tikzCodeBlock}

	\end{minipage}
	\hfill
	\begin{minipage}{0.45\textwidth}
		\input{figs/simpleEx.tex}
	\end{minipage}
	\caption{Example of simple \code{tikz()} usage.}
\end{figure}

One of the most exciting aspects of the \code{tikz()} function is that it allows the inclusion of arbitrary \LaTeX{} code in plotting commands. An important issue to note is that many \LaTeX{} commands pare prefixed by the backaslash, \textbackslash, character. This character has a special meaning as an escape charcter in many computing applications, including \lang{R}. Therefore, it is necessary to place two backslashes, \textbackslash\textbackslash, in the input to \lang{R} commands in order to cause one to appear in the output.  The next example demonstrates how to use \LaTeX{} commands in plot annotation.

% Disable chunk page breaking so the following code doesn't get mangled.
\makeatletter
\tikzCode@breakPagesfalse
\makeatother

\begin{figure}[H]
	\centering
	\begin{minipage}{0.5\textwidth}
<<latexEx,echo=T,results=hide,keep.source=T>>=
require(tikzDevice)
tikz('latexEx.tex',
  width=3.5,height=3.5)

x <- rnorm(10)
y <- x + rnorm(5,sd=0.25)

model <- lm(y ~ x)
rsq <- summary( model )$r.squared
rsq <- signif(rsq,4)

plot(x,y,main='Hello \\LaTeX!')
abline(model,col='red')

mtext(paste("Linear model: $R^{2}=",
  rsq,"$" ),line=0.5)
  
legend('bottomright', legend = 
  paste("$y = ",
    round(coef(model)[2],3), 'x +',
    round(coef(model)[1],3), '$',
    sep=''), bty= 'n')

dev.off()
@
	\end{minipage}
	\hfill
	\begin{minipage}{0.45\textwidth}
		\input{figs/latexEx.tex}
	\end{minipage}
	\caption{A more complicated example of \code{tikz()} usage incorporating natively rendered \LaTeX{} commands.}
\end{figure}

% Reinstate tikzCodeBlock defaults.
\makeatletter
\tikzCode@breakPagestrue
\makeatother

\subsubsection{\code{bareBones} Mode}

\code{barBones} output is designed to facilitate inclusion of code generated by
\code{tikz()} into a larger \TikZ\ graphic. Normally \code{tikz()} packages the
commands it produces as a self-contained figure. This is done by placing the
\verb`\begin{tikzpicture}` and \verb`\end{tikzpicture}` commands at the
beginning and end of the output file. When \code{bareBones} is invoked, the
\code{tikzpicture} environment is omitted which allows the output to be
embedded inside another \code{tikzpicture} of the users own construction.

<<bareBonesExample,echo=T,results=hide,keep.source=T>>=
require(tikzDevice)
require(maps)

tikz('westCoast.tex', bareBones=TRUE)
map('state', regions=c('california', 'oregon', 'washington'),
    lwd=4, col='grey40')

eurekaLon <- grconvertX(-124.161, to='device')
eurekaLat <- grconvertY(40.786, to='device')

longviewLon <- grconvertX(-122.962, to='device')
longviewLat <- grconvertY(46.148, to='device')

coosLon <- grconvertX(-124.237, to='device')
coosLat <- grconvertY(43.378, to='device')

sfLon <- grconvertX(-122.419, to='device')
sfLat <- grconvertY(37.775, to='device')

tikzAnnotate(paste('\\coordinate (humBay) at (',
  eurekaLon, ',', eurekaLat, ');', sep='') )

tikzAnnotate(paste('\\coordinate (longView) at (',
  longviewLon, ',', longviewLat, ');', sep='') )

tikzAnnotate(paste('\\coordinate (coosBay) at (',
  coosLon, ',', coosLat, ');', sep='') )

tikzAnnotate(paste('\\coordinate (sfBay) at (',
  sfLon, ',', sfLat, ');', sep='') )

dev.off()
@

The \verb`\include{}` command may now be used to import the device output into
another \code{tikzpicture}. The included code must be wrapped in a \code{scope}
environment that contains the options \code{x=1pt} and \code{y=1pt}. This
informs \TikZ{} of the units being used in the coordinates of the plot output.
The options \code{xshift} and \code{yshift} may also be applied to the
\code{scope} in order to position the plot. The following code demonstrates how
to embed \code{bareBones} output in a \code{tikzpicture}:

\begin{tikzCodeBlock}[title={Example of a \TikZ{} environment including \code{bareBones} output},
  code body/.append style={codebody color=white},
  listing style=latexsource]
\begin{tikzpicture}

  % Include bareBones output inside a scope with x and y units set to 1pt
  \begin{scope}[x=1pt,y=1pt]
    \input{figs/westCoast}
  \end{scope}

  % Label ports using coordinates placed into the barBones output by the
  % tikzAnnotate function.
  \foreach \name/\port in {
    Longview/longView,
    Coos Bay/coosBay,
    Humboldt Bay/humBay,
    Oakland/sfBay%
  } {
    \node[circle, draw, ultra thick, fill=green!60!brown!40,
      outer sep=6pt,minimum size=12pt,
      pin={[
        draw, ultra thick,
        rounded corners,
        pin edge={black, ultra thick, <-, >=stealth}
      ] 180 : \name}] at (\port) {};
  }

\end{tikzpicture}
\end{tikzCodeBlock}



\begin{figure}[H]

	\centering

	\begin{tikzpicture}

    \begin{scope}[x=1pt,y=1pt]
      \input{figs/westCoast}
    \end{scope}

    \foreach \name/\port in {
      Longview/longView,
      Coos Bay/coosBay,
      Humboldt Bay/humBay,
      Oakland/sfBay%
    } {
      \node[circle, draw, ultra thick, fill=green!60!brown!40,
        outer sep=6pt,minimum size=12pt,
        pin={[
          draw, ultra thick,
          rounded corners,
          pin edge={black, ultra thick, <-, >=stealth}
        ] 180 : \name}] at (\port) {};
    }

	\end{tikzpicture}

	\caption{A \TikZ{} drawing with embedded output from \code{tikz(bareBones=TRUE)}.}
\end{figure}

\subsubsection{\code{standAlone} Mode}

When the \code{standAlone} option is passed to \code{tikz()}, the resulting \code{.tex} file will be a complete \LaTeX{} document designed to be compiled on its own.  This means that in addition to \verb`\begin{tikzpicture}` and \verb`\end{tikzpicture}` the file will also contain \verb`\begin{document}`, \verb`\end{document}` and a \LaTeX{} preamble.  The \code{preview} package is also used in files produced by \code{standAlone} and is used to crop the pages in the resulting document to the bounding boxes of the figures that it contains.  Stand-alone output may be produced in the following manner:

<<standAloneExample,echo=T,results=hide,keep.source=T>>=
require(tikzDevice)
tikz('standAloneExample.tex',standAlone=T)
plot(sin,-pi,2*pi,main="A Stand Alone TikZ Plot")
dev.off()
@


<<standAloneCompileExample, results=hide, eval=F>>=

	require(tools)
	
	catch <- system(paste(Sys.which('pdflatex'),
		'-interaction=batchmode -output-directory figs/ figs/standAloneExample.tex'),
		ignore.stderr=T)
	
	# If compiling the example failed, we don't want to include a broken link.	
	if( catch == 0 ){
		pdfLink <- "The file \\\\code{standAloneExample.tex} may then be compiled to produce
			\\\\href{./figs/standAloneExample.pdf}{standAloneExample.pdf}. "
	}else{
		pdfLink <- ""
	}
    #%\Sexpr{print(pdfLink)}
@

Note that files produced using the \code{standAlone} option should not be included in \LaTeX{} documents using the \verb`\input{}` command! Use \verb`\includegraphics{}` or load the \code{pdfpages} package and use \verb`\includepdf{}`.

\subsubsection{\code{console} output Mode}

Version 0.5.0 of \pkg{tikzDevice} introduced the \code{console} option.  Instead of sending its output to a file \code{tikz} will send it output to \code{stdout}. This kind of output can be redirected to a file with \code{sink()} or spit out directly into a \TeX{} document from a \lang{Sweave} file so that the \TeX{} file is self contained.  

\begin{tikzCodeBlock}[title={consoleExample.Rnw},listing style=sweavechunk]
 \documentclass{article}
 \usepackage{tikz}
 \usepackage[nogin]{Sweave}
 \begin{document}
 \begin{figure}[ht]
 \centering
 <<inline,echo=F,results=tex>>=

 require(tikzDevice)
 tikz(console=T,width=5,height=5)
   x <- rnorm(100)
   plot(x)
 dummy <- dev.off()

 @
 \caption{caption}
 \label{fig:inline}
 \end{figure}
 \end{document}
\end{tikzCodeBlock}

\subsubsection{Getting around special \LaTeX{} characters}

\subsubsection{Using the Global Options: An Xe\LaTeX{} example}

It is also possible to use other typesetting engines like Xe\LaTeX{} by using the global options provided by \pkg{tikzDevice}.  The following example was inspired by Dario Taraborelli and his article \href{http://nitens.org/taraborelli/latex}{The Beauty of LaTeX}.

\begin{tikzCodeBlock}[title={Xe\LaTeX{} Example},listing style=sweavechunk]
#Set options for using XeLaTeX
options(tikzLatex = 'xelatex')
options(tikzDocumentDeclaration = '\\documentclass{article}')
	# The preview package must be loaded first with the xetex driver option
options( tikzLatexPackages = c(
	"\\usepackage[active,tightpage,xetex]{preview}"
	,"\\PreviewEnvironment{pgfpicture}"
	,"\\setlength\\PreviewBorder{0pt}"
	,"\\usepackage{fontspec}"
	,"\\usepackage[colorlinks, breaklinks, pdftitle={The Beauty of LaTeX}," 	
	,"pdfauthor={Taraborelli, Dario}]{hyperref}"
	,"\\usepackage{tikz}"
	,"\\usepackage{color}"
	,"\\definecolor{Gray}{rgb}{.7,.7,.7}"
	,"\\definecolor{lightblue}{rgb}{.2,.5,1}"
	,"\\definecolor{myred}{rgb}{1,0,0}"
	,"\\newcommand{\\red}[1]{\\color{myred} #1}"
	,"\\newcommand{\\reda}[1]{\\color{myred}\\fontspec[Variant=2]{Zapfino}#1}"
	,"\\newcommand{\\redb}[1]{\\color{myred}\\fontspec[Variant=3]{Zapfino}#1}"
	,"\\newcommand{\\redc}[1]{\\color{myred}\\fontspec[Variant=4]{Zapfino}#1}"
	,"\\newcommand{\\redd}[1]{\\color{myred}\\fontspec[Variant=5]{Zapfino}#1}"
	,"\\newcommand{\\rede}[1]{\\color{myred}\\fontspec[Variant=6]{Zapfino}#1}"
	,"\\newcommand{\\redf}[1]{\\color{myred}\\fontspec[Variant=7]{Zapfino}#1}"
	,"\\newcommand{\\redg}[1]{\\color{myred}\\fontspec[Variant=8]{Zapfino}#1}"
	,"\\newcommand{\\lbl}[1]{\\color{lightblue} #1}"
	,"\\newcommand{\\lbla}[1]{\\color{lightblue}\\fontspec[Variant=2]{Zapfino}#1}"
	,"\\newcommand{\\lblb}[1]{\\color{lightblue}\\fontspec[Variant=3]{Zapfino}#1}"
	,"\\newcommand{\\lblc}[1]{\\color{lightblue}\\fontspec[Variant=4]{Zapfino}#1}"
	,"\\newcommand{\\lbld}[1]{\\color{lightblue}\\fontspec[Variant=5]{Zapfino}#1}"
	,"\\newcommand{\\lble}[1]{\\color{lightblue}\\fontspec[Variant=6]{Zapfino}#1}"
	,"\\newcommand{\\lblf}[1]{\\color{lightblue}\\fontspec[Variant=7]{Zapfino}#1}"
	,"\\newcommand{\\lblg}[1]{\\color{lightblue}\\fontspec[Variant=8]{Zapfino}#1}"
	,"\\newcommand{\\old}[1]{"
	,"\\fontspec[Ligatures={Common, Rare},Variant=1,%
Swashes={LineInitial, LineFinal}]{Zapfino}"
	,"\\fontsize{25pt}{30pt}\\selectfont #1}%"
	,"\\newcommand{\\smallprint}[1]{\\fontspec{Hoefler Text}\\fontsize{10pt}{13pt}"%
	,"\\color{Gray}\\selectfont #1}%\n"
	))

#Set the content using custom defined commands
label <- c(  
  "\\noindent{\\red d}roo{\\lbl g}"
  ,"\\noindent{\\reda d}roo{\\lbla g}"
  ,"\\noindent{\\redb d}roo{\\lblb g}"
  ,"\\noindent{\\redf d}roo{\\lblf g}\\\\[.3cm]"
  ,"\\noindent{\\redc d}roo{\\lblc g}"
  ,"\\noindent{\\redd d}roo{\\lbld g}"
  ,"\\noindent{\\rede d}roo{\\lble g}"
  ,"\\noindent{\\redg d}roo{\\lblg g}\\\\[.2cm]")

#Set the titles using custom defined commands, and hyperlinks
title <- c(
    "\\smallprint{D. Taraborelli (2008), 
      \\href{http://nitens.org/taraborelli/latex}%","{The Beauty of \\LaTeX}}"
    ,"\\smallprint{\\\\\\emph{Some rights reserved}.% 
    ,"\\href{http://creativecommons.org/licenses/by-sa/3.0/}
      {\\textsc{cc-by-sa}}}"
	)
	
#Draw the graphic
lim <- 0:(length(label)+1)
tikz('xelatexEx.tex',standAlone=T,width=5,height=5)
plot(lim,lim,cex=0,pch='.',xlab = 'Xe\\LaTeX{} Test',
    ylab='', main = title[1], sub = title[2])
for(i in 1:length(label))
    text(i,i,label[i])
dev.off()
\end{tikzCodeBlock}

Compiling the resulting file \code{xelatexEx.tex} like so:

\begin{tikzCodeBlock}[title={Compiling with Xe\LaTeX{}},listing style=bashsource]
xelatex xelatexEx.tex
\end{tikzCodeBlock}

will produce the output in \autoref{fig:xelatex}!  Please note some of the fonts used in the example may not be available on your system. 

\begin{figure}[!h]
\centering
\includegraphics{img/testXeLaTeX.pdf}
\caption{Result of Xe\LaTeX{} example}\label{fig:xelatex}
\end{figure}

\newpage
\subsubsection{Annotating Graphics with \TikZ{} Commands}

The function \code{tikzAnnotate} provides the ability to annotate you graphics with \TikZ{} commands.  There are a lot of exciting possibilities with this feature; It basically opens up the door for you to draw anything on your plot that can be drawn with \TikZ{}. Check out the results in \autoref{fig:annotation}.

<<annotation,echo=T,results=hide,keep.source=T>>=
require(tikzDevice)

# Load some additional TikZ libraries
tikz("annotation.tex",width=4,height=4,
  packages = c(getOption('tikzLatexPackages'),
    "\\usetikzlibrary{decorations.pathreplacing}",
    "\\usetikzlibrary{positioning}",
    "\\usetikzlibrary{shapes.arrows,shapes.symbols}")
)

p <- rgamma (300 ,1)
outliers <- which( p > quantile(p,.75)+1.5*IQR(p) )
boxplot(p)

# Add named coordinates that other TikZ commands can hook onto
tikzCoord(1, min(p[outliers]), 'min outlier')
tikzCoord(1, max(p[outliers]), 'max outlier')

# Use tikzAnnotate to insert arbitrary code, such as drawing a
# fancy path between min outlier and max outlier.
tikzAnnotate(c("\\draw[very thick,red,",
  # Turn the path into a brace.
  'decorate,decoration={brace,amplitude=12pt},',
  # Shift it 1em to the left of the coordinates
  'transform canvas={xshift=-1em}]',
  '(min outlier) --',
  # Add a node with some text in the middle of the path
  'node[single arrow,anchor=tip,fill=white,draw=green,',
  'left=14pt,text width=0.70in,align=center]',
  '{Holy Outliers Batman!}', '(max outlier);'))

# tikzNode can be used to place nodes with customized options and content
tikzNode(
  opts='starburst,fill=green,draw=blue,very thick,right=of max outlier',
  content='Wow!'
)

dev.off()
@

\begin{figure}[!h]
\centering
\input{figs/annotation.tex}
\caption{An example using \TikZ{} annotation.}\label{fig:annotation}
\end{figure}

\begin{landscape}

\subsubsection{\code{tikz()} vs. \code{pdf()} for \code{plotmath} symbols and Unicode characters}

This is a side-by-side example showing how \code{tikz(..., engine = 'xetex')} handles UTF-8
characters and plotmath symbols compared to the standard R \code{pdf()} device.

\begin{figure}[!h]
\centering
  \begin{minipage}{4.25in}
    \includegraphics[width=4.25in]{img/plotmathDefault.pdf}
    \caption{\code{example(text)} using the standard \code{pdf()} device.}\label{fig:plotmathDefault}
  \end{minipage}
  \vspace{1em}
  \begin{minipage}{4.25in}
    \includegraphics[width=4.25in]{img/plotmathTikz.pdf}
    \caption{\code{example(text)} using \code{tikz(..., engine = 'xetex')}.}\label{fig:plotmathTikz}
  \end{minipage}
\end{figure}

\end{landscape}

% Return to the normal working directory
<<pathStepOut,results=hide>>=
	setwd('../')
@

%----------------------------  text metrics function documentation ---------------------------------------

\section{The \code{getLatexCharMetrics()} and \code{getLatexStrWidth()} Functions}

\subsection{Description}

These two functions may be used to retrieve font metrics through the interface provided by the \pkg{tikzDevice} package. Cached values of the metrics are returned if they have been calculated by the \pkg{tikzDevice} before. If no cached values exist, the \LaTeX{} compiler will be invoked to generate them.

\subsection{Usage}

The font metric functions are called as follows:

\begin{Verbatim}[frame=single]
getLatexStrWidth( texString, cex = 1, face= 1)

getLatexCharMetrics( charCode, cex = 1, face = 1 )
\end{Verbatim}

\begin{description}
\item[\code{texString}]{ A string for which to compute the width. \LaTeX{} commands may be used in the string, however all backslashes will need to be doubled.}
\item[\code{charCode}]{ An integer between 32 and 126 which indicates a printable character in the ASCII symbol table using the T1 font encoding. }
\item[\code{cex}]{ The character expansion factor to be used when determining metrics. }
\item[\code{face}]{ An integer specifying the \lang{R} font face to use during metric calculations. The accepted values are as follows: 
	\begin{description}
		\item[1:]{Text should be set in normal font face.}
		\item[2:]{Text should be set in {\bfseries bold font face}.}
		\item[3:]{Text should be set in {\itshape italic font face}.}
		\item[4:]{Text should be set in {\bfseries\itshape bold italic font face}.}
		\item[5:]{Text should be interpreted as \code{plotmath} symbol characters. Requests for font face 5 are currently ignored.}
	\end{description}
	}
\end{description}

\subsection{Examples}

The \code{getLatexStrWidth()} function may be used to calculate the width of strings containing fairly arbitrary \LaTeX{} commands. For example, consider the following calculations:


<<strWidthDemo,echo=T>>=
getLatexStrWidth( "The symbol: alpha" )
getLatexStrWidth( "The symbol: $\\alpha$" )
@

For the first calculation, the word ``alpha" was interpreted as just a word and the widths of the characters `a', `l', `p', `h' and `a' were included in the string width. For the second string, \verb`\alpha` was interpreted as a mathematical symbol and only the width of the symbol `$\alpha$' was included in the string width.

The \code{getLatexCharWidth()} function must be passed an integer corresponding to an ASCII character code and returns three values:

	\begin{itemize}
		
		\item{The \code{ascent} of the character- the distance between the baseline and the highest point of the character's glyph.}
		
		\item{The \code{descent} of the character- the distance between the baseline and the lowest point of the character's glyph.}
		
		\item{The width of the character.}

	\end{itemize}
	
The character `y' has an \code{ASCII} symbol code of 121 and possesses a tail that descends below the text line. Therefore a non-zero value will be returned for the descent of `y'. The character `x', \code{ASCII} code 120, has no descenders, so its descent will be returned as zero.

<<charMetricDemo,echo=T,keep.source=T>>=
# Get metrics for 'y'
getLatexCharMetrics(121)

# Get metrics for 'x' - the second value is the descent
# and should be zero or very close to zero.
getLatexCharMetrics(120)
@

Note that characters, along with numbers outside the range of [32-126], may not be passed to the \nolinebreak\code{getLatexCharMetrics()}  function. If for some reason a floating point number is passed, it will be floored through conversion by \code{as.integer()}.

<<charMetricErrors,echo=T,keep.source=T>>=
getLatexCharMetrics('y')
getLatexCharMetrics(20)

# Will return metrics for 'y'
getLatexCharMetrics(121.99)
@


\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\part{Installation Guide}
\label{part:two}

This section is intended to offer pointers on how to obtain a \LaTeX{} distribution if there is not one already installed on your system. The distributions detailed in this section are favorites of the \pkg{tikzDevice} developers as they integrated package managers which greatly simplify the process of installing additional \LaTeX{} packages. Currently this section is not, and may never be, a troubleshooting guide for \LaTeX{} installation. For those unfortunate situations we refer the user to the documentation of each distribution.

\section{Obtaining a \LaTeX{} Distribution}

A \LaTeX{} distribution provides the packages and support programs required by the \pkg{tikzDevice} and the documents that use its output. In addition a \LaTeX{} compiler, a few extension packaged are required. \autoref{tikz:required} describes how to obtain and install these packages.

\subsection{Windows}

Windows users will probably prefer the MiKTeX distribution available at \url{http://www.miktex.org}. An amazing feature of the MiKTeX distribution is that it contains a package manager that will attempt to install missing packages on-the-fly. Normally when \LaTeX{} is compiling a document that tries to load a missing package it will wipe out with a warning message. When the MiKTeX compilers are used compilation will be suspended while the new package is downloaded.

% Perhaps a mention of the new portable MiKTeX distribution that can be run off
% of a thumbdrive? I haven't used it yet so I don't feel qualified to discuss it at this
% time.


\subsection{UNIX/Linux}

For users running a Linux or UNIX operating system, we recommend the TeX Live distribution which is available at \url{http://www.tug.org/texlive/acquire.html}. TeX Live is maintained by the TeX Users Group and a new version is released every year. Note that the version of TeX Live provided by many Linux package management systems is the 2007 version. We recommend using TeX Live 2008 or higher as the \code{tlmgr} package manager was introduced in the 2008 distribution. Using \code{tlmgr} greatly simplifies the adding and removing packages from the distribution. The website offers an installation package, called \code{install-tl.tar.gz} or something similar, that contains a shell script that can be used to install an up-to-date version of the TeX Live distribution.

\subsection{Mac OS X}

For users running Apple's OS X, we recommend the Mac TeX package available at \url{http://www.tug.org/mactex/}. Mac TeX is basically TeX Live packaged inside a convenient OS X installer along with a few add-on packages. One striking difference between the Mac TeX and TeX Live installers is that the installer for Mac TeX includes the whole TeX Live distribution in the initial download- for TeX Live 2008 this amounts to approximately 1.2 GB. This is quite a large download that contains several packages that the average or even advanced user will never ever use. To conserve time and space we recommend installing from the basic installer at \url{http://www.tug.org/mactex/morepackages.html} and using the \code{tlmgr} utility to add desired add-on packages.

Adam R. Maxwell has created a very nice graphical interface to \code{tlmgr} for OS X called the TeX Live Utility. It may be obtained from \url{http://code.google.com/p/mactlmgr/} and we highly recommend it.


\section{Installing \TikZ{} and Other Packages}
\label{tikz:required}

Unsurprisingly, \pkg{tikzDevice} requires the \TikZ{} package to be installed and available in order to function properly. \TikZ{} is an abstraction of a lower-level graphics language called \lang{PGF} and both are distributed as the the \code{pgf} package. 


\subsection{Using a \LaTeX{} Package Manager}

The easiest way to install \LaTeX{} packages is by using a distribution that includes a package manager such as MiKTeX or TeX Live/Mac TeX. For Windows users, the MiKTeX package manager usually handles package installation automagically during compilation of a document that is requesting a missing package. The MiKTeX package manager, \code{mpm}, can also be run manually from the command prompt:

\begin{tikzCodeBlock}[title={Using \code{mpm} to install packages},listing style=bashsource,code body/.append style={codebody color=white}]
mpm --install packagename
\end{tikzCodeBlock}

For versions of TeX Live and Mac TeX dated 2008 or newer, the \code{tlmgr} package manager is used in an almost identical manner:

\begin{tikzCodeBlock}[title={Using \code{tlmgr} to install packages},listing style=bashsource,code body/.append style={codebody color=white}]
tlmgr install packagename
\end{tikzCodeBlock}

\subsection{Manual Installation}

Sometimes an automated package manager cannot be used. Common reasons may be that one is not available, as is the case with the TeX Live 2007 distribution, or that when running the package manager you do not have write access to the location where \LaTeX{} packages are stored, as is the case with accounts on shared computers. If this is the case, a manual install may be the best option for making a \LaTeX{} package available.

Generally, the best place to find \LaTeX{} packages is the Comprehensive TeX Archive Network, or \lang{CTAN} located at \url{http://www.ctan.org}. In the case of the PGF/\TikZ{} package, the project homepage at \url{http://www.sourceforge.net/projects/pgf} is also a good place to obtain the package- especially if you would like to play with the bleeding-edge development version.

Generally speaking, all \LaTeX{} packages are stored in a specially directory called a \code{texmf} folder. Most \TeX{} distributions allow for each user to have their own personal  \code{texmf} folder somewhere in their home path. The most usual locations, and here {\bfseries\itshape usual} is and unfortunately loose term, are as follows:

\begin{tikzCodeBlock}[title={For UNIX/Linux},listing style=bashsource,code body/.append style={codebody color=white}]
~/texmf
\end{tikzCodeBlock}

\begin{tikzCodeBlock}[title={For Mac OS X},listing style=bashsource,code body/.append style={codebody color=white}]
~/Library/texmf
\end{tikzCodeBlock}

\begin{tikzCodeBlock}[title={For Windows, using MiKTeX},listing style=bashsource,code body/.append style={codebody color=white}]
# None predefined. However the following command will open
# the MiKTeX options panel and a new texmf folder may be assigned
# under the "Roots" tab.
mo
\end{tikzCodeBlock}


The location of files and subfolders in the \code{texmf} directory should follow a standard pattern called the \TeX{} Directory Structure or TDS which is documented here: \url{http://tug.org/tds/tds.pdf}. Fortunately, most packages available on \lang{CTAN} are archived in such a way that they will unpack into a TDS-complient configuration. TDS-complient archives usually have the phrase \code{tds} somewhere in their filename and may be installed from a UNIX shell\footnote{Sorry Windows users, we enjoy using command prompt about as much as a poke in the eye with a sharp stick. Hence we don't use it enough to offer advice. May we suggest \href{http://www.cygwin.com}{Cygwin}?} like so:

\begin{tikzCodeBlock}[title={Installing \LaTeX{} package archives},listing style=bashsource,code body/.append style={codebody color=white}]
# For zip files.
unzip package.tds.zip -d /path/to/texmf

# For tarballs.
tar -xzf -C /path/to/texmf package.tar.gz
\end{tikzCodeBlock}

For packages that aren't provided in TDS-complient form look for installation notes- usually provided in the form of an \code{INSTALL} file. If all else fails \LaTeX{} packages can usually be installed by copying the files ending in \code{.sty} to \code{texmf/tex/latex/}.

After package files have been unpacked to a \code{texmf} folder, the database of installed packages needs to be updated for the \LaTeX{} compiler to take notice of the additions. This is done with the \code{mktexlsr} command:

\begin{tikzCodeBlock}[title={Registering new \LaTeX{} packages},listing style=bashsource,code body/.append style={codebody color=white}]
mktexlsr

# Successful package installation can be checked by running the 
# kpsewhich command. For a package accessed in a document
# by \usepackage{package}, kpsewhich should return a path to
# package.sty
kpsewhich tikz.sty
!out/Users/Smithe/Library/texmf/tex/latex/pgf/frontendlayer/tikz.sty!/out
\end{tikzCodeBlock}

\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\part{Package Internals}
\label{part:three}

\epigraph{We will encourage you to develop the three great virtues of a programmer: {\itshape laziness}, {\itshape impatience}, and {\itshape hubris}.}{{\itshape Programming Perl}\\ --{\scshape Larry Wall}}

\section{Introduction and Background}

% A friendly reminder that this portion of the documen-scratch that, ravings may be more % incoherent and crazy than the preceding sections..
\tikzDocDisclaim{Caveat Lector}
{
The following introduction currently presents a \sout{vision}(delusion?) of what this section of the documentation could be. Currently the only portion of the inner workings of this package that we attempt to explain and document are those related to using the \LaTeX{} compiler to obtain font metrics.
}

We learn best through working with examples. When it comes to programming languages this involves taking working code that someone else has written, breaking it in as many places at it can possibly be broken, and then trying to build something out of the wreckage. Open source software facilitates this process wonderfully by ensuring the source code of a project is always available for inspection and experimentation. The \pkg{tikzDevice} its self was created by disassembling and then rebuilding Valerio Aimale's Pic\TeX{} device driver which is a part of the \lang{R} core codebase.

This section is our attempt to help anyone who may be experimenting with our code, and by extension the internals of the R graphics system. There may also be useful, or useless, tidbits concerning building R packages and interacting with the core R language. The R language can be extended in so many interesting and useful ways and it is our hope that the following documentation may provide a case study for anyone attempting such an extension.

We will make an attempt to assume no special expertise with any of the systems or programming languages leveraged by this package and described by this documentation. Therefore, if you are an experienced developer and find yourself thinking ``My god, are they {\bfseries really} about to launch into a description of how C header files work?", please feel free to skip ahead a few paragraphs. We received our formal introduction to computer programming in a college engineering program- therefore our programming background is rooted in Fortran (or, if you prefer, {\scshape fortran}). We are attempting to write the sort of documentation that we would have found invaluable at the start of this project

Therefore, this section is for all the budding developers like ourselves out there- people who have done some programming and who are starting to take a close look at the nuts and bolts of the \lang{R} programming environment. If you feel like you are wandering through a vast forest getting smacked in the face by every branch then maybe this section will help pull some of those branches out of the way...

...then again we have a lot of material to cover: R, C, \LaTeX , \TikZ{} , typography and the details of computerized font systems. Our grip may fail and send those branches flying back with increased velocity.

We wish you luck!\\
\vbox{}\quad{\itshape -The tikzDevice Team}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Anatomy of an \lang{R} Graphics Device}

The core of an \lang{R} graphics device is a collection of functions, written in C, that perform various specialized tasks. A description of some of these functions can be found in the {\itshape R Internals} manual while the main documentation is in the C header file \code{GraphicsDevice.h}. For most \lang{R} installations this header file can be found in the directory \code{R\_HOME/include/R\_ext}. For copies of \lang{R} distributed in source code form, \code{GraphicsDevice.h} is located inside \code{R-version/src/include/R\_ext}. The following is a description of the functions each graphics device is expected to provide:


\setlength\columnsep{5em}

\begin{multicols}{2}


\subsection*{Drawing Routines}

\begin{itemize}

\item[\code{circle}]{This function is required to draw a circle centered at a given location with a given radius.}

\item[\code{clip}]{This function specifies a rectangular area to be used a a clipping boundary for any device output that follows.}

\item[\code{line}]{This function draws a line between two points.}

\item[\code{polygon}]{This function draws lines between a list of points and then connects the first point to the last point.}

\item[\code{polyline}]{This function draws lines between a list of points.}

\item[\code{rect}]{This function is given a lower left corner and an upper right corner and draws a rectangle between the two.}

\item[\code{text}]{This function inserts text at a given location.}

\end{itemize}

\subsection*{Font Metric Routines}

\begin{itemize}

\item[\code{metricInfo}]{This function is given the name of a single character and reports the ascent, descent and width of that character.}

\item[\code{strWidth}]{This function is given a text string and reports the width of that string.}

\end{itemize}

\subsection*{Utility Routines}

\begin{itemize}

\item[\code{activate}]{This function is called when the device is designated as the active output device- i.e. by using \code{dev.set()} in \lang{R}}

\item[\code{close}]{This function is called when the device is shut down- i.e. by using \code{dev.off()} in \lang{R}}

\item[\code{deactivate}]{This function is called when another device is designated as the active output device.}

\item[\code{locator}]{This function is mainly used by devices with a GUI window and reports the location of a mouseclick.}

\item[\code{mode}]{This function is called when a device begins drawing output and again when the device finishes drawing output.}

\item[\code{newPage}]{This function initiates the creation of a new page of output.}

\item[\code{size}]{This function reports the size of the canvas the device is drawing on.}

\end{itemize}

\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Calculating Font Metrics}

Font metrics are measurements associated with the glyphs, or printed characters, of a particular font. \lang{R} requires three of these metrics in order to produce correctly aligned output. The three metrics graphics devices are required to supply are:

\begin{tikzpicture}

\coordinate (centerpoint) at (0,0);

\node[anchor=north,outer sep=0pt] (title) at ($(centerpoint) + (4em,0)$) {\bfseries Ascent};

\node[scale=4,text=black!40,inner sep=0pt,outer sep=0pt,below=0.25em of title] (char) {g};
\draw[color=black,very thick] (char.base west) -- (char.base east);
\draw[color=black,very thick] (char.north west) -- (char.north east);
\draw[color=red,very thick,<->,>=stealth] ([xshift=10pt]char.base west) -- ([xshift=10pt]char.north west);


\newdimen\yone
\newdimen\ytwo

\pgfextracty{\yone}{\pgfpointanchor{char}{north}}
\pgfextracty{\ytwo}{\pgfpointanchor{char}{south}}
\pgfmathparse{ \yone - \ytwo }

\yone = \pgfmathresult pt

\node[anchor = north west,outer sep=0pt,text width=0.6\textwidth] at ($(centerpoint) + (8em, 0)$){
Ascent is the distance between the baseline and the tallest point on a
character's glyph. For the "g" printed to the left, the ascent has been
calculated as: \the\yone
};
\end{tikzpicture}



\begin{tikzpicture}

\coordinate (centerpoint) at (0,0) {};

\node[anchor=north,outer sep=0pt] (title) at ($(centerpoint) + (4em,0)$) {\bfseries Descent};

\node[scale=4,text=black!40,inner sep=0pt,outer sep=0pt,below= 0.25em of title.south] (char) {g};
\draw[color=black,very thick] (char.base west) -- (char.base east);
\draw[color=black,very thick] (char.south west) -- (char.south east);
\draw[color=red,very thick,<-,>=stealth] ([xshift=10pt]char.south west) -- +(0,-6pt);
\draw[color=red,very thick,<-,>=stealth] ([xshift=10pt]char.base west) -- +(0,+6pt);


\newdimen\yone
\newdimen\ytwo

\pgfextracty{\yone}{\pgfpointanchor{char}{base}}
\pgfextracty{\ytwo}{\pgfpointanchor{char}{south}}
\pgfmathparse{ \yone - \ytwo }

\yone = \pgfmathresult pt

\node[anchor = north west,outer sep=0pt,text width=0.6\textwidth] at ($(centerpoint) + (8em, 0)$){
Descent is the distance between the baseline and the lowest point on a
character's glyph. For the "g" printed to the left, the descent has been
calculated as: \the\yone
};
\end{tikzpicture}



\begin{tikzpicture}

\coordinate (centerpoint) at (0,0);

\node[outer sep=0pt,anchor=north] (title) at ($(centerpoint) + (4em,0)$) {\bfseries Width};

\node[scale=4,text=black!40,inner sep=0pt,outer sep=0pt,below= 0.25em of title.south] (char) {g};
\draw[color=black,very thick] (char.south west) -- (char.north west);
\draw[color=black,very thick] (char.south east) -- (char.north east);
\draw[color=red,very thick,<->,>=stealth] (char.base west) -- (char.base east);

\newdimen\xone
\newdimen\xtwo

\pgfextractx{\xone}{\pgfpointanchor{char}{east}}
\pgfextractx{\xtwo}{\pgfpointanchor{char}{west}}
\pgfmathparse{ \xone - \xtwo }

\xone = \pgfmathresult pt

\node[anchor = north west,outer sep=0pt,text width=0.6\textwidth] at ($(centerpoint) + (8em, 0)$){
Width is the distance between the left and right sides of a character's glyph.
For the "g" printed to the left, the width has been calculated as: \the\xone};
\end{tikzpicture}

Providing font metrics and string widths is without a doubt most difficult task a \lang{R} graphics device must undertake. The calculation of string widths is made even difficult for the \pkg{tikzDevice} as we attempt to process arbitrary \LaTeX{} strings. Inside \lang{R} the string ``\verb`$\alpha$`" literally has 8 characters, but when it is typeset it only has one: $\alpha$.

Calculating font metrics is a tricky business to begin with and the fact that the typeset representation of a \LaTeX{} string is different from its representation in source code compounds the difficulty of the task immensely. Therefore, we took the path of laziness and started looking for an easy way out (remember the three great virtues of a programmer?). The solution we came up with seemed easy enough-- make \LaTeX{} calculate these metrics for us, after all that is what a \LaTeX{} compiler does for a living.

Now, how to do that?

\subsection{Character Metrics}

As a starting point, let's examine the interface of the C function that \lang{R} calls in order to determine character metrics:

\begin{tikzCodeBlock}[title={Function declaration for \code{metricInfo}}]
void (metricInfo)(int c, const pGEcontext gc,
  double* ascent, double* descent, double* width,
  pDevDesc dd);
\end{tikzCodeBlock}

The most important variables involved in the function are \code{c}, \code{ascent}, \code{descent} and \code{width}. The incoming variable is \code{c}, which contains the character for which \lang{R} is requesting font metrics. Interestingly, \code{c} is passed as an integer, not a character as one might expect. What's up with that? Well, the short answer is that \lang{R} passes the \code{ASCII} or \code{UTF8} {\itshape symbol code} of a character and not the character it's self. How to use that character code to recover a character will be explained later.

The outgoing variables are \code{ascent}, \code{descent} and \code{width}. The asterisks, `*', in their definitions mean these variables are passed as {\itshape pointers} as opposed to {\itshape values}. A complete discussion of the differences between pointers and values could, and has, filled up several chapters of several programming books. The important distinction in context of the \code{metricInfo} function is that when a number is assigned to a pointer variable, that number is available elsewhere after the function terminates. In contrast, when a number is assigned to a value variable, that number disappears when the function ends unless it is explicitly sent back out to the wide world through the \code{return} statement. So, the main task of the \code{metricInfo} function is to assign values to \code{ascent}, \code{descent} and \code{width}.

The other two variables present in the function are the \code{pGEcontext} variable \code{gc} and the \code{pDevDesc} variable \code{dd}. \code{gc} contains information such as the font face, foreground color, background color, character expansion factor, ect. currently in use by the graphics system. \code{dd} is the object which contains \lang{R}'s representation of the graphics device. For the sake of simplifying the following discussion, we will ignore these variables.

So, to recap-- we have an integer \code{c} coming in that represents a code for a character in the \code{ASCII} or \code{UTF8} symbol tables (for the sake of the following discussion, we will assume \code{ASCII} characters only). Our overall task is to somehow turn that integer into three numbers which can be assigned to the pointer variables \code{ascent}, \code{descent} and \code{width}. And, since we're being lazy, we've decided that the best way to do that is to ask the \LaTeX{} compiler to compute the numbers for us.

Recovering these numbers from the \LaTeX{} compiler involves the execution of three additional tasks:

\begin{enumerate}

	\item{We must write a \LaTeX{} input file that contains instructions for calculating the metrics.}
	
	\item{We call the \LaTeX{} compiler to process that input file.}
	
	\item{We must read the compiler's output in order to recover the metrics.}

\end{enumerate}

Each of these tasks could be executed from inside our \lang{C} function, \code{metricInfo}. However, we will run into some difficulties- namely with step 2, which involves calling out to the operating system with orders to run \LaTeX . Each operating system handles these calls a little differently and our package must attempt to get this job done whether it is running on Windows, UNIX, Linux or Mac OS X.

Portable \lang{C} code could be written to handle each of these situations, but that is starting to sound like work and we're trying to be lazy here. What we need is to be able to work at a higher {\itshape level of abstraction}. That is-- instead of using \lang{C}, we need to be working inside a language that shields us from such details as what operating system is being used. \lang{R} may have called this \lang{C} function to calculate font metrics, but we really want to do the actual computations back inside \lang{R}.

\subsection{Calling \lang{R} Functions from \lang{C} Functions}

The ``Ritual of the Calling of the R Function" is easy enough to perform as long as you don't have burning need to know all the details of the objects you are handling. The \lang{C} level representation of a \lang{R} object such as a variable or function is an object known as a \code{SEXP}. For the exact details on what a \code{SEXP} is and how it works, we refer the interested user to chapter one of the {\itshape R Internals} manual.

The \lang{R} function we will be calling is declared in the \lang{R} environment as follows:

\begin{tikzCodeBlock}[title={Definition of target \lang{R} function},listing style=sweavechunk]
getLatexCharMetrics <- function( charCode ){

  # System call to LaTeX

}
\end{tikzCodeBlock}

In order to call this function for \lang{C}, we need a vector composed of two \lang{C}-level \lang{R} objects-- one containing the name of the function we are calling and another one containing the value we are passing for \code{charCode}. This is set up in \lang{C} as follows:

\begin{tikzCodeBlock}[title={Preparing a \lang{R} function call inside \lang{C}}]
void (metricInfo)(int c, const pGEcontext gc, double* ascent, double* descent,
  double* width, pDevDesc dd){
  
  SEXP RCallBack;
  PROTECT( RCallBack = allocVector(LANGSXP, 2) );
  
  SEXP metricFun = findFun( install("getLatexCharMetrics"), R_Global_Env );
  
  SETCAR( RCallBack, metricFun );
  
  SETCADR( RCallBack, ScalarInteger( c ) );
  SET_TAG( CDR( RCallBack ), install("charCode") );

  \\ To be continued...

}
\end{tikzCodeBlock}

The first thing that happens in the code chunk above is that a new \code{SEXP} variable named \code{RCallBack} is created. This variable will be the agent through which we will communicate with the \lang{R} environment. The next action is to allocate our callback variable as a vector of length 2-- we need one slot for the \lang{R} function name and one slot for the value that is being passed into the function. This allocation happens inside the \lang{R} environment, so it is executed inside the \code{PROTECT} statement. The reason for using \code{PROTECT} is that the \lang{R} garbage collector is constantly on the prowl for unused objects in the \lang{R} environment. An object is considered ``unused" if it is not attached to any variable name in the \lang{R} environment. Since the object is only attached to the variable \code{RCallBack} in our \lang{C} function, the \lang{R} garbage collector will see it a valid candidate for deletion. The purpose of \code{PROTECT} is to keep our new vector from being trashed.

The next portion of the \lang{C} function retrieves the \lang{R} function object for \code{getLatexCharMetrics}. The function is searched for in \lang{R} global namespace, so it must be one that is available to the user from the \lang{R} command prompt when the package is loaded. The function is stored in the \code{SEXP} variable \code{metricFun}. We do not have to involve \code{PROTECT} in the assignment since \code{getLatexCharMetrics} exists as a variable name in the \lang{R} environment.

The last portion of the code chunk is responsible for loading the function name and call value into \code{RCallBack}. The \code{CAR} statement is used to retrieve the value of a \code{SEXP} variable and the \code{SETCAR} statement is used to set the value of a \code{SEXP}. In this case we use \code{SETCAR} to designate the \lang{R} function stored in \code{metricFun} as the first value of \code{RCallBack}.

When dealing with a vector \code{SEXP} such as \code{RCallBack}, which has 2 slots, we need to use a different function to access the second slot. The \code{CDR} function will allow us to move to the second slot in \code{RCallBack} where we may perform a \code{SETCAR} to specify a value. In the example code, these operations were combined by using the \code{SETCADR} function which has the same effect as:

\begin{tikzCodeBlock}[no break=true,listing style=sweavechunk]
SETCAR( CDR(RCallBack), ScalarInteger( c ) );
\end{tikzCodeBlock}

After assigning the value of the \lang{C} variable \code{c} as the second value of \code{RCallBack}, we need to "tag" it as the value that corresponds to the \code{charCode} argument of \code{getLatexCharMetrics}. This is done by using the \code{SET\_TAG} function. Once again, we use \code{CDR} to shift our area of operation to the second slot of \code{RCallBack}. Now that the \code{RCallBack} object is set up, we are ready to actually call the \code{getLatexCharMetrics} function.

\begin{tikzCodeBlock}[title={Executing a \lang{R} function call inside \lang{C}}]
SEXP LatexMetrics;
PROTECT( LatexMetrics = eval( RCallBack, R_GlobalEnv) );
\end{tikzCodeBlock}

And that's it! We create a new \code{SEXP} to hold the return values of \code{getLatexCharMetrics} and execute the \code{eval} function to cause \code{getLatexCharMetrics} to be executed inside the \lang{R} environment. The details of the \lang{R} function will be explained in the next section, for now let's assume that it returns the three values we're interested in as a vector of three numbers. How do we extract these values and assign then to \code{ascent}, \code{descent} and \code{width}?

\begin{tikzCodeBlock}[title={Recovering return values from a \lang{R} function call}]
  *ascent = REAL(RMetrics)[0];
  *descent = REAL(RMetrics)[1];
  *width = REAL(RMetrics)[2];

  UNPROTECT(2);

  return;
\end{tikzCodeBlock}

Here the \code{REAL} function is used to coerce the \code{SEXP} variable \code{RMetrics} to a vector of real numbers. These numbers are then extracted and assigned to the return values of \code{metricInfo}. In \lang{C} we must specify the `first' value in a vector using the index 0 rather than the index 1 \footnote{There are good logical reasons for this from the point of view of a computer scientist-- but if your background in arrays is rooted in linear algebra it will be a bit disorienting.}. The last thing to do is release the restrictions we placed on the \lang{R} garbage collector. Since we used the \code{PROTECT} function twice, we must call \code{UNPROTECT} and pass 2 as the argument.

\subsection{Implementing a System Call to \LaTeX}

Now we may turn to the actual guts of the \lang{R} function \code{getLatexCharMetrics}.  The first thing we need to do is set up a file for \LaTeX{} input:

\begin{tikzCodeBlock}[title={Creating a \LaTeX{} input file},listing style=sweavechunk]
getLatexCharMetrics <- function( charCode ){

  texDir <- tempdir()
  
  texLog <- file.path( texDir,'tikzStringWidthCalc.log' )
  texFile <- file.path( texDir,'tikzStringWidthCalc.tex' )

  texIn <- file( texFile, 'w')
  
  # To be continued...
\end{tikzCodeBlock}

The first thing we do is choose a place to create this input file. Now, when the \LaTeX{} compiler is run on a \code{.tex} file, a lot of additional files get created-- the whole process is a bit messy. Since the user probably wouldn't appreciate having to clean up our mess, we use the \code{tempdir()} function to retrieve a path to a {\itshape temporary directory} on the system. Here is the first place we benefit from the added level of abstraction granted by \lang{R}. Each operating system has different locations for temporary directories. If we were still working in \lang{C}, we would have to worry about such details. \lang{R} takes care of those details for us.

Now that we have a place to work, we set up a couple of filenames- one for the input file, which ends in \code{.tex} and one for the \LaTeX{} log file, which ends in \code{.log}. We then open the \code{.tex} file for writing. The next step is to setup the preamble of the \LaTeX{} file.

\begin{tikzCodeBlock}[title={Setting up the preamble of a \LaTeX{} input file},listing style=sweavechunk]
  writeLines("\\documentclass{article}", texIn)
  
  writeLines("\\usepackage[T1]{fontenc}", texIn)
  
  writeLines("\\usepackage{tikz}", texIn)
  writeLines("\\usetikzlibrary{calc}", texIn)
 
  writeLines("\\batchmode", texIn)
\end{tikzCodeBlock}

Here we have started a standard \LaTeX{} input file by specifying
\code{article} as the document class. We also add the \code{fontenc} package
and specify \code{T1} as its option. This ensures we are using the Type 1 font
encoding- by default \TeX and \LaTeX{} use an encoding called \code{OT1}. Why
do we need to worry about font encodings? Well, a font encoding specifies which
\code{ASCII} symbol codes map to which characters and by default, \lang{R}
expects us to be using the Type 1 encoding (\lang{R} does support other
encodings- but we're ignoring that for now). For example, in the Type 1
encoding, the character that corresponds to the \code{ASCII} code 60 is the
less-than sign: `{\char60}'. If we were to allow \TeX{}
to retain its default \code{OT1} encoding, that same character code would
instead map to an upside-down exclamation point: `{\usefont{OT1}{lmr}{m}{n}\char60}'.

The other two packages we load are the \code{tikz} package and its \code{calc}
library. Essentially we will have \TikZ{} drop the character into a box and
report some measurements concerning the size of that box. The last command,
\code{batchmode} tells \LaTeX{} that there isn't any user available to interact
with-- so it should bother to stop and ask any questions while processing this
file.

The next step is to set up the part of the \LaTeX{} file that will actually
calculate and report the widths we are looking for. As mentioned before, this
is done by setting the character inside a \TikZ{} node and extracting the
dimensions of the box that surrounds it. In an attempt to improve clarity, the
following code will be presented as straight \LaTeX{} --
\code{getLatexCharMetrics} inserts it into the \code{texIn} file by means of
\code{writeLines} as we have been doing all along. The string highlighted in
{\color{red} red} should be replaced with the value of the variable charCode
that was passed in to the function\code{getLatexCharMetrics}.

\begin{tikzCodeBlock}[title={Extracting character dimensions using \TikZ},listing style=latexexample]
\begin{tikzpicture}

\node[inner sep=0pt,outer sep=0pt] (char) {\charXXcharCodeXX};

\path let \p1 = ($(char.east) - (char.west)$), 
  \n1 = {veclen(\x1,\y1)} in (char.east) -- (char.west)
  node{ \typeout{tikzTeXWidth=\n1} };
 
\path let \p1 = ($(char.north) - (char.base)$), 
  \n1 = {veclen(\x1,\y1)} in (char.north) -- (char.base)
  node{ \typeout{tikzTeXAscent=\n1} };
  
\path let \p1 = ($(char.base) - (char.south)$), 
  \n1 = {veclen(\x1,\y1)} in (char.base) -- (char.south)
  node{ \typeout{tikzTeXDescent=\n1} };
\end{tikzCodeBlock}

What the heck just happened? Well, first we instructed \LaTeX{} to enter the \TikZ{} picture environment using \verb`\begin{tikzpicture}`. Then we ordered \TikZ{} to create a node named "char" containing the command \verb`\char` followed by the value of charCode. For example, if we were passed `103' as the character code, which corresponds to the character `g', the node line should be:

\begin{tikzCodeBlock}[listing style=latexexample]
\node[inner sep=0pt,outer sep=0pt] (char) {\char103};
\end{tikzCodeBlock}

The \code{inner sep} and \code{outer sep} options are set to \code{0pt} in order to ensure the boundaries of the node `hug' the contents tightly. Now the whole point of setting the character inside a node is that \TikZ{} defines `anchors' along the bounding box of the node. All anchors are referred using a \code{node name.posistion} notation. Since we named the node \code{char}, all the anchors start with \code{char}. The anchor posistions relevant to our problem are shown below:

\begin{center}
\begin{tikzpicture}

	\node[draw=black, very thick,inner sep=0, outer sep=0, text=black!40,scale=14] 
	  (char) {\char103};
	  
	\foreach \anchor/\placement in 
		{north/above, south/below, base/below, east/right, west/left} {
		
		\draw[shift=(char.\anchor),color=red] plot[mark=*] coordinates{(0,0)}
			node[\placement,text=red] {\small\texttt{(char.\anchor)}};
	}
	
	\node[above= 1em of char.north] {Node Bounding Box}
		edge[ultra thick,->,>=stealth,out=0,in=0] ($(char.10) + (6pt,12pt)$);
		
	
\end{tikzpicture}
\end{center}

The `base' anchor sits on the baseline of the text-- therefore to calculate the ascent of the character `g', all we have to do is figure out the difference in height between the positions \code{char.north} and \code{char.base}. Similarly, for the descent we would calculate the difference in height between \code{char.base} and \code{char.south} and width can be obtained using \code{char.west} and \code{char.east}. This is the purpose of the admittedly cryptic \verb`\path` commands that are inserted in the \LaTeX{} input file. Let's examine one of them:

\begin{tikzCodeBlock}[]
\path let \p1 = ($(char.north) - (char.base)$), 
  \n1 = {veclen(\x1,\y1)} in node{ \typeout{tikzTeXAscent=\n1} };
\end{tikzCodeBlock}

So, what exactly is going on here? Normally, the \verb`\path` command is used to draw lines between points and add additional coordinates or nodes along those lines. For example, the command:

\begin{tikzCodeBlock}[]
\path[draw] (0,0) -- (1,1) node {Hi!};
\end{tikzCodeBlock}

Draws a line from \code{(0,0)} to \code{(1,1)} and places a node at \code{(1,1)} containing the word `Hi!'. In the \TikZ{} code produced by \code{getLatexCharMetrics}, the \code{let} operation is specified. Basically, \code{let} postpones the actual drawing of a path and performs calculations until the \code{in} keyword is encountered. The result of these calculations are stored in a set of special variables which must start with \verb`\n`, \verb`\p`, \verb`\x` or \verb`\y`. The first \code{let} operation executed is:

\begin{tikzCodeBlock}[]
\p1 = ( $(char.north) - (char.base)$ )
\end{tikzCodeBlock}

This performs a vector subtraction between the coordinates of \code{char.north} and \code{char.base}. The resulting x and y components are stored in the `point' variable \verb`\p1`. The second operation executed is:

\begin{tikzCodeBlock}[]
\n1 = {veclen(\x1,\y1)}
\end{tikzCodeBlock}

This code \code{let} operation treats the coordinates stored in \verb`\p1` as a vector and calculates its magnitude. The `1' appended to the \verb`\x` and \verb`\y` variables specifies that we are accessing the x and y components of \verb`\p1`. This result is stored in the `number' variable \verb`\n1`. Now, that our metric is stored in \verb`\n1`, our final task is to ensure it makes it into the \LaTeX{} \code{.log} file-- this is done by adding a \code{node} containing the \verb`\typeout` command. The contents of the node:

\begin{tikzCodeBlock}[]
\typeout{tikzTexAscent=\n1}
\end{tikzCodeBlock}

Cause the phrase `tikzTexAscent=' to appear in the \code{.log} file- followed by the ascent calculated using the node anchors. After the ascent, descent and width have been calculated the \LaTeX{} compiler may be shut down, this is done by adding the final two lines to the input file:

\begin{tikzCodeBlock}[title={Terminating a \LaTeX{} compilation},listing style=sweavechunk]
  writeLines("\\makeatother", texIn)
  
  writeLines("\\@@end", texIn)
  
  close(texIn)
\end{tikzCodeBlock}

Now that the input file has been prepped, we must process it using the \LaTeX{} compiler and load the contents of the resulting \code{.log} so that we may search for the metrics we dumped using \verb`\typeout`.

\begin{tikzCodeBlock}[title={Terminating a \LaTeX{} compilation},listing style=sweavechunk]
  latexCmd <- getOption('tikzLatex')
  latexCmd <- paste( latexCmd, '-interaction=batchmode',
    '-output-directory', texDir, texFile)

  silence <- system( latexCmd, intern=T, ignore.stderr=T)
 
  texOut <- file( texLog, 'r' )
 
  logContents <- readLines( texOut )
  close( texOut )
\end{tikzCodeBlock}

The \LaTeX{} compiler is executed through the \code{system} function which handles the details of implementing a system call on whatever operating system we happen to be using. We assign the return value of the \code{system} function to a dummy variable called \code{silence} so that no output floods the user's screen. The last task is to extract our metrics from the text of the \code{.log} we loaded.

\begin{tikzCodeBlock}[title={Parsing the \code{.log} file text},listing style=sweavechunk]
  match <- logContents[ grep('tikzTeXWidth=', logContents) ]
  width <- gsub('[=A-Za-z]','',match)

  match <- logContents[ grep('tikzTeXAscent=', logContents) ]
  ascent <- gsub('[=A-Za-z]','',match)
 
  match <- logContents[ grep('tikzTeXDescent=', logContents) ]
  descent <- gsub('[=A-Za-z]','',match)
 
  return( as.double( c(ascent,descent,width) ) )
\end{tikzCodeBlock}

Here we use the \code{grep} function to search through the log output for the tags `tikzTeXWidth=', `tikzTeXAscent=' and `tikzTeXDescent=' that we specified when we used \verb`\typeout`. After we recover a line containing one of these tags, we use the \code{gsub} command to remove the letters and the equals sign from the text line-- leaving just the number we're interested in. These values are then coerced using \code{as.double} and set as the return value of \code{getLatexCharMetrics}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{On the Importance of Font and Style Consistency in Reports}
If you haven't figured it out by now, we are quite picky about the way our graphics and reports look.  We are especially picky about the consistency in fonts (both sizes and shapes).  Without launching into a diatribe about this, we just want to say with tools like \pkg{tikzDevice} you no longer have to settle for what is ``just okay.'' So go nuts, be picky about how your text and graphics look.  Don't be afraid to snub your nose at reports which pay no attention to detail.  Be that person who says ``NO! I wont settle for half rate graphics, I want the best!''

\section{The \pkg{pgfSweave} Package and Automatic Report Generation}
Now for a little shameless self promotion. The authors of \pkg{tikzDevice} have another package called \pkg{pgfSweave} which provides a driver for Sweave.  \pkg{pgfSweave} started as an interface to \href{http://sourceforge.net/projects/eps2pgf/}{eps2pgf} and its ability to interpret strings in eps files as \LaTeX{}.  This was used to much the same effect as \pkg{tikzDevice}.  The problem was the conversion from eps to pgf was SLOW.  Long story short, by combining this functionality with the externalization feature of pgf and the \pkg{cacheSweave} we were able to achieve bearable compilation speed and nice looking graphics.   \pkg{pgfSweave} is in the process of getting pumped up by interfacing with the \pkg{tikzDevice} package.   We hope that the combination will be a self-caching, consistency-inducing, user-empowering tool for high quality reports.

\newpage

\bibliography{refs}

\end{document}\n