summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex
diff options
context:
space:
mode:
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.tex654
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}