%% LyX 2.0.5.1 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[nohyper,justified]{tufte-handout}
\usepackage[T1]{fontenc}
\usepackage{booktabs}
\usepackage{url}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.

\title{Customizing Syntax Highlighting Themes}
\author{Yihui Xie \& Ramnath Vaidyanathan}
\newcommand{\noun}[1]{\textsc{#1}}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\renewcommand{\textfraction}{0.05}
\renewcommand{\topfraction}{0.8}
\renewcommand{\bottomfraction}{0.8}
\renewcommand{\floatpagefraction}{0.75}

\usepackage[breaklinks=true,pdfstartview=FitH]{hyperref}

\makeatother

\begin{document}

<<setup, include=FALSE, cache=FALSE>>=
opts_chunk$set(fig.path='figure/theme-', cache.path='cache/theme-', cache=TRUE)
options(replace.assign=TRUE,width=78)
knit_hooks$set(par=function(before, options, envir){if (before) par(mar=c(4,4,.1,.1),cex.lab=.95,cex.axis=.9,mgp=c(2,.7,0),tcl=-.3)})
@
<<solarized-theme, cache=FALSE, echo=FALSE>>=
thm = knit_theme$get("solarized-dark")
knit_theme$set(thm)
@

\maketitle
\begin{abstract}
This manual%
\footnote{source code at \url{https://github.com/yihui/knitr/blob/master/inst/examples/knitr-themes.Rnw}%
} shows how to customize syntax highlighting of source code using themes.
It walks the user through the basics of syntax highlighting in \textbf{knitr},
the use of built-in themes as well as those from \url{http://www.eclipsecolorthemes.org/}.
\end{abstract}
The \textbf{knitr} package uses the \textbf{highlight} package by
Romain Francois to highlight source code in a document. In short,
the \textbf{highlight} package parses the source code using the \noun{bison}
parser, tokenizes it into grammar symbols, and formats their appearance
based on a CSS style file. 


\section{Usage}

We can use the object \texttt{knit\_theme} to set / get a theme. See
\texttt{?knit\_theme} for the usage. For example, we set the theme
of this document to be \texttt{solarized-dark}:

<<solarized-theme>>=
@


\section{Built-in Themes}

\begin{margintable}
<<eclipse-css, comment=NA, echo=FALSE>>=
cat(c(readLines('../themes/edit-eclipse.css', n=30),'...'),sep='\n')
@
\end{margintable}


The listing on the right shows the CSS file for one of the themes,
\texttt{edit-eclipse}, which was adapted from Andre Simon's excellent
highlighter%
\footnote{\url{http://www.andre-simon.de/}%
}. The \textbf{knitr} package comes pre-loaded with a number of themes
based on this highlighter. Here is list of all available code themes:

<<all-themes>>=
knit_theme$get()
@

Shown below is how the \texttt{solarized-dark} theme looks like when
applied to R code:

<<demo-code, eval = FALSE>>=
# SCRAPE THE DATA FROM WEB 

base_url = "http://www.mlsoccer.com/stats/%s/reg"
years    = 1996:2010
options(width = 40)

#' Function to save data for each year
save_data = function(y){
  url  = sprintf(base_url, y)
  tab  = XML::readHTMLTable(url, header = FALSE, stringsAsFactors = FALSE);
  pos  = max(grep("United", tab));
  tab  = tab[[pos]];
  tab$year   = y;
  return(tab)            
}
	
team.list  = plyr::llply(years, save_data);
mls        = reshape::merge_recurse(team.list);
@


\section{Eclipse Color Themes}

A rich repository of syntax highlighting themes for use with Eclipse
IDE is available at \url{http://www.eclipsecolorthemes.org/}. In
order to use one of these themes with \textbf{knitr}, it needs to
be converted into a CSS file that can be parsed by \textbf{highlight}.
This is achieved by mapping language tokens across the two formats
(Table \ref{mar:Token-Mapping}) to create a CSS file.

\begin{margintable}
\renewcommand\arraystretch{1.3}

\caption{Token mapping\label{mar:Token-Mapping}}


\noindent %
\begin{tabular}{ll}
\toprule 
\textbf{Highlight (CSS)} & \textbf{Eclipse (XML)}\tabularnewline
\midrule
background & background\tabularnewline
number & number\tabularnewline
functioncall & method\tabularnewline
string & string\tabularnewline
keyword & keyword\tabularnewline
argument & localVariable\tabularnewline
comment & singleLineComment\tabularnewline
roxygencomment & javadoc\tabularnewline
formalargs & localVariable\tabularnewline
eqformalargs & foreground\tabularnewline
assignement & foreground\tabularnewline
package & class\tabularnewline
slot & foreground\tabularnewline
symbol & localVariableDeclaration\tabularnewline
prompt & foreground\tabularnewline
\bottomrule
\end{tabular}
\end{margintable}


If you want to use an eclipse theme that is not shipped with \textbf{knitr},
you can use the utility function \emph{eclipse\_theme()} to automatically
download, map and save the theme as a CSS file. For example, if you
want to use the theme Oughsumm%
\footnote{\url{http://www.eclipsecolorthemes.org/?view=theme&id=1885} (theme
id is 1885)%
}, you can use the code below in your first chunk:

<<eclipse-theme, eval=FALSE>>=
css = eclipse_theme(1885)
thm = knit_theme$get(css)
knit_theme$set(thm)
@

Note this requires Internet connection, and we can put the code to
download the theme in a cached chunk, so it will be downloaded only
once, then we set the theme in an uncached chunk using the parsed
theme object. For example, download the theme:

%% please use cache=TRUE and echo=FALSE for this chunk
<<download-theme, eval=FALSE, message=FALSE>>=
(css = eclipse_theme(1885))
thm = knit_theme$get(css)
@

Then apply the theme:

%% cache=FALSE for this chunk
<<apply-theme, eval=FALSE>>=
knit_theme$set(thm)
@

Even we do not have Internet connection the next time, we can still
use the theme.


\section{Misc}

One thing to consider is the foreground color of plots when we use
dark themes; we need to make it lighter, otherwise the graphical elements
will be difficult to be read. We can access the foreground color of
the theme in the list returned by \texttt{knit\_theme\$get(theme)},
e.g., for this document:

<<fg-color>>=
## the object thm is from the first chunk
thm$foreground  # foreground color
thm$background  # background color
@

When we make plots, we may use these colors, e.g.

<<plot-color, fig.width=6, fig.height=4, out.width='.8\\linewidth', par=TRUE>>=
## can design a chunk hook to set foreground color automatically
fgcolor=thm$foreground
par(fg=fgcolor, col.axis=fgcolor, col.lab=fgcolor)
plot(rnorm(100),pch=19)
@

Of course, we do not need to worry about these colors when we use
a white background for the plots.

\end{document}
