diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-drivers.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-drivers.tex | 468 |
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} |