diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex | 654 |
1 files changed, 306 insertions, 348 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex index 3674f2f86d9..e107e8f097a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex @@ -11,43 +11,38 @@ \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. - +\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. +\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. +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} +\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. +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|: - +|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 2006 by Till Tantau % @@ -69,423 +64,386 @@ content of the file |latex/pgf/frontends/tikz.sty|: 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. +|\end{pgfpicture}| you use |\pgfpicture| and |\endpgfpicture|. -Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex| -also just include the correct |tikz.code.tex| file. +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 +|\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 Con\TeX t -satanically restricts the length of module names to 6 characters -and \pgfname's long names are mapped -to cryptic 6-letter-names for you by the module |pgfmod|. - - - +satanically restricts the length of module names to 6 characters and \pgfname's +long names are mapped to cryptic 6-letter-names for you by the module |pgfmod|. \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: +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. + \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. +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 +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. +|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. +``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 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. + 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} + 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. + 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 - Shading is fully implemented, but yields the same quality as the - implementation for |dvips|. - \item - Opacity is not supported. - \item - Remembering of pictures (inter-picture connections) is not - supported. - \end{enumerate} + 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 Shading is fully implemented, but yields the same quality as + the implementation for |dvips|. + \item Opacity is 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 the Acrobat Distiller. +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. - \item - For remembering of pictures (inter-picture connections) you need - to use a recent version of |pdftex| running in DVI-mode. - \end{enumerate} + 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. + \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 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|. + 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. - +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. + 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 +% 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{document} \end{codeexample} - And then run + And then run + % \begin{codeexample}[code only] latex example -dvisvgm example +dvisvgm example \end{codeexample} - or better + % + or better + % \begin{codeexample}[code only] lualatex --output-format=dvi example -dvisvgm 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.) + % + (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. + 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: + 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 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. + \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} - If you use text that contains anything special, even something as - simple as |$\alpha$|, this may corrupt the graphic. + 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. + \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{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. + 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} |