summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex238
1 files changed, 135 insertions, 103 deletions
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}