Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-drivers.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Supported Formats}
12 \label{section-formats}
13
14 \TeX\ was designed to be a flexible system. This is true both for the
15 \emph{input} for \TeX\ as well as for the \emph{output}. The present section
16 explains which input formats there are and how they are supported by \pgfname.
17 It also explains which different output formats can be produced.
18
19
20 \subsection{Supported Input Formats: \LaTeX, Plain \TeX, Con\TeX t}
21
22 \TeX\ does not prescribe exactly how your input should be formatted. While it
23 is \emph{customary} that, say, an opening brace starts a scope in \TeX, this is
24 by no means necessary. Likewise, it is \emph{customary} that environments start
25 with |\begin|, but \TeX\ could not really care less about the exact command
26 name.
27
28 Even though \TeX\ can be reconfigured, users can not. For this reason, certain
29 \emph{input formats} specify a set of commands and conventions how input for
30 \TeX\ should be formatted. There are currently three ``major'' formats: Donald
31 Knuth's original |plain| \TeX\ format, Leslie Lamport's popular \LaTeX\ format,
32 and Hans Hangen's Con\TeX t format.
33
34
35 \subsubsection{Using the \LaTeX\ Format}
36
37 Using \pgfname\ and \tikzname\ with the \LaTeX\ format is easy: You say
38 |\usepackage{pgf}| or |\usepackage{tikz}|. Usually, that is all you need to do,
39 all configuration will be done automatically and (hopefully) correctly.
40
41 The style files used for the \LaTeX\ format reside in the subdirectory
42 |latex/pgf/| of the \pgfname-system. Mainly, what these files do is to include
43 files in the directory |generic/pgf|. For example, here is the content of the
44 file |latex/pgf/frontends/tikz.sty|:
45 %
46 \begin{codeexample}[code only]
47 % Copyright 2019 by Till Tantau
48 %
49 % This file may be distributed and/or modified
50 %
51 % 1. under the LaTeX Project Public License and/or
52 % 2. under the GNU Public License.
53 %
54 % See the file doc/generic/pgf/licenses/LICENSE for more details.
55
56
57 \RequirePackage{pgf,pgffor}
58
59 \input{tikz.code.tex}
60
61 \endinput
62 \end{codeexample}
63
64 The files in the |generic/pgf| directory do the actual work.
65
66
67 \subsubsection{Using the Plain \TeX\ Format}
68
69 When using the plain \TeX\ format, you say |\input{pgf.tex}| or
70 |\input{tikz.tex}|. Then, instead of |\begin{pgfpicture}| and
71 |\end{pgfpicture}| you use |\pgfpicture| and |\endpgfpicture|.
72
73 Unlike for the \LaTeX\ format, \pgfname\ is not as good at discerning the
74 appropriate configuration for the plain \TeX\ format. In particular, it can
75 only automatically determine the correct output format if you use |pdftex| or
76 |tex| plus |dvips|. For all other output formats you need to set the macro
77 |\pgfsysdriver| to the correct value. See the description of using output
78 formats later on.
79
80 Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex| also just
81 include the correct |tikz.code.tex| file.
82
83
84 \subsubsection{Using the Con\TeX t Format}
85
86 When using the Con\TeX t format, you say |\usemodule[pgf]| or
87 |\usemodule[tikz]|. As for the plain \TeX\ format you also have to replace the
88 start- and end-of-environment tags as follows: Instead of |\begin{pgfpicture}|
89 and |\end{pgfpicture}| you use |\startpgfpicture| and |\stoppgfpicture|;
90 similarly, instead of |\begin{tikzpicture}| and |\end{tikzpicture}| you use
91 must now use |\starttikzpicture| and |\stoptikzpicture|; and so on for other
92 environments.
93
94 The Con\TeX t support is very similar to the plain \TeX\ support, so the same
95 restrictions apply: You may have to set the output format directly and graphics
96 inclusion may be a problem.
97
98 In addition to |pgf| and |tikz| there also exist modules like |pgfcore| or
99 |pgfmodulematrix|. To use them, you may need to include the module |pgfmod|
100 first (the modules |pgf| and |tikz| both include |pgfmod| for you, so typically
101 you can skip this). This special module is necessary since old versions of
102 Con\TeX t~MkII before 2005 satanically restricted the length of module names to
103 8 characters and \pgfname's long names are mapped to cryptic 6-letter-names for
104 you by the module |pgfmod|. This restriction was never in place in
105 Con\TeX t~MkIV and the |pgfmod| module can be safely ignored nowadays.
106
107
108 \subsection{Supported Output Formats}
109 \label{section-drivers}
110
111 An output format is a format in which \TeX\ outputs the text it has typeset.
112 Producing the output is (conceptually) a two-stage process:
113 %
114 \begin{enumerate}
115 \item \TeX\ typesets your text and graphics. The result of this
116 typesetting is mainly a long list of letter--coordinate pairs, plus
117 (possibly) some ``special'' commands. This long list of pairs is
118 written to something called a |.dvi|-file (informally known as
119 ``device-independent file'').
120 \item Some other program reads this |.dvi|-file and translates the
121 letter--coordinate pairs into, say, PostScript commands for placing
122 the given letter at the given coordinate.
123 \end{enumerate}
124
125 The classical example of this process is the combination of |latex| and
126 |dvips|. The |latex| program (which is just the |tex| program called with the
127 \LaTeX-macros preinstalled) produces a |.dvi|-file as its output. The |dvips|
128 program takes this output and produces a |.ps|-file (a PostScript file).
129 Possibly, this file is further converted using, say, |ps2pdf|, whose name is
130 supposed to mean ``PostScript to PDF''. Another example of programs using this
131 process is the combination of |tex| and |dvipdfm|. The |dvipdfm| program takes
132 a |.dvi|-file as input and translates the letter--coordinate pairs therein into
133 \pdf-commands, resulting in a |.pdf| file directly. Finally, the |tex4ht| is
134 also a program that takes a |.dvi|-file and produces an output, this time it is
135 a |.html| file. The programs |pdftex| and |pdflatex| are special: They directly
136 produce a |.pdf|-file without the intermediate |.dvi|-stage. However, from the
137 programmer's point of view they behave exactly as if there was an intermediate
138 stage.
139
140 Normally, \TeX\ only produces letter--coordinate pairs as its ``output''. This
141 obviously makes it difficult to draw, say, a curve. For this, ``special''
142 commands can be used. Unfortunately, these special commands are not the same
143 for the different programs that process the |.dvi|-file. Indeed, every program
144 that takes a |.dvi|-file as input has a totally different syntax for the
145 special commands.
146
147 One of the main jobs of \pgfname\ is to ``abstract away'' the difference in the
148 syntax of the different programs. However, this means that support for each
149 program has to be ``programmed'', which is a time-consuming and complicated
150 process.
151
152
153 \subsubsection{Selecting the Backend Driver}
154
155 When \TeX\ typesets your document, it does not know which program you are going
156 to use to transform the |.dvi|-file. If your |.dvi|-file does not contain any
157 special commands, this would be fine; but these days almost all |.dvi|-files
158 contain lots of special commands. It is thus necessary to tell \TeX\ which
159 program you are going to use later on.
160
161 Unfortunately, there is no ``standard'' way of telling this to \TeX. For the
162 \LaTeX\ format a sophisticated mechanism exists inside the |graphics| package
163 and \pgfname\ plugs into this mechanism. For other formats and when this
164 plugging does not work as expected, it is necessary to tell \pgfname\ directly
165 which program you are going to use. This is done by redefining the macro
166 |\pgfsysdriver| to an appropriate value \emph{before} you load |pgf|. If you
167 are going to use the |dvips| program, you set this macro to the value
168 |pgfsys-dvips.def|; if you use |pdftex| or |pdflatex|, you set it to
169 |pgfsys-pdftex.def|; and so on. In the following, details of the support of the
170 different programs are discussed.
171
172
173 \subsubsection{Producing PDF Output}
174
175 \pgfname\ supports three programs that produce \pdf\ output (\pdf\ means
176 ``portable document format'' and was invented by the Adobe company): |dvipdfm|,
177 |pdftex|, and |vtex|. The |pdflatex| program is the same as the |pdftex|
178 program: it uses a different input format, but the output is exactly the same.
179
180 \begin{filedescription}{pgfsys-pdftex.def}
181 This is the driver file for use with pdf\TeX, that is, with the |pdftex| or
182 |pdflatex| command. It includes |pgfsys-common-pdf.def|.
183
184 This driver has a lot of functionality. (Almost) everything \pgfname\ ``can
185 do at all'' is implemented in this driver.
186 \end{filedescription}
187
188 \begin{filedescription}{pgfsys-dvipdfm.def}
189 This is a driver file for use with (|la|)|tex| followed by |dvipdfm|. It
190 includes |pgfsys-common-pdf.def|.
191
192 This driver supports most of \pgfname's features, but there are some
193 restrictions:
194 %
195 \begin{enumerate}
196 \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion
197 and does not support masking.
198 \item In plain \TeX\ mode it does not support image inclusion.
199 \end{enumerate}
200 \end{filedescription}
201
202 \begin{filedescription}{pgfsys-xetex.def}
203 This is a driver file for use with |xe|(|la|)|tex| followed by |xdvipdfmx|.
204 This driver supports largely the same operations as the |dvipdfm| driver.
205 \end{filedescription}
206
207 \begin{filedescription}{pgfsys-vtex.def}
208 This is the driver file for use with the commercial \textsc{vtex} program.
209 Even though it produces \textsc{pdf} output, it includes
210 |pgfsys-common-postscript.def|. Note that the \textsc{vtex} program can
211 produce \emph{both} Postscript and \textsc{pdf} output, depending on the
212 command line parameters. However, whether you produce Postscript or
213 \textsc{pdf} output does not change anything with respect to the driver.
214
215 This driver supports most of \pgfname's features, except for the following
216 restrictions:
217 %
218 \begin{enumerate}
219 \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion
220 and does not support masking.
221 \item In plain \TeX\ mode it does not support image inclusion.
222 \item Shadings are approximated with discrete colors. This typically
223 leads to aliasing patterns in PostScript and \textsc{pdf} viewing
224 applications.
225 \item Opacity, Transparency Groups, Fadings and Blend Modes are not
226 supported.
227 \item Remembering of pictures (inter-picture connections) is not
228 supported.
229 \end{enumerate}
230 \end{filedescription}
231
232 It is also possible to produce a |.pdf|-file by first producing a PostScript
233 file (see below) and then using a PostScript-to-\pdf\ conversion program like
234 |ps2pdf| or Acrobat Distiller.
235
236
237 \subsubsection{Producing PostScript Output}
238
239 \begin{filedescription}{pgfsys-dvips.def}
240 This is a driver file for use with (|la|)|tex| followed by |dvips|. It
241 includes |pgfsys-common-postscript.def|.
242
243 This driver also supports most of \pgfname's features, except for the
244 following restrictions:
245 %
246 \begin{enumerate}
247 \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion.
248 Image masking is supported if the PostScript output is further
249 processed with |ps2pdf| to produce \textsc{pdf}.
250 \item In plain \TeX\ mode it does not support image inclusion.
251 \item Functional shadings are approximated with Type-0 functions
252 (sampled functions), because Type-4 functions are not available in
253 the latest (version 3) PostScript language definition. Due to
254 their fixed resolution, Type-0 functional shadings are of lesser
255 quality at higher zoom levels as compared to functional shadings
256 from \textsc{pdf} producing drivers. Axial and radial shadings are
257 fully supported. The same output quality (smooth shadings) is
258 achieved as with drivers that produce \textsc{pdf} output.
259 \item Although fully supported, opacity and fadings are \textsc{pdf}
260 features that become visible only after further processing the
261 PostScript output with |ps2pdf|. Note that newer Ghostscript
262 versions are necessary for producing opacity in the \textsc{pdf}
263 output. Also, beginning with version 9.52 of Ghostscript, command
264 line option |-dALLOWPSTRANSPARENCY| must be added:
265 \begin{codeexample}[code only]
266 ps2pdf -dALLOWPSTRANSPARENCY example.ps
267 \end{codeexample}
268 \item For remembering of pictures (inter-picture connections) you
269 need to use a recent version of |pdftex| running in DVI-mode.
270 \end{enumerate}
271 \end{filedescription}
272
273 \begin{filedescription}{pgfsys-textures.def}
274 This is a driver file for use with the \textsc{textures} program. It
275 includes |pgfsys-common-postscript.def|.
276
277 This driver shares the restrictions of the |vtex| driver, but adds limited
278 opacity support (no transparency groups, fadings and blend modes, though).
279 \end{filedescription}
280
281 You can also use the |vtex| program together with |pgfsys-vtex.def| to produce
282 Postscript output.
283
284
285 \subsubsection{Producing SVG Output}
286
287 \begin{filedescription}{pgfsys-dvisvgm.def}
288 This driver converts \textsc{dvi} files to \textsc{svg} file, including
289 text and fonts. When you select this driver, \pgfname\ will output the
290 required raw \textsc{svg} code for the pictures it produces.
291
292 Since the |graphics| package does not (yet?) support this driver directly,
293 there is special rule for this driver in \LaTeX: If the option |dvisvgm| is
294 given to the |tikz| package, this driver gets selected (normally, the
295 driver selected by |graphics| would be used). For packages like |beamer|
296 that load \pgfname\ themselves, this means that the option |dvisvgm| should
297 be given to the document class.
298 %
299 \begin{codeexample}[code only]
300 % example.tex
301 \documentclass[dvisvgm]{minimal}
302
303 \usepackage{tikz}
304
305 \begin{document}
306 Hello \tikz [baseline] \fill [fill=blue!80!black] (0,.75ex) circle[radius=.75ex];
307 \end{document}
308 \end{codeexample}
309
310 And then run
311 %
312 \begin{codeexample}[code only]
313 latex example
314 dvisvgm example
315 \end{codeexample}
316 %
317 or better
318 %
319 \begin{codeexample}[code only]
320 lualatex --output-format=dvi example
321 dvisvgm example
322 \end{codeexample}
323 %
324 (This is ``better'' since it gives you access to the full power of Lua\TeX\
325 inside your \TeX-file. In particular, \tikzname\ is able to run graph
326 drawing algorithms in this case.)
327
328 Unlike the |tex4ht| driver below, this driver has full support of text
329 nodes.
330 \end{filedescription}
331
332 \begin{filedescription}{pgfsys-tex4ht.def}
333 This is a driver file for use with the |tex4ht| program. It is selected
334 automatically when the |tex4ht| style or command is loaded. It includes
335 |pgfsys-common-svg.def|.
336
337 The |tex4ht| program converts |.dvi|-files to |.html|-files. While the
338 \textsc{html}-format cannot be used to draw graphics, the
339 \textsc{svg}-format can. This driver will ask \pgfname\ to produce an
340 \textsc{svg}-picture for each \pgfname\ graphic in your text.
341
342 When using this driver you should be aware of the following restrictions:
343 %
344 \begin{enumerate}
345 \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion.
346 \item In plain \TeX\ mode it does not support image inclusion.
347 \item Remembering of pictures (inter-picture connections) is not
348 supported.
349 \item Text inside |pgfpicture|s is not supported very well. The
350 reason is that the \textsc{svg} specification currently does not
351 support text very well and, although it is possible to ``escape
352 back'' to \textsc{html}, \tikzname\ has then to guess what size
353 the text rendered by the browser would have.
354 \item Unlike for other output formats, the bounding box of a picture
355 ``really crops'' the picture.
356 \item Matrices do not work.
357 \item Functional shadings are not supported.
358 \end{enumerate}
359
360 The driver basically works as follows: When a |{pgfpicture}| is started,
361 appropriate |\special| commands are used to directed the output of |tex4ht|
362 to a new file called |\jobname-xxx.svg|, where |xxx| is a number that is
363 increased for each graphic. Then, till the end of the picture, each (system
364 layer) graphic command creates a special that inserts appropriate
365 \textsc{svg} literal text into the output file. The exact details are a bit
366 complicated since the imaging model and the processing model of
367 PostScript/\pdf\ and \textsc{svg} are not quite the same; but they are
368 ``close enough'' for \pgfname's purposes.
369
370 Because text is not supported very well in the \textsc{svg} standard, you
371 may wish to use the following options to modify the way text is handled:
372
373 \begin{key}{/pgf/tex4ht node/escape=\meta{boolean} (default |false|)}
374 Selects the rendering method for a text node with the tex4ht driver.
375
376 When this key is set to |false|, text is translated into \textsc{svg}
377 text, which is somewhat limited: simple characters (letters, numerals,
378 punctuation, $\sum$, $\int$, \ldots), subscripts and superscripts (but
379 not subsubscripts) will display but everything else will be filtered
380 out, ignored or will produce invalid \textsc{html} code (in the worst
381 case). This means that two kind of texts render reasonably well:
382 %
383 \begin{enumerate}
384 \item First, plain text without math mode, special characters or
385 anything else special.
386 \item Second, \emph{very} simple mathematical text that contains
387 subscripts or superscripts. Even then, variables are not
388 correctly set in italics and, in general, text simple does
389 not look very nice.
390 \end{enumerate}
391 %
392 If you use text that contains anything special, even something as
393 simple as |$\alpha$|, this may corrupt the graphic.
394 %
395 \begin{codeexample}[code only]
396 \tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$};
397 \end{codeexample}
398
399 When you write |node[/pgf/tex4ht node/escape=true] {|\meta{text}|}|,
400 \pgfname\ escapes back to \textsc{html} to render the \meta{text}. This
401 method produces valid \textsc{html} code in most cases and the support for
402 complicated text nodes is much better since code that renders well outside
403 a |{pgfpicture}|, should also render well inside a text node. Another
404 advantage is that inside text nodes with fixed width, \textsc{html} will
405 produce line breaks for long lines. On the other hand, you need a browser
406 with good \textsc{svg} support to display the picture. Also, the text will
407 display differently, depending on your browsers, the fonts you have on your
408 system and your settings. Finally, \pgfname\ has to guess the size of the
409 text rendered by the browser to scale it and prevent it from sticking from
410 the node. When it fails, the text will be either cropped or too small.
411 %
412 \begin{codeexample}[code only]
413 \tikz \node[draw,/pgf/tex4ht node/escape=true]
414 {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$};
415 \end{codeexample}
416 %
417 \end{key}
418
419 \begin{key}{/pgf/tex4ht node/css=\meta{filename} (default |\string\jobname|)}
420 This option allows you to tell the browser what \textsc{css} file it
421 should use to style the display of the node (only with
422 |tex4ht node/escape=true|).
423 \end{key}
424
425 \begin{key}{/pgf/tex4ht node/class=\meta{class name} (default foreignobject)}
426 This option allows you to give a class name to the node, allowing it to
427 be styled by a \textsc{css} file (only with |tex4ht node/escape=true|).
428 \end{key}
429
430 \begin{key}{/pgf/tex4ht node/id=\meta{id name} (default |\string\jobname\ picture number-node number|)}
431 This option allows you to give a unique id to the node, allowing
432 it to be styled by a \textsc{css} file (only with
433 |tex4ht node/escape=true|).
434 \end{key}
435 \end{filedescription}
436
437
438 \subsubsection{Producing Perfectly Portable DVI Output}
439
440 \begin{filedescription}{pgfsys-dvi.def}
441 This is a driver file that can be used with any output driver, except for
442 |tex4ht|.
443
444 The driver will produce perfectly portable |.dvi| files by composing all
445 pictures entirely of black rectangles, the basic and only graphic shape
446 supported by the \TeX\ core. Even straight, but slanted lines are tricky to
447 get right in this model (they need to be composed of lots of little
448 squares).
449
450 Naturally, \emph{very little} is possible with this driver. In fact, so
451 little is possible that it is easier to list what is possible:
452 %
453 \begin{itemize}
454 \item Text boxes can be placed in the normal way.
455 \item Lines and curves can be drawn (stroked). If they are not
456 horizontal or vertical, they are composed of hundreds of small
457 rectangles.
458 \item Lines of different width are supported.
459 \item Transformations are supported.
460 \end{itemize}
461 %
462 Note that, say, even filling is not supported! (Let alone color or anything
463 fancy.)
464
465 This driver has only one real application: It might be useful when you only
466 need horizontal or vertical lines in a picture. Then, the results are quite
467 satisfactory.
468 \end{filedescription}