% Copyright 2005 by Till Tantau . % % This program can be redistributed and/or modified under the terms % of the LaTeX Project Public License Distributed from CTAN % archives in directory macros/latex/base/lppl.txt. \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 2005 by Till Tantau . % % This program can be redistributed and/or modified under the terms % of the GNU Public License, version 2. \RequirePackage{pgf,calc,pgffor,pgflibraryplothandlers,xkeyval} \input{tikz.code} \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}|. Instead of |\begin{pgfpicture}| and |\end{pgfpicture}| you use |\pgfpicture| and |\endpicture|. 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} Currently, there is no special support for the Con\TeX t format. Rather, you have to use \pgfname\ and \tikzname\ as if you were using the plain \TeX\ format when using Con\TeX t. This may change in the future. \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 tho 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. \end{enumerate} \end{filedescription} \begin{filedescription}{pgfsys-vtex.def} This is the driver file for use with the commercial \textsc{vtex} program. Even though is will produce \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 implemented at all. \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. \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 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 it is also not possible to correctly ``escape back'' to \textsc{html}. All these problems will hopefully disappear in the future, but currently only two kinds of text work reasonably well: First, plain text without math mode, special characters or anything else special. 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. \item If you use text that contains anything special, even something as simple as |$\alpha$|, this may corrupt the graphic since |text4ht| does not always produce valid \textsc{xml} code. So, once more, \emph{stick to very simple node text inside graphics.} Sorry. \item Unlike for other output formats, the bounding box of a picture ``really crops'' the picture. \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 specials that insert 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. \end{filedescription}