diff options
author | Karl Berry <karl@freefriends.org> | 2013-03-10 22:38:10 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-03-10 22:38:10 +0000 |
commit | 89135e7e1b6a211b066867735c41e9a1a4310c5f (patch) | |
tree | 2196faea0cf74bd49d034d56443ae7644a638c35 /Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex | |
parent | 6380d0315e1132891b4735999c26b0a41e6d1aaa (diff) |
pst2pdf (10mar13)
git-svn-id: svn://tug.org/texlive/trunk@29333 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex | 238 |
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} |