diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse1.html')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse1.html | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse1.html b/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse1.html new file mode 100644 index 00000000000..90394a61cc6 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-tex4ht/en/pgfmanualse1.html @@ -0,0 +1,460 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html > +<head><title>1 Introduction</title> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<meta name="generator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)"> +<meta name="originator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)"> +<!-- html --> +<meta name="src" content="pgfmanual.tex"> +<meta name="date" content="2005-10-23 18:34:00"> +<link rel="stylesheet" type="text/css" href="pgfmanual.css"> +</head><body +> + <div class="crosslinks"><p class="noindent">[<a +href="pgfmanualse2.html" >next</a>] [<a +href="#tailpgfmanualse1.html">tail</a>] [<a +href="pgfmanual.html#pgfmanualse1.html" >up</a>] </p></div> + <h3 class="sectionHead"><span class="titlemark">1 </span> <a + id="x2-30001"></a>Introduction</h3> +<!--l. 11--><p class="noindent">The <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> package, where “<span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>” is supposed to mean “portable graphics format” (or “pretty, good, functional” if +you prefer...), is a package for creating graphics in an “inline” manner. The package defines a number of +<span class="TEX">T<span +class="E">E</span>X</span> commands that draw graphics. For example, the code <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\tikz</span><span +class="cmtt-10"> \draw</span><span +class="cmtt-10"> (0pt,0pt)</span><span +class="cmtt-10"> --</span><span +class="cmtt-10"> (20pt,6pt);</span></span></span> yields the +line <object data="pgfmanual-3.svg" width="20.4pt" height="6.4pt" type="image/svg+xml"><p>SVG-Viewer needed.</p></object> and the code <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\tikz</span><span +class="cmtt-10"> \fill[orange]</span><span +class="cmtt-10"> (1ex,1ex)</span><span +class="cmtt-10"> circle</span><span +class="cmtt-10"> (1ex);</span></span></span> yields <object data="pgfmanual-4.svg" width="8.61108pt" height="8.61108pt" type="image/svg+xml"><p>SVG-Viewer needed.</p></object>. +<!--l. 20--><p class="indent"> In a sense, when using <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> you “program” your graphics, just as you “program” your document +when using <span class="TEX">T<span +class="E">E</span>X</span>. This means that you get the advantages of the “<span class="TEX">T<span +class="E">E</span>X</span>-approach to typesetting” +also for your graphics: quick creation of simple graphics, precise positioning, the use of macros, often +superior typography. You also inherit all the disadvantages: steep learning curve, no <span +class="cmcsc-10"><small +class="small-caps">W</small><small +class="small-caps">Y</small><small +class="small-caps">S</small><small +class="small-caps">I</small><small +class="small-caps">W</small><small +class="small-caps">Y</small><small +class="small-caps">G</small></span>, small +changes require a long recompilation time, and the code does not really “show” how things will look +like. +<!--l. 31--><p class="noindent"> + <h4 class="subsectionHead"><span class="titlemark">1.1 </span> <a + id="x2-40001.1"></a>Structure of the System</h4> +<!--l. 33--><p class="noindent">The <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> system consists of different layers: +<!--l. 35--><p class="indent"> + <dl class="description"><dt class="description"> +<span +class="cmbx-10">System layer:</span> </dt><dd +class="description">This layer provides a complete abstraction of what is going on “in the driver.” The driver + is a program like <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">dvips</span></span></span> or <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">dvipdfm</span></span></span> that takes a <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.dvi</span></span></span> file as input and generates a <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.ps</span></span></span> or a <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.pdf</span></span></span> file. + (The <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pdftex</span></span></span> program also counts as a driver, even though it does not take a <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.dvi</span></span></span> file as input. Never + mind.) Each driver has its own syntax for the generation of graphics, causing headaches to everyone + who wants to create graphics in a portable way. <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>’s system layer “abstracts away” these differences. + For example, the system command <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\pgfsys@lineto{10pt}{10pt}</span></span></span> extends the current path to the + coordinate (10pt<span +class="cmmi-10">,</span>10pt) of the current <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{pgfpicture}</span></span></span>. Depending on whether <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">dvips</span></span></span>, <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">dvipdfm</span></span></span>, or + <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pdftex</span></span></span> is used to process the document, the system command will be converted to different <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\special</span></span></span> + commands. + <!--l. 51--><p class="noindent">The system layer is as “minimalistic” as possible since each additional command makes it more work to + port <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> to a new driver. Currently, only drivers that produce PostScript or <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">D</small><small +class="small-caps">F</small> </span>output are supported + and only few of these (hence the name <span +class="cmti-10">portable </span>graphics format is currently a bit boastful). However, + in principle, the system layer could be ported to many different drivers quite easily. It should even be + possible to produce, say, <span +class="cmcsc-10"><small +class="small-caps">S</small><small +class="small-caps">V</small><small +class="small-caps">G</small> </span>output in conjunction with <span +class="cmcsc-10"><small +class="small-caps">T</small><small +class="small-caps">E</small><small +class="small-caps">X</small>4<small +class="small-caps">H</small><small +class="small-caps">T</small></span>. + <!--l. 61--><p class="noindent">As a user, you will not use the system layer directly. + </dd><dt class="description"> +<span +class="cmbx-10">Basic layer:</span> </dt><dd +class="description">The basic layer provides a set of basic commands that allow you to produce complex graphics + in a much easier way than by using the system layer directly. For example, the system layer provides no + commands for creating circles since circles can be composed from the more basic Bézier curves (well, + almost). However, as a user you will want to have a simple command to create circles (at least I do) + instead of having to write down half a page of Bézier curve support coordinates. Thus, the basic layer + provides a command <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\pgfpathcircle</span></span></span> that generates the necessary curve coordinates for you. + <!--l. 74--><p class="noindent">The basic layer is consists of a <span +class="cmti-10">core</span>, which consists of several interdependent packages that can only be + loaded <span +class="cmti-10">en bloc, </span>and additional packages that extend the core by more special-purpose commands like + node management or a plotting interface. For instance, the <span +class="cmcsc-10"><small +class="small-caps">B</small><small +class="small-caps">E</small><small +class="small-caps">A</small><small +class="small-caps">M</small><small +class="small-caps">E</small><small +class="small-caps">R</small> </span>package uses the core, but not all + of the additional packages of the basic layer. + </dd><dt class="description"> +<span +class="cmbx-10">Frontend layer:</span> </dt><dd +class="description">A frontend (of which there can be several) is a set of commands or a special syntax that makes + using the basic layer easier. A problem with directly using the basic layer is that code written for this layer is + often too “verbose.” For example, to draw a simple triangle, you may need as many as five commands when + using the basic layer: One for beginning a path at the first corner of the triangle, one for extending the path to + the second corner, one for going to the third, one for closing the path, and one for actually painting the + triangle (as opposed to filling it). With the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">tikz</span></span></span> frontend all this boils down to a single simple <span +class="cmcsc-10"><small +class="small-caps">M</small><small +class="small-caps">E</small><small +class="small-caps">T</small><small +class="small-caps">A</small><small +class="small-caps">F</small><small +class="small-caps">O</small><small +class="small-caps">N</small><small +class="small-caps">T</small></span>-like + command: + + + <table width="100%" +class="verbatim"><tr class="verbatim"><td +class="verbatim"><div class="verbatim"> + \draw (0,0) -- (1,0) -- (1,1) -- cycle; +</div> + </td></tr></table> + <!--l. 94--><p class="nopar"> + <!--l. 96--><p class="noindent">There are different frontends: + <ul class="itemize1"> + <li class="itemize">The Ti<span +class="cmti-10">k</span>Z frontend is the “natural” frontend for <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>. It gives you access to all features of <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>, + but it is intended to be easy to use. The syntax is a mixture of <span +class="cmcsc-10"><small +class="small-caps">M</small><small +class="small-caps">E</small><small +class="small-caps">T</small><small +class="small-caps">A</small><small +class="small-caps">F</small><small +class="small-caps">O</small><small +class="small-caps">N</small><small +class="small-caps">T</small> </span>and <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">S</small><small +class="small-caps">T</small><small +class="small-caps">R</small><small +class="small-caps">I</small><small +class="small-caps">C</small><small +class="small-caps">K</small><small +class="small-caps">S</small> </span>and + some ideas of myself. This frontend is <span +class="cmti-10">neither </span>a complete <span +class="cmcsc-10"><small +class="small-caps">M</small><small +class="small-caps">E</small><small +class="small-caps">T</small><small +class="small-caps">A</small><small +class="small-caps">F</small><small +class="small-caps">O</small><small +class="small-caps">N</small><small +class="small-caps">T</small> </span>compatibility layer nor a + <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">S</small><small +class="small-caps">T</small><small +class="small-caps">R</small><small +class="small-caps">I</small><small +class="small-caps">C</small><small +class="small-caps">K</small><small +class="small-caps">S</small> </span>compatibility layer and it is not intended to become either. + </li> + <li class="itemize">The <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgfpict2e</span></span></span> frontend reimplements the standard <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span +class="E">E</span>X</span></span> <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> environment and + commands like <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\line</span></span></span> or <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">\vector</span></span></span> using the <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> basic layer. This layer is not really “necessary” + since the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pict2e.sty</span></span></span> package does at least as good a job at reimplementing the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> + environment. Rather, the idea behind this package is to have a simple demonstration of how a + frontend can be implemented.</li></ul> + <!--l. 116--><p class="noindent">It would be possible to implement a <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgftricks</span></span></span> frontend that maps <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">S</small><small +class="small-caps">T</small><small +class="small-caps">R</small><small +class="small-caps">I</small><small +class="small-caps">C</small><small +class="small-caps">K</small><small +class="small-caps">S</small> </span>commands to <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> commands. + However, I have not done this and even if fully implemented, many things that work in <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">S</small><small +class="small-caps">T</small><small +class="small-caps">R</small><small +class="small-caps">I</small><small +class="small-caps">C</small><small +class="small-caps">K</small><small +class="small-caps">S</small></span> will not + work, namely whenever some <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">S</small><small +class="small-caps">T</small><small +class="small-caps">R</small><small +class="small-caps">I</small><small +class="small-caps">C</small><small +class="small-caps">K</small><small +class="small-caps">S</small></span> command relies too heavily on PostScript trickery. Nevertheless, such + a package might be useful in some situations.</dd></dl> +<!--l. 124--><p class="indent"> As a user of <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> you will use the commands of a frontend plus perhaps some commands of the basic layer. +For this reason, this manual explains the frontends first, then the basic layer, and finally the system +layer. +<!--l. 131--><p class="noindent"> + <h4 class="subsectionHead"><span class="titlemark">1.2 </span> <a + id="x2-50001.2"></a>Comparison with Other Graphics Packages</h4> +<!--l. 133--><p class="noindent">There were two main motivations for creating <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>: + <ol type="1" class="enumerate1" > + <li class="enumerate" value="1" +><a + id="x2-5002x1"></a>The standard <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span +class="E">E</span>X</span></span> <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> environment is not powerful enough to create anything but really + simple graphics. This is certainly not due to a lack of knowledge or imagination on the part of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span +class="E">E</span>X</span></span>’s + designer(s). Rather, this is the price paid for the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> environment’s portability: It works together + with all backend drivers. + </li> + <li class="enumerate" value="2" +><a + id="x2-5004x2"></a>The <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{pstricks}</span></span></span> package is certainly powerful enough to create any conceivable kind of graphic, but it + is not portable at all. Most importantly, it does not work with <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pdftex</span></span></span> nor with any other driver that + produces anything but PostScript code.</li></ol> +<!--l. 149--><p class="indent"> The <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> package is a trade-off between portability and expressive power. It is not as portable as <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> and +perhaps not quite as powerful as <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{pspicture}</span></span></span>. However, it is more powerful than <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{picture}</span></span></span> and more portable +than <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">{pspicture}</span></span></span>. +<!--l. 154--><p class="noindent"> + <h4 class="subsectionHead"><span class="titlemark">1.3 </span> <a + id="x2-60001.3"></a>Utilities: Page Management</h4> +<!--l. 156--><p class="noindent">The <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> package include a special subpackage called <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgfpages</span></span></span>, which is used to assemble several pages into a single +page. This package is not really about creating graphics, but it is part of <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> nevertheless, mostly because its +implementation uses <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> heavily. + + +<!--l. 161--><p class="indent"> The subpackage <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgfpages</span></span></span> provides commands for assembling several “virtual pages” into a single “physical +page.” The idea is that whenever <span class="TEX">T<span +class="E">E</span>X</span> has a page ready for “shipout,” <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgfpages</span></span></span> interrupts this shipout and +instead stores the page to be shipped out in a special box. When enough “virtual pages” have been accumulated in +this way, they are scaled down and arranged on a “physical page,” which then <span +class="cmti-10">really </span>shipped out. This mechanism +allows you to create “two page on one page” versions of a document directly inside <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span +class="E">E</span>X</span></span> without the use of any +external programs. +<!--l. 171--><p class="indent"> However, <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgfpages</span></span></span> can do quite a lot more than that. You can use it to put logos and watermark on pages, print +up to 16 pages on one page, add borders to pages, and more. +<!--l. 178--><p class="noindent"> + <h4 class="subsectionHead"><span class="titlemark">1.4 </span> <a + id="x2-70001.4"></a>How to Read This Manual</h4> +<!--l. 180--><p class="noindent">This manual describes both the design of the <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> system and its usage. The organization is very roughly according +to “user-friendliness.” The commands and subpackages that are easiest and most frequently used are described first, +more low-level and esoteric features are discussed later. +<!--l. 186--><p class="indent"> If you have not yet installed <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span>, please read the installation first. Second, it might be a good idea to read the +tutorial. Finally, you might wish to skim through the description of Ti<span +class="cmti-10">k</span>Z. Typically, you will not need to read the +sections on the basic layer. You will only need to read the part on the system layer if you intend to write your own +frontend or if you wish to port <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> to a new driver. +<!--l. 193--><p class="indent"> The “public” commands and environments provided by the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">pgf</span></span></span> package are described throughout the text. In +each such description, the described command, environment or option is printed in red. Text shown in green is +optional and can be left out. +<!--l. 200--><p class="noindent"> + <h4 class="subsectionHead"><span class="titlemark">1.5 </span> <a + id="x2-80001.5"></a>Getting Help</h4> +<!--l. 202--><p class="noindent">When you need help with <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> and Ti<span +class="cmti-10">k</span>Z, please do the following: +<!--l. 205--><p class="indent"> + <ol type="1" class="enumerate1" > + <li class="enumerate" value="1" +><a + id="x2-8002x1"></a>Read the manual, at least the part that has to do with your problem. + </li> + <li class="enumerate" value="2" +><a + id="x2-8004x2"></a>If that does not solve the problem, try having a look at the sourceforge development page for <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> and + Ti<span +class="cmti-10">k</span>Z (see the title of this document). Perhaps someone has already reported a similar problem and + someone has found a solution. + </li> + <li class="enumerate" value="3" +><a + id="x2-8006x3"></a>On the website you will find numerous forums for getting help. There, you can write to help forums, + file bug reports, join mailing lists, and so on. + </li> + <li class="enumerate" value="4" +><a + id="x2-8008x4"></a>Before you file a bug report, especially a bug report concerning the installation, make sure that this + is really a bug. In particular, have a look at the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.log</span></span></span> file that results when you <span class="TEX">T<span +class="E">E</span>X</span> your files. This + <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.log</span></span></span> file should show that all the right files are loaded from the right directories. Nearly all installation + problems can be resolved by looking at the <span class="obeylines-h"><span class="verb"><span +class="cmtt-10">.log</span></span></span> file. + </li> + <li class="enumerate" value="5" +><a + id="x2-8010x5"></a><span +class="cmti-10">As a last resort </span>you can try to email me (the author). I do not mind getting emails, I simply get + way too many of them. Because of this, I cannot guarantee that your emails will be answered timely + or even at all. Your chances that your problem will be fixed are somewhat higher if you mail to the + <span +class="cmcsc-10"><small +class="small-caps">P</small><small +class="small-caps">G</small><small +class="small-caps">F</small></span> mailing list (naturally, I read this list and answer questions when I have the time). + </li> + <li class="enumerate" value="6" +><a + id="x2-8012x6"></a>Please, do not phone me in my office. If you need a hotline, buy a commercial product.</li></ol> + + + + + + + <div class="crosslinks"><p class="noindent">[<a +href="pgfmanualse2.html" >next</a>] [<a +href="pgfmanualse1.html" >front</a>] [<a +href="pgfmanual.html#pgfmanualse1.html" >up</a>] </p></div> +<!--l. 8--><p class="indent"> <a + id="tailpgfmanualse1.html"></a> +</body></html> |