From 89135e7e1b6a211b066867735c41e9a1a4310c5f Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sun, 10 Mar 2013 22:38:10 +0000
Subject: pst2pdf (10mar13)

git-svn-id: svn://tug.org/texlive/trunk@29333 c570f23f-e606-0410-a88d-b1316a301751
---
 .../texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex   | 238 ++++++++++++---------
 1 file changed, 135 insertions(+), 103 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex')

diff --git a/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex b/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
index c0b893bc843..238bf937673 100644
--- a/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
+++ b/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
@@ -1,8 +1,8 @@
-%% $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}
+\documentclass[10pt,english,BCOR10mm,DIV12,bibliography=totoc,parskip=false,smallheadings
+    headexclude,footexclude,oneside]{pst-doc}
 \usepackage[utf8]{inputenc}
-\usepackage{pst-text,pst-grad,pst-exa}
+\RequirePackage{xspace}
+\usepackage{pst-text,pst-grad}
 \let\pstFV\fileversion
 \DeclareFixedFont{\RM}{T1}{ptm}{b}{n}{4cm}
 \renewcommand\bgImage{\pscharpath[fillstyle=gradient,
@@ -16,8 +16,8 @@
 \begin{document}
 
 \title{\texttt{pst2pdf}}
-\subtitle{Running a PSTricks document with pdflatex;\\  \small v. 0.13}
-\author{Herbert Vo\ss  \\ Pablo Gonzales Luengo}
+\subtitle{Running a PSTricks document with pdflatex;\\  \small v. 0.14}
+\author{Herbert Vo\ss  \\ Pablo Gonz\'{a}lez Luengo}
 \docauthor{}
 \date{\today}
 \maketitle
@@ -26,131 +26,163 @@
 
 \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.
+%\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
+%\vfill\noindent
+%Thanks to: 
+%Rolf Niepraschk
 
-\end{abstract}
+%\end{abstract}
+
+%\clearpage
 
-\clearpage
 
 \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
+\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 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}
+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. 
 
-The options listed in Table~\ref{perloptions} refer only to the script and not the \LaTeX\ file.
+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.
 
-\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\\
-\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}
+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.
 
-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{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}).
 
-\section{\PST\ code}
-The per scripts scans the files for \Lenv{pspicture} and \Lenv{postscript} environments,
+\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:
 
-\bgroup
-\raggedright
-\nocite{*}
-\bibliographystyle{plain}
-\bibliography{pst2pdf-doc}
-\egroup
-
-\printindex
+\begin{BDef}
+\nxLprog{perl} \nxLprog{pst2pdf} \Larg{file.tex} \OptArg*{--options}
+\end{BDef}
 
+For \TeX Live users:
 
-\end{document}
+\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}
 
-\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}.
+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}).
 
-The package provides the environment \Lenv{PSTexample} with the optional
-arguments listed in Table~\ref{pst-exaoptions}.
+\section{Options}
+\label{options}
+The options listed in Table~\ref{perloptions} refer only to the \emph{script} and not the \LaTeX\ file.
 
-\begin{table}
-\caption{Possible optional arguments for the package \LPack{pst-exa}}\label{pst-exaoptions}
-\begin{tabularx}{\linewidth}{@{} l l l X @{}}\\\toprule
+\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
-\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.\\
-\Lkeyword{imageDir} & literal   &images/    & directory for the created images and tex files.\\\bottomrule
+\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:\\
 
-
-
-
-\section{Examples}
-The package contains some example files for running 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}
-
-%\section{List of all optional arguments for \texttt{pst-exa}}
-%
-%\xkvview{family=pst-exa,columns={key,type,default}}
-
-
-
+\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}
-- 
cgit v1.2.3

