% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Input and Output Formats}
\label{section-formats}


\TeX\ was designed to be a flexible system. This is true both for the
\emph{input} for \TeX\ as well as for the \emph{output}. The present
section explains which input formats there are and how they are
supported by \pgfname. It also explains which different output formats
can be produced.



\subsection{Supported Input Formats}

\TeX\ does not prescribe exactly how your input should be
formatted. While it is \emph{customary} that, say, an opening brace
starts a scope in \TeX, this is by no means necessary. Likewise, it is
\emph{customary} that environments start with |\begin|, but \TeX\
could not really care less about the exact command name.

Even though \TeX\ can be reconfigured, users can not. For this reason,
certain \emph{input formats} specify a set of commands and conventions
how input for \TeX\ should be formatted. There are currently three
``major'' formats: Donald Knuth's original |plain| \TeX\ format,
Leslie Lamport's popular \LaTeX\ format, and Hans Hangen's Con\TeX t
format.


\subsubsection{Using the  \LaTeX\ Format}

Using \pgfname\ and \tikzname\ with the \LaTeX\ format is easy: You
say |\usepackage{pgf}| or |\usepackage{tikz}|. Usually, that is all
you need to do, all configuration will be done automatically and
(hopefully) correctly.

The style files used for the \LaTeX\ format reside in the subdirectory
|latex/pgf/| of the \pgfname-system. Mainly, what these files do is to
include files in the directory |generic/pgf|. For example, here is the
content of the file |latex/pgf/frontends/tikz.sty|:

\begin{codeexample}[code only]
% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Public License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\RequirePackage{pgf,pgffor}

\input{tikz.code.tex}

\endinput
\end{codeexample}

The files in the |generic/pgf| directory do the actual work.



\subsubsection{Using the Plain \TeX\ Format}

When using the plain \TeX\ format, you say |\input{pgf.tex}| or
|\input{tikz.tex}|. Then, instead of  |\begin{pgfpicture}| and
  |\end{pgfpicture}| you use  |\pgfpicture| and |\endpgfpicture|.

Unlike for the \LaTeX\ format, \pgfname\ is not as good at discerning
the appropriate configuration for the plain \TeX\ format. In
particular, it can only automatically determine the correct output
format if you use |pdftex| or |tex| plus |dvips|. For all other output
formats you need to set the macro |\pgfsysdriver| to the correct
value. See the description of using output formats later on.

\pgfname\ was originally written for use with \LaTeX\ and this shows
in a number of places. Nevertheless, the plain \TeX\ support is
reasonably good.

Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex|
also just include the correct |tikz.code.tex| file.



\subsubsection{Using the Con\TeX t Format}

When using the Con\TeX t format\footnote{Note that \pgfname/\tikzname{}
  is not supported by recent Con\TeX t versions (like mark IV, the
  Lua\TeX-aware part of Con\TeX t).}, you say |\usemodule[pgf]| or
|\usemodule[tikz]|. As for the plain \TeX\ format you also have to
replace the start- and end-of-environment tags as follows: Instead of
|\begin{pgfpicture}| and |\end{pgfpicture}| you use |\startpgfpicture|
and |\stoppgfpicture|; similarly, instead of |\begin{tikzpicture}| and
  |\end{tikzpicture}| you use must now use |\starttikzpicture| and
|\stoptikzpicture|; and so on for other environments.

The Con\TeX t support is very similar to the plain \TeX\ support, so
the same restrictions apply: You may have to set the output
format directly and graphics inclusion may be a problem.

In addition to |pgf| and |tikz| there also exist modules like
|pgfcore| or |pgfmodulematrix|. To
use them, you may need to include the module |pgfmod| first (the
modules |pgf| and |tikz| both include |pgfmod| for you, so typically
you can skip this). This special module is necessary since Con\TeX t
satanically restricts the length of module names to 6 characters
and \pgfname's long names are mapped
to cryptic 6-letter-names for you by the module |pgfmod|.





\subsection{Supported Output Formats}
\label{section-drivers}

An output format is a format in which \TeX\ outputs the text it has
typeset. Producing the output is (conceptually) a two-stage process:
\begin{enumerate}
\item
  \TeX\ typesets your text and graphics. The result of this
  typesetting is mainly a long list of letter--coordinate pairs, plus
  (possibly) some ``special'' commands. This long list of pairs
  is written to something called a |.dvi|-file.
\item
  Some other program reads this |.dvi|-file and translates the
  letter--coordinate pairs into, say, PostScript commands for placing
  the given letter at the given coordinate.
\end{enumerate}

The classical example of this process is the combination of |latex|
and |dvips|. The |latex| program (which is just the |tex| program
called with the \LaTeX-macros preinstalled) produces a |.dvi|-file as
its output. The |dvips| program takes this output and produces a
|.ps|-file (a PostScript) file. Possibly, this file is further
converted using, say, |ps2pdf|, whose name is supposed to mean
``PostScript to PDF.'' Another example of programs using this
process is the combination of |tex| and |dvipdfm|. The |dvipdfm|
program takes a |.dvi|-file as
input and translates the letter--coordinate pairs therein into
\pdf-commands, resulting in a |.pdf| file directly. Finally, the
|tex4ht| is also a program that takes a |.dvi|-file and produces an
output, this time it is a |.html| file. The programs |pdftex| and
|pdflatex| are special: They directly produce a |.pdf|-file without
the intermediate |.dvi|-stage. However, from the programmer's point of
view they behave exactly as if there where an intermediate stage.

Normally, \TeX\ only produces letter--coordinate pairs as its
``output.'' This obviously makes is difficult to draw, say, a
curve. For this, ``special'' commands can be used. Unfortunately,
these special commands are not the same for the different programs
that process the |.dvi|-file. Indeed, every program that takes a
|.dvi|-file as input has a totally different syntax for the special
commands.

One of the main jobs of \pgfname\ is to ``abstract way'' the
difference in the syntax of the different programs. However, this
means that support for each program has to be ``programmed,'' which is
a time-consuming and complicated process.


\subsubsection{Selecting the Backend Driver}

When \TeX\ typesets your document, it does not know which program
you are going to use to transform the |.dvi|-file. If your |.dvi|-file
does not contain any special commands, this would be fine; but these
days almost all |.dvi|-files contain lots of special commands. It is
thus necessary to tell \TeX\ which program you are going to use later
on.

Unfortunately, there is no ``standard'' way of telling this to
\TeX. For the \LaTeX\ format a sophisticated mechanism exists inside
the |graphics| package and \pgfname\ plugs into this mechanism. For
other formats and when this plugging does not work as expected, it is
necessary to tell \pgfname\ directly which program you are going to
use. This is done by redefining the macro |\pgfsysdriver| to an
appropriate value \emph{before} you load |pgf|. If you are going to
use the |dvips| program, you set this macro to the value
|pgfsys-dvips.def|; if you use |pdftex| or |pdflatex|, you set it to
|pgfsys-pdftex.def|; and so on. In the following, details of the
support of the different programs are discussed.


\subsubsection{Producing PDF Output}

\pgfname\ supports three programs that produce \pdf\ output (\pdf\ means
``portable document format'' and was invented by the Adobe company):
|dvipdfm|, |pdftex|, and |vtex|. The |pdflatex| program is the same as the
|pdftex| program: it uses a different input format, but the output is
exactly the same.

\begin{filedescription}{pgfsys-pdftex.def}
  This is the driver file for use with pdf\TeX, that is, with the
  |pdftex| or |pdflatex| command. It includes
  |pgfsys-common-pdf.def|.

  This driver has the ``complete'' functionality. This means,
  everything \pgfname\ ``can do at all'' is implemented in this
  driver.
\end{filedescription}

\begin{filedescription}{pgfsys-dvipdfm.def}
  This is a driver file for use with (|la|)|tex| followed by |dvipdfm|. It
  includes |pgfsys-common-pdf.def|.

  This driver supports most of \pgfname's features, but there are some
  restrictions:
  \begin{enumerate}
  \item
    In \LaTeX\ mode it uses |graphicx| for the graphics
    inclusion and does not support masking.
  \item
    In plain \TeX\ mode it does not support image inclusion.
  \item
    For remembering of pictures (inter-picture connections) you need
    to use a recent version of |pdftex| running in DVI-mode.
  \item
    Patterns are not (cannot) be supported.
  \item
    Functional shadings are not (cannot) be supported.
  \end{enumerate}
\end{filedescription}

\begin{filedescription}{pgfsys-xetex.def}
  This is a driver file for use with |xe|(|la|)|tex| followed by
  |xdvipdfmx|. This driver supports the same operations as the dvipdfm
  driver,  except that remembering of pictures (inter-picture
  connections)   always works.
\end{filedescription}

\begin{filedescription}{pgfsys-vtex.def}
  This is the driver file for use with the commercial \textsc{vtex}
  program. Even though it produces  \textsc{pdf} output, it
  includes |pgfsys-common-postscript.def|. Note that the
  \textsc{vtex} program can produce \emph{both} Postscript and
  \textsc{pdf} output, depending on the command line
  parameters. However, whether you produce Postscript or
  \textsc{pdf} output does not change anything with respect to the
  driver.

  This driver supports most of \pgfname's features, except for
  the following restrictions:
  \begin{enumerate}
  \item
    In \LaTeX\ mode it uses |graphicx| for the graphics
    inclusion and does not support masking.
  \item
    In plain \TeX\ mode it does not support image inclusion.
  \item
    Shading is fully implemented, but yields the same quality as the
    implementation for |dvips|.
  \item
    Opacity is not supported.
  \item
    Remembering of pictures (inter-picture connections) is not
    supported.
  \end{enumerate}
\end{filedescription}

It is also possible to produce a |.pdf|-file by first producing a
PostScript file (see below) and then using a PostScript-to-\pdf\
conversion program like |ps2pdf| or the Acrobat Distiller.


\subsubsection{Producing PostScript Output}

\begin{filedescription}{pgfsys-dvips.def}
  This is a driver file for use with (|la|)|tex| followed by
  |dvips|. It includes |pgfsys-common-postscript.def|.

  This driver also supports most of \pgfname's features, except for
  the following restrictions:
  \begin{enumerate}
  \item
    In \LaTeX\ mode it uses |graphicx| for the graphics
    inclusion and does not support masking.
  \item
    In plain \TeX\ mode it does not support image inclusion.
  \item
    Shading is fully implemented, but the results will not be
    as good as with a driver producing |.pdf| as output.
  \item
    Opacity works only in conjunction with newer versions of
    Ghostscript.
  \item
    For remembering of pictures (inter-picture connections) you need
    to use a recent version of |pdftex| running in DVI-mode.
  \end{enumerate}
\end{filedescription}

\begin{filedescription}{pgfsys-textures.def}
  This is a driver file for use with the \textsc{textures} program. It
  includes |pgfsys-common-postscript.def|.

  This driver has exactly the same restrictions as the driver for
  |dvips|.
\end{filedescription}

You can also use the |vtex| program together with |pgfsys-vtex.def| to
produce Postscript output.



\subsubsection{Producing HTML / SVG Output}

The |tex4ht| program converts |.dvi|-files to |.html|-files. While the
\textsc{html}-format cannot be used to draw graphics, the
\textsc{svg}-format can. Using the following driver, you can ask
\pgfname\ to produce an \textsc{svg}-picture for each \pgfname\
graphic in your text.

\begin{filedescription}{pgfsys-tex4ht.def}
  This is a driver file for use with the |tex4ht| program. It includes
  |pgfsys-common-svg.def|.

  When using this driver you should be aware of the following
  restrictions:
  \begin{enumerate}
  \item
    In \LaTeX\ mode it uses |graphicx| for the graphics
    inclusion.
  \item
    In plain \TeX\ mode it does not support image inclusion.
  \item
    Remembering of pictures (inter-picture connections) is not
    supported.
  \item
    Text inside |pgfpicture|s is not supported very well. The reason
    is that the \textsc{svg} specification currently does not support
    text very well and, although it is  possible to ``escape
    back'' to \textsc{html}, |Tikz| has then to guess what size the text
    rendered by the browser would have.
  \item
    Unlike for other output formats, the bounding box of a picture
    ``really crops'' the picture.
  \item
    Matrices do not work.
  \item
    Functional shadings are not supported.
  \end{enumerate}

  The driver basically works as follows: When a |{pgfpicture}| is
  started, appropriate |\special| commands are used to directed the
  output of |tex4ht| to a new file called |\jobname-xxx.svg|, where
  |xxx| is a number that is increased for each graphic. Then, till the
  end of the picture, each (system layer) graphic command creates a
  special that inserts appropriate \textsc{svg} literal text into the
  output file. The exact details are a bit complicated since the
  imaging model and the processing model of PostScript/\pdf\ and
  \textsc{svg} are not quite the same; but they are ``close enough''
  for \pgfname's purposes.

  Because text is not supported very well in the
  \textsc{svg} standard, you may wish to use the following options to
  modify the way text is handled:

  \begin{key}{/tikz/tex4ht node/escape=\meta{boolean} (default |false|)}
    Selects the rendering method for a text node with the tex4ht driver.

    When this key is set to |false|, text is translated into
    \textsc{svg} text, which is somewhat limited: simple
    characters (letters, numerals, punctuation, $\sum$, $\int$, \ldots),
    subscripts and superscripts (but not subsubscripts) will display but
    everything else will be filtered out, ignored or will produce
    invalid \textsc{html} code (in the worst case). This means that two
    kind of texts render reasonably well:
    \begin{enumerate}
    \item First, plain text without math mode, special characters or
      anything else special.
    \item Second, \emph{very} simple mathematical text that contains
      subscripts or superscripts. Even then, variables are not correctly
      set in italics and, in general, text simple does not look very
      nice.
    \end{enumerate}
    If you use text that contains anything special, even something as
    simple as |$\alpha$|, this may corrupt the graphic.

\begin{codeexample}[code only]
\tikz \node[draw,tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$};
\end{codeexample}

    When you write |node[tex4ht node/escape=true] {|\meta{text}|}|,
    \tikzname\ escapes back to \textsc{html} to render the
    \meta{text}. This method produces valid \textsc{html} code in most
    cases and the support for complicated text nodes is much better since
    code that renders well outside a |{tikzpicture}|, should also
    render well inside a text node. Another advantage is that inside
    text nodes with fixed width, \textsc{html} will produce line
    breaks for long  lines. On the other hand, you need a browser with
    good \textsc{svg} support to display the picture. Also, the text
    will display differently, depending on your browsers, the fonts
    you have on your system and your settings. Finally,
    \tikzname\ has to guess the size of the text rendered by the
    browser to scale it and prevent it from sticking from the
    node. When it fails, the text will be either cropped or too small.
\begin{codeexample}[code only]
\tikz \node[draw,tex4ht node/escape=true]
  {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$};
\end{codeexample}
  \end{key}

  \begin{key}{/tikz/tex4ht node/css=\meta{filename}  (default |\string\jobname|)}
    This option allows you to tell the browser what \textsc{css} file
    it should  use to style the display of the node (only with
    |tex4ht node/escape=true|).
  \end{key}

  \begin{key}{/tikz/tex4ht node/class=\meta{class name}  (default foreignobject)}
    This option allows you to give a class name to the node, allowing
    it to be styled by a \textsc{css} file (only with
    |tex4ht node/escape=true|).
  \end{key}

  \begin{key}{/tikz/tex4ht node/id=\meta{id name} (default
      |\string\jobname\ picture number-node number|)}
    This option allows you to give a unique id to the node, allowing
    it to be styled by a \textsc{css} file (only with
    |tex4ht  node/escape=true|).
  \end{key}
\end{filedescription}


\subsubsection{Producing Perfectly Portable DVI Output}

\begin{filedescription}{pgfsys-dvi.def}
  This is a driver file that can be used with any output driver,
  except for |tex4ht|.

  The driver will produce perfectly portable |.dvi| files by composing
  all pictures entirely of black rectangles, the basic and only graphic
  shape supported by the \TeX\ core. Even straight, but slanted lines
  are tricky to get right in this model (they need to be composed of
  lots of little squares).

  Naturally, \emph{very little} is possible with this driver. In fact,
  so little is possible that it is easier to list what is possible:
  \begin{itemize}
  \item Text boxes can be placed in the normal way.
  \item Lines and curves can be drawn (stroked). If they are not
    horizontal or vertical, they are composed of hundred of small
    rectangles.
  \item Lines of different width are supported.
  \item Transformations are supported.
  \end{itemize}
  Note that, say, even filling is not supported! (Let alone color or
  anything fancy.)

  This driver has only one real application: It might be useful when
  you only need horizontal or vertical lines in a picture. Then, the
  results are quite satisfactory.
\end{filedescription}
