\documentclass[10pt,english,BCOR10mm,DIV12,bibliography=totoc,parskip=false,smallheadings
    headexclude,footexclude,oneside]{pst-doc}
\usepackage[utf8]{inputenc}
\RequirePackage{xspace}
\usepackage{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;\\  \small v. 0.14}
\author{Herbert Vo\ss  \\ Pablo Gonz\'{a}lez Luengo}
\docauthor{}
\date{\today}
\maketitle

\tableofcontents

\clearpage

%\begin{abstract}
%\noindent
%\Lprog{pst2pdf} is a \Lprog{perl} \emph{script} for running a PSTricks document in a last run
%with pdflatex. 

%\vfill\noindent
%Thanks to: 
%Rolf Niepraschk

%\end{abstract}

%\clearpage


\section{Introduction}
\PST\ as \PS\ related package uses the programming language \PS\ for internal
calculations. This is an important advantage, 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 \Lprog{perl} \emph{script} \Lprog{pst2pdf}, it extracts
all \PST\ related code into single documents with the same preamble as the original
main document.

The \nxLprog{pst2pdf} \emph{script} runs document, clips all whitespace around the
image and creates a \Lext{pdf} (and \Lext{eps},\Lext{ppm}) image of the \PST\ 
related code. In a last run which is the \Lprog{pdflatex} the \PST\ code in the
main document is replaced by the created images.

\section{Requirements}
\subsection{Programs needed}
\nxLprog{pst2pdf} needs \Lprog{pdftk}, \Lprog{ImageMagick} and \Lprog{poppler-utils} (or \Lprog{xpdf-utils}) for the process file in usual way. If you need a create .pdf image files (whitout related software) use single mode (see \ref{single}).

\subsection{Preparating file}
The script scan the file 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.

Put all related \PST\ package in separate lines in your preamble, \nxLprog{pst2pdf} delete al lines contains \PST\ package before last run.

This is an example of environments that support for \nxLprog{pst2pdf}:

\vspace{10pt}
\begin{minipage}[c]{0.25\textwidth}
\begin{verbatim}
\pspicture*
\psset{...}
pstricks code	
\endpspicture
\end{verbatim}
\end{minipage}
\begin{minipage}[c]{0.25\textwidth}
\begin{verbatim}
\begin{pspicture}
\psset{...}
pstricks code	
\end{pspicture}
\end{verbatim}
\end{minipage}
\begin{minipage}[c]{0.25\textwidth}
\begin{verbatim}
\begin{pspicture*}
\psset{...}
pstricks code	
\end{pspicture*}
\end{verbatim}
\end{minipage}
\begin{minipage}[c]{0.25\textwidth}
\begin{verbatim}
\begin{postscript}
\psset{...}
pstricks code	
\end{postscript}
\end{verbatim}
\end{minipage}

\section{Running the script}
\subsection{Default mode}
The general syntax for the \Lprog{perl} \emph{script} is simple:

\begin{BDef}
\nxLprog{perl} \nxLprog{pst2pdf} \Larg{file.tex} \OptArg*{--options}
\end{BDef}

For \TeX Live users:

\begin{BDef}
\nxLprog{pst2pdf} \Larg{file.tex} \OptArg*{--options}
\end{BDef}

\subsection{Single mode}
\label{single}
If \nxLprog{pst2pdf} can not process a file, used the option \Loption{--single} this process will create the file, whiout pdftk 
(take a more time to create images files) by default create PDF files. For exampple:

\begin{BDef}
\nxLprog{pst2pdf} \Larg{file.tex} \OptArg*{--pdf} \OptArg*{--single}
\end{BDef}

create file-pdf.pdf and file-pst-1.pdf, file-pst-2.pdf, file-pst-\dots.pdf for all \Lenv{pspicture} and \Lenv{postscript} environments in the directory for the created images (see \ref{options}).

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

\begin{table}[htp]
\caption{Optional arguments for \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 & images/  & the directory for the created images.\\
\Loption{--Iext}     & literal & .pdf     & the extension for \Loption{PrependGraphicsExtensions}.\\  
\Loption{--DPI}      & integer & 75       & the dots per inch for a created \Lext{ppm} file.\\
\Loption{--Iscale}   & real    & 1        & the value for the option \Loption{scale} in \Lcs{includegraphics}.\\ 
\Loption{--eps}      & boolean & 0        & creates \Lext{eps} images files (need pdftops).\\
\Loption{--ppm}      & boolean & 0        & creates \Lext{ppm} images files (need pdftoppm).\\
\Loption{--files}    & boolean & 0        & creates \Lext{tex} for all images.\\
\Loption{--verbose}  & boolean & 1        & for a long \nxLprog{pst2pdf} log.\\
\Loption{--norun}    & boolean & 0        & create files, but no compile.\\
\Loption{--clear}    & boolean & 0        & delete all temporary files.\\
\Loption{--help}     & boolean & 1        & print help and exit.\\
\Loption{--single}   & boolean & 0        & create images type (whitout pdftk).\\
\Loption{--all}      & boolean & 0        & generte all image type (.pdf, .eps, .tex).\\
\Loption{--version}  & boolean & 0        & print version and exit.\\
\Loption{--license}  & boolean & 0        & print license and exit.\\
\Loption{--xetex}    & boolean & 0        & using \Lprog{xelatex} instead of \Lprog{latex} for the process.\\
\Loption{--noImages} & boolean & 0        & generate files but no images (need \Loption{--norun}).\\
\Loption{--runBibTeX}& boolean & 0        & runs \Lprog{bibtex} \\
\Loption{--runBiber} & boolean & 0        & runs \Lprog{biber} if a file with extension \Lext{bcf} exists \\\bottomrule
\end{tabularx}
\end{table}

For Help in command line use:

\begin{BDef}
\nxLprog{pst2pdf} \OptArg*{--help}
\end{BDef}

\section{Other image format}
If your need \Lext{png}, \Lext{jpg} or other image type use \nxLprog{pst2pdf} \Larg{file.tex} \OptArg*{--ppm} , than move to images dir and use \nxLprog{mogrify} command (from \Lprog{ImageMagick}), for examples:\\

\begin{BDef} 
\nxLprog{mogrify} -format \OptArg*{png *.ppm} 
\end{BDef}
generate PNG images files and \\
\begin{BDef} 
\nxLprog{mogrify} -format \OptArg*{jpg *.ppm} 
\end{BDef} 
generate JPG images files.
\bgroup
\raggedright
\nocite{*}
\bibliographystyle{plain}
\bibliography{pst2pdf-doc}
\egroup
\printindex
\end{document}
