\documentclass[english,a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

\newcommand{\Anchor}[1]{\hypertarget{#1}{}}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarks=true,bookmarksopen=true,bookmarksnumbered=true]{hyperref}
}{}

%% do we have the fancyhdr package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
%% do we have the fancyheadings package?
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

\input{version.tex}

\setlength{\emergencystretch}{1.5em}

%%\usepackage{url}
%%\let\URL\url \let\Email\url \let\File\url

\hyphenation{Ghost-script}

\begin{document}

\begin{Name}{1}{pstoedit}{Dr.\ Wolfgang Glunz}{Conversion Tools}{PSTOEDIT}
  \Prog{pstoedit} - a tool converting PostScript files into various
  vector graphic formats
\end{Name}

\section{Synopsis}
%%%%%%%%%%%%%%%%%%

\subsection{From a command shell}

\Prog{pstoedit} \oOpt{-v -help}
\\

\Prog{pstoedit}
\input{generalhelpshort.tex}

\Anchor{GUI}
\subsection{From PstoeditQtGui}

\Prog{PstoeditQtGui} provides an alternative to the command driven operation.
The GUI provides access to almost all options and features that are supported by \Prog{pstoedit}.
In addition it supports the conversion of multiple files in one job and also provides some 
shortcuts to some of \Prog{Ghostscript}'s high level output devices.

The GUI is implemented using QT (\URL{https://www.qt.io}).

The various options provided by \Prog{pstoedit} are displayed in different tabs in the GUI according to their category.
A link to a more detailed description of each option into this manual is provided with each option in the GUI.

Side note: None of the options are "hard coded" into the GUI. Instead the meta information is retrieved from \Prog{pstoedit} itself.
By this the GUI is always up to date with respect to the options and formats provided by \Prog{pstoedit}.

\section{Description}
%%%%%%%%%%%%%%%%%%%%%

\subsection{RELEASE LEVEL}

This man-page documents release \Version\ of \Prog{pstoedit}.

\subsection{USE}

\Prog{pstoedit} converts PostScript files into various vector graphics
formats. The resulting files can be edited or imported into various drawing
packages. Type

     \textbf{pstoedit -help}

\noindent for a list of supported output formats. Pstoedit comes with a
large set of format drivers built into in the binary. 

\subsection{PRINCIPLE OF CONVERSION}

\Prog{pstoedit} works by redefining some of PostScript's basic drawing operators,
such as \textbf{stroke} or \textbf{show} (bitmaps drawn by the image
operator are not supported by all output formats.) After
redefining these operators, the PostScript file that needs to be
converted is processed by a PostScript interpreter, e.g., Ghostscript
(\Cmd{gs}{1}). You normally need to have a PostScript interpreter installed in
order to use this program. However, you can perform some "back end only" processing
of files following the conventions of the pstoedit intermediate format by specifying the \Opt{-bo} option. See "Available formats and their specific options" below.

The output that is written by the interpreter due to the redefinition of the
drawing operators is a kind of 'flat' PostScript file containing only simple
operations such as moveto, lineto, show, etc. You can view this file using the
\Opt{-f debug} option.

This output is read by the end-processing functions of \Prog{pstoedit} and triggers
the drawing functions in the selected output format driver sometimes called also "back-end".

\subsection{NOTES ON GHOSTSCRIPT}

Although pstoedit was designed to allow the use of any kind of PostScript interpreter, it 
has only been tested in combination with \Prog{Ghostscript} 
(\URL{https://ghostscript.com}).

Up to version 9.55 of \Prog{Ghostscript}, it's PDF interpreter was implemented in PostScript itself.
That allowed \Prog{pstoedit} to handle PDF files in the same way as PostScript files since the same 
mechanisms for intercepting the drawing operations could be used.

However, from version 9.56 on, the PDF interpreter of \Prog{Ghostscript} was implemented in C and 
hence the interceptions used by pstoedit are no longer effective when processing PDF files.

You need to convert the PDF to PostScript at first before you can convert it into another format.
You can use \Prog{Ghostscript} for that or also use the gs:ps2write (\Opt{-f gs:ps2write}) driver from \Prog{pstoedit}.

\section{Options}

\input{generalhelplong.tex}


If neither an input nor an output file is given as argument, pstoedit works as filter reading from standard input and
writing to standard output.
The special filename "-" can also be used. It represents standard input if it is the first on the command line and standard output if it is the second. So "pstoedit - output.xxx" reads from standard input and writes to output.xxx


\section{Available formats and their specific options}

\Prog{pstoedit} allows passing individual options to an output format driver. This is done by
appending all options to the format specified after the \Opt{-f} option. The format
specifier and its options must be separated by a colon (:). If more than one
option needs to be passed to the output format driver, the whole argument to \Opt{-f} must be
enclosed within double-quote characters, thus:

\OptArg{-f}{~"format[:option option ...]"}

To see which options are supported by a specific format, type:
     \textbf{pstoedit -f format:-help}
     \\

The following description of the different formats supported by pstoedit is extracted from the source code of the individual drivers.

\input{driverhelp.tex}

\section{NOTES ON SPECIFIC FORMATS AND DRIVERS}
  \subsection{autotrace}
    pstoedit cooperates with autotrace. Autotrace can now produce a dump file
    for further processing by pstoedit using the \Opt{-bo} (back-end only) option.
    Autotrace is a program written by a group around Martin Weber and can be
    found at \URL{https://sourceforge.net/projects/autotrace/}.

  \subsection{Ps2ai}
    The ps2ai output format driver is not a native pstoedit output format driver. It does not use the
    pstoedit PostScript flattener, instead it uses the PostScript program
    ps2ai.ps which is installed in the Ghostscript distribution directory. It
    is included to provide the same "look-and-feel" for the conversion to AI.
    However, lot's of files do not
    convert nicely or at all using ps2ai.ps. So a native pstoedit driver would
    be much better. Anyone out there to take this? The AI format is usable for
    example by Mayura Draw (\URL{http://www.mayura.com}). Also a driver to the
    Mayura native format would be nice.

    An alternative to the ps2ai based driver is available via the -f plot:ai format if the libplot(ter) is installed.

    You should use a version of Ghostscript greater than or equal to 6.00 for using the ps2ai output format driver.


  \subsection{MetaPost}
    Note that, as far as Scott knows, MetaPost does not support PostScript's
    eofill. The MetaPost output format driver just converts eofill to fill, and issues a warning if
    verbose is set. Fortunately, very few PostScript programs rely on the
    even-odd fill rule, even though many specify it.

    For more on MetaPost see:

    \URL{http://tug.org/metapost}  % \URL{http://cm.bell-labs.com/who/hobby/MetaPost.html}

  \subsection{Context Free - CFDG}
    The driver for the CFDG format (drvcfdg) defines
    one shape per page of PostScript, but only the first shape is actually
    rendered (unless the user edits the generated CFDG code, of course).
    CFDG does not support multi-page output, so this probably is a reasonable thing to do.

    For more on Context Free see: \URL{http://www.contextfreeart.org/}

  \subsection{\LaTeX2e}
    \begin{itemize}
   \item \LaTeX2e's picture environment is not very powerful. As a result, many
     elementary PostScript constructs are ignored -- fills, line
     thicknesses (besides "thick" and "thin"), and dash patterns, to name a
     few. Furthermore, complex pictures may overrun \TeX's\  memory capacity.
     (The eepic package overcomes many such restrictions.)

   \item Some PostScript constructs are not supported directly by "picture",
     but can be handled by external packages. If a figure uses color, the
     top-level document will need to do a \verb+"\usepackage{color}"+ or \verb+"\usepackage{xcolor}"+. And if a
     figure contains rotated text, the top-level document will need to do a
     \verb+"\usepackage{rotating}"+.

   \item All lengths, coordinates, and font sizes output by the output format driver are in
     terms of \verb+\unitlength+, so scaling a figure is simply a matter of doing
     a \verb+"\setlength{\unitlength}{...}"+.

   \item The output format driver currently supports one output format driver specific option,
     "integers", which rounds all lengths, coordinates, and font sizes to
     the nearest integer. This makes hand-editing the picture a little
     nicer.

   \item Why is this output format driver useful? 
     One answer is portability; any \LaTeX2e\ system can handle the picture environment, 
     even if it cannot handle
     PostScript graphics. (pdf\LaTeX\ comes to mind here.) A second answer
     is that pictures can be edited easily to contain any arbitrary 
     \LaTeX2e\  code. For instance, the text in a figure can be modified to contain
     complex mathematics, non-Latin alphabets, bibliographic citations, or
     -- the real reason Scott wrote the \LaTeX2e\ output format driver -- hyperlinks to the
     surrounding document (with help from the hyperref package).
   \end{itemize}


  \subsection{Creating a new output format driver}
    To implement a new output format driver you can start from \File{drvsampl.cpp} and
    \File{drvsampl.h}. See also comments in \File{drvbase.h} and
    \File{drvfuncs.h} for an explanation of methods that should be implemented
    for a new output format driver.


\section{ENVIRONMENT VARIABLES}

A default PostScript interpreter to be called by pstoedit is specified at
compile time. You can overwrite the default by setting the GS environment
variable to the name of a suitable PostScript interpreter.

You can check which name of a PostScript interpreter was compiled into
pstoedit using: \textbf{pstoedit} \Opt{-help -v}.

See the Ghostscript manual for descriptions of environment variables used by
Ghostscript, most importantly \verb+GS_FONTPATH+ and \verb+GS_LIB+; other
environment variables also affect output to display, print, and additional
filtering and processing. See the related documentation.

\Prog{pstoedit} allocates temporary files using the function \Cmd{tempnam}{3}.
Thus the location for temporary files might be controllable by other
environment variables used by this function. See the \Cmd{tempnam}{3} man-page
for descriptions of environment variables used. On UNIX like system this is
probably the \verb+TMPDIR+ variable, on DOS/WINDOWS either \verb+TMP+ or
\verb+TEMP+.

\section{TROUBLE SHOOTING}

If you have problems with \Prog{pstoedit} first try whether Ghostscript
successfully displays your file. If yes, then try
\textbf{pstoedit} \Opt{-f ps} \Arg{infile.ps} \Arg{testfile.ps}
and check whether \Arg{testfile.ps} still displays correctly using
Ghostscript. If this file does not look correctly then there seems to be a
problem with \Prog{pstoedit}'s PostScript front-end. If this file looks good
but the output for a specific format is wrong, the problem is probably in
the output format driver for the specific format. In either case send bug fixes and
reports to the author.

A common problem with PostScript files is that the PostScript file redefines
one of the standard PostScript operators inconsistently. There is no effect
of this if you just print the file since the original PostScript "program"
uses these new operators in the new meaning and does not use the original
ones anymore. However, when run under the control of pstoedit, these
operators are expected to work with the original semantics.

So far I've seen redefinitions for:

\begin{itemize}
   \item lt - "less-then" to mean "draw a line to"
   \item string - "create a string object" to mean "draw a string"
   \item length - "get the length of e.g. a string" to a "float constant"
\end{itemize}

I've included work-arounds for the ones mentioned above, but some others
could show up in addition to those.


\section{RESTRICTIONS}

\begin{itemize}
\item Non-standard fonts (e.g. \TeX\ bitmap fonts) are mapped to a default font which
can be changed using the \Opt{-df} option. \Prog{pstoedit} chooses the size of
the replacement font such that the width of the string in the original font is
the same as with the replacement font. This is done for each text fragment
displayed. Special character encoding support is limited in this case. If a
character cannot be mapped into the target format, pstoedit displays a '\#'
instead. See also the -uchar option.
\item pstoedit supports bitmap graphics only for some output format drivers.
\item Some output format drivers, e.g. the Gnuplot output format driver or the 3D output format driver (rpl, lwo, rib) do not support text.
\item For most output format drivers pstoedit does not support clipping (mainly due to limitations in the target format). You can try to use the
\Opt{-sclip} option to simulate clipping. However, this does not work in all cases as expected.
\item Special note about the Java output format drivers (java1 and java2).
The java output format drivers generate a java source file that needs other files in
order to be compiled and usable. These other files are Java classes (one
applet and support classes) that allow stepping through the individual pages
of a converted PostScript document. This applet can easily be activated from
a HTML-document. See the \File{contrib/java/java1/readme\_java1.txt} or
\File{contrib/java/java2/readme\_java2.htm} files for more details.
\end{itemize}

\section{FAQs}

\begin{enumerate}
\item Why do letters like O or B get strange if converted to TGIF/XFIG
using the \Opt{-dt} option?

Most output format drivers do not support composite paths with
intermediate gaps (moveto's) and second do not support very well the (eo)fill
operators of PostScript (winding rule). For such objects \Prog{pstoedit} breaks
them into smaller objects whenever such a gap is found. This results in the
"hole" being filled with black color instead of being transparent. Since
version 3.11 you can try the \Opt{-ssp} option in combination with the XFIG
output format driver.

\item Why does pstoedit produce ugly results from PostScript files generated by dvips?

This is because \TeX\ documents usually use bitmap fonts. Such fonts cannot be used as native
font in other format. So pstoedit replaces the \TeX\ font with another native
font. Of course, the replacement font will in most cases produce another
look, especially if mathematical symbols are used.
Try to use PostScript fonts instead of the bitmap fonts when generating a PostScript file from \TeX\ or \LaTeX.
\end{enumerate}

\section{AUTHOR}
Wolfgang Glunz, \Email{wglunz35\_AT\_pstoedit.net}, \URL{https://de.linkedin.com/in/wolfgangglunz}

\section{CANONICAL ARCHIVE SITE}
\URL{https://www.pstoedit.com}

At this site you also find more information about \Prog{pstoedit} and related
programs and hints how to subscribe to a mailing list in order to get informed
about new releases and bug-fixes.

If you like pstoedit - please express so also at Facebook \URL{https://www.facebook.com/pstoedit}.

\section{ACKNOWLEDGMENTS}

\begin{itemize}\setlength{\itemsep}{0cm}
  \item Klaus Steinberger \Email{Klaus.Steinberger\_AT\_physik.uni-muenchen.de}
     wrote the initial version of this man-page.
  \item Lar Kaufman revised the increasingly complex
     command syntax diagrams and updated the structure and content of this
     man-page following release 2.5.
  \item David B. Rosen \Email{rosen\_AT\_unr.edu} provided ideas and some PostScript
     code from his ps2aplot program.
  \item Ian MacPhedran \Email{Ian\_MacPhedran\_AT\_engr.USask.CA} provided the XFIG
     output format driver.
  \item Carsten Hammer \Email{chammer\_AT\_hermes.hrz.uni-bielefeld.de} provided the
     Gnuplot output format driver and the initial DXF output format driver.
  \item Christoph Jaeschke provided the OS/2 metafile (MET) output format driver.
  Thomas Hoffmann \Email{thoffman\_AT\_zappa.sax.de} did some further updates on the OS/2 part.
  \item Jens Weber \Email{rz47b7\_AT\_PostAG.DE} provided the MS Windows metafile (WMF)
     output format driver, and a graphical user interface (GUI).
  \item G. Edward Johnson \Email{lorax\_AT\_nist.gov} provided the CGM Draw library
     used in the CGM output format driver.
  \item Gerhard Kircher \Email{kircher\_AT\_edvz.tuwien.ac.at} provided some bug
     fixes.
  \item Bill Cheng \Email{bill.cheng\_AT\_acm.org} provided help with the TGIF
     format and some changes to TGIF to make the output format driver easier to implement.
  \item Reini Urban \Email{rurban\_AT\_sbox.tu-graz.ac.at} provided input for the
     extended DXF output format driver.
  \item Glenn M. Lewis \Email{glenn\_AT\_gmlewis.com} provided RenderMan (RIB),
     Real3D (RPL), and LightWave 3D (LWO) output format drivers.
  \item Piet van Oostrum \Email{piet\_AT\_cs.ruu.nl} made several bug fixes.
  \item Lutz Vieweg \Email{lkv\_AT\_mania.robin.de} provided several bug fixes and
     suggestions for improvements.
  \item Derek B. Noonburg \Email{derekn\_AT\_vw.ece.cmu.edu} and Rainer Dorsch
     \Email{rd\_AT\_berlepsch.wohnheim.uni-ulm.de} isolated and resolved a
     Linux-specific core dump problem.
  \item Rob Warner \Email{rcw2\_AT\_ukc.ac.uk} made pstoedit compile under RiscOS.
  \item Patrick Gosling \Email{jpmg\_AT\_eng.cam.ac.uk} made some suggestions
     regarding the usage of pstoedit in Ghostscript's SAFER mode.
  \item Scott Pakin \Email{scott+ps2ed\_AT\_pakin.org} for the Idraw output format driver and the
	autoconf support.
  \item Peter Katzmann \Email{p.katzmann\_AT\_thiesen.com} for the HPGL output format driver.
  \item Chris Cox \Email{ccox\_AT\_airmail.net} contributed the Tcl/Tk output format driver.
  \item Thorsten Behrens \Email{Thorsten\_Behrens\_AT\_public.uni-hamburg.de} and
     Bjoern Petersen for reworking the WMF output format driver.
  \item Leszek Piotrowicz \Email{leszek\_AT\_sopot.rodan.pl} implemented the image
     support for the XFIG driver and a JAVA based GUI.
  \item Egil Kvaleberg \Email{egil\_AT\_kvaleberg.no} contributed the pic output format driver.
  \item Kai-Uwe Sattler \Email{kus\_AT\_iti.cs.uni-magdeburg.de} implemented the
     output format driver for Kontour.
  \item Scott Pakin, \Email{scott+ps2ed\_AT\_pakin.org} provided the MetaPost and \LaTeX2e\ and MS PowerPoint output format driver.
  \item The MS PowerPoint driver (pptx) uses the libzip library - \URL{https://libzip.org}. Under MS Windows, libzip and libz are linked statically into the driver DLL. Thanks to the whole libzip team. The libzip license is explained here \URL{https://libzip.org/license}.
  \item Burkhard Plaum \Email{plaum\_AT\_IPF.Uni-Stuttgart.de} added support for
     complex filled paths for the XFIG output format driver.
  \item Bernhard Herzog \Email{herzog\_AT\_online.de} contributed the output format driver for
     sketch ( \URL{http://www.skencil.org/} )
  \item Rolf Niepraschk (\Email{niepraschk\_AT\_ptb.de}) converted the HTML man page
     to \LaTeX\  format. This allows generating the UNIX style and the HTML manual from this
     base format.
  \item Several others sent smaller bug fixed and bug reports. Sorry if I do not
     mention them all here.
  \item Gisbert W. Selke (\Email{gisbert\_AT\_tapirsoft.de}) for the Java 2 output format driver.
  \item Robert S. Maier (\Email{rsm\_AT\_math.arizona.edu}) for many improvements on
	the libplot output format driver and for libplot itself.
  \item The authors of pstotext (\Email{mcjones\_AT\_pa.dec.com} and \Email{birrell\_AT\_pa.dec.com})
	for giving me the permission to use their simple PostScript code for
	performing rotation.
  \item Daniel Gehriger \Email{gehriger\_AT\_linkcad.com} for his help concerning the handling of Splines in the DXF format.
  \item Allen Barnett \Email{libemf\_AT\_lignumcomputing.com} for his work on the libEMF which allows creating WMF/EMF files under *nix systems.
  \item Dave \Email{dave\_AT\_opaque.net} for providing the libming which is a multiplatform library for generating SWF files.
  \item Masatake Yamoto for the introduction of autoconf, automake and libtool into pstoedit
  \item Bob Friesenhahn for his help and the building of the Magick++ API to ImageMagick.
  \item Barak Pearlmutter from Debian for his upfront testing of new versions.
  \item But most important: Peter Deutsch, Ken Sharp, Chris Liddell from the GhostScript team at Artifex, and Russell
        Lang \Email{gsview\_AT\_ghostgum.com.au} for their help and answers regarding Ghostscript and gsview.
\end{itemize}

\section{LEGAL NOTICES}

Trademarks mentioned are the property of their respective owners.

Some code incorporated in the pstoedit package is subject to copyright or
other intellectual property rights or restrictions including attribution
rights. See the notes in individual files.

\Prog{pstoedit} is controlled under the Free Software Foundation GNU Public
License (GPL). However, this does not apply to the additional plugins.

Ghostscript is a redistributable software package with copyright
restrictions controlled by Artifex \URL{https://artifex.com/}.

\Prog{pstoedit} has no other relation to Ghostscript besides calling it in a
subprocess.

The authors, contributors, and distributors of pstoedit are not responsible
for its use for any purpose, or for the results generated thereby.

Restrictions such as the foregoing may apply in other countries according to
international conventions and agreements.


\LatexManEnd

\end{document}