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.tex146
1 files changed, 146 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex b/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
new file mode 100644
index 00000000000..c201a359881
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/pst2pdf/pst2pdf-doc.tex
@@ -0,0 +1,146 @@
+%% $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}
+
+