%% $Id: pst-func-doc.tex 245 2010-01-04 17:07:30Z herbert $
\documentclass[11pt,english,BCOR10mm,DIV12,bibliography=totoc,parskip=false,
   smallheadings, headexclude,footexclude,oneside]{pst-doc}
\usepackage[utf8]{inputenc}
\usepackage{pst-exa,pst-text,pst-grad}
\let\pstFV\fileversion
\DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{4cm}
\renewcommand\bgImage{\pscharpath[fillstyle=gradient,
  gradbegin=red,gradend=blue,gradangle=-90]{\RM pst2pdf}}

\lstset{language=PSTricks,basicstyle=\footnotesize\ttfamily}
\def\DVI{\textsc{DVI}}
\def\PDF{\textsc{PDF}}
\def\gs{\textsc{Ghostscript}}
%
\begin{document}

\title{\texttt{pst2pdf}}
\subtitle{Running a PSTricks document with pdflatex and \nxLPack{pst-exa}; v.\pstFV}
\author{Herbert Vo\ss}
\docauthor{}
\date{\today}
\maketitle

\tableofcontents

\clearpage

\begin{abstract}
\noindent
\Lprog{pst2pdf} is a Perl script for running a PSTricks document in a last run
with pdflatex. \LPack{pst-exa} is a package that supports the printing of
code and output of PSTricks examples when running in pdf mode.

\vfill\noindent
Thanks to: \\
Rolf Nirpraschk

\end{abstract}


\section{Introduction}
\PST as \PS-related package uses the programming language \PS for internal
calculations. This is an important adavantage, because floating point arithmetic is no
problem. Nearly all mathematical calculation can be done when running the \DVI-file
with \gs. However, creating a \PDF file in a direct way with \Lprog{pdflatex} is
not possible. \Lprog{pdflatex} cannot understand the \PS related stuff. Instead
of running \Lprog{pdflatex} one can use the Perl script \Lprog{pdf2eps}, it extracts
all \PST-related code into single documents with the same preamble as the original
main document. Then the script runs this document, clips all whitespace arounf the
image and creates a \Lext{pdf}, \Lext{eps}, and \Lext{png} image of the \PST 
related code. In a last run which is the \Lprog{pdflatex} the \PST code in the
main dcouemnt is replaced by the created images.

\section{Running the Perl script}
The genral syntax for the Perl script is simple

\begin{BDef}
\Lprog{pst2pdf} \Larg{file}\OptArg*{\Lext{tex}} \OptArg*{options}
\end{BDef}

The options listed in Table~\ref{perloptions} refer only to the script and not the \LaTeX\ file.

\begin{table}
\caption{Possible optional arguments for the Perl script \nxLprog{pst2pdf}}\label{perloptions}
\begin{tabularx}{\linewidth}{@{} l l >{\ttfamily}l X @{}}\\\toprule
\emph{name} & \emph{values} & \textrm{\emph{default}} & \emph{description}\\\midrule
\Loption{--imageDir} & literal & imgages/ & the directory for the created images\\
\Loption{--Iext}     & literal & .pdf     & the extension for \Lcs{includegraphics}, can be empty, then
    \Lcs{includegraphics} decides which image is used.\\  
\Loption{--DPI}      & integer & 75       & the dots per inch for a created png file, if possible\\
\Loption{--Iscale}   & real    & 1        & the value for the option \Loption{scale} in \Lcs{includegraphics}.
	Important when using a greater dpi value.\\ 
\Loption{--tempDir}  & literal & .        & the temporary directory for the temp files\\
\Loption{--verbose}  & boolean & 1        & for a long \Lprog{pst2pdf} log\\
\Loption{--clear}    & boolean & 0        & delete all temporary files\\
\Loption{--noImages} & boolean & 0        & create no images, build only the pdf with the alread existing images\\\bottomrule
\end{tabularx}
\end{table}

After the \Lprog{pst2pdf} run there exists a pdf file called \texttt{\Lcs{jobname}-pdf.pdf}. And when not using
the \Loption{--clear} option also the corresponding \TeX{} file \texttt{\Lcs{jobname}-pdf.tex}.
The preamble of the document should contain all code which is important to the \PST code.

\section{\PST code}
The per scripts scans the files for \Lenv{pspicture} and \Lenv{postscript} environments,
which are then taken with its contents from the main file to create stand alone documents
with the same preamble as the main document. The \Lenv{pspicture} environment can be nested,
the \Lenv{postscript} one not! But it can contain an environment \Lenv{pspicture}, but not vice versa.
The \Lenv{postscript} environment should always be used, when there is some code before a \Lenv{pspicture}
environment or for some code which is not inside of a \Lenv{pspicture} environment.

\section{The package \nxLPack{pst-exa}}
The package \LPack{pst-exa} was created to realize examples with printed code and output
side by side or on top of each other. The package looks in the image directory for the source
code of the examples and inserts only the code between the environment \Lenv{document},
which is the sequence \LBEG{document} \ldots\ \LEND{document}.

The package provides the environment \Lenv{PSTexample} with the optional
arguments listed in Table~\ref{pst-exaoptions}.

\begin{table}
\caption{Possible optional arguments for the Perl script \nxLprog{pst2pdf}}\label{pst-exaoptions}
\begin{tabularx}{\linewidth}{@{} l l l X @{}}\\\toprule
\emph{name} & \emph{values} & \textrm{\emph{default}} & \emph{description}\\\midrule
\Lkeyword{pos}    & \Lkeyval{l},\Lkeyval{r},\Lkeyval{b},\Lkeyval{t} & \Lkeyval{l} & position of the image, maybe left, right, bottom ot top of the code.\\
\Lkeyword{halign} & \Lkeyval{l},\Lkeyval{r},\Lkeyval{c}   & \Lkeyval{c} & the horizontal alignment of the image.\\  
\Lkeyword{valign} & \Lkeyval{l},\Lkeyval{r},\Lkeyval{c}   & \Lkeyval{c} & the vertical alignment of the image.\\
\Lkeyword{frame}  & see lst  &  & option is passed to \Lcs{lstinputlisting} from the package \LPack{listings}.\\ 
\Lkeyword{width}  & length   &0.5\Ldim{linewidth}  & the width of the example box.\\
\Lkeyword{sep}    & length   &1em        & separation between image and code.\\\bottomrule
\end{tabularx}
\end{table}

\section{Examples}
The package contains some example files for uning the script without and
with the package \LPack{pst-exa}.

\begin{compactdesc}
\item[test1.tex] running \verb=pst2pdf test1=. The test file contains a jpg-image, which is only possible with pdflatex.
\item[test2.tex] same as \LFile{test1}, but with using \LPack{pst-exa} and example--code combination.
\item[test3.tex] another example 
\end{compactdesc}

\clearpage
\section{List of all optional arguments for \texttt{pst-exa}}

\xkvview{family=pst-exa,columns={key,type,default}}




\bgroup
\raggedright
\nocite{*}
\bibliographystyle{plain}
\bibliography{pst2pdf-doc}
\egroup

\printindex



\end{document}