% Copyright 2019 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{Supported 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: \LaTeX, Plain \TeX, Con\TeX t}

\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 2019 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.

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, 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 old versions of
Con\TeX t~MkII before 2005 satanically restricted the length of module names to
8 characters and \pgfname's long names are mapped to cryptic 6-letter-names for
you by the module |pgfmod|.  This restriction was never in place in
Con\TeX t~MkIV and the |pgfmod| module can be safely ignored nowadays.


\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 (informally known as
        ``device-independent 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 was an intermediate
stage.

Normally, \TeX\ only produces letter--coordinate pairs as its ``output''. This
obviously makes it 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 away'' 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 a lot of functionality. (Almost) 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.
    \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 largely the same operations as the |dvipdfm| driver.
\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 Shadings are approximated with discrete colors. This typically
          leads to aliasing patterns in PostScript and \textsc{pdf} viewing
          applications.
        \item Opacity, Transparency Groups, Fadings and Blend Modes are 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 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.
            Image masking is supported if the PostScript output is further
            processed with |ps2pdf| to produce \textsc{pdf}.
        \item In plain \TeX\ mode it does not support image inclusion.
        \item Functional shadings are approximated with Type-0 functions
            (sampled functions), because Type-4 functions are not available in
            the latest (version 3) PostScript language definition. Due to
            their fixed resolution, Type-0 functional shadings are of lesser
            quality at higher zoom levels as compared to functional shadings
            from \textsc{pdf} producing drivers. Axial and radial shadings are
            fully supported. The same output quality (smooth shadings) is
            achieved as with drivers that produce \textsc{pdf} output.
        \item Although fully supported, opacity and fadings are \textsc{pdf}
            features that become visible only after further processing the
            PostScript output with |ps2pdf|. Note that newer Ghostscript
            versions are necessary for producing opacity in the \textsc{pdf}
            output. Also, beginning with version 9.52 of Ghostscript, command
            line option |-dALLOWPSTRANSPARENCY| must be added:
\begin{codeexample}[code only]
ps2pdf -dALLOWPSTRANSPARENCY example.ps
\end{codeexample}
        \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 shares the restrictions of the |vtex| driver, but adds limited
    opacity support (no transparency groups, fadings and blend modes, though).
\end{filedescription}

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


\subsubsection{Producing SVG Output}

\begin{filedescription}{pgfsys-dvisvgm.def}
    This driver converts \textsc{dvi} files to \textsc{svg} file, including
    text and fonts. When you select this driver, \pgfname\ will output the
    required raw \textsc{svg} code for the pictures it produces.

    Since the |graphics| package does not (yet?) support this driver directly,
    there is special rule for this driver in \LaTeX: If the option |dvisvgm| is
    given to the |tikz| package, this driver gets selected (normally, the
    driver selected by |graphics| would be used). For packages like |beamer|
    that load \pgfname\ themselves, this means that the option |dvisvgm| should
    be given to the document class.
    %
\begin{codeexample}[code only]
% example.tex
\documentclass[dvisvgm]{minimal}

\usepackage{tikz}

\begin{document}
Hello \tikz [baseline] \fill [fill=blue!80!black] (0,.75ex) circle[radius=.75ex];
\end{document}
\end{codeexample}

    And then run
    %
\begin{codeexample}[code only]
latex example
dvisvgm example
\end{codeexample}
    %
    or better
    %
\begin{codeexample}[code only]
lualatex --output-format=dvi example
dvisvgm example
\end{codeexample}
    %
    (This is ``better'' since it gives you access to the full power of Lua\TeX\
    inside your \TeX-file. In particular, \tikzname\ is able to run graph
    drawing algorithms in this case.)

    Unlike the |tex4ht| driver below, this driver has full support of text
    nodes.
\end{filedescription}

\begin{filedescription}{pgfsys-tex4ht.def}
    This is a driver file for use with the |tex4ht| program. It is selected
    automatically when the |tex4ht| style or command is loaded. It includes
    |pgfsys-common-svg.def|.

    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. This driver will ask \pgfname\ to produce an
    \textsc{svg}-picture for each \pgfname\ graphic in your text.

    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}, \tikzname\ 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}{/pgf/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,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$};
\end{codeexample}

    When you write |node[/pgf/tex4ht node/escape=true] {|\meta{text}|}|,
    \pgfname\ 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 |{pgfpicture}|, 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, \pgfname\ 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,/pgf/tex4ht node/escape=true]
  {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$};
\end{codeexample}
    %
    \end{key}

    \begin{key}{/pgf/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}{/pgf/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}{/pgf/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 hundreds 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}