% \VignetteIndexEntry{odfWeave Manual}
% \VignetteDepends{odfWeave}
% \VignetteKeywords{Sweave}
% \VignettePackage{odfWeave}
\documentclass[12pt]{article}
\usepackage{amsmath}
\usepackage[pdftex]{graphicx}
\usepackage{color}
\usepackage{xspace}
\usepackage{fancyvrb}
\usepackage{fancyhdr}
\usepackage{lastpage}
\usepackage{algorithm2e}
\usepackage[
         colorlinks=true,
         linkcolor=blue,
         citecolor=blue,
         urlcolor=blue]
         {hyperref}
\usepackage{Sweave}         

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

% define new colors for use
\definecolor{darkgreen}{rgb}{0,0.6,0}
\definecolor{darkred}{rgb}{0.6,0.0,0}
\definecolor{lightbrown}{rgb}{1,0.9,0.8}
\definecolor{brown}{rgb}{0.6,0.3,0.3}
\definecolor{darkblue}{rgb}{0,0,0.8}
\definecolor{darkmagenta}{rgb}{0.5,0,0.5}

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

\newcommand{\odfWeave}{{\tt odfWeave}\xspace}
\newcommand{\odfWeaveFunc}{{\tt odfWeave}\xspace}

\newcommand{\bld}[1]{\mbox{\boldmath $#1$}}
\newcommand{\shell}[1]{\mbox{$#1$}}
\renewcommand{\vec}[1]{\mbox{\bf {#1}}}

\newcommand{\ReallySmallSpacing}{\renewcommand{\baselinestretch}{.6}\Large\normalsize}
\newcommand{\SmallSpacing}{\renewcommand{\baselinestretch}{1.1}\Large\normalsize}

\newcommand{\halfs}{\frac{1}{2}}

\setlength{\oddsidemargin}{-.25 truein}
\setlength{\evensidemargin}{0truein}
\setlength{\topmargin}{-0.2truein}
\setlength{\textwidth}{7 truein}
\setlength{\textheight}{8.5 truein}
\setlength{\parindent}{0.20truein}
\setlength{\parskip}{0.10truein}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagestyle{fancy}
\lhead{}
\chead{OdfWeave}
\rhead{}
\lfoot{}
\cfoot{}
\rfoot{\thepage\ of \pageref{LastPage}}
\renewcommand{\headrulewidth}{1pt}
\renewcommand{\footrulewidth}{1pt}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\title{The OdfWeave Package}
\author{Max Kuhn \\ max.kuhn@pfizer.com}


\begin{document}

\maketitle

\thispagestyle{empty}
	
\section{Introduction}

<<loadLib, results = hide, echo = FALSE>>=
library(odfWeave)
@

The \texttt{Sweave} function (Leisch, 2002) is a powerful component of R. It can be used to combine R code with \LaTeX{} so that the output of the code is embedded in the processed document. The capabilities of \texttt{Sweave} were later extended to HTML format in the \texttt{R2HTML} package.

A written record of an analysis can be created using \texttt{Sweave}, but additional annotation of the results may be needed such as context--specific interpretation of the results. \texttt{Sweave} can be used to automatically create reports, but it can be difficult for researchers to add their subject--specific insight to pdf or HTML files.

The \odfWeave package was created so that the functionality of \texttt{Sweave} can used to generate documents that the end--user can easily edit. 

The markup language used is the Open Document Format (ODF), which is an open, non--proprietary format that encompasses text documents, presentations and spreadsheets. Version 1.0 of the specification was finalized in May of 2005 (OASIS, 2005). One year later, the format was approved for release as an ISO and IEC International Standard. 

There are several editors/office suites that can produce ODF files. OpenOffice is a free, open source editor that, as of version 2.0, uses ODF as the default format. \odfWeave has been tested with OpenOffice to produce text documents. As of the current version, \odfWeave processing of presentations and spreadsheets should be considered to be experimental (but should be supported in subsequent versions). OpenOffice can be used to export the document to MS Word, rich text format, HTML, plain text or pdf formats.

One advantage to using \texttt{Sweave} with ODF files is that no experience with markup languages is needed, so a broader set of users can create documents. However, the Open Document Format is very new and may go through significant changes in the future 

Users can create documents with \texttt{Sweave} commands in ODF using (almost) exactly the same format as required when using \LaTeX{} markup. A basic call to \odfWeaveFunc looks like
\begin{verbatim}
odfWeave(inFile, outFile, workDir = odfTmpDir(), control = odfWeaveControl())
\end{verbatim}
where \texttt{inFile} and \texttt{outFile} are the source and destination file names, \texttt{workDir} is a path where the files are processed and \texttt{control} is a control object that can be used to specify image formats and style specifications. The functionality of \odfWeave is described in more detail later.

\section{Requirements}

To use \odfWeave, the user must have a basic understanding of \texttt{Sweave}.

\odfWeave  requires files to be in the Open Document Format, version 1.0 or above. These can be generated by OpenOffice version 2.0 or above (see Section 3). The package also requires a utility to zip and unzip compressed files, such as \texttt{unzip}\footnote{a free utility available for many operating systems at \href{http://www.info-zip.org/} {http://www.info-zip.org/}}, \texttt{Winzip} or \texttt{jar}.

Also, by default, \odfWeaveFunc tries to save images in png format. In Unix and Linux, a png device may not be available. There are three options if this is the case: enable the png device, using the \texttt{bitmap} device (which requires GhostScript) or specify an alternate image format.



\section{The Open Document Format}

The Open Document Format is a document format that encompasses text documents, spreadsheets, presentations and other types of files. The document extension depends on the document type: odt for text documents, odp for presentations and so on. Open Document Format files are compressed archives of several files and folders which can be decompressed using standard tools such as \texttt{unzip}, \texttt{jar} or \texttt{WinZip}. Some resources for the format are:
\begin{itemize}
\item The format specification (OASIS, 2005)
\item "Introduction to the format internals" by David Carrera
\item "OASIS OpenDocument Essentials -- Using OASIS OpenDocument XML" by J. David Eisenberg
\end{itemize}

A typical document will have a structure similar to:
\begin{Verbatim}[samepage=true]
 Name
 ----
 content.xml
 layout-cache
 META-INF/
 META-INF/manifest.xml
 meta.xml
 mimetype
 Pictures/
 Pictures/rplot.png
 settings.xml
 styles.xml
 Thumbnails/
 Thumbnails/thumbnail.png
\end{Verbatim}

There are sub--directories in the archive:
\begin{itemize}
\item {\bf \tt META-INF/} contains manifest.xml, which enumerates the entries in the compressed archive
\item {\bf \tt Pictures/} contains any image files that are included in the document. 
\item {\bf \tt Thumbnails} has images of the rendered document.
\end{itemize}

Additionally, the files contained in the compressed archive include:
\begin{itemize}
\item {\bf \tt content.xml} contains the content of the document (e.g. text paragraphs, tables, etc.)and some formatting.
\item {\bf \tt meta.xml} contains summary information about the document, such as creation date, number of edits, document statistics (e.g. number of words, etc) and the identification of the application that generated the document.
\item {\bf \tt settings.xml} lists the configuration of the document, such as the zoom when opened or printing options.
\item {\bf \tt styles.xml} has formatting information for almost all of the elements in the document, such as fonts or table formatting.
\end{itemize}

Since ODF is based on XML, the underlying markup tends to be very verbose. For example, the in--line \texttt{Sweave} expression:
\begin{quote}
{\tt \footnotesize
$\backslash$Sexpr\{paste(letters[1:5],   collapse = \textcolor{red}{"},\textcolor{red}{"})\}
}
\end{quote}
produces the following markup in \texttt{content.xml}:
\begin{quote}
{\tt \footnotesize
<text:p text:style-name="SomeStyleDef">

  $\backslash$Sexpr\{paste(letters[1:5], \textcolor{red}{<text:s text:c="2"/>}collapse = \textcolor{red}{\&quot;},\textcolor{red}{\&quot;})\} 
  
</text:p>
}
\end{quote}
Code chunks yield similar formatting:
\begin{quote}
{\tt \footnotesize
\textcolor{red}{<<}figureTest2,fig = TRUE,echo=FALSE,results=hide\textcolor{red}{>>}=

library(lattice)

out \textcolor{red}{<}- densityplot(~randomData, adjust = 1.5)

print(out)

@
}
\end{quote}
The resulting markup in \texttt{content.xml} would look like:
\begin{quote}
{\tt \footnotesize
<text:p>\textcolor{red}{\&lt;\&lt;}figureTest2,fig = TRUE,echo=FALSE,results=hide\textcolor{red}{\&gt;\&gt;}=</text:p>

<text:p>library(lattice)</text:p>

<text:p>out \textcolor{red}{\&lt;}- densityplot(~randomData, adjust = 1.5)</text:p>

<text:p>print(out)</text:p>

<text:p>@</text:p>}
\end{quote}

A significant portion of the \texttt{odfWeave} code base is for pre--processing the XML files so that they can be passed to the \texttt{Sweave} function in conjunction with a custom ODF driver. All R code written in ODF documents will be encased in XML tags, which isn't an issue for in--line commands, but these must be stripped for code chunks. Also, several characters ("\texttt{>}", "\texttt{<}", "\texttt{\&}", single quotes and double quotes) are automatically converted to alternative representations ("\texttt{\&gt}", "\texttt{\&lt}", "\texttt{\&amp}", "\texttt{\&apos}" and "\texttt{\&quot}"). Also, two or more consecutive spaces are represented using XML tags. One additional complication arises from the automatic character conversion features of some editors. For example, minus signs ("-") are sometimes converted to long dashes ("--"). These characters must be caught and converted before they are sent to the R parser. 


Given the structure of an ODF file, \texttt{odfWeave} must decompress the file, pre--process the XML files, Sweave and then re--compress the archive. 


\section{Using odfWeave}

The functionality of \texttt{Sweave} is mostly preserved in \texttt{odfWeave}, such as weaving, hooks, figure environments, etc. Some functionality, such as writing output to separate files for each code chunk using the \texttt{split} argument, doesn't make sense when using ODF. As another example, ODF supports a broad range of image formats, so \texttt{pdf} or \texttt{eps} arguments to code chunks are somewhat limiting.

In--line \texttt{Sweave} expressions are created using \verb|\Sexpr|. Code chunks can be created with the noweb convention (using \verb|<<>>=|). The \LaTeX{} code chunk syntax is not currently supported.

The image format and sizes are specified using \texttt{getImageDefs} and \texttt{setImageDefs}. For example:
\begin{Verbatim}[samepage=true]
> getImageDefs()
$type
[1] "png"

$device
[1] "png"

$plotHeight
[1] 480

$plotWidth
[1] 480

$dispHeight
[1] 5

$dispWidth
[1] 5

$args
list()
\end{Verbatim}

This shows that the type of image to generate is "png" via the \texttt{png} device driver. The \texttt{plotHeight} and \texttt{plotWidth} values are set in the units of the particular device driver (pixels in this case, but other devices use inches). The dimensions of the image file and the dimensions of the rendered image can be set independently using \texttt{dispHeight} and \texttt{dispWidth} (always in inches). The \texttt{args} element is a list of graphics device arguments. For example, when using postscript graphics, you might need to use the options \texttt{horizontal = FALSE}, \texttt{onefile = FALSE} and \texttt{paper = "special"}.

To change the defaults, this list can be saved and edited. The modified version can be used via \texttt{setImageDefs(modObject)}, where \texttt{modObject} is a modified version of the above list. This can be done prior to calling \texttt{odfWeave} or can be set in--between figure code chunks.


The \texttt{odfTable} class can be used to convert vectors, matrices and data frames to native ODF tables, much like the \texttt{latex} function in the \texttt{Hmisc} package. The \texttt{odfCat} can be used to write out text in native ODF format. There are also functions to created bulleted lists and inserting external images (i.e. images not created in a chunk with \texttt{fig = TRUE}). 

Figure \ref{figure:before} shows an example text document prior to weaving. For illustrative purposes, we might want to adjust the display size of the image to a 4.5 inch square. The R code to do this is:
\begin{verbatim}
library(odfWeave)
inFile <- "example.odt"
outFile <- "out.odt"

imageDefs <- getImageDefs()
imageDefs$dispWidth <- 4.5
imageDefs$dispHeight<- 4.5
setImageDefs(imageDefs)

odfWeave(inFile, outFile)
\end{verbatim}
Figure \ref{figure:after} shows the results. Note that since the first in--line \texttt{Sexpr} command had uniform formatting, the output of that command retained the formatting. In general, the formatting of in--line \texttt{Sweave} tags and code chunks is required to be uniform (as an error is likely to be produced otherwise). For example,  \texttt{round({\it sqrt(2)}, 2)}, ends up looking like
      
      {\center \small \verb+<text:p>round(<text:span text:style-name="T10">sqrt(2)</text:span>, 2)</text:p>+}
      
\noindent and can be difficult to process and parse.

One additional note about this example: the initial code chunk that loads the data does not specify the full path to the file. In this example, the source data were previously zipped into the ODF file (using \texttt{zip example.odt pcrData.csv}) so that the source data are embedded with the analysis and report. Once the file is processed using \texttt{odfWeave}, the resulting document also contains the source data in its original form. 


\begin{figure}[p]
% displayed in oo at 90%
\begin{center}
\framebox{\includegraphics[clip, width=0.85\textwidth]{RnewsExample}}
\end{center}
\caption{\label{figure:before}
An example of an ODF document containing \texttt{Sweave} tags.}
\end{figure}


\begin{figure}[p]
% displayed in oo at 90%
\begin{center}
\framebox{\includegraphics[clip, width=0.85\textwidth]{RnewsOut}}
\end{center}
\caption{\label{figure:after}
The processed ODF document.}
\end{figure}


\section{Formatting}

There are two main components to specifying output formats: style definitions and style assignments. The definition has the specific components (such as a table cell) and their format values (e.g. boxed with solid black lines). The function \texttt{getStyleDefs} can fetch the pre--existing styles in the package. For example:
<<getStyleDefs>>=
getStyleDefs()$ArialNormal
@


These can be modified and new definitions can be added. The function \texttt{setStyledefs} "registers" the style changes with the package. When \odfWeaveFunc is called, these definitions are written to the style sections of the XML files. There is a second mechanism to assign styles to specific output elements. The functions \texttt{getStyles} and \texttt{setStyles} can be used to tell odfWeave which style definition to use for a particular output:

<<getStyleDefs, print = TRUE>>=
currentStyles <- getStyles()
@

For example, the \texttt{input} and \texttt{output} elements control how R code and command--line output look. To change either of these, an existing definition can be assigned to these entries and reset using \verb|setStyles(currentStyles)|. Unlike the style definitions, the style assignments can be modified throughout the R code. 

The package also contains a function, \texttt{tableStyles}, that can be used to differentially format specific cells and text in tables.

\section{Other Functions} 

There are a few miscellaneous functions also included in the package. \texttt{pkgVersions} can create a summary of the packages and versions in the search path:
<<pkgVersions, print = TRUE>>=
 pkgVersions("matrix", ncol = 3)
@
The function \texttt{listString} takes a vector and returns a textual list. For example,  \verb|letters[1:4]| would become "\Sexpr{listString(letters[1:4])}". Also, \texttt{matrixPaste} can take a series of character matrices with the same dimensions and perform an element--wise paste.

\section{Converting ODF to Other Formats}

Using OpenOffice, ODF files can be manually converted to other formats using the  "Save As" or "Export" items in the File menu. To convert documents using a command line interface, there are at least two options:
\begin{itemize}
\item on platforms with the Bash shell, Nathan Coulter has written a script that uses the Python internals that are installed with OpenOffice, called ooconvert. This can be found at \linebreak \href{http://sourceforge.net/projects/ooconvert} {http://sourceforge.net/projects/ooconvert}.
\item there is a Java class, called  JOOConverter, that is available at \href{http://jooreports.sourceforge.net/} {http://jooreports.sourceforge.net/} that can also convert documents.
\end{itemize}.



\section{References}

\begin{description}
\item Carrera, D. (2005). {\em Introduction to the format internals}.  URL:   \href{http://opendocumentfellowship.org/Articles/IntroductionToTheFormatInternals} {http://opendocumentfellowship.org/ Articles/IntroductionToTheFormatInternals}.

\item Eisenberg, J. D. (2005). {\em OASIS OpenDocument Essentials -- Using OASIS OpenDocument XML}. URL: \href{http://books.evc-cit.info/} {http://books.evc-cit.info/}.

\item Leisch, F. (2002). {\em Sweave, Part I: Mixing R and \LaTeX{}}. R News, 2(3):28--31. URL: \href{http://cran.r-project.org/doc/Rnews} {http://cran.r-project.org/doc/Rnews}.

\item Organization for the Advancement of Structured Information Standards (OASIS) (2005). {\em Open Document Format for Office Applications (OpenDocument)} v1.0. URL: \href{http://www.oasis-open.org/committees/download.php/12572/OpenDocument-v1.0-os.pdf} {http://www.oasis-open.org/committees/download.php/12572/OpenDocument-v1.0-os.pdf}

\end{description}

\end{document}
