summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-drivers.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-drivers.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-drivers.tex468
1 files changed, 468 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-drivers.tex b/graphics/pgf/base/doc/pgfmanual-en-drivers.tex
new file mode 100644
index 0000000000..9ab6af46f1
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-drivers.tex
@@ -0,0 +1,468 @@
+% 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}