\documentclass[a4paper]{article}
%\VignetteIndexEntry{Persistent representations}
%\VignettePackage{grid}
\newcommand{\grid}{{\tt grid}}
\newcommand{\R}{{\tt R}}
\setlength{\parindent}{0in}
\setlength{\parskip}{.1in}
\setlength{\textwidth}{140mm}
\setlength{\oddsidemargin}{10mm}
\title{Saving and Loading \grid{} Graphics}
\author{Paul Murrell}

\begin{document}
\maketitle

<<echo=FALSE, results=hide>>=
library(graphics)
library(grid)
ps.options(pointsize=12)
options(width=60)

@
This is a general discussion concerning how you might go about 
creating (and reusing) persistent representations of \grid{} 
graphics, and some of the pitfalls in the various options.

\subsection*{\R{} code}

The way I usually work with graphics is to write \R{} code in a text file
and copy-and-paste or {\tt source()} it into R.  In this case,
the presistent
representation of the graphics is the raw \R{} code.

The representation is fully editable.

The representation is persistent across \R{} sessions, but may not be
persistent across \R{} versions because the names, argument lists,
and/or behaviour of the \grid{} functions may
change.  The representation can be reloaded into R.
Incompatibilities between versions should be handled gracefully by
\R{}'s argument-matching, type-checking, and/or version-checking.

\subsection*{Device output}

Another way of creating a persistent version of \grid{} graphics is to
``save'' it to a persistent device format (e.g., PostScript, PDF, ...).

It is possible to edit this representation, but hardly convenient.

The representation is persistent regardless of \R{} sessions or versions,
but it cannot be reloaded into \R{}.

\subsection*{Display lists}

A third way of creating a persistent version of \grid{} graphics is to
``save'' an \R{} display list using, for example, ...

<<fig=true, include=false, label=grid>>=
grid.grill()
temp <- recordPlot()
save(temp, file="mygridplot")

@
This representation is not editable\footnote{Well, there's nothing stopping
you editing it, but you should take out life insurance first.  Display
lists may become sensibly editable in the future.}, but it can be
reloaded ...

<<>>=
load("mygridplot")
temp

@
... and rerun to reproduce the output.

\includegraphics{saveload-grid}

The representation is persistent across \R{} sessions (although you have
to make sure that \grid{} has been reloaded).  Differences between
\grid{} versions may lead to segmentation faults if the API of the \grid{}
code being called by the display list has changed sufficiently.

\subsection*{\grid{} {\tt grob}s}

Yet another way of creating a persistent version
of \grid{} graphics is to {\tt save()} a \grid{} {\tt grob} ...

<<>>=
gt <- textGrob("hi")
save(gt, file="mygridplot")

@
The representation is reloadable so you can reproduce an image ...

<<results=hide>>=
load("mygridplot")
grid.draw(gt)

@
And the representation is editable;  there is an API for interacting
with \grid{} {\tt grobs}, including adding new elements, removing 
elements, editing features of a {\tt grob} and so on.  See 
{\tt getGrob()}, {\tt addGrob()}, {\tt removeGrob()},
and {\tt editGrob()}.

The representation is persistent across \R{} sessions, but is 
vulnerable to changes in the internal representation of \grid{}
{\tt grob}s.  The advantage of this representation is that it is 
possible to share and edit graphics produced by someone else,
without seeing the code they used to produce it.

\end{document}