diff options
| author | Karl Berry <karl@freefriends.org> | 2014-02-27 00:01:50 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2014-02-27 00:01:50 +0000 |
| commit | 90ae413a94da014dbf7a6a8ab584f7c668483a5a (patch) | |
| tree | 4e0528a2b2fb2004988e7fc804ea2f1354f1f5d5 /Master/texmf-dist/doc/generic/pgf | |
| parent | 800cc56380d1edfe567a6a66bef13e8950eb2b0c (diff) | |
pgf 3.0.0
git-svn-id: svn://tug.org/texlive/trunk@33057 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf')
141 files changed, 30200 insertions, 8907 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/ChangeLog b/Master/texmf-dist/doc/generic/pgf/ChangeLog index 6b0704d18ca..d4dc120c045 100644 --- a/Master/texmf-dist/doc/generic/pgf/ChangeLog +++ b/Master/texmf-dist/doc/generic/pgf/ChangeLog @@ -1,3 +1,1098 @@ +2013-12-20 Till Tantau <tantau@users.sourceforge.net> + + - Release 3.0.0! + +2013-12-20 Till Tantau <tantau@users.sourceforge.net> + + - In preparation for the release 3.0.0, I pimped the manual a + bit. It will now automatically detect whether graph drawing + C libs are available or not. Also, syntax hilighting is now + always switched on. I also some subtle optical hints to + crossreferenced words in the code examples; this is pretty + useful, I think. + - Did a lot of cleaning up for the release. + +2013-12-18 Till Tantau <tantau@users.sourceforge.net> + + - Fixed a bug in Vertex.lua that returned wrong anchor + positions for non-centered vertices. + +2013-12-13 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #280 "Layered layout" produces unknown key with graphs library. + - Fixed bug #279 "Some parts of arguments in foreach macro are lost". + - Fixed bug #258 "Default arrow edge style puts circumflex in + drawn end node" by now allowing people to say tip=on proper draw. + +2013-12-08 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - intersections lib: ensured that 'name path global' is reset between main paths. + +2013-11-30 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - worked on intersections lib (internals only); added O(N) list + append/prepend utilities + +2013-11-18 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Added keys 'rotate around x', 'rotate around y' and + 'rotate around z' to rotate the xyz coordinate system + around the x, y, or z axis. + +2013-11-17 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Fixes for 'text effects along path' decoration and docs. + +2013-11-16 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - external lib: added support for 'up to date check=md5' for lualatex. + Now, lualatex and pdftex both result in the same checksums (by means of + \usepackage{pdftexcmds}) + +2013-11-16 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Finalised 'text effects along path' decoration and docs. + +2013-11-11 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Changed keyval example (and references to define@key) + in pgfcalendar documentation to pgfkeys stuff. + +2013-11-08 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Minor fixes to decorations.text and math libraries documentation + +2013-11-07 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Added 'text effects along path' decoration. + +2013-11-01 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - Fixed regression/bug in 'name path global'. + +2013-10-31 Till Tantau <tantau@users.sourceforge.net> + + - Applied path for bug #277 "\beforeforegroundpath not working". + +2013-10-09 Till Tantau <tantau@users.sourceforge.net> + + - Prepared manual for new release (fixed overful boxes and + index problems). + +2013-10-08 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Updated math library (minor fixes). + +2013-10-07 Till Tantau <tantau@users.sourceforge.net> + + - Applied some fixes so that C code for graph drawing works + once more. + - Arrow tips and their doc are now officially finished! + - Added documentation of nonlinear transformations. + +2013-10-06 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - modified release script to allow uploads of unstable TDS + zips to http://pgf.sourceforge.net using + make -f pgf/scripts/pgf/Makefile.pgf_release upload USER=cfeuersaenger + +2013-10-02 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Fixed problem with math parser inserting extraneous + spaces when parsing \dimenexpr + +2013-09-30 Till Tantau <tantau@users.sourceforge.net> + + - Changed blend mode syntax to standard pgf syntax (since PDF + and SVG do not agree on names...). + - Added scale and slant options for arrow tips. + - Added more generic arrow tips. + +2013-09-24 Till Tantau <tantau@users.sourceforge.net> + + - First version of comlete arrow documentation finished. Still + need to document the arrows.meta library, though. + - Added "tips" option for drawing arrow tips without drawing + paths. + +2013-09-23 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #273 "Graph drawing sublayouts fails". + - Incorporated first partial documentation of the arrow tips + into the main documentation. + - Fixed bug bugs:#272 "SVG parser error after close path" as + suggested by Mark Wibrow. + - Also changed the default syntax for svg path command so that + it uses braces instead of quotation marks. (Quotation marks + still work, of course.) + +2013-09-22 Till Tantau <tantau@users.sourceforge.net> + + - Started working on arrow doc. + +2013-09-20 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Added macro to convert string of digits to comma separated list. + +2013-09-18 Till Tantau <tantau@users.sourceforge.net> + + - First version of new arrow tip management done. Up and + running! Still needs documentation and the old arrow tip + codes should (but need not) be ported. + - Did some porting of old code, added fixes. Doc still missing. + +2013-09-17 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #264: "\pgfkeys /errors/unknown key should (?) expand first argument" + - Fixed bug #268: "`matrix of nodes' isn't working properly any more" + +2013-09-11 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Corrected typos (bug #266 and bug #265) + +2013-09-11 Mark Wibrow <vibrovski@users.sourceforge.net> + + - added magnetic tape shape. + +2013-09-09 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #262/267: "Line breaks are not working in labels anyy more." + - Fixed bug #260: "TikZ node on background in pgfextra" + - Started work on bending arrows. + +2013-09-05 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - external lib: fixed bug: file dependency handling was incorrect and + suffered from regression caused by MD5 checks + +2013-08-31 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - repaired incompatibility with pgfplots <= 1.8: samples key was + evaluated in context of floating point unit and new pgf code relied on dimension + registers. + +2013-08-29 Till Tantau <tantau@users.sourceforge.net> + + - Added "turn" key. + +2013-08-28 Till Tantau <tantau@users.sourceforge.net> + + - Added "angle" pic type and "angles" library. + - Patched gd loader code so that it works with context mark IV. + +2013-08-27 Till Tantau <tantau@users.sourceforge.net> + + - Added new pic path command. + - Patched pgfsys-dvipdfmx.def to step around the bug in + (x)dvipdfmx that caused scaled boxes (including scaled + graphics) inside nodes to be displayed incorrectly. + +2013-08-24 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - fixed bug in fpu: 0^0 and 0^x both produced nan. Now we get + 0^0=1 and 0^x = 0. + +2013-08-22 Till Tantau <tantua@users.sourceforge.net> + + - Removed claims from manual (not by me...) that TikZ does not + work with Mark IV of context. I just tried it and everything + I tried (including advanced stuff like shadings) worked fine. + +2013-08-18 Mark Wibrow <vibrovski@users.sourceforge.net> + + - Fixed pgf intersection library to ensure that + specialround tokens are processed. + +2013-08-06 Till Tantau <tantua@users.sourceforge.net> + + - Added support for dvisvgm. Quite nice... + +2013-08-05 Till Tantau <tantua@users.sourceforge.net> + + - Worked on tex4ht code. Works reasonably well know and even + graph drawing is possible (when luatex is used for + typesetting; for this I needed to fix some latin1 characters in + html4.4ht). Also, I renamed /tikz/tex4ht... to /pgf/tex4ht + (someone else added that) since tikz has nothing to do with + that stuff. + Typesetting the manual in tex4ht no longer works, but that seems + like too much bother for my taste. + +2013-08-02 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #256 "The special \pgfcoordinate macro doesn't + expand \pgfpictureid." + +2013-08-04 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - external lib: fixed incompatibility of pdflscape with + external lib + +2013-08-01 Till Tantau <tantua@users.sourceforge.net> + + - Fixed a problem with pdf resources of transparency groups in + dvipdfmx. + +2013-07-31 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #149 "/tikz/raw gnuplot ignoring segmented plot" + by introducing a new way of handling plot streams. There are + now new kinds of points (outliers and undefined points) and + "new data sets" commands inside streams. Handlers (like the + lineto and curve handlers) can be configured to interpret + these as jumps (this is the default). + - Fixed bug #255 "Trig computations offend fp via fixedpointarithmetic lib" + +2013-07-31 Mark Wibrow <vibrovski@users.sourceforge.net> + - Added "math" library. Could be integrated with calc library. + +2013-07-26 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - Fixed bug in external lib: mode=list and make did not cope well with + \ref in externalized images. These will be remade now. + +2013-07-24 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #162 "PGF manual examples use undefined "shape example" style" + - Fixed bug #169 "ghostscript error: /undefined in pgfo" + - Concerning bug #167 "node pin option sets + inconsistent/incorrect angle" I added some clarification in + the manual that explains the observed behaviour. + - Fixed bug #158 "\pgfmathparse does not support e-TeXs + \numexpr and \dimexpr". You can now also use + \pgfmathsetlength to assign a muskip a value. Internally, + "mu" is treated like "pt", but if an expression contains + "mu", \pgfmathsetlength and \pgfmathaddtolength will convert + the number to "mu" before the assignment. + +2013-07-22 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #173 "Tikz's transparency, xelatex and preview + package" by adding a specific fix for the interaction + between preview.sty and everyshi.sty in pgfutil-latex.def. + +2013-07-19 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - optimized mark=* and mark=o (q path versions lead to 10% time reduction) + - adopted new pgfkeys feature to /handler config/full or existing ( + required when /.search also is used to find the correct key path) + +2013-07-19 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #175 "In PGF oo module, calling a method strips grouping" + - Fixed bug #181 "Need to document |- coordinates using calc notation" + - Fixed bug #187 "\pgfmathanglebetweenpoints is not documented" + - Increased accuracy of atan, atan2 and + \pgfmathanglebetweenpoints. + +2013-07-18 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug "#168 PGF is sensitive to dollar catcode" + - Fixed bug "#186 pgfonlayer makes pgf forget options" and + added "every on background layer" option. + - Fixed bug "#192 pgffor scope iteration is buggy" + - Fixed bug "#196 Incoherent syntax for Bézier curves" + - Fixed bug "#199 Drawing error for chamfered rectangle" + - Fixed bug "#201 Markings fail with "Dimension too Large" on + certain paths" by fixing a mistake and the decoration core + and, additionally, in pgfmathanglebetweenpoints. + - Fixed bug "#254 building currenct CVS version fails on + graphdrawing with current luatex": Will now work nicely with + TeXLive 2013 and Lua 5.2. + - Added feature request "bug #203 Blending modes and better transparency" + +2013-07-17 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #204 "strange influence of \baselinestretch on + tikz figure" by no longer sharing \pgfutil@tempa with latex: + This register gets changed by LaTeX in a fontchange, which, in + turn can happen at the beginning of every + \pgfmathsetlength. + - Fixed bug #207 "Decoration markings not on path on large + lines" by using a more precise computation of positions on + straight lines in decorations. Also, the angle computation + is now much more precise by fixedin bug #201. + - Fixed bug #212 "Error if using plot into a \foreach loop in + a single path" by making \pgffor@beginhook and friends local + to the current \foreach. A nice side-effect is that one can + now nest \foreach statements on a path and also mix in the + plots. Hopefully, no one relied on the (undocumented, + unsupported) old bevahiour of the hooks. + - Fixed bug #213 "pgfmathsetcounter only works in local scope" + by adding a note in the documentation. + - Fixed bug #211 "\nodepart ignores text transparency" + - Fixed bug #220 "Transformations ignored in edge decoration." + - Fixed bug #221 "xyz spherical and cylindrical coordinate, radius not defined" + - Fixed bug #225 "pgfkeys "/errors/unknown choice value" ignores parameters" + - Fixed bug #253 "\pgfkeysfiltered cannot accept long arguments" + - Fixed bug #252 "I'm not able to build the current CVS + version". This included a number of patches to fix problems + introduced with the bugfixes introduced recently + +2013-07-16 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug #226 "matrix column sep=-\pgflinewidth changes after empty cell" + - Fixed bug #229 "pgfpagesuselayout breaks beamer class" + (hopefully, setting page sizes is really messy in TeX!). + - Fixed bug #232 "pow function broken for 0^x for non-integer values of x" + - Fixed bug #165 "\draw with empty domain results in infinite calculation" + - Added better error message to adress bug #244 "mindmap-style + "invalidates" coordinate shape." + - Fixed bug #235 "\def\costhirty{0.8660256} not really used" + +2013-07-15 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug "#237 CVS-version: pdfimage error: key interpolate undefined" + - Fixed bug "#245 broken key /pgf/decoration/reset marks" + - Fixed bug "#239 picture disappear after a zero-width rectangle width shading" + - Fixed bug "#247 Error messages hard to catch in plain TeX/ConTeXt" + - Fixed bug "#166 Possibly typos in circuits.logic.IEC" + - Fixed bug "#249 pgfkeys: /handlers/first char syntax is not + 'self-contained' (CVS version)" + - Fixed bug "#248 circuits adjustable annotation improperly placed" + +2013-07-13 Till Tantau <tantua@users.sourceforge.net> + + - Fixed bug "#250 pgfkyes: .append style and similar undouble # tokens" + - Fixed bug "#143 label changes center of a matrix node" + +2013-07-12 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #128 "fit does not scale if used in scaled scope" + - Fixed bug #136 "\hrulefill inherits or not pgf line styles" + - Fixed bug #224 "Including Tikzpicture in third part of + multipart node" + +2013-07-11 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #251 "cross out shape interacts with path options of path it is drawn on" + - Fixed bug #139 "Placement of node inside matix environment" + - Fixed bug #131 "text centering calculates wrong" and added + new "node font" option. + - Fixed bug #121 "Annoying "Underfull \hbox (badness 10000)" message" + - Fixed bug #134 "Edge node style affecting arrowhead". + +2013-07-08 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #132 "Error in matrix with column sep "between" + origins" + - Fixed bug #133 "\draw[-<<,>=stealth] (10,45) -- (40,45); does + not work." However, this introduces a (small, only visual) + incompatibility with previous versions. If you need the visual + effect "-<<" used to have (which, in a sense, was wrong), use + "-< <" instead. The new "-> >" is also quite handy. + +2013-06-28 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #116 "Decorations can't be repositioned when + pre/post used." + +2013-06-25 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #241 "div/null error by (270:length) and a fading line." + - Fixed bug #126 "Incorrect placed labels for inplicite positioned nodes." + - Added foreach syntax to nodes. This is useful and also + needed to fix the problem that the foreach statement cannot + be used after a to path. + +2013-06-24 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #18 and #74 (active characters and tikz) by virtue + of the new "babel" library, which deactivates catcodes at the + beginning of tikz pictures and reactivates them in nodes. + +2013-06-21 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #110 "cannot add node after cycle operation" + - Fixed bug #88 "\pgftransformarrow does not rotate with \pgfpointanchor" + - Fixed bug #86 "macro-expanded tree node has bad edge anchor" + - Fixed bug #85 "PGF + Crop package, at least for pdftex." + +2013-06-20 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #83 "Transparency Problem with \usepackage{endfloat}." + - Applied patch #19 pgfkeys: ".search also" fails at unbalanced "\if" values + - Applied patch #18 Missing grid lines with + negative increment + - Applied patch #17 TikZ folding library + - Applied patch #14 inheritance in the oo module + - Applied patch #13 leaking space in \pgfpointintersectionoflines + - Applied patch #11 Patch for Bug #3165961 (\pgfmathmax and \pgfmathmin) + - Fixed problem of patch #9 Add papersize to XeTeX driver + - Applied patch #8 Support for changing physical page size with XeTeX + (also added position saving support, while I was at it...) + - Applied patches #3, #4, #5, #6 (typos in manual) as far as possible + +2013-06-18 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #236 "Scaled closed paths, start/end points dont exactly match": + "cycle" can now be used with all path operations where it + makes sense, not only with --. In particular, things like + ".. cycle" or "to [bend right] cycle" are now allowed. + +2013-05-23 Till Tantau <tantau@users.sourceforge.net> + + - Reworked handling of edge and vertex paths in gd. In + particular, edge--vertex intersections are now computed in + Lua, rather than in TikZ. This is much more powerful and + allows beautiful arcs between vertices. It is also very + useful for planar graph drawings when several edges leave a + vertex in the same direction. + +2013-04-08 Till Tantau <tantau@users.sourceforge.net> + + - Did away with luadoc, now using simple handcoded documentor + that will also work with Lua 5.2 + - Redid OGDF support. Resonably stable base now. + - Added better C support. + - Should now work with both Lua 5.1 and 5.2 + +2013-03-15 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - fixed incompatibility of fixltx2e and external lib + +2013-02-08 Till Tantau <tantau@users.sourceforge.net> + + - Reworked Storage mechanism of graph drawing system. + - Added phylogenetics library for graph drawing; documentation + still only rudimentary. + +2012-12-30 Till Tantau <tantau@users.sourceforge.net> + + - Started adding support for calling C graph drawing functions + from Lua. + - First proof of concept for OGDF finished. + - Must still address luatex shared library link problems. + +2012-12-25 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - fixed bug in external lib: \tikzexternalgetnextfilename did reset the + value of \tikzsetnextfilename and 'export next' + +2012-11-30 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - updated driver pgfsys-xetex: now, it supports all that the new driver + for dvipdfmx does which includes fadings, functional shadings, and + patterns. + +2012-11-30 Till Tantau <tantau@users.sourceforge.net> + + - First complete documentation of the graph drawing + system. (Finally!) + +2012-11-27 Till Tantau <tantau@users.sourceforge.net> + + - Renamed gd files to shorter versions: instead of + pgf/gd/model/pgf.gd.model.Edges.lua we now have + pgf/gd/model/Edge.lua and so on. + - Worked on gd documentation. Only binding doc is still a + mess. + +2012-11-26 Till Tantau <tantau@users.sourceforge.net> + + - Worked on gd documentation. + +2012-11-21 Till Tantau <tantau@users.sourceforge.net> + + - New version of gd lib. The internals have been completely + redone. In particular, no tikz libraries are needed for the + individual algorithms any longer, all declarations are now + done completely inside Lua. This makes gd usable (in + principle) independently of tikz and pgf. + - Because of this, all declarations of algorithms need to be + redone. + +2012-11-10 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - external lib: fixed spurious white space (caused by 'up to date check') + +2012-11-01 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - manual styles: improved robustness of auto cross references & active spaces + +2012-10-18 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fixed a bug with active colon in circuits lib. Probably more to + fix in other libraries. + +2012-10-11 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + + - Improved precision of math functions asin and acos (using linear + interpolation instead of constant interpolation) + +2012-09-27 Till Tantau <tantau@users.sourceforge.net> + + - Worked on gd. + +2012-09-26 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + - fixed pgfsys-pdftex.def : very old regression with \setbeamercovered{transparent} and \pause + Patch by Hendrik Vogt + +2012-08-29 Till Tantau <tantau@users.sourceforge.net> + + - Added support for sublayouts in gd (not yet fully + documented). This allows one to use several algorithms inside + a single graph. + +2012-06-28 Till Tantau <tantau@users.sourceforge.net> + + - Redone handling of clusters in gd yet again. Renamed them to + "collections". Much better system now, can handle hyperedges, + subgraphs and other stuff (in principle). + - Nodes generated by a gd algorithm now have correct size + information (this one was tricky!). + +2012-06-22 Till Tantau <tantau@users.sourceforge.net> + + - Redone handling of clusters in gd. + - Worked on gd documentation. + +2012-06-18 Christian Feuersaenger <cfeuersaenger@users.sourceforge.net> + - fixed minor expansion issue \foreach \x in {a,...,d} lead to unexpanded value \x + +2012-06-18 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - externalization: added special switch to deactivate incompatible + geometry drivers during externalization + +2012-05-31 Till Tantau <tantau@users.sourceforge.net> + + - Redone pgf.gd.model.Arc + - Added documentation for said class. + +2012-05-23 Till Tantau <tantau@users.sourceforge.net> + + - Worked on gd documentation. + - Replaced old luadoc by customized version. Gets called + directly from tex. + +2012-05-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - external lib: added support for MD5/diff based up-to-date checks. + Changes to a picture will automatically result in a remake of the + respective external graphics. + +2012-05-03 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fix bug #3527068 (\pgfmathatantwo did not exist) + +2012-05-14 Till Tantau <tantau@users.sourceforge.net> + + - Changed pgf.gd.new_graph_drawing_algorithm syntax. Not + likely to change again... + - Added support for algorithms to create nodes and edge in the + syntactic digraph. + - Introduced library graphdrawing.examples that includes some + code demonstrating how "things are done". + + +2012-05-13 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - context: fixed catcode issues by means of suitable module + \protect/\unprotect statements. + +2012-05-06 Till Tantau <tantau@users.sourceforge.net> + + - Introduced a new class model for graph drawing (Digraph, + Arc, and Vertex instead of Graph, Edge, Node). I'm currently + porting all the old code, but it takes a while and it's a + bit messy right now. Some easy algorithms are already based + on the new system, old ones not. In the end, things should + be significantly faster and also easier to program. + +2012-05-03 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Attempt to fix bug in calc lib when '!' or ':' are active (not + fully tested but should work). + +2012-05-02 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Attempt to fix bug with label and pin when ':' is active (not + fully tested but should work). + +2012-04-19 Till Tantau <tantau@users.sourceforge.net> + + - Finished the first two chapters of the documentation of gd + (overview and tikz usage). + - Module system is now redone and the directory structure + has been reorganized. No more messing around with lua + modules, everything is perfectly portable now. + +2012-04-17 Till Tantau <tantau@users.sourceforge.net> + + - Started to completely redo the module system of graph + drawing in lua. I'm in the middle of it, so its currently + messy, but it works. + +2012-04-12 Till Tantau <tantau@users.sourceforge.net> + + - Implemented packing procedure for graph drawing. + - Cleaned up graph drawing source some more. + - Renamed lots of files (still not happy with it, though). + +2012-04-11 Till Tantau <tantau@users.sourceforge.net> + + - Implemented Reingold-Tilford tree layout. + +2012-04-05 Till Tantau <tantau@users.sourceforge.net> + + - Implemented my first graph drawing algorithm: circular layout. + +2012-04-03 Till Tantau <tantau@users.sourceforge.net> + + - Introduced new declaration mechanism for graph drawing + algorithm classes + - Implemented preprocessing step of decomposing a graph into + connected components. + +2012-04-02 Till Tantau <tantau@users.sourceforge.net> + + - Cleaned up graph drawing algorithm directories: Moved + obsolete algorithms to special directory. + - Switched graph drawing calling interface from function-base + to object-based: All graph drawing algorithms must now be + implemented in a class + - Cleaned up file and class names of graph drawing engine. + +2012-03-30 Till Tantau <tantau@users.sourceforge.net> + + - Fixed problem that in case math library is loaded before pgf + some math functions were broken (because \pgfmath@xa and + \pgf@xa were different registers, which they should not be). + +2012-03-29 Till Tantau <tantau@users.sourceforge.net> + + - Added anchoring and orientation to graph drawing library. + +2012-03-21 Till Tantau <tantau@users.sourceforge.net> + + - Added arrows.spaced library. + - Added quotation syntax to graph lib. + - Renamed some graph drawing layouts. + - Worked on documentation of graph drawing lib. + +2012-03-07 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Moved wrappers for luatex primitives (\pgfutil@directlua, + \pgfutil@ifluatex, \pgfutil@luaescapestring) to pgfutil-common.tex + - Added support for luatex to the profiler library by emulating + \pdfelapsedtime. + +2012-02-27 Till Tantau <tantau@users.sourceforge.net> + + - Fixed wrong edef in graph lib that broke the /-syntax when + text contained expandable stuff. + +2012-02-21 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - More work on the luamath parser and evaluator. + +2012-01-24 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fix a bug in tikz polar coordinates (reported on tex.se + http://tex.stackexchange.com/questions/41828/using-math-in-tikz): + braces around a delimited argument are removed. + +2012-01-10 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fix a bug in pgfmath != operator (reported and fixed on tex.se + http://tex.stackexchange.com/questions/40605/using-in-pgfmathparse) + +2012-01-09 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fix a pgfmath dependency for pgffor. + +2012-01-03 Till Tantau <tantau@users.sourceforge.net> + + - Added pos support to the arc command (finally...). + - Added support to the graph library for drawing tries. + - Added support to the graph library for adding edge labels in + an easier way. + +2011-12-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added the 'fixed relative' number formatting style. + +2011-12-28 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added 'const plot mark mid' and 'jump mark mid' plot handlers. + +2011-12-02 Till Tantau <tantau@users.sourceforge.net> + + - Renamed "layered drawing" to "layered layout" for + consistency. + +2011-11-12 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - More work on the lua math parser and evaluator. + - Added wrappers for luatex primitives: \pgfutil@directlua, + \pgfutil@ifluatex, \pgfutil@luaescapestring + - Make lua code more lua 5.2 compatible + +2011-11-11 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Work on the lua math parser and evaluator. Begin to merge Mark's + code with mine. + +2011-11-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added FPU support for ==, !=, <=, >=, ? + +2011-10-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed problem with pgf number printer: it introduced spurious spaces + tracker id 3430171. Thanks to Clemens Koppensteiner for the bugfix. + +2011-09-25 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - \pgfsetlayers can now be given inside of a pgfpicture (or tikzpicture) + +2011-06-22 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - The lua math parser now works on basic expressions (no units, no + arrays, no strings, no functions, ...?). + +2011-06-02 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Some work on a lua (lpeg based) math parser. + +2011-05-31 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Added a gnuplot call key to pgfmoduleplot.code.tex (feature + request #3308340). + +2011-05-30 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Initial work on layered drawing algorithms. + +2011-05-25 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Added dim function for array to pgfmath (to be documented) + - Some work on a ODE solver + +2011-05-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - removed spurious white spaces in my bugfix for pgfmathdivide + +2011-05-19 Till Tantau <tantau@users.sourceforge.net> + + - Second attempt at fixing spy lib... + +2011-05-18 Matthias Schulz <ma.schulz@email.de> + + - graph drawing: + - added short overview for nodes and edges (lua class documentation) + +2011-05-17 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Separate 'spring layout' and 'spring electrical layout' families. + Rename existing algorithms accordingly. + - Add an implementation of the Floyd-Warshall algorithm. + - Add a new 'Hu2006 spring' algorithm based solely on springs. + - Improve the initial layout of 'Hu2006 spring electrical' by + taking the graph size and diameter into account. + - Rework existing spring electrical algorithms and improve + documentation. + - Catch -!- edges and remove them from the Lua graph when detected. + +2011-05-14 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Update documentation of spring and spring-electrical parameters. + Add TODO items where things are missing, unclear or need to be + worked on. + - Make initial step dimension and the electric charge of nodes + configurable. Both, Walshaw2000 and Hu2006 support this. + - Improve the approximation of the repulsive force. + +2011-05-13 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug 3297817 (spy postscript problem). + - Fixed bug of missing newpath in postscript and opacity + settings. + +2011-05-13 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Rename graphdrawing.spring to graphdrawing.force. + - Fix NaN bug in the orientation helper. + - Initial work on improving and documenting the parameters for + spring and spring-electrical algorithms. + - Properly forward default node and edge parameters to Lua. + +2011-05-12 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Add Fibonacci heap and priority queue classes. + - Add Lua file for common graph algorithms. Implement Dijkstra. + - Add method Graph:getPseudoDiameter(). + - Hu2006: Scale coordinations of nodes in a coarse graph based on + the quotient of its pseudo diameters and that of the parent coarse + graph, as described in the paper. + +2011-05-11 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Fix several interpolation bugs in the coarse graph class. + - Use the coarse graph class in the Walshaw2000 algorithm. + +2011-05-11 Till Tantau <tantau@users.sourceforge.net> + + - Worked on documentation of gd backend. Still need to + document graph parameters. + +2011-05-10 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Remove files from the old graph drawing library tree. + - Disable verbose logging by default. + - Specify sane initial values for spring algorithm parameters. + +2011-05-10 Till Tantau <tantau@users.sourceforge.net> + + - Added .graph drawing parameter initial key. + +2011-05-09 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Implement graph coarsening in the Hu2006 algorithm. + - Name force-based algorithms after the paper author and year. + +2011-05-09 Till Tantau <tantau@users.sourceforge.net> + + - Reorganized graph drawing documentation. + +2011-05-06 Jannis Pohlmann <jannis@xfce.org> + + - Finished the graph drawing library reorganization started by Till. + +2011-05-06 Till Tantau <tantau@users.sourceforge.net> + + - Reorganized the graph drawing key and directory + structure. The documentation is still missing. Also, lots of + files still need to be moved, but I'll leave that to Jannis. + +2011-05-06 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - implement a quadtree optimization in the Walshaw algorithm. + - add a simple version of the Hu spring-electrical algorithm that + seems to work almost as good as the Walshaw even without + the multilevel approach implemented (which is the only thing + that really makes the Walshaw algorithm useful). + +2011-05-04 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Initial work on a quad tree implementation for spring and spring + electrical algorithms, with unit test. + - Improve the internals of the Vector class. + +2011-05-03 Till Tantau <tantau@users.sourceforge.net> + + - graph drawing: Started to cleanup pgf and tikz layers. Ongoing... + +2011-05-03 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Fix Walshaw algorithm to properly set the subnodes when copying + the coarse graphs. Simplify the code that updates the node + coordinates. + +2011-05-02 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Modify the doclet to allow underscores in parameter names. + - Document the Vector class as well as the table, iter and traversal + helpers. + - Remove old table and iterator helpers. Rename helper files. Rename + table.merge() and table.copy() to table.custom_merge() and + table.custom_copy() to avoid name clashes with luatools. Add + string helpers, including string.parse_braces(). Update algorithms + to work with these changes. + - Allow vectors to have an origin vector, similar to the Position + class. Introduce new alternative table-based syntax for + Vector:set() that is much easier to read. Update unit tests + and algorithms. + +2011-05-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fpu: added support for log10 and log2 + +2011-05-02 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Drop the 'not yet positionedPGFGDINTERNAL' node name prefix + internally. It's stripped off now when nodes are passed over to + Lua and its added back again when shipping the node out to TeX. + - Drop the Node:shortname() method which is no longer needed. + - Improve coding style and documentation of the Interface, Sys, + Node, Edge and Graph classes. + - Rename Sys:logMessage() to Sys:log(). + - Make parameter labels in the API docs not appear in bold. + - Disable verbose logging by default. + - Add methods Edge:getNodes() and Node:getEdges(). + +2011-05-02 Jannis Pohlmann <jannis@xfce.org> + + - graph drawing: + - Initial work on spring-electrical and layered drawing algorithms. + - Major rework of the Lua code of the graphdrawing library: added + a Vector class for improved math operations and node positioning, + added quite a number of table and iterator helpers, added + post-processing code for fixing the orientation of graph drawings, + updated the graph/node/edge data structures to store nodes in the order + they appear instead of storing them in a random order, implement + coordinate keys for nodes, and much more. + +2011-04-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - number printing: added '1000 sep in fractionals' switch + +2011-04-29 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Work on pgflibraryluamath (added pgfpointnormalised) + +2011-04-27 Matthias Schulz <ma.schulz@email.de> + + - Graphdrawing library documentation, split into two files, removed + noluatex file, reworked the text (added information). + +2011-04-25 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - First attempt to do math with lua (very basical): pgflibraryluamath + +2011-04-18 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - bugfix for rounding error in \pgfmathdivide{83.407811000}{16.68156400} + was 4.10, is now 5.0: it could happen in rare cases that digits where + appended where they shouldhave been than added (4 + .10 instead of 4 + 1.0) + +2011-04-22 Jannis Pohlmann <jannis@xfce.org> + + - Implemented a G_n subgraph for creating grid (or: mesh) graphs. + This also introduces a new key /tikz/graphs/wrap after=<number> that + configures how the nodes in such a grid graph are connected. Some of + the common subgraph keys such as /tikz/graphs/V and /tikz/graphs/n + can be used with G_n subgraphs as well. + - Added a simple grid placement strategy. It currently does not + support the chain shift and group shift keys properly and does not + implement any placement order other than left-to-right, so there is + room for improvement. + +2011-04-18 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - external lib: reduced number of \newwrite allocations and allowed to disable features + to safe more of them (aux in dpth=false,disable dependency files) + +2011-04-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added '/pgf/number format/relative' formatting style. + +2011-03-22 Till Tantau <tantau@users.sourceforge.net> + + - Finished documentation of data visualization (sort of)! + - First usable version of data visualization! + +2011-03-15 Till Tantau <tantau@users.sourceforge.net> + + - Worked on dv documentation. Finished chapter on visualizers, + style sheets. Legends still missing + +2011-03-07 Till Tantau <tantau@users.sourceforge.net> + + - Worked on dv documentation. Finished chapter on axes. + +2011-03-07 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Incorporated a bugfix of Hans Hagen which makes pgf compatible with + Context Mk IV. + Verified: the patch is backwards compatible with TL 2009 and TL 2010 + i.e. Context MkII and it works with Context Mk IV. + +2011-01-22 Till Tantau <tantau@users.sourceforge.net> + + - Worked on dv documentation. + +2011-01-05 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Attempt to fix a bug #1911195 with pgfpages and rotation (fix + contributed by Mark Wibrow). Note: Mark was not sure it has side + effects. + +2010-12-17 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Documentation will now compile with auto-xref enabled (a problem + with \_ in the graph lib not handled correctly by + pgfmanual.pdflinks.code.tex). + - Fix bug #3104978 thanks to Heiko Oberdiek patch on ctt. + +2010-12-17 Till Tantau <tantau@users.sourceforge.net> + + - Changed the graph syntax for anonymous nodes in the graph + library and simplified the as= syntax. + - Added fresh nodes options to graph library. + +2010-12-14 Till Tantau <tantau@users.sourceforge.net> + + - Fixed graph lib so that it compiles with plain TeX. + +2010-12-10 Till Tantau <tantau@users.sourceforge.net> + + - Small fixed in the graph library. + +2010-12-07 Till Tantau <tantau@users.sourceforge.net> + + - Finished graph library! + +2010-12-06 Till Tantau <tantau@users.sourceforge.net> + + - Nearly finished graph lib and its documentation. + +2010-11-30 Till Tantau <tantau@users.sourceforge.net> + + - Fixed bug #3123605 (hopefully...). + - Worked on graph lib. + +2010-11-19 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Some integer arithmetics functions for the math parser + (contributed by Alain Matthes): gcd, isprime, isodd, iseven + +2010-11-19 Till Tantau <tantau@users.sourceforge.net> + + - Second attempt at making \tikz work also with fragile stuff + following. The new code will no longer fail in a situation + like \tikz \foreach ... + - Worked on graph lib stuff. + +2010-11-06 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - A luatex version of the doc is available (fixed inputenc issues + since luatex works with utf8 by default). + +2010-11-04 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Fix bug in pgfmathfunctions.basic.code.tex (bug reported by + Alain Matthes and fixed by Paul Gaborit on fctt): wrong + interaction between pow and exp (linked to \pgfmath@x modified + outside macro call). + +2010-11-01 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - Make \pgfkeys@exp@call long (bug reported by Florent Chervet on + fctt) + - Fix bug in pgflibraryshapes.callouts.code.tex: \pgf@test changed + to \pgf@node@name (bug reported by Zarko F. Cucej on ctt and fix + contributed by Mark Wibrow) + +2010-10-27 Christophe Jorssen <cjorssen@users.sourceforge.net> + + - fixed bug 3096333 (Fix contributed by Mark Wibrow): pgffor + failed to update \lastx in some cases + 2010-10-25 Christian Feuersaenger <ludewich@users.sourceforge.net> Released version 2.10 @@ -2265,3 +3360,7 @@ - Added pgfshade.sty + +;;; Local Variables: +;;; coding: undecided-unix +;;; End: diff --git a/Master/texmf-dist/doc/generic/pgf/FILES b/Master/texmf-dist/doc/generic/pgf/FILES index 941e8a18ab7..551504ed0a3 100644 --- a/Master/texmf-dist/doc/generic/pgf/FILES +++ b/Master/texmf-dist/doc/generic/pgf/FILES @@ -1,52 +1,44 @@ -pgf/doc/generic/pgf/images/brave-gnu-world-logo-mask.jpg +pgf/doc/generic/pgf/AUTHORS +pgf/doc/generic/pgf/ChangeLog +pgf/doc/generic/pgf/FILES pgf/doc/generic/pgf/images/brave-gnu-world-logo-mask.bb +pgf/doc/generic/pgf/images/brave-gnu-world-logo-mask.jpg pgf/doc/generic/pgf/images/brave-gnu-world-logo.25.bb pgf/doc/generic/pgf/images/brave-gnu-world-logo.25.eps pgf/doc/generic/pgf/images/brave-gnu-world-logo.25.jpg pgf/doc/generic/pgf/images/brave-gnu-world-logo.bb pgf/doc/generic/pgf/images/brave-gnu-world-logo.eps pgf/doc/generic/pgf/images/brave-gnu-world-logo.jpg +pgf/doc/generic/pgf/images/brave-gnu-world-logo.xbb pgf/doc/generic/pgf/images/pgfmanual-mindmap-1.pdf pgf/doc/generic/pgf/images/pgfmanual-mindmap-2.pdf -pgf/doc/generic/pgf/licenses/LICENSE +pgf/doc/generic/pgf/INSTALL pgf/doc/generic/pgf/licenses/gnu-free-documentation-license-1.2.txt pgf/doc/generic/pgf/licenses/gnu-public-license-2.txt pgf/doc/generic/pgf/licenses/latex-project-public-license-1.3c.txt +pgf/doc/generic/pgf/licenses/LICENSE pgf/doc/generic/pgf/licenses/manifest-code.txt pgf/doc/generic/pgf/licenses/manifest-documentation.txt pgf/doc/generic/pgf/macros/pgfmanual-en-macros.tex -pgf/doc/generic/pgf/text-en/plots/pgfmanual-sine.table -pgf/doc/generic/pgf/text-en/plots/pgf-x.table -pgf/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.table -pgf/doc/generic/pgf/text-en/plots/pgf-exp.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgf-exp.table -pgf/doc/generic/pgf/text-en/plots/pgf-parametric-example.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgf-parametric-example.table -pgf/doc/generic/pgf/text-en/plots/pgf-sin.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgf-sin.table -pgf/doc/generic/pgf/text-en/plots/pgf-x.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgfmanual-sine.gnuplot -pgf/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.table -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex +pgf/doc/generic/pgf/pgfmanual.pdf +pgf/doc/generic/pgf/README pgf/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex -pgf/doc/generic/pgf/text-en/texmf.cnf pgf/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-drivers.tex @@ -56,12 +48,29 @@ pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-examples.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-introduction.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-polar.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithm-layer.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithms-in-c.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-circular.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-examples.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-force.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-layered.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-misc.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-ogdf.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-overview.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-phylogenetics.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-trees.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-installation.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-3d.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-library-angles.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-arrows.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-automata.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-backgrounds.tex @@ -79,6 +88,7 @@ pgf/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-lsystems.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-library-math.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-mindmaps.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-patterns.tex @@ -95,6 +105,8 @@ pgf/doc/generic/pgf/text-en/pgfmanual-en-library-through.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-trees.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-library-turtle.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-license.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-main-body.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-main-preamble.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-main.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex @@ -113,53 +125,132 @@ pgf/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-arrows.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-chains.tex +pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-map.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex -pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex.orig pgf/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex pgf/doc/generic/pgf/text-en/pgfmanual-en-xxcolor.tex -pgf/doc/generic/pgf/version-for-dvipdfm/en/pgfmanual.tex +pgf/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-asymptotic-example.table +pgf/doc/generic/pgf/text-en/plots/pgf-exp.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-exp.table +pgf/doc/generic/pgf/text-en/plots/pgf-parametric-example.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-parametric-example.table +pgf/doc/generic/pgf/text-en/plots/pgf-sin.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-sin.table +pgf/doc/generic/pgf/text-en/plots/pgf-tan-example.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-tan-example.table +pgf/doc/generic/pgf/text-en/plots/pgf-x.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgf-x.table +pgf/doc/generic/pgf/text-en/plots/pgfmanual-sine.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgfmanual-sine.table +pgf/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.gnuplot +pgf/doc/generic/pgf/text-en/plots/pgfplotgnuplot-example.table pgf/doc/generic/pgf/version-for-dvipdfm/en/Makefile +pgf/doc/generic/pgf/version-for-dvipdfm/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-dvipdfm/pgfmanual-dvipdfm.cfg -pgf/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-dvipdfmx/en/Makefile +pgf/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual-test.tex +pgf/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-dvipdfmx/pgfmanual-dvipdfmx.cfg pgf/doc/generic/pgf/version-for-dvips/en/Makefile pgf/doc/generic/pgf/version-for-dvips/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-dvips/pgfmanual-dvips.cfg +pgf/doc/generic/pgf/version-for-luatex/en/Makefile +pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual-test.tex +pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual.tex +pgf/doc/generic/pgf/version-for-luatex/pgfmanual-luatex.cfg pgf/doc/generic/pgf/version-for-pdftex/en/Makefile -pgf/doc/generic/pgf/version-for-pdftex/en/pgfmanual.figlist pgf/doc/generic/pgf/version-for-pdftex/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-pdftex/pgfmanual-pdftex.cfg -pgf/doc/generic/pgf/version-for-tex4ht/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-tex4ht/en/Makefile +pgf/doc/generic/pgf/version-for-tex4ht/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-tex4ht/pgfmanual-tex4ht.cfg -pgf/doc/generic/pgf/version-for-vtex/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-vtex/en/Makefile +pgf/doc/generic/pgf/version-for-vtex/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-vtex/pgfmanual-vtex.cfg -pgf/doc/generic/pgf/version-for-xetex/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-xetex/en/Makefile +pgf/doc/generic/pgf/version-for-xetex/en/pgfmanual.tex pgf/doc/generic/pgf/version-for-xetex/pgfmanual-xetex.cfg -pgf/doc/generic/pgf/ChangeLog -pgf/doc/generic/pgf/AUTHORS -pgf/doc/generic/pgf/pgfmanual.pdf -pgf/doc/generic/pgf/FILES -pgf/doc/generic/pgf/INSTALL -pgf/doc/generic/pgf/README -pgf/doc/generic/pgf/TODO +pgf/source/generic/pgf/c/config/ExampleLocalMakefileConfig.mk +pgf/source/generic/pgf/c/config/MakefileConfig.mk +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/examples/c/Makefile +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/examples/c/SimpleDemoC.c +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/examples/c/SimpleDemoCPlusPlus.c++ +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/interface/c/InterfaceFromC++.c++ +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/interface/c/InterfaceFromC++.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/interface/c/InterfaceFromC.c +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/interface/c/InterfaceFromC.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/interface/c/Makefile +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/energybased_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/FastMultipoleEmbedder_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/FMMMLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/GEMLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/MultilevelLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/BarycenterPlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/CirclePlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/EdgeCoverMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/IndependentSetMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/LocalBiconnectedMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/MatchingMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/MedianPlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/multilevelmixer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/RandomMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/RandomPlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/SolarMerger_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/SolarPlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/multilevelmixer/ZeroPlacer_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/SpringEmbedderFR_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/SpringEmbedderFRExact_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/energybased/SpringEmbedderKK_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/InterfaceFromOGDF.c++ +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/InterfaceFromOGDF.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/BarycenterHeuristic_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/CoffmanGrahamRanking_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/DfsAcyclicSubgraph_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/FastHierarchyLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/FastSimpleHierarchyLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/GreedyCycleRemoval_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/GreedyInsertHeuristic_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/layered_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/LongestPathRanking_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/MedianHeuristic_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/OptimalRanking_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/SiftingHeuristic_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/SplitHeuristic_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/layered/SugiyamaLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/Makefile +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/misclayout/BalloonLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/misclayout/CircularLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/misclayout/misclayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/module/module_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/ogdf_script.c++ +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/planarity/planarity_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/planarity/PlanarizationLayout_script.h +pgf/source/generic/pgf/c/graphdrawing/pgf/gd/ogdf/c/SimpleDemoOGDF.c++ +pgf/source/generic/pgf/c/INSTALL +pgf/source/generic/pgf/c/Makefile +pgf/source/generic/pgf/testsuite/external/Makefile +pgf/source/generic/pgf/testsuite/external/tikzexternaltest.code.tex +pgf/source/generic/pgf/testsuite/external/tikzexternaltest.sharedpreamble.tex +pgf/source/generic/pgf/testsuite/external/tikzexternaltest.tex +pgf/source/generic/pgf/testsuite/external/tikzexternaltestmakefile.tex +pgf/source/generic/pgf/testsuite/mathtest/pgfmathtestsuite.tex pgf/tex/context/third/pgf/basiclayer/t-pgf.tex pgf/tex/context/third/pgf/basiclayer/t-pgfbim.tex pgf/tex/context/third/pgf/basiclayer/t-pgfbla.tex @@ -177,70 +268,14 @@ pgf/tex/context/third/pgf/utilities/t-pgffor.tex pgf/tex/context/third/pgf/utilities/t-pgfkey.tex pgf/tex/context/third/pgf/utilities/t-pgfmod.tex pgf/tex/context/third/pgf/utilities/t-pgfrcs.tex -pgf/tex/latex/pgf/basiclayer/pgfbaseimage.sty -pgf/tex/latex/pgf/basiclayer/pgf.sty -pgf/tex/latex/pgf/basiclayer/pgfbaselayers.sty -pgf/tex/latex/pgf/basiclayer/pgfbasematrix.sty -pgf/tex/latex/pgf/basiclayer/pgfbasepatterns.sty -pgf/tex/latex/pgf/basiclayer/pgfbaseplot.sty -pgf/tex/latex/pgf/basiclayer/pgfbaseshapes.sty -pgf/tex/latex/pgf/basiclayer/pgfbasesnakes.sty -pgf/tex/latex/pgf/basiclayer/pgfcore.sty -pgf/tex/latex/pgf/compatibility/pgfcomp-version-0-65.sty -pgf/tex/latex/pgf/compatibility/pgfarrows.sty -pgf/tex/latex/pgf/compatibility/pgfautomata.sty -pgf/tex/latex/pgf/compatibility/pgflibraryplothandlers.sty -pgf/tex/latex/pgf/compatibility/pgfcomp-version-1-18.sty -pgf/tex/latex/pgf/compatibility/pgfheaps.sty -pgf/tex/latex/pgf/compatibility/pgflibraryarrows.sty -pgf/tex/latex/pgf/compatibility/pgflibraryautomata.sty -pgf/tex/latex/pgf/compatibility/pgflibrarytikzbackgrounds.sty -pgf/tex/latex/pgf/compatibility/pgflibraryplotmarks.sty -pgf/tex/latex/pgf/compatibility/pgflibraryshapes.sty -pgf/tex/latex/pgf/compatibility/pgflibrarysnakes.sty -pgf/tex/latex/pgf/compatibility/pgflibrarytikztrees.sty -pgf/tex/latex/pgf/compatibility/pgfnodes.sty -pgf/tex/latex/pgf/compatibility/pgfshade.sty -pgf/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex -pgf/tex/latex/pgf/doc/pgfmanual.code.tex -pgf/tex/latex/pgf/doc/pgfmanual.prettyprinter.code.tex -pgf/tex/latex/pgf/doc/pgfmanual.sty -pgf/tex/latex/pgf/frontendlayer/libraries/tikzlibraryexternal.code.tex -pgf/tex/latex/pgf/frontendlayer/pgfpict2e.sty -pgf/tex/latex/pgf/frontendlayer/tikz.sty -pgf/tex/latex/pgf/math/pgfmath.sty -pgf/tex/latex/pgf/systemlayer/pgfsys.sty -pgf/tex/latex/pgf/utilities/pgfcalendar.sty -pgf/tex/latex/pgf/utilities/pgffor.sty -pgf/tex/latex/pgf/utilities/pgfkeys.sty -pgf/tex/latex/pgf/utilities/pgfpages.sty -pgf/tex/latex/pgf/utilities/pgfrcs.sty -pgf/tex/latex/pgf/utilities/tikzexternal.sty -pgf/tex/latex/pgf/utilities/xxcolor.sty -pgf/tex/plain/pgf/basiclayer/pgfbaseimage.tex -pgf/tex/plain/pgf/basiclayer/pgf.tex -pgf/tex/plain/pgf/basiclayer/pgfbaselayers.tex -pgf/tex/plain/pgf/basiclayer/pgfbasematrix.tex -pgf/tex/plain/pgf/basiclayer/pgfbasepatterns.tex -pgf/tex/plain/pgf/basiclayer/pgfbaseplot.tex -pgf/tex/plain/pgf/basiclayer/pgfbaseshapes.tex -pgf/tex/plain/pgf/basiclayer/pgfbasesnakes.tex -pgf/tex/plain/pgf/basiclayer/pgfcore.tex -pgf/tex/plain/pgf/frontendlayer/tikz.tex -pgf/tex/plain/pgf/math/pgfmath.tex -pgf/tex/plain/pgf/systemlayer/pgfsys.tex -pgf/tex/plain/pgf/utilities/pgfcalendar.tex -pgf/tex/plain/pgf/utilities/pgffor.tex -pgf/tex/plain/pgf/utilities/pgfkeys.tex -pgf/tex/plain/pgf/utilities/pgfrcs.tex -pgf/tex/generic/pgf/basiclayer/pgfcorearrows.code.tex pgf/tex/generic/pgf/basiclayer/pgfcore.code.tex -pgf/tex/generic/pgf/basiclayer/pgfcoregraphicstate.code.tex +pgf/tex/generic/pgf/basiclayer/pgfcorearrows.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoreexternal.code.tex -pgf/tex/generic/pgf/basiclayer/pgfcorepathconstruct.code.tex +pgf/tex/generic/pgf/basiclayer/pgfcoregraphicstate.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoreimage.code.tex pgf/tex/generic/pgf/basiclayer/pgfcorelayers.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoreobjects.code.tex +pgf/tex/generic/pgf/basiclayer/pgfcorepathconstruct.code.tex pgf/tex/generic/pgf/basiclayer/pgfcorepathprocessing.code.tex pgf/tex/generic/pgf/basiclayer/pgfcorepathusage.code.tex pgf/tex/generic/pgf/basiclayer/pgfcorepatterns.code.tex @@ -250,41 +285,38 @@ pgf/tex/generic/pgf/basiclayer/pgfcorescopes.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoreshade.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoretransformations.code.tex pgf/tex/generic/pgf/basiclayer/pgfcoretransparency.code.tex -pgf/tex/generic/pgf/frontendlayer/svg/svgpgf.cfg -pgf/tex/generic/pgf/frontendlayer/svg/svgpgf.xmt -pgf/tex/generic/pgf/frontendlayer/svg/svgtest.cfg -pgf/tex/generic/pgf/frontendlayer/svg/svgtest.tex -pgf/tex/generic/pgf/frontendlayer/svg/svgtest.xml -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.ee.IEC.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.CDH.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.ee.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.ee.IEC.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.CDH.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.IEC.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.US.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/circuits/tikzlibrarycircuits.logic.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.barcharts.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.3d.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.polar.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.barcharts.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.formats.functions.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.polar.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/datavisualization/tikzlibrarydatavisualization.sparklines.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/graphs/tikzlibrarygraphs.basic.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/graphs/tikzlibrarygraphs.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarybackgrounds.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/graphs/tikzlibrarygraphs.standard.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzexternalshared.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrary3d.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryangles.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryarrows.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryautomata.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarycalendar.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarybabel.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarybackgrounds.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarybending.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarycalc.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarycalendar.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarychains.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.pathreplacing.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.footprints.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.fractals.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.markings.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.pathmorphing.code.tex -pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.gates.logic.IEC.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.pathreplacing.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.shapes.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarydecorations.text.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryer.code.tex @@ -295,6 +327,7 @@ pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryfolding.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryfpu.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryintersections.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarylindenmayersystems.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarymath.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarymatrix.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarymindmap.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarypatterns.code.tex @@ -302,12 +335,14 @@ pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarypetri.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryplothandlers.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryplotmarks.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarypositioning.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryquotes.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryscopes.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshadings.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshadows.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.arrows.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.callouts.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.code.tex +pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.gates.logic.IEC.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.gates.logic.US.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.geometric.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryshapes.misc.code.tex @@ -321,8 +356,180 @@ pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarytopaths.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibrarytrees.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/libraries/tikzlibraryturtle.code.tex pgf/tex/generic/pgf/frontendlayer/tikz/tikz.code.tex -pgf/tex/generic/pgf/libraries/datavisualization/pgflibrarydatavisualization.formats.functions.code.tex +pgf/tex/generic/pgf/graphdrawing/lua/LUA_CODING_STYLE +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/bindings/Binding.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/bindings/BindingToPGF.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/bindings.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/circular/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/circular/Tantau2012.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/circular.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Anchoring.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/ComponentAlign.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/ComponentDirection.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/ComponentDistance.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/ComponentOrder.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Components.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Distances.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/FineTune.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/LayoutPipeline.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/NodeAnchors.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Orientation.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Sublayouts.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Cluster.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Edge.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Graph.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Iterators.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Node.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/deprecated/Vector.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/circular/Tantau2012.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/control/Anchoring.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/FastMultipoleEmbedder.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/FMMMLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/GEMLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/MultilevelLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/BarycenterPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/CirclePlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/EdgeCoverMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/IndependentSetMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/LocalBiconnectedMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/MatchingMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/MedianPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/RandomMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/RandomPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/SolarMerger.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/SolarPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/multilevelmixer/ZeroPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/SpringEmbedderFR.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/SpringEmbedderFRExact.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased/SpringEmbedderKK.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/energybased.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/BarycenterHeuristic.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/CoffmanGrahamRanking.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/DfsAcyclicSubgraph.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/FastHierarchyLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/FastSimpleHierarchyLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/GreedyCycleRemoval.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/GreedyInsertHeuristic.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/LongestPathRanking.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/MedianHeuristic.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/OptimalRanking.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/SiftingHeuristic.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/SplitHeuristic.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered/SugiyamaLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/layered.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/misclayout/BalloonLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/misclayout/CircularLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/misclayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/AcyclicSubgraphModule.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/HierarchyLayoutModule.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/InitialPlacer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/MultilevelBuilder.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/RankingModule.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/module/TwoLayerCrossMin.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/planarity/PlanarizationLayout.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/ogdf/planarity.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc/trees/ReingoldTilford1981.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/ASCIIDisplayer.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/BindingToASCII.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/example_graph_for_ascii_displayer.txt +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/SimpleDemo.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/SimpleEdgeDemo.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples/SimpleHuffman.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/examples.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/CoarseGraph.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/Control.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/ControlCoarsening.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/ControlElectric.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/ControlIteration.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/ControlSprings.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/ControlStart.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/QuadTree.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/SpringElectricalHu2006.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/SpringElectricalLayouts.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/SpringElectricalWalshaw2000.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/SpringHu2006.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force/SpringLayouts.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/force.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface/InterfaceCore.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface/InterfaceToAlgorithms.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface/InterfaceToC.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface/InterfaceToDisplay.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface/Scope.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/interface.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/crossing_minimization.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/CrossingMinimizationGansnerKNV1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/cycle_removal.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/CycleRemovalBergerS1990a.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/CycleRemovalBergerS1990b.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/CycleRemovalEadesLS1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/CycleRemovalGansnerKNV1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/edge_routing.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/EdgeRoutingGansnerKNV1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/NetworkSimplex.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/node_positioning.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/node_ranking.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/NodePositioningGansnerKNV1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/NodeRankingGansnerKNV1993.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/NodeRankingMinimumHeight.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/Ranking.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered/Sugiyama.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/layered.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Bezier.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/DepthFirstSearch.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Direct.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Event.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/LookupTable.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/PathLengths.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/PriorityQueue.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Simplifiers.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Stack.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Storage.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib/Transform.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/lib.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Arc.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Collection.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Coordinate.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Digraph.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Edge.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Hyperedge.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Path.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Vertex.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/model.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/ogdf/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/ogdf.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/AuthorDefinedPhylogeny.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/BalancedMinimumEvolution.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/BalancedNearestNeighbourInterchange.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/DistanceMatrix.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/Maeusle2012.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/PhylogeneticTree.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics/SokalMichener1958.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/phylogenetics.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/tools/make_gd_wrap.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ChildSpec.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/library.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/ReingoldTilford1981.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/SpanningTreeComputation.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd.lua +pgf/tex/generic/pgf/graphdrawing/lua/pgf.lua +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.circular.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.examples.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.force.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.layered.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/pgflibrarygraphdrawing.trees.code.tex +pgf/tex/generic/pgf/graphdrawing/tex/tikzlibrarygraphdrawing.code.tex pgf/tex/generic/pgf/libraries/datavisualization/pgflibrarydatavisualization.barcharts.code.tex +pgf/tex/generic/pgf/libraries/datavisualization/pgflibrarydatavisualization.formats.functions.code.tex pgf/tex/generic/pgf/libraries/datavisualization/pgflibrarydatavisualization.polar.code.tex pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.footprints.code.tex pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.fractals.code.tex @@ -331,23 +538,17 @@ pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.pathmorphing.cod pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.pathreplacing.code.tex pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.shapes.code.tex pgf/tex/generic/pgf/libraries/decorations/pgflibrarydecorations.text.code.tex -pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.IEC.code.tex -pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.ee.IEC.code.tex -pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.ee.code.tex -pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.US.code.tex -pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.callouts.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.arrows.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.geometric.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.multipart.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.misc.code.tex -pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.symbols.code.tex -pgf/tex/generic/pgf/libraries/pgflibraryintersections.code.tex +pgf/tex/generic/pgf/libraries/luamath/pgflibraryluamath.code.tex +pgf/tex/generic/pgf/libraries/luamath/pgfluamath.functions.lua +pgf/tex/generic/pgf/libraries/luamath/pgfluamath.parser.lua pgf/tex/generic/pgf/libraries/pgflibraryarrows.code.tex +pgf/tex/generic/pgf/libraries/pgflibraryarrows.meta.code.tex +pgf/tex/generic/pgf/libraries/pgflibraryarrows.spaced.code.tex +pgf/tex/generic/pgf/libraries/pgflibrarycurvilinear.code.tex pgf/tex/generic/pgf/libraries/pgflibraryfadings.code.tex -pgf/tex/generic/pgf/libraries/pgflibraryfpu.code.tex pgf/tex/generic/pgf/libraries/pgflibraryfixedpointarithmetic.code.tex +pgf/tex/generic/pgf/libraries/pgflibraryfpu.code.tex +pgf/tex/generic/pgf/libraries/pgflibraryintersections.code.tex pgf/tex/generic/pgf/libraries/pgflibrarylindenmayersystems.code.tex pgf/tex/generic/pgf/libraries/pgflibrarypatterns.code.tex pgf/tex/generic/pgf/libraries/pgflibraryplothandlers.code.tex @@ -356,39 +557,56 @@ pgf/tex/generic/pgf/libraries/pgflibraryprofiler.code.tex pgf/tex/generic/pgf/libraries/pgflibraryshadings.code.tex pgf/tex/generic/pgf/libraries/pgflibrarysnakes.code.tex pgf/tex/generic/pgf/libraries/pgflibrarysvg.path.code.tex -pgf/tex/generic/pgf/math/pgfmathcalc.code.tex +pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.ee.code.tex +pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.ee.IEC.code.tex +pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.code.tex +pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.IEC.code.tex +pgf/tex/generic/pgf/libraries/shapes/circuits/pgflibraryshapes.gates.logic.US.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.arrows.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.callouts.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.geometric.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.misc.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.multipart.code.tex +pgf/tex/generic/pgf/libraries/shapes/pgflibraryshapes.symbols.code.tex +pgf/tex/generic/pgf/lua/pgf/manual/DocumentParser.lua +pgf/tex/generic/pgf/lua/pgf/manual.lua pgf/tex/generic/pgf/math/pgfmath.code.tex -pgf/tex/generic/pgf/math/pgfmathfunctions.base.code.tex +pgf/tex/generic/pgf/math/pgfmathcalc.code.tex pgf/tex/generic/pgf/math/pgfmathfloat.code.tex -pgf/tex/generic/pgf/math/pgfmathfunctions.comparison.code.tex +pgf/tex/generic/pgf/math/pgfmathfunctions.base.code.tex pgf/tex/generic/pgf/math/pgfmathfunctions.basic.code.tex pgf/tex/generic/pgf/math/pgfmathfunctions.code.tex -pgf/tex/generic/pgf/math/pgfmathfunctions.trigonometric.code.tex +pgf/tex/generic/pgf/math/pgfmathfunctions.comparison.code.tex +pgf/tex/generic/pgf/math/pgfmathfunctions.integerarithmetics.code.tex pgf/tex/generic/pgf/math/pgfmathfunctions.misc.code.tex pgf/tex/generic/pgf/math/pgfmathfunctions.random.code.tex pgf/tex/generic/pgf/math/pgfmathfunctions.round.code.tex +pgf/tex/generic/pgf/math/pgfmathfunctions.trigonometric.code.tex +pgf/tex/generic/pgf/math/pgfmathode.code.tex pgf/tex/generic/pgf/math/pgfmathparser.code.tex pgf/tex/generic/pgf/math/pgfmathutil.code.tex +pgf/tex/generic/pgf/modules/pgfmodulebending.code.tex pgf/tex/generic/pgf/modules/pgfmoduledatavisualization.code.tex pgf/tex/generic/pgf/modules/pgfmoduledecorations.code.tex pgf/tex/generic/pgf/modules/pgfmodulematrix.code.tex +pgf/tex/generic/pgf/modules/pgfmodulenonlineartransformations.code.tex pgf/tex/generic/pgf/modules/pgfmoduleoo.code.tex pgf/tex/generic/pgf/modules/pgfmoduleparser.code.tex pgf/tex/generic/pgf/modules/pgfmoduleplot.code.tex pgf/tex/generic/pgf/modules/pgfmoduleshapes.code.tex pgf/tex/generic/pgf/modules/pgfmodulesnakes.code.tex pgf/tex/generic/pgf/modules/pgfmodulesorting.code.tex -pgf/tex/generic/pgf/rendering/pgfrendertransform.code.tex -pgf/tex/generic/pgf/rendering/pgfrenderpoints.code.tex -pgf/tex/generic/pgf/systemlayer/pgfsys-dvi.def pgf/tex/generic/pgf/systemlayer/pgf.cfg pgf/tex/generic/pgf/systemlayer/pgfsys-common-pdf-via-dvi.def pgf/tex/generic/pgf/systemlayer/pgfsys-common-pdf.def pgf/tex/generic/pgf/systemlayer/pgfsys-common-postscript.def pgf/tex/generic/pgf/systemlayer/pgfsys-common-svg.def +pgf/tex/generic/pgf/systemlayer/pgfsys-dvi.def pgf/tex/generic/pgf/systemlayer/pgfsys-dvipdfm.def pgf/tex/generic/pgf/systemlayer/pgfsys-dvipdfmx.def pgf/tex/generic/pgf/systemlayer/pgfsys-dvips.def +pgf/tex/generic/pgf/systemlayer/pgfsys-dvisvgm.def pgf/tex/generic/pgf/systemlayer/pgfsys-pdftex.def pgf/tex/generic/pgf/systemlayer/pgfsys-tex4ht.def pgf/tex/generic/pgf/systemlayer/pgfsys-textures.def @@ -397,38 +615,71 @@ pgf/tex/generic/pgf/systemlayer/pgfsys-xetex.def pgf/tex/generic/pgf/systemlayer/pgfsys.code.tex pgf/tex/generic/pgf/systemlayer/pgfsysprotocol.code.tex pgf/tex/generic/pgf/systemlayer/pgfsyssoftpath.code.tex -pgf/tex/generic/pgf/utilities/pgfexternalwithdepth.tex pgf/tex/generic/pgf/utilities/pgfcalendar.code.tex pgf/tex/generic/pgf/utilities/pgfexternal.tex -pgf/tex/generic/pgf/utilities/pgfkeysfiltered.code.tex +pgf/tex/generic/pgf/utilities/pgfexternalwithdepth.tex pgf/tex/generic/pgf/utilities/pgffor.code.tex pgf/tex/generic/pgf/utilities/pgfkeys.code.tex -pgf/tex/generic/pgf/utilities/pgfutil-common.tex +pgf/tex/generic/pgf/utilities/pgfkeysfiltered.code.tex pgf/tex/generic/pgf/utilities/pgfrcs.code.tex +pgf/tex/generic/pgf/utilities/pgfutil-common-lists.tex +pgf/tex/generic/pgf/utilities/pgfutil-common.tex pgf/tex/generic/pgf/utilities/pgfutil-context.def pgf/tex/generic/pgf/utilities/pgfutil-latex.def pgf/tex/generic/pgf/utilities/pgfutil-plain.def -pgf/README -pgf/source/latex/pgf/incoming/GrzegorzMurzynowski/pgfdatabasearrows.pdf -pgf/source/latex/pgf/incoming/GrzegorzMurzynowski/pgfdatabasearrows.sty -pgf/source/latex/pgf/incoming/GrzegorzMurzynowski/pgfdatabasearrows.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/interconnection.pdf -pgf/source/latex/pgf/incoming/KarlheinzOchs/basics.pdf -pgf/source/latex/pgf/incoming/KarlheinzOchs/basics.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/fir.pdf -pgf/source/latex/pgf/incoming/KarlheinzOchs/fir.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/signalflowdiagram.sty -pgf/source/latex/pgf/incoming/KarlheinzOchs/interconnection.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/macros.sty -pgf/source/latex/pgf/incoming/KarlheinzOchs/pgflibrarytikzsignalflowoperators.code.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/pgflibrarytikzsignalflowarrows.code.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/pgflibrarytikzsignalflowblocks.code.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/pgflibrarytikzsignalflowdiagram.code.tex -pgf/source/latex/pgf/incoming/KarlheinzOchs/placement.pdf -pgf/source/latex/pgf/incoming/KarlheinzOchs/placement.tex -pgf/source/latex/pgf/testsuite/external/Makefile -pgf/source/latex/pgf/testsuite/external/tikzexternaltest.code.tex -pgf/source/latex/pgf/testsuite/external/tikzexternaltest.sharedpreamble.tex -pgf/source/latex/pgf/testsuite/external/tikzexternaltest.tex -pgf/source/latex/pgf/testsuite/external/tikzexternaltestmakefile.tex -pgf/source/latex/pgf/testsuite/mathtest/pgfmathtestsuite.tex +pgf/tex/latex/pgf/basiclayer/pgf.sty +pgf/tex/latex/pgf/basiclayer/pgfbaseimage.sty +pgf/tex/latex/pgf/basiclayer/pgfbaselayers.sty +pgf/tex/latex/pgf/basiclayer/pgfbasematrix.sty +pgf/tex/latex/pgf/basiclayer/pgfbasepatterns.sty +pgf/tex/latex/pgf/basiclayer/pgfbaseplot.sty +pgf/tex/latex/pgf/basiclayer/pgfbaseshapes.sty +pgf/tex/latex/pgf/basiclayer/pgfbasesnakes.sty +pgf/tex/latex/pgf/basiclayer/pgfcore.sty +pgf/tex/latex/pgf/compatibility/pgfarrows.sty +pgf/tex/latex/pgf/compatibility/pgfautomata.sty +pgf/tex/latex/pgf/compatibility/pgfcomp-version-0-65.sty +pgf/tex/latex/pgf/compatibility/pgfcomp-version-1-18.sty +pgf/tex/latex/pgf/compatibility/pgfheaps.sty +pgf/tex/latex/pgf/compatibility/pgflibraryarrows.sty +pgf/tex/latex/pgf/compatibility/pgflibraryautomata.sty +pgf/tex/latex/pgf/compatibility/pgflibraryplothandlers.sty +pgf/tex/latex/pgf/compatibility/pgflibraryplotmarks.sty +pgf/tex/latex/pgf/compatibility/pgflibraryshapes.sty +pgf/tex/latex/pgf/compatibility/pgflibrarysnakes.sty +pgf/tex/latex/pgf/compatibility/pgflibrarytikzbackgrounds.sty +pgf/tex/latex/pgf/compatibility/pgflibrarytikztrees.sty +pgf/tex/latex/pgf/compatibility/pgfnodes.sty +pgf/tex/latex/pgf/compatibility/pgfshade.sty +pgf/tex/latex/pgf/doc/pgfmanual.code.tex +pgf/tex/latex/pgf/doc/pgfmanual.pdflinks.code.tex +pgf/tex/latex/pgf/doc/pgfmanual.prettyprinter.code.tex +pgf/tex/latex/pgf/doc/pgfmanual.sty +pgf/tex/latex/pgf/frontendlayer/libraries/tikzlibraryexternal.code.tex +pgf/tex/latex/pgf/frontendlayer/pgfpict2e.sty +pgf/tex/latex/pgf/frontendlayer/tikz.sty +pgf/tex/latex/pgf/math/pgfmath.sty +pgf/tex/latex/pgf/systemlayer/pgfsys.sty +pgf/tex/latex/pgf/utilities/pgfcalendar.sty +pgf/tex/latex/pgf/utilities/pgffor.sty +pgf/tex/latex/pgf/utilities/pgfkeys.sty +pgf/tex/latex/pgf/utilities/pgfpages.sty +pgf/tex/latex/pgf/utilities/pgfrcs.sty +pgf/tex/latex/pgf/utilities/tikzexternal.sty +pgf/tex/latex/pgf/utilities/xxcolor.sty +pgf/tex/plain/pgf/basiclayer/pgf.tex +pgf/tex/plain/pgf/basiclayer/pgfbaseimage.tex +pgf/tex/plain/pgf/basiclayer/pgfbaselayers.tex +pgf/tex/plain/pgf/basiclayer/pgfbasematrix.tex +pgf/tex/plain/pgf/basiclayer/pgfbasepatterns.tex +pgf/tex/plain/pgf/basiclayer/pgfbaseplot.tex +pgf/tex/plain/pgf/basiclayer/pgfbaseshapes.tex +pgf/tex/plain/pgf/basiclayer/pgfbasesnakes.tex +pgf/tex/plain/pgf/basiclayer/pgfcore.tex +pgf/tex/plain/pgf/frontendlayer/tikz.tex +pgf/tex/plain/pgf/math/pgfmath.tex +pgf/tex/plain/pgf/systemlayer/pgfsys.tex +pgf/tex/plain/pgf/utilities/pgfcalendar.tex +pgf/tex/plain/pgf/utilities/pgffor.tex +pgf/tex/plain/pgf/utilities/pgfkeys.tex +pgf/tex/plain/pgf/utilities/pgfrcs.tex diff --git a/Master/texmf-dist/doc/generic/pgf/TODO b/Master/texmf-dist/doc/generic/pgf/TODO deleted file mode 100644 index 1c391261d33..00000000000 --- a/Master/texmf-dist/doc/generic/pgf/TODO +++ /dev/null @@ -1,5 +0,0 @@ -1) Allow midway placement of nodes on arcs. -2) Write RiesZ (RiesZ ist ein schönes Zeichenprogramm), a Java-GUI for TikZ. - (Good students's project!!!) -3) Fix text problems in SVG. - diff --git a/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.25.eps b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.25.eps index 7fc67685fa9..9c02410d1d2 100644 --- a/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.25.eps +++ b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.25.eps @@ -1,469 +1,4 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%Title: brave-gnu-world-logo.25.eps -%%CreationDate: 09.10.2006 22:09 Uhr -%%BoundingBox: 0 0 342 387 -%%HiResBoundingBox: 0 0 342 387 -%%SuppressDotGainCompensation -%%EndComments -%%BeginProlog -%%EndProlog -%%BeginSetup -%%EndSetup -%ImageData: 342 387 8 3 0 1 3 "beginimage" -%BeginPhotoshop: 13952 -% 3842494D0425000000000010000000000000000000000000000000003842494D -% 03EA000000001DA63C3F786D6C2076657273696F6E3D22312E302220656E636F -% 64696E673D225554462D38223F3E0A3C21444F435459504520706C6973742050 -% 55424C494320222D2F2F4170706C6520436F6D70757465722F2F44544420504C -% 49535420312E302F2F454E222022687474703A2F2F7777772E6170706C652E63 -% 6F6D2F445444732F50726F70657274794C6973742D312E302E647464223E0A3C -% 706C6973742076657273696F6E3D22312E30223E0A3C646963743E0A093C6B65 -% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D48 -% 6F72697A6F6E74616C5265733C2F6B65793E0A093C646963743E0A09093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F72 -% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74 -% 696E676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E61 -% 70706C652E7072696E742E7469636B65742E6974656D41727261793C2F6B6579 -% 3E0A09093C61727261793E0A0909093C646963743E0A090909093C6B65793E63 -% 6F6D2E6170706C652E7072696E742E50616765466F726D61742E504D486F7269 -% 7A6F6E74616C5265733C2F6B65793E0A090909093C7265616C3E37323C2F7265 -% 616C3E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F6D -% 2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E0A -% 090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D31302D -% 30395432303A30333A33365A3C2F646174653E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B -% 65793E0A090909093C696E74656765723E303C2F696E74656765723E0A090909 -% 3C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B65 -% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D4F -% 7269656E746174696F6E3C2F6B65793E0A093C646963743E0A09093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F -% 6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E -% 676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E617070 -% 6C652E7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A -% 09093C61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E50616765466F726D61742E504D4F7269656E74 -% 6174696F6E3C2F6B65793E0A090909093C696E74656765723E313C2F696E7465 -% 6765723E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469 -% 636B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F -% 6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E -% 0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D3130 -% 2D30395432303A30333A33365A3C2F646174653E0A090909093C6B65793E636F -% 6D2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F -% 6B65793E0A090909093C696E74656765723E303C2F696E74656765723E0A0909 -% 093C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B -% 65793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D -% 5363616C696E673C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F6B6579 -% 3E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E676D61 -% 6E616765723C2F737472696E673E0A09093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A09093C -% 61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E50616765466F726D61742E504D5363616C696E673C2F -% 6B65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B6579 -% 3E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F -% 6B65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E74 -% 696E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B6579 -% 3E0A090909093C646174653E323030362D31302D30395432303A30333A33365A -% 3C2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E74 -% 656765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F -% 61727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E -% 7072696E742E50616765466F726D61742E504D566572746963616C5265733C2F -% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072 -% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909 -% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E50616765466F726D61742E504D566572746963616C5265733C2F6B65793E0A -% 090909093C7265616C3E37323C2F7265616C3E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B65793E -% 0A090909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D -% 616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E617070 -% 6C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E0A0909 -% 09093C646174653E323030362D31302D30395432303A30333A33365A3C2F6461 -% 74653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465676572 -% 3E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61727261 -% 793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E7072696E -% 742E50616765466F726D61742E504D566572746963616C5363616C696E673C2F -% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072 -% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909 -% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E50616765466F726D61742E504D566572746963616C5363616C696E673C2F6B -% 65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B -% 65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E7469 -% 6E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E -% 6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E -% 0A090909093C646174653E323030362D31302D30395432303A30333A33365A3C -% 2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465 -% 6765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61 -% 727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E70 -% 72696E742E7375625469636B65742E70617065725F696E666F5F7469636B6574 -% 3C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E -% 7072696E742E50616765466F726D61742E504D41646A75737465645061676552 -% 6563743C2F6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E61 -% 70706C652E7072696E742E7469636B65742E63726561746F723C2F6B65793E0A -% 0909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D616E -% 616765723C2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A090909 -% 3C61727261793E0A090909093C646963743E0A09090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E50616765466F726D61742E504D41646A757374 -% 656450616765526563743C2F6B65793E0A09090909093C61727261793E0A0909 -% 090909093C7265616C3E302E303C2F7265616C3E0A0909090909093C7265616C -% 3E302E303C2F7265616C3E0A0909090909093C7265616C3E3738333C2F726561 -% 6C3E0A0909090909093C7265616C3E3535393C2F7265616C3E0A09090909093C -% 2F61727261793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E -% 742E7469636B65742E636C69656E743C2F6B65793E0A09090909093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 7469636B65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E -% 323030362D31302D30395432303A30333A33365A3C2F646174653E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E737461 -% 7465466C61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E -% 74656765723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09 -% 093C2F646963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E -% 50616765466F726D61742E504D41646A75737465645061706572526563743C2F -% 6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E63726561746F723C2F6B65793E0A0909093C73 -% 7472696E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C -% 2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E7469636B65742E6974656D41727261793C2F6B65793E0A0909093C61727261 -% 793E0A090909093C646963743E0A09090909093C6B65793E636F6D2E6170706C -% 652E7072696E742E50616765466F726D61742E504D41646A7573746564506170 -% 6572526563743C2F6B65793E0A09090909093C61727261793E0A090909090909 -% 3C7265616C3E2D31383C2F7265616C3E0A0909090909093C7265616C3E2D3138 -% 3C2F7265616C3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A09 -% 09090909093C7265616C3E3537373C2F7265616C3E0A09090909093C2F617272 -% 61793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469 -% 636B65742E636C69656E743C2F6B65793E0A09090909093C737472696E673E63 -% 6F6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E67 -% 3E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B -% 65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E32303036 -% 2D31302D30395432303A30333A33365A3C2F646174653E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E7374617465466C -% 61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E74656765 -% 723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09093C2F64 -% 6963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E50617065 -% 72496E666F2E504D50617065724E616D653C2F6B65793E0A09093C646963743E -% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E617070 -% 6C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A -% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E69 -% 74656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C64 -% 6963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E50 -% 61706572496E666F2E504D50617065724E616D653C2F6B65793E0A0909090909 -% 3C737472696E673E69736F2D61343C2F737472696E673E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C -% 2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C652E707269 -% 6E742E706D2E506F73745363726970743C2F737472696E673E0A09090909093C -% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461 -% 74653C2F6B65793E0A09090909093C646174653E323030332D30372D30315431 -% 373A34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E -% 0A09090909093C696E74656765723E313C2F696E74656765723E0A090909093C -% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C -% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D -% 556E61646A757374656450616765526563743C2F6B65793E0A09093C64696374 -% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170 -% 706C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E -% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 6974656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C -% 646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 5061706572496E666F2E504D556E61646A757374656450616765526563743C2F -% 6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E302E -% 303C2F7265616C3E0A0909090909093C7265616C3E302E303C2F7265616C3E0A -% 0909090909093C7265616C3E3738333C2F7265616C3E0A0909090909093C7265 -% 616C3E3535393C2F7265616C3E0A09090909093C2F61727261793E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69 -% 656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C65 -% 2E7072696E74696E676D616E616765723C2F737472696E673E0A09090909093C -% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461 -% 74653C2F6B65793E0A09090909093C646174653E323030362D31302D30395432 -% 303A30333A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E -% 0A09090909093C696E74656765723E303C2F696E74656765723E0A090909093C -% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C -% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D -% 556E61646A75737465645061706572526563743C2F6B65793E0A09093C646963 -% 743E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65 -% 742E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E61 -% 70706C652E7072696E742E706D2E506F73745363726970743C2F737472696E67 -% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E6974656D41727261793C2F6B65793E0A0909093C61727261793E0A09090909 -% 3C646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E5061706572496E666F2E504D556E61646A7573746564506170657252656374 -% 3C2F6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E -% 2D31383C2F7265616C3E0A0909090909093C7265616C3E2D31383C2F7265616C -% 3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A0909090909093C -% 7265616C3E3537373C2F7265616C3E0A09090909093C2F61727261793E0A0909 -% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E63 -% 6C69656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E617070 -% 6C652E7072696E74696E676D616E616765723C2F737472696E673E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F64 -% 446174653C2F6B65793E0A09090909093C646174653E323030362D31302D3039 -% 5432303A30333A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E -% 6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65 -% 793E0A09090909093C696E74656765723E303C2F696E74656765723E0A090909 -% 093C2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09 -% 093C6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E -% 7070642E504D50617065724E616D653C2F6B65793E0A09093C646963743E0A09 -% 09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6372 -% 6561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170706C65 -% 2E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A0909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E697465 -% 6D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C646963 -% 743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E506170 -% 6572496E666F2E7070642E504D50617065724E616D653C2F6B65793E0A090909 -% 09093C737472696E673E41343C2F737472696E673E0A09090909093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B -% 65793E0A09090909093C737472696E673E636F6D2E6170706C652E7072696E74 -% 2E706D2E506F73745363726970743C2F737472696E673E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F6444617465 -% 3C2F6B65793E0A09090909093C646174653E323030332D30372D30315431373A -% 34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170706C -% 652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E0A09 -% 090909093C696E74656765723E313C2F696E74656765723E0A090909093C2F64 -% 6963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E41504956657273 -% 696F6E3C2F6B65793E0A09093C737472696E673E30302E32303C2F737472696E -% 673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E707269766174654C6F636B3C2F6B65793E0A09093C66616C73652F3E0A0909 -% 3C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74797065 -% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74 -% 2E5061706572496E666F5469636B65743C2F737472696E673E0A093C2F646963 -% 743E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 41504956657273696F6E3C2F6B65793E0A093C737472696E673E30302E32303C -% 2F737472696E673E0A093C6B65793E636F6D2E6170706C652E7072696E742E74 -% 69636B65742E707269766174654C6F636B3C2F6B65793E0A093C66616C73652F -% 3E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74 -% 7970653C2F6B65793E0A093C737472696E673E636F6D2E6170706C652E707269 -% 6E742E50616765466F726D61745469636B65743C2F737472696E673E0A3C2F64 -% 6963743E0A3C2F706C6973743E0A3842494D03E9000000000078000300000048 -% 004800000000030F022FFFEEFFEE033802410367057B03E00002000000480048 -% 0000000002D802280001000000640000000100030303000000017FFF00010001 -% 0000000000000000000000006808001901900000000000200000000000000000 -% 0000000000000000000000000000000000003842494D03ED0000000000100048 -% 00000001000200480000000100023842494D042600000000000E000000000000 -% 000000003F8000003842494D040D0000000000040000001E3842494D04190000 -% 000000040000001E3842494D03F3000000000009000000000000000001003842 -% 494D040A00000000000100003842494D271000000000000A0001000000000000 -% 00023842494D03F5000000000048002F66660001006C66660006000000000001 -% 002F6666000100A1999A0006000000000001003200000001005A000000060000 -% 00000001003500000001002D000000060000000000013842494D03F800000000 -% 00700000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000 -% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFF -% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFFFFFFFFFF -% FFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800003842494D04080000000000100000 -% 00010000024000000240000000003842494D041E000000000004000000003842 -% 494D041A00000000036300000006000000000000000000000183000001560000 -% 001700620072006100760065002D0067006E0075002D0077006F0072006C0064 -% 002D006C006F0067006F002E0032003500000001000000000000000000000000 -% 0000000000000001000000000000000000000156000001830000000000000000 -% 0000000000000000010000000000000000000000000000000000000010000000 -% 010000000000006E756C6C0000000200000006626F756E64734F626A63000000 -% 01000000000000526374310000000400000000546F70206C6F6E670000000000 -% 0000004C6566746C6F6E67000000000000000042746F6D6C6F6E670000018300 -% 000000526768746C6F6E670000015600000006736C69636573566C4C73000000 -% 014F626A6300000001000000000005736C6963650000001200000007736C6963 -% 6549446C6F6E67000000000000000767726F757049446C6F6E67000000000000 -% 00066F726967696E656E756D0000000C45536C6963654F726967696E0000000D -% 6175746F47656E6572617465640000000054797065656E756D0000000A45536C -% 6963655479706500000000496D672000000006626F756E64734F626A63000000 -% 01000000000000526374310000000400000000546F70206C6F6E670000000000 -% 0000004C6566746C6F6E67000000000000000042746F6D6C6F6E670000018300 -% 000000526768746C6F6E67000001560000000375726C54455854000000010000 -% 000000006E756C6C54455854000000010000000000004D736765544558540000 -% 0001000000000006616C74546167544558540000000100000000000E63656C6C -% 54657874497348544D4C626F6F6C010000000863656C6C546578745445585400 -% 000001000000000009686F727A416C69676E656E756D0000000F45536C696365 -% 486F727A416C69676E0000000764656661756C740000000976657274416C6967 -% 6E656E756D0000000F45536C69636556657274416C69676E0000000764656661 -% 756C740000000B6267436F6C6F7254797065656E756D0000001145536C696365 -% 4247436F6C6F7254797065000000004E6F6E6500000009746F704F7574736574 -% 6C6F6E67000000000000000A6C6566744F75747365746C6F6E67000000000000 -% 000C626F74746F6D4F75747365746C6F6E67000000000000000B72696768744F -% 75747365746C6F6E6700000000003842494D041100000000000101003842494D -% 0414000000000004000000013842494D040C0000000011340000000100000071 -% 00000080000001540000AA000000111800180001FFD8FFE000104A4649460001 -% 0201004800480000FFED000C41646F62655F434D0002FFEE000E41646F626500 -% 648000000001FFDB0084000C08080809080C09090C110B0A0B11150F0C0C0F15 -% 18131315131318110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C -% 0C0C0C0C0C0C0C0C0C0C0C010D0B0B0D0E0D100E0E10140E0E0E14140E0E0E0E -% 14110C0C0C0C0C11110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C -% 0C0C0C0C0C0C0C0C0C0C0C0CFFC00011080080007103012200021101031101FF -% DD00040008FFC4013F0000010501010101010100000000000000030001020405 -% 060708090A0B0100010501010101010100000000000000010002030405060708 -% 090A0B1000010401030204020507060805030C33010002110304211231054151 -% 611322718132061491A1B14223241552C16233347282D14307259253F0E1F163 -% 733516A2B283264493546445C2A3743617D255E265F2B384C3D375E3F3462794 -% A485B495C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F637475767778797 -% A7B7C7D7E7F71100020201020404030405060707060535010002110321311204 -% 4151617122130532819114A1B14223C152D1F0332462E1728292435315637334 -% F1250616A2B283072635C2D2449354A317644555367465E2F2B384C3D375E3F3 -% 4694A485B495C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F62737475767 -% 778797A7B7C7FFDA000C03010002110311003F00F5549249252952EA5D6303A6 -% B01C9B3F48E04D74B06EB1D1FBACFDCFCDF56CD94FEFD8A9F5AEB8EC4B1B8182 -% CF5BA85A040896B377D17387B7D4B1DB7D94FF00D72EF4AA50E93F57C54F766F -% 513F69CDB4EE739E43849FECB5AE733E87B7F435FD0A2AAAA494969FAC06FD6A -% C0CA73791ED64F9E82C72B9566DF63B6FD8EE66B05CF35868F3FE777BBFB0C56 -% 80F979240009294275911E09D2492535322DEA35585D5555E4526206E2C7B74F -% 76ED2C6DBEEFDDF4FF00E2FF00C22A77F51EAFF46BC7C7A9C7F3ADB6C81F9DF4 -% 7D0ABF35BFBEB5D2494E5E066E7DAE8BDF8CFD09D94EEDC60EDFCF73BF3BF796 -% 931E1ED04692260F2151EA1D1E9CB3EAD4EFB3E50D45AD120FFC755F46DFFCF9 -% FCB553A7F53BC669E9FD440A731809601F42D1AFE998FF00F09BA3D9FF00A53D -% 8929DB49327494A49249253FFFD0F55599D77ABFECDA18DA5A2CCCC825B8EC3A -% 8111BEE7810E732ADECF637F9DB5F553FA3F53D5669AE4F12D6F53EB36752B3D -% F57A831F10088D8D163FD4DDB7E8B696DD97F43E9E4D74FF00A2494E8740E91E -% 8B1F999536655F2E7BDC649DC439DBB46B7DDB7F37FF003C7A55ADBF34CC6ED6 -% 86F8052494A49258791F59EB7DBF67E9349EA16FFA469DB5027DA3F4B0EF57FA -% D5B7D1FF0086494EE24B370733A8D8FDB96CA5A4CC8ADD3B6086EDE5DB9FB9DF -% C853EA3D6FA7F4EDADBDE4DCF12CA2B05D6113B6767E637F9566C494DF4967E2 -% F59AB206EFB3DF5375F73DA3B6A67D373DCAF32C658DDCC70703DC24A64B3BAD -% F4A6F52C4DAC8665D277E2DA646D7FEEB8B7FC15BFCDDBFF006E7F395D6B4524 -% 94E3F42EA8FCEA032F9664D07D3B6B321DB99ED79B3E97FEAE5B0B987B8627D6 -% 6CCF4CED65B48B1FB7B13E9B777F9C3D477F5D74CD208D381A7DDA24A5D24924 -% 94FF00FFD1F547025A434C3A343E6B95FAAAE68C4A75DA7DF519D00B1E2835EF -% 67B7E936A733DDF9F52EAD60E574BC9C0CBBB3701A6EC6CA9765E20FA41C4973 -% EDA3F7F7B8EED9F4FD4FE6FE9FE8D29DB37541BBDCE01BC1713027E2A166661D -% 4D2FB6FAEB6375739CF6803E24959B5E4D790C635AE9DA76D8DB25C5A63F384B -% 1CFB2BDAA4DE89D2FD3F57228640F77BF489ECFF00A2D494E65D9197F59AF763 -% 636EA3A55662C79106D3CFBDA47B5BFB98EFFF00D0BFFB8AB6B1FA562E352296 -% B4069FCD048DC63DDB8B8EF7EEFCFF007FFE05FA34B1EE6399E874F6B1B4D6ED -% 81EC1EC6E81EE867B3F7FF007D068E9F6FDAB7643DD786C1208105C3875BEEF7 -% 7FC055FA5F47F9CFE752009DBF15A6755E2DD6D0DADB0D6C37521ADD00D1C36B -% 581BB550B6BC1392F71654ECD11BC020DAD6E9B7D92EB7DCDFDDF52C7AD0B1AD -% 9DE40DEE01AEE4CB44BB6FE6AAB8A5D91634E562D7518B1ECF7377B06E6ED63D -% A3DDEA58D77AB76DFD1D7FCDFBD2063746FE8A24F4AFF0BD281D958ED690F2EA -% F7E9B4CC03EDFD1EDFF02E74B37D5F4FDFFA556A9C864876E0D6C7B23BE9FB8D -% FA5FF93FF068EDA61CE6C35CC70F708E67F7964BB1FD5C9B7EC47EC81AFF004D -% A1DB832C786C96FA2F1ED6FF0053FEDBB13B849BAD695C7FBDE9E8EC5993454D -% 9BAC6543C5CE0047C5D0B3737EB3F4BC7696D160CCC8FCCA68F749FE5DAD9AEB -% FF00ABFDCAEC556DC9739FF63EA558AED322B9FE69F103D967B7F44DF67A9EE6 -% 7FD6958C7C66B59EC6358ED443181A07F298FF00D35D637DDFA3F4DBFF006D26 -% AE73B031B2ADCD7E56701F6ACA2CB1F5813B6B043AA6ECFCDF5ACA29AAADDF4F -% 1E9CABAEFF0008BA7ADBB5B1E249FBC9720518B5B786901C4971792E738E8DDC -% F73FDDEEDBB7FE2995D7FCD2B49294924924A7FFD2F55492492520BB131AD70B -% 2CAC1B1BC5834788F0B1BB5EAB64E48345C08FB5381DAFC6ADA1E040DCEA4EEF -% DE6BBDCFB91731D9EF70A30C32ADD05F91619869277368A5BEEB2EF6FF0085F4 -% AAFD27F86F7D4876E217EFB3A85E3ECC047A0D3B6B826375EF9DF91EDF66C7FE -% 87FE0AD40D9D00DFAA083DE97C66E558FAEDC9BAB68FA5563E39961046DF7DAF -% DAFC86B5AEF66DAA867F215AB9C5AD0448931204F6EEA149AC173995892434B9 -% A002E81B771FCD4AE739DB1F503635AE2486380D60B750EDAD7FF9E8C850D100 -% 820EBDDCCBD96BAC739D7FA75D624B18DFFA565B61FF00A0C594EEB1496EFA1B -% 6B9F4BA77BB6B5AE274DB66DDCEDBFC9DAB6ADE9F8F98D7D598CB5C09DE2A712 -% CD3F976D2FD963777F2D3E1BF16B2DAF02B365434229D82961F377B773FF007F -% 6FA8A200750C03181F30D7C3F97A9CEFB45D9353AABDE0525A1F153C8D9DB67E -% 8EB2E66DFA75D9BFF46B55D9CEAF2EBA2DA5EFA5EC97646D90D33B5A5E59F98F -% 9FFAC7FC56FF0042A757EA34E2B4D2D6B6DC8B012E635DED6B4FB77E44FD062A -% 755DD66DC57D8D76350C8F4BD67B9CD718FCEADCF6BAB73754E8896E02E88978 -% 70F8BB39189899B43314B89A5B04110E0E05AEDA196582CF7B7F9CDECFD325D2 -% 31DD46132AB2CF55ED2438F8104FE8F977F37F450BA6613DB41BAFBBD7C8BD8C -% 6DEE6BB4696496D34D94FA7FA3A9F659EFDBEA588F45D915BC372FD30EB6368A -% C1FA41BFA5DEE27DDF454B44824EFD596EA8550D9B8924926AE524924929FFD3 -% F554C74D53A8BDA1ED2D3C1E47924A44CB1FF69B1AF2D02016346A4B40D6C7FB -% 7DBB9FEC6FFC5A0BB3706CCC6E31BEB75C06E65421CE691FE11DF4B67F21567E -% 0DD915BDF97A5971F731A4B9AD00FE8AA6CFEEB7F9DFF4967A8957F64E9EE656 -% DDAD2E92F7C06807F96EFDE530803B1B95550FE2D696522C513ADBA2DC7A8012 -% DDC7C5DA93F1944F6B60683B008745ECB9BB9A6478F8A8B1EF0FF4DD5B84925D -% 669B493FD53BFF00CE6A866640D166870571446FD833B68A6D20D8D0E2D9027C -% 0FD26FF55CA9D580FC2A5CDC67B4971DCEB2FDC63C5DB1AE6D7F47F36BF415C6 -% 58C2D1E9CB9BC0238FF3BF393DAF656C2EB012D04030D2EE4EDFA2D0EFFCC134 -% 709D579DABBBCE3F0F2B3DD7065FEB536C7AD94DFD1B1DE9977A7563D156F73E -% A6EFFD25B65D67A9FF0017B158FB0E261DB4D977A7EA39BB2AF6973811FE8F76 -% E72D2A3AB74FBC5A59688A1CE6DA4F0DDBF9CE7FF36D67F2B77FE09BD1DD451B -% 8DA58DDF1F4C8D614D0C911A01A3164C529697FF0072D2C3ADF4836DAF739D61 -% 009768E33A37467B559C8B1B5D4D6BD9BD847B817098FA3A6FFA7F4BF7D1DA1A -% 00DBC762B23AC6506D4D0F6C5AED6AD636C3873FBDBFD9FA2FF0B67E8D899932 -% 13B685118184753C44BAB8F732FA596B0CB5C3BE864687FE9222CCFABC727F67 -% 4640877A961699E5AE77A9C7E66C73FD2DBFF06B4D0F3661B6AA49249253FFD4 -% F5550B63D27CC81B4EA2678EDB21FF00E6A9A6735AE696B84B5C2083C1052521 -% 756DB7D37133B007026473DF669EE5917B76BDF6BEB796D7616D4C716D758FE5 -% 0FCEB372D2B32DEC6D0D6D42CB6DD1E1AE68637696B6EF7D858E77A5BBF32BFC -% C51FD9D5BB25F9169F56C71258481B5A3B358DFDEDBF9EA6C79044907A7460CB -% 8CCA363525AACCBCD758DAEB6358D03DDB89E4FEEED5A34D8F6B0BAF78D3BC6D -% 1F892A4DA76C00040F1D4A1370DDB8BAD7FAAE719F701007EEB1A94A5097411F -% CD8F1C32C28EFE1D190BECB2C0DA9AD2CFCE7870D3FAAD83B9584014EC3B8B8B -% 8766E908A663DC62398D1472AD299E065AF10D5AD7D599BB6D26B7D446A2E930 -% 7F77D9FCE31DFCBFA1FF000BBFF461AB1B230B1B2AE786E55AE3BEBC7AC7A758 -% DAD8AE9AD8E758DDCE7FB9F77E7FFDB6AF36D63EB0FACEF69E0B759F8154F32E -% C8C70F758F636A26597381DACFE45CDDDF4BFD1DDFF5BFD17E8FD5611C3A81AA -% FB02CD5F7F1497DD15C5A62752C64C9FE40DB0EFF5FA0B16D75965B664871391 -% EB86D0D0FDD5D15967A5F687532DFD2BB75DE9FF00C27E8FFD221E5E5B9DF67B -% CD576CB5F1481A3AD77954E76F6334FF00468DD3F14D4CB2ECD0319D63CD950B -% 1BC47E84DB65BA535DB6BEFDB8D5DBF99FE0FF009DF4C63F9AE4C71E33648E9A -% 7F55D2E867761B9ED9F49D63853BB9D8C8A013FD6755B968A0E1D031F16AA75F -% 6B759E64FB9DFF0049193E5B9F3648EC1492492097FFD5F5549249252175465C -% 19A171DED9D4077E77B7F95FF56B2197E4B6E353AD3894D0F1E8D75ED797B662 -% E65CCDB635B56EFE6FD3F4ED62DB7B43DA5A6402224120EBE0E6C39AB2BA80B3 -% 1EA631F63D9481FA7CA76E76CAC37F4AF73EBDBFA6DAC6ECBACFD1D7FCF7E93F -% 997B67777F4639020831BBFC1B14F53ADD98EC176E7DD24B0B58E03601BF758E -% 70D9FF0007BD8EFF0047FBEACE564371A875EFFA0C8DE7B35A486BAC77EED75B -% 7F4967F2163538169F4FA8623ADB5EC8153B29C5E367D0F5D94511BDDE9BECF4 -% BDCCFE73E82D5C7C877A7B0EEB6C61DAE716ECDC47EEB53C4254B84C0AE22906 -% 454FAEBBEBB05955801ACD7EF0F0ED5AE6B99BB7336AA7D40D97B4B585D536A9 -% 2E7176D0EFE4EC66EB1EADDEF2C754E86EA483B84BBE8B9D0CD5BFBAA961F56F -% B56406331DCEC7B1FB29BC35DB5C035EFB2F2EDA6AF437B19456EF57D4B2CFF0 -% 7E9FA6FB146601DB50A944CAC0F36A60D79877B8D8E73C18697CB8347FC1876D -% 5A7EADE1BE98607088758490493FBAC60F77F9EC44BD8E6B41A9BE32D02499FE -% DD6D6AA96E6D58A7D323ED196D689AEB074DDF47D5B0EF652D77F2FF00EB75A9 -% 8C8486C3CBAB008CE32278BFB12E174F38F90FCAB6C375D635B5EE7B40735838 -% ADAE6FE6EEF7BFFE11553D359665D7451FA3E9F4B8BDD8EC02BAA49F58C56D1F -% A675B92EDF63FF0099F4FF0043E9FE96E49D5E5E639A2D787020C5357B6B0276 -% D85EF796D96ECFE6FE87FD67F48B4B1B1ABC6ABD3AC47771F13F3DCA23103CFB -% 766789BD3A2649249357292492494FFFD6F554924925290EEA59706EED0B0EE6 -% 38685AE1F9CD3FF47F96CFD1BFF4688924A73FA937A836B73B1ACFA65A37113E -% 9025AC7BEBAEB0DF53FD2FE9ACFF00C013E167E2DEC0DA6C6BAD76E06C6B086B -% 9ECF6DBDBE96EFF07BD5F42BB1E9BD8596B0381F9107F79AF6FB98EFE53521D7 -% B1457F22E4E7E46654FF00758DA5BCBDF638C081BBD9B5BB76FB7E9D8F546BEA -% B936D95DD48BEE6BA41706BEBADC08D3D371FF00C8FBD6FB7A7630209DEF8FA3 -% EA3DCF23FAAFB0B9FDFF0079577742C7B06CBEFC8BABEF5BAD2D0E3FBD61A7D2 -% 7D9FBBB1EFF4BFE0D33835DD8C62FE56E659D4F305753ADB61ECD59435E1BBDC -% DFA2EC87B9DEB3F1B77D3F47F4977FC5AD46306535DE9D64B490E36BC1ADAF71 -% 078AA1B6BABAFD9FF1BFE9559C5C0C2C36918D4B6A9E481A9FEB3CFB9CAC27C6 -% E3B15E23A51D50D18B5504B9A25EE0017F7DADFA15B7F72AAF77E8EB6A324924 -% B94924924A524924929FFFD93842494D04210000000000790000000101000000 -% 1800410064006F00620065002000500068006F0074006F00730068006F007000 -% 200045006C0065006D0065006E007400730000001C00410064006F0062006500 -% 2000500068006F0074006F00730068006F007000200045006C0065006D006500 -% 6E0074007300200032002E003000000001003842494D042200000000012E4D4D -% 002A000000080007011200030000000100010000011A00050000000100000062 -% 011B0005000000010000006A012800030000000100020000013100020000001D -% 0000007201320002000000140000008F8769000400000001000000A4000000D0 -% 0000004800000001000000480000000141646F62652050686F746F73686F7020 -% 456C656D656E747320322E3000323030363A31303A30392032323A30393A3238 -% 00000003A001000300000001FFFF0000A00200040000000100000156A0030004 -% 00000001000001830000000000000006010300030000000100060000011A0005 -% 000000010000011E011B00050000000100000126012800030000000100020000 -% 02010004000000010000012E0202000400000001000000000000000000000048 -% 0000000100000048000000013842494D03FD0000000000070000000000000000 -%EndPhotoshop -%begin_xml_code -/pdfmark where {pop true} {false} ifelse -/currentdistillerparams where {pop currentdistillerparams -/CoreDistVersion get 5000 ge } {false} ifelse -and not {userdict /pdfmark /cleartomark load put} if -[/NamespacePush pdfmark -[/_objdef {photoshop_metadata_stream} /type /stream /OBJ pdfmark -/MetadataString 5038 string def % exact length of metadata -/TempString 100 string def -/ConsumeMetadata { -currentfile TempString readline pop pop -currentfile MetadataString readstring pop pop -} bind def -ConsumeMetadata -%begin_xml_packet: 5038 -<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> +%!PS-Adobe-3.0 EPSF-3.0
%%Title: brave-gnu-world-logo.25.eps
%%CreationDate: 09.10.2006 22:09 Uhr
%%BoundingBox: 0 0 342 387
%%HiResBoundingBox: 0 0 342 387
%%SuppressDotGainCompensation
%%EndComments
%%BeginProlog
%%EndProlog
%%BeginSetup
%%EndSetup
%ImageData: 342 387 8 3 0 1 3 "beginimage"
%BeginPhotoshop: 13952
% 3842494D0425000000000010000000000000000000000000000000003842494D
% 03EA000000001DA63C3F786D6C2076657273696F6E3D22312E302220656E636F
% 64696E673D225554462D38223F3E0A3C21444F435459504520706C6973742050
% 55424C494320222D2F2F4170706C6520436F6D70757465722F2F44544420504C
% 49535420312E302F2F454E222022687474703A2F2F7777772E6170706C652E63
% 6F6D2F445444732F50726F70657274794C6973742D312E302E647464223E0A3C
% 706C6973742076657273696F6E3D22312E30223E0A3C646963743E0A093C6B65
% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D48
% 6F72697A6F6E74616C5265733C2F6B65793E0A093C646963743E0A09093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F72
% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74
% 696E676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E61
% 70706C652E7072696E742E7469636B65742E6974656D41727261793C2F6B6579
% 3E0A09093C61727261793E0A0909093C646963743E0A090909093C6B65793E63
% 6F6D2E6170706C652E7072696E742E50616765466F726D61742E504D486F7269
% 7A6F6E74616C5265733C2F6B65793E0A090909093C7265616C3E37323C2F7265
% 616C3E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F6D
% 2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E0A
% 090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D31302D
% 30395432303A30333A33365A3C2F646174653E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B
% 65793E0A090909093C696E74656765723E303C2F696E74656765723E0A090909
% 3C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B65
% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D4F
% 7269656E746174696F6E3C2F6B65793E0A093C646963743E0A09093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F
% 6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E
% 676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E617070
% 6C652E7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A
% 09093C61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E50616765466F726D61742E504D4F7269656E74
% 6174696F6E3C2F6B65793E0A090909093C696E74656765723E313C2F696E7465
% 6765723E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469
% 636B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F
% 6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E
% 0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D3130
% 2D30395432303A30333A33365A3C2F646174653E0A090909093C6B65793E636F
% 6D2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F
% 6B65793E0A090909093C696E74656765723E303C2F696E74656765723E0A0909
% 093C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B
% 65793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D
% 5363616C696E673C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F6B6579
% 3E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E676D61
% 6E616765723C2F737472696E673E0A09093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A09093C
% 61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E50616765466F726D61742E504D5363616C696E673C2F
% 6B65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B6579
% 3E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F
% 6B65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E74
% 696E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B6579
% 3E0A090909093C646174653E323030362D31302D30395432303A30333A33365A
% 3C2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E74
% 656765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F
% 61727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E
% 7072696E742E50616765466F726D61742E504D566572746963616C5265733C2F
% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072
% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909
% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E50616765466F726D61742E504D566572746963616C5265733C2F6B65793E0A
% 090909093C7265616C3E37323C2F7265616C3E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B65793E
% 0A090909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D
% 616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E617070
% 6C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E0A0909
% 09093C646174653E323030362D31302D30395432303A30333A33365A3C2F6461
% 74653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465676572
% 3E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61727261
% 793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E7072696E
% 742E50616765466F726D61742E504D566572746963616C5363616C696E673C2F
% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072
% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909
% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E50616765466F726D61742E504D566572746963616C5363616C696E673C2F6B
% 65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B
% 65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E7469
% 6E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E
% 6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E
% 0A090909093C646174653E323030362D31302D30395432303A30333A33365A3C
% 2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465
% 6765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61
% 727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E70
% 72696E742E7375625469636B65742E70617065725F696E666F5F7469636B6574
% 3C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E
% 7072696E742E50616765466F726D61742E504D41646A75737465645061676552
% 6563743C2F6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E61
% 70706C652E7072696E742E7469636B65742E63726561746F723C2F6B65793E0A
% 0909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D616E
% 616765723C2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A090909
% 3C61727261793E0A090909093C646963743E0A09090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E50616765466F726D61742E504D41646A757374
% 656450616765526563743C2F6B65793E0A09090909093C61727261793E0A0909
% 090909093C7265616C3E302E303C2F7265616C3E0A0909090909093C7265616C
% 3E302E303C2F7265616C3E0A0909090909093C7265616C3E3738333C2F726561
% 6C3E0A0909090909093C7265616C3E3535393C2F7265616C3E0A09090909093C
% 2F61727261793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E
% 742E7469636B65742E636C69656E743C2F6B65793E0A09090909093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 7469636B65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E
% 323030362D31302D30395432303A30333A33365A3C2F646174653E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E737461
% 7465466C61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E
% 74656765723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09
% 093C2F646963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E
% 50616765466F726D61742E504D41646A75737465645061706572526563743C2F
% 6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E63726561746F723C2F6B65793E0A0909093C73
% 7472696E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C
% 2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E7469636B65742E6974656D41727261793C2F6B65793E0A0909093C61727261
% 793E0A090909093C646963743E0A09090909093C6B65793E636F6D2E6170706C
% 652E7072696E742E50616765466F726D61742E504D41646A7573746564506170
% 6572526563743C2F6B65793E0A09090909093C61727261793E0A090909090909
% 3C7265616C3E2D31383C2F7265616C3E0A0909090909093C7265616C3E2D3138
% 3C2F7265616C3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A09
% 09090909093C7265616C3E3537373C2F7265616C3E0A09090909093C2F617272
% 61793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469
% 636B65742E636C69656E743C2F6B65793E0A09090909093C737472696E673E63
% 6F6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E67
% 3E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B
% 65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E32303036
% 2D31302D30395432303A30333A33365A3C2F646174653E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E7374617465466C
% 61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E74656765
% 723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09093C2F64
% 6963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E50617065
% 72496E666F2E504D50617065724E616D653C2F6B65793E0A09093C646963743E
% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E617070
% 6C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A
% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E69
% 74656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C64
% 6963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E50
% 61706572496E666F2E504D50617065724E616D653C2F6B65793E0A0909090909
% 3C737472696E673E69736F2D61343C2F737472696E673E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C
% 2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C652E707269
% 6E742E706D2E506F73745363726970743C2F737472696E673E0A09090909093C
% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461
% 74653C2F6B65793E0A09090909093C646174653E323030332D30372D30315431
% 373A34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E
% 0A09090909093C696E74656765723E313C2F696E74656765723E0A090909093C
% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C
% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D
% 556E61646A757374656450616765526563743C2F6B65793E0A09093C64696374
% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170
% 706C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E
% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 6974656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C
% 646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 5061706572496E666F2E504D556E61646A757374656450616765526563743C2F
% 6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E302E
% 303C2F7265616C3E0A0909090909093C7265616C3E302E303C2F7265616C3E0A
% 0909090909093C7265616C3E3738333C2F7265616C3E0A0909090909093C7265
% 616C3E3535393C2F7265616C3E0A09090909093C2F61727261793E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69
% 656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C65
% 2E7072696E74696E676D616E616765723C2F737472696E673E0A09090909093C
% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461
% 74653C2F6B65793E0A09090909093C646174653E323030362D31302D30395432
% 303A30333A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E
% 0A09090909093C696E74656765723E303C2F696E74656765723E0A090909093C
% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C
% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D
% 556E61646A75737465645061706572526563743C2F6B65793E0A09093C646963
% 743E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65
% 742E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E61
% 70706C652E7072696E742E706D2E506F73745363726970743C2F737472696E67
% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E6974656D41727261793C2F6B65793E0A0909093C61727261793E0A09090909
% 3C646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E5061706572496E666F2E504D556E61646A7573746564506170657252656374
% 3C2F6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E
% 2D31383C2F7265616C3E0A0909090909093C7265616C3E2D31383C2F7265616C
% 3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A0909090909093C
% 7265616C3E3537373C2F7265616C3E0A09090909093C2F61727261793E0A0909
% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E63
% 6C69656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E617070
% 6C652E7072696E74696E676D616E616765723C2F737472696E673E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F64
% 446174653C2F6B65793E0A09090909093C646174653E323030362D31302D3039
% 5432303A30333A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E
% 6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65
% 793E0A09090909093C696E74656765723E303C2F696E74656765723E0A090909
% 093C2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09
% 093C6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E
% 7070642E504D50617065724E616D653C2F6B65793E0A09093C646963743E0A09
% 09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6372
% 6561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170706C65
% 2E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A0909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E697465
% 6D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C646963
% 743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E506170
% 6572496E666F2E7070642E504D50617065724E616D653C2F6B65793E0A090909
% 09093C737472696E673E41343C2F737472696E673E0A09090909093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B
% 65793E0A09090909093C737472696E673E636F6D2E6170706C652E7072696E74
% 2E706D2E506F73745363726970743C2F737472696E673E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F6444617465
% 3C2F6B65793E0A09090909093C646174653E323030332D30372D30315431373A
% 34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170706C
% 652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E0A09
% 090909093C696E74656765723E313C2F696E74656765723E0A090909093C2F64
% 6963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E41504956657273
% 696F6E3C2F6B65793E0A09093C737472696E673E30302E32303C2F737472696E
% 673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E707269766174654C6F636B3C2F6B65793E0A09093C66616C73652F3E0A0909
% 3C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74797065
% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74
% 2E5061706572496E666F5469636B65743C2F737472696E673E0A093C2F646963
% 743E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 41504956657273696F6E3C2F6B65793E0A093C737472696E673E30302E32303C
% 2F737472696E673E0A093C6B65793E636F6D2E6170706C652E7072696E742E74
% 69636B65742E707269766174654C6F636B3C2F6B65793E0A093C66616C73652F
% 3E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74
% 7970653C2F6B65793E0A093C737472696E673E636F6D2E6170706C652E707269
% 6E742E50616765466F726D61745469636B65743C2F737472696E673E0A3C2F64
% 6963743E0A3C2F706C6973743E0A3842494D03E9000000000078000300000048
% 004800000000030F022FFFEEFFEE033802410367057B03E00002000000480048
% 0000000002D802280001000000640000000100030303000000017FFF00010001
% 0000000000000000000000006808001901900000000000200000000000000000
% 0000000000000000000000000000000000003842494D03ED0000000000100048
% 00000001000200480000000100023842494D042600000000000E000000000000
% 000000003F8000003842494D040D0000000000040000001E3842494D04190000
% 000000040000001E3842494D03F3000000000009000000000000000001003842
% 494D040A00000000000100003842494D271000000000000A0001000000000000
% 00023842494D03F5000000000048002F66660001006C66660006000000000001
% 002F6666000100A1999A0006000000000001003200000001005A000000060000
% 00000001003500000001002D000000060000000000013842494D03F800000000
% 00700000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000
% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFF
% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFFFFFFFFFF
% FFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800003842494D04080000000000100000
% 00010000024000000240000000003842494D041E000000000004000000003842
% 494D041A00000000036300000006000000000000000000000183000001560000
% 001700620072006100760065002D0067006E0075002D0077006F0072006C0064
% 002D006C006F0067006F002E0032003500000001000000000000000000000000
% 0000000000000001000000000000000000000156000001830000000000000000
% 0000000000000000010000000000000000000000000000000000000010000000
% 010000000000006E756C6C0000000200000006626F756E64734F626A63000000
% 01000000000000526374310000000400000000546F70206C6F6E670000000000
% 0000004C6566746C6F6E67000000000000000042746F6D6C6F6E670000018300
% 000000526768746C6F6E670000015600000006736C69636573566C4C73000000
% 014F626A6300000001000000000005736C6963650000001200000007736C6963
% 6549446C6F6E67000000000000000767726F757049446C6F6E67000000000000
% 00066F726967696E656E756D0000000C45536C6963654F726967696E0000000D
% 6175746F47656E6572617465640000000054797065656E756D0000000A45536C
% 6963655479706500000000496D672000000006626F756E64734F626A63000000
% 01000000000000526374310000000400000000546F70206C6F6E670000000000
% 0000004C6566746C6F6E67000000000000000042746F6D6C6F6E670000018300
% 000000526768746C6F6E67000001560000000375726C54455854000000010000
% 000000006E756C6C54455854000000010000000000004D736765544558540000
% 0001000000000006616C74546167544558540000000100000000000E63656C6C
% 54657874497348544D4C626F6F6C010000000863656C6C546578745445585400
% 000001000000000009686F727A416C69676E656E756D0000000F45536C696365
% 486F727A416C69676E0000000764656661756C740000000976657274416C6967
% 6E656E756D0000000F45536C69636556657274416C69676E0000000764656661
% 756C740000000B6267436F6C6F7254797065656E756D0000001145536C696365
% 4247436F6C6F7254797065000000004E6F6E6500000009746F704F7574736574
% 6C6F6E67000000000000000A6C6566744F75747365746C6F6E67000000000000
% 000C626F74746F6D4F75747365746C6F6E67000000000000000B72696768744F
% 75747365746C6F6E6700000000003842494D041100000000000101003842494D
% 0414000000000004000000013842494D040C0000000011340000000100000071
% 00000080000001540000AA000000111800180001FFD8FFE000104A4649460001
% 0201004800480000FFED000C41646F62655F434D0002FFEE000E41646F626500
% 648000000001FFDB0084000C08080809080C09090C110B0A0B11150F0C0C0F15
% 18131315131318110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C
% 0C0C0C0C0C0C0C0C0C0C0C010D0B0B0D0E0D100E0E10140E0E0E14140E0E0E0E
% 14110C0C0C0C0C11110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C
% 0C0C0C0C0C0C0C0C0C0C0C0CFFC00011080080007103012200021101031101FF
% DD00040008FFC4013F0000010501010101010100000000000000030001020405
% 060708090A0B0100010501010101010100000000000000010002030405060708
% 090A0B1000010401030204020507060805030C33010002110304211231054151
% 611322718132061491A1B14223241552C16233347282D14307259253F0E1F163
% 733516A2B283264493546445C2A3743617D255E265F2B384C3D375E3F3462794
% A485B495C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F637475767778797
% A7B7C7D7E7F71100020201020404030405060707060535010002110321311204
% 4151617122130532819114A1B14223C152D1F0332462E1728292435315637334
% F1250616A2B283072635C2D2449354A317644555367465E2F2B384C3D375E3F3
% 4694A485B495C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F62737475767
% 778797A7B7C7FFDA000C03010002110311003F00F5549249252952EA5D6303A6
% B01C9B3F48E04D74B06EB1D1FBACFDCFCDF56CD94FEFD8A9F5AEB8EC4B1B8182
% CF5BA85A040896B377D17387B7D4B1DB7D94FF00D72EF4AA50E93F57C54F766F
% 513F69CDB4EE739E43849FECB5AE733E87B7F435FD0A2AAAA494969FAC06FD6A
% C0CA73791ED64F9E82C72B9566DF63B6FD8EE66B05CF35868F3FE777BBFB0C56
% 80F979240009294275911E09D2492535322DEA35585D5555E4526206E2C7B74F
% 76ED2C6DBEEFDDF4FF00E2FF00C22A77F51EAFF46BC7C7A9C7F3ADB6C81F9DF4
% 7D0ABF35BFBEB5D2494E5E066E7DAE8BDF8CFD09D94EEDC60EDFCF73BF3BF796
% 931E1ED04692260F2151EA1D1E9CB3EAD4EFB3E50D45AD120FFC755F46DFFCF9
% FCB553A7F53BC669E9FD440A731809601F42D1AFE998FF00F09BA3D9FF00A53D
% 8929DB49327494A49249253FFFD0F55599D77ABFECDA18DA5A2CCCC825B8EC3A
% 8111BEE7810E732ADECF637F9DB5F553FA3F53D5669AE4F12D6F53EB36752B3D
% F57A831F10088D8D163FD4DDB7E8B696DD97F43E9E4D74FF00A2494E8740E91E
% 8B1F999536655F2E7BDC649DC439DBB46B7DDB7F37FF003C7A55ADBF34CC6ED6
% 86F8052494A49258791F59EB7DBF67E9349EA16FFA469DB5027DA3F4B0EF57FA
% D5B7D1FF0086494EE24B370733A8D8FDB96CA5A4CC8ADD3B6086EDE5DB9FB9DF
% C853EA3D6FA7F4EDADBDE4DCF12CA2B05D6113B6767E637F9566C494DF4967E2
% F59AB206EFB3DF5375F73DA3B6A67D373DCAF32C658DDCC70703DC24A64B3BAD
% F4A6F52C4DAC8665D277E2DA646D7FEEB8B7FC15BFCDDBFF006E7F395D6B4524
% 94E3F42EA8FCEA032F9664D07D3B6B321DB99ED79B3E97FEAE5B0B987B8627D6
% 6CCF4CED65B48B1FB7B13E9B777F9C3D477F5D74CD208D381A7DDA24A5D24924
% 94FF00FFD1F547025A434C3A343E6B95FAAAE68C4A75DA7DF519D00B1E2835EF
% 67B7E936A733DDF9F52EAD60E574BC9C0CBBB3701A6EC6CA9765E20FA41C4973
% EDA3F7F7B8EED9F4FD4FE6FE9FE8D29DB37541BBDCE01BC1713027E2A166661D
% 4D2FB6FAEB6375739CF6803E24959B5E4D790C635AE9DA76D8DB25C5A63F384B
% 1CFB2BDAA4DE89D2FD3F57228640F77BF489ECFF00A2D494E65D9197F59AF763
% 636EA3A55662C79106D3CFBDA47B5BFB98EFFF00D0BFFB8AB6B1FA562E352296
% B4069FCD048DC63DDB8B8EF7EEFCFF007FFE05FA34B1EE6399E874F6B1B4D6ED
% 81EC1EC6E81EE867B3F7FF007D068E9F6FDAB7643DD786C1208105C3875BEEF7
% 7FC055FA5F47F9CFE752009DBF15A6755E2DD6D0DADB0D6C37521ADD00D1C36B
% 581BB550B6BC1392F71654ECD11BC020DAD6E9B7D92EB7DCDFDDF52C7AD0B1AD
% 9DE40DEE01AEE4CB44BB6FE6AAB8A5D91634E562D7518B1ECF7377B06E6ED63D
% A3DDEA58D77AB76DFD1D7FCDFBD2063746FE8A24F4AFF0BD281D958ED690F2EA
% F7E9B4CC03EDFD1EDFF02E74B37D5F4FDFFA556A9C864876E0D6C7B23BE9FB8D
% FA5FF93FF068EDA61CE6C35CC70F708E67F7964BB1FD5C9B7EC47EC81AFF004D
% A1DB832C786C96FA2F1ED6FF0053FEDBB13B849BAD695C7FBDE9E8EC5993454D
% 9BAC6543C5CE0047C5D0B3737EB3F4BC7696D160CCC8FCCA68F749FE5DAD9AEB
% FF00ABFDCAEC556DC9739FF63EA558AED322B9FE69F103D967B7F44DF67A9EE6
% 7FD6958C7C66B59EC6358ED443181A07F298FF00D35D637DDFA3F4DBFF006D26
% AE73B031B2ADCD7E56701F6ACA2CB1F5813B6B043AA6ECFCDF5ACA29AAADDF4F
% 1E9CABAEFF0008BA7ADBB5B1E249FBC9720518B5B786901C4971792E738E8DDC
% F73FDDEEDBB7FE2995D7FCD2B49294924924A7FFD2F55492492520BB131AD70B
% 2CAC1B1BC5834788F0B1BB5EAB64E48345C08FB5381DAFC6ADA1E040DCEA4EEF
% DE6BBDCFB91731D9EF70A30C32ADD05F91619869277368A5BEEB2EF6FF0085F4
% AAFD27F86F7D4876E217EFB3A85E3ECC047A0D3B6B826375EF9DF91EDF66C7FE
% 87FE0AD40D9D00DFAA083DE97C66E558FAEDC9BAB68FA5563E39961046DF7DAF
% DAFC86B5AEF66DAA867F215AB9C5AD0448931204F6EEA149AC173995892434B9
% A002E81B771FCD4AE739DB1F503635AE2486380D60B750EDAD7FF9E8C850D100
% 820EBDDCCBD96BAC739D7FA75D624B18DFFA565B61FF00A0C594EEB1496EFA1B
% 6B9F4BA77BB6B5AE274DB66DDCEDBFC9DAB6ADE9F8F98D7D598CB5C09DE2A712
% CD3F976D2FD963777F2D3E1BF16B2DAF02B365434229D82961F377B773FF007F
% 6FA8A200750C03181F30D7C3F97A9CEFB45D9353AABDE0525A1F153C8D9DB67E
% 8EB2E66DFA75D9BFF46B55D9CEAF2EBA2DA5EFA5EC97646D90D33B5A5E59F98F
% 9FFAC7FC56FF0042A757EA34E2B4D2D6B6DC8B012E635DED6B4FB77E44FD062A
% 755DD66DC57D8D76350C8F4BD67B9CD718FCEADCF6BAB73754E8896E02E88978
% 70F8BB39189899B43314B89A5B04110E0E05AEDA196582CF7B7F9CDECFD325D2
% 31DD46132AB2CF55ED2438F8104FE8F977F37F450BA6613DB41BAFBBD7C8BD8C
% 6DEE6BB4696496D34D94FA7FA3A9F659EFDBEA588F45D915BC372FD30EB6368A
% C1FA41BFA5DEE27DDF454B44824EFD596EA8550D9B8924926AE524924929FFD3
% F554C74D53A8BDA1ED2D3C1E47924A44CB1FF69B1AF2D02016346A4B40D6C7FB
% 7DBB9FEC6FFC5A0BB3706CCC6E31BEB75C06E65421CE691FE11DF4B67F21567E
% 0DD915BDF97A5971F731A4B9AD00FE8AA6CFEEB7F9DFF4967A8957F64E9EE656
% DDAD2E92F7C06807F96EFDE530803B1B95550FE2D696522C513ADBA2DC7A8012
% DDC7C5DA93F1944F6B60683B008745ECB9BB9A6478F8A8B1EF0FF4DD5B84925D
% 669B493FD53BFF00CE6A866640D166870571446FD833B68A6D20D8D0E2D9027C
% 0FD26FF55CA9D580FC2A5CDC67B4971DCEB2FDC63C5DB1AE6D7F47F36BF415C6
% 58C2D1E9CB9BC0238FF3BF393DAF656C2EB012D04030D2EE4EDFA2D0EFFCC134
% 709D579DABBBCE3F0F2B3DD7065FEB536C7AD94DFD1B1DE9977A7563D156F73E
% A6EFFD25B65D67A9FF0017B158FB0E261DB4D977A7EA39BB2AF6973811FE8F76
% E72D2A3AB74FBC5A59688A1CE6DA4F0DDBF9CE7FF36D67F2B77FE09BD1DD451B
% 8DA58DDF1F4C8D614D0C911A01A3164C529697FF0072D2C3ADF4836DAF739D61
% 009768E33A37467B559C8B1B5D4D6BD9BD847B817098FA3A6FFA7F4BF7D1DA1A
% 00DBC762B23AC6506D4D0F6C5AED6AD636C3873FBDBFD9FA2FF0B67E8D899932
% 13B685118184753C44BAB8F732FA596B0CB5C3BE864687FE9222CCFABC727F67
% 4640877A961699E5AE77A9C7E66C73FD2DBFF06B4D0F3661B6AA49249253FFD4
% F5550B63D27CC81B4EA2678EDB21FF00E6A9A6735AE696B84B5C2083C1052521
% 756DB7D37133B007026473DF669EE5917B76BDF6BEB796D7616D4C716D758FE5
% 0FCEB372D2B32DEC6D0D6D42CB6DD1E1AE68637696B6EF7D858E77A5BBF32BFC
% C51FD9D5BB25F9169F56C71258481B5A3B358DFDEDBF9EA6C79044907A7460CB
% 8CCA363525AACCBCD758DAEB6358D03DDB89E4FEEED5A34D8F6B0BAF78D3BC6D
% 1F892A4DA76C00040F1D4A1370DDB8BAD7FAAE719F701007EEB1A94A5097411F
% CD8F1C32C28EFE1D190BECB2C0DA9AD2CFCE7870D3FAAD83B9584014EC3B8B8B
% 8766E908A663DC62398D1472AD299E065AF10D5AD7D599BB6D26B7D446A2E930
% 7F77D9FCE31DFCBFA1FF000BBFF461AB1B230B1B2AE786E55AE3BEBC7AC7A758
% DAD8AE9AD8E758DDCE7FB9F77E7FFDB6AF36D63EB0FACEF69E0B759F8154F32E
% C8C70F758F636A26597381DACFE45CDDDF4BFD1DDFF5BFD17E8FD5611C3A81AA
% FB02CD5F7F1497DD15C5A62752C64C9FE40DB0EFF5FA0B16D75965B664871391
% EB86D0D0FDD5D15967A5F687532DFD2BB75DE9FF00C27E8FFD221E5E5B9DF67B
% CD576CB5F1481A3AD77954E76F6334FF00468DD3F14D4CB2ECD0319D63CD950B
% 1BC47E84DB65BA535DB6BEFDB8D5DBF99FE0FF009DF4C63F9AE4C71E33648E9A
% 7F55D2E867761B9ED9F49D63853BB9D8C8A013FD6755B968A0E1D031F16AA75F
% 6B759E64FB9DFF0049193E5B9F3648EC1492492097FFD5F5549249252175465C
% 19A171DED9D4077E77B7F95FF56B2197E4B6E353AD3894D0F1E8D75ED797B662
% E65CCDB635B56EFE6FD3F4ED62DB7B43DA5A6402224120EBE0E6C39AB2BA80B3
% 1EA631F63D9481FA7CA76E76CAC37F4AF73EBDBFA6DAC6ECBACFD1D7FCF7E93F
% 997B67777F4639020831BBFC1B14F53ADD98EC176E7DD24B0B58E03601BF758E
% 70D9FF0007BD8EFF0047FBEACE564371A875EFFA0C8DE7B35A486BAC77EED75B
% 7F4967F2163538169F4FA8623ADB5EC8153B29C5E367D0F5D94511BDDE9BECF4
% BDCCFE73E82D5C7C877A7B0EEB6C61DAE716ECDC47EEB53C4254B84C0AE22906
% 454FAEBBEBB05955801ACD7EF0F0ED5AE6B99BB7336AA7D40D97B4B585D536A9
% 2E7176D0EFE4EC66EB1EADDEF2C754E86EA483B84BBE8B9D0CD5BFBAA961F56F
% B56406331DCEC7B1FB29BC35DB5C035EFB2F2EDA6AF437B19456EF57D4B2CFF0
% 7E9FA6FB146601DB50A944CAC0F36A60D79877B8D8E73C18697CB8347FC1876D
% 5A7EADE1BE98607088758490493FBAC60F77F9EC44BD8E6B41A9BE32D02499FE
% DD6D6AA96E6D58A7D323ED196D689AEB074DDF47D5B0EF652D77F2FF00EB75A9
% 8C8486C3CBAB008CE32278BFB12E174F38F90FCAB6C375D635B5EE7B40735838
% ADAE6FE6EEF7BFFE11553D359665D7451FA3E9F4B8BDD8EC02BAA49F58C56D1F
% A675B92EDF63FF0099F4FF0043E9FE96E49D5E5E639A2D787020C5357B6B0276
% D85EF796D96ECFE6FE87FD67F48B4B1B1ABC6ABD3AC47771F13F3DCA23103CFB
% 766789BD3A2649249357292492494FFFD6F554924925290EEA59706EED0B0EE6
% 38685AE1F9CD3FF47F96CFD1BFF4688924A73FA937A836B73B1ACFA65A37113E
% 9025AC7BEBAEB0DF53FD2FE9ACFF00C013E167E2DEC0DA6C6BAD76E06C6B086B
% 9ECF6DBDBE96EFF07BD5F42BB1E9BD8596B0381F9107F79AF6FB98EFE53521D7
% B1457F22E4E7E46654FF00758DA5BCBDF638C081BBD9B5BB76FB7E9D8F546BEA
% B936D95DD48BEE6BA41706BEBADC08D3D371FF00C8FBD6FB7A7630209DEF8FA3
% EA3DCF23FAAFB0B9FDFF0079577742C7B06CBEFC8BABEF5BAD2D0E3FBD61A7D2
% 7D9FBBB1EFF4BFE0D33835DD8C62FE56E659D4F305753ADB61ECD59435E1BBDC
% DFA2EC87B9DEB3F1B77D3F47F4977FC5AD46306535DE9D64B490E36BC1ADAF71
% 078AA1B6BABAFD9FF1BFE9559C5C0C2C36918D4B6A9E481A9FEB3CFB9CAC27C6
% E3B15E23A51D50D18B5504B9A25EE0017F7DADFA15B7F72AAF77E8EB6A324924
% B94924924A524924929FFFD93842494D04210000000000790000000101000000
% 1800410064006F00620065002000500068006F0074006F00730068006F007000
% 200045006C0065006D0065006E007400730000001C00410064006F0062006500
% 2000500068006F0074006F00730068006F007000200045006C0065006D006500
% 6E0074007300200032002E003000000001003842494D042200000000012E4D4D
% 002A000000080007011200030000000100010000011A00050000000100000062
% 011B0005000000010000006A012800030000000100020000013100020000001D
% 0000007201320002000000140000008F8769000400000001000000A4000000D0
% 0000004800000001000000480000000141646F62652050686F746F73686F7020
% 456C656D656E747320322E3000323030363A31303A30392032323A30393A3238
% 00000003A001000300000001FFFF0000A00200040000000100000156A0030004
% 00000001000001830000000000000006010300030000000100060000011A0005
% 000000010000011E011B00050000000100000126012800030000000100020000
% 02010004000000010000012E0202000400000001000000000000000000000048
% 0000000100000048000000013842494D03FD0000000000070000000000000000
%EndPhotoshop
%begin_xml_code
/pdfmark where {pop true} {false} ifelse
/currentdistillerparams where {pop currentdistillerparams
/CoreDistVersion get 5000 ge } {false} ifelse
and not {userdict /pdfmark /cleartomark load put} if
[/NamespacePush pdfmark
[/_objdef {photoshop_metadata_stream} /type /stream /OBJ pdfmark
/MetadataString 5038 string def % exact length of metadata
/TempString 100 string def
/ConsumeMetadata {
currentfile TempString readline pop pop
currentfile MetadataString readstring pop pop
} bind def
ConsumeMetadata
%begin_xml_packet: 5038
<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> <?adobe-xap-filters esc="CR"?> <x:xapmeta xmlns:x='adobe:ns:meta/' x:xaptk='XMP toolkit 2.8.2-33, framework 1.5'> <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'> @@ -526,77 +61,7 @@ ConsumeMetadata -<?xpacket end='w'?> -%end_xml_packet -[{photoshop_metadata_stream} 2 dict begin /Type /Metadata def /Subtype /XML def currentdict end /PUT pdfmark -[{photoshop_metadata_stream} MetadataString /PUT pdfmark -[/_objdef {nextImage} /NI pdfmark -%end_xml_code -gsave % EPS gsave -/hascolor -/deviceinfo where -{pop deviceinfo /Colors known -{deviceinfo /Colors get exec 1 gt} -{false} ifelse} -{/statusdict where -{pop statusdict /processcolors known -{statusdict /processcolors get exec 1 gt} -{false} ifelse} -{false} ifelse} -ifelse -def -40 dict begin -/_image systemdict /image get def -/_setgray systemdict /setgray get def -/_currentgray systemdict /currentgray get def -/_settransfer systemdict /settransfer get def -/_currenttransfer systemdict /currenttransfer get def -/blank 0 _currenttransfer exec -1 _currenttransfer exec eq def -/negative blank -{0 _currenttransfer exec 0.5 lt} -{0 _currenttransfer exec 1 _currenttransfer exec gt} -ifelse def -/inverted? negative def -/level2 systemdict /languagelevel known -{languagelevel 2 ge} {false} ifelse def -/level3 systemdict /languagelevel known -{languagelevel 3 ge} {false} ifelse def -level2 {/band 0 def} {/band 5 def} ifelse -gsave % Image Header gsave -/rows 387 def -/cols 342 def -342 387 scale -level2 { -/DeviceRGB -setcolorspace currentdict /PhotoshopDuotoneColorSpace undef currentdict /PhotoshopDuotoneAltColorSpace undef } if -/beginimage level2 -{/image load def} -{{pop .9 setgray 0 0 moveto 0 1 lineto -1 1 lineto 1 0 lineto fill 0 setgray -0 1 translate 1 cols div 1 rows div scale -/ratio {cols 400 div mul} def -/Helvetica findfont 15 ratio scalefont setfont -5 ratio -20 ratio moveto -(Mit JPEG komprimierte Bilder ben\232tigen PostScript Level 2) show -/x 128 string def -{currentfile x readline {} {pop exit} ifelse -(~>) search {pop pop pop exit} {pop} ifelse -} loop } def} -ifelse -12 dict begin -/ImageType 1 def -/Width cols def -/Height rows def -/ImageMatrix [cols 0 0 rows neg 0 rows] def -/BitsPerComponent 8 def -/Decode [0 1 0 1 0 1] def -/DataSource currentfile /ASCII85Decode filter -/DCTDecode filter def -currentdict end -%%BeginBinary: 12801 -beginimage -s4IA0!"_al8O`[\!W`9l!([(is6]js6"FnCAH67k!!!!"s4[O,!"obO%M0*b&.fQt +<?xpacket end='w'?>
%end_xml_packet
[{photoshop_metadata_stream} 2 dict begin /Type /Metadata def /Subtype /XML def currentdict end /PUT pdfmark
[{photoshop_metadata_stream} MetadataString /PUT pdfmark
[/_objdef {nextImage} /NI pdfmark
%end_xml_code
gsave % EPS gsave
/hascolor
/deviceinfo where
{pop deviceinfo /Colors known
{deviceinfo /Colors get exec 1 gt}
{false} ifelse}
{/statusdict where
{pop statusdict /processcolors known
{statusdict /processcolors get exec 1 gt}
{false} ifelse}
{false} ifelse}
ifelse
def
40 dict begin
/_image systemdict /image get def
/_setgray systemdict /setgray get def
/_currentgray systemdict /currentgray get def
/_settransfer systemdict /settransfer get def
/_currenttransfer systemdict /currenttransfer get def
/blank 0 _currenttransfer exec
1 _currenttransfer exec eq def
/negative blank
{0 _currenttransfer exec 0.5 lt}
{0 _currenttransfer exec 1 _currenttransfer exec gt}
ifelse def
/inverted? negative def
/level2 systemdict /languagelevel known
{languagelevel 2 ge} {false} ifelse def
/level3 systemdict /languagelevel known
{languagelevel 3 ge} {false} ifelse def
level2 {/band 0 def} {/band 5 def} ifelse
gsave % Image Header gsave
/rows 387 def
/cols 342 def
342 387 scale
level2 {
/DeviceRGB
setcolorspace currentdict /PhotoshopDuotoneColorSpace undef currentdict /PhotoshopDuotoneAltColorSpace undef } if
/beginimage level2
{/image load def}
{{pop .9 setgray 0 0 moveto 0 1 lineto
1 1 lineto 1 0 lineto fill 0 setgray
0 1 translate 1 cols div 1 rows div scale
/ratio {cols 400 div mul} def
/Helvetica findfont 15 ratio scalefont setfont
5 ratio -20 ratio moveto
(Mit JPEG komprimierte Bilder ben\232tigen PostScript Level 2) show
/x 128 string def
{currentfile x readline {} {pop exit} ifelse
(~>) search {pop pop pop exit} {pop} ifelse
} loop } def}
ifelse
12 dict begin
/ImageType 1 def
/Width cols def
/Height rows def
/ImageMatrix [cols 0 0 rows neg 0 rows] def
/BitsPerComponent 8 def
/Decode [0 1 0 1 0 1] def
/DataSource currentfile /ASCII85Decode filter
/DCTDecode filter def
currentdict end
%%BeginBinary: 12801
beginimage
s4IA0!"_al8O`[\!W`9l!([(is6]js6"FnCAH67k!!!!"s4[O,!"obO%M0*b&.fQt '+km!,8q:3)C$FB(Ddl(+qY4l$k*OQ&I]'V$k*OQ$k*OQ$k*OQ$k*OQ$k*OQ$k*OQ $iq%U',DH$)]';0'FkT_'GM#e%Ls0b$k*OQ$kX'[$k*OQ$kWmV$k*OQ$k*OQ$k*OQ $k*OQ$k*OQ$k*OQ$k30O!"fJ;K)o!T!?qLF&HMtG!WUsU"995;_uW(&!!*6(!<E3% @@ -789,9 +254,4 @@ P"?rK,a(_k8L0HsP"?p`Uln:q.3t'J8kC:k;NaTsPekl!n"d`jmi)3+S>%b'+%/FF (5C.cK]sbFP`eT`V'M3q.7keJ8lA5+P*D,$,c)cL8L[4VP"JVD,a+CT8L156fBs8X *0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrkVqb0V *0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrkVqb0V -*0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@Cs4I~> -%%EndBinary -grestore end % Image Trailer grestore -grestore % EPS grestore -[{nextImage} 1 dict begin /Metadata {photoshop_metadata_stream} def currentdict end /PUT pdfmark -[/NamespacePop pdfmark +*0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@Cs4I~>
%%EndBinary
grestore end % Image Trailer grestore
grestore % EPS grestore
[{nextImage} 1 dict begin /Metadata {photoshop_metadata_stream} def currentdict end /PUT pdfmark
[/NamespacePop pdfmark
\ No newline at end of file diff --git a/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.eps b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.eps index 680ee260892..1c5f93cff22 100644 --- a/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.eps +++ b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.eps @@ -1,541 +1,4 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%Title: brave-gnu-world-logo.eps -%%CreationDate: 09.10.2006 22:10 Uhr -%%BoundingBox: 0 0 342 387 -%%HiResBoundingBox: 0 0 342 387 -%%SuppressDotGainCompensation -%%EndComments -%%BeginProlog -%%EndProlog -%%BeginSetup -%%EndSetup -%ImageData: 342 387 8 3 0 1 3 "beginimage" -%BeginPhotoshop: 16252 -% 3842494D0425000000000010000000000000000000000000000000003842494D -% 03EA000000001DA63C3F786D6C2076657273696F6E3D22312E302220656E636F -% 64696E673D225554462D38223F3E0A3C21444F435459504520706C6973742050 -% 55424C494320222D2F2F4170706C6520436F6D70757465722F2F44544420504C -% 49535420312E302F2F454E222022687474703A2F2F7777772E6170706C652E63 -% 6F6D2F445444732F50726F70657274794C6973742D312E302E647464223E0A3C -% 706C6973742076657273696F6E3D22312E30223E0A3C646963743E0A093C6B65 -% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D48 -% 6F72697A6F6E74616C5265733C2F6B65793E0A093C646963743E0A09093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F72 -% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74 -% 696E676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E61 -% 70706C652E7072696E742E7469636B65742E6974656D41727261793C2F6B6579 -% 3E0A09093C61727261793E0A0909093C646963743E0A090909093C6B65793E63 -% 6F6D2E6170706C652E7072696E742E50616765466F726D61742E504D486F7269 -% 7A6F6E74616C5265733C2F6B65793E0A090909093C7265616C3E37323C2F7265 -% 616C3E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F6D -% 2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E0A -% 090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D31302D -% 30395432303A31303A30355A3C2F646174653E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B -% 65793E0A090909093C696E74656765723E303C2F696E74656765723E0A090909 -% 3C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B65 -% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D4F -% 7269656E746174696F6E3C2F6B65793E0A093C646963743E0A09093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F -% 6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E -% 676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E617070 -% 6C652E7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A -% 09093C61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E50616765466F726D61742E504D4F7269656E74 -% 6174696F6E3C2F6B65793E0A090909093C696E74656765723E313C2F696E7465 -% 6765723E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469 -% 636B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F -% 6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E -% 0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D3130 -% 2D30395432303A31303A30355A3C2F646174653E0A090909093C6B65793E636F -% 6D2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F -% 6B65793E0A090909093C696E74656765723E303C2F696E74656765723E0A0909 -% 093C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B -% 65793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D -% 5363616C696E673C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F6B6579 -% 3E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E676D61 -% 6E616765723C2F737472696E673E0A09093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A09093C -% 61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E50616765466F726D61742E504D5363616C696E673C2F -% 6B65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B6579 -% 3E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F -% 6B65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E74 -% 696E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B6579 -% 3E0A090909093C646174653E323030362D31302D30395432303A31303A30355A -% 3C2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E74 -% 656765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F -% 61727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E -% 7072696E742E50616765466F726D61742E504D566572746963616C5265733C2F -% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072 -% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909 -% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E50616765466F726D61742E504D566572746963616C5265733C2F6B65793E0A -% 090909093C7265616C3E37323C2F7265616C3E0A090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B65793E -% 0A090909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D -% 616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E617070 -% 6C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E0A0909 -% 09093C646174653E323030362D31302D30395432303A31303A30355A3C2F6461 -% 74653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465676572 -% 3E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61727261 -% 793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E7072696E -% 742E50616765466F726D61742E504D566572746963616C5363616C696E673C2F -% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072 -% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963 -% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909 -% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E50616765466F726D61742E504D566572746963616C5363616C696E673C2F6B -% 65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B -% 65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E7469 -% 6E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E -% 6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E -% 0A090909093C646174653E323030362D31302D30395432303A31303A30355A3C -% 2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465 -% 6765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61 -% 727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E70 -% 72696E742E7375625469636B65742E70617065725F696E666F5F7469636B6574 -% 3C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E -% 7072696E742E50616765466F726D61742E504D41646A75737465645061676552 -% 6563743C2F6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E61 -% 70706C652E7072696E742E7469636B65742E63726561746F723C2F6B65793E0A -% 0909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D616E -% 616765723C2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A090909 -% 3C61727261793E0A090909093C646963743E0A09090909093C6B65793E636F6D -% 2E6170706C652E7072696E742E50616765466F726D61742E504D41646A757374 -% 656450616765526563743C2F6B65793E0A09090909093C61727261793E0A0909 -% 090909093C7265616C3E302E303C2F7265616C3E0A0909090909093C7265616C -% 3E302E303C2F7265616C3E0A0909090909093C7265616C3E3738333C2F726561 -% 6C3E0A0909090909093C7265616C3E3535393C2F7265616C3E0A09090909093C -% 2F61727261793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E -% 742E7469636B65742E636C69656E743C2F6B65793E0A09090909093C73747269 -% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374 -% 72696E673E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 7469636B65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E -% 323030362D31302D30395432303A31303A30355A3C2F646174653E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E737461 -% 7465466C61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E -% 74656765723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09 -% 093C2F646963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E -% 50616765466F726D61742E504D41646A75737465645061706572526563743C2F -% 6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E6170706C652E -% 7072696E742E7469636B65742E63726561746F723C2F6B65793E0A0909093C73 -% 7472696E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C -% 2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E7469636B65742E6974656D41727261793C2F6B65793E0A0909093C61727261 -% 793E0A090909093C646963743E0A09090909093C6B65793E636F6D2E6170706C -% 652E7072696E742E50616765466F726D61742E504D41646A7573746564506170 -% 6572526563743C2F6B65793E0A09090909093C61727261793E0A090909090909 -% 3C7265616C3E2D31383C2F7265616C3E0A0909090909093C7265616C3E2D3138 -% 3C2F7265616C3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A09 -% 09090909093C7265616C3E3537373C2F7265616C3E0A09090909093C2F617272 -% 61793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469 -% 636B65742E636C69656E743C2F6B65793E0A09090909093C737472696E673E63 -% 6F6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E67 -% 3E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B -% 65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E32303036 -% 2D31302D30395432303A31303A30355A3C2F646174653E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E7374617465466C -% 61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E74656765 -% 723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09093C2F64 -% 6963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E50617065 -% 72496E666F2E504D50617065724E616D653C2F6B65793E0A09093C646963743E -% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E617070 -% 6C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A -% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E69 -% 74656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C64 -% 6963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E50 -% 61706572496E666F2E504D50617065724E616D653C2F6B65793E0A0909090909 -% 3C737472696E673E69736F2D61343C2F737472696E673E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C -% 2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C652E707269 -% 6E742E706D2E506F73745363726970743C2F737472696E673E0A09090909093C -% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461 -% 74653C2F6B65793E0A09090909093C646174653E323030332D30372D30315431 -% 373A34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E -% 0A09090909093C696E74656765723E313C2F696E74656765723E0A090909093C -% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C -% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D -% 556E61646A757374656450616765526563743C2F6B65793E0A09093C64696374 -% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170 -% 706C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E -% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 6974656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C -% 646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E -% 5061706572496E666F2E504D556E61646A757374656450616765526563743C2F -% 6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E302E -% 303C2F7265616C3E0A0909090909093C7265616C3E302E303C2F7265616C3E0A -% 0909090909093C7265616C3E3738333C2F7265616C3E0A0909090909093C7265 -% 616C3E3535393C2F7265616C3E0A09090909093C2F61727261793E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69 -% 656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C65 -% 2E7072696E74696E676D616E616765723C2F737472696E673E0A09090909093C -% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461 -% 74653C2F6B65793E0A09090909093C646174653E323030362D31302D30395432 -% 303A31303A30355A3C2F646174653E0A09090909093C6B65793E636F6D2E6170 -% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E -% 0A09090909093C696E74656765723E303C2F696E74656765723E0A090909093C -% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C -% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D -% 556E61646A75737465645061706572526563743C2F6B65793E0A09093C646963 -% 743E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65 -% 742E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E61 -% 70706C652E7072696E742E706D2E506F73745363726970743C2F737472696E67 -% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E6974656D41727261793C2F6B65793E0A0909093C61727261793E0A09090909 -% 3C646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E74 -% 2E5061706572496E666F2E504D556E61646A7573746564506170657252656374 -% 3C2F6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E -% 2D31383C2F7265616C3E0A0909090909093C7265616C3E2D31383C2F7265616C -% 3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A0909090909093C -% 7265616C3E3537373C2F7265616C3E0A09090909093C2F61727261793E0A0909 -% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E63 -% 6C69656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E617070 -% 6C652E7072696E74696E676D616E616765723C2F737472696E673E0A09090909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F64 -% 446174653C2F6B65793E0A09090909093C646174653E323030362D31302D3039 -% 5432303A31303A30355A3C2F646174653E0A09090909093C6B65793E636F6D2E -% 6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65 -% 793E0A09090909093C696E74656765723E303C2F696E74656765723E0A090909 -% 093C2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09 -% 093C6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E -% 7070642E504D50617065724E616D653C2F6B65793E0A09093C646963743E0A09 -% 09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6372 -% 6561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170706C65 -% 2E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A0909 -% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E697465 -% 6D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C646963 -% 743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E506170 -% 6572496E666F2E7070642E504D50617065724E616D653C2F6B65793E0A090909 -% 09093C737472696E673E41343C2F737472696E673E0A09090909093C6B65793E -% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B -% 65793E0A09090909093C737472696E673E636F6D2E6170706C652E7072696E74 -% 2E706D2E506F73745363726970743C2F737472696E673E0A09090909093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F6444617465 -% 3C2F6B65793E0A09090909093C646174653E323030332D30372D30315431373A -% 34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170706C -% 652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E0A09 -% 090909093C696E74656765723E313C2F696E74656765723E0A090909093C2F64 -% 6963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C6B65 -% 793E636F6D2E6170706C652E7072696E742E7469636B65742E41504956657273 -% 696F6E3C2F6B65793E0A09093C737472696E673E30302E32303C2F737472696E -% 673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574 -% 2E707269766174654C6F636B3C2F6B65793E0A09093C66616C73652F3E0A0909 -% 3C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74797065 -% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74 -% 2E5061706572496E666F5469636B65743C2F737472696E673E0A093C2F646963 -% 743E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E -% 41504956657273696F6E3C2F6B65793E0A093C737472696E673E30302E32303C -% 2F737472696E673E0A093C6B65793E636F6D2E6170706C652E7072696E742E74 -% 69636B65742E707269766174654C6F636B3C2F6B65793E0A093C66616C73652F -% 3E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74 -% 7970653C2F6B65793E0A093C737472696E673E636F6D2E6170706C652E707269 -% 6E742E50616765466F726D61745469636B65743C2F737472696E673E0A3C2F64 -% 6963743E0A3C2F706C6973743E0A3842494D03E9000000000078000300000048 -% 004800000000030F022FFFEEFFEE033802410367057B03E00002000000480048 -% 0000000002D802280001000000640000000100030303000000017FFF00010001 -% 0000000000000000000000006808001901900000000000200000000000000000 -% 0000000000000000000000000000000000003842494D03ED0000000000100048 -% 00000001000200480000000100023842494D042600000000000E000000000000 -% 000000003F8000003842494D040D0000000000040000001E3842494D04190000 -% 000000040000001E3842494D03F3000000000009000000000000000001003842 -% 494D040A00000000000100003842494D271000000000000A0001000000000000 -% 00023842494D03F5000000000048002F66660001006C66660006000000000001 -% 002F6666000100A1999A0006000000000001003200000001005A000000060000 -% 00000001003500000001002D000000060000000000013842494D03F800000000 -% 00700000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000 -% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFF -% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFFFFFFFFFF -% FFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800003842494D04080000000000100000 -% 00010000024000000240000000003842494D041E000000000004000000003842 -% 494D041A00000000035D00000006000000000000000000000183000001560000 -% 001400620072006100760065002D0067006E0075002D0077006F0072006C0064 -% 002D006C006F0067006F00000001000000000000000000000000000000000000 -% 0001000000000000000000000156000001830000000000000000000000000000 -% 0000010000000000000000000000000000000000000010000000010000000000 -% 006E756C6C0000000200000006626F756E64734F626A63000000010000000000 -% 00526374310000000400000000546F70206C6F6E6700000000000000004C6566 -% 746C6F6E67000000000000000042746F6D6C6F6E670000018300000000526768 -% 746C6F6E670000015600000006736C69636573566C4C73000000014F626A6300 -% 000001000000000005736C6963650000001200000007736C69636549446C6F6E -% 67000000000000000767726F757049446C6F6E6700000000000000066F726967 -% 696E656E756D0000000C45536C6963654F726967696E0000000D6175746F4765 -% 6E6572617465640000000054797065656E756D0000000A45536C696365547970 -% 6500000000496D672000000006626F756E64734F626A63000000010000000000 -% 00526374310000000400000000546F70206C6F6E6700000000000000004C6566 -% 746C6F6E67000000000000000042746F6D6C6F6E670000018300000000526768 -% 746C6F6E67000001560000000375726C54455854000000010000000000006E75 -% 6C6C54455854000000010000000000004D736765544558540000000100000000 -% 0006616C74546167544558540000000100000000000E63656C6C546578744973 -% 48544D4C626F6F6C010000000863656C6C546578745445585400000001000000 -% 000009686F727A416C69676E656E756D0000000F45536C696365486F727A416C -% 69676E0000000764656661756C740000000976657274416C69676E656E756D00 -% 00000F45536C69636556657274416C69676E0000000764656661756C74000000 -% 0B6267436F6C6F7254797065656E756D0000001145536C6963654247436F6C6F -% 7254797065000000004E6F6E6500000009746F704F75747365746C6F6E670000 -% 00000000000A6C6566744F75747365746C6F6E67000000000000000C626F7474 -% 6F6D4F75747365746C6F6E67000000000000000B72696768744F75747365746C -% 6F6E6700000000003842494D041100000000000101003842494D041400000000 -% 0004000000013842494D040C000000001A350000000100000071000000800000 -% 01540000AA0000001A1900180001FFD8FFE000104A4649460001020100480048 -% 0000FFED000C41646F62655F434D0002FFEE000E41646F626500648000000001 -% FFDB0084000C08080809080C09090C110B0A0B11150F0C0C0F15181313151313 -% 18110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C -% 0C0C0C0C0C010D0B0B0D0E0D100E0E10140E0E0E14140E0E0E0E14110C0C0C0C -% 0C11110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C -% 0C0C0C0C0C0CFFC00011080080007103012200021101031101FFDD00040008FF -% C4013F0000010501010101010100000000000000030001020405060708090A0B -% 0100010501010101010100000000000000010002030405060708090A0B100001 -% 0401030204020507060805030C33010002110304211231054151611322718132 -% 061491A1B14223241552C16233347282D14307259253F0E1F163733516A2B283 -% 264493546445C2A3743617D255E265F2B384C3D375E3F3462794A485B495C4D4 -% E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F637475767778797A7B7C7D7E7F7 -% 1100020201020404030405060707060535010002110321311204415161712213 -% 0532819114A1B14223C152D1F0332462E1728292435315637334F1250616A2B2 -% 83072635C2D2449354A317644555367465E2F2B384C3D375E3F34694A485B495 -% C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F62737475767778797A7B7C7 -% FFDA000C03010002110311003F00F5549249252962FD63FADFD0BEADD3BFA95F -% FA67006BC4AA1D7BC1DC039B4EE6EDAFF46FFD35BE9D3FF09BD61FD7EFAFE3A1 -% 8FD91D22323AEDE000000E18E1C3DB658DFA2FC87B7DD451FF00A1191FA2F4AA -% C9E1FA4FD5DCEEA998EEA7D58BFA8751CC74D3597026D70038716BABAF1F1D8D -% DB65FF00CC52CF469AB67A94D8929EA2CFF1C4CB2D8E9FD132322AEEEB2C6D6E -% E63F9BAD993F9BFF0008B5A9FF0018D45AD31D1F3C585E6BA9B1400F7EA1B5D7 -% BF258EB2C76DFA14D76A9F4FFA834B58D7E7E4D8D773F66C6706D4D91F47D6B2 -% BFB4DCE6EEFE77F56FFC2F5ADDE9BD07A474B71B30B19B5DCE043AF717597104 -% 8739AFCABDD6E4399B9BBB67AA9292F4DBFA86452EB73B1460B8B88AA8F505AF -% 0C1F45F7BEAFD0B2C7FF00A1A5F7FA7FF721FF00E0ADA4924A79BEBBD47EB974 -% 9B1F7E06053D6B05DAB59597539356AEDCCB1937332D9B7D3F4ACC7632DFF494 -% 7F855CB752FF0019FF005971C7A7FB2A8E9F748939A320340D665B65185FF07F -% E13FF3E2F4D49253E59D37FC66FD64B323D4C9AF03269827ECF8FEA31CE8F67E -% 8B21CFC8D9EFFF004B4FFDB5FCF57E83D13AFF004EEB743ADC37383EBDBEB63D -% A36DB5EE1B99BD9AEE63FF00C1DF53ACC7BBFC0DB62C4FAD5FE2EFA4F5B6D995 -% 84D6F4EEABF49B91588AEC7025F199437D96FA9BDDFA7FE91FF1BE9FA2BCFABB -% FAD740EBC303A89FB1754C40E38990C135DA1FFE1F7B87EB38D76CF753FF005B -% FD0E4D1FA24A7DB9258DF56FEB0B3ACE31173063E75207AF44CB48FCDC9C677F -% 84C5B7F33FD1FF00336FE916CA4A524924929FFFD0F555CC7D7DFAE15FD58E96 -% 3D269B3A96687D7835812039BB77DF618DBB28F52BFD1FF86B3F47F43D5B6AE9 -% D782F56EA87EB37D6BCAEAAE71B315961A30441814D42CB3D50DB7DCDD98F5DB -% 97657B7FA45DFE0D2527FAADD06CCA7D9D433C3F2AFB9C2581FF00A5BEEB9DBD -% 98E2CB377BED7B7D5CABBFC151FA7C8B3D15EBDD07A1D7D2F1F7DA18FCFB9A06 -% 4DCC076C0FA18F8FBE5D5E263FD0A6BFFAF59FA7B6D58DF527A355481956FBED -% A2B635B31FA3B2D636FBDBB3DCE6DCDAACAFF49F4FF58BAA5D724A52499CE6B1 -% A5CE21AD689738E8001DCAE03AFF00F8DAC1C6C87E07D5FC63D57246E67AF3B6 -% 86BFE830B3682FCA67A9FB9E8D567F81C9494FA024BCBFA6FF008CDFAD0EC963 -% 73B0F06DAF5DF4D0E7D76684336B2CB2DC9ABD5F51DF42C6319FF0D5AE9FA87F -% 8CAFAAB81D3E9CCB6EB1F66434BABC163272416BBD1B59754E2C663BAAB37FF3 -% F6D7EAFA567D9FD6494F5292E1F0FF00C6C746C8B62DC0CDA292EDA2ED8D7800 -% 7D27DB5D563AE6EC6EDDDE9577AEB7A6756E9BD5F1465F4DC8665504ED2F61E1 -% D01DE9D8C3EFAACDAE6FE8EC6FA8929B6B9FFAEDF5529FACFD1DD8A36579F4FE -% 930725E0FB1FA6E61733DEDAB21ADF4EDFFADDFE958FA2B5D024929F11FAB3D7 -% 3A85393582F38BD4F049AB6580B75691F68C7CE66D7BFECB7ECD96B367AACCA6 -% 7E8EAFB4D78FE9FB2F4ECFA3A8E15799402D65920B1D1B98F6935DD4D9B4B9BE -% A536B1F559B5CBC5FEB8B2AE9FFE303AA8A229AEC6B2D796E9B5D6B28B6DB7FE -% DE7BAE7AEFBEA266165F6E00115DB59B76811B2DC77370AFF5777B9D6DF5FD99 -% DFF07E8BFF00B694F66924924A7FFFD1F50CA6DCFC5B9943B6DCEADC2B7710E2 -% 0EC77F9CBE7BFAB4E0031BB8377BECA4171F687DA296D46C0DF76C7EC77FDB5F -% CB5F44AF2FFAEFF50F37133EFEBBD0697E5D19AE2EEA3D3DB2FB03DC4BDD918C -% DFA56B2C7B9DBAAFE728B1FF00A1FD0FF454A75FEABFD6CE958551C5CFB7ECF5 -% 585A5B976FB6BF576B6ABB1EFB3E856FFD17A8CB5DB29FF03FA3B29FD274EFFA -% CBF5718DDCFEAB86D6F89C8A80FF00AB5E29565B32D95ED7EE021B66FF007169 -% 8D1CF6EEAFD4B58DFF00AEBFFAEAE51F567A78A1D939748A98D87B59639AC3EF -% FE65B90E26AAE86BBE97BFFF0003FCF4A6F7D6CFAD79DF5D731DD27A3EFABA15 -% 0EFD259043B21CD3B9AFB07E653B87EAD8EFFF008EBFF58FB3E3D15B1BEAF328 -% A994359B8D861B5D675B0804BFE916D96FE6FAAC67E67E8BFC27A0AE74EB72F2 -% 5870FEAFE28BE9A5C2B665D601C7A3633D4B6DB03D94D3EADAEB376FBEFF00A1 -% BFF43916FF00379FD33A66664752756E75BD42C69DAEAEB0C7EE206DDD6DB697 -% 6DDBFF0069BF4791F63FE91FA0BD3A1094FE51F5DB4592CB18EA5B67A664E3D2 -% 2CFB3D8CA7710D2D6398C0EDAF6B296B3D3AD9EAEBFB9EA7F3BF43F3F3727168 -% 19363AD65673C1FD333783732086ED756E2EB9F6FF00C5FDA2F7B3FE1175DD4D -% B57D9CBF368C367516FA78ADC2A326FBC8C6AEC7E4E463F517D77D1535FEA3BF -% 43BFF9CBFF0056FD27ABE9ACCE9F89899F636ACAE9F878990197598CCFB5B28B -% 2B25D35E2E6E1DF75F915DBB3D4C87BEBC6FF47EAD767E92C481C7C5C249F31C -% 3308E324D47865A5D7CAE05D7D74EFAAF0FA5EE716163DA46D734B37D3B086FA -% 16FD0F568FE77DFF00A657BA5F54C8C1CCAF370EFF00B2DAD86B5ED1B9AF6C7F -% 35918ECFE9547FC67E9B7FF45FB3FD35B35F41EAB876BF763B6DC4B6B873F633 -% 63B74FF3B4B5D7D9F67D5ED6E5595FBFFE2972AFC5AF2736EFD9CE6E157EA0AA -% 9DC1EDAED786FB9BE859BBD2FA5F9BFF006CFEE38E23FA244BF050C9FBC0C5F5 -% 7E8DF5F3A4655219D5AEA7A5E6B44B9B6D81B4BC69FA5C5C9B7D3ADFBB77F30E -% FD62AFF8BFD3595BAD7F8D3FAA9D36A78C6C8FDA59634AE8C604B4B88259BB28 -% B7D06D7BBD8FF4DD75ACFF004162F2BBED78B0E1753A832CD4327F9A7C7B5BB2 -% C1FE05AE6FBF6BFF00EDB46C6C460692D0CADDA83B581B13F9D5B9A2FC8B9BFB -% 9E933E87F39E8A8D911B9DD47AC754BFAAF5100E6E7BD8E3535BA064B7ECF486 -% 39DFE15F551450CDFF00D169CBB6FF00E6BD45E93F526870CC65A5C48B3ED16B -% 09DB2F639D57BDAD23D477B9DEA596FEFDB5D5FF0072172BD2FA68BEE630576F -% A4F0EDC04BF22E062A7574D67DEF7E47D0BBF49ECC3FE7B2A9C15E97F573A3BB -% A6E33ACBDA1995901BEA3038BF635BBBD2A5D6E9EB58CF52CF52EDBFF07FCC55 -% 424A7612492494FF00FFD2F5549249253CF7D68FABFF0055F268B3AA755C3DD7 -% D23DB918FB9992E7BB6D345553F1DD5D9917BECF4E9C5AADF53F49FA35C2E4F5 -% 3661D76B2DA3EDF994EFAB23A78AFED5563B590F7613C3856CCACBF6FA99BD4E -% EFF26E33FF0047D330723D3FD1749F5D7A9F52CCCFAFA27437554E6B008CAB1E -% 5B6B5D68B2BB5BD3298FD264D78CCB7D5CD67F43AAEBAA65B55CFB3D3E7F230C -% B2ACACAEB9946F65120D3539C7098F7FE8EBFB7E5BEFAF2BABE53D9E97EADEAF -% F83FD62CF4922247488DF792C9DE801AEB6931EFCEFDA15D7D53229C8C363C33 -% 0BA4E23EB661E457B3754FF4EDF4FD7C2AABB7F9CA3A6B2AC8B7F49FCD7A2B5B -% AE67E453D0FECD5B9CEA3D573336EC4A982B67B4BAAC5CAFB3D8FF00D5AFB1FF -% 00A4BD9E933F57F432FF004795F67B70BA2E4E3E3DB9165384324BFF00441C1A -% DC72F1F9D6DAEA5F4E2D357FC17ABB2BAFF4752DAEA3D4DDD4307131FA18A2DA -% 301CE7E6E2E23DB5B18F1FD15DBEE7D3859B4D0EDEFBB17ED6CFD73ECB91FA5A -% EAB2A5265C5C38AA20D91F6B1717171441D28D7EFF00F8CF0993539C5FBEF15B -% 291B9D5D55B8811F9D75B90E63BFEB752C8BBAAE3ED69A45B63AA3BCBDE1AD0E -% 27F36CDBBB756BAAB3A062D9EA37A9D79B65D66EB68A2C6B6963DAD875B73BA8 -% 5566563E5D0DF519FCCBF7D2A3D32CC365CCAFA7537E63041B29C67B1986C7FD -% 16B9F75ADDEFFF0084B37AA5A0BB04D74F958408C7420923A7F37170065DD7D4 -% 6AB5CD14002D632A77B6BD7F9B0D656FDAD64FE8B73FF43FE0D74EDEAACBBAB5 -% 54F54A2D38F750D37676D0368693B72AC7E3B1CC7D6EDDEFB3D0A2CC6FE777AC -% BEBF9D8B84D76331953F2EDDC6E6E35E6DA9A09FFB55B9BB773377E62CFC4B3A -% BDD857DB5DB8B8C368A4DD6BCD6F7899FD0BED3E9B94B8BDCF9A029920244588 -% 81127691F9BC5ECBAAF4BE92FE934F45AB25D9349B5D6E0DD5D6CBDB734B0B3E -% CD4E5FAB7E3FDA5AD637D47B3D3C9A3D2F655E865FA8AC7D4AFA96DCCE995DB6 -% 7516BEB63BD3C8AEBAE6EAEC60FD2E1DAEB9F6D0C7635DF47F57BBD7A7D2B3F9 -% 9F4960F4AE946EC62D17FDAAEC96B6BCA2D756CABD6AC3DF8D55198CB2BF4DBE -% EF7DDB3F4967AAB4FEAA75FCBE97D7AAB7A99ADADEA8598D7FA43F3E3D3664DF -% EED8EF4727F41F68FDCBAFF53D5FD0FA73F0C88E23BF567040A1B7F2EEFA574D -% E8FD3FA6348C5ACFA8F1166458E365CFFF008DC8B4BED7FF005377A75FF83575 -% 249317A92492494FFFD3F5540CDCBA7070EFCDBE7D1C6ADF759024EDADA6C7ED -% 1FD56A3AC6FADED73FEAEE5D4D0E70BFD3A5ED67D2732DB6AA2D637FAF558F6A -% 205903BA09A04F67CF7033735DD49EFCCBC56FB817E4B2A8B5F73277E5BED716 -% 8AFECD7DFF00AB50C6DB5E27A18FFA0F52BF52EB639FD5FA4F53EA95BDF7D74B -% F56E363068BACAC47BF3B2AF6B7ECD4E43F6ECA7171BF9AAD6565E065E7B6CCB -% EA00B6ECB3AD4C97319B0B6BA316B69FA0DA59ECD8D51ADDD3FA45B4D74B9A5C -% 4137BDCD0D0D703F45EF8F7395D8E2BE136234D2965AE214657FB1EB3A2FD5AC -% 1CE65561C3765C1871B1CD74FF00C3653ACFFA152E94748E9B896558B9D9D4D3 -% EAB837170DA2AA019D19556C76EB2E589F54BEB1DB957B28B2C2719C4CFBAAAD -% BFD7DC18CB9FB7F777AA37D79D5B5ECCEE9B7FA5937D97752CDC50C7E2DAF7B9 -% E5CE65949BADFB1B58D63297E5329F43FED5FE9941CD66CB8F4034FD8BB1C61C -% 3C422724AF500FC81EA3EB5D5F57A707F6BE0D9D42DAF78C4631AE2D13E9FAA2 -% FDAEAB1BD37EDABD97FF00DB6B88C5E875E063D9FB2F3701F1FCF65F546BEA35 -% C0F7BAA6FAD761DBFF0007B28A3FEBCB7BA3F59C3C8C3C5E9E3A7D995D1AA7B6 -% 8A6F6D6E6B68630399F68BB3BDBD3F32B63BDB63E9BBD7FF0083CAB568F55C1E -% 974D03A87567557E257B431CCADD90F74FD06D7454C737FB7B2C55E1EDE404CE -% C3626090008F144F4F95F27C9AB273DD90CA328DD8EF2DFB4E5340AABB4D5BFD -% 1F4F1696EF7B6BF51DFA4BBFF0244FB062605943F20B03EC6EDADA185EE04705 -% ACB0EE5DD1FACBF563A858DB3A6DD461BAB7FA577DB5CEAB68076B2C6D78D5D9 -% 89E959FE96DC9ABFE13629E67D54C4A1B9199BEA3601B9D977B0D74B43BFD1DB -% 7FB6EFE47A2AD619E28815F9316486422AA8741178FC2A1D8C0E5E53DE5F6383 -% 7F492DB1D3F4767A7BB62D7CEFD99574AC2A32697DADBF7FDA5CDB87A8CAD8E1 -% 8FE8E39B9B5D76DF6FDA5CFB3D4B6AA6AABFE16C5BBD12AE9991655563E3E466 -% 565C19F6A35B4540BBDAEB3DCFF57D26CFEE2E33EB4F561922B6FA5B1A379C0A -% BE8FA55FABFE135B7ED19190CAAAFB4BFD6B3D6B595D389FA2AFF4ADE672C741 -% 0DEC52DC6271167524D01FCBFAAFAEFD55EA87ABFD5DC0CF738D96DB486DEF23 -% 693757FA0C9F60FF00BB15DAB55711FE2872326DFAAF757907F98CCB5958F06B -% 9B4E4B9BFF006EE45ABB75036D4924924A7FFFD4F5558DF5BDF6D7F56F3ADA49 -% 6BEA636D2F01C4B5B5BD965B6B3D27D36FA9556C7D95FA76D6FDEB6557EA1875 -% 67E064E0DD22ACBA5F45846876D8D756E8FECB920A7C9EEA6ACA38EE3906D662 -% D4CB5F75EDF4FDD73836D77A34BBDAFF006EC7596FBFD8B9FBDAD63ADBECA9E6 -% BAEE7578F5B8B29AC1ECED9EEB2DDCBB1A73AA181D3F1AFE97567754CE0FC67D -% 15B8627A2CC670AF2AA7DF93BB7E6E265BF7FA0CF57F55F52FBBF43E9AC7B7A1 -% 0A3AADE3A9EF7673CB9D8E5CC1B5CD0760FB3501D67B9D5ED77D3FE5AB98720E -% 2E1EDDDA99B1CB8788F5EDFCA2D06750EAD7DADA2BDAC635BEE0E240D7F77D3D -% BB96DF4EB5F80D6E665DB2FA3FA3B48343371FF876BFD472BB8FD1FA87A6D751 -% 8CD6318D906DF7DA5C78F6FB58CFEA6E552EFAB5998E0E6752C865CEB6093686 -% B4B5AEF6B5B4D13F9AAC4CE396FA9FDE916B43DC8EDE91FBB10A1D6BAE751C81 -% 5636539A376E7D8DCB018C6F01B4D3634AE9B05BD4322E6E4BBA8E7166303EF6 -% 369B19FCADDEDF771FB8B98FB25188064DD6597D6E3B69A890DAE7FE118D1B95 -% DBE9C9C8A98DC9CDAB171DBEEB035E71E96B40ED57D3B1CA0963801A533C72CC -% CB5B010F59C56E3D95E2F4ECEA9D80E712CC5EA356512D2E3B8D2D6D1558FEA1 -% 539CE73EBB2EFD255FCDDD7DDFA351E9FD2F1307A6754CDEA783FB50E316E4D3 -% 82C16E26234B22A3E85777E8D8E731CFB3F494FAD91FCDD14BEC57F13AEF4AC2 -% C607A6D2FCDA1CE0D2E61735D69F065D99B1EDABFA8A97D64CEEB228FB65B7D6 -% DC5DE0D75BDBB6BC279DD6578D663D363AAC8B7F47EAE1755B3FED47A95FEA17 -% 7A75AA73C631DCA313E619C480B908EA770373E6D6EA9D5B2998EEC379AFA763 -% 3C7E93030B7B5CFD1D355F6B36E5DBB98FD8FF0052EC7FFC28B98C8B85A1F940 -% 9194EC8D9556D7EFA68A7D36D755BE87B76BFF0048FF0041BBBF45E97A5E9A06 -% 4D97D871AEF42F73322C2DC7810EBDE0ECDB5D7B9EE6B77FE6318AE61747B71B -% 09FD43A8BEBC375B3914D17822D35CBB1DD9505BE937D5BACF4B11B77E93F476 -% 5D4D1E9FE99478ACCAE66FCD18C4F52753AD7689FEAC5F48FF0014B5399F56F2 -% 2D8229BF32C763B9D12EAD95D18BBFFCFC7B176CB17EA6F4B7F49FAAFD3B06D0 -% E6DCDA459736CFA4DB2E2ECABEB3FF001575CFAD6D2909B24B30D8292492412F -% FFD5F5549249253E7FF59FA2BA8EB36D54322BEA85B97845D5B1F43336B0E666 -% 36E6E8EAA9C8A1FF006AB1FF00E9BED19DFF0068D71BD3BAFF0059E997BF1ABC -% DBFA6D588F7369C41B6EDAE2FDB94CBB0DFBE86FA567A9B6B6FD9FD25ECDD57A -% 5E3F54C3762DC5D59FA555F512CB6A7C1636EA2D6FBEBB36BDECFE5D6FB2AB3F -% 45658BC83AF62752C0CDFB0756B6F168975D9CFDF683496B68B3305EDFD25DED -% AF1EADF657FAAFF84FD37F3CD98BA901AEC4FF00D12C538906E3609D3FDF76F1 -% FEB7579F9197D3B2E8CAEA179B3ED347D8E9DAD732B6EEDB9955C5DE87BB657E -% BD3EA63FBEAB6DF47F49BF732EDE91D3F16EEA8CC68CE636B376156F66EA6B2E -% 6B2FC9B6CC6AAFB594E356FF005AFB3659FF004D79C63F4FCDF4DBD5F019916B -% 6A314D992E360158DD53AEAE9A19FA6F4B73FDDBBD3FF825D1F40FACAFE9186F -% C3A319F9E64D6E360FB33741EE6B31EB190CBB9FF0FE9A9E10C9C3E202B8A028 -% 4883D24D8CFC8C7AADAF26CCA63A9B9C7D0C5E9CDF5CD8D9735B7DD9DBF73B7E -% DFCC585D7F21DD41CE755EAE3328FE75D75D1BDDE544D97B96F7526331B0307A -% 93BA3E253EAD8EA48B6B326297E4D57D7F637E135DBFECF7FDA7FC1FF33F6654 -% 3A7750AF39AD03A636BA32ED34E26563D37D4031822FCADB6372B0B231FD7FD5 -% BFE50FB431FF00E0D18E500F0CAEC782D30B97A2B6E2FA3CD60559AF2E79B5CF -% B1876B0D9EF0D1FF00042C236FF9AB77173B330996578D8B45965B5BA9393635 -% CE7FE91A6BB5B8D5D1B37BFD377F38F7A2751A5D4877D9F19F4575CD6FA4B4B9 -% FBBFD23DCCB2AA68639DFE95DEA2A1665518321FB32B318C00D4C6B9DB77F6B2 -% DDEFAA9FEDFF00EC3298CA128D57F6B1819233BBEBA7F55B7D331B2BA7E47DA9 -% D96F7E4DB532B69F49AEB98D67E869A6BB1AF7ECF53F3B66CF5BFC3AB9D23A4D -% 3D73EB0E1F4BC661FD8D82FF00B5E550C0CFB392DF73BD59AF6E6BB3733F47F4 -% 28C5A71BEDB8DD3EAB31FF004EB0DB89D4FAC64D54301C8B321C594E2E382CAB -% DA36DAEB2C77E652D3B2D7B99FABB3F9CAFF004F532CF5DFAAFF0056707EAEF4 -% FF00B3E3B41C8BA1F9778E6CB23B6EF7368ABE863D5F98CFF497D975D6D69803 -% 402BC1B10DBC3F96CECA492498BD4924924A7FFFD6F5549249252952EA9D2713 -% AAE31A32439AE1269BEB3B6DA9C46DF571EDFF0006FF00FC0EDAFF00437B2DA6 -% CB2B5752494F997D6BE8DF5C7A66396E2DCEBBA73A03ECC16BAAF4F46FDA6FBF -% A762EC7DBEB3C7ADEA3B272E967A6FFD16262DDE9ACCE85D7BA735CCF4AAC7AE -% F757635D9F5D0E70F5D83FA6578D3E93EF636CAAEBB1BF9A7BFF0098F4D7B02C -% AEABF55BEAF75871B3A8605375CE2D27200F4EEF6FD0FD6A8F4F23DB1FE95189 -% A24EBAF62B4C7EBFDEF57FD27C67AA5DD5E8C99CBB5F55F631AE75D90F739EE6 -% 387A83D3B7F3E9B367F38FB3DFB3F9AFF06A855D63A97DA19958F66497B8906C -% A8BE96991B36D6FA9DEDFF0037DEBD6F23FC58740BEFF546466D4D6886542E16 -% 359F4B5ADF975E4DEDDAE7EEFE79059FE2A3A00205D9BD4322A9F7D365CC0C7C -% F6B7D1A29B5DC7FA451FB601D18FDAA363F3D5F361F597AC0AAAFB5E6D8EAEB6 -% 6D6E27AA58CB23F372F65953EDC777F85DBFA7C9FF00C11747D1BEABE5F5CD8F -% C4C72709E5B65B9F91BA8C7B090DDDF67C46B6ACDC8AAA63FF0045FA4A2AC8FC -% FCCA7FC27A074AFA97F557A4383F03A6D2CB1AFF005196D80DD635C349AAFC93 -% 75B57FD6DEB6D3E371BA3BB208F7F579B95D03EAEE0F43C7D94FE9B25E22ECA7 -% B5A1EE03E8D4C6D6D65746355FE031286B28ABFE37D5B2CD5492497292492494 -% A49249253FFFD9003842494D0421000000000079000000010100000018004100 -% 64006F00620065002000500068006F0074006F00730068006F00700020004500 -% 6C0065006D0065006E007400730000001C00410064006F006200650020005000 -% 68006F0074006F00730068006F007000200045006C0065006D0065006E007400 -% 7300200032002E003000000001003842494D042200000000012E4D4D002A0000 -% 00080007011200030000000100010000011A00050000000100000062011B0005 -% 000000010000006A012800030000000100020000013100020000001D00000072 -% 01320002000000140000008F8769000400000001000000A4000000D000000048 -% 00000001000000480000000141646F62652050686F746F73686F7020456C656D -% 656E747320322E3000323030363A31303A30392032323A31303A313900000003 -% A001000300000001FFFF0000A00200040000000100000156A003000400000001 -% 000001830000000000000006010300030000000100060000011A000500000001 -% 0000011E011B0005000000010000012601280003000000010002000002010004 -% 000000010000012E020200040000000100000000000000000000004800000001 -% 00000048000000013842494D03FD0000000000070000000000000000 -%EndPhotoshop -%begin_xml_code -/pdfmark where {pop true} {false} ifelse -/currentdistillerparams where {pop currentdistillerparams -/CoreDistVersion get 5000 ge } {false} ifelse -and not {userdict /pdfmark /cleartomark load put} if -[/NamespacePush pdfmark -[/_objdef {photoshop_metadata_stream} /type /stream /OBJ pdfmark -/MetadataString 5038 string def % exact length of metadata -/TempString 100 string def -/ConsumeMetadata { -currentfile TempString readline pop pop -currentfile MetadataString readstring pop pop -} bind def -ConsumeMetadata -%begin_xml_packet: 5038 -<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> +%!PS-Adobe-3.0 EPSF-3.0
%%Title: brave-gnu-world-logo.eps
%%CreationDate: 09.10.2006 22:10 Uhr
%%BoundingBox: 0 0 342 387
%%HiResBoundingBox: 0 0 342 387
%%SuppressDotGainCompensation
%%EndComments
%%BeginProlog
%%EndProlog
%%BeginSetup
%%EndSetup
%ImageData: 342 387 8 3 0 1 3 "beginimage"
%BeginPhotoshop: 16252
% 3842494D0425000000000010000000000000000000000000000000003842494D
% 03EA000000001DA63C3F786D6C2076657273696F6E3D22312E302220656E636F
% 64696E673D225554462D38223F3E0A3C21444F435459504520706C6973742050
% 55424C494320222D2F2F4170706C6520436F6D70757465722F2F44544420504C
% 49535420312E302F2F454E222022687474703A2F2F7777772E6170706C652E63
% 6F6D2F445444732F50726F70657274794C6973742D312E302E647464223E0A3C
% 706C6973742076657273696F6E3D22312E30223E0A3C646963743E0A093C6B65
% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D48
% 6F72697A6F6E74616C5265733C2F6B65793E0A093C646963743E0A09093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F72
% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74
% 696E676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E61
% 70706C652E7072696E742E7469636B65742E6974656D41727261793C2F6B6579
% 3E0A09093C61727261793E0A0909093C646963743E0A090909093C6B65793E63
% 6F6D2E6170706C652E7072696E742E50616765466F726D61742E504D486F7269
% 7A6F6E74616C5265733C2F6B65793E0A090909093C7265616C3E37323C2F7265
% 616C3E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F6D
% 2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E0A
% 090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D31302D
% 30395432303A31303A30355A3C2F646174653E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B
% 65793E0A090909093C696E74656765723E303C2F696E74656765723E0A090909
% 3C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B65
% 793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D4F
% 7269656E746174696F6E3C2F6B65793E0A093C646963743E0A09093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F
% 6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E
% 676D616E616765723C2F737472696E673E0A09093C6B65793E636F6D2E617070
% 6C652E7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A
% 09093C61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E50616765466F726D61742E504D4F7269656E74
% 6174696F6E3C2F6B65793E0A090909093C696E74656765723E313C2F696E7465
% 6765723E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469
% 636B65742E636C69656E743C2F6B65793E0A090909093C737472696E673E636F
% 6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E673E
% 0A090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E6D6F64446174653C2F6B65793E0A090909093C646174653E323030362D3130
% 2D30395432303A31303A30355A3C2F646174653E0A090909093C6B65793E636F
% 6D2E6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F
% 6B65793E0A090909093C696E74656765723E303C2F696E74656765723E0A0909
% 093C2F646963743E0A09093C2F61727261793E0A093C2F646963743E0A093C6B
% 65793E636F6D2E6170706C652E7072696E742E50616765466F726D61742E504D
% 5363616C696E673C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E63726561746F723C2F6B6579
% 3E0A09093C737472696E673E636F6D2E6170706C652E7072696E74696E676D61
% 6E616765723C2F737472696E673E0A09093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A09093C
% 61727261793E0A0909093C646963743E0A090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E50616765466F726D61742E504D5363616C696E673C2F
% 6B65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B6579
% 3E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F
% 6B65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E74
% 696E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B6579
% 3E0A090909093C646174653E323030362D31302D30395432303A31303A30355A
% 3C2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E74
% 656765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F
% 61727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E
% 7072696E742E50616765466F726D61742E504D566572746963616C5265733C2F
% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072
% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909
% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E50616765466F726D61742E504D566572746963616C5265733C2F6B65793E0A
% 090909093C7265616C3E37323C2F7265616C3E0A090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B65793E
% 0A090909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D
% 616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E617070
% 6C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E0A0909
% 09093C646174653E323030362D31302D30395432303A31303A30355A3C2F6461
% 74653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465676572
% 3E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61727261
% 793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E7072696E
% 742E50616765466F726D61742E504D566572746963616C5363616C696E673C2F
% 6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E7072
% 696E742E7469636B65742E63726561746F723C2F6B65793E0A09093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E746963
% 6B65742E6974656D41727261793C2F6B65793E0A09093C61727261793E0A0909
% 093C646963743E0A090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E50616765466F726D61742E504D566572746963616C5363616C696E673C2F6B
% 65793E0A090909093C7265616C3E313C2F7265616C3E0A090909093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B
% 65793E0A090909093C737472696E673E636F6D2E6170706C652E7072696E7469
% 6E676D616E616765723C2F737472696E673E0A090909093C6B65793E636F6D2E
% 6170706C652E7072696E742E7469636B65742E6D6F64446174653C2F6B65793E
% 0A090909093C646174653E323030362D31302D30395432303A31303A30355A3C
% 2F646174653E0A090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 7469636B65742E7374617465466C61673C2F6B65793E0A090909093C696E7465
% 6765723E303C2F696E74656765723E0A0909093C2F646963743E0A09093C2F61
% 727261793E0A093C2F646963743E0A093C6B65793E636F6D2E6170706C652E70
% 72696E742E7375625469636B65742E70617065725F696E666F5F7469636B6574
% 3C2F6B65793E0A093C646963743E0A09093C6B65793E636F6D2E6170706C652E
% 7072696E742E50616765466F726D61742E504D41646A75737465645061676552
% 6563743C2F6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E61
% 70706C652E7072696E742E7469636B65742E63726561746F723C2F6B65793E0A
% 0909093C737472696E673E636F6D2E6170706C652E7072696E74696E676D616E
% 616765723C2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E6974656D41727261793C2F6B65793E0A090909
% 3C61727261793E0A090909093C646963743E0A09090909093C6B65793E636F6D
% 2E6170706C652E7072696E742E50616765466F726D61742E504D41646A757374
% 656450616765526563743C2F6B65793E0A09090909093C61727261793E0A0909
% 090909093C7265616C3E302E303C2F7265616C3E0A0909090909093C7265616C
% 3E302E303C2F7265616C3E0A0909090909093C7265616C3E3738333C2F726561
% 6C3E0A0909090909093C7265616C3E3535393C2F7265616C3E0A09090909093C
% 2F61727261793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E
% 742E7469636B65742E636C69656E743C2F6B65793E0A09090909093C73747269
% 6E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C2F7374
% 72696E673E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 7469636B65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E
% 323030362D31302D30395432303A31303A30355A3C2F646174653E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E737461
% 7465466C61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E
% 74656765723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09
% 093C2F646963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E
% 50616765466F726D61742E504D41646A75737465645061706572526563743C2F
% 6B65793E0A09093C646963743E0A0909093C6B65793E636F6D2E6170706C652E
% 7072696E742E7469636B65742E63726561746F723C2F6B65793E0A0909093C73
% 7472696E673E636F6D2E6170706C652E7072696E74696E676D616E616765723C
% 2F737472696E673E0A0909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E7469636B65742E6974656D41727261793C2F6B65793E0A0909093C61727261
% 793E0A090909093C646963743E0A09090909093C6B65793E636F6D2E6170706C
% 652E7072696E742E50616765466F726D61742E504D41646A7573746564506170
% 6572526563743C2F6B65793E0A09090909093C61727261793E0A090909090909
% 3C7265616C3E2D31383C2F7265616C3E0A0909090909093C7265616C3E2D3138
% 3C2F7265616C3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A09
% 09090909093C7265616C3E3537373C2F7265616C3E0A09090909093C2F617272
% 61793E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469
% 636B65742E636C69656E743C2F6B65793E0A09090909093C737472696E673E63
% 6F6D2E6170706C652E7072696E74696E676D616E616765723C2F737472696E67
% 3E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B
% 65742E6D6F64446174653C2F6B65793E0A09090909093C646174653E32303036
% 2D31302D30395432303A31303A30355A3C2F646174653E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E7374617465466C
% 61673C2F6B65793E0A09090909093C696E74656765723E303C2F696E74656765
% 723E0A090909093C2F646963743E0A0909093C2F61727261793E0A09093C2F64
% 6963743E0A09093C6B65793E636F6D2E6170706C652E7072696E742E50617065
% 72496E666F2E504D50617065724E616D653C2F6B65793E0A09093C646963743E
% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E617070
% 6C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A
% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E69
% 74656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C64
% 6963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E50
% 61706572496E666F2E504D50617065724E616D653C2F6B65793E0A0909090909
% 3C737472696E673E69736F2D61343C2F737472696E673E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C
% 2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C652E707269
% 6E742E706D2E506F73745363726970743C2F737472696E673E0A09090909093C
% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461
% 74653C2F6B65793E0A09090909093C646174653E323030332D30372D30315431
% 373A34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E
% 0A09090909093C696E74656765723E313C2F696E74656765723E0A090909093C
% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C
% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D
% 556E61646A757374656450616765526563743C2F6B65793E0A09093C64696374
% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170
% 706C652E7072696E742E706D2E506F73745363726970743C2F737472696E673E
% 0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 6974656D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C
% 646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E
% 5061706572496E666F2E504D556E61646A757374656450616765526563743C2F
% 6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E302E
% 303C2F7265616C3E0A0909090909093C7265616C3E302E303C2F7265616C3E0A
% 0909090909093C7265616C3E3738333C2F7265616C3E0A0909090909093C7265
% 616C3E3535393C2F7265616C3E0A09090909093C2F61727261793E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E636C69
% 656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E6170706C65
% 2E7072696E74696E676D616E616765723C2F737472696E673E0A09090909093C
% 6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F644461
% 74653C2F6B65793E0A09090909093C646174653E323030362D31302D30395432
% 303A31303A30355A3C2F646174653E0A09090909093C6B65793E636F6D2E6170
% 706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E
% 0A09090909093C696E74656765723E303C2F696E74656765723E0A090909093C
% 2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C
% 6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E504D
% 556E61646A75737465645061706572526563743C2F6B65793E0A09093C646963
% 743E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65
% 742E63726561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E61
% 70706C652E7072696E742E706D2E506F73745363726970743C2F737472696E67
% 3E0A0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E6974656D41727261793C2F6B65793E0A0909093C61727261793E0A09090909
% 3C646963743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E74
% 2E5061706572496E666F2E504D556E61646A7573746564506170657252656374
% 3C2F6B65793E0A09090909093C61727261793E0A0909090909093C7265616C3E
% 2D31383C2F7265616C3E0A0909090909093C7265616C3E2D31383C2F7265616C
% 3E0A0909090909093C7265616C3E3832343C2F7265616C3E0A0909090909093C
% 7265616C3E3537373C2F7265616C3E0A09090909093C2F61727261793E0A0909
% 0909093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E63
% 6C69656E743C2F6B65793E0A09090909093C737472696E673E636F6D2E617070
% 6C652E7072696E74696E676D616E616765723C2F737472696E673E0A09090909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F64
% 446174653C2F6B65793E0A09090909093C646174653E323030362D31302D3039
% 5432303A31303A30355A3C2F646174653E0A09090909093C6B65793E636F6D2E
% 6170706C652E7072696E742E7469636B65742E7374617465466C61673C2F6B65
% 793E0A09090909093C696E74656765723E303C2F696E74656765723E0A090909
% 093C2F646963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09
% 093C6B65793E636F6D2E6170706C652E7072696E742E5061706572496E666F2E
% 7070642E504D50617065724E616D653C2F6B65793E0A09093C646963743E0A09
% 09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E6372
% 6561746F723C2F6B65793E0A0909093C737472696E673E636F6D2E6170706C65
% 2E7072696E742E706D2E506F73745363726970743C2F737472696E673E0A0909
% 093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E697465
% 6D41727261793C2F6B65793E0A0909093C61727261793E0A090909093C646963
% 743E0A09090909093C6B65793E636F6D2E6170706C652E7072696E742E506170
% 6572496E666F2E7070642E504D50617065724E616D653C2F6B65793E0A090909
% 09093C737472696E673E41343C2F737472696E673E0A09090909093C6B65793E
% 636F6D2E6170706C652E7072696E742E7469636B65742E636C69656E743C2F6B
% 65793E0A09090909093C737472696E673E636F6D2E6170706C652E7072696E74
% 2E706D2E506F73745363726970743C2F737472696E673E0A09090909093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E6D6F6444617465
% 3C2F6B65793E0A09090909093C646174653E323030332D30372D30315431373A
% 34393A33365A3C2F646174653E0A09090909093C6B65793E636F6D2E6170706C
% 652E7072696E742E7469636B65742E7374617465466C61673C2F6B65793E0A09
% 090909093C696E74656765723E313C2F696E74656765723E0A090909093C2F64
% 6963743E0A0909093C2F61727261793E0A09093C2F646963743E0A09093C6B65
% 793E636F6D2E6170706C652E7072696E742E7469636B65742E41504956657273
% 696F6E3C2F6B65793E0A09093C737472696E673E30302E32303C2F737472696E
% 673E0A09093C6B65793E636F6D2E6170706C652E7072696E742E7469636B6574
% 2E707269766174654C6F636B3C2F6B65793E0A09093C66616C73652F3E0A0909
% 3C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74797065
% 3C2F6B65793E0A09093C737472696E673E636F6D2E6170706C652E7072696E74
% 2E5061706572496E666F5469636B65743C2F737472696E673E0A093C2F646963
% 743E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E
% 41504956657273696F6E3C2F6B65793E0A093C737472696E673E30302E32303C
% 2F737472696E673E0A093C6B65793E636F6D2E6170706C652E7072696E742E74
% 69636B65742E707269766174654C6F636B3C2F6B65793E0A093C66616C73652F
% 3E0A093C6B65793E636F6D2E6170706C652E7072696E742E7469636B65742E74
% 7970653C2F6B65793E0A093C737472696E673E636F6D2E6170706C652E707269
% 6E742E50616765466F726D61745469636B65743C2F737472696E673E0A3C2F64
% 6963743E0A3C2F706C6973743E0A3842494D03E9000000000078000300000048
% 004800000000030F022FFFEEFFEE033802410367057B03E00002000000480048
% 0000000002D802280001000000640000000100030303000000017FFF00010001
% 0000000000000000000000006808001901900000000000200000000000000000
% 0000000000000000000000000000000000003842494D03ED0000000000100048
% 00000001000200480000000100023842494D042600000000000E000000000000
% 000000003F8000003842494D040D0000000000040000001E3842494D04190000
% 000000040000001E3842494D03F3000000000009000000000000000001003842
% 494D040A00000000000100003842494D271000000000000A0001000000000000
% 00023842494D03F5000000000048002F66660001006C66660006000000000001
% 002F6666000100A1999A0006000000000001003200000001005A000000060000
% 00000001003500000001002D000000060000000000013842494D03F800000000
% 00700000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000
% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFF
% FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800000000FFFFFFFFFFFFFFFF
% FFFFFFFFFFFFFFFFFFFFFFFFFFFF03E800003842494D04080000000000100000
% 00010000024000000240000000003842494D041E000000000004000000003842
% 494D041A00000000035D00000006000000000000000000000183000001560000
% 001400620072006100760065002D0067006E0075002D0077006F0072006C0064
% 002D006C006F0067006F00000001000000000000000000000000000000000000
% 0001000000000000000000000156000001830000000000000000000000000000
% 0000010000000000000000000000000000000000000010000000010000000000
% 006E756C6C0000000200000006626F756E64734F626A63000000010000000000
% 00526374310000000400000000546F70206C6F6E6700000000000000004C6566
% 746C6F6E67000000000000000042746F6D6C6F6E670000018300000000526768
% 746C6F6E670000015600000006736C69636573566C4C73000000014F626A6300
% 000001000000000005736C6963650000001200000007736C69636549446C6F6E
% 67000000000000000767726F757049446C6F6E6700000000000000066F726967
% 696E656E756D0000000C45536C6963654F726967696E0000000D6175746F4765
% 6E6572617465640000000054797065656E756D0000000A45536C696365547970
% 6500000000496D672000000006626F756E64734F626A63000000010000000000
% 00526374310000000400000000546F70206C6F6E6700000000000000004C6566
% 746C6F6E67000000000000000042746F6D6C6F6E670000018300000000526768
% 746C6F6E67000001560000000375726C54455854000000010000000000006E75
% 6C6C54455854000000010000000000004D736765544558540000000100000000
% 0006616C74546167544558540000000100000000000E63656C6C546578744973
% 48544D4C626F6F6C010000000863656C6C546578745445585400000001000000
% 000009686F727A416C69676E656E756D0000000F45536C696365486F727A416C
% 69676E0000000764656661756C740000000976657274416C69676E656E756D00
% 00000F45536C69636556657274416C69676E0000000764656661756C74000000
% 0B6267436F6C6F7254797065656E756D0000001145536C6963654247436F6C6F
% 7254797065000000004E6F6E6500000009746F704F75747365746C6F6E670000
% 00000000000A6C6566744F75747365746C6F6E67000000000000000C626F7474
% 6F6D4F75747365746C6F6E67000000000000000B72696768744F75747365746C
% 6F6E6700000000003842494D041100000000000101003842494D041400000000
% 0004000000013842494D040C000000001A350000000100000071000000800000
% 01540000AA0000001A1900180001FFD8FFE000104A4649460001020100480048
% 0000FFED000C41646F62655F434D0002FFEE000E41646F626500648000000001
% FFDB0084000C08080809080C09090C110B0A0B11150F0C0C0F15181313151313
% 18110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C
% 0C0C0C0C0C010D0B0B0D0E0D100E0E10140E0E0E14140E0E0E0E14110C0C0C0C
% 0C11110C0C0C0C0C0C110C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C0C
% 0C0C0C0C0C0CFFC00011080080007103012200021101031101FFDD00040008FF
% C4013F0000010501010101010100000000000000030001020405060708090A0B
% 0100010501010101010100000000000000010002030405060708090A0B100001
% 0401030204020507060805030C33010002110304211231054151611322718132
% 061491A1B14223241552C16233347282D14307259253F0E1F163733516A2B283
% 264493546445C2A3743617D255E265F2B384C3D375E3F3462794A485B495C4D4
% E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F637475767778797A7B7C7D7E7F7
% 1100020201020404030405060707060535010002110321311204415161712213
% 0532819114A1B14223C152D1F0332462E1728292435315637334F1250616A2B2
% 83072635C2D2449354A317644555367465E2F2B384C3D375E3F34694A485B495
% C4D4E4F4A5B5C5D5E5F55666768696A6B6C6D6E6F62737475767778797A7B7C7
% FFDA000C03010002110311003F00F5549249252962FD63FADFD0BEADD3BFA95F
% FA67006BC4AA1D7BC1DC039B4EE6EDAFF46FFD35BE9D3FF09BD61FD7EFAFE3A1
% 8FD91D22323AEDE000000E18E1C3DB658DFA2FC87B7DD451FF00A1191FA2F4AA
% C9E1FA4FD5DCEEA998EEA7D58BFA8751CC74D3597026D70038716BABAF1F1D8D
% DB65FF00CC52CF469AB67A94D8929EA2CFF1C4CB2D8E9FD132322AEEEB2C6D6E
% E63F9BAD993F9BFF0008B5A9FF0018D45AD31D1F3C585E6BA9B1400F7EA1B5D7
% BF258EB2C76DFA14D76A9F4FFA834B58D7E7E4D8D773F66C6706D4D91F47D6B2
% BFB4DCE6EEFE77F56FFC2F5ADDE9BD07A474B71B30B19B5DCE043AF717597104
% 8739AFCABDD6E4399B9BBB67AA9292F4DBFA86452EB73B1460B8B88AA8F505AF
% 0C1F45F7BEAFD0B2C7FF00A1A5F7FA7FF721FF00E0ADA4924A79BEBBD47EB974
% 9B1F7E06053D6B05DAB59597539356AEDCCB1937332D9B7D3F4ACC7632DFF494
% 7F855CB752FF0019FF005971C7A7FB2A8E9F748939A320340D665B65185FF07F
% E13FF3E2F4D49253E59D37FC66FD64B323D4C9AF03269827ECF8FEA31CE8F67E
% 8B21CFC8D9EFFF004B4FFDB5FCF57E83D13AFF004EEB743ADC37383EBDBEB63D
% A36DB5EE1B99BD9AEE63FF00C1DF53ACC7BBFC0DB62C4FAD5FE2EFA4F5B6D995
% 84D6F4EEABF49B91588AEC7025F199437D96FA9BDDFA7FE91FF1BE9FA2BCFABB
% FAD740EBC303A89FB1754C40E38990C135DA1FFE1F7B87EB38D76CF753FF005B
% FD0E4D1FA24A7DB9258DF56FEB0B3ACE31173063E75207AF44CB48FCDC9C677F
% 84C5B7F33FD1FF00336FE916CA4A524924929FFFD0F555CC7D7DFAE15FD58E96
% 3D269B3A96687D7835812039BB77DF618DBB28F52BFD1FF86B3F47F43D5B6AE9
% D782F56EA87EB37D6BCAEAAE71B315961A30441814D42CB3D50DB7DCDD98F5DB
% 97657B7FA45DFE0D2527FAADD06CCA7D9D433C3F2AFB9C2581FF00A5BEEB9DBD
% 98E2CB377BED7B7D5CABBFC151FA7C8B3D15EBDD07A1D7D2F1F7DA18FCFB9A06
% 4DCC076C0FA18F8FBE5D5E263FD0A6BFFAF59FA7B6D58DF527A355481956FBED
% A2B635B31FA3B2D636FBDBB3DCE6DCDAACAFF49F4FF58BAA5D724A52499CE6B1
% A5CE21AD689738E8001DCAE03AFF00F8DAC1C6C87E07D5FC63D57246E67AF3B6
% 86BFE830B3682FCA67A9FB9E8D567F81C9494FA024BCBFA6FF008CDFAD0EC963
% 73B0F06DAF5DF4D0E7D76684336B2CB2DC9ABD5F51DF42C6319FF0D5AE9FA87F
% 8CAFAAB81D3E9CCB6EB1F66434BABC163272416BBD1B59754E2C663BAAB37FF3
% F6D7EAFA567D9FD6494F5292E1F0FF00C6C746C8B62DC0CDA292EDA2ED8D7800
% 7D27DB5D563AE6EC6EDDDE9577AEB7A6756E9BD5F1465F4DC8665504ED2F61E1
% D01DE9D8C3EFAACDAE6FE8EC6FA8929B6B9FFAEDF5529FACFD1DD8A36579F4FE
% 930725E0FB1FA6E61733DEDAB21ADF4EDFFADDFE958FA2B5D024929F11FAB3D7
% 3A85393582F38BD4F049AB6580B75691F68C7CE66D7BFECB7ECD96B367AACCA6
% 7E8EAFB4D78FE9FB2F4ECFA3A8E15799402D65920B1D1B98F6935DD4D9B4B9BE
% A536B1F559B5CBC5FEB8B2AE9FFE303AA8A229AEC6B2D796E9B5D6B28B6DB7FE
% DE7BAE7AEFBEA266165F6E00115DB59B76811B2DC77370AFF5777B9D6DF5FD99
% DFF07E8BFF00B694F66924924A7FFFD1F50CA6DCFC5B9943B6DCEADC2B7710E2
% 0EC77F9CBE7BFAB4E0031BB8377BECA4171F687DA296D46C0DF76C7EC77FDB5F
% CB5F44AF2FFAEFF50F37133EFEBBD0697E5D19AE2EEA3D3DB2FB03DC4BDD918C
% DFA56B2C7B9DBAAFE728B1FF00A1FD0FF454A75FEABFD6CE958551C5CFB7ECF5
% 585A5B976FB6BF576B6ABB1EFB3E856FFD17A8CB5DB29FF03FA3B29FD274EFFA
% CBF5718DDCFEAB86D6F89C8A80FF00AB5E29565B32D95ED7EE021B66FF007169
% 8D1CF6EEAFD4B58DFF00AEBFFAEAE51F567A78A1D939748A98D87B59639AC3EF
% FE65B90E26AAE86BBE97BFFF0003FCF4A6F7D6CFAD79DF5D731DD27A3EFABA15
% 0EFD259043B21CD3B9AFB07E653B87EAD8EFFF008EBFF58FB3E3D15B1BEAF328
% A994359B8D861B5D675B0804BFE916D96FE6FAAC67E67E8BFC27A0AE74EB72F2
% 5870FEAFE28BE9A5C2B665D601C7A3633D4B6DB03D94D3EADAEB376FBEFF00A1
% BFF43916FF00379FD33A66664752756E75BD42C69DAEAEB0C7EE206DDD6DB697
% 6DDBFF0069BF4791F63FE91FA0BD3A1094FE51F5DB4592CB18EA5B67A664E3D2
% 2CFB3D8CA7710D2D6398C0EDAF6B296B3D3AD9EAEBFB9EA7F3BF43F3F3727168
% 19363AD65673C1FD333783732086ED756E2EB9F6FF00C5FDA2F7B3FE1175DD4D
% B57D9CBF368C367516FA78ADC2A326FBC8C6AEC7E4E463F517D77D1535FEA3BF
% 43BFF9CBFF0056FD27ABE9ACCE9F89899F636ACAE9F878990197598CCFB5B28B
% 2B25D35E2E6E1DF75F915DBB3D4C87BEBC6FF47EAD767E92C481C7C5C249F31C
% 3308E324D47865A5D7CAE05D7D74EFAAF0FA5EE716163DA46D734B37D3B086FA
% 16FD0F568FE77DFF00A657BA5F54C8C1CCAF370EFF00B2DAD86B5ED1B9AF6C7F
% 35918ECFE9547FC67E9B7FF45FB3FD35B35F41EAB876BF763B6DC4B6B873F633
% 63B74FF3B4B5D7D9F67D5ED6E5595FBFFE2972AFC5AF2736EFD9CE6E157EA0AA
% 9DC1EDAED786FB9BE859BBD2FA5F9BFF006CFEE38E23FA244BF050C9FBC0C5F5
% 7E8DF5F3A4655219D5AEA7A5E6B44B9B6D81B4BC69FA5C5C9B7D3ADFBB77F30E
% FD62AFF8BFD3595BAD7F8D3FAA9D36A78C6C8FDA59634AE8C604B4B88259BB28
% B7D06D7BBD8FF4DD75ACFF004162F2BBED78B0E1753A832CD4327F9A7C7B5BB2
% C1FE05AE6FBF6BFF00EDB46C6C460692D0CADDA83B581B13F9D5B9A2FC8B9BFB
% 9E933E87F39E8A8D911B9DD47AC754BFAAF5100E6E7BD8E3535BA064B7ECF486
% 39DFE15F551450CDFF00D169CBB6FF00E6BD45E93F526870CC65A5C48B3ED16B
% 09DB2F639D57BDAD23D477B9DEA596FEFDB5D5FF0072172BD2FA68BEE630576F
% A4F0EDC04BF22E062A7574D67DEF7E47D0BBF49ECC3FE7B2A9C15E97F573A3BB
% A6E33ACBDA1995901BEA3038BF635BBBD2A5D6E9EB58CF52CF52EDBFF07FCC55
% 424A7612492494FF00FFD2F5549249253CF7D68FABFF0055F268B3AA755C3DD7
% D23DB918FB9992E7BB6D345553F1DD5D9917BECF4E9C5AADF53F49FA35C2E4F5
% 3661D76B2DA3EDF994EFAB23A78AFED5563B590F7613C3856CCACBF6FA99BD4E
% EFF26E33FF0047D330723D3FD1749F5D7A9F52CCCFAFA27437554E6B008CAB1E
% 5B6B5D68B2BB5BD3298FD264D78CCB7D5CD67F43AAEBAA65B55CFB3D3E7F230C
% B2ACACAEB9946F65120D3539C7098F7FE8EBFB7E5BEFAF2BABE53D9E97EADEAF
% F83FD62CF4922247488DF792C9DE801AEB6931EFCEFDA15D7D53229C8C363C33
% 0BA4E23EB661E457B3754FF4EDF4FD7C2AABB7F9CA3A6B2AC8B7F49FCD7A2B5B
% AE67E453D0FECD5B9CEA3D573336EC4A982B67B4BAAC5CAFB3D8FF00D5AFB1FF
% 00A4BD9E933F57F432FF004795F67B70BA2E4E3E3DB9165384324BFF00441C1A
% DC72F1F9D6DAEA5F4E2D357FC17ABB2BAFF4752DAEA3D4DDD4307131FA18A2DA
% 301CE7E6E2E23DB5B18F1FD15DBEE7D3859B4D0EDEFBB17ED6CFD73ECB91FA5A
% EAB2A5265C5C38AA20D91F6B1717171441D28D7EFF00F8CF0993539C5FBEF15B
% 291B9D5D55B8811F9D75B90E63BFEB752C8BBAAE3ED69A45B63AA3BCBDE1AD0E
% 27F36CDBBB756BAAB3A062D9EA37A9D79B65D66EB68A2C6B6963DAD875B73BA8
% 5566563E5D0DF519FCCBF7D2A3D32CC365CCAFA7537E63041B29C67B1986C7FD
% 16B9F75ADDEFFF0084B37AA5A0BB04D74F958408C7420923A7F37170065DD7D4
% 6AB5CD14002D632A77B6BD7F9B0D656FDAD64FE8B73FF43FE0D74EDEAACBBAB5
% 54F54A2D38F750D37676D0368693B72AC7E3B1CC7D6EDDEFB3D0A2CC6FE777AC
% BEBF9D8B84D76331953F2EDDC6E6E35E6DA9A09FFB55B9BB773377E62CFC4B3A
% BDD857DB5DB8B8C368A4DD6BCD6F7899FD0BED3E9B94B8BDCF9A029920244588
% 81127691F9BC5ECBAAF4BE92FE934F45AB25D9349B5D6E0DD5D6CBDB734B0B3E
% CD4E5FAB7E3FDA5AD637D47B3D3C9A3D2F655E865FA8AC7D4AFA96DCCE995DB6
% 7516BEB63BD3C8AEBAE6EAEC60FD2E1DAEB9F6D0C7635DF47F57BBD7A7D2B3F9
% 9F4960F4AE946EC62D17FDAAEC96B6BCA2D756CABD6AC3DF8D55198CB2BF4DBE
% EF7DDB3F4967AAB4FEAA75FCBE97D7AAB7A99ADADEA8598D7FA43F3E3D3664DF
% EED8EF4727F41F68FDCBAFF53D5FD0FA73F0C88E23BF567040A1B7F2EEFA574D
% E8FD3FA6348C5ACFA8F1166458E365CFFF008DC8B4BED7FF005377A75FF83575
% 249317A92492494FFFD3F5540CDCBA7070EFCDBE7D1C6ADF759024EDADA6C7ED
% 1FD56A3AC6FADED73FEAEE5D4D0E70BFD3A5ED67D2732DB6AA2D637FAF558F6A
% 205903BA09A04F67CF7033735DD49EFCCBC56FB817E4B2A8B5F73277E5BED716
% 8AFECD7DFF00AB50C6DB5E27A18FFA0F52BF52EB639FD5FA4F53EA95BDF7D74B
% F56E363068BACAC47BF3B2AF6B7ECD4E43F6ECA7171BF9AAD6565E065E7B6CCB
% EA00B6ECB3AD4C97319B0B6BA316B69FA0DA59ECD8D51ADDD3FA45B4D74B9A5C
% 4137BDCD0D0D703F45EF8F7395D8E2BE136234D2965AE214657FB1EB3A2FD5AC
% 1CE65561C3765C1871B1CD74FF00C3653ACFFA152E94748E9B896558B9D9D4D3
% EAB837170DA2AA019D19556C76EB2E589F54BEB1DB957B28B2C2719C4CFBAAAD
% BFD7DC18CB9FB7F777AA37D79D5B5ECCEE9B7FA5937D97752CDC50C7E2DAF7B9
% E5CE65949BADFB1B58D63297E5329F43FED5FE9941CD66CB8F4034FD8BB1C61C
% 3C422724AF500FC81EA3EB5D5F57A707F6BE0D9D42DAF78C4631AE2D13E9FAA2
% FDAEAB1BD37EDABD97FF00DB6B88C5E875E063D9FB2F3701F1FCF65F546BEA35
% C0F7BAA6FAD761DBFF0007B28A3FEBCB7BA3F59C3C8C3C5E9E3A7D995D1AA7B6
% 8A6F6D6E6B68630399F68BB3BDBD3F32B63BDB63E9BBD7FF0083CAB568F55C1E
% 974D03A87567557E257B431CCADD90F74FD06D7454C737FB7B2C55E1EDE404CE
% C3626090008F144F4F95F27C9AB273DD90CA328DD8EF2DFB4E5340AABB4D5BFD
% 1F4F1696EF7B6BF51DFA4BBFF0244FB062605943F20B03EC6EDADA185EE04705
% ACB0EE5DD1FACBF563A858DB3A6DD461BAB7FA577DB5CEAB68076B2C6D78D5D9
% 89E959FE96DC9ABFE13629E67D54C4A1B9199BEA3601B9D977B0D74B43BFD1DB
% 7FB6EFE47A2AD619E28815F9316486422AA8741178FC2A1D8C0E5E53DE5F6383
% 7F492DB1D3F4767A7BB62D7CEFD99574AC2A32697DADBF7FDA5CDB87A8CAD8E1
% 8FE8E39B9B5D76DF6FDA5CFB3D4B6AA6AABFE16C5BBD12AE9991655563E3E466
% 565C19F6A35B4540BBDAEB3DCFF57D26CFEE2E33EB4F561922B6FA5B1A379C0A
% BE8FA55FABFE135B7ED19190CAAAFB4BFD6B3D6B595D389FA2AFF4ADE672C741
% 0DEC52DC6271167524D01FCBFAAFAEFD55EA87ABFD5DC0CF738D96DB486DEF23
% 693757FA0C9F60FF00BB15DAB55711FE2872326DFAAF757907F98CCB5958F06B
% 9B4E4B9BFF006EE45ABB75036D4924924A7FFFD4F5558DF5BDF6D7F56F3ADA49
% 6BEA636D2F01C4B5B5BD965B6B3D27D36FA9556C7D95FA76D6FDEB6557EA1875
% 67E064E0DD22ACBA5F45846876D8D756E8FECB920A7C9EEA6ACA38EE3906D662
% D4CB5F75EDF4FDD73836D77A34BBDAFF006EC7596FBFD8B9FBDAD63ADBECA9E6
% BAEE7578F5B8B29AC1ECED9EEB2DDCBB1A73AA181D3F1AFE97567754CE0FC67D
% 15B8627A2CC670AF2AA7DF93BB7E6E265BF7FA0CF57F55F52FBBF43E9AC7B7A1
% 0A3AADE3A9EF7673CB9D8E5CC1B5CD0760FB3501D67B9D5ED77D3FE5AB98720E
% 2E1EDDDA99B1CB8788F5EDFCA2D06750EAD7DADA2BDAC635BEE0E240D7F77D3D
% BB96DF4EB5F80D6E665DB2FA3FA3B48343371FF876BFD472BB8FD1FA87A6D751
% 8CD6318D906DF7DA5C78F6FB58CFEA6E552EFAB5998E0E6752C865CEB6093686
% B4B5AEF6B5B4D13F9AAC4CE396FA9FDE916B43DC8EDE91FBB10A1D6BAE751C81
% 5636539A376E7D8DCB018C6F01B4D3634AE9B05BD4322E6E4BBA8E7166303EF6
% 369B19FCADDEDF771FB8B98FB25188064DD6597D6E3B69A890DAE7FE118D1B95
% DBE9C9C8A98DC9CDAB171DBEEB035E71E96B40ED57D3B1CA0963801A533C72CC
% CB5B010F59C56E3D95E2F4ECEA9D80E712CC5EA356512D2E3B8D2D6D1558FEA1
% 539CE73EBB2EFD255FCDDD7DDFA351E9FD2F1307A6754CDEA783FB50E316E4D3
% 82C16E26234B22A3E85777E8D8E731CFB3F494FAD91FCDD14BEC57F13AEF4AC2
% C607A6D2FCDA1CE0D2E61735D69F065D99B1EDABFA8A97D64CEEB228FB65B7D6
% DC5DE0D75BDBB6BC279DD6578D663D363AAC8B7F47EAE1755B3FED47A95FEA17
% 7A75AA73C631DCA313E619C480B908EA770373E6D6EA9D5B2998EEC379AFA763
% 3C7E93030B7B5CFD1D355F6B36E5DBB98FD8FF0052EC7FFC28B98C8B85A1F940
% 9194EC8D9556D7EFA68A7D36D755BE87B76BFF0048FF0041BBBF45E97A5E9A06
% 4D97D871AEF42F73322C2DC7810EBDE0ECDB5D7B9EE6B77FE6318AE61747B71B
% 09FD43A8BEBC375B3914D17822D35CBB1DD9505BE937D5BACF4B11B77E93F476
% 5D4D1E9FE99478ACCAE66FCD18C4F52753AD7689FEAC5F48FF0014B5399F56F2
% 2D8229BF32C763B9D12EAD95D18BBFFCFC7B176CB17EA6F4B7F49FAAFD3B06D0
% E6DCDA459736CFA4DB2E2ECABEB3FF001575CFAD6D2909B24B30D8292492412F
% FFD5F5549249253E7FF59FA2BA8EB36D54322BEA85B97845D5B1F43336B0E666
% 36E6E8EAA9C8A1FF006AB1FF00E9BED19DFF0068D71BD3BAFF0059E997BF1ABC
% DBFA6D588F7369C41B6EDAE2FDB94CBB0DFBE86FA567A9B6B6FD9FD25ECDD57A
% 5E3F54C3762DC5D59FA555F512CB6A7C1636EA2D6FBEBB36BDECFE5D6FB2AB3F
% 45658BC83AF62752C0CDFB0756B6F168975D9CFDF683496B68B3305EDFD25DED
% AF1EADF657FAAFF84FD37F3CD98BA901AEC4FF00D12C538906E3609D3FDF76F1
% FEB7579F9197D3B2E8CAEA179B3ED347D8E9DAD732B6EEDB9955C5DE87BB657E
% BD3EA63FBEAB6DF47F49BF732EDE91D3F16EEA8CC68CE636B376156F66EA6B2E
% 6B2FC9B6CC6AAFB594E356FF005AFB3659FF004D79C63F4FCDF4DBD5F019916B
% 6A314D992E360158DD53AEAE9A19FA6F4B73FDDBBD3FF825D1F40FACAFE9186F
% C3A319F9E64D6E360FB33741EE6B31EB190CBB9FF0FE9A9E10C9C3E202B8A028
% 4883D24D8CFC8C7AADAF26CCA63A9B9C7D0C5E9CDF5CD8D9735B7DD9DBF73B7E
% DFCC585D7F21DD41CE755EAE3328FE75D75D1BDDE544D97B96F7526331B0307A
% 93BA3E253EAD8EA48B6B326297E4D57D7F637E135DBFECF7FDA7FC1FF33F6654
% 3A7750AF39AD03A636BA32ED34E26563D37D4031822FCADB6372B0B231FD7FD5
% BFE50FB431FF00E0D18E500F0CAEC782D30B97A2B6E2FA3CD60559AF2E79B5CF
% B1876B0D9EF0D1FF00042C236FF9AB77173B330996578D8B45965B5BA9393635
% CE7FE91A6BB5B8D5D1B37BFD377F38F7A2751A5D4877D9F19F4575CD6FA4B4B9
% FBBFD23DCCB2AA68639DFE95DEA2A1665518321FB32B318C00D4C6B9DB77F6B2
% DDEFAA9FEDFF00EC3298CA128D57F6B1819233BBEBA7F55B7D331B2BA7E47DA9
% D96F7E4DB532B69F49AEB98D67E869A6BB1AF7ECF53F3B66CF5BFC3AB9D23A4D
% 3D73EB0E1F4BC661FD8D82FF00B5E550C0CFB392DF73BD59AF6E6BB3733F47F4
% 28C5A71BEDB8DD3EAB31FF004EB0DB89D4FAC64D54301C8B321C594E2E382CAB
% DA36DAEB2C77E652D3B2D7B99FABB3F9CAFF004F532CF5DFAAFF0056707EAEF4
% FF00B3E3B41C8BA1F9778E6CB23B6EF7368ABE863D5F98CFF497D975D6D69803
% 402BC1B10DBC3F96CECA492498BD4924924A7FFFD6F5549249252952EA9D2713
% AAE31A32439AE1269BEB3B6DA9C46DF571EDFF0006FF00FC0EDAFF00437B2DA6
% CB2B5752494F997D6BE8DF5C7A66396E2DCEBBA73A03ECC16BAAF4F46FDA6FBF
% A762EC7DBEB3C7ADEA3B272E967A6FFD16262DDE9ACCE85D7BA735CCF4AAC7AE
% F757635D9F5D0E70F5D83FA6578D3E93EF636CAAEBB1BF9A7BFF0098F4D7B02C
% AEABF55BEAF75871B3A8605375CE2D27200F4EEF6FD0FD6A8F4F23DB1FE95189
% A24EBAF62B4C7EBFDEF57FD27C67AA5DD5E8C99CBB5F55F631AE75D90F739EE6
% 387A83D3B7F3E9B367F38FB3DFB3F9AFF06A855D63A97DA19958F66497B8906C
% A8BE96991B36D6FA9DEDFF0037DEBD6F23FC58740BEFF546466D4D6886542E16
% 359F4B5ADF975E4DEDDAE7EEFE79059FE2A3A00205D9BD4322A9F7D365CC0C7C
% F6B7D1A29B5DC7FA451FB601D18FDAA363F3D5F361F597AC0AAAFB5E6D8EAEB6
% 6D6E27AA58CB23F372F65953EDC777F85DBFA7C9FF00C11747D1BEABE5F5CD8F
% C4C72709E5B65B9F91BA8C7B090DDDF67C46B6ACDC8AAA63FF0045FA4A2AC8FC
% FCCA7FC27A074AFA97F557A4383F03A6D2CB1AFF005196D80DD635C349AAFC93
% 75B57FD6DEB6D3E371BA3BB208F7F579B95D03EAEE0F43C7D94FE9B25E22ECA7
% B5A1EE03E8D4C6D6D65746355FE031286B28ABFE37D5B2CD5492497292492494
% A49249253FFFD9003842494D0421000000000079000000010100000018004100
% 64006F00620065002000500068006F0074006F00730068006F00700020004500
% 6C0065006D0065006E007400730000001C00410064006F006200650020005000
% 68006F0074006F00730068006F007000200045006C0065006D0065006E007400
% 7300200032002E003000000001003842494D042200000000012E4D4D002A0000
% 00080007011200030000000100010000011A00050000000100000062011B0005
% 000000010000006A012800030000000100020000013100020000001D00000072
% 01320002000000140000008F8769000400000001000000A4000000D000000048
% 00000001000000480000000141646F62652050686F746F73686F7020456C656D
% 656E747320322E3000323030363A31303A30392032323A31303A313900000003
% A001000300000001FFFF0000A00200040000000100000156A003000400000001
% 000001830000000000000006010300030000000100060000011A000500000001
% 0000011E011B0005000000010000012601280003000000010002000002010004
% 000000010000012E020200040000000100000000000000000000004800000001
% 00000048000000013842494D03FD0000000000070000000000000000
%EndPhotoshop
%begin_xml_code
/pdfmark where {pop true} {false} ifelse
/currentdistillerparams where {pop currentdistillerparams
/CoreDistVersion get 5000 ge } {false} ifelse
and not {userdict /pdfmark /cleartomark load put} if
[/NamespacePush pdfmark
[/_objdef {photoshop_metadata_stream} /type /stream /OBJ pdfmark
/MetadataString 5038 string def % exact length of metadata
/TempString 100 string def
/ConsumeMetadata {
currentfile TempString readline pop pop
currentfile MetadataString readstring pop pop
} bind def
ConsumeMetadata
%begin_xml_packet: 5038
<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?> <?adobe-xap-filters esc="CR"?> <x:xapmeta xmlns:x='adobe:ns:meta/' x:xaptk='XMP toolkit 2.8.2-33, framework 1.5'> <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'> @@ -598,77 +61,7 @@ ConsumeMetadata -<?xpacket end='w'?> -%end_xml_packet -[{photoshop_metadata_stream} 2 dict begin /Type /Metadata def /Subtype /XML def currentdict end /PUT pdfmark -[{photoshop_metadata_stream} MetadataString /PUT pdfmark -[/_objdef {nextImage} /NI pdfmark -%end_xml_code -gsave % EPS gsave -/hascolor -/deviceinfo where -{pop deviceinfo /Colors known -{deviceinfo /Colors get exec 1 gt} -{false} ifelse} -{/statusdict where -{pop statusdict /processcolors known -{statusdict /processcolors get exec 1 gt} -{false} ifelse} -{false} ifelse} -ifelse -def -40 dict begin -/_image systemdict /image get def -/_setgray systemdict /setgray get def -/_currentgray systemdict /currentgray get def -/_settransfer systemdict /settransfer get def -/_currenttransfer systemdict /currenttransfer get def -/blank 0 _currenttransfer exec -1 _currenttransfer exec eq def -/negative blank -{0 _currenttransfer exec 0.5 lt} -{0 _currenttransfer exec 1 _currenttransfer exec gt} -ifelse def -/inverted? negative def -/level2 systemdict /languagelevel known -{languagelevel 2 ge} {false} ifelse def -/level3 systemdict /languagelevel known -{languagelevel 3 ge} {false} ifelse def -level2 {/band 0 def} {/band 5 def} ifelse -gsave % Image Header gsave -/rows 387 def -/cols 342 def -342 387 scale -level2 { -/DeviceRGB -setcolorspace currentdict /PhotoshopDuotoneColorSpace undef currentdict /PhotoshopDuotoneAltColorSpace undef } if -/beginimage level2 -{/image load def} -{{pop .9 setgray 0 0 moveto 0 1 lineto -1 1 lineto 1 0 lineto fill 0 setgray -0 1 translate 1 cols div 1 rows div scale -/ratio {cols 400 div mul} def -/Helvetica findfont 15 ratio scalefont setfont -5 ratio -20 ratio moveto -(Mit JPEG komprimierte Bilder ben\232tigen PostScript Level 2) show -/x 128 string def -{currentfile x readline {} {pop exit} ifelse -(~>) search {pop pop pop exit} {pop} ifelse -} loop } def} -ifelse -12 dict begin -/ImageType 1 def -/Width cols def -/Height rows def -/ImageMatrix [cols 0 0 rows neg 0 rows] def -/BitsPerComponent 8 def -/Decode [0 1 0 1 0 1] def -/DataSource currentfile /ASCII85Decode filter -/DCTDecode filter def -currentdict end -%%BeginBinary: 21006 -beginimage -s4IA0!"_al8O`[\!W`9l!([(is6]js6"FnCAH67k!!!!"s4[O,!"obO%M0*b&.fQt +<?xpacket end='w'?>
%end_xml_packet
[{photoshop_metadata_stream} 2 dict begin /Type /Metadata def /Subtype /XML def currentdict end /PUT pdfmark
[{photoshop_metadata_stream} MetadataString /PUT pdfmark
[/_objdef {nextImage} /NI pdfmark
%end_xml_code
gsave % EPS gsave
/hascolor
/deviceinfo where
{pop deviceinfo /Colors known
{deviceinfo /Colors get exec 1 gt}
{false} ifelse}
{/statusdict where
{pop statusdict /processcolors known
{statusdict /processcolors get exec 1 gt}
{false} ifelse}
{false} ifelse}
ifelse
def
40 dict begin
/_image systemdict /image get def
/_setgray systemdict /setgray get def
/_currentgray systemdict /currentgray get def
/_settransfer systemdict /settransfer get def
/_currenttransfer systemdict /currenttransfer get def
/blank 0 _currenttransfer exec
1 _currenttransfer exec eq def
/negative blank
{0 _currenttransfer exec 0.5 lt}
{0 _currenttransfer exec 1 _currenttransfer exec gt}
ifelse def
/inverted? negative def
/level2 systemdict /languagelevel known
{languagelevel 2 ge} {false} ifelse def
/level3 systemdict /languagelevel known
{languagelevel 3 ge} {false} ifelse def
level2 {/band 0 def} {/band 5 def} ifelse
gsave % Image Header gsave
/rows 387 def
/cols 342 def
342 387 scale
level2 {
/DeviceRGB
setcolorspace currentdict /PhotoshopDuotoneColorSpace undef currentdict /PhotoshopDuotoneAltColorSpace undef } if
/beginimage level2
{/image load def}
{{pop .9 setgray 0 0 moveto 0 1 lineto
1 1 lineto 1 0 lineto fill 0 setgray
0 1 translate 1 cols div 1 rows div scale
/ratio {cols 400 div mul} def
/Helvetica findfont 15 ratio scalefont setfont
5 ratio -20 ratio moveto
(Mit JPEG komprimierte Bilder ben\232tigen PostScript Level 2) show
/x 128 string def
{currentfile x readline {} {pop exit} ifelse
(~>) search {pop pop pop exit} {pop} ifelse
} loop } def}
ifelse
12 dict begin
/ImageType 1 def
/Width cols def
/Height rows def
/ImageMatrix [cols 0 0 rows neg 0 rows] def
/BitsPerComponent 8 def
/Decode [0 1 0 1 0 1] def
/DataSource currentfile /ASCII85Decode filter
/DCTDecode filter def
currentdict end
%%BeginBinary: 21006
beginimage
s4IA0!"_al8O`[\!W`9l!([(is6]js6"FnCAH67k!!!!"s4[O,!"obO%M0*b&.fQt '+km!,8q:3)C$FB(Ddl(+qY4l$k*OQ&I]'V$k*OQ$k*OQ$k*OQ$k*OQ$k*OQ$k*OQ $iq%U',DH$)]';0'FkT_'GM#e%Ls0b$k*OQ$kX'[$k*OQ$kWmV$k*OQ$k*OQ$k*OQ $k*OQ$k*OQ$k*OQ$k30O!"fJ;K)o!T!?qLF&HMtG!WUsU"995;_uW(&!!*6(!<E3% @@ -985,9 +378,4 @@ P"KeukZoD(0?%Inm@+%To>d`-]BZ:eT4b-1P?\XtIBLQ#Ou?0'_*:r(p6IVgL7U\d e<718C=1KkIR!E`os"4GNSjHmdoMW',cN&P8P2Q"P#@H7,a>*f8L5f2P"A8;,a)&g 8L0OrP"?rK,a(_ps4?ZO?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrk Vqb0V*0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrk -Vqb0V*0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrkVuPE~> -%%EndBinary -grestore end % Image Trailer grestore -grestore % EPS grestore -[{nextImage} 1 dict begin /Metadata {photoshop_metadata_stream} def currentdict end /PUT pdfmark -[/NamespacePop pdfmark +Vqb0V*0NpB`?jKb,cBEq?6#,#IDmMkaX!e>;I1?+8q"Z)iQ3@CgeqGuP"L/A-/lrkVuPE~>
%%EndBinary
grestore end % Image Trailer grestore
grestore % EPS grestore
[{nextImage} 1 dict begin /Metadata {photoshop_metadata_stream} def currentdict end /PUT pdfmark
[/NamespacePop pdfmark
\ No newline at end of file diff --git a/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.xbb b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.xbb new file mode 100644 index 00000000000..8a4669dd911 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/images/brave-gnu-world-logo.xbb @@ -0,0 +1,6 @@ +%%Title: /Users/tantau/Library/texmf/tex/generic/pgf/doc/generic/pgf/images/brave-gnu-world-logo.jpg +%%Creator: extractbb 20130405 +%%BoundingBox: 0 0 342 387 +%%HiResBoundingBox: 0.000000 0.000000 342.000000 387.000000 +%%CreationDate: Tue Aug 27 10:50:29 2013 + diff --git a/Master/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex b/Master/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex index 116cde6d9bf..e687ae3c426 100644 --- a/Master/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex +++ b/Master/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex @@ -7,8 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -% $Header: /cvsroot/pgf/pgf/doc/generic/pgf/macros/pgfmanual-en-macros.tex,v 1.45 2009/11/15 13:13:24 ludewich Exp $ - +% $Header: /cvsroot/pgf/pgf/doc/generic/pgf/macros/pgfmanual-en-macros.tex,v 1.79 2013/12/20 15:22:35 tantau Exp $ \providecommand\href[2]{\texttt{#1}} @@ -18,20 +17,34 @@ \colorlet{examplefill}{yellow!80!black} \definecolor{graphicbackground}{rgb}{0.96,0.96,0.8} -\definecolor{codebackground}{rgb}{0.8,0.8,1} +\definecolor{codebackground}{rgb}{0.9,0.9,1} \newenvironment{pgfmanualentry}{\list{}{\leftmargin=2em\itemindent-\leftmargin\def\makelabel##1{\hss##1}}}{\endlist} -\newcommand\pgfmanualentryheadline[1]{\itemsep=0pt\parskip=0pt\item\strut{#1}\par\topsep=0pt} +\newcommand\pgfmanualentryheadline[1]{\itemsep=0pt\parskip=0pt{\raggedright\item\strut{#1}\par}\topsep=0pt} \newcommand\pgfmanualbody{\parskip3pt} +\let\origtexttt=\texttt +\def\texttt#1{{\def\textunderscore{\char`\_}\def\textbraceleft{\char`\{}\def\textbraceright{\char`\}}\origtexttt{#1}}} +\def\exclamationmarktext{!} +\def\atmarktext{@} + +{ + \catcode`\|=12 + \gdef\pgfmanualnormalbar{|} + \catcode`\|=13 + \AtBeginDocument{\gdef|{\ifmmode\pgfmanualnormalbar\else\expandafter\verb\expandafter|\fi}} +} + \newenvironment{pgflayout}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{\texttt{\string\pgfpagesuselayout\char`\{\declare{#1}\char`\}}\oarg{options}} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \texttt{\string\pgfpagesuselayout\char`\{\declare{#1}\char`\}}\oarg{options}% + } \index{#1@\protect\texttt{#1} layout}% \index{Page layouts!#1@\protect\texttt{#1}}% - \pgfmanualpdflabel{#1}{}% \pgfmanualbody } { @@ -48,12 +61,149 @@ \end{pgfmanualentry} } +\makeatletter + +\def\includeluadocumentationof#1{ + \directlua{require 'pgf.manual.DocumentParser'} + \directlua{pgf.manual.DocumentParser.include '#1'} +} + +\newenvironment{luageneric}[4]{ + \pgfmanualentry + \pgfmanualentryheadline{#4 \texttt{#1\declare{#2}}#3} + \index{#2@\protect\texttt{#2} (Lua)}% + \def\temp{#1} + \ifx\temp\pgfutil@empty\else + \index{#1@\protect\texttt{#1}!#2@\protect\texttt{#2} (Lua)}% + \fi + \pgfmanualbody +}{\endpgfmanualentry} + +\newenvironment{luatable}[3]{ + \medskip + \luageneric{#1}{#2}{ (declared in \texttt{#3})}{\textbf{Lua table}} +}{\endluageneric} + +\newenvironment{luafield}[1]{ + \pgfmanualentry + \pgfmanualentryheadline{Field \texttt{\declare{#1}}} + \pgfmanualbody +}{\endpgfmanualentry} + + +\newenvironment{lualibrary}[1]{ + \pgfmanualentry + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Graph Drawing Library} \texttt{\declare{#1}}% + } + \index{#1@\protect\texttt{#1} graph drawing library}% + \index{Libraries!#1@\protect\texttt{#1}}% + \index{Graph drawing libraries!#1@\protect\texttt{#1}}% + \vskip.25em + {\ttfamily\char`\\usegdlibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX\space and plain \TeX}\\ + {\ttfamily\char`\\usegdlibrary[\declare{#1}]\space \char`\%\space\space Con\TeX t}\smallskip\par + \pgfmanualbody +}{\endpgfmanualentry} + +\newenvironment{luadeclare}[4]{ + \pgfmanualentry + \def\manual@temp@default{#3}% + \def\manual@temp@initial{#4}% + \def\manual@temp@{#3#4}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + {\ttfamily/graph + drawing/\declare{#1}\opt{=}}\opt{#2}\hfill% + \ifx\manual@temp@\pgfutil@empty\else% + (\ifx\manual@temp@default\pgfutil@empty\else% + default {\ttfamily #3}\ifx\manual@temp@initial\pgfutil@empty\else, \fi% + \fi% + \ifx\manual@temp@initial\pgfutil@empty\else% + initially {\ttfamily #4}% + \fi% + )\fi% + }% + \index{#1@\protect\texttt{#1} key}% + \pgfmanualbody + \gdef\myname{#1}% +% \keyalias{tikz} +% \keyalias{tikz/graphs} +}{\endpgfmanualentry} + +\newenvironment{luadeclarestyle}[4]{ + \pgfmanualentry + \def\manual@temp@para{#2}% + \def\manual@temp@default{#3}% + \def\manual@temp@initial{#4}% + \def\manual@temp@{#3#4}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + {\ttfamily/graph drawing/\declare{#1}}\ifx\manual@temp@para\pgfutil@empty\else\opt{\texttt=}\opt{#2}\fi\hfill% + (style\ifx\manual@temp@\pgfutil@empty\else, % + \ifx\manual@temp@default\pgfutil@empty\else% + default {\ttfamily #3}\ifx\manual@temp@initial\pgfutil@empty\else, \fi% + \fi% + \ifx\manual@temp@initial\pgfutil@empty\else% + initially {\ttfamily #4}% + \fi% + \fi)% + }% + \index{#1@\protect\texttt{#1} key}% + \pgfmanualbody% + \gdef\myname{#1}% +% \keyalias{tikz} +% \keyalias{tikz/graphs} +}{\endpgfmanualentry} + +\newenvironment{luanamespace}[2]{ + \luageneric{#1}{#2}{}{\textbf{Lua namespace}} +}{\endluageneric} + +\newenvironment{luafiledescription}[1]{}{} + +\newenvironment{luacommand}[4]{ + \hypertarget{pgf/lua/#1}{\luageneric{#2}{#3}{\texttt{(#4)}}{\texttt{function}}} +}{\endluageneric} + +\newenvironment{luaparameters}{\par\emph{Parameters:}% + \parametercount=0\relax% + \let\item=\parameteritem% + \let\list=\restorelist% +} +{\par +} + +\newenvironment{luareturns}{\par\emph{Returns:}% + \parametercount=0\relax% + \let\item=\parameteritem% + \let\list=\restorelist% +} +{\par +} + +\newcount\parametercount + +\newenvironment{parameterdescription}{\unskip% + \parametercount=0\relax% + \let\item=\parameteritem% + \let\list=\restorelist% +} +{\par +} +\let\saveditemcommand=\item +\let\savedlistcommand=\list +\def\denselist#1#2{\savedlistcommand{#1}{#2}\parskip0pt\itemsep0pt} +\def\restorelist{\let\item=\saveditemcommand\denselist} +\def\parameteritem{\pgfutil@ifnextchar[\parameteritem@{}}%} +\def\parameteritem@[#1]{\advance\parametercount by1\relax\hskip0.15em plus 1em\emph{\the\parametercount.}\kern1ex\def\test{#1}\ifx\test\pgfutil@empty\else#1\kern.5em\fi} + \newenvironment{commandlist}[1]{% - \begin{pgfmanualentry} - \foreach \xx in {#1} {% - \expandafter\extractcommand\xx\@@ - }% - \pgfmanualbody + \begin{pgfmanualentry} + \foreach \xx in {#1} {% + \expandafter\extractcommand\xx\@@ + }% + \pgfmanualbody }{% \end{pgfmanualentry} }% @@ -64,20 +214,21 @@ % \begin{internallist}[register]{\pgf@xa,\pgf@xb} % \end{internallist} \newenvironment{internallist}[2][register]{% - \begin{pgfmanualentry} - \foreach \xx in {#2} {% - \expandafter\extractinternalcommand\expandafter{\xx}{#1}% - }% - \pgfmanualbody + \begin{pgfmanualentry} + \foreach \xx in {#2} {% + \expandafter\extractinternalcommand\expandafter{\xx}{#1}% + }% + \pgfmanualbody }{% \end{pgfmanualentry} }% \def\extractinternalcommand#1#2{% - \pgfmanualentryheadline{Internal #2 \declare{\texttt{\string#1}}}% \removeats{#1}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{\textbackslash\strippedat}{}% + Internal #2 \declare{\texttt{\string#1}}}% \index{Internals!\strippedat @\protect\myprintocmmand{\strippedat}}% \index{\strippedat @\protect\myprintocmmand{\strippedat}}% - \pgfmanualpdflabel{\textbackslash\strippedat}{}% } %% MW: START MATH MACROS @@ -89,120 +240,147 @@ \def\extractmathfunctionname@#1(#2)#3\tmpb{\def\mathname{#1}} \makeatother - + \newenvironment{math-function}[1]{ - \def\mathdefaultname{#1} - \extractmathfunctionname{#1} - \edef\mathurl{{math:\mathname}}\expandafter\hypertarget\expandafter{\mathurl}{}% - \begin{pgfmanualentry} - \pgfmanualentryheadline{\texttt{#1}}% - \index{\mathname @\protect\texttt{\mathname} math function}% - \index{Math functions!\mathname @\protect\texttt{\mathname}}% - \pgfmanualbody + \def\mathdefaultname{#1} + \extractmathfunctionname{#1} + \edef\mathurl{{math:\mathname}}\expandafter\hypertarget\expandafter{\mathurl}{}% + \begin{pgfmanualentry} + \pgfmanualentryheadline{\texttt{#1}}% + \index{\mathname @\protect\texttt{\mathname} math function}% + \index{Math functions!\mathname @\protect\texttt{\mathname}}% + \pgfmanualbody } { - \end{pgfmanualentry} + \end{pgfmanualentry} } \def\pgfmanualemptytext{} \def\pgfmanualvbarvbar{\char`\|\char`\|} \newenvironment{math-operator}[4][]{% - \begin{pgfmanualentry} - \csname math#3operator\endcsname{#2}{#4} - \def\mathtest{#4}% - \ifx\mathtest\pgfmanualemptytext% - \def\mathtype{(#3 operator)} - \else% - \def\mathtype{(#3 operator; uses the \texttt{#4} function)} - \fi% - \pgfmanualentryheadline{\mathexample\hfill\mathtype}% - \def\mathtest{#1}% - \ifx\mathtest\pgfmanualemptytext% - \index{#2@\protect\texttt{#2} #3 math operator}% - \index{Math operators!#2@\protect\texttt{#2}}% - \fi% - \pgfmanualbody + \begin{pgfmanualentry} + \csname math#3operator\endcsname{#2}{#4} + \def\mathtest{#4}% + \ifx\mathtest\pgfmanualemptytext% + \def\mathtype{(#3 operator)} + \else% + \def\mathtype{(#3 operator; uses the \texttt{#4} function)} + \fi% + \pgfmanualentryheadline{\mathexample\hfill\mathtype}% + \def\mathtest{#1}% + \ifx\mathtest\pgfmanualemptytext% + \index{#2@\protect\texttt{#2} #3 math operator}% + \index{Math operators!#2@\protect\texttt{#2}}% + \fi% + \pgfmanualbody } {\end{pgfmanualentry}} \newenvironment{math-operators}[5][]{% - \begin{pgfmanualentry} - \csname math#4operator\endcsname{#2}{#3} - \def\mathtest{#5}% - \ifx\mathtest\pgfmanualemptytext% - \def\mathtype{(#4 operators)} - \else% - \def\mathtype{(#4 operators; use the \texttt{#5} function)} - \fi% - \pgfmanualentryheadline{\mathexample\hfill\mathtype}% - \def\mathtest{#1}% - \ifx\mathtest\pgfmanualemptytext% - \index{#2#3@\protect\texttt{#2\protect\ #3} #4 math operators}% - \index{Math operators!#2#3@\protect\texttt{#2\protect\ #3}}% - \fi% - \pgfmanualbody + \begin{pgfmanualentry} + \csname math#4operator\endcsname{#2}{#3} + \def\mathtest{#5}% + \ifx\mathtest\pgfmanualemptytext% + \def\mathtype{(#4 operators)} + \else% + \def\mathtype{(#4 operators; use the \texttt{#5} function)} + \fi% + \pgfmanualentryheadline{\mathexample\hfill\mathtype}% + \def\mathtest{#1}% + \ifx\mathtest\pgfmanualemptytext% + \index{#2#3@\protect\texttt{#2\protect\ #3} #4 math operators}% + \index{Math operators!#2#3@\protect\texttt{#2\protect\ #3}}% + \fi% + \pgfmanualbody } {\end{pgfmanualentry}} \def\mathinfixoperator#1#2{% - \def\mathoperator{\texttt{#1}}% - \def\mathexample{\mvar{x}\space\texttt{#1}\space\mvar{y}}% + \def\mathoperator{\texttt{#1}}% + \def\mathexample{\mvar{x}\space\texttt{#1}\space\mvar{y}}% } \def\mathprefixoperator#1#2{% - \def\mathoperator{\texttt{#1}}% - \def\mathexample{\texttt{#1}\mvar{x}}% + \def\mathoperator{\texttt{#1}}% + \def\mathexample{\texttt{#1}\mvar{x}}% } \def\mathpostfixoperator#1#2{% - \def\mathoperator{\texttt{#1}} - \def\mathexample{\mvar{x}\texttt{#1}}% + \def\mathoperator{\texttt{#1}} + \def\mathexample{\mvar{x}\texttt{#1}}% } \def\mathgroupoperator#1#2{% - \def\mathoperator{\texttt{#1\ #2}}% - \def\mathexample{\texttt{#1}\mvar{x}\texttt{#2}}% + \def\mathoperator{\texttt{#1\ #2}}% + \def\mathexample{\texttt{#1}\mvar{x}\texttt{#2}}% } \expandafter\let\csname matharray accessoperator\endcsname=\mathgroupoperator \expandafter\let\csname matharrayoperator\endcsname=\mathgroupoperator \def\mathconditionaloperator#1#2{% - \def\mathoperator{#1\space#2} - \def\mathexample{\mvar{x}\ \texttt{#1}\ \mvar{y}\ {\texttt{#2}}\ \mvar{z}} + \def\mathoperator{#1\space#2} + \def\mathexample{\mvar{x}\ \texttt{#1}\ \mvar{y}\ {\texttt{#2}}\ \mvar{z}} } \newcommand\mathcommand[1][\mathdefaultname]{% - \expandafter\makemathcommand#1(\empty)\stop% - \expandafter\extractcommand\mathcommandname\@@% - \medskip + \expandafter\makemathcommand#1(\empty)\stop% + \expandafter\extractcommand\mathcommandname\@@% + \medskip } \makeatletter \def\makemathcommand#1(#2)#3\stop{% - \expandafter\def\expandafter\mathcommandname\expandafter{\csname pgfmath#1\endcsname}% - \ifx#2\empty% - \else% - \@makemathcommand#2,\stop, - \fi} + \expandafter\def\expandafter\mathcommandname\expandafter{\csname pgfmath#1\endcsname}% + \ifx#2\empty% + \else% + \@makemathcommand#2,\stop, + \fi} \def\@makemathcommand#1,{% - \ifx#1\stop% - \else% - \expandafter\def\expandafter\mathcommandname\expandafter{\mathcommandname{\ttfamily\char`\{#1\char`\}}}% - \expandafter\@makemathcommand% - \fi} + \ifx#1\stop% + \else% + \expandafter\def\expandafter\mathcommandname\expandafter{\mathcommandname{\ttfamily\char`\{#1\char`\}}}% + \expandafter\@makemathcommand% + \fi} \makeatother \def\calcname{\textsc{calc}} + +\newenvironment{math-keyword}[1]{ + \extracttikzmathkeyword#1@ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\texttt{\color{red}\mathname}\mathrest}% + \index{\mathname @\protect\texttt{\mathname} tikz math function}% + \index{TikZ math functions!\mathname @\protect\texttt{\mathname}}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\def\extracttikzmathkeyword#1#2@{% + \def\mathname{#1}% + \def\mathrest{#2}% +} + %% MW: END MATH MACROS \def\extractcommand#1#2\@@{% - \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}% \removeats{#1}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{\textbackslash\strippedat}{}% + \declare{\texttt{\string#1}}#2% + }% \index{\strippedat @\protect\myprintocmmand{\strippedat}} - \pgfmanualpdflabel{\textbackslash\strippedat}{}% +} + +\def\luaextractcommand#1#2\relax{% + \declare{\texttt{\string#1}}#2\par% +% \removeats{#1}% + % \index{\strippedat @\protect\myprintocmmand{\strippedat}} + % \pgfmanualpdflabel{\textbackslash\strippedat}{}% } @@ -217,12 +395,14 @@ } \def\extractenvironement#1#2\@@{% - \pgfmanualentryheadline{{\ttfamily\char`\\begin\char`\{\declare{#1}\char`\}}#2}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + {\ttfamily\char`\\begin\char`\{\declare{#1}\char`\}}#2% + }% \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}% \pgfmanualentryheadline{{\ttfamily\char`\\end\char`\{\declare{#1}\char`\}}}% \index{#1@\protect\texttt{#1} environment}% \index{Environments!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% } @@ -263,10 +443,26 @@ \newenvironment{shape}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Shape {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Shape} {\ttfamily\declare{#1}}% + }% \index{#1@\protect\texttt{#1} shape}% \index{Shapes!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{pictype}[2]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Pic type} {\ttfamily\declare{#1}#2}% + }% + \index{#1@\protect\texttt{#1} pic type}% + \index{Pic Types!#1@\protect\texttt{#1}} \pgfmanualbody } { @@ -275,10 +471,11 @@ \newenvironment{shading}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Shading {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Shading} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} shading}% \index{Shadings!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% \pgfmanualbody } { @@ -286,12 +483,58 @@ } +\newenvironment{graph}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Graph} {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} graph}% + \index{Graphs!#1@\protect\texttt{#1}} + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{gdalgorithm}[2]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Layout} {\ttfamily/graph drawing/\declare{#1}\opt{=}}\opt{\meta{options}}}% + \index{#1@\protect\texttt{#1} layout}% + \index{Layouts!#1@\protect\texttt{#1}}% + \foreach \algo in {#2} + {\edef\marshal{\noexpand\index{#2@\noexpand\protect\noexpand\texttt{#2} algorithm}}\marshal}% + \index{Graph drawing layouts!#1@\protect\texttt{#1}} + \item{\small alias {\ttfamily/tikz/#1}}\par + \item{\small alias {\ttfamily/tikz/graphs/#1}}\par + \item{\small Employs {\ttfamily algorithm=#2}}\par + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + \newenvironment{dataformat}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Format {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Format} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} format}% \index{Formats!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{stylesheet}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Style sheet} {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} style sheet}% + \index{Style sheets!#1@\protect\texttt{#1}} \pgfmanualbody } { @@ -309,10 +552,11 @@ \def\gobble#1{} \def\extracthandler#1#2\@nil{% - \pgfmanualentryheadline{Key handler \meta{key}{\ttfamily/\declare{#1}}#2}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{/handlers/#1}{}% + \textbf{Key handler} \meta{key}{\ttfamily/\declare{#1}}#2}% \index{\gobble#1@\protect\texttt{#1} handler}% \index{Key handlers!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{/handlers/#1}% } @@ -336,17 +580,17 @@ % \mchoice{choice1,choice2,choice3} \newcommand\mchoice[1]{% - \begingroup - \firstchoicetrue - \foreach \mchoice@ in {#1} {% - \iffirstchoice - \global\firstchoicefalse - \else - \choicesep - \fi - \choicearg{\mchoice@}% - }% - \endgroup + \begingroup + \firstchoicetrue + \foreach \mchoice@ in {#1} {% + \iffirstchoice + \global\firstchoicefalse + \else + \choicesep + \fi + \choicearg{\mchoice@}% + }% + \endgroup }% % \begin{key}{/path/x=value} @@ -369,39 +613,39 @@ % #1: the key % #2: a default path (or empty) \def\insertpathifneeded#1#2{% - \def\insertpathifneeded@@{#2}% - \ifx\insertpathifneeded@@\empty - \def\mykey{#1}% - \else - \insertpathifneeded@#2\@nil - \ifpgfutil@in@ - \def\mykey{#2/#1}% - \else - \def\mykey{#1}% - \fi - \fi + \def\insertpathifneeded@@{#2}% + \ifx\insertpathifneeded@@\empty + \def\mykey{#1}% + \else + \insertpathifneeded@#2\@nil + \ifpgfutil@in@ + \def\mykey{#2/#1}% + \else + \def\mykey{#1}% + \fi + \fi }% \def\insertpathifneeded@#1#2\@nil{% - \def\insertpathifneeded@@{#1}% - \def\insertpathifneeded@@@{/}% - \ifx\insertpathifneeded@@\insertpathifneeded@@@ - \pgfutil@in@true - \else - \pgfutil@in@false - \fi + \def\insertpathifneeded@@{#1}% + \def\insertpathifneeded@@@{/}% + \ifx\insertpathifneeded@@\insertpathifneeded@@@ + \pgfutil@in@true + \else + \pgfutil@in@false + \fi }% % \begin{keylist}[default path] -% {/path/option 1=value,/path/option 2=value2} +% {/path/option 1=value,/path/option 2=value2} % \end{keylist} \newenvironment{keylist}[2][]{% - \begin{pgfmanualentry} + \begin{pgfmanualentry} \def\extrakeytext{}% - \foreach \xx in {#2} {% - \expandafter\insertpathifneeded\expandafter{\xx}{#1}% - \expandafter\extractkey\mykey\@nil% - }% - \pgfmanualbody + \foreach \xx in {#2} {% + \expandafter\insertpathifneeded\expandafter{\xx}{#1}% + \expandafter\extractkey\mykey\@nil% + }% + \pgfmanualbody }{% \end{pgfmanualentry} }% @@ -415,12 +659,14 @@ \ifpgfutil@in@% \extractequalinitial#1\@nil% \else - \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill(\extrakeytext no value)}% + \pgfmanualentryheadline{% \def\mykey{#1}% \def\mypath{}% - \def\myname{}% + \gdef\myname{}% \firsttimetrue% + \pgfmanualdecomposecount=0\relax% \decompose#1/\nil% + {\ttfamily\declare{#1}}\hfill(\extrakeytext no value)}% \fi \fi% } @@ -434,31 +680,49 @@ \ifpgfutil@in@% \extractinitial{#1}#2\@nil% \else - \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}% + \pgfmanualentryheadline{% + \def\mykey{#1}% + \def\mypath{}% + \gdef\myname{}% + \firsttimetrue% + \pgfmanualdecomposecount=0\relax% + \decompose#1/\nil% + {\ttfamily\declare{#1}=}#2\hfill(\extrakeytext no default)}% \fi% \fi% - \def\mykey{#1}% - \def\mypath{}% - \def\myname{}% - \firsttimetrue% - \decompose#1/\nil% } \def\extractdefault#1#2(default #3)\@nil{% - \pgfmanualentryheadline{{\ttfamily\declare{#1}\opt{=}}\opt{#2}\hfill (\extrakeytext default {\ttfamily#3})}% + \pgfmanualentryheadline{% + \def\mykey{#1}% + \def\mypath{}% + \gdef\myname{}% + \firsttimetrue% + \pgfmanualdecomposecount=0\relax% + \decompose#1/\nil% + {\ttfamily\declare{#1}\opt{=}}\opt{#2}\hfill (\extrakeytext default {\ttfamily#3})}% } \def\extractinitial#1#2(initially #3)\@nil{% - \pgfmanualentryheadline{{\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}% + \pgfmanualentryheadline{% + \def\mykey{#1}% + \def\mypath{}% + \gdef\myname{}% + \firsttimetrue% + \pgfmanualdecomposecount=0\relax% + \decompose#1/\nil% + {\ttfamily\declare{#1}=}#2\hfill (\extrakeytext no default, initially {\ttfamily#3})}% } \def\extractequalinitial#1 (initially #2)\@nil{% - \pgfmanualentryheadline{{\ttfamily\declare{#1}}\hfill (\extrakeytext initially {\ttfamily#2})}% - \def\mykey{#1}% - \def\mypath{}% - \def\myname{}% - \firsttimetrue% - \decompose#1/\nil% + \pgfmanualentryheadline{% + \def\mykey{#1}% + \def\mypath{}% + \gdef\myname{}% + \firsttimetrue% + \pgfmanualdecomposecount=0\relax% + \decompose#1/\nil% + {\ttfamily\declare{#1}}\hfill (\extrakeytext initially {\ttfamily#2})}% } % Introduces a key alias '/#1/<name of current key>' @@ -468,6 +732,7 @@ } \newif\iffirsttime +\newcount\pgfmanualdecomposecount \makeatother @@ -477,26 +742,48 @@ % aha. \index{#1@\protect\texttt{#1} key}% \index{\mypath#1@\protect\texttt{#1}}% - \def\myname{#1}% + \gdef\myname{#1}% + \pgfmanualpdflabel{#1}{} \else% - \iffirsttime - \begingroup - % also make a pdf link anchor with full key path. - \def\hyperlabelwithoutslash##1/\nil{% - \pgfmanualpdflabel{##1}{}% - }% - \hyperlabelwithoutslash/#1/#2\nil - \endgroup - \def\mypath{#1@\protect\texttt{/#1/}!}% - \firsttimefalse - \else - \expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}% - \fi - \def\firsttime{} - \decompose/#2\nil% + \advance\pgfmanualdecomposecount by1\relax% + \ifnum\pgfmanualdecomposecount>2\relax% + \decomposetoodeep#1/#2\nil% + \else% + \iffirsttime% + \begingroup% + % also make a pdf link anchor with full key path. + \def\hyperlabelwithoutslash##1/\nil{% + \pgfmanualpdflabel{##1}{}% + }% + \hyperlabelwithoutslash/#1/#2\nil% + \endgroup% + \def\mypath{#1@\protect\texttt{/#1/}!}% + \firsttimefalse% + \else% + \expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}% + \fi% + \def\firsttime{}% + \decompose/#2\nil% + \fi% \fi% } +\def\decomposetoodeep#1/#2/\nil{% + % avoid too-deep nesting in index + \index{#1/#2@\protect\texttt{#1/#2} key}% + \index{\mypath#1/#2@\protect\texttt{#1/#2}}% + \decomposefindlast/#1/#2/\nil% +} +\makeatletter +\def\decomposefindlast/#1/#2\nil{% + \def\test{#2}% + \ifx\test\pgfutil@empty% + \gdef\myname{#1}% + \else% + \decomposefindlast/#2\nil% + \fi% +} +\makeatother \def\indexkey#1{% \def\mypath{}% \decompose#1/\nil% @@ -511,21 +798,23 @@ \end{pgfmanualentry} } \def\extractpredefinedmethod#1(#2)\@nil{% - \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt) \hfill(predefined for all classes)} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + Method \declare{\ttfamily #1}\texttt(#2\texttt) \hfill(predefined for all classes)} \index{#1@\protect\texttt{#1} method}% \index{Methods!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% } \newenvironment{ooclass}[1]{ \begin{pgfmanualentry} \def\currentclass{#1} - \pgfmanualentryheadline{Class \declare{\texttt{#1}}} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Class} \declare{\texttt{#1}}} \index{#1@\protect\texttt{#1} class}% \index{Class #1@Class \protect\texttt{#1}}% \index{Classes!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% \pgfmanualbody } { @@ -543,14 +832,17 @@ \def\extractmethod#1(#2)\@nil{% \def\test{#1} \ifx\test\currentclass - \pgfmanualentryheadline{Constructor \declare{\ttfamily #1}\texttt(#2\texttt)} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + Constructor \declare{\ttfamily #1}\texttt(#2\texttt)} \else - \pgfmanualentryheadline{Method \declare{\ttfamily #1}\texttt(#2\texttt)} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + Method \declare{\ttfamily #1}\texttt(#2\texttt)} \fi \index{#1@\protect\texttt{#1} method}% \index{Methods!#1@\protect\texttt{#1}} \index{Class \currentclass!#1@\protect\texttt{#1}}% - \pgfmanualpdflabel{#1}{}% } \newenvironment{attribute}[1]{ @@ -564,24 +856,28 @@ \def\extractattribute#1=#2;\@nil{% \def\test{#2}% \ifx\test\@empty - \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially empty)} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + Private attribute \declare{\ttfamily #1} \hfill (initially empty)} \else - \pgfmanualentryheadline{Private attribute \declare{\ttfamily #1} \hfill (initially {\ttfamily #2})} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + Private attribute \declare{\ttfamily #1} \hfill (initially {\ttfamily #2})} \fi \index{#1@\protect\texttt{#1} attribute}% \index{Attributes!#1@\protect\texttt{#1}} \index{Class \currentclass!#1@\protect\texttt{#1}}% - \pgfmanualpdflabel{#1}{}% } \newenvironment{predefinednode}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Predefined node {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Predefined node} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} node}% \index{Predefined node!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% \pgfmanualbody } { @@ -590,10 +886,11 @@ \newenvironment{coordinatesystem}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Coordinate system {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{Coordinate system} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} coordinate system}% \index{Coordinate systems!#1@\protect\texttt{#1}} - \pgfmanualpdflabel{#1}{}% \pgfmanualbody } { @@ -602,7 +899,7 @@ \newenvironment{snake}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Snake {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{\textbf{Snake} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} snake}% \index{Snakes!#1@\protect\texttt{#1}} \pgfmanualbody @@ -613,7 +910,7 @@ \newenvironment{decoration}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{Decoration {\ttfamily\declare{#1}}}% + \pgfmanualentryheadline{\textbf{Decoration} {\ttfamily\declare{#1}}}% \index{#1@\protect\texttt{#1} decoration}% \index{Decorations!#1@\protect\texttt{#1}} \pgfmanualbody @@ -627,14 +924,17 @@ \makeatletter \newenvironment{pathoperation}[3][]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\path}\ + \def\pgfmanualtest{#1}% + \pgfmanualentryheadline{% + \ifx\pgfmanualtest\@empty% + \pgfmanualpdflabel{#2}{}% + \fi% + \textcolor{gray}{{\ttfamily\char`\\path}\ \ \dots} \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}% - \def\pgfmanualtest{#1}% \ifx\pgfmanualtest\@empty% \index{#2@\protect\texttt{#2} path operation}% \index{Path operations!#2@\protect\texttt{#2}}% - \pgfmanualpdflabel{#2}{}% \fi% \pgfmanualbody } @@ -643,14 +943,17 @@ } \newenvironment{datavisualizationoperation}[3][]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\datavisualization}\ + \def\pgfmanualtest{#1}% + \pgfmanualentryheadline{% + \ifx\pgfmanualtest\@empty% + \pgfmanualpdflabel{#2}{}% + \fi% + \textcolor{gray}{{\ttfamily\char`\\datavisualization}\ \ \dots} \declare{\texttt{#2}}#3\ \textcolor{gray}{\dots\texttt{;}}}% - \def\pgfmanualtest{#1}% \ifx\pgfmanualtest\@empty% \index{#2@\protect\texttt{#2} (data visualization)}% \index{Data visualization!#2@\protect\texttt{#2}}% - \pgfmanualpdflabel{#2}{}% \fi% \pgfmanualbody } @@ -659,19 +962,14 @@ } \makeatother -\def\extractcommand#1#2\@@{% - \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}% - \removeats{#1}% - \index{\strippedat @\protect\myprintocmmand{\strippedat}} - \pgfmanualpdflabel{\textbackslash\strippedat}{}% -} - \def\doublebs{\texttt{\char`\\\char`\\}} \newenvironment{package}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\char`\\usepackage\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX}} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + {\ttfamily\char`\\usepackage\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX}} \index{#1@\protect\texttt{#1} package}% \index{Packages and files!#1@\protect\texttt{#1}}% \pgfmanualentryheadline{{\ttfamily\char`\\input \declare{#1}.tex\space\space\space \char`\%\space\space plain \TeX}} @@ -685,13 +983,14 @@ \newenvironment{pgfmodule}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\char`\\usepgfmodule\char`\{\declare{#1}\char`\}\space\space\space + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + {\ttfamily\char`\\usepgfmodule\char`\{\declare{#1}\char`\}\space\space\space \char`\%\space\space \LaTeX\space and plain \TeX\space and pure pgf}} \index{#1@\protect\texttt{#1} module}% \index{Modules!#1@\protect\texttt{#1}}% \pgfmanualentryheadline{{\ttfamily\char`\\usepgfmodule[\declare{#1}]\space\space \char`\%\space\space Con\TeX t\space and pure pgf}} \pgfmanualbody - \pgfmanualpdflabel{#1}{}% } { \end{pgfmanualentry} @@ -699,17 +998,37 @@ \newenvironment{pgflibrary}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\char`\\usepgflibrary\char`\{\declare{#1}\char`\}\space\space\space - \char`\%\space\space \LaTeX\space and plain \TeX\space and pure pgf}} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{\tikzname\ Library} \texttt{\declare{#1}}} \index{#1@\protect\texttt{#1} library}% \index{Libraries!#1@\protect\texttt{#1}}% - \pgfmanualentryheadline{{\ttfamily\char`\\usepgflibrary[\declare{#1}]\space\space \char`\%\space\space Con\TeX t\space and pure pgf}} - \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space - \char`\%\space\space \LaTeX\space and plain \TeX\space when using \tikzname}} - \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space - \char`\%\space\space Con\TeX t\space when using \tikzname}} + \vskip.25em% + {{\ttfamily\char`\\usepgflibrary\char`\{\declare{#1}\char`\}\space\space\space + \char`\%\space\space \LaTeX\space and plain \TeX\space and pure pgf}}\\ + {{\ttfamily\char`\\usepgflibrary[\declare{#1}]\space\space \char`\%\space\space Con\TeX t\space and pure pgf}}\\ + {{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space + \char`\%\space\space \LaTeX\space and plain \TeX\space when using \tikzname}}\\ + {{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space + \char`\%\space\space Con\TeX t\space when using \tikzname}}\\[.5em] + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{purepgflibrary}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{{\small PGF} Library} \texttt{\declare{#1}}} + \index{#1@\protect\texttt{#1} library}% + \index{Libraries!#1@\protect\texttt{#1}}% + \vskip.25em% + {{\ttfamily\char`\\usepgflibrary\char`\{\declare{#1}\char`\}\space\space\space + \char`\%\space\space \LaTeX\space and plain \TeX}}\\ + {{\ttfamily\char`\\usepgflibrary[\declare{#1}]\space\space \char`\%\space\space Con\TeX t}}\\[.5em] \pgfmanualbody - \pgfmanualpdflabel{#1}{}% } { \end{pgfmanualentry} @@ -717,12 +1036,15 @@ \newenvironment{tikzlibrary}[1]{ \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX\space and plain \TeX}} + \pgfmanualentryheadline{% + \pgfmanualpdflabel{#1}{}% + \textbf{\tikzname\ Library} \texttt{\declare{#1}}} \index{#1@\protect\texttt{#1} library}% \index{Libraries!#1@\protect\texttt{#1}}% - \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space \char`\%\space\space Con\TeX t}} + \vskip.25em% + {{\ttfamily\char`\\usetikzlibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX\space and plain \TeX}}\\ + {{\ttfamily\char`\\usetikzlibrary[\declare{#1}]\space \char`\%\space\space Con\TeX t}}\\[.5em] \pgfmanualbody - \pgfmanualpdflabel{#1}{}% } { \end{pgfmanualentry} @@ -858,89 +1180,225 @@ \def\noindexing{\let\index=\@gobble} +\newenvironment{arrowtipsimple}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\textbf{Arrow Tip Kind} {\ttfamily#1}} + \index{#1@\protect\texttt{#1} arrow tip}% + \index{Arrow tips!#1@\protect\texttt{#1}}% + \def\currentarrowtype{#1} + \pgfmanualbody} +{ + \end{pgfmanualentry} +} -\newcommand\symarrow[1]{ +\newenvironment{arrowtip}[4]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\textbf{Arrow Tip Kind} {\ttfamily#1}} + \index{#1@\protect\texttt{#1} arrow tip}% + \index{Arrow tips!#1@\protect\texttt{#1}}% + \pgfmanualbody + \def\currentarrowtype{#1} + \begin{minipage}[t]{10.25cm} + #2 + \end{minipage}\hskip5mm\begin{minipage}[t]{4.75cm} + \leavevmode\vskip-2em + \tikz{ + \draw [black!50,line width=5mm,-{#1[#3,color=black]}] (-4,0) -- (0,0); + \foreach \action in {#4} + { \expandafter\processaction\action\relax } + } + \end{minipage}\par\smallskip + } +{ + \end{pgfmanualentry} +} + +\newenvironment{arrowcap}[5]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{\textbf{Arrow Tip Kind} {\ttfamily#1}} + \index{#1@\protect\texttt{#1} arrow tip}% + \index{Arrow tips!#1@\protect\texttt{#1}}% + \pgfmanualbody + \def\currentarrowtype{#1} + \begin{minipage}[t]{10.25cm} + #2 + \end{minipage}\hskip5mm\begin{minipage}[t]{4.75cm} + \leavevmode\vskip-2em + \tikz{ + \path [tips, line width=10mm,-{#1[#3,color=black]}] (-4,0) -- (0,0); + \draw [line width=10mm,black!50] (-3,0) -- (#5,0); + \foreach \action in {#4} + { \expandafter\processaction\action\relax } + } + \end{minipage}\par\smallskip + } +{ + \end{pgfmanualentry} +} + +\def\processaction#1=#2\relax{ + \expandafter\let\expandafter\pgf@temp\csname manual@action@#1\endcsname + \ifx\pgf@temp\relax\else + \pgf@temp#2/0/\relax + \fi +} +\def\manual@action@length#1/#2/#3\relax{% + \draw [red,|<->|,semithick,xshift=#2] ([yshift=4pt]current bounding + box.north -| -#1,0) coordinate (last length) -- node + [above=-2pt] {|length|} ++(#1,0); +} +\def\manual@action@width#1/#2/#3\relax{% + \draw [overlay, red,|<->|,semithick] (.5,-#1/2) -- node [below,sloped] {|width|} (.5,#1/2); +} +\def\manual@action@inset#1/#2/#3\relax{% + \draw [red,|<->|,semithick,xshift=#2] ([yshift=-4pt]current bounding + box.south -| last length) -- node [below] {|inset|} ++(#1,0); +} + +\newenvironment{arrowexamples} +{\begin{tabbing} + \hbox to \dimexpr\linewidth-5.5cm\relax{\emph{Appearance of the below at line width} \hfil} \= + \hbox to 1.9cm{\emph{0.4pt}\hfil} \= \hbox to 2cm{\emph{0.8pt}\hfil} \= \emph{1.6pt} \\ + } +{\end{tabbing}\vskip-1em} + +\newenvironment{arrowcapexamples} +{\begin{tabbing} + \hbox to \dimexpr\linewidth-5.5cm\relax{\emph{Appearance of the below at line width} \hfil} \= + \hbox to 1.9cm{\emph{1ex}\hfil} \= \hbox to 2cm{\emph{1em}\hfil} \\ + } +{\end{tabbing}\vskip-1em} + +\def\arrowcapexample#1[#2]{\def\temp{#1}\ifx\temp\pgfutil@empty\arrowcapexample@\currentarrowtype[{#2}]\else\arrowcapexample@#1[{#2}]\fi} +\def\arrowcapexample@#1[#2]{% + {\sfcode`\.1000\small\texttt{#1[#2]}} \> + \kern-.5ex\tikz [baseline,>={#1[#2]}] \draw [line + width=1ex,->] (0,.5ex) -- (2em,.5ex); \> + \kern-.5em\tikz [baseline,>={#1[#2]}] \draw [line + width=1em,->] (0,.5ex) -- (2em,.5ex); \\ +} + +\def\arrowexample#1[#2]{\def\temp{#1}\ifx\temp\pgfutil@empty\arrowexample@\currentarrowtype[{#2}]\else\arrowexample@#1[{#2}]\fi} +\def\arrowexample@#1[#2]{% + {\sfcode`\.1000\small\texttt{#1[#2]}} \> + \tikz [baseline,>={#1[#2]}] \draw [line + width=0.4pt,->] (0,.5ex) -- (2em,.5ex); thin \> + \tikz [baseline,>={#1[#2]}] \draw [line + width=0.8pt,->] (0,.5ex) -- (2em,.5ex); \textbf{thick} \> + \tikz [baseline,>={#1[#2]}] \draw [line + width=1.6pt,->] (0,.5ex) -- (3em,.5ex); \\ +} +\def\arrowexampledup[#1]{\arrowexample[{#1] \currentarrowtype[}]} +\def\arrowexampledupdot[#1]{\arrowexample[{#1] . \currentarrowtype[}]} + +\def\arrowexampledouble#1[#2]{\def\temp{#1}\ifx\temp\pgfutil@empty\arrowexampledouble@\currentarrowtype[{#2}]\else\arrowexampledouble@#1[{#2}]\fi} +\def\arrowexampledouble@#1[#2]{% + {\sfcode`\.1000\small\texttt{#1[#2]} on double line} \> + \tikz [baseline,>={#1[#2]}] + \draw [double equal sign distance,line width=0.4pt,->] (0,.5ex) -- (2em,.5ex); thin \> + \tikz [baseline,>={#1[#2]}] + \draw [double equal sign distance,line width=0.8pt,->] (0,.5ex) -- (2em,.5ex); \textbf{thick} \> + \tikz [baseline,>={#1[#2]}] + \draw [double equal sign distance, line width=1.6pt,->] (0,.5ex) -- (3em,.5ex); \\ +} + + + +\newcommand\symarrow[1]{% \index{#1@\protect\texttt{#1} arrow tip}% - \index{Arrow tips!#1@\protect\texttt{#1}} + \index{Arrow tips!#1@\protect\texttt{#1}}% \texttt{#1}& yields thick \begin{tikzpicture}[arrows={#1-#1},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and thin \begin{tikzpicture}[arrows={#1-#1},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} } -\newcommand\symarrowdouble[1]{ +\newcommand\symarrowdouble[1]{% \index{#1@\protect\texttt{#1} arrow tip}% - \index{Arrow tips!#1@\protect\texttt{#1}} + \index{Arrow tips!#1@\protect\texttt{#1}}% \texttt{#1}& yields thick \begin{tikzpicture}[arrows={#1-#1},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and thin \begin{tikzpicture}[arrows={#1-#1},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture}, double \begin{tikzpicture}[arrows={#1-#1},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and \begin{tikzpicture}[arrows={#1-#1},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} } -\newcommand\sarrow[2]{ +\newcommand\sarrow[2]{% \index{#1@\protect\texttt{#1} arrow tip}% - \index{Arrow tips!#1@\protect\texttt{#1}} + \index{Arrow tips!#1@\protect\texttt{#1}}% \index{#2@\protect\texttt{#2} arrow tip}% - \index{Arrow tips!#2@\protect\texttt{#2}} + \index{Arrow tips!#2@\protect\texttt{#2}}% \texttt{#1-#2}& yields thick \begin{tikzpicture}[arrows={#1-#2},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and thin \begin{tikzpicture}[arrows={#1-#2},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} } -\newcommand\sarrowdouble[2]{ +\newcommand\sarrowdouble[2]{% \index{#1@\protect\texttt{#1} arrow tip}% - \index{Arrow tips!#1@\protect\texttt{#1}} + \index{Arrow tips!#1@\protect\texttt{#1}}% \index{#2@\protect\texttt{#2} arrow tip}% - \index{Arrow tips!#2@\protect\texttt{#2}} + \index{Arrow tips!#2@\protect\texttt{#2}}% \texttt{#1-#2}& yields thick \begin{tikzpicture}[arrows={#1-#2},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and thin \begin{tikzpicture}[arrows={#1-#2},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture}, double \begin{tikzpicture}[arrows={#1-#2},thick,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} and \begin{tikzpicture}[arrows={#1-#2},thin,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); + \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw[double,double equal sign distance] (0pt,.5ex) -- (1cm,.5ex); \end{tikzpicture} } -\newcommand\carrow[1]{ +\newcommand\carrow[1]{% \index{#1@\protect\texttt{#1} arrow tip}% - \index{Arrow tips!#1@\protect\texttt{#1}} + \index{Arrow tips!#1@\protect\texttt{#1}}% \texttt{#1}& yields for line width 1ex \begin{tikzpicture}[arrows={#1-#1},line width=1ex,baseline] - \useasboundingbox (0pt,-0.5ex) rectangle (1.5cm,2ex); + \useasboundingbox (-1mm,-0.5ex) rectangle (1.6cm,2ex); + \fill [black!15] (1.5cm,-.5ex) rectangle (1.6cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; \draw (0pt,.5ex) -- (1.5cm,.5ex); \end{tikzpicture} } @@ -1046,32 +1504,62 @@ % a proper replacement sequence for tabs (as many spaces as % configured) \def\codeexample@tabinit{% - \ifnum\pgfkeysvalueof{/codeexample/tabsize}=0\relax - \let\codeexample@tabinit@replacementchars=\relax - \let\codeexample@tabinit@catcode=\relax - \else - \let\codeexample@tabinit@catcode=\codeexample@tabinit@catcode@ - \let\codeexample@tabinit@replacementchars=\codeexample@tabinit@replacementchars@ - \fi + \ifnum\pgfkeysvalueof{/codeexample/tabsize}=0\relax + \let\codeexample@tabinit@replacementchars=\relax + \let\codeexample@tabinit@catcode=\relax + \else + \let\codeexample@tabinit@catcode=\codeexample@tabinit@catcode@ + \let\codeexample@tabinit@replacementchars=\codeexample@tabinit@replacementchars@ + \fi } +\newif\ifpgfmanualtikzsyntaxhilighting + \pgfqkeys{/codeexample}{% - width/.code= {\setlength\codeexamplewidth{#1}}, - graphic/.code= {\colorlet{graphicbackground}{#1}}, - code/.code= {\colorlet{codebackground}{#1}}, - execute code/.is if=code@execute, - code only/.code= {\code@executefalse}, - pre/.store in=\code@pre, - post/.store in=\code@post, + width/.code= {\setlength\codeexamplewidth{#1}}, + graphic/.code= {\colorlet{graphicbackground}{#1}}, + code/.code= {\colorlet{codebackground}{#1}}, + execute code/.is if=code@execute, + code only/.code= {\code@executefalse}, + pre/.store in=\code@pre, + post/.store in=\code@post, % #1 is the *complete* environment contents as it shall be % typeset. In particular, the catcodes are NOT the normal ones. - typeset listing/.code= {#1}, - render instead/.store in=\code@render, - vbox/.code= {\def\code@pre{\vbox\bgroup\setlength{\hsize}{\linewidth-6pt}}\def\code@post{\egroup}}, - ignorespaces/.code= {\let\@gobble@till@return=\@gobble@till@return@ignore}, - leave comments/.code= {\def\code@catcode@hook{\catcode`\%=12}\let\commenthandler=\relax\let\typesetcomment=\relax}, - tabsize/.initial=0,% FIXME : this here is merely used for indentation. It is just a TAB REPLACEMENT. - every codeexample/.style={width=4cm+7pt}, + typeset listing/.code= {#1}, + render instead/.store in=\code@render, + vbox/.code= {\def\code@pre{\vbox\bgroup\setlength{\hsize}{\linewidth-6pt}}\def\code@post{\egroup}}, + ignorespaces/.code= {\let\@gobble@till@return=\@gobble@till@return@ignore}, + leave comments/.code= {\def\code@catcode@hook{\catcode`\%=12}\let\commenthandler=\relax\let\typesetcomment=\relax}, + tabsize/.initial=0,% FIXME : this here is merely used for indentation. It is just a TAB REPLACEMENT. + every codeexample/.style={width=4cm+7pt, tikz syntax=true}, + from file/.code={\codeexamplefromfiletrue\def\codeexamplesource{#1}}, + tikz syntax/.is if=pgfmanualtikzsyntaxhilighting, +} + + +\newread\examplesource + + +% Opening, reading and closing the results file + +\def\opensource#1{ + \immediate\openin\examplesource=#1 +} +\def\do@codeexamplefromfile{% + \immediate\openin\examplesource\expandafter{\codeexamplesource}% + \def\examplelines{}% + \readexamplelines + \closein\examplesource + \expandafter\endofcodeexample\expandafter{\examplelines}% +} + +\def\readexamplelines{ + \ifeof\examplesource% + \else + \immediate\read\examplesource to \exampleline + \expandafter\expandafter\expandafter\def\expandafter\expandafter\expandafter\examplelines\expandafter\expandafter\expandafter{\expandafter\examplelines\exampleline} + \expandafter\readexamplelines% + \fi } \let\code@pre\pgfutil@empty @@ -1079,6 +1567,7 @@ \let\code@render\pgfutil@empty \def\code@catcode@hook{} +\newif\ifcodeexamplefromfile \newdimen\codeexamplewidth \newif\ifcode@execute \newbox\codeexamplebox @@ -1086,6 +1575,10 @@ \begingroup% \code@executetrue \pgfqkeys{/codeexample}{every codeexample,#1}% + \ifpgfmanualtikzsyntaxhilighting% + \pgfkeys{/codeexample/syntax hilighting}% + \fi% + \ifcodeexamplefromfile\begingroup\fi \codeexample@tabinit% assigns \codeexample@tabinit@[catcode,replacementchars] \parindent0pt \begingroup% @@ -1100,7 +1593,11 @@ \code@catcode@hook% \codeexample@tabinit@catcode \relax% - \find@example} + \ifcodeexamplefromfile% + \expandafter\do@codeexamplefromfile% + \else% + \expandafter\find@example% + \fi} \def\endofcodeexample#1{% \endgroup% \ifcode@execute% @@ -1155,6 +1652,7 @@ \fi% \code@mid% \colorbox{codebackground}{% + \pgfkeysvalueof{/codeexample/prettyprint/base color}% \begin{minipage}[t]{\code@width}% {% \let\do\@makeother @@ -1179,7 +1677,7 @@ \code@end% \par% \medskip - \end{codeexample} + \endcodeexample\endgroup } \def\endcodeexample{\endgroup} @@ -1189,16 +1687,52 @@ \usepackage{pgfmanual} -\makeatletter -% \pgfautoxrefs will be defined by 'make dist' -\pgfutil@ifundefined{pgfautoxrefs}{% - \def\pgfmanualpdflabel#1#2{#2}% NO-OP - \def\pgfmanualpdfref#1#2{#2}% - \pgfkeys{ - /pdflinks/codeexample links=false,% DISABLED. - }% -}{} -\makeatother + +% autoxref is now always on + +% \makeatletter +% % \pgfautoxrefs will be defined by 'make dist' +% \pgfutil@ifundefined{pgfautoxrefs}{% +% \renewcommand\pgfmanualpdflabel[3][]{#3}% NO-OP +% \def\pgfmanualpdfref#1#2{#2}% +% \pgfkeys{ +% /pdflinks/codeexample links=false,% DISABLED. +% }% +% }{} +% \makeatother + +\newdimen\pgfmanualcslinkpreskip + +% Styling of the pretty printer +\pgfkeys{ + /codeexample/syntax hilighting/.style={ + /codeexample/prettyprint/key name/.code={\textcolor{green!50!black}{\pgfmanualpdfref{##1}{##1}}}, + /codeexample/prettyprint/key name with handler/.code 2 args={\textcolor{green!50!black}{\pgfmanualpdfref{##1}{##1}}/\textcolor{blue!70!black}{\pgfmanualpdfref{/handlers/##2}{##2}}}, + /codeexample/prettyprint/key value display only/.code={\textcolor{green!50!black}{{\itshape{\let\pgfmanualwordstartup\relax\pgfmanualprettyprintcode{##1}}}}}, + /codeexample/prettyprint/cs/.code={\textcolor{blue!70!black}{\pgfmanualcslinkpreskip4.25pt\pgfmanualpdfref{##1}{##1}}}, + /codeexample/prettyprint/cs with args/.code 2 args={\textcolor{black}{\pgfmanualcslinkpreskip4.25pt\pgfmanualpdfref{##1}{##1}}\{\textcolor{black}{\pgfmanualprettyprintcode{##2}}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/pgfkeys/.initial=1, + /codeexample/prettyprint/cs/pgfkeys/.code 2 args={\textcolor{black}{\pgfmanualcslinkpreskip4.25pt\pgfmanualpdfref{##1}{##1}}\{\textcolor{black}{\pgfmanualprettyprintpgfkeys{##2}}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/begin/.initial=1, + /codeexample/prettyprint/cs/begin/.code 2 args={\textcolor{black}{##1}\{\textcolor{blue!70!black}{\pgfmanualpdfref{##2}{##2}}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/end/.initial=1, + /codeexample/prettyprint/cs/end/.code 2 args={\textcolor{black}{##1}\{\textcolor{blue!70!black}{\pgfmanualpdfref{##2}{##2}}\pgfmanualclosebrace}, + /codeexample/prettyprint/word/.code={\pgfmanualwordstartup{\begingroup\pgfkeyssetvalue{/pdflinks/search key prefixes in}{}\pgfmanualpdfref{##1}{##1}\endgroup}}, + /codeexample/prettyprint/point/.code={\textcolor{violet}{##1}},% + /codeexample/prettyprint/point with cs/.code 2 args={\textcolor{violet}{(\pgfmanualpdfref{##1}{##1}:##2}},% + /codeexample/prettyprint/comment font=\itshape, + /codeexample/prettyprint/base color/.initial=\color{black!55}, + /pdflinks/render hyperlink/.code={% + {\setbox0=\hbox{##1}% + \rlap{{\color{white}\dimen0\wd0\advance\dimen0by-\pgfmanualcslinkpreskip\hskip\pgfmanualcslinkpreskip\vrule width\dimen0 height-1pt depth1.6pt}}% + \box0% + }% + } + } +} + +\def\pgfmanualwordstartup{\textcolor{black}} + %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/doc/generic/pgf/pgfmanual.pdf b/Master/texmf-dist/doc/generic/pgf/pgfmanual.pdf Binary files differindex 68d7e593a38..24ba754a77e 100644 --- a/Master/texmf-dist/doc/generic/pgf/pgfmanual.pdf +++ b/Master/texmf-dist/doc/generic/pgf/pgfmanual.pdf diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex index 77172602df0..81d12c2c6e9 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex @@ -31,6 +31,8 @@ In detail, paths can be used in the following ways: \item You can \emph{stroke} (also known as \emph{draw}) a path. \item + You can add \emph{arrow tips} to a path. +\item You can \emph{fill} a path with a uniform color. \item You can \emph{clip} subsequent renderings against the path. @@ -42,7 +44,7 @@ In detail, paths can be used in the following ways: You can also perform any combination of the above, though it makes no sense to fill and shade a path at the same time. -To perform (a combination of) the first three actions, you can use the +To perform (a combination of) the first four actions, you can use the following command: \begin{command}{\pgfusepath\marg{actions}} Applies the given \meta{actions} to the current path. Afterwards, @@ -59,8 +61,8 @@ following command: \pgfusepath{fill} \end{pgfpicture} \end{codeexample} - \item \declare{|stroke|} - strokes the path. See Section~\ref{section-stroke} for further details. + \item \declare{|stroke|} strokes the path. See + Section~\ref{section-stroke} for further details. \begin{codeexample}[] \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} @@ -69,9 +71,10 @@ following command: \pgfusepath{stroke} \end{pgfpicture} \end{codeexample} + \item \declare{|draw|} has the same effect as |stroke|. \item \declare{|clip|} - clips all subsequent drawings against the path. See - Section~\ref{section-clip} for further details. + clips all subsequent drawings against the path. Always supresses + arrow tips. See Section~\ref{section-clip} for further details. \begin{codeexample}[] \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} @@ -251,91 +254,6 @@ this may change in the future, so do not count on this. You can set the stroke opacity using |\pgfsetstrokeopacity|. This command is described in Section~\ref{section-transparency}. -\subsubsection{Graphic Parameter: Arrows} - -After a path has been drawn, \pgfname\ can add arrow tips at the -ends. It will only add arrows at the beginning of the first subpath -and at the end of the last subpath. For closed paths the result is not -defined, that is, it may change without notice in the future. - -\begin{command}{\pgfsetarrowsstart\marg{arrow kind}} - Sets the arrow tip kind used at the start of a (possibly curved) - path. When this option is used, the line will often be slightly - shortened to ensure that the tip of the arrow will exactly ``touch'' - the ``real'' start of the line. - - To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|. -\begin{codeexample}[] -\begin{pgfpicture} - \pgfsetarrowsstart{latex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{1cm}{0cm}} - \pgfusepath{stroke} - \pgfsetarrowsstart{to} - \pgfpathmoveto{\pgfpoint{0cm}{2mm}} - \pgfpathlineto{\pgfpoint{1cm}{2mm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{codeexample} - - The effect of this command persists only till the end of the current - \TeX\ scope. - - The different possible arrow kinds are explained in - Section~\ref{section-arrows}. -\end{command} - -\begin{command}{\pgfsetarrowsend\marg{arrow kind}} - Sets the arrow tip kind used at the end of a path. -\begin{codeexample}[] -\begin{pgfpicture} - \pgfsetarrowsstart{latex} - \pgfsetarrowsend{to} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{1cm}{0cm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{codeexample} -\end{command} - -\begin{command}{\pgfsetarrows{\texttt{\char`\{}}\meta{start kind}|-|\meta{end kind}{\texttt{\char`\}}}} - Sets the start arrow kind to \meta{start kind} and the end kind to - \meta{end kind}. -\begin{codeexample}[] -\begin{pgfpicture} - \pgfsetarrows{latex-to} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{1cm}{0cm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{codeexample} -\end{command} - -\begin{command}{\pgfsetshortenstart\marg{dimension}} - This command will shortened the start of every stroked path by the - given dimension. This shortening is done in addition to automatic - shortening done by a start arrow, but it can be used even if no - start arrow is given. - - This command is useful if you wish arrows or lines to ``stop shortly - before'' a given point. -\begin{codeexample}[] -\begin{pgfpicture} - \pgfpathcircle{\pgfpointorigin}{5mm} - \pgfusepath{stroke} - \pgfsetarrows{latex-} - \pgfsetshortenstart{4pt} - \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle - \pgfpathlineto{\pgfpoint{2cm}{0cm}} - \pgfusepath{stroke} -\end{pgfpicture} -\end{codeexample} -\end{command} - -\begin{command}{\pgfsetshortenend\marg{dimension}} - Works like |\pgfsetshortenstart|. -\end{command} - \subsubsection{Inner Lines} @@ -345,7 +263,7 @@ color. This is a useful effect for creating ``double'' lines, for instance by setting the line width to 2pt and stroking a black line and then setting the inner line width to 1pt and stroking a white line on the same path as the original path. This results in what looks -like two lines, each of thickness 0.5pt, spaces 1pt apart. +like two lines, each of thickness 0.5pt, spaced 1pt apart. You may wonder why there is direct support for this ``double stroking'' in the basic layer. After all, this effect is easy to @@ -416,6 +334,98 @@ Two commands are used to set the inner line width and color. \end{command} +\subsection{Arrow Tips on a Path} +\label{section-tips} + +After a path has been drawn, \pgfname\ can add arrow tips at the +ends, depending on how the |tips| key is set, on whether |stroke| or +|clip| arw used and on whether the path contains closed subpaths. The +exact rules when arrow tips are added are explained in +Section~\ref{section-arrow-tips-where}. + +\begin{command}{\pgfsetarrowsstart\marg{start arrow tip specification}} + Sets the arrow tip kind used at the start of a (possibly curved) + path. The syntax of the \meta{start arrow specification} is detailed + in Section~\ref{section-arrow-spec}. + + To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{Latex[length=10pt]} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \pgfsetarrowsstart{Computer Modern Rightarrow} + \pgfpathmoveto{\pgfpoint{0cm}{2mm}} + \pgfpathlineto{\pgfpoint{1cm}{2mm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + + The effect of this command persists only till the end of the current + \TeX\ scope. +\end{command} + +\begin{command}{\pgfsetarrowsend\marg{end arrow tip specification}} + Sets the arrow tip kind used at the end of a path. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsstart{Latex[length=10pt]} + \pgfsetarrowsend{Computer Modern Rightarrow} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetarrows\marg{argument}} + The \meta{argument} can be of the form \meta{start arrow tip + specifciation}|-|\meta{end arrow tip specification}. In this + case, both the start and the end arrow specification are set: +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrows{Latex[length=10pt]->>} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + Alternatively, \meta{argument} can be of the form |[|\meta{arrow + keys}|]|. In this case, the \meta{arrow keys} will be set for all + arrow tips in the current scope, see Section~\ref{section-arrow-scopes}. +\end{command} + + +\begin{command}{\pgfsetshortenstart\marg{dimension}} + This command will shortened the start of every stroked path by the + given dimension. This shortening is done in addition to automatic + shortening done by a start arrow, but it can be used even if no + start arrow is given. + + It is usually better to use the |sep| key with arrow tips. + + This command is useful if you wish arrows or lines to ``stop shortly + before'' a given point. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{5mm} + \pgfusepath{stroke} + \pgfsetarrows{Latex-} + \pgfsetshortenstart{4pt} + \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetshortenend\marg{dimension}} + Works like |\pgfsetshortenstart|. +\end{command} + + + \subsection{Filling a Path} \label{section-fill} @@ -423,7 +433,7 @@ Filling a path means coloring every interior point of the path with the current fill color. It is not always obvious whether a point is ``inside'' a path when the path is self-intersecting and/or consists or multiple parts. In this case either the nonzero winding number rule -or the even-odd crossing number rule is used to decide, which points +or the even-odd crossing number rule is used to decide which points lie ``inside.'' These rules are explained in Section~\ref{section-rules}. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex index aac739b9d1f..15926efe567 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex @@ -1,4 +1,4 @@ -% Copyright 2006 by Till Tantau +% Copyright 2013 by Till Tantau % % This file may be distributed and/or modified % @@ -8,54 +8,30 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Arrow Tips} +\section{Defining New Arrow Tip Kinds} \label{section-arrows} \subsection{Overview} -\subsubsection{When Does PGF Draw Arrow Tips?} - -\pgfname\ offers an interface for placing \emph{arrow tips} at the end -of lines. The interface works as follows: - -\begin{enumerate} -\item - You (or someone else) assigns a name to a certain kind of arrow - tips. For example, the - arrow tip |latex| is the arrow tip used by the standard \LaTeX\ - picture environment; the arrow tip |to| looks like the tip of the - arrow in \TeX's |\to| command; and so on. - - This is done once at the beginning of the document. -\item - Inside some picture, at some point you specify that in the current - scope from now on you would like tips of, say, kind |to| to be added - at the end and/or beginning of all paths. - - When an arrow kind has been installed and when \pgfname\ is about to - stroke a path, the following things happen: - \begin{enumerate} - \item - The beginning and/or end of the path is shortened appropriately. - \item - The path is stroked. - \item - The arrow tip is drawn at the beginning and/or end of the path, - appropriately rotated and appropriately resized. - \end{enumerate} -\end{enumerate} - -In the above description, there are a number of ``appropriately.'' -The exact details are not quite trivial and described later on. - - -\subsubsection{Meta-Arrow Tips} - -In \pgfname, arrows are ``meta-arrows'' in the same way that fonts in -\TeX\ are ``meta-fonts.'' When a meta-arrow is resized, it is not -simply scaled, but a possibly complicated transformation is applied to -the size. +In present section we have a look at how you can define new arrow tips +for use in \pgfname. The low-level commands for selecting which arrow +tips are to be used have already been described in +Section~\ref{section-tips}, the general syntax rules for using arrows +are detailed in Section~\ref{section-tikz-arrows}. Although +Section~\ref{section-tikz-arrows} describes the use of arrows in +\tikzname, in reality, \tikzname\ itself does not actually do anything +about arrow tips; all of the functionality is implemented on the +\pgfname\ level in the commands described in +Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key +handler described in Section~\ref{section-tikz-arrows} is actually +implemented on the \pgfname\ layer. + +What has \emph{not} yet been covered is how you can actually define a +complete new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the +same way that fonts in \TeX\ are ``meta-fonts.'' When a meta-arrow is +resized, it is not simply scaled, but a possibly complicated +transformation is applied to the size. A meta-font is not one particular font at a specific size with a specific stroke width (and with a large number of other parameters @@ -73,84 +49,42 @@ text was scaled down, while the second text is a ``normal'' tiny text. The second text is easier to read. \pgfname's meta-arrows work in a similar fashion: The shape of an -arrow tip can vary according to the line width of the arrow tip is -used. Thus, an arrow tip drawn at a line width of 5pt will typically -\emph{not} be five times as large as an arrow tip of line width -1pt. Instead, the size of the arrow will get bigger only slowly as the -line width increases. +arrow tip can vary according to a great number of parameters, the line +width of the arrow tip being one of them. Thus, an arrow tip drawn at +a line width of 5pt will typically \emph{not} be five times as large +as an arrow tip of line width 1pt. Instead, the size of the arrow will +get bigger only slowly as the line width increases. -To appreciate the difference, here are the |latex| and |to| arrows, as -drawn by \pgfname\ at four different sizes: +To appreciate the difference, here are the |Latex| and +|Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different sizes: \medskip -\begin{tikzpicture} - \draw[-latex,line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-latex,line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-latex,line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-latex,line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; - - \draw[-to,line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-to,line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-to,line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-to,line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; +\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow] + \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-1, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + + \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-2, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; \end{tikzpicture} \medskip -Here, by comparison, is the same arrow when it is simply ``resized'' -(as done by some programs): - -\pgfarrowsdeclare{bad latex}{bad latex} -{ - \pgfarrowsleftextend{-1\pgflinewidth} - \pgfarrowsrightextend{9\pgflinewidth} -} -{ - \pgfpathmoveto{\pgfpoint{9\pgflinewidth}{0pt}} - \pgfpathcurveto - {\pgfpoint{6.3333\pgflinewidth}{.5\pgflinewidth}} - {\pgfpoint{2\pgflinewidth}{2\pgflinewidth}} - {\pgfpoint{-1\pgflinewidth}{3.75\pgflinewidth}} - \pgfpathlineto{\pgfpoint{-1\pgflinewidth}{-3.75\pgflinewidth}} - \pgfpathcurveto - {\pgfpoint{2\pgflinewidth}{-2\pgflinewidth}} - {\pgfpoint{6.3333\pgflinewidth}{-.5\pgflinewidth}} - {\pgfpoint{9\pgflinewidth}{0pt}} - \pgfusepathqfill -} - -\pgfarrowsdeclare{bad to}{bad to} -{ - \pgfarrowsleftextend{-2\pgflinewidth} - \pgfarrowsrightextend{\pgflinewidth} -} -{ - \pgfsetlinewidth{0.8\pgflinewidth} - \pgfsetdash{}{0pt} - \pgfsetroundcap - \pgfsetroundjoin - \pgfpathmoveto{\pgfpoint{-3\pgflinewidth}{4\pgflinewidth}} - \pgfpathcurveto - {\pgfpoint{-2.75\pgflinewidth}{2.5\pgflinewidth}} - {\pgfpoint{0pt}{0.25\pgflinewidth}} - {\pgfpoint{0.75\pgflinewidth}{0pt}} - \pgfpathcurveto - {\pgfpoint{0pt}{-0.25\pgflinewidth}} - {\pgfpoint{-2.75\pgflinewidth}{-2.5\pgflinewidth}} - {\pgfpoint{-3\pgflinewidth}{-4\pgflinewidth}} - \pgfusepathqstroke -} +Here, by comparison, are the same arrows when they are simply ``resized'': \medskip -\begin{tikzpicture} - \draw[-bad latex,line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-bad latex,line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-bad latex,line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-bad latex,line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; - - \draw[-bad to,line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; - \draw[-bad to,line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; - \draw[-bad to,line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; - \draw[-bad to,line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; +\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow] + \draw[-{1[length=1pt]}, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-{1[length=4pt]}, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-{1[length=12pt]}, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-{1[length=32pt]}, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; + + \draw[-{2[length=0.455pt]}, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt}; + \draw[-{2[length=1.82pt]}, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt}; + \draw[-{2[length=5.46pt]}, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt}; + \draw[-{2[length=14.56pt]}, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt}; \end{tikzpicture} \bigskip @@ -163,632 +97,807 @@ appearance of an arrow tip. In particular, the width of the inner line tips as well as other options that are specific to the arrow tip. +\subsection{Terminology} +\label{section-arrow-terminology} -\subsection{Declaring an Arrow Tip Kind} - -To declare an arrow kind ``from scratch,'' the following command is -used: +Before we have a look at the exact commands used for defining arrow +tips, we need to fix some terminology. Consider the following drawing +of an arrow tip where the arrow tip is drawn transparently so that we +can see what is ``happening behind it'': -\begin{command}{\pgfarrowsdeclare\marg{start name}\marg{end - name}\marg{extend code}\marg{arrow tip code}} - This command declares a new arrow kind. An arrow kind has two names, - which will typically be the same. When the arrow tip needs to be - drawn, the \meta{arrow tip code} will be invoked, but the canvas - transformation is setup beforehand to a rotation such that when an - arrow tip pointing right is specified, the arrow tip that is - actually drawn points in the direction of the line. +\begin{tikzpicture} + \draw [red!50, ,line width=1cm] (0,0) -- (4,0); + \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0); + + \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis}; + \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis}; + + \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$}; + \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};; +\end{tikzpicture} - \medskip - \textbf{Naming the arrow kind.} - The \meta{start name} is the name - used for the arrow tip when it is at the start of a path, the \meta{end - name} is the name used at the end of a path. For example, the - arrow kind that looks like a parenthesis has the \meta{start - name} |(| and the \meta{end name} |)| so that you can say - |\pgfsetarrows{(-)}| to specify that you want parenthesis arrows and - both ends. - - The \meta{end name} and \meta{start name} can be quite arbitrary and - may contain spaces. +I have also added a coordinate system. The code for drawing an arrow +tip always draws it in the way shown above: Pointing right along the +$x$-axis. + +We will use the following terminology: +\begin{itemize} +\item The point where tip of the arrow ends is called the + \emph{tip end}. It is at $(1,0)$ in our example and we always + assume it to lie on the $x$-axis, so we just treat it as a distance, + 1 in this case. This is the position where the original path was + supposed to end (so if the arrow tip had not been added to the red + path, it would have ended here). +\item The \emph{back end} of the arrow is where a vertical line just + to the left of the arrow intersects the $x$-axis. In our case, this + is the point $(-3,0)$ and again we treat it as a distance, $-3$ in + this case. +\item The \emph{line end} is the position where the path now + ends. This should be a position inside the arrow head that gets + ``covered'' by the path. Note that a path may have a round or a rect + head and should still be covered. Clearly, necessary shortening of + the path will be the difference between the tip end and the line + end. +\item The \emph{visual back end} is the position where the path and + the the arrow head ``meet last'' on the path. In our case, because + of the inset, the visual back end is not the same as the back end: + The arrow ends ``visually'' at $(-2,0)$. The difference between the + back end and the visual back end is important when the arrow tip is + flexed, see Section~\ref{section-arrow-flex} for an explanation of + flexing. +\item There is also a \emph{visual tip end}, the counterpart of the + visual back end for the front. In our case, the visual tip end and + the tip end obviously coincide, but if we were to reverse the arrow + tip, the visual tip end would be different form the tip end (while + the visual back end would then coincide with the new back end). +\item There are four points that make up the \emph{convex hull} of the + arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$. + + Normally, \pgfname\ automatically keeps track of a bounding box of + everything you draw. However, since arrow tips are drawn so often, + \pgfname\ caches the code needing for drawing arrow tips internally + and because of this cache it cannot determine the size of the arrow + tip just based on the drawing commands used for drawing the + tip. Instead, a convex hull of the arrow tip must be explicitly + provided in the definition. +\end{itemize} + +When you design a new arrow tip, all of the above parameters must be +defined. + +\subsection{Caching and Rendering of Arrows} + +As a last preparation for the description of the commands for +declaring arrows, it is important to understand the exact process by +which \pgfname\ draws arrows. - \medskip - \textbf{Basics of the arrow tip code.} - Let us next have a look at the \meta{arrow tip code}. This code will - be used to draw the arrow tip when \pgfname\ thinks this is - necessary. The code should draw an arrow that ``points right,'' - which means that is should draw an arrow at the end of a line coming - from the left and ending at the origin. - - As an example, suppose we wanted to declare an arrow tip consisting - of two arcs, that is, we want the arrow tip to look more or less - like the red part of the following picture: -\begin{codeexample}[] -\begin{tikzpicture}[line width=3pt] - \draw (-2,0) -- (0,0); - \draw[red,line join=round,line cap=round] - (-10pt,10pt) arc (180:270:10pt) arc (90:180:10pt); -\end{tikzpicture} -\end{codeexample} +\begin{enumerate} +\item First, you have to define an arrow tip kind using + |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that %} + |foo| is now the name of an arrow tip. In particular, the + parser for arrow tip specifications will now treat |foo| as the name + of an arrow tip and will not try to consider |f|, |o|, and |o| as + the names of single-char shorthands. + + Other than storing the definitions in the declaration internally, + this command has little other effect. In particular, no drawing or + other processing takes place. +\item Now assume that at some point the arrow tip |foo| is actually + used. In this case, certain options may have been set, for instance + the user may have requested the arrow tip + |foo[length=5pt,open]|. What happens next depends on whether it is + the first time the arrow tip |foo| is used with \emph{these exact + options} ornot. +\item Assume that is the first time |foo| is requested at a length of + 5pt and in an ``open'' version. \pgfname\ now retrieves the + definition of the arrow tip kind that it stored in the first step + and executes the so-called \emph{setup} code. When this code is + executed, all the options will be in force (for + instance, |\pgfarrowlength| will equal |5pt| in our case). The job + of the setup code is two-fold: First, it needs to compute all of the + parameters listed in Section~\ref{section-arrow-terminology}, that + is, it has to compute where the tip end will lie in the arrow tip's + coordinate system \emph{at the particular size of 5pt}, where the + back end will be, where the convex hull points lie, and so + on. Second, the setup code should precompute values that will be + important for constructing the path of the arrow. In our example, + there is little to do in this regard, but for more complicated + arrows, all time-consuming preparations are done now. + + It is \emph{not} the job of the setup to actually draw the arrow + tip, only to ``prepare'' this as much as possible. + + The setup code will always be executed only once for each arrow tip + kind for a given set of options. Thus, when a user uses + |foo[length=5pt,open]| once more later anywhere in the document, the + setup code will not be executed again. +\item The next thing that happens is that we have a look at the + \emph{drawin code} stored in the |code| field of the arrow. In our + example, the drawing code would consist of creating a filled path + with four straight segments. + + In most cases, what happens now is that the drawing code is executed in a + special sandbox in which the low-level driver commands that do the + actual drawing are intercepted and stored away in a so-called + \emph{cache}. Once such a cache has been created, its contents will + be reused whenever |foo[length=5pt,open]| is requested by a user and + just like the setup code, the drawing code will not be executed + again. + + There are, however, two cases in which the drawing code gets executed + each time the arrow is used: First, an arrow tip kind can specify + that this should always happen by saying |cachable=false| in its + definition. This is necessary if the drawing code contains + low-level drawing commands that cannot be intercepted such as a use + of |\pgftext| for arrow tips that ``contain text.'' Second, when the + |bend| option is used, the same arrow tip will look different each + time it is used, namely in dependence on the exact curvature of the + path to which it is added. + + Because the drawing code may be executed several times, while the + setup code may not, we must find a way to ``communicate'' the + values computed by the setup code to the drawing code. This is done + by explicitly calling |\pgfarrowssave| inside the setup + code. Whatever is ``saved'' in this way is restored each time before + the drawing code is executed. +\end{enumerate} - We could use the following as \meta{arrow tip code} for this: -\begin{codeexample}[code only] -\pgfarrowsdeclare{arcs}{arcs}{...} -{ - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-10pt}{10pt}} - \pgfpatharc{180}{270}{10pt} - \pgfpatharc{90}{180}{10pt} - \pgfusepathqstroke -} -\end{codeexample} +As can be seen, the process is a bit involved, but it leads to +a reasonably fast arrow tip management. - Indeed, when the |...| is set appropriately (in a moment), we can - write the following: -\pgfarrowsdeclare{arcs}{arcs}{\pgfarrowsleftextend{0pt}\pgfarrowsrightextend{0pt}} -{ - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-10pt}{10pt}} - \pgfpatharc{180}{270}{10pt} - \pgfpatharc{90}{180}{10pt} - \pgfusepathqstroke -} -\begin{codeexample}[] -\begin{tikzpicture} - \draw[-arcs,line width=3pt] (-2,0) -- (0,0); - \draw[arcs-arcs,line width=1pt] (-2,-1.5) -- (0,-1); - \useasboundingbox (-2,-2) rectangle (0,0.75); -\end{tikzpicture} -\end{codeexample} - As can be seen in the second example, the arrow tip is automatically - rotated as needed when the arrow is drawn. This is achieved by a - canvas rotation. +\subsection{Declaring an Arrow Tip Kind} +\begin{command}{\pgfdeclarearrow\marg{config}} + This command is both used to define a new arrow tip kind and to to + declare a so-called shorthand. We have a look at the case that a + complete new arrow tip kind is created and then have a look how the + command can be used to create shorthands. + \medskip - \textbf{Special considerations about the arrow tip code.} - There are several things you need to be aware of when designing - arrow tip code: - \begin{itemize} - \item - Inside the code, you may not use the |\pgfusepath| - command. The reason is that this command internally calls arrow - construction commands, which is something you obviously do not want - to happen. - - Instead of |\pgfusepath|, use the quick versions. Typically, you - will use |\pgfusepathqstroke|, |\pgfusepathqfill|, or - |\pgfusepathqfillstroke|. - \item - The code will be executed only once, namely the first time the - arrow tip needs to be drawn. The resulting low-level driver - commands are protocolled and stored away. In all subsequent - uses of the arrow tip, the protocolled code is directly inserted. - \item - However, the code will be executed anew for each line width. Thus, - an arrow of line width 2pt may result in a different protocol than - the same arrow for a line width of 0.4pt. - \item - If you stroke the path that you construct, you should first set - the dashing to solid and setup fixed joins and caps, as - needed. This will ensure that the arrow tip will always look the - same. - \item - When the arrow tip code is executed, it is automatically put - inside a low-level scope, so nothing will ``leak out'' from the - scope. - \item - The high-level coordinate transformation matrix will be set to the - identity matrix when the code is executed for the first time. - \end{itemize} + \noindent\textbf{Defining a Complete New Arrow Tip Kind.} + The \meta{config} is a key--value list in which different keys are + used to setup the to-be defined arrow. The following keys can be given: - \medskip - \textbf{Designing meta-arrows.} - The \meta{arrow tip code} should adjust the size of the arrow in - accordance with the line width. For a small line width, the arrow - tip should be small, for a large line width, it should be - larger. However, the size of the arrow typically \emph{should not} - grow in direct proportion to the line width. On the other hand, the - size of the arrow head typically \emph{should} grow ``a bit'' with - the line width. - - For these reasons, \pgfname\ will not simply executed your arrow - code within a scaled scope, where the scaling depends on the line - width. Instead, your \meta{arrow tip code} is reexecuted again for - each different line width. - - In our example, we could use the following code for the new arrow - tip kind |arc'| (note the prime): + \begin{itemize} + \item \declare{|name|}|=|\meta{name} or |name=|\meta{start name}|-|\meta{end + name} + + This defines the name of the arrow tip. It is legal to define an + arrow tip a second time, in this case the previous definition will + be overwritten in the current \TeX\ scope. It is customary to use + a name with an uppercase fist letter for a ``complete'' arrow tip + kind. Short names and lower case names should be used for + shorthands that change their meaning inside a document, while + arrow tips with uppercase first letters should not be redefined. + + If the name contains a hyphen, the second syntax is assumed and + everything before the hyphen will be the name used in start arrow + specifications, while the text after the hyphen is the name used + in end specifications. + \item \declare{|parameters|}|=|\marg{list of macros} + + As explained earlier, an arrow tip typically needs to be redrawn + each time an option like |length| or |inset| is changed. However, + for some arrow tips, the |inset| has no influence, while for other + it is important whether the arrow is reversed or not. (How keys + like |length| actually set \TeX\ dimensions like |\pgfarrowlength| + is explained in Section~\ref{section-arrow-options}.) + + The job of the |parameters| key is to specify which dependencies + the arrow tip has. Everything that will influence any of the + parameters computed in the setup code or used in the drawing code + should be listed here. + + The \meta{list of macros} will be used inside a + |\csname|-|\endcsname| pair and should expand to the current + values of the relevant parameters have. For example, if the arrow + tip depends on the current value of |\pgfarrowlength| and + |\pgfarrowwidth| only, then \meta{list of macros} should be set to + |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is + optional, the \meta{list of macros} does not really have to be a + list, just something that can be expanded unambiuously.) + + Note that the line width (|\pgflinewidth|) and the inner line + width (|\pgfinnerlinewidth|) are always parameters and need not be + specified in the |parameters|. + + It is important to get this parameter right. Otherwise, arrow tips + may look wrong because \pgfname\ thinks that it can reuse some + code when, in reality, this code actually depends on a parameter + not listed here. + + \item \declare{|setup code|}|=|\marg{code} + + When an arrow tip is used, the value stored in |parameters| is + expanded and it is tested whether the result was encountered + before. If not, the \meta{code} gets executed (only this + once). The code can now do aribtrarily complicated computations + the prepare the later drawing of the arrow tip. Also the + \meta{code} must specify the different tip and back ends and the + convex hull points. This is done by calling the following macros + inside the \meta{code}: + + \begin{command}{\pgfarrowssettipend\marg{dimension}} + When this command is called inside the setup code of an arrow + tip, it specifies that the tip of the drawn arrow will end + exactly at \meta{dimension}. For example, for our earlier + example of the large arrow tip, where the tip end was at 1cm, we + would call \begin{codeexample}[code only] -\newdimen\arrowsize -\pgfarrowsdeclare{arcs'}{arcs'}{...} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} - \pgfpatharc{180}{270}{4\arrowsize} - \pgfpatharc{90}{180}{4\arrowsize} - \pgfusepathqstroke -} +\pgfarrowssettipend{1cm} \end{codeexample} -\newdimen\arrowsize -\pgfarrowsdeclare{arcs'}{arcs'}{\pgfarrowsleftextend{0pt}\pgfarrowsrightextend{0pt}} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} - \pgfpatharc{180}{270}{4\arrowsize} - \pgfusepathqstroke - \pgfpathmoveto{\pgfpointorigin} - \pgfpatharc{90}{180}{4\arrowsize} - \pgfusepathqstroke -} -\begin{codeexample}[] -\begin{tikzpicture} - \draw[-arcs',line width=3pt] (-2,0) -- (0,0); - \draw[arcs'-arcs',line width=1pt] (-2,-1.5) -- (0,-1); - \useasboundingbox (-2,-1.75) rectangle (0,0.5); -\end{tikzpicture} + Note that for efficience reasons, the \meta{dimension} is not + passed through |\pgfmathsetlength|; rather what happens is that + |\pgf@x=|\meta{dimension} gets executed. In particular, you can + pack further computations into the \meta{dimension} by simply + starting it with a number and then appending some code that + modifies |\pgf@x|. Here is an example where instead of 1cm we + use $1\mathrm{cm} - \frac12\mathrm{linewidth}$ as the tip end: +\begin{codeexample}[code only] +\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth} \end{codeexample} + If the command is not called at all inside the setup code, the + tip end is set to |0pt|. + \end{command} - However, sometimes, it can also be useful to have arrows that do not - resize at all when the line width changes. This can be achieved by - giving absolute size coordinates in the code, as done for |arc|. On - the other hand, you can also have the arrow resize linearly with the - line width by specifying all coordinates as multiples of - |\pgflinewidth|. - - \medskip - \textbf{The left and right extend.} - Let us have another look at the exact left and right ``ends'' of our - arrow tip. Let us draw the arrow tip |arc'| at a very large size: - -\begin{codeexample}[] -\begin{tikzpicture} - \draw[help lines] (-2,-1) grid (1,1); - \draw[line width=10pt,-arcs'] (-2,0) -- (0,0); - \draw[line width=2pt,white] (-2,0) -- (0,0); -\end{tikzpicture} + \begin{command}{\pgfarrowssetbackend\marg{dimension}} + Works like the command for the tip end, only it sets the back + end. In our example we would call +\begin{codeexample}[code only] +\pgfarrowssettipend{-3cm} \end{codeexample} + Defaults to |0pt|. + \end{command} + + \begin{command}{\pgfarrowssetlineend\marg{dimension}} + Sets the line end, so in the example we have + |\pgfarrowssettipend{-1cm}|. Default to |0pt|. + \end{command} + + \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}} + Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in + our example. Default to the value of the normal back end. + \end{command} + + \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}} + Sets the visual tip end. Default to the value of the normal tip + end and, thus, we need not set it in our example. + \end{command} + + \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}} + Adds a point to the convex hull of the arrow tip. As for the + previous commands, no math parsing is done; instead \pgfname\ + says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y + dimension}. Thus, both ``dimensions'' can contain code for + advancing and thus modifying |\pgf@x| and |\pgf@y|. + + In our example we would write +\begin{codeexample}[code only] +\pgfarrowshullpoint{1cm}{0pt} +\pgfarrowshullpoint{-3cm}{2cm} +\pgfarrowshullpoint{-3cm}{-2cm} +\end{codeexample} + \end{command} - As one can see, the arrow tip does not ``touch'' the origin as it - should, but protrudes a little over the origin. One remedy to this - undesirable effect is to change the code of the arrow tip such that - everything is shifted half an |\arrowsize| to the left. While this - will cause the arrow tip to touch the origin, the line itself will - then interfere with the arrow: The arrow tip will be partly - ``hidden'' by the line itself. - - \pgfname\ uses a different approach to solving the problem: The - \meta{extend code} argument can be used to ``tell'' \pgfname\ how - much the arrow protrudes over the origin. The argument is also used - to tell \pgfname\ where the ``left'' end of the arrow is. However, - this number is important only when the arrow is being reversed or - composed with other arrow tips. - - Once \pgfname\ knows the right extend of an arrow kind, it can - \emph{shorten} lines by this amount when drawing arrows. - Here is a picture that shows what the visualizes the extends. The - arrow tip itself is shown in red once more: + \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}} + This command works like the previous command, only it normally + adds \emph{two} points to the convex hull: First, the point $(\meta{x + dimension},\meta{y dimension})$ and, secondly, the point $(\meta{x + dimension},-\meta{y dimension})$. However, the second point is + only added if the arrow is not a harpoon. - \medskip - \begin{tikzpicture} - \draw[line width=1cm,-arcs',red] (-6,0) -- (0,0); - \draw[line width=1cm,black] (-6,0) -- (0,0); - \draw[help lines] (-6,0) -- (2,0) (0,-3) -- (0,3) coordinate (a); - \draw[help lines,xshift=0.5cm] (0,-3) -- (0,3) coordinate (b); - \draw[help lines,xshift=-2.5cm-0.8pt] (0,-3) -- (0,3) coordinate (c); - - \coordinate (xline 1) at (0,1.5); - \coordinate (xline 2) at (0,2.8); - - \draw[|->|] (xline 1 -| a) -- node[above=2pt] {right extend} (xline 1 -| b); - \draw[|<-|] (xline 2 -| c) -- node[above=2pt] {left extend} (xline 2 -| a); - - \draw (0,0) -- (1,-1) node[below right] {origin}; - \end{tikzpicture} - - - The \meta{extend code} is normal \TeX\ code that is executed - whenever \pgfname\ wants to know how far the arrow tip will protrude - to the right and left. The code should call the following two - commands: \declare{|\pgfarrowsrightextend|} and - \declare{|\pgfarrowsleftextend|}. Both arguments take one argument - that specifies the size. Here is the final code for the |arc''| arrow - tip: -\begin{codeexample}[] -\pgfarrowsdeclare{arcs''}{arcs''} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} - \pgfarrowsrightextend{.5\pgflinewidth} -} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} - \pgfpatharc{180}{270}{4\arrowsize} - \pgfusepathqstroke - \pgfpathmoveto{\pgfpointorigin} - \pgfpatharc{90}{180}{4\arrowsize} - \pgfusepathqstroke -} -\begin{tikzpicture} - \draw[help lines] (-2,-1) grid (1,1); - \draw[line width=10pt,-arcs''] (-2,0) -- (0,0); - \draw[line width=2pt,white] (-2,0) -- (0,0); -\end{tikzpicture} + Thus, in our example we could simplify the convex hull to +\begin{codeexample}[code only] +\pgfarrowshullpoint{1cm}{0pt} +\pgfarrowsupperhullpoint{-3cm}{2cm} \end{codeexample} + If the \meta{y dimension} is zero or less, only one point, + namely $(\meta{x dimension},\meta{y dimension})$, is added to + the hull. Thus, we could also have used the upper convex hull + command in the first of the two of the above commands. + \end{command} + + \begin{command}{\pgfarrowssave\marg{macro}} + As explained earlier, the setup code needs to ``communicate'' + with the drawing code via ``saved values.'' This command get the + name of a macro and will store the value this macro had + internally. Then, each time drawing code is executed, the value + of this macro will be restored. + \end{command} + + \begin{command}{\pgfarrowssavethe\marg{register}} + Works like |\pgfarrowssave|, only the parameter must be a + register and |\the|\meta{register} will be saved. + Typically, you will write something like +\begin{codeexample}[code only] +\pgfarrowssavethe{\pgfarrowlength} +\pgfarrowssavethe{\pgfarrowwidth} +\end{codeexample} + To ensure that inside the drawing code the the dimension + registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with + the values they had during the setup. + \end{command} + + \item \declare{|drawing code|}|=|\marg{code} + + This code will be executed at least once for each setting of the + parameters when the time arrow tip is actually drawn. Usually, + this one execution will be all and the + low-level commands generated inside the \meta{code} will we stored + in a special cache; but in some cases the \meta{code} gets + executed each time the arrow tip is used, so do not assume + anything about it. Inside the \meta{code}, you have access to all + values that were saved in the setup code as well as to the line + width. + + The \meta{code} should draw the arrow tip ``going right along the + $x$-axis.'' \pgfname\ will take care of setting up a canvas + transformation beforehand to a rotation such that when the + drawing is rendered, the arrow tip that is actually drawn points + in the direction of the line. Alternatively, when bending is + switched on, even more complicated low-level transformations will + be done automatically. + + The are some special considerations concerning the \meta{code}: + \begin{itemize} + \item + In the \meta{code} you may \emph{not} use |\pgfusepath| + since this would try to add arrow tips to the arrow tip and lead + to a recursion. Use the ``quick'' versions |\pgfusepathqstroke| + and so on instead, which never try to add arrow tips. + \item + If you stroke the path that you construct, you should first set + the dashing to solid and set up fixed joins and caps, as + needed. This will ensure that the arrow tip will always look the + same. + \item + When the arrow tip code is executed, it is automatically put + inside a low-level scope, so nothing will ``leak out'' from the + scope. + \item + The high-level coordinate transformation matrix will be set to the + identity matrix when the code is executed for the first time. + \end{itemize} + + \item \declare{|cache|}|=|\meta{true or false} + + When set to |true|, which is the default, the \meta{code} will be + executed only once for a partiular value of parameters and the + low-level commands created by the drawing code (using the system + layer protocol subsystem, see Section~\ref{section-protocols}) + will be cached and reused later on. However, when the drawing code + contains ``uncachable'' code like a call to |\pgftext|, caching + must be switched off by saying |cache=false|. + + \item \declare{|bending mode|}|=|\meta{mode} + + This key is important only when the |bend| option is used with an + arrow, see Section~\ref{section-arrow-flex} for an introduction to + this option. The |bend| option asks us to, well, bend the arrow + head. For some arrow head this is not possible or leads to very + strange drawings (for instance, when the |\pgftext| command is + used) and then it is better to switch bending off for the arrow + head (|flex| will then be used instead). To achieve this, set + \meta{mode} to |none|. + + For most arrow tips it does, however, make sense to bend + them. There are (at least) two different mathematical ways of + doing so, see Section~\ref{section-library-curvilinear} for details. Which of + these ways is use can be configured by setting \meta{mode} to + either |orthogonal| or to |polar|. It is best to try simply try + out both when designing an arrow tip to see which works + better. Since |orthogonal| is quicker and often gives good oder + even better results, it is the default. Some arrow tips, however, + profit from saying |bending mode=polar|. + + \item \declare{|defaults|}|=|\meta{arrow keys} + + The \meta{arrow keys} allow you to configure the default values + for the parameters on which an arrow tip depends. The \meta{arrow + keys} will be executed first before any other arrow tip options + are executed, see Section~\ref{section-arrow-scopes} for the exact + sequence. Also see Section~\ref{section-arrow-options} below for + more details on arrow options. + \end{itemize} - \medskip - \textbf{Taking inner lines into account.} - In addition to the line width, there is another parameter that (may) - influence the way an arrow looks: The inner line width, which is the - line width of the second line that is stroked on top of a normal - line in order to create the effect of a ``double'' line. When this - line width changes, the arrow tip code is also reexecuted (and - cached), so your code may depend on the current value of the inner - line width. - - The following example shows how this works. The |implies| arrow - defined below has to setup the line width not for the ``main'' line - width, but for the main line width minus the inner line width, - divided by~2. + This concludes the description of the keys you provide for the + declaration of an arrow. Let us now have a look at a simple example + that uses these features: We want to define an arrow tip kind |foo| + that produces the arrow tip we used as our running examlpe. However, + to make things a bit more interesting, let us make it + ``configurable'' insofar as the length of the arrow tip can be + configured using the |length| option, which sets the + |\pgfarrowlength|. By default, this length should be the gigantic + 4cm we say in the example, but uses should be able to set it to + anything they like. We will not worry about the arrow width or + insets, of arrow line width, or harpoons, or anything else in this + example to keep it simple. + + Here is the code: \begin{codeexample}[code only] -\pgfarrowsdeclare{implies}{implies}{...} -{ - \pgfmathsetlength{\pgfutil@tempdimb}{.5\pgflinewidth-.5*\pgfinnerlinewidth}% - \pgfsetlinewidth{\pgfutil@tempdimb} - \pgfsetdash{}{0pt} - \pgfsetroundcap - \pgfsetroundjoin - \pgfmathsetlength{\pgfutil@tempdima}{.25\pgflinewidth+.25*\pgfinnerlinewidth}% - \pgfpathmoveto {\pgfpoint{-1.4\pgfutil@tempdima}{2.65\pgfutil@tempdima}} - \pgfpathcurveto{\pgfpoint{-0.75\pgfutil@tempdima}{1.25\pgfutil@tempdima}} - {\pgfpoint{1\pgfutil@tempdima}{0.05\pgfutil@tempdima}} - {\pgfpoint{2\pgfutil@tempdima}{0pt}} - \pgfpathcurveto{\pgfpoint{1\pgfutil@tempdima}{-0.05\pgfutil@tempdima}} - {\pgfpoint{-.75\pgfutil@tempdima}{-1.25\pgfutil@tempdima}} - {\pgfpoint{-1.4\pgfutil@tempdima}{-2.65\pgfutil@tempdima}} - \pgfusepathqstroke -} +\pgfdeclarearrow{ + name = foo, + parameters = { \the\pgfarrowlength }, + setup code = { + % The different end values: + \pgfarrowssettipend{.25\pgfarrowlength} + \pgfarrowssetlineend{-.25\pgfarrowlength} + \pgfarrowssetvisualbackend{-.5\pgfarrowlength} + \pgfarrowssetbackend{-.75\pgfarrowlength} + % The hull + \pgfarrowshullpoint{.25\pgfarrowlength}{0pt} + \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength} + \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength} + % Saves: Only the length: + \pgfarrowssavethe\pgfarrowlength + }, + drawing code = { + \pgfpathmoveto{.25\pgfarrowlength}{0pt} + \pgfpathlineto{-.75\pgfarrowlength}{.5\pgfarrowlength} + \pgfpathlineto{-.5\pgfarrowlength}{0pt} + \pgfpathlineto{-.75\pgfarrowlength}{-.5\pgfarrowlength} + \pgfpathclose + \pgfusepathqfill + }, + defaults = { length = 4cm } +} \end{codeexample} - Here is the effect for different combinations of line width and - inner line width: + We can now use it: +\pgfdeclarearrow{ + name = foo, + parameters = { \the\pgfarrowlength }, + setup code = { + % The different end values: + \pgfarrowssettipend{.25\pgfarrowlength} + \pgfarrowssetlineend{-.25\pgfarrowlength} + \pgfarrowssetvisualbackend{-.5\pgfarrowlength} + \pgfarrowssetbackend{-.75\pgfarrowlength} + % The hull + \pgfarrowshullpoint{.25\pgfarrowlength}{0pt} + \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength} + \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength} + % Saves: Only the length: + \pgfarrowssavethe\pgfarrowlength + }, + drawing code = { + \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}} + \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}} + \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}} + \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}} + \pgfpathclose + \pgfusepathqfill + }, + defaults = { length = 4cm } +} \begin{codeexample}[] -\begin{tikzpicture} - \foreach \linewidth in {2,2.4,...,4.4} - \foreach \innerlinewidth in {0.4,0.8,...,1.8} - { - \pgfsetlinewidth{\linewidth pt} - \pgfsetinnerlinewidth{\innerlinewidth pt} - \draw [-implies] (\innerlinewidth*50pt,\linewidth*40pt) -- ++(4mm,0); - } -\end{tikzpicture} +\tikz \draw [-foo] (0,0) -- (8,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0); \end{codeexample} \medskip - \textbf{Arrow options.} - You may wish to have further option influence the appearance of an - arrow tip. For instance, for a ``pointed'' arrow you may wish to set - the opening angle of the tip. Then, whenever this option changes - that arrow tip code also needs to be reexecuted, even though the - line width has stayed the same. - - You can use the commands |\pgfsetarrowoptions| and - |\pgfgetarrowoptions| to set such options for an arrow tip. Whenever - an arrow tip needs to be rendered, it is checked whether the arrow - tip code has already been executed for the current (expanded) value of the - options. If so, the cached code is used; otherwise the code is - executed once more. Naturally, inside the code the current value of - the arrow options should be taken into account. - - Arrow options can and must be specified individually for each arrow - type. - - In the following example, we make the arc angle an option. -\begin{codeexample}[] -\pgfarrowsdeclare{var arc}{var arc} % options is an angle -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} - \pgfarrowsrightextend{.5\pgflinewidth} -} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpointorigin} - \pgfpatharc{-90}{-180+\pgfgetarrowoptions{var arc}}{4\arrowsize} - \pgfusepathqstroke - \pgfpathmoveto{\pgfpointorigin} - \pgfpatharc{90}{180-\pgfgetarrowoptions{var arc}}{4\arrowsize} - \pgfusepathqstroke -} -\begin{tikzpicture} - \draw[help lines] (-2,-4) grid (1,4); - \foreach \option in {-60,-50,...,60} - { - \pgfsetarrowoptions{var arc}{\option} - \draw[ultra thick,-var arc] (-2,\option/15) -- (0,\option/15); - } -\end{tikzpicture} + \noindent\textbf{Defining a Shorthand.} + The |\pgfdeclarearrow| command can also used to define + \emph{shorthands}. This works as follows: + \begin{itemize} + \item First, you must provide a |name| just in the same way as when + you define a full-flung new arrow tip kind. + \item Second, instead of all of the other options listed above, you + just use one more option: + + \smallskip + \declare{|means|}|=|\meta{end arrow specification} + + This sets up things so that whenever \meta{name} is now used in an + arrow specification, it will be replaced by the \meta{end arrow + specification} (the problems resulting form the \meta{name} + begin used in a start arrow specification are taken care of + automatically). See also Section~\ref{section-arrow-tip-macro} for + details on the order in which options get executed in such cases. + + Note that the \meta{end arrow specification} will be executed + immediately to build the so-called arrow option caches, a concept + explored in more detail in + Section~\ref{section-arrow-option-cache}. In practice, this has + mainly two effects: First, all arrow tips referred to in the + specification must already exist (at least as ``dummy'' + versions). Second, all dimensions mentioned in options of the + \meta{end arrow specification} will be evaluated immediately. For + instance, when you write +\begin{codeexample}[code only] +\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] } \end{codeexample} + The value |2cm+\mydimen| is evaluated immediately. When |foo| is + used later on and |\mydimen| has changed, this has no effect. + \end{itemize} \end{command} -\pgfarrowsdeclare{arcs''}{arcs''} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfarrowsleftextend{-4\arrowsize-.5\pgflinewidth} - \pgfarrowsrightextend{.5\pgflinewidth} -} -{ - \arrowsize=0.2pt - \advance\arrowsize by .5\pgflinewidth - \pgfsetdash{}{0pt} % do not dash - \pgfsetroundjoin % fix join - \pgfsetroundcap % fix cap - \pgfpathmoveto{\pgfpoint{-4\arrowsize}{4\arrowsize}} - \pgfpatharc{180}{270}{4\arrowsize} - \pgfusepathqstroke - \pgfpathmoveto{\pgfpointorigin} - \pgfpatharc{90}{180}{4\arrowsize} - \pgfusepathqstroke -} - -\begin{command}{\pgfsetarrowoptions\marg{arrow tip}\marg{text}} - Sets the options for the \meta{arrow tip} to \meta{text}. The - default, before any call to this macro is made, is 0. -\end{command} -\begin{command}{\pgfgetarrowoptions\marg{arrow tip}} - This will expand to the current value of the options for the - \meta{arrow tip}. -\end{command} +\subsection{Handling Arrow Options} +\label{section-arrow-options} -\subsection{Declaring a Derived Arrow Tip Kind} +When you declare an arrow tip, your drawing code should take into +account the different arrow keys set for it (like the arrow tip length, +width, or harpooning). The different arrow keys that are available +have been described in detail in Section~\ref{section-arrow-config}; but +how do we access the values set by an option like |length| or +|harpoon| or |bend| in the drawing code? In the present section we +have a look at how this works. -It is possible to declare arrow kinds in terms of existing ones. For -these command to work correctly, the left and right extends must be -set correctly. -\begin{command}{\pgfarrowsdeclarealias\marg{start name}\marg{end - name}\marg{old start name}\marg{old end name}} - This command can be used to create an alias (another name) for an - existing arrow kind. +\subsubsection{Dimension Options} -\begin{codeexample}[] -\pgfarrowsdeclarealias{<}{>}{arcs''}{arcs''}% -\begin{tikzpicture} - \pgfsetarrows{<->} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} -\end{codeexample} -\end{command} +Most arrow keys, like |length| or |width'|, simple set a \TeX\ +dimension register to a certain value. For example, |length| sets the +value of the \TeX\ dimension register |\pgfarrowlength|. Note that +|length| takes several values as input with a complicated semantics as +explained for the |length| key on +page~\pageref{length-arrow-key}. All of these settings are not +important for the setup code: When it gets executed, the code behind +the |length| key will have computed a simple number that is stored +in |\pgfarrowlength|. Indeed, inside the setup code you do not have +access to the exact value given to the |length| key; just to the +final computed value. +The following \TeX\ dimensions are available to the setup code: -\begin{command}{\pgfarrowsdeclarereversed\marg{start name}\marg{end - name}\marg{old start name}\marg{old end name}} - This command creates a new arrow kind that is the ``reverse'' of an - existing arrow kind. The (automatically cerated) code of the new - arrow kind will contain a flip of the canvas and the meanings of the - left and right extend will be reversed. +\begin{itemize} +\item |\pgfarrowslength|. It gets set by the arrow keys |length| and |angle|. +\item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|. +\item |\pgfarrowsinset|. It gets set by |inset| and |inset'|. +\item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|. +\end{itemize} -\begin{codeexample}[] -\pgfarrowsdeclarereversed{arcs reversed}{arcs reversed}{arcs''}{arcs''}% -\begin{tikzpicture} - \pgfsetarrows{arcs reversed-arcs reversed} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} -\end{codeexample} -\end{command} +If your setup code depends on any of them, add them to the +|parameters| key of the arrow tip. +\subsubsection{True--False Options} -\begin{command}{\pgfarrowsdeclarecombine\opt{|*|}\opt{\oarg{offset}}\marg{start - name}\marg{end name}\marg{first start name}\marg{first end - name}\penalty0\marg{second start name}\marg{second end name}} - This command creates a new arrow kind that combines two existing - arrow kinds. The first arrow kind is the ``innermost'' arrow kind, - the second arrow kind is the ``outermost.'' +A number of arrow keys just do a yes/no switch, like |reversed|. All +of them setup a \TeX-if that you can access in the setup code: - The code for the combined arrow kind will install a canvas - translation before the innermost arrow kind in drawn. This - translation is calculated such that the right tip of the innermost - arrow touches the right end of the outermost arrow. The optional - \meta{offset} can be used to increase (or decrease) the distance - between the inner and outermost arrow. +\begin{itemize} +\item |\ifpgfarrowreversed| is setup by |reversed|. +\item |\ifpgfarrowswap| is setup by |swap| and also |right|. +\item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and |right|. +\item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set + to false by |line cap=butt|. It also gets (re)set by |round| and |sharp|. +\item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set + to false by |line join=miter|. It also gets (re)set by |round| and |sharp|. +\item |\ifpgfarrowopen| is set to true by |fill=none| and by |open| + (which is a shorthand for |fill=none|) and set to false by |color| + and all other |fill=|\meta{color}. +\end{itemize} -\begin{codeexample}[] -\pgfarrowsdeclarecombine[\pgflinewidth] - {combined}{combined}{arcs''}{arcs''}{latex}{latex}% -\begin{tikzpicture} - \pgfsetarrows{combined-combined} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} +If you code depends on any of these, you must add them to +the |parameters| in such a way that the parameters are different when +the \TeX-if is set from when it is not set. An easy way to achieve +this is to write something like +\begin{codeexample}[code only] + parameters = { \the\pgfarrowlength,..., + \ifpgfarrowharpoon h\fi\ + \ifpgfarrowroundjoin j\fi} \end{codeexample} +In other words, for each set parameter on which the arrow tip depends, +a specific letter is added to the parameters, making them unique. + +The first two of the above keys are a bit special: Reversing and swapping an +arrow tip can be done just by fiddling with the +transformation matrix: a reverse is a ``flip'' along the $y$-axis and +a swap is a flip along the $x$-axis. This is done automatically by +\pgfname. + +Nevertheless, you may wish to modify you code in dependence +especially of the |reverse| key: When |\ifpgfarrowreverse| is true, +\pgfname\ will flip the coordinate system along the $y$-axis, will +negate all end values (like line end, tip end, and so on) and will +exchange the meaning of back end and tip end as well as of visual back +end and visual back end. Usually, this is exactly what one need; +\emph{except} that the line end may no longer be appropriate. After +all, the line end should be chosen so that it is completely covered by +the arrow. Now, when the arrow tip is open, a reversed arrow should no +longer have the line end near the old visual back end, but near to the +old visual tip end. + +For these reasons, you may need to make the computation of the line +end dependent on whether the arrow is reversed or not. Note that when +you specify a different line end for a reversed arrow tip, the +transformation and inverting of the coordinate system will still be +done, meaning that if |reverse| is true, you need to specify a line +end in the ``old'' coordinate system that is at the position where, +after everything is inverted, it will be at the correct +position. Usually that means that if the |reverse| option is set, you +need to \emph{increase} the line end. + + +\subsubsection{Inaccessible Options} + +There are some options that influence the way an arrow tip looks, but +that you cannot access inside the setup code. Handling these options +lies entirely with \pgfname. If you wish your setup code to handle +these options, you have to setup your own ``parallel'' options. + +\begin{itemize} +\item |quick|, |flex|, |flex'|, and |bend| are all handled + automatically. You can, however, set the |bending mode| to avoid + bending of your arrow tip. +\item The colors set by |color| and |fill|. You can, however, access + them indirectly, namely through the current stroke and fill colors. +\item |sep| +\end{itemize} + + +\subsubsection{Defining New Arrow Keys} +\label{section-arrow-option-cache} + +The set of predefined options is already quite long and most arrow +tips will not need more than the predefined options. However, +sometimes an arrow tip may need to introduce a new special-purpose +option. For instance, suppose we wish to introcue a new fictive arrow +key |depth|. In such cases, you must do two things: - In the star variant, the end of the line is not in the outermost - arrow, but inside the innermost arrow. - -\begin{codeexample}[] -\pgfarrowsdeclarecombine*[\pgflinewidth] - {combined'}{combined'}{arcs''}{arcs''}{latex}{latex}% -\begin{tikzpicture} - \pgfsetarrows{combined'-combined'} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} +\begin{enumerate} +\item + Introduce a new dimension register or macro that will hold the + configuration value and which will be accessed by the setup + code. The could be achieved by saying +\begin{codeexample}[code only] +\newdimen\pgfarrowdepth \end{codeexample} -\end{command} - - -\begin{command}{\pgfarrowsdeclaredouble\opt{\oarg{offset}}\marg{start - name}\marg{end name}\marg{old start name}\marg{old end - name}} - This command is a shortcut for combining an arrow kind with itself. +\item + Introduce a new arrow key option |/pgf/arrow keys/depth| that allows + users to configure the new macro or register. +\end{enumerate} -\begin{codeexample}[] -\pgfarrowsdeclaredouble{<<}{>>}{arcs''}{arcs''}% -\begin{tikzpicture} - \pgfsetarrows{<<->>} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} +When an arrow is selected via for instance |foo[depth=5pt]|, the +key--value pairs between the square brackets are executed with the +path prefix |/pgf/arrow keys|. Thus, in the example, our depth key +would get executed. Thus, it is temping to write something like +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth/.code = \pgfmathsetlength{\pgfarrowdepth}{#1}} \end{codeexample} -\end{command} - - -\begin{command}{\pgfarrowsdeclaretriple\opt{\oarg{offset}}\marg{start - name}\marg{end name}\marg{old start name}\marg{old end - name}} - This command is a shortcut for combining an arrow kind with itself - and then again. -\begin{codeexample}[] -\pgfarrowsdeclaretriple{<<<}{>>>}{arcs''}{arcs''}% -\begin{tikzpicture} - \pgfsetarrows{<<<->>>} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} +Sadly, this will not work. The reason is that the is yet another level +of caching involved when \pgfname\ processes arrow tips: The option +cache! The problem is each time an arrow tip is used, even when the +drawing code of the arrow tip is nicely cached, we still need to +process the options in |foo[length=5pt]| to find out which version in +the cache we would like to access. To make matters worse, |foo| might +be a shorthand that calls other arrow tips, which add more options, +and so on. Unfortunately, executing keys is quite an expensive +operation (\pgfname's key--value parser is powerful, but that power +comes at a price). So, whenever possible, we do \emph{not} want the +key--value parser to be started. + +For these reasons, when something like |foo[|\meta{options}|]| is +encountered inside a shorthand, the \meta{options} are executed only +once. They should now setup the \emph{arrow option cache}, which is +some code that, when executed, should setup the values that the +\meta{options} configure. In our example, the |depth| key should add +something to the arrow option cache that sets |\pgfarrowdepth| to the +given value. + +Adding something to the arrow option cache is done using the following +command: + +\begin{command}{\pgfarrowsaddtooptions\marg{code}} + This command should be called by keys with the prefix + |/pgf/arrow keys| to add code to the arrow option cache. For our + |depth| key example, we could use this key as follows: +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth/.code= + \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}} +\end{codeexample} + Actually, this is still not optimal since the expensive + |\pgfmathsetlength| command is now called each time an arrow tip is + used with the |depth| option set. The trick is to do the expensive + operation only once and then store only very quick code in the arrow + option cache: +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy +\end{codeexample} + The above code will not (yet) work since |\somedimen| will surely + have a different value when the cache is executed. The trick is to + use some |\expandafter|s: +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen} \end{codeexample} \end{command} +\begin{command}{\pgfarrowsaddtolateoptions\marg{code}} + This command works like |\pgfarrowsaddtooptions|, only the + \meta{code} will be executed ``later'' than the code added by the + normal version of the command. This is useful for keys that depend + on the length of an arrow: Keys like |width'| want to define the + arrow width as a multiple of the arrow length, but when the |width'| + key is given, the length may not yet have been specified. By making + the computation of the width a ``late'' option, we ensure that + |\pgfarrowlength| will have been setup correctly. +\end{command} +If you define a new option that sets a dimensions and if that +dimension should change in accordance to the setting of either +|scale length| or |scale width|, you need to make \pgfname\ ``aware'' +of this using the following key: +\begin{command}{\pgfarrowsaddtolengthscalelist\marg{dimension register}} + Each time an arrow tip is used, the given \meta{dimension register} + will be multiplied by the |scale length| factor prior to the actual + drawing. You call this command only once in the preamble somewhere. +\end{command} - -\subsection{Using an Arrow Tip Kind} - -The following commands install the arrow kind that will be used when -stroking is done. - -\begin{command}{\pgfsetarrowsstart\marg{start arrow kind}} - Installs the given \meta{start arrow kind} for all subsequent - strokes in the in the current \TeX-group. If \meta{start arrow kind} - is empty, no arrow tips will be drawn at the start of the last - segment of paths. -\begin{codeexample}[] -\begin{tikzpicture} - \pgfsetarrowsstart{latex} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} -\end{codeexample} +\begin{command}{\pgfarrowsaddtowidthscalelist\marg{dimension register}} + Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters. \end{command} -\begin{command}{\pgfsetarrowsend\marg{start arrow kind}} - Like |\pgfsetarrowsstart|, only for the end of the arrow. + +\begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent + size specification}} + This command is useful for parsing the values given to keys like + |length| or |width| the expect a dimension followed optionally for + some numbers. This command converts the \meta{line-width dependent + size specification}, which may consist of one, two, or three + numbers, into a triple of three numbers in curly braces, which gets + stored in the macro |\pgfarrowstheparameters|. Here is an example, + where |\showvalueofmacro| is used in this example to show the value + stored in a macro: + \makeatletter + \def\showvalueofmacro#1{% + \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname} + } \begin{codeexample}[] -\begin{tikzpicture} - \pgfsetarrowsend{latex} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} +\pgfarrowsthreeparameters{2pt 1} +\showvalueofmacro\pgfarrowstheparameters \end{codeexample} \end{command} -\emph{Warning:} If the compatibility mode is active (which is the -default), there also exist old commands called |\pgfsetstartarrow| and -|\pgfsetendarrow|, which are incompatible with the meta-arrow -management. +\begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line + width factor}\marg{outer factor}} + This command take three parameters and does the ``line width + dependent computation'' described on page~\pageref{length-arrow-key} + for the |length| key. The result is returned in |\pgf@x|. -\begin{command}{\pgfsetarrows\texttt{\char`\{}\meta{start kind}|-|\meta{end kind}\texttt{\char`\}}} - Calls |\pgfsetarrowsstart| for \meta{start kind} and - |\pgfsetarrowsend| for \meta{end kind}. -\begin{codeexample}[] -\begin{tikzpicture} - \pgfsetarrows{latex-to} - \pgfsetlinewidth{1ex} - \pgfpathmoveto{\pgfpointorigin} - \pgfpathlineto{\pgfpoint{3.5cm}{2cm}} - \pgfusepath{stroke} - \useasboundingbox (-0.25,-0.25) rectangle (3.75,2.25); -\end{tikzpicture} + The idea is that you can setup line-width dependent keys like + |length| or |width| using code like the following: +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% +} \end{codeexample} \end{command} +\begin{command}{\pgfarrowslengthdependent\marg{dimension}\marg{length factor}\marg{dummy}} + This command take three parameters, of which the last one is + ignored, and does the ``length dependent computation'' described for + the |width'| and |inset'| keys. The result is returned in |\pgf@x|. -\subsection{Predefined Arrow Tip Kinds} - -\label{standard-arrows} - -The following arrow tip kinds are always defined: + You can setup length dependent keys using code like the following: +\begin{codeexample}[code only] +\pgfkeys{/pgf/arrow keys/depth'/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% +} +\end{codeexample} +\end{command} -{ -\bigskip -\catcode`\|=12 -\begin{tabular}{ll} - \sarrow{stealth}{stealth} \\ - \sarrow{stealth reversed}{stealth reversed} \\ - \sarrow{to}{to} \\ - \sarrow{to reversed}{to reversed} \\ - \sarrow{latex}{latex} \\ - \sarrow{latex reversed}{latex reversed} \\ - \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}% - \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}} - \texttt{|-|}& yields thick - \begin{tikzpicture}[arrows={|-|},thick] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); - \draw (0,0) -- (1,0); - \end{tikzpicture} and thin - \begin{tikzpicture}[arrows={|-|},thin] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); - \draw (0,0) -- (1,0); - \end{tikzpicture} -\end{tabular} -} - -For further arrow tips, see page~\pageref{section-library-arrows}. %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex index ea145e8fb06..92da9d37342 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex @@ -48,10 +48,9 @@ The workflow for using decorations is the following: \emph{to-be-decorated} path. \item You place the path construction commands inside the environment |{pgfdecoration}|. This environment takes the name of a previously - declared decoration as a parameter. It will then starting ``walking + declared decoration as a parameter. It will then start ``walking along'' the to-be-decorated path. As it does this, a special finite - automaton called a \emph{decoration automaton} produces as its - output new path construction commands (or even other outputs). These + automaton called a \emph{decoration automaton} produces new path commands as its output (or even other outputs). These outputs replace the to-be-decorated path; indeed, after the to-be-decorated path has been fully walked along it is thrown away, only the output of the automaton persists. @@ -80,7 +79,7 @@ automata are presented. \subsubsection{The Different Paths} -In order to prevent confusion with different types of path, such +In order to prevent confusion with different types of paths, such as those that are extended, those that are decorated and those that are created, the following conventions will be used: @@ -118,14 +117,14 @@ It is permissible that a decoration issues a |\pgfusepath| command. As usual, this causes the current path to be filled or stroked or some other action to be taken and the current path is set to the empty path. As described above, when the decoration -automaton starts the current path is the preexisting path and as the -automaton progresses, the current path is constantly being extend by -the output path. This means that first time e |\pgfusepath| command is +automaton starts, the current path is the preexisting path and as the +automaton progresses, the current path is constantly being extended by +the output path. This means that first time a |\pgfusepath| command is used on a decoration, the preexisting path is part of the path this command operates on; in subsequent calls only the part of the output path constructed since the last |\pgfusepath| command will be used. -You can use this mechanism to stroke or fill different part of the +You can use this mechanism to stroke or fill different parts of the output path in different colors, line widths, fills and shades; all within the same decoration. Alternatively, a decoration can choose to produce no output path at all: the |text| decoration simply typesets @@ -134,17 +133,17 @@ text along a path. \subsubsection{Segments and States} -The most common use a decoration is to ``repeat something along a +The most common use of a decoration is to ``repeat something along a path'' (for example, the |zigzag| decoration repeats \tikz\draw decorate[decoration=zigzag] {(0,0)--(\pgfdecorationsegmentlength,0)}; along a path). However, it -not necessarily the case that only one thing be repeated: a decoration +not necessarily the case that only one thing is repeated: a decoration can consist of different parts, or \emph{segments}, repeated in a particular order. When you declare a decoration, you provide a description of how their different segments will be rendered. The description of -each segment should be given in a way as if the ``x-axis'' of the +each segment should be given in a way as if the ``$x$-axis'' of the segment is the tangent to the path at a particular point, and that point is the origin of the segment. Thus, for example, the segment of the |zigzag| decoration might be @@ -157,10 +156,10 @@ defined using the following code: \pgfname\ will ensure that an appropriate coordinate transformation is in place when the segment is rendered such that -the segment actually points in the right direction. Also +the segment actually points in the right direction. Also, subsequent segments will be transformed such that they are ``further along the path'' toward the end of the path. -All transformations are setup automatically. +All transformations are set up automatically. Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the beginning of the segment code. Doing so would subdivide the path into @@ -182,7 +181,7 @@ Decorations use a mechanism known in theoretical in computer science as \emph{finite state automata} to describe which segment is used at a particular point. The idea is the following: For the first segment we start in a special \emph{state} called the \emph{initial state}. In -this state, and also in all other state later, \pgfname\ first +this state, and also in all other states later, \pgfname\ first computes how much space is left on the input path. That is, \pgfname\ keeps track of the distance to the end of the input path. Attached to each state there is a set of rules of the following form: ``If the remaining @@ -193,7 +192,7 @@ so, immediately switches to state~$q$. Only if none of the rules tell us to switch to another state, \pgfname\ will execute the state's code. This code will (typically) add a segment to the output path. In addition to the rules -there is also width parameter attached to each state. \pgfname\ then +there is also a width parameter attached to each state. \pgfname\ then translates the coordinate system by this width and reduces the remaining distance on the input path. Then, \pgfname\ either stays in the current state or switches to another state, depending on yet @@ -225,16 +224,16 @@ this command describes the decoration automaton. certain distance. This will also work if the path is not a straight line. That is, it is permissible that the path curves are veers at a sharp angle. It is also permissible that while traveling along the - input path the current input segment ends and a new input segment starts. In this + input path, the current input segment ends and a new input segment starts. In this case, the remaining distance on the first input segment is subtracted - from the \meta{dimension} and then we traveled along the second + from the \meta{dimension} and then we travel along the second input segment for the remaining distance. This input segment may also end early, in which case we travel along the next input segment, and so on. Note that it cannot happen that we travel past the end of the input path since this would have caused an immediate switch to the |final| state. - Note note that the computation of the path lengths has only a low + Note that the computation of the path lengths has only a low accuracy because of \TeX's small math capabilities. Do not expect high accuracy alignments when using decorations (unless the input path consists only of horizontal and vertical lines). @@ -251,15 +250,15 @@ this command describes the decoration automaton. happen: \begin{enumerate} \item - The \meta{options} are parsed. This may lead, see below, to a - state switch. When this happens, the following steps are not + The \meta{options} are parsed. This may lead to a + state switch, see below. When this happens, the following steps are not executed. The \meta{options} are executed one after the other in the given order. If an option causes a state switch, the switch is immediate, even if later options might cause a different state switch. \item The \meta{code} is executed in a \TeX-group with the current - transformation matrix setup in such a way that the origin is on + transformation matrix set up in such a way that the origin is on the input path at the current point (the point at the distance traveled up to now) and the coordinate system is rotated in such a way that the positive $x$-axis points in the direction of @@ -268,7 +267,7 @@ this command describes the decoration automaton. As described earlier, the \meta{code} can have two different effects: If it just contains path construction commands, the - decoration will produce an output path, which is extends the + decoration will produce an output path, that is, it extends the preexisting path. Here is an example: \begin{codeexample}[] @@ -295,7 +294,7 @@ this command describes the decoration automaton. \end{codeexample} Alternatively, the \meta{code} can also contain the - |\pgfusepath| command. This will use the path in usual manner, + |\pgfusepath| command. This will use the path in the usual manner, where ``the path'' is the preexisting path plus a part of the output path for the first invocation and the different parts of the rest of the output path for the following invocation. Here is @@ -332,13 +331,13 @@ this command describes the decoration automaton. The \meta{options} are executed with the key path set to |/pgf/decoration automaton|. The following keys are defined: - \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}} + \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}} When this key is encountered, \pgfname\ checks whether the remaining distance to the end of the input path is less than \meta{dimension}. If so, an immediate state switch to \meta{new state} occurs. \end{key} - \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}| to |\meta{new state}} + \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}} When this key is encountered, \pgfname\ checks whether the remaining distance to the end of the current input segment of the input path is less than \meta{dimension}. If so, an immediate @@ -395,7 +394,7 @@ this command describes the decoration automaton. operation. Otherwise, it is checked whether the current input segment is a closepath segment and whether the remaining distance on the current input segment is at most - \meta{distance}. If so, the a closepath operation is used to + \meta{distance}. If so, then a closepath operation is used to close the decorated path and the automaton continues with the next subpath, remaining in the current state. @@ -403,11 +402,11 @@ this command describes the decoration automaton. \end{key} \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}} - This key has the following effect: Firstly, the \TeX-if + This key has the following effect: Firstly, in case the \TeX-if |\ifpgfdecoratepathhascorners| is false, nothing happens. Otherwise, it is tested whether the remaining distance on the current input segment is at most \meta{dimension}. If so, - a lineto operation is used to reach the end of this input + a |lineto| operation is used to reach the end of this input segment and the automaton continues with the next input segment, but remains in the current state. @@ -421,10 +420,10 @@ this command describes the decoration automaton. next state. For this, the following two options are useful: \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}} - If the \meta{code} of state is executed, the \meta{precode} is - executed first and it executed outside the \TeX-group of the + If the \meta{code} of the state is executed, the \meta{precode} is + executed first and it is executed outside the \TeX-group of the \meta{code}. Note that when the \meta{precode} is executed, the - transformation matrix is not setup. + transformation matrix is not set up. \end{key} \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}} @@ -588,7 +587,7 @@ Once a decoration has been declared, it can be used. \item The decoration automata move along the input paths, thus creating (and possibly using) the output paths. These output paths extend - (unless they are used) the current path. + the current path (unless they are used). \end{enumerate} Some important points should be noted regarding the use of this @@ -597,18 +596,18 @@ Once a decoration has been declared, it can be used. \begin{itemize} \item If \meta{environment contents} does not begin with - |\pgfpathmoveto|, he last known point on the preexisting path is + |\pgfpathmoveto|, the last known point on the preexisting path is assumed as the starting point. \item All except the last of any sequence of consecutive move-to commands in \meta{environment contents} are discarded. \item - Any move-to commands at end of \meta{environment contents} are + Any move-to commands at the end of \meta{environment contents} are ignored. \item Any close-path commands on the input path are interpreted as straight lines. - Internally something a little more complicated is going on, + Internally, something a little more complicated is going on, however, a closed path on the input path has no effect on the output path, other than causing the automaton to travel in a straight line towards the location of the last move-to command on @@ -617,16 +616,16 @@ Once a decoration has been declared, it can be used. Although tangent computations for the input path work with the last point on the preexisting path, no automatic move-to operations are issued for the output path. - If an output path commences with a line-to or curve-to when the + If an output path starts with a line-to or curve-to when the existing path is empty, an appropriate move-to command should be - inserted before the decoration commences. + inserted before the decoration starts. \item If a decoration uses its own path, the first time this happens the preexisting path is part of the path that is used at this point. \end{itemize} - When the decoration automata ``work on'' their respective input - paths, before the automaton starts, \meta{before code} is +Before the automata start to "work on" their respective inputs paths, + \meta{before code} is executed. After the decoration automaton has finished, \meta{after code} is executed. @@ -733,7 +732,7 @@ Once a decoration has been declared, it can be used. \end{command} The following style is executed each time a decoration is used. You - may use it to setup default options for decorations. + may use it to set up default options for decorations. \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)} This style is executed for every decoration. \end{stylekey} @@ -822,8 +821,7 @@ multiple decorations. It is, in essence, an automaton that decorates an input path with decoration automatons. In general, however, the end effect is still that a path is decorated with other paths, and the input path should be thought of as being divided into sub-input-paths, each with -their own decoration. Like ordinary decorations, before a -meta-decoration can be used it must be declared. +their own decoration. Like ordinary decorations, a meta-decoration must be declared before it can be used. \subsubsection{Declaring Meta-Decorations} @@ -886,7 +884,7 @@ meta-decoration can be used it must be declared. \end{command} \begin{command}{\beforedecoration\marg{before code}} - Defines \marg{before code} as (typically) \pgfname{} commands to be + Defines \meta{before code} as (typically) \pgfname{} commands to be executed before the decoration is applied to the current segment. This command can be omitted. If you wish to set up some decoration specific parameters @@ -895,7 +893,7 @@ meta-decoration can be used it must be declared. \end{command} \begin{command}{\afterdecoration\marg{after code}} - Defines \marg{after code} as commands to be executed after the + Defines \meta{after code} as commands to be executed after the decoration has been applied to the current segment. This command can be omitted. \end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex index cb36ae4442a..63d6ebeacf7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-design.tex @@ -11,7 +11,7 @@ \section{Design Principles} This section describes the basic layer of \pgfname. This layer is -build on top of the system layer. Whereas the system layer just +built on top of the system layer. Whereas the system layer just provides the absolute minimum for drawing graphics, the basic layer provides numerous commands that make it possible to create sophisticated graphics easily and also quickly. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex index fc4606b0848..33792dd1a2f 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-external.tex @@ -107,7 +107,7 @@ As we see in Figure~\ref{fig1}, the world is flat. \end{figure} \end{codeexample} - Each graphic that is be externalized should have a unique name. Note + Each graphic to be externalized should have a unique name. Note that this name will be used as the name of a file in the file system, so it should not contain any funny characters. @@ -136,7 +136,7 @@ As we see in Figure~\ref{fig1}, the world is flat. the graphic file is included. \item The most complex behaviour arises when current the |\jobname| equals the \meta{file name prefix} and, furthermore, the - a \emph{real job name} has been declared. The behaviour for this + \emph{real job name} has been declared. The behaviour for this case is explained later. \end{enumerate} @@ -178,7 +178,7 @@ modify the |\jobname| appropriately. This is done in two steps: the graphic for which you need an external graphic to be generated. To set the |\jobname|, you use the |--jobname=| option of \TeX: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] bash> latex --jobname=survey-graphic1 survey.tex \end{codeexample} \end{enumerate} @@ -199,19 +199,19 @@ The following things will now happen: Note that, typically, \meta{everything} will contain just a single |{tikzpicture}| or |{pgfpicture}| environment. However, this need - not be the case, you use, say, a |{pspicture}| environment as + not be the case, you can use, say, a |{pspicture}| environment as \meta{everything} or even just some normal \TeX-text. \item At the |\endpgfgraphicnamed|, the box \emph{is} shipped out using the original |\shipout| command. Thus, unlike everything else, the contents of the graphic is made part of the output. \item When the box containing the graphic is shipped out, the paper - size is modified such that it exactly equal to the height and width + size is modified such that it is exactly equal to the height and width of the box. \end{enumerate} The net effect of everything described above is that the two commands -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] bash> latex --jobname=survey-graphic1 survey.tex bash> dvips survey-graphic1 \end{codeexample} @@ -222,7 +222,7 @@ page that contains exactly the graphic produced by the code between exactly the size of the graphic. If you use pdf\TeX, producing the graphic is even simpler: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] bash> pdflatex --jobname=survey-graphic1 survey.tex \end{codeexample} \noindent produces the single-page |pdf|-file |survey-graphic1.pdf|. @@ -360,7 +360,7 @@ external graphics. To create the external graphics, we run |pdflatex| twice, once for each graphic: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] bash> pdflatex --jobname=survey-f1 survey.tex This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) entering extended mode @@ -372,7 +372,7 @@ Output written on survey-f1.pdf (1 page, 1016 bytes). Transcript written on survey-f1.log. \end{codeexample} -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] bash> pdflatex --jobname=survey-f2 survey.tex This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) entering extended mode @@ -416,7 +416,9 @@ By comparison, in this figure we see a rectangle: \end{document} \end{codeexample} If we now run pdf\LaTeX, then, indeed, \pgfname\ is no longer needed: -\begin{codeexample}[code only] +% In the following, we switch off typesetting of listings because the +% parentheses confuse the pretty printer +\begin{codeexample}[code only,typeset listing/.code=#1] bash> pdflatex survey.tex This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6) entering extended mode diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex index 2267999f3df..79ff832a88d 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-images.tex @@ -100,7 +100,7 @@ option: inserted and a warning is printed. \item \declare{|interpolate=|\meta{true or false}} selects whether the - image should ``smoothed'' when zoomed. False by default. + image should be ``smoothed'' when zoomed. False by default. \item \declare{|mask=|\meta{mask name}} selects a transparency mask. The mask must previously be declared using |\pgfdeclaremask| (see @@ -118,7 +118,7 @@ option: \begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}} The \marg{existing image name} is ``cloned'' and the \marg{new image - name} can now be used whenever original image is used. This + name} can now be used whenever the original image is used. This command is useful for creating aliases for alternate extensions and for accessing the last image inserted using |\pgfimage|. @@ -135,7 +135,7 @@ option: If the macro |\pgfalternateextension| expands to some nonempty \meta{alternate extension}, \pgfname\ will first try to use the image - names \meta{image name}|.|\meta{alternate extension}. If this + named \meta{image name}|.|\meta{alternate extension}. If this image is not defined, \pgfname\ will next check whether \meta{alternate extension} contains a |!| character. If so, everything up to this exclamation mark and including it is deleted from \meta{alternate diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex index ec5d715f168..035e10b1edd 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-internalregisters.tex @@ -71,7 +71,7 @@ looking into the source code of |\pgfpointadd| to see which registers are used. \end{internallist} \begin{internallist}[openin handle]{\r@pgf@reada} - An |\openin| handle which is used to read files within locally scoped parts of \pgfname, for example to check if a file exists or to read data files. You should always use |\immediate| in front of output operations involving |\w@pgf@writea| and you should always close the file before returning from your code. + An |\openin| handle which is used to read files within locally scoped parts of \pgfname, for example to check if a file exists or to read data files. You should always use |\immediate| in front of output operations involving |\r@pgf@writea| and you should always close the file before returning from your code. \begin{codeexample}[code only] \immediate\openin\r@pgf@reada=myfile.dat % do something with \macro diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex index 3563d91db33..0f1c9e1eb02 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-layers.tex @@ -15,7 +15,7 @@ \subsection{Overview} \pgfname\ provides a layering mechanism for composing graphics from -multiple layers. (This mechanism is not be confused with the +multiple layers. (This mechanism is not to be confused with the conceptual ``software layers'' the \pgfname\ system is composed of.) Layers are often used in graphic programs. The idea is that you can draw on the different layers in any order. So you might start drawing @@ -53,7 +53,7 @@ layer. You can declare a new layer using the following command: \begin{command}{\pgfdeclarelayer\marg{name}} This command declares a layer named \meta{name} for later - use. Mainly, this will setup some internal bookkeeping. + use. Mainly, this will set up some internal bookkeeping. \end{command} The next step toward using a layer is to tell \pgfname\ which layers @@ -62,8 +62,7 @@ ordering. Thus, it is possible to have more layers declared than are actually used. \begin{command}{\pgfsetlayers\marg{layer list}} - This command, which should be used \emph{outside} a |{pgfpicture}| - environment, tells \pgfname\ which layers will be used in + This command tells \pgfname\ which layers will be used in pictures. They are stacked on top of each other in the order given. The layer |main| should always be part of the list. Here is an example: @@ -72,6 +71,9 @@ actually used. \pgfdeclarelayer{foreground} \pgfsetlayers{background,main,foreground} \end{codeexample} + + This command should be given either outside of any picture or ``directly inside'' of a picture. + Here, the ``directly inside'' means that there should be no further level of \TeX\ grouping between |\pgfsetlayers| and the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}| (with similar restrictions). \end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex index d77f1312123..ca17510a797 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-matrices.tex @@ -25,15 +25,15 @@ options very similar to the |\pgfnode| command. In the following, the basic idea behind the alignment mechanism is explained first. Then the command |\pgfmatrix| is explained. At the -end of the section additional ways of modifying the width of columns -and rows is discussed. +end of the section, additional ways of modifying the width of columns +and rows are discussed. \subsection{Cell Pictures and Their Alignment} A matrix consists of rows of \emph{cells}. Cells are separated using the special command |\pgfmatrixnextcell|, rows are ended using the -command |\pgfmatrixendrow| (the command |\\| is setup to mean the same +command |\pgfmatrixendrow| (the command |\\| is set up to mean the same as |\pgfmatrixendrow| by default). Each cell contains a \emph{cell picture}, although cell pictures are not complete pictures as they lack layers. However, each cell picture has its own bounding box like a @@ -41,7 +41,7 @@ normal picture does. These bounding boxes are important for the alignment as explained in the following. Each cell picture will have an origin somewhere in the picture (or -even outside the picture). The position of these origins is important +even outside the picture). The position of these origins are important for the alignment: On each row the origins will be on the same horizontal line and for each column the origins will also be on the same vertical line. These two requirements mean that the cell pictures @@ -93,7 +93,7 @@ All matrices are typeset using the following command: The resulting matrix is used as the |text| box of the node. As for a normal node, the \meta{usage} commands are applied, so that the - path(s) of the resulting node are stroked or filled or whatever. + path(s) of the resulting node is (are) stroked or filled or whatever. \medskip \textbf{Specifying the cells and rows.\ } @@ -108,7 +108,7 @@ All matrices are typeset using the following command: to |\pgfmatrixnextcell|. This way, it will ``look'' as if |&| is used. \item Rows are ended using the command |\pgfmatrixendrow|, but |\\| - is setup to mean the same by default. However, some environments + is set up to mean the same by default. However, some environments like |{minipage}| redefine |\\|, so it is good to have |\pgfmatrixendrow| as a ``fallback.'' \item Every row \emph{including the last row} must be ended using @@ -232,10 +232,10 @@ commands for the column spacing. been started, subsequent uses of this optional argument for the column have no effect. - To determine the space between the two columns the are separated by + To determine the space between the two columns that are separated by |\pgfmatrixnextcell|, the following algorithm is executed: \begin{enumerate} - \item Both the default separation list (as setup by + \item Both the default separation list (as set up by |\pgfsetmatrixcolumnsep|) and the \meta{additional sep list} are processed, in this order. If the \meta{additional sep list} argument is missing, only the default separation list is @@ -244,7 +244,7 @@ commands for the column spacing. well as occurrences of the keywords |between origins| and |between borders|. \item All dimensions occurring in either list are added together to - arrive at an dimension $d$. + arrive at a dimension $d$. \item The last occurrence of either of the keywords is located. If neither keyword is present, we proceed as if |between borders| were present. @@ -260,7 +260,7 @@ commands for the column spacing. \item For the |between origins| mode, the spacing between the two columns is computed differently: Recall that the origins of the cell pictures in both pictures lie on two vertical lines. The - spacing between the two columns is setup such that the horizontal + spacing between the two columns is set up such that the horizontal distance between these two lines is exactly $d$. This mode may only be used between columns \emph{already @@ -268,9 +268,9 @@ commands for the column spacing. \end{itemize} All of the above rules boil down to the following effects: \begin{itemize} - \item A default spacing between columns should be setup using + \item A default spacing between columns should be set up using |\pgfsetmatrixcolumnsep|. For example, you might say - |\pgfsetmatrixcolumnsep{5pt}| to have columns be spaced apart by + |\pgfsetmatrixcolumnsep{5pt}| to have columns spaced apart by |5pt|. You could say \begin{verbatim} \pgfsetmatrixcolumnsep{1cm,between origins} @@ -355,7 +355,7 @@ commands are called differently. way as for columns. For the last row the optional argument has no effect. - Inside matrices (and only there) the command |\\| is setup to mean + Inside matrices (and only there) the command |\\| is set up to mean the same as this command. \end{command} @@ -422,7 +422,7 @@ current column in a callback: \begin{command}{\pgfmatrixcurrentrow} This counter stores the current row of the current cell of the - matrix. Do not even think of changing this counter. + matrix. Do not even think about changing this counter. \end{command} \begin{command}{\pgfmatrixcurrentcolumn} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex index 5df4c13b6bb..c40d308b3f4 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex @@ -38,7 +38,7 @@ path is stroked or filled. \subsubsection{Creating and Referencing Nodes} You create a node by calling the macro |\pgfnode| or the more general -|\pgfmultipartnode|. These macro takes several parameters and draws +|\pgfmultipartnode|. This macro takes several parameters and draws the requested shape at a certain position. In addition, it will ``remember'' the node's position within the current |{pgfpicture}|. You can then, later on, refer to the @@ -46,7 +46,7 @@ node's position. Coordinate transformations are ``fully supported,'' which means that if you used coordinate transformations to shift or rotate the shape of a node, the node's position will still be correctly determined by \pgfname. This is \emph{not} the case if you use canvas -transformations, instead. +transformations instead. \subsubsection{Anchors} @@ -81,7 +81,7 @@ The simplest shape, the |coordinate|, has just one anchor, namely the shapes like the |rectangle| shape also have a \emph{background path}. This is a \pgfname-path that is defined by the shape. The shape does not prescribe what should happen with the path: When a node -is created this path may be stroked (resulting in a frame around the +is created, this path may be stroked (resulting in a frame around the label), filled (resulting in a background color for the text), or just discarded. @@ -91,12 +91,12 @@ text, when a shape is drawn, up to seven different layers are drawn: \begin{enumerate} \item The ``behind the background layer.'' Unlike the background path, - which be used in different ways by different nodes, the graphic + which can be used in different ways by different nodes, the graphic commands given for this layer will always stroke or always fill the path they construct. They might also insert some text that is ``behind everything.'' \item - The background path layer. How this path is used depends on how the + The background path layer. How this path is used depends on the arguments of the |\pgfnode| command. \item The ``before the background path layer.'' This layer works like the @@ -111,7 +111,7 @@ text, when a shape is drawn, up to seven different layers are drawn: executed.'' \item The foreground path layer. This path is treated in the same way as the - background path, only it is drawn only after the label text has been + background path, only it is drawn after the label text has been drawn. \item The ``before the foreground layer.'' @@ -142,8 +142,8 @@ multipart nodes: They only have one part named |text|. When a shape is declared, you must specify the node parts. There is a simple command called |\nodeparts| that takes a list of the part names as input. When you create a node of a multipart shape, for each part -of the node you must have setup a \TeX-box containing the text of the -part. For a part named |XYZ| you must setup the box +of the node you must have set up a \TeX-box containing the text of the +part. For a part named |XYZ| you must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor |XYZ|. See the description of |\pgfmultipartnode| for more details. @@ -225,9 +225,9 @@ the description of |\pgfmultipartnode| for more details. shapes), this command can also be used with multi-part nodes. When this command is called, for each node part of the node you must - have setup one \TeX-box. Suppose the shape has two parts: The |text| + have set up one \TeX-box. Suppose the shape has two parts: The |text| part and the |lower| part. Then, prior to calling - |\pgfmultipartnode|, you must have setup the boxes + |\pgfmultipartnode|, you must have set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These boxes may contain any \TeX-text. The shape code will then compute the positions of the shape's anchors based on the sizes of the these @@ -253,7 +253,7 @@ the description of |\pgfmultipartnode| for more details. part name. Although you need a different box for each part of a single shape, two different shapes may very well use the same box even when the names of the parts are different. Suppose you have a - |circle split| shape that has an |lower| part and you have a + |circle split| shape that has a |lower| part and you have a |uml class| shape that has a |methods| part. Then, in order to avoid exhausting \TeX's limited number of box registers, you can say \begin{codeexample}[code only] @@ -389,11 +389,12 @@ node. These values are stored in the following keys. \subsubsection{Deferred Node Positioning} +\label{section-shapes-deferred-node-positioning} Normally, when a node is created using a command like |\pgfnode|, the node is immediately inserted into the current picture. In particular, you have no chance to change the position of a created node after it -has been create. Using |\pgfpositionnodelater| in concert with +has been created. Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can create a node whose position is determined only at some later time. @@ -406,7 +407,7 @@ determined only at some later time. node is not relevant for the picture's bounding box, but a bounding box for the node is computed and stored in the macros |\pgfpositionnodelaterminx| to |\pgfpositionnodelatermaxy|. Then, - the \meta{macro name} is called with the following macros setup: + the \meta{macro name} is called with the following macros set up: \begin{command}{\pgfpositionnodelaterbox} A box register number (|0| currently) that stores the node's paths @@ -416,9 +417,9 @@ determined only at some later time. \begin{command}{\pgfpositionnodelatername} The name of the just-created-node. This name will be the - originally "desired" name of the box plus the fixed prefix - |not yet positioned@|. The idea is to ensure that the original - name is not inadvertently used before the node is actually + originally ``desired'' name of the box plus the fixed prefix + |not yet positionedPGFINTERNAL|. The idea is to ensure that the + original name is not inadvertently used before the node is actually positioned. When |\pgfpositionnodenow| is called, it will change the name to the original name. \end{command} @@ -426,7 +427,8 @@ determined only at some later time. \begin{command}{\pgfpositionnodelaterminx} The minimal $x$-position of a bounding box of the node. This bounding box refers to the node when it is positioned with the - anchor at the origin. + anchor at the origin. It is guaranteed, that this macro will + contain a dimension in the format \meta{number}|pt|. \end{command} \begin{command}{\pgfpositionnodelaterminy} \end{command} @@ -443,6 +445,17 @@ determined only at some later time. above macros are local to a scope that ends right after the call to \meta{macro name}, so it is your job to copy the values to safety inside \meta{macro name}. + + The following two macros will also be set inside the call to + \meta{macro name}, but they are only ``informative'' in the sense + that you need \emph{not} restore these macros when + |\pgfpositionnodenow| is called. + + \begin{command}{\pgfpositionnodelaterpath} + This macro stores the path of the background of the node. See + Section~\ref{section-soft-paths} for an overview of how these + paths are encode. + \end{command} By setting \meta{macro name} to |\relax| (which is the default), you can switch off the whole mechanism. When a picture is interrupted, @@ -452,12 +465,13 @@ determined only at some later time. \begin{command}{\pgfpositionnodenow\marg{coordinate}} This command is used to position a node that has previously been - created with |\pgfpositionnodelater|. When |\pgfpositionnodenow| is + created using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is called, the macros and boxes mentioned in the description of |\pgfpositionnodenow| must be set to the value they had when the \meta{macro name} was called. Provided this is the case, this command will insert the box into the current picture, shifted by - \meta{coordinate}. Subsequently, you can refer to the node with its + \meta{coordinate}. Then, the late code (see below) + is called. Subsequently, you can refer to the node with its original name as if it had just been created. \begin{codeexample}[] @@ -493,6 +507,22 @@ determined only at some later time. \end{command} +\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}} + When you call this macro inside a scope for which the + |\pgfpositionnodelater| has been called, the \meta{code} will be + stored internally. Later, when the node named \meta{node name} is + actually positioned using |\pgfpositionnodenow|, the \meta{code} + will be executed. When this macro is called multiple times with the + same \meta{node name}, the \meta{code} accumulates. However, When + |\pgfpositionnodenow| is called, the code stored for the node is + cleared. + + The main purpose of this mechanism is to allow \tikzname\ to store + so-called ``late options'' with a node that will be positioned only + later. +\end{command} + + \subsection{Using Anchors} Each shape defines a set of anchors. We saw already that the anchors @@ -568,9 +598,9 @@ following commands: A special situation arises when the \meta{node} lies in a picture different from the current picture. In this case, if you have not told \pgfname\ that the picture should be ``remembered,'' the - \meta{node} will be treated as if it lied in the current + \meta{node} will be treated as if it lay in the current picture. For example, if the \meta{node} was at position $(3,2)$ in - the original picture, it is treated as if it lied at position + the original picture, it is treated as if it lay at position $(3,2)$ in the current picture. However, if you have told \pgfname\ to remember the picture position of the node's picture and also of the current picture, @@ -625,7 +655,7 @@ not-so-easy. Because of this, \pgfname\ does not do so automatically. Rather, you have to proceed as follows: \begin{enumerate} \item You have to use a backend driver that supports position - tracking. pdf\TeX\ is one such drivers, |dvips| currently is not. + tracking. pdf\TeX\ is one such driver, |dvips| currently is not. \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere before or inside every picture \begin{itemize} @@ -670,6 +700,12 @@ should not attempt to redefine. bounding box of the current path. \end{predefinednode} +\begin{predefinednode}{current subpath start} + This node is of shape |coordinate| and is at the beginning of the + current subpath. This is the position of the last move-to + operation. +\end{predefinednode} + \begin{predefinednode}{current page} This node is inside a virtual remembered picture. The size of this node is the size of the current page. This means that if you create @@ -769,7 +805,7 @@ In order to define a new shape, you must provide: \subsubsection{Normal Anchors Versus Saved Anchors} -Anchors are special places in shape. For example, the |north east| +Anchors are special places in a shape. For example, the |north east| anchor, which is a normal anchor, lies at the upper right corner of the |rectangle| shape, as does |\northeast|, which is a saved anchor. The difference is the following: \emph{saved anchors are @@ -782,7 +818,7 @@ The idea behind all this is that a shape can declare a very large number of normal anchors, but when a node of this shape is created, these anchors are not actually computed. However, this causes a problem: When we wish to reference an anchor of a node at some later -time, we must still able to compute the position of the anchor. For +time, we must still be able to compute the position of the anchor. For this, we may need a lot of information: What was the transformation matrix that was in force when the node was created? What was the size of the text box? What were the values of the different separation @@ -791,7 +827,7 @@ dimensions? And so on. To solve this problem, \pgfname\ will always compute the locations of all \emph{saved anchors} and store these positions. Then, when an normal anchor position is requested later on, the anchor position can -be given just from knowing where the locations of the saved anchors. +be given just from knowing where the locations of the saved anchors are. As an example, consider the |rectangle| shape. For this shape two anchors are saved: The |\northeast| corner and the |\southwest| @@ -856,13 +892,13 @@ The following command declares a new shape: By default, a shape has just one node part called |text|. However, there can be several node parts. For example, the |circle split| shape has two parts: the |text| part, which - shows that upper text, and a |lower| part, which shows the + shows that the upper text, and a |lower| part, which shows the lower text. For the |circle split| shape the |\nodeparts| command was called with the argument |{text,lower}|. When a multipart node is created, the text labels are drawn in the sequences listed in the \meta{list of node parts}. For each node - part there you must have declared one anchor and the \TeX-box of + part, you must have declared one anchor and the \TeX-box of the part is placed at this anchor. For a node part called |XYZ| the \TeX-box |\pgfnodepartXYZbox| is placed at anchor |XYZ|. \end{command} @@ -877,7 +913,7 @@ The following command declares a new shape: is executed, the \TeX-boxes of the node parts will contain the text labels of the node. Possibly, these box are void. For example, if there is just a |text| part, the node - |\pgfnodeparttextbox| will be setup when the \meta{code} is + |\pgfnodeparttextbox| will be set up when the \meta{code} is executed. The \meta{code} can use the width, height, and depth of the @@ -1029,9 +1065,9 @@ The following command declares a new shape: creation is applied automatically to the coordinates returned by the anchor's \meta{code}. - Out |simple rectangle| only has one text label (node - part) called |text|. This is the default situation, so we need not - do anything. For the |text| node part we must setup a |text| + Our |simple rectangle| only has one text label (node + part) called |text|. This is the default situation, so we do not need to + do anything. For the |text| node part we must set up a |text| anchor. This anchor is used upon creation of a node to determine the lower left corner of the text label (within the private coordinate system of the shape). By default, the |text| anchor is @@ -1095,12 +1131,12 @@ The following command declares a new shape: shape. What exactly is considered as the ``border'' of the shape depends on the shape. - When the user request a point on the border of the shape using the + When the user requests a point on the border of the shape using the |\pgfpointshapeborder| command, the \meta{code} will be executed to discern this point. When the execution of the \meta{code} starts, the dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$ in the shape's coordinate system. It is now the job of - the \meta{code} to setup |\pgf@x| and |\pgf@y| such that they + the \meta{code} to set up |\pgf@x| and |\pgf@y| such that they specify the point on the shape's border that lies on a straight line from the shape's center to the point $p$. Usually, this is a somewhat complicated computation, involving many case distinctions @@ -1255,7 +1291,7 @@ The following command declares a new shape: }\hskip-1.2cm \begin{tikzpicture} \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; - \node[fill=examplefill,draw,ellipse,double] + \node[fill=yellow!80!black,draw,ellipse,double] at ([shift=(-80:3cm)]x) (y) {Use Case}; \draw[dashed] (x) -- (y); diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex index 5284f22bb36..eacaa4b84e8 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex @@ -16,7 +16,7 @@ The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A path consists of several parts, each of which is either a closed or open curve. An open curve has a starting point and an end point and, in between, consists of several \emph{segments}, each of which is -either a straight line or a Bézier curve. Here is an example of a +either a straight line or a B\'ezier curve. Here is an example of a path (in red) consisting of two parts, one open, one closed: \begin{codeexample}[] @@ -58,7 +58,7 @@ Section~\ref{section-bb} for more details. Each path construction command extends the current path in some way. The ``current path'' is a global entity that persists across \TeX\ groups. Thus, between calls to the path construction commands -you can perform arbitrary computations and even open and closed \TeX\ +you can perform arbitrary computations and even open and close \TeX\ groups. The current path only gets ``flushed'' when the |\pgfusepath| command is called (or when the soft-path subsystem is used directly, see Section~\ref{section-soft-paths}). @@ -83,7 +83,7 @@ can also be used to start a new part of a path. \pgfpathlineto{\pgfpoint{2cm}{1cm}} \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} \pgfpathlineto{\pgfpoint{3cm}{0cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} @@ -95,14 +95,14 @@ can also be used to start a new part of a path. \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} \pgfpathlineto{\pgfpoint{3cm}{0cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} The command will apply the current coordinate transformation matrix to \meta{coordinate} before using it. - The command will update the bounding box of the current path and + It will update the bounding box of the current path and picture, if necessary. \end{command} @@ -121,14 +121,14 @@ can also be used to start a new part of a path. \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{1cm}} \pgfpathlineto{\pgfpoint{2cm}{1cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} The command will apply the current coordinate transformation matrix to \meta{coordinate} before using it. - The command will update the bounding box of the current path and + It will update the bounding box of the current path and picture, if necessary. \end{command} @@ -136,10 +136,10 @@ can also be used to start a new part of a path. \subsection{The Curve-To Path Operations} \begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}} - This command extends the current path with a Bézier curve from the + This command extends the current path with a B\'ezier curve from the last point of the path to \meta{coordinate}. The \meta{support 1} and \meta{support 2} are the first and second support point of the - Bézier curve. For more information on Bézier curve, please consult a + B\'ezier curve. For more information on B\'ezier curves, please consult a standard textbook on computer graphics. Like the line-to command, this command may not be the first path @@ -149,14 +149,14 @@ can also be used to start a new part of a path. \pgfpathmoveto{\pgfpointorigin} \pgfpathcurveto {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} The command will apply the current coordinate transformation matrix to \meta{coordinate} before using it. - The command will update the bounding box of the current path and + It will update the bounding box of the current path and picture, if necessary. However, the bounding box is simply made large enough such that it encompasses all of the support points and the \meta{coordinate}. This will guarantee that the curve is @@ -168,14 +168,14 @@ can also be used to start a new part of a path. \begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}} This command works like |\pgfpathcurveto|, only it uses a quadratic - Bézier curve rather than a cubic one. This means that only one + B\'ezier curve rather than a cubic one. This means that only one support point is needed. \begin{codeexample}[] \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfpathquadraticcurveto {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} @@ -189,7 +189,7 @@ can also be used to start a new part of a path. \end{command} -There exist two commands to draw only part of a cubic Bézier curve: +There exist two commands to draw only part of a cubic B\'ezier curve: \begin{command}{\pgfpathcurvebetweentime\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}} @@ -257,7 +257,7 @@ circles to a path are described. \begin{command}{\pgfpatharc\marg{start angle}\marg{end angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}} This command appends a part of a circle (or an ellipse) to the current - path. Imaging the curve between \meta{start angle} and \meta{end + path. Imagine the curve between \meta{start angle} and \meta{end angle} on a circle of radius \meta{radius} (if $\meta{start angle} < \meta{end angle}$, the curve goes around the circle counterclockwise, otherwise clockwise). This curve is now moved such @@ -398,7 +398,7 @@ circles to a path are described. are numerically very unstable. In particular, the arc will not always really end at the \meta{target coordinate}, but may be off by up to several points. A more precise positioning is currently - infeasible due to \TeX's numerical weaknesses. The only case that + infeasible due to \TeX's numerical weaknesses. The only case it works quite nicely is when the resulting angle is a multiple of~$90^\circ$. \end{command} @@ -406,7 +406,7 @@ circles to a path are described. \begin{command}{\pgfpatharctoprecomputed\marg{center point}\marg{start angle}\marg{end angle}\marg{end point}\\\marg{x-radius}\marg{y-radius}\marg{ratio x-radius/y-radius}\marg{ratio y-radius/x-radius}} A specialized arc operation which is fast and numerically stable, provided a lot of information is given in advance. - In contrast to |\pgfpatharc|, it explicitly interpolates start- and end points. + In contrast to |\pgfpatharc|, it explicitly interpolates start and end points. In contrast to |\pgfpatharcto|, this routine is numerically stable and quite fast since it relies on a lot of available information. \begin{codeexample}[] @@ -438,8 +438,9 @@ circles to a path are described. \end{codeexample} \begin{command}{\pgfpatharctomaxstepsize} - The quality of arc approximation taken by |\pgfpatharctoprecomputed| by means of Bezier splines is % TODOsp: Bezier --> Bézier? - controlled by a mesh width, which is initially + The quality of arc approximation taken by + |\pgfpatharctoprecomputed| by means of B\'ezier splines is + controlled by a mesh width, which is initially |\def\pgfpatharctoprecomputed{45}|. @@ -539,15 +540,15 @@ start a new part of the path. \subsection{The Grid Path Operation} -\begin{command}{\pgfpathgrid\oarg{options}\marg{lower left}\marg{upper right}} +\begin{command}{\pgfpathgrid\oarg{options}\marg{first corner}\marg{second corner}} Appends a grid to the current path. That is, a (possibly large) number of parts are added to the path, each part consisting of a single horizontal or vertical straight line segment. Conceptually, the origin is part of the grid and the grid is clipped - to the rectangle specified by the \meta{lower left} and - the \meta{upper right} corner. However, no clipping occurs (this - command just adds parts to the current path). Rather, the points + to the rectangle specified by the \meta{first corner} and + the \meta{second corner}. However, no clipping occurs (this + command just adds parts to the current path) and the points where the lines enter and leave the ``clipping area'' are computed and used to add simple lines to the current path. @@ -575,7 +576,7 @@ start a new part of the path. \end{pgfpicture} \end{codeexample} The command will apply coordinate transformations and update the - bounding boxes tightly. As for ellipses, the transformations are + bounding boxes. As for ellipses, the transformations are applied to the ``conceptually finished'' grid. \begin{codeexample}[] \begin{pgfpicture} @@ -592,14 +593,14 @@ start a new part of the path. \begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}} This command appends two half-parabolas to the current path. The first starts at the current point and ends at the current point plus - \meta{bend vector}. At his point, it has its bend. The second half - parabola starts at that bend point and end at point that is given by + \meta{bend vector}. At this point, it has its bend. The second half + parabola starts at that bend point and ends at point that is given by the bend plus \meta{end vector}. If you set \meta{end vector} to the null vector, you append only a half parabola that goes from the current point to the bend; by setting \meta{bend vector} to the null vector, you append only a - half parabola that goes to current point plus \meta{end vector} and + half parabola that goes through the current point and \meta{end vector} and has its bend at the current point. It is not possible to use this command to draw a part of a parabola @@ -672,7 +673,7 @@ cosine curves in intervals that are multiples of $\pi/2$. \pgfpathcosine{\pgfpoint{1cm}{-1cm}} \pgfpathsine{\pgfpoint{1cm}{-1cm}} \pgfpathcosine{\pgfpoint{1cm}{1cm}} - \pgfsetfillcolor{examplefill} + \pgfsetfillcolor{yellow!80!black} \pgfusepath{fill,stroke} \end{pgfpicture} \end{codeexample} @@ -693,7 +694,7 @@ documented in Section~\ref{section-plots}. \subsection{Rounded Corners} Normally, when you connect two straight line segments or when you -connect two curves that end and start ``at different angles'' you get +connect two curves that end and start ``at different angles,'' you get ``sharp corners'' between the lines or curves. In some cases it is desirable to produce ``rounded corners'' instead. Thus, the lines or curves should be shortened a bit and then connected by arcs. @@ -841,7 +842,7 @@ are (globally) updated. To facilitate this, you can use the following command: \begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}} - Updates all of the above dimension in such a way that the point + Updates all of the above dimensions in such a way that the point specified by the two arguments is inside both bounding boxes. For the picture's bounding box this updating occurs only if |\ifpgf@relevantforpicturesize| is true, see below. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex index cfb74f5b51b..6837464fccd 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex @@ -15,7 +15,7 @@ \subsection{Overview} There are many ways of filling a path. First, you can fill it using a -solid color and this is also the fasted method. Second, you can also +solid color and this is also the fastest method. Second, you can also fill it using a shading, which means that the color changes smoothly between two (or more) different colors. Third, you can fill it using a tiling pattern and it is explained in the following how this is done. @@ -58,13 +58,12 @@ internally, a new (fixed) instance of a pattern is declared when the parameters of a pattern change. Second, the phase of patterns is not well-defined, that is, it is not -clear where origin of the ``first'' tile is. To be more precise, +clear where the origin of the ``first'' tile is. To be more precise, PostScript and \textsc{pdf} on the one hand and \textsc{svg} on the other hand define the origin differently. PostScript and \textsc{pdf} define a fixed origin that is independent of where the path lies. This has the highly desirable effect that if you use the same pattern to -fill multiple paths, this has the same effect as if you used the -pattern to will a single path that is the union of all the paths. By +fill multiple paths, the outcome is the same as if you had filled a single path consisting of the union of all these paths. By comparison, \textsc{svg} uses the upper-left (?) corner of the path to be filled as the origin. However, the \textsc{svg} specification is a bit vague on this question. @@ -83,9 +82,9 @@ command is used for this: \marg{tile size}% \marg{code}} - This command declares a new form-only pattern. The \marg{name} is a - name for later reference. The two parameters \marg{lower left} and - \marg{upper right} must describe a bounding box that is large enough + This command declares a new form-only pattern. The \meta{name} is a + name for later reference. The two parameters \meta{lower left} and + \meta{upper right} must describe a bounding box that is large enough to encompass the complete tile. The size of a tile is given by \meta{tile size}, that is, a tile is @@ -134,11 +133,11 @@ command is used for this: Normally, when this argument is empty, once a pattern has been declared, it becomes ``frozen''. This means that it is not possible to enlarge the pattern or change the line width later on. - By specifying \meta{variables} no pattern is actually created. + By specifying \meta{variables}, no pattern is actually created. Instead, the arguments are stored away (so the macros, registers or keys do not have to be defined in advance). - When the fill patten is set, \pgfname{} checks if the pattern has + When the fill pattern is set, \pgfname{} checks if the pattern has already been created with the \meta{variables} set to their current values (\pgfname{} is usually ``smart enough'' to distinguish between macros, registers and keys). If so, this already-declared-pattern @@ -223,7 +222,7 @@ Once a pattern has been declared, it can be used. This command specifies that paths that are filled should be filled with the ``color'' by the pattern \meta{name}. For an inherently colored pattern, the \meta{color} parameter is ignored. For - form-only patterns, the \meta{color} parameter specified the color + form-only patterns, the \meta{color} parameter specifies the color to be used for the pattern. \begin{codeexample}[] \begin{tikzpicture} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex index 89b51dffbad..61e627f8304 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-plots.tex @@ -51,13 +51,22 @@ sets of commands exist. The commands for creating streams start with \subsection{Generating Plot Streams} \subsubsection{Basic Building Blocks of Plot Streams} -A \emph{plot stream} is a (long) sequence of the following three + +A \emph{plot stream} is a (long) sequence of the following commands: \begin{enumerate} \item |\pgfplotstreamstart|, \item - |\pgfplotstreampoint|, and + |\pgfplotstreampoint|, +\item + |\pgfplotstreampointoutlier|, +\item + |\pgfplotstreampointundefined|, +\item + |\pgfplotstreamnewdataset|, +\item + |\pgfplotstreamspecial|, and \item |\pgfplotstreamend|. \end{enumerate} @@ -75,11 +84,17 @@ end with the last command. Here is an example of a plot stream: \pgfplotstreamend \end{codeexample} +Streams are \emph{global}, meaning that they are not influenced by +\TeX\ groups. + \begin{command}{\pgfplotstreamstart} This command signals that a plot stream starts. The effect of this command is to call the internal command |\pgf@plotstreamstart|, which is set by the current plot handler to do whatever needs to be - done at the beginning of the plot. + done at the beginning of the plot. It will also reset the + meaning of the internal commands like |\pgf@plotstreampoint| to the + initial setting for the plot handler (what this means will be + explained in a moment). \end{command} \begin{command}{\pgfplotstreampoint\marg{point}} @@ -88,18 +103,110 @@ end with the last command. Here is an example of a plot stream: which is also set by the current plot handler. This command should now ``handle'' the point in some sensible way. For example, a line-to command might be issued for the point. + + When a plot handler is installed, it will setup the internal command + |\pgf@plotstreampoint| in some way. It is permissible to change the + meaning of this internal command during a stream. For instance, a + handler might setup |\pgf@plotstreampoint| in some sensible way for + the first point and then redefine it so that subsequent points are + handled in some other way. + + As mentioned earlier, the |\pgfplotstreamstart| will always reset + the definition of the internal command to the initial meaning it had + when the handler was installed. This is true for the other commands + mentioned in the following. +\end{command} + +\begin{command}{\pgfplotstreampointoutlier\marg{point}} + An \emph{outlier} is a point that is ``out of bounds'' in some + way. For instance, it might have very large coordinates or the + coordinates might just be outside some specified + range. Nevertheless, an outlier is still a well-defined point. This + command is issued, for instance, by \textsc{gnuplot} when a value is + outside the specified range. + + You can configure how outliers are treated using the following key: + \begin{key}{/pgf/handle outlier points in plots=\meta{how} + (initially jump)} + \keyalias{tikz} + You can set \meta{how} to one of the following values: + \begin{itemize} + \item |plot| This will cause the outlier to be drawn normally, + just as if |\pgfplotstreampoint| had been used rather than this + command. + \item |ignore| The outlier will be completely ignored, just as if + the command had not been used at all. + \item |jump| This causes the internal macro |\pgf@plotstreamjump| + to be called. A ``jump'' in a stream is a position where a + ``gap'' is introduced. For instance, a simple line-to plot + handler will stop the current subpath at a jump position and + begin with a move-to operation at the next normal point of the + stream. + + The net effect of this setting is that at outlier points plots + get interrupted and ``restarted'' when the points are no longer + outliers. This is usually the behaviour you will be looking for. + \end{itemize} + \end{key} +\end{command} + +\begin{command}{\pgfplotstreampointundefined} + This command indicated that the stream contains an ``undefined'' + point like a point where some coordinate results for a division by + zero. Such a point cannot be plotted, which is why it is not given + as a parameter. However, such a point \emph{can} result in a jump in + the plot, depending on the setting of the following key: + \begin{key}{/pgf/handle undefined points in plots=\meta{how} + (initially jump)} + \keyalias{tikz} + You can set \meta{how} to one of the following values: + \begin{itemize} + \item |ignore| The undefined point will be completely ignored, just as if + the command had not been used at all. + \item |jump| This causes the internal macro |\pgf@plotstreamjump| + to be called. + \end{itemize} + \end{key} +\end{command} + +\begin{command}{\pgfplotstreamnewdataset} + This command indicated that in the stream a ``new data set'' starts. + So, the stream does not end, but there is a logical break in the + data. For example, when a table is read from a file, empty lines are + interpreted as indicating new data sets. What happens when a new + data set is encountered is governed by the following key: + \begin{key}{/pgf/handle new data sets in plots=\meta{how} + (initially jump)} + \keyalias{tikz} + You can set \meta{how} to one of the following values: + \begin{itemize} + \item |ignore| The command will be completely ignored, just as if + the command had not been used at all. + \item |jump| This causes the internal macro |\pgf@plotstreamjump| + to be called. + \end{itemize} + \end{key} +\end{command} + +\begin{command}{\pgfplotstreamspecial\marg{text}} + This command causes |\pgf@plotstreamspecial| to be called with + \meta{text} as its parameter. This allows handler-specific + information to be passed to the handler. All normal handlers ignore + this command. \end{command} \begin{command}{\pgfplotstreamend} This command signals that a plot stream ends. It calls - |\pgf@plotstreamend|, which should now do any necessary ``cleanup.'' + |\pgf@plotstreamend|, which should now do any necessary ``cleanup.'' \end{command} Note that plot streams are not buffered, that is, the different points are handled immediately. However, using the recording handler, it is possible to record a stream. + \subsubsection{Commands That Generate Plot Streams} +\label{section-plot-jumps} Plot streams can be created ``by hand'' as in the earlier example. However, most of the time the coordinates will be produced @@ -109,23 +216,44 @@ file and converts it into a plot stream. \begin{command}{\pgfplotxyfile\marg{filename}} This command will try to open the file \meta{filename}. If this succeeds, it will convert the file contents into a plot stream as - follows: A |\pgfplotstreamstart| is issued. Then, each nonempty line - of the file should start with two numbers separated by a space, such - as |0.1 1| or |100 -.3|. Anything following the numbers is ignored. - - Each pair \meta{x} and \meta{y} of numbers is converted into one - plot stream point in the xy-coordinate system. Thus, a line like -\begin{codeexample}[code only] -2 -5 some text + follows: A |\pgfplotstreamstart| is issued. Then, for each nonempty + line a |\pgfplotstreamnewdataset| is produced. Other lines in the + file should start with two numbers separated by a space, such as + |0.1 1| or |100 -.3|. The numbers may be followed by some text, + which will be ignore \emph{except} if it is exactly ``|u|'' or + ``|o|''. For ``|u|'', the point is considered to be undefined and + |\pgfplotstreampointundefined| is called. For ``|o|'', the point is + considered to be an outlier and |\pgfplotstreampointoutlier| is + called. Otherwise, each pair \meta{x} and \meta{y} of numbers is + converted into one plot stream point in the xy-coordinate + system. Thus, a line like +\begin{codeexample}[code only, tikz syntax=false] +0 Nan u +1 1 some text +2 4 +3 9 + +4 16 o +5 25 oo \end{codeexample} is turned into \begin{codeexample}[code only] -\pgfplotstreampoint{\pgfpointxy{2}{-5}} +\pgfplotstreamstart +\pgfplotstreampointundefined +\pgfplotstreampoint{\pgfpointxy{1}{1}} +\pgfplotstreampoint{\pgfpointxy{2}{4}} +\pgfplotstreampoint{\pgfpointxy{3}{9}} +\pgfplotstreamnewdataset +\pgfplotstreampointoutlier{\pgfpointxy{4}{16}} +\pgfplotstreampoint{\pgfpointxy{5}{25}} +\pgfplotstreamend \end{codeexample} + (Note that the last line is not an outlier because |oo| is not the + same as |o|). The two characters |%| and |#| are also allowed in a file and they are both treated as comment characters. Thus, a line starting with - either of them is empty and, hence, ignored. + either of them is treated as empty. When the file has been read completely, |\pgfplotstreamend| is called. @@ -136,24 +264,25 @@ file and converts it into a plot stream. This command works like |\pgfplotxyfile|, only \emph{three} numbers are expected on each non-empty line. They are converted into points in the xyz-coordinate system. Consider, the following file: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] % Some comments # more comments 2 -5 1 first entry -2 -.2 2 second entry +2 -.2 2 o 2 -5 2 third entry \end{codeexample} It is turned into the following stream: \begin{codeexample}[code only] \pgfplotstreamstart +\pgfplotstreamnewdataset +\pgfplotstreamnewdataset \pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}} -\pgfplotstreampoint{\pgfpointxyz{2}{-.2}{2}} +\pgfplotstreampointoutlier{\pgfpointxyz{2}{-.2}{2}} \pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}} \pgfplotstreamend \end{codeexample} \end{command} - Currently, there is no command that can decide automatically whether the xy-coordinate system should be used or whether the xyz-system should be used. However, it would not be terribly difficult to write a @@ -202,7 +331,7 @@ intelligently. Let us start with the situation where none of these files exists. Then \pgfname\ will first generate the file \meta{prefix}|.gnuplot|. In this file it writes -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] set terminal table; set output "#1.table"; set format "%.5f" \end{codeexample} where |#1| is replaced by \meta{prefix}. Then, in a second line, it @@ -239,11 +368,23 @@ set terminal table; set output "#1.table"; set format "%.5f" read. As explained in Section~\ref{section-tikz-gnuplot}, the net effect - of the above mechanism is that |gnuplot| is called as little as + of the above mechanism is that |gnuplot| is called as seldom as possible and that when you pass along the |.gnuplot| and |.table| files with your |.tex| file to someone else, that person can \TeX\ the |.tex| file without having |gnuplot| installed and without having the |\write18| mechanism switched on. + + \begin{key}{/pgf/plot/gnuplot call=\meta{gnuplot invocation} (initially gnuplot)} + This key can be used to change the way gnuplot is called. + + Some portable Mik\TeX{} distribution needs something like the + following. + +\begin{codeexample}[code only] + \pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"} +\end{codeexample} + + \end{key} \end{command} @@ -252,13 +393,13 @@ set terminal table; set output "#1.table"; set format "%.5f" \label{section-plot-handlers} -A \emph{plot handler} prescribes what ``should be done'' with a +A \emph{plot handler} determines what ``should be done'' with a plot stream. You must set the plot handler before the stream starts. The following commands install the most basic plot handlers; more plot handlers are defined in the file |pgflibraryplothandlers|, which is documented in Section~\ref{section-library-plothandlers}. -All plot handlers work by setting redefining the following three +All plot handlers work by setting or redefining the following three macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and |\pgf@plotstreamend|. @@ -322,7 +463,7 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and \begin{command}{\pgfplothandlerrecord\marg{macro}} When this handler is installed, each time a plot stream command is - called, this command will be appended to \meta{macros}. Thus, at + called, this command will be appended to \meta{macro}. Thus, at the end of the stream, \meta{macro} will contain all the commands that were issued on the stream. You can then install another handler and invoke \meta{macro} to ``replay'' the stream @@ -346,6 +487,112 @@ macros: |\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and \end{codeexample} \end{command} + + +\subsection{Defining New Plot Handlers} + +You can define new plot handlers using the following command: + +\begin{command}{\pgfdeclareplothandler\marg{macro}\marg{arguments}\marg{configuration}} + This command creates a new plot handler that can subsequently be + called using the macro \meta{macro}. This macro take the arguments + given in \meta{arguments}, which can be a list like |#1#2| if + \meta{macro} should be invoked with two arguments. Here is a typical example: +\begin{codeexample}[code only] +\pgfdeclareplothandler{\myhandler}{#1}{...} +... +\myhandler{foo} +\pgfplotstreamstart +... +\pgfplotstreamend +\end{codeexample} + + The \meta{configuration} is used to define the behaviour of the + handler. It is a list of key--value pairs, where the following keys + are allowed: + \begin{itemize} + \item |start=|\meta{code}. The \meta{code} will be executed whenever + |\pgfplotstreamstart| is used while the handler \meta{macro} is + selected. Inside the \meta{code}, you can use |#1|, |#2|, and so + on to refer to the parameters that were given to \meta{macro}: +\begin{codeexample}[width=6cm] +\pgfdeclareplothandler{\myhandler}{#1}{ + start = Hi #1., + end = Bye #1., +} +\myhandler{foo} +\pgfplotstreamstart +\pgfplotstreamend +\myhandler{bar} +\pgfplotstreamstart +\pgfplotstreamend +\end{codeexample} + \item |end=|\meta{code} Works just like |start|. + \item |point=|\meta{code}. The \meta{code} will be executed whenever + |\pgfplotstreampoint| is used while the handler \meta{macro} is in + force. Inside the \meta{code}, you can use |#1|, |#2|, and so on + to refer to the arguments give to \meta{macro}, while you can use + |##1| to refer to the argument given to |\pgfplotstreampoint| + itself (this will be the coordinate). +\begin{codeexample}[] +\pgfdeclareplothandler{\myhandler}{#1}{ + point=\pgfpathcircle{##1}{#1} % ##1 is the coordinate, + % #1 the parameter for \myhandler +} +\begin{pgfpicture} + \myhandler{1pt} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0pt}{0pt}} + \pgfplotstreampoint{\pgfpoint{3pt}{3pt}} + \pgfplotstreampoint{\pgfpoint{6pt}{3pt}} + \pgfplotstreampoint{\pgfpoint{9pt}{0pt}} + \pgfplotstreamend + \pgfusepath{stroke} + \myhandler{3pt} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0pt}{0pt}} + \pgfplotstreampoint{\pgfpoint{9pt}{0pt}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} + The \meta{code} will also be called for + |\pgfplotstreampointoutlier| when this command has been configured + to |plot| the outliers. + \item |jump=|\meta{code} The \meta{code} will be called whenever a + jump has been requested indirectly via an outlier point, and + undefined point, or a new data set (for each of which the command + needs to be configured to |jump|). As always, inside the + \meta{code} you can access |#1| and so on. + \item |special=|\meta{code} Causes \meta{code} to be executed + whenever |\pgfplotstreamspecial|\marg{something} is used. Inside + the \meta{code}, you can access \meta{something} via |##1| and the + parameters of \meta{macro} as |#1|, |#2|, and so on. + \end{itemize} + + In addition to the above keys, there exist also ``code macro + versions'' of them: + \begin{itemize} + \item |point macro=|\meta{some macro}. Causes |\pgfplotstreampoint| + to call \meta{some macro} directly (actually, + |\pgf@plotstreampoint| is set to be equal to \meta{some + macro}). Inside the \meta{some macro} you can use |#1| to access + the coordinate passed to |\pgfplotstreampoint| and you can no + longer access the parameters passed to the original call to + \meta{macro} that installed the handler. So, \meta{some macro} + must take exactly one argument, namely |#1|. + \item |special macro=|\meta{some macro}. As |point macro|, only for + specials. + \item |start macro=|\meta{some macro}. Causes \meta{some macro} to + be executed at the start. This macro, like the below ones, may not + take any parameters and will not have access to the parameters + passed to the original \meta{macro}. + \item |end macro=|\meta{some macro}. As above. + \item |jump macro=|\meta{some macro}. As above. + \end{itemize} +\end{command} + + %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex index 931a6a7bcf9..833118bdf57 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex @@ -121,7 +121,7 @@ $y$-vector do not necessarily point ``horizontally'' and \end{command} \begin{command}{\pgfsetyvec\marg{point}} - Works like |\pgfsetyvec|. + Works like |\pgfsetxvec|. \end{command} @@ -178,7 +178,7 @@ three dimensional graphics. \end{command} \begin{command}{\pgfsetzvec\marg{point}} - Works like |\pgfsetzvec|. + Works like |\pgfsetxvec|. \end{command} Inside the $xyz$-coordinate system, you can also specify points @@ -206,7 +206,7 @@ using spherical and cylindrical coordinates. \begin{command}{\pgfpointspherical\marg{longitude}\marg{latitude}\marg{radius}} This command yields a point ``on the surface of the earth'' - specified by the \meta{longitude} and the \marg{latitude}. The + specified by the \meta{longitude} and the \meta{latitude}. The radius of the earth is given by \meta{radius}. The equator lies in the $xy$-plane. \begin{codeexample}[] @@ -274,7 +274,7 @@ coordinates. \begin{command}{\pgfpointnormalised\marg{point}} - This command returns a normalized version of \meta{point}, that is, + This command returns a normalised version of \meta{point}, that is, a vector of length 1pt pointing in the direction of \meta{point}. If \meta{point} is the $0$-vector or extremely short, a vector of length 1pt pointing upwards is returned. @@ -304,7 +304,7 @@ coordinates. \label{section-pointsattime} The commands in this section allow you to specify points on a line or -a curve. Imaging a point ``traveling'' along a curve from some point +a curve. Imagine a point ``traveling'' along a curve from some point $p$ to another point $q$. At time $t=0$ the point is at $p$ and at time $t=1$ it is at $q$ and at time, say, $t=1/2$ it is ``somewhere in the middle.'' The exact location at time $t=1/2$ will not necessarily @@ -313,7 +313,7 @@ curve from $p$ and $q$ is equal. Rather, the exact location will depend on the ``speed'' at which the point is traveling, which in turn depends on the lengths of the support vectors in a complicated manner. If you are interested in the details, please see a good book -on Bézier curves. +on B\'ezier curves. @@ -336,7 +336,7 @@ on Bézier curves. \end{command} \begin{command}{\pgfpointlineatdistance\marg{distance}\marg{start point}\marg{end point}} - Yields a point that is located \meta{distance} many units removed + Yields a point that is located \meta{distance} many units away from the start point in the direction of the end point. In other words, this is the point that results if we travel \meta{distance} steps from \meta{start point} towards \meta{end point}. @@ -354,9 +354,31 @@ on Bézier curves. \end{codeexample} \end{command} +\begin{command}{\pgfpointarcaxesattime\marg{time + $t$}\marg{center}\marg{0-degree axis}\marg{90-degree + axis}\marg{start angle}\\\marg{end angle}} + Yields a point on the arc between \meta{start angle} and \meta{end + angle} on an ellipse whose center is at \meta{center} and whose + two principal axes are \meta{0-degree axis} and \meta{90-degree + axis}. For $t=0$ the point at the \meta{start angle} is returned + and for $t=1$ the point at the \meta{end angle}. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} + \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointarcaxesattime{\t}{\pgfpoint{0cm}{1cm}} + {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}{0}{60}]{\t}} +\end{tikzpicture} +\end{codeexample} +\end{command} + \begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}} - Yields a point that is on the Bézier curve from $p$ to $q$ with the + Yields a point that is on the B\'ezier curve from $p$ to $q$ with the support points $s_1$ and $s_2$. The time $t$ is used to determine the location, where $t=0$ yields $p$ and $t=1$ yields $q$. @@ -492,7 +514,7 @@ mechanism to determine border points of shapes. This library defines the below command and allows you to calculate the intersections of two arbitrary paths. However, due to the low accuracy of \TeX, the paths should not be ``too complicated''. - In particular, you should not try to intersect paths consisting + In particular, you should not try to intersect paths consisting of lots of very small segments such as plots or decorated paths. \end{pgflibrary} @@ -611,7 +633,7 @@ takes a coordinate as parameter will just execute this parameter and then use the values of |\pgf@x| and |\pgf@y| as the coordinates to which it will move the pen on the current path. -since commands like |\pgfpointnormalised| modify other variables +Since commands like |\pgfpointnormalised| modify other variables besides |\pgf@x| and |\pgf@y| during the computation of the final values of |\pgf@x| and |\pgf@y|, it is a good idea to enclose a call of a command like |\pgfpoint| in a \TeX-scope and then make the changes of diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex index f43e9d29de8..c7f762bef6c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-quick.tex @@ -27,7 +27,7 @@ be processed or if you expect your commands to be executed very often. \begin{command}{\pgfqpointxy\marg{$s_x$}\marg{$s_y$}} This command does the same as |\pgfpointxy|, but \meta{$s_x$} and \meta{$s_y$} - must be simple numbers without unit, like |1.234| or |5.0|. Mathematical expressions or units are not allows. + must be simple numbers without unit, like |1.234| or |5.0|. Mathematical expressions or units are not allowed. \end{command} \begin{command}{\pgfqpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}} @@ -177,7 +177,7 @@ not want arrows to be drawn. ``translational part'' of the coordinate transformation matrix, instead of adding the translational part to the current canvas transformation matrix directly. Both methods have the same - effect (box \meta{box number} is translated where it should), but + effect (box \meta{box number} is translated to where it should be), but the method used by |\pgfqboxsynced| ensures that hyperlinks are placed correctly. Note that scaling and rotation will not (cannot, even) apply to hyperlinks. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex index ceb90cb8adf..9d8e999a863 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex @@ -41,7 +41,7 @@ The \pgfname\ system consists of several layers: The basic layer is documented in the present part. \item[Frontend layer.] - The frontend layer is not loaded by a single packages. Rather, + The frontend layer is not loaded by a single package. Rather, different packages, like \tikzname\ or \textsc{pgfpict2e}, are different frontends to the basic layer. @@ -101,7 +101,7 @@ apply. In essence, the following scoping mechanisms are available: keep changes of the graphic state local to that environment. The effect of commands that change the graphic state are local to - the current |{pgfscope}| but not always to the current \TeX\ + the current |{pgfscope}|, but not always to the current \TeX\ group. Thus, if you open a \TeX\ group (some text in curly braces) inside a |{pgfscope}|, and if you change, for example, the dash pattern, the effect of this changed dash pattern will persist till @@ -133,7 +133,7 @@ apply. In essence, the following scoping mechanisms are available: The |\pgftext| command can be used to create a scope in which \TeX\ ``escapes back'' to normal \TeX\ mode. The text passed to the |\pgftext| is ``heavily guarded'' against having any effect on the - scope in which it is used. For example, it is possibly to use + scope in which it is used. For example, it is possible to use another |{pgfpicture}| environment inside the argument of |\pgftext|. \end{enumerate} @@ -154,6 +154,7 @@ rules: + \subsection{The Hierarchical Structure of the Package} Before we come to the structuring commands provided by \pgfname\ to @@ -212,9 +213,9 @@ The following package is just a convenience. What this command does is to load the file |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in - the \meta{module names}. Thus, to write your own module, + the list of \meta{module names}. Thus, to write your own module, all you need to do is to place a file of the appropriate name - somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t + somewhere \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t users can then use your library. \end{command} @@ -294,7 +295,7 @@ environment. ``mentioned'' despite the fact that you will not ``see'' them in your code. - Once the \meta{environment contents} has been parsed completely, a + Once the \meta{environment contents} have been parsed completely, a \TeX\ box is created whose size is the size of the computed bounding box and this box is inserted at the current position. @@ -366,7 +367,7 @@ Rectangles \begin{pgfpicture} In order to make \pgfname\ ``remember'' a picture, the \TeX-if |\||ifpgfrememberpicturepositiononpage| should be set to |true|. It is only important that this \TeX-if is |true| at the end of the - |{pgfpicture}|-environment, so you can switch it on inside the + |{pgfpicture}|-en\-vi\-ron\-ment, so you can switch it on inside the environment. However, you can also just switch it on globally, then the positions of all pictures are remembered. @@ -401,7 +402,7 @@ Rectangles \begin{pgfpicture} If this option is set to true of a picture, \pgfname\ will attempt to record the position of the picture on the page. (This attempt - will fail with most drivers and when it works it typically requires + will fail with most drivers and when it works, it typically requires two runs of \TeX.) The position is not directly accessible. Rather, the nodes mechanism will use this position if you access a node from another picture. See Sections~\ref{section-cross-pictures-pgf} @@ -417,16 +418,25 @@ Rectangles \begin{pgfpicture} picture has been typeset completely, \pgfname\ must decide at which height the baseline of the picture should lie. Normally, the baseline is set to the $y$-coordinate of the bottom of the picture, - but it is often desirable to use another height. + but it is often desirable to use a different height. \begin{codeexample}[] -Text \tikz{\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, - \tikz{\pgfsetbaseline{0pt} - \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, - \tikz{\pgfsetbaseline{.5ex} - \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, - \tikz{\pgfsetbaseline{-1ex} - \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}. +Text +\begin{pgfpicture} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} +\end{pgfpicture}, +\begin{pgfpicture} + \pgfsetbaseline{0pt} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} +\end{pgfpicture}, +\begin{pgfpicture} + \pgfsetbaseline{.5ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} +\end{pgfpicture}, +\begin{pgfpicture} + \pgfsetbaseline{-1ex} + \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke} +\end{pgfpicture}. \end{codeexample} \end{command} @@ -443,11 +453,11 @@ Text \tikz{\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}, \begin{codeexample}[] Hello -\tikz{ +\begin{pgfpicture} \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}} % Note: no shape X, yet - \node [cross out,draw] (X) {world.}; -} + \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}} +\end{pgfpicture} \end{codeexample} \end{command} @@ -637,7 +647,7 @@ a shading into a |{pgfpicture}|. This command will typeset \meta{text} in normal \TeX\ mode and insert the resulting box into the |{pgfpicture}|. The bounding box of the graphic will be updated so that all of the text box is - inside. Be default, the text box is centered at the origin, but this + inside. By default, the text box is centered at the origin, but this can be changed either by giving appropriate \meta{options} or by applying an appropriate coordinate transformation beforehand. @@ -737,3 +747,21 @@ a shading into a |{pgfpicture}|. \end{key} \end{command} + + +\subsection{Error Messages and Warnings} + +Sometimes, a command inside \pgfname\ may fail. In this case, two +commands are useful to communicate with the author: + +\begin{command}{\pgferror\marg{message}} + Stops the processing of the current document and prints out the + \meta{message}. In \LaTeX, this will be done using |\PackageError|, + otherwise |\errmessage| is used directly. +\end{command} + +\begin{command}{\pgfwarning\marg{message}} + Prints the \meta{message} on the output, but does not interrupt the + processing. In \LaTeX, this will be done using |\PackageWarning|, + otherwise a write to stream $17$ is used. +\end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex index d38f6bf3759..16d4dd04d99 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-shadings.tex @@ -27,7 +27,7 @@ complicated shadings. Horizontal shadings could be created by rotating a vertical shading by 90 degrees, but explicit commands for creating both horizontal and vertical shadings are included for convenience. -Once you have declared a shading, you can insert it into text using +Once you have declared a shading, you can insert it into the text using the command |\pgfuseshading|. This command cannot be used directly in a |{pgfpicture}|, you have to put a |\pgftext| around it. The second command for using shadings, |\pgfshadepath|, on the other hand, can @@ -38,8 +38,8 @@ A horizontal shading is a horizontal bar of a certain height whose color changes smoothly. You must at least specify the colors at the left and at the right end of the bar, but you can also add color specifications for points in between. For example, suppose you -which to create a bar that is red at the left end, green in the -middle, and blue at the end. Suppose you would like the bar to be 4cm +wish to create a bar that is red at the left end, green in the +middle, and blue at the end, and you would like the bar to be 4cm long. This could be specified as follows: \begin{codeexample}[code only] rgb(0cm)=(1,0,0); rgb(2cm)=(0,1,0); rgb(4cm)=(0,0,1) @@ -63,7 +63,7 @@ in increasing order. \begin{command}{\pgfdeclarehorizontalshading\oarg{color list}\marg{shading name}\marg{shading height}\marg{color specification}} Declares a horizontal shading named \meta{shading name} of the specified - \meta{height} with the specified colors. The length of the bar is + \meta{height} with the specified colors. The width of the bar is deduced automatically from the maximum dimension in the specification. \begin{codeexample}[] @@ -127,7 +127,7 @@ in increasing order. \begin{command}{\pgfdeclareradialshading\oarg{color list}\marg{shading name}\marg{center point}\marg{color specification}} - Declares an radial shading. A radial shading is a circle whose inner + Declares a radial shading. A radial shading is a circle whose inner color changes as specified by the color specification. Assuming that the center of the shading is at the origin, the color of the center will be the color specified for 0cm and the color of the border of @@ -161,9 +161,9 @@ in increasing order. This command creates a \emph{functional shading}. For such a shading, the color of each point is calculated by calling a function - that gets the coordinates of the point as input and yields the + that takes the coordinates of the point as input and yields the color as an output. Note that the function is evaluated by the - \emph{renderer}, not by \pgfname\ or \TeX or someone else at + \emph{renderer}, not by \pgfname\ or \TeX\ or someone else at compile-time. This means that the evaluation of this function has to be done \emph{extremely quickly} and the function should be \emph{very simple}. For this reason, only a very restricted set of @@ -200,7 +200,7 @@ in increasing order. empty (or should be treated as if it were empty). The function should then replace these two values by three values, representing the red, green, and blue color of the point. The numbers should be - real values, not integers since Apple's PDF renderer is broken in + real values, not integers since, Apple's PDF renderer is broken in this regard (use cvr at the end if necessary). Conceptually, the function will be evaluated once for each point of @@ -212,7 +212,7 @@ in increasing order. Because of the rather difficult PostScript syntax, use this macro only \emph{if you know what you are doing} (or if you are - advantageous, of course). + adventurous, of course). As for other shadings, the optional \meta{color list} is used to determine whether a shading needs to be recalculated when a color @@ -232,7 +232,7 @@ in increasing order. 40 sub dup mul 0.5 mul add sqrt % exponential decay dup mul neg 1.0005 exch exp 1.0 exch sub - % Compute distance form (70bp,70bp) from stored coordinate, scaled + % Compute distance from (70bp,70bp) from stored coordinate, scaled 3 1 roll 70 sub dup mul .5 mul exch 70 sub dup mul add sqrt @@ -246,7 +246,7 @@ in increasing order. Inside the PostScript function \meta{type 4 function} you cannot use colors directly. Rather, you must push the color components on the - stack. For this, it is useful to call |\pgfshadecolorrgb| in the + stack. For this, it is useful to call |\pgfshadecolortorgb| in the \meta{init code}: \begin{command}{\pgfshadecolortorgb\marg{color name}\marg{macro}} @@ -358,7 +358,7 @@ be used in the \meta{type 4 function} argument. This command must be used inside a |{pgfpicture}| environment. The effect is a bit complex, so let us go over it step by step. - First, \pgfname\ will setup a local scope. + First, \pgfname\ will set up a local scope. Second, it uses the current path to clip everything inside this scope. However, the current path is once more available after the @@ -374,7 +374,7 @@ be used in the \meta{type 4 function} argument. Inside the scope, the low-level transformation matrix is modified. The center of the shading is translated (moved) such that it lies on the center of the bounding box of the path. The low-level coordinate - system is also scaled such that the shading ``covers'' the shading (the + system is also scaled such that the shading ``covers'' the path (the details are a bit more complex, see below). Then, the coordinate system is rotated by \meta{angle}. Finally, if the macro |\pgfsetadditionalshadetransform| has been used, an additional @@ -385,7 +385,7 @@ be used in the \meta{type 4 function} argument. shading seems to ``fill'' the path. If both the path and the shadings were always rectangles and if - rotation were never involved, it would be easy to scale shadings + rotations were never involved, it would be easy to scale shadings such they always cover the path. However, when a vertical shading is rotated, it must obviously be ``magnified'' so that it still covers the path. Things get worse when the path is not a @@ -512,7 +512,7 @@ be used in the \meta{type 4 function} argument. \end{tikzpicture} \end{codeexample} - Note that rainbow shadings are \emph{way} to colorful in almost all + Note that rainbow shadings are \emph{way} too colorful in almost all applications. \end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex index 44774b573b3..145463b7ffb 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex @@ -7,19 +7,20 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Coordinate and Canvas Transformations} +\section{Coordinate, Canvas, and Nonlinear Transformations} \subsection{Overview} -\pgfname\ offers two different ways of scaling, shifting, and rotating +\pgfname\ offers different ways of scaling, shifting, and rotating (these operations are generally known as \emph{transformations}) graphics: You can apply \emph{coordinate transformations} to all -coordinates and you can apply \emph{canvas transformations} to the -canvas on which you draw. (The names ``coordinate'' and ``canvas'' +coordinates, you can apply \emph{canvas transformations} to the +canvas on which you draw, and you can apply \emph{additional nonlinear + transformations.} (The names ``coordinate'' and ``canvas'' transformations are not standard, I introduce them only for the purposes of this manual.) -The difference is the following: +The differences are the following: \begin{itemize} \item @@ -44,6 +45,17 @@ The difference is the following: canvas is transformed, in this case stretched by a factor of two. In the resulting image \emph{everything} will be larger: Text, lines, coordinates, and shadings. +\item + Nonlinear transformations are a special form of coordinate + transformations that are, as the name suggests, not linear. The + support for nonlinear transformations is quite different from the + support for linear coordinate transformations, the main reason being + speed: While linear coordinate transformations can be applied very + quickly (\pgfname\ does so almost constantly), nonlinear + transformations are much harder to apply and also to use. For this + reason, nonlinear transformations are implemented in a special + module |nonlineartransformations| that has to be loaded + explicitly. By default, they are not available. \end{itemize} In many cases, it is preferable that you use coordinate @@ -52,13 +64,16 @@ transformations are used, \pgfname\ looses track of the coordinates of nodes and shapes. Also, canvas transformations often cause undesirable effects like changing text size. For these reasons, \pgfname\ makes it easy to setup the coordinate transformation, but a bit harder to -change the canvas transformation. +change the canvas transformation. Because of the speed penalties +caused by nonlinear transformations, they are even harder to set up. \subsection{Coordinate Transformations} +\label{section-linear-coordinate-transformations} \subsubsection{How PGF Keeps Track of the Coordinate Transformation Matrix} +\label{section-transform-cm} \pgfname\ has an internal coordinate transformation matrix. This matrix is applied to coordinates ``in certain situations.'' This means @@ -70,7 +85,7 @@ matrix to their inputs. The coordinate transformation matrix consists of four numbers $a$, $b$, $c$, and $d$, and two dimensions $s$ and $t$. When the coordinate -transformation matrix is applied to a coordinate $(x,y)$ the new +transformation matrix is applied to a coordinate $(x,y)$, the new coordinate $(ax+by+s,cx+dy+t)$ results. For more details on how transformation matrices work in general, please see, for example, the \textsc{pdf} or PostScript reference or a textbook on computer @@ -187,8 +202,8 @@ coordinate transformations. -\begin{command}{\pgftransformrotate\marg{degrees}} - Rotates coordinates counterclockwise by \meta{degrees}. +\begin{command}{\pgftransformrotate\marg{angles}} + Rotates coordinates counterclockwise by \meta{angles} given in degrees. \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -236,7 +251,7 @@ coordinate transformations. \begin{command}{\pgftransformarrow\marg{start}\marg{end}} - Shift coordinates to the end of the line going from \meta{start} + Shifts coordinates to the end of the line going from \meta{start} to \meta{end} with the correct rotation. \begin{codeexample}[] \begin{tikzpicture} @@ -280,7 +295,7 @@ coordinate transformations. ensure that the rotation is done in such a way that text is never ``upside down.'' - There is another \TeX\ if that influences this command. If you set + There is another \TeX\ |\if| that influences this command. If you set |\ifpgfresetnontranslationattime| to true, then, between shifting the coordinate and (possibly) rotating/sloping the coordinate, the command |\pgftransformresetnontranslations| is @@ -341,6 +356,33 @@ coordinate transformations. \end{command} +\begin{command}{\pgftransformarcaxesattime\marg{time + $t$}\marg{center}\marg{0-degree axis}\marg{90-degree + axis}\marg{start angle}\marg{end angle}} + Shifts coordinates by a specific point on an arc at a specific + time, see Section~\ref{section-pointsattime} once more. + + As for the previous commands, |\ifpgfslopedattime| + decides whether an additional rotation should be applied and + |\ifpgfallowupsidedowattime| is also considered. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} + \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{stroke} + \pgfslopedattimetrue + \pgftransformarcaxesattime{.25} + {\pgfpoint{0cm}{1cm}} + {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}} + {0}{60} + \pgftext{Hi!} +\end{tikzpicture} +\end{codeexample} + The value of |\ifpgfresetnontranslationsattime| is also taken into account. +\end{command} + + { \let\ifpgfslopedattime=\relax \begin{textoken}{\ifpgfslopedattime} @@ -352,7 +394,7 @@ coordinate transformations. \let\ifpgfallowupsidedowattime=\relax \begin{textoken}{\ifpgfallowupsidedowattime} Decides whether the ``at time'' transformation commands should - allow the rotation be down in such a way that ``upside-down text'' + allow the rotation be done in such a way that ``upside-down text'' can result. \end{textoken} } @@ -370,7 +412,7 @@ coordinate transformations. The coordinate transformation commands introduced up to now are always applied in addition to any previous transformations. In contrast, the commands presented in the following can be used to change the -transformation matrix ``absolutely.'' Note that this is, in general, +transformation matrix ``in absolute terms.'' Note that this is, in general, dangerous and will often produce unexpected effects. You should use these commands only if you really know what you are doing. @@ -467,7 +509,7 @@ transformation matrices. \subsection{Canvas Transformations} The canvas transformation matrix is not managed by \pgfname, but by -the output format like \pdf\ or PostScript. All the \pgfname\ does is +the output format like \pdf\ or PostScript. All that \pgfname\ does is to call appropriate low-level |\pgfsys@| commands to change the canvas transformation matrix. @@ -582,9 +624,463 @@ a coordinate transformation, see the previous section). \end{contextenvironment} +\subsection{Nonlinear Transformations} +\label{section-nonlinear-transformations} +In order to use nonlinear transformations, you first have to load the +following \pgfname\ module: + +\begin{pgfmodule}{nonlineartransformations} + Loads the necessary functionality for nonlinear transformations. +\end{pgfmodule} + + +\subsubsection{Introduction} + +The difference between the coordinate transformations introduced in +Section~\ref{section-linear-coordinate-transformations} above to +nonlinear transformations is, of course, that the transformations can +be nonlinear. An example of a nonlinear transformation is the +transformation underlying polar coordinates: A polar coordinate +$(r,d)$ gets transformed to the canvas position $(d\cos r,d\sin r)$, +which is clearly not a linear transformation. + +Nonlinear transformations work somewhat like the normal linear +coordinate transformations in the sense that they apply to coordinate +and thereby to the construction of paths, but not to things like text +or line width or shadings. (Indeed, it is not possible to apply +nonlinear transformations to, say, text.) + +This means that there is a fundamental +difference between, on the one hand, calling a function like +|\pgfpointpolar| or specifying a coordinate as |(45:2)| in \tikzname\ +and, on the other hand, installing the nonlinear transformation +``polar coordinates'' using the command |\pgftransformnonlinear|: In a +coordinate like |(45:2)| the user explicitly says ``please evaluate +this one coordinate in polar coordinate and then continue in the +normal coordinate system with the result.'' Otherwise nothing changes +and a line between two points specified in this way is still a +straight line. + +Things are quite different when we install a polar +\emph{transformation} using |\pgftransformnonlinear|. Now, even a +seemingly low-level Cartesian coordinate |\pgfqpoint{1pt}{1pt}| will +get transformed. Even more drastically, what is specified as a +straight line like +\begin{codeexample}[code only] +\draw (0,1) -- (1,1); +\end{codeexample} +can become curved since \emph{everything} gets transformed. + + +\subsubsection{Installing Nonlinear Transformation} + +\makeatletter +\def\polartransformation{ + % \pgf@x will contain the radius + % \pgf@y will contain the distance + \pgfmathsincos@{\pgf@x}% + % pgfmathresultx is now the cosine of radius and + % pgfmathresulty is the sine of radius + \pgf@x=\pgfmathresultx\pgf@y% + \pgf@y=\pgfmathresulty\pgf@y% +} +\makeatother + +\begin{command}{\pgftransformnonlinear\marg{transformation code}} + This command adds the \meta{transformation code} to the list of non-linear + transformations currently in force. Thus, similar to linear + coordinate transformations, each additional call to this function + adds another transformation to the current \TeX\ scope and the + effect ends at the end of the current scope. In practice, however, + you typically will not have more than one active nonlinear + transformation. + + The job of the \meta{transformation code} is to map a point~$p$ + given in the registers |\pgf@x| and |\pgf@y| to a new + coordinate~$f(p)$, which should be returned in |\pgf@x| and |\pgf@y| + as well. As an example, suppose we wish to install polar coordinates + as the nonlinear transformation. For this, we need a bit of code: +\begin{codeexample}[code only] +\def\polartransformation{% + % \pgf@x will contain the radius + % \pgf@y will contain the distance + \pgfmathsincos@{\pgf@x}% + % pgfmathresultx is now the cosine of radius and + % pgfmathresulty is the sine of radius + \pgf@x=\pgfmathresultx\pgf@y% + \pgf@y=\pgfmathresulty\pgf@y% +} +\end{codeexample} + (In case you wonder why you cannot just call |\pgfpointpolar| at + this point: You can, but this function internally uses |\pgf@x| + and |\pgf@y| in complicated ways, so you would first have to safe + them so some other registers. Also, the above is faster.) + + If we were to call this function again, we would get something funny + like ``polar-polar coordinates,'' so let's not do this. Let us + instead have a look at the effect this call has: Once a nonlinear + transformation is installed, all subsequent path constructions are + affected by this transformation. In particular, a normal grid now + becomes the typical ``polar grid.'' + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + % Start nonlinear transformation + \pgftransformnonlinear{\polartransformation}% see above + + % Draw something with this transformation in force + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Applying Nonlinear Transformations to Points} + +\begin{command}{\pgfpointtransformednonlinear\marg{point}} + Works like |\pgfpointtransformed|, but also applies the current + nonlinear transformation; that is, it first applies the current + linear transformation and then the current nonlinear + transformations. Note that, just like |\pgfpointtransformed|, you + normally do not call this function directly since it is called + internally by the path drawing commands. +\end{command} + + +\subsubsection{Applying Nonlinear Transformations to Paths} + +When a nonlinear transformation is installed, the normal path +construction commands like |\pgfpathmoveto| get adjusted so that the +``honour'' the nonlinear transformations currently in force. For +|\pgfpathmoveto| this is pretty simple: Instead of just applying the +linear transformation matrix to the point to which the path should +``jump'' next, we also apply the nonlinear transformation. However, +for a command like |\pgfpathlineto|, things are much more difficult: +A straight line will no longer be a straight line! + +In order to make straight lines ``bend'', the following changes are in +force while a nonlinear transformation is installed: + +\begin{enumerate} +\item Whenever a straight line between two points $p$ and $q$ should + be added to the path, either through |\pgfpathlineto| or through + |\pgfpathclose|, we replace this straight line by a ``degenerated + curve'' from $p$ to $q$ whose control points are at one third and + two third of the distance between $p$ and $q$ on the line between + $p$ and $q$. In this way, while nonlinear transformations are in + force, we only need to transform curves. +\item Next, suppose we wish to transform a curve from $p$ to $q$ with + supports $s$ and $t$. For this, we simply apply the nonlinear + transformation $f$ to all four points and draw a line with the + results. Note that this mapping is actually not quite satisfactory + for long lines that are strongly curved: +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgftransformnonlinear{\polartransformation} + % The curve with the controls computed by pgf: a nice quarter arc + \draw [red] (0,20mm) -- (90pt,20mm); + } + % Here is the curve with controls just transformed: + \draw (0:20mm) .. controls (30pt:20mm) and (60pt:20mm) .. (90pt:20mm); +\end{tikzpicture} +\end{codeexample} + As the example shows, the control points now lie on the arc; but in + reality they should point along the tangents at the start and the + end. This is exactly when \pgfname\ does through the computation + described above. +\item + To overcome the effect of the control points being ``off,'' it is + necessary to split up longer curves into smaller parts, which are + drawn individually to increase the accuracy. When such splitting + occurs, can be configured using the following command: + \begin{command}{\pgfsettransformnonlinearflatness\marg{dimension} + (initially 5pt)} + Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum + of the distances in $x$- and $y$-directions) between the start of + a curve and its first control point or between the first and + second control points or between the second control point and the + end is more than \meta{distance}, the curve gets split in the + middle (more precisely, at time $t= 0.5$) and we draw the two + parts individually (for them, splitting may occur again, if the + curve is still too long). +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \draw[red] (0:20mm) arc [start angle=0, end angle=90, radius=2cm]; + { + \pgftransformnonlinear{\polartransformation} + \pgfsettransformnonlinearflatness{2pt} % very precise + \draw (0,20mm) -- (90pt,20mm); + } +\end{tikzpicture} +\end{codeexample} + \end{command} +\end{enumerate} + + +\subsubsection{Applying Nonlinear Transformations to Text} + +Earlier, it was pointed that nonlinear transformations do not apply +to text. Nevertheless, when you use |\pgftext| or |\pgfnode|, +\pgfname\ will do a sort of ``best effort'' to render the text in +the nonlinear coordinate system: The point where the text should be +shown can obviously be computed easily. When then temporarily reset +the nonlinear transformation and, instead, setup a linear +transformation that matches the nonlinear transformation at the +point where the text should be. Then, the text is shown. This means +that if the text is longer, it will not ``follow'' the nonlinear +transformation, but near the origin of the text it will look +``correct.'' As an example, let us add some text at the grid point +of the above example: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \pgftransformnonlinear{\polartransformation}% see above + + % Draw something with this transformation in force + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + + \foreach \angle in {0,30,60,90} + \foreach \dist in {1,2} + { + \pgftransformshift{\pgfpoint{\angle pt}{\dist cm}} + \pgftext{\angle$^\circ$} + } +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Approximating Nonlinear Transformations Using Linear Transformations} + +At any given point, the current nonlinear transformation can be +approximated using a linear transformation. The following two +functions allow you to install such a local approximation: + +\begin{command}{\pgfapproximatenonlineartransformation} + This command will do two things: + \begin{enumerate} + \item It clears the nonlinear transformations for the rest of the + current \TeX\ scope, so only linear transformations apply. + \item However, before removing the nonlinear transformations, the + linear transformation matrix is modified so that it mimics the + effect the nonlinear transformation had at the origin. That is, + after you call this command, drawing something near the origin + will look almost the same as if you had not called it. + \end{enumerate} + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \pgftransformnonlinear{\polartransformation}% see above + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + + \begin{scope}[shift={(45pt,20mm)}] + % Draw something near "origin": + \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (10pt,-10pt) -- (-10pt,10pt); + + % Now draw the same, but in the "approximate" coordinate system: + \pgfapproximatenonlineartransformation + \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (10pt,-10pt) -- (-10pt,10pt); + \pgftext{foo}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + This command is used by |\pgftext| and |\pgfnode| to transform text + when a nonlinear transformation is in force. +\end{command} + +\begin{command}{\pgfapproximatenonlineartranslation} + This command works like the normal approximation command, but it + will only approximate how the origin gets translated, it will not + approximate the rotation, skewing, or scaling that is involved. This + is useful for drawing text at the right position, but without + ``mutilating'' the text. +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \pgftransformnonlinear{\polartransformation}% see above + \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); + + \begin{scope}[shift={(45pt,20mm)}] + % Draw something near "origin": + \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (10pt,-10pt) -- (-10pt,10pt); + + % Now draw the same, but in the "approximate" coordinate system: + \pgfapproximatenonlineartranslation + \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (10pt,-10pt) -- (-10pt,10pt); + \pgftext{foo}; + \end{scope} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Nonlinear Transformation Libraries} +\label{section-library-curvilinear} + +\begin{pgflibrary}{curvilinear} + This library defines commands for computing nonlinear + transformations ``along B\'ezier curves''. +\end{pgflibrary} + +Up to now, our running example for a nonlinear transformation was +polar transformation. However, is \pgfname\ nonlinear transformations +are \emph{actually} mainly used for transforming arrow tips; and these +need to be transformed ``along curves.'' The |curvilinear| library +defines a number of commands that offer the necessary computations for +such transformations. + +\begin{command}{\pgfsetcurvilinearbeziercurve\marg{start}\marg{first + support}\marg{second support}\marg{end}} + Prior to using any other command from this library, you first call + this function to ``install'' a B\'ezier curve to which the commands + will refer. This curve will be local to the current \TeX\ scope and + you can install only one curve at a time. + + The main job of this command is to store the passed points + internally and to build a lookup table for distance-to-time + conversions, see the next command. +\begin{codeexample}[code only] +\pgfsetcurvilinearbeziercurve + {\pgfpointorigin} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{2cm}{1cm}} + {\pgfpoint{3cm}{0cm}} +\end{codeexample} +\end{command} + +\begin{command}{\pgfcurvilineardistancetotime\marg{distance}} + This command does a ``distance-to-time-conversion'': It tries to + compute a time $t$, returned in |\pgf@x|, that corresponds to + travelling \meta{distance} along the curve that has last been + installed using the command |\pgfsetcurvilinearbeziercurve|. The distance-to-time-conversion + uses the precomputations done by that command. Note that several + compromises had to be made between speed and accuracy: + \begin{itemize} + \item The conversion will be best near the start of the curve. + \item The more ``degenerate'' the curve, the worse the results. + \end{itemize} +\end{command} + + +\begin{command}{\pgfpointcurvilinearbezierorthogonal\marg{distance}\marg{offset}} + This command computes the following point: Consider the curve + last installed using the command |\pgfsetcurvilinearbeziercurve|. We + travel along this curve by \meta{distance}, arriving at a point + $p$. Then, we turn by $90^\circ$ and travel by \meta{offset} units + ``aways from the curve,'' arriving at a point $q$. This point $q$ + will now be returned in |\pgf@x| and |\pgf@y|; furthermore, the + transformed local coordinate system at point $q$ will also be + returned |\pgf@xa| and the other registers, see + |\pgftransformnonlinear| for details. + \makeatletter +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{11mm}{20mm}} + {\pgfpoint{20mm}{11mm}} + {\pgfpoint{20mm}{0mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfpointcurvilinearbezierpolar\marg{x}\marg{y}} + This command is similar to the previous version, but the + transformation is different: The idea is that a line form $(0,0)$ to + $(x,0)$ gets transformed to the curve from the start of the curve to + a point at distance $x$ along the curve. This is identical to what + the ``orthogonal'' transformation above also does. The difference is + that a line from $(0,0)$ to $(0,y)$ gets still transformed to an + initial segment of the curve of a length of $y$, but now rotated by + $90^\circ$. In general, the point $p = (x,y)$ gets transferred to a + point that at distance $|p| = \sqrt{x^2+y^2}$ along the curve, but + rotated by the angle of $p$ relative to the $x$-axis. + + All of these computations mainly have the following effect: Two + straight lines from the start of the curve as in a |Straight Barb| + arrow tip get transformed to an initial segment of the curve whose + length is the length of the two lines, but this segment gets rotated + by the angle of the two lines. + \makeatletter +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{11mm}{20mm}} + {\pgfpoint{20mm}{11mm}} + {\pgfpoint{20mm}{0mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + % Add a "barb": + \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}% + \draw (0,-30pt) grid [step=10pt] (80pt,30pt); + % Add a "barb": + \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt); + } + \draw[red, very thick] + (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); +\end{tikzpicture} +\end{codeexample} +\end{command} %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" %%% End: + +% LocalWords: nonlineartransformations PGF cx dy pdf PostScript pgfscope xstep +% LocalWords: Reinstalls shiftx backend pgflowlevelscope ystep ezier lookup xa +% LocalWords: precomputations diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex index a286fcfcd34..1243597df54 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transparency.tex @@ -56,7 +56,7 @@ Specifying a stroke and/or fill opacity is quite easy. \end{codeexample} \end{command} -Note the following effect: If you setup a certain opacity for stroking +Note the following effect: If you set up a certain opacity for stroking or filling and you stroke or fill the same area twice, the effect accumulates: @@ -72,6 +72,29 @@ Often, this is exactly what you intend, but not always. You can use transparency groups, see the end of this section, to change this. +\subsection{Specifying a Blend Mode} + +To set the blend mode, use the following command: + +\begin{command}{\pgfsetblendmode\marg{mode}} + Sets the blend mode to one of the values described in + Section~\ref{section-blend-modes}. As described there, blend modes + are an advanced feature of \textsc{pdf} and not always rendered + correctly. + + +\begin{codeexample}[] +\tikz [transparency group] { + \pgfsetblendmode{screen} + + \fill[red!90!black] ( 90:.6) circle (1); + \fill[green!80!black] (210:.6) circle (1); + \fill[blue!90!black] (330:.6) circle (1); +} +\end{codeexample} +\end{command} + + \subsection{Specifying a Fading} The method used by \pgfname\ for specifying fadings is quite @@ -91,9 +114,9 @@ transparent. \begin{command}{\pgfdeclarefading\marg{name}\marg{contents}} - This command declare a fading named \meta{name} for later use. The + This command declares a fading named \meta{name} for later use. The ``picture'' on which the fading is based is given by the - \meta{contents}. This \meta{contents} is normally typeset in a \TeX\ + \meta{contents}. The \meta{contents} are normally typeset in a \TeX\ box. The resulting box is then used as the ``picture.'' In particular, inside the \meta{contents} you must explicitly open a |{pgfpicture}| environment if you wish to use \pgfname\ commands. @@ -168,7 +191,7 @@ transparent. \end{command} After having declared a fading, we can use it. As for shadings, there -are two different commands for using fadings: +are different commands for using fadings: \begin{command}{\pgfsetfading\marg{name}\marg{transformations}} This command sets the graphic state parameter ``fading'' to a @@ -177,7 +200,7 @@ are two different commands for using fadings: current scope or until a different transparency setting is chosen. When the fading is installed, it will be centered on the origin with - its natural size. Anything outside the fading pictures's original + its natural size. Anything outside the fading picture's original bounding box will be transparent and, thus, the fading effectively clips against this bounding box. @@ -212,7 +235,7 @@ are two different commands for using fadings: \begin{command}{\pgfsetfadingforcurrentpath\marg{name}\marg{transformations}} This command works like |\pgfsetfading|, but the fading is scaled - are transformed according to the following rules: + and transformed according to the following rules: \begin{enumerate} \item If the current path is empty, the command has the same effect as @@ -257,15 +280,33 @@ are two different commands for using fadings: \end{command} +\begin{command}{\pgfsetfadingforcurrentpathstroked\marg{name}\marg{transformations}} + This command works line |\pgfsetfadingforcurrentpath|, only the + current path is enlarged by the line width in both $x$- and + $y$-direction. This is exactly the enlargement necessary to + compensate for the fact that if the current path will be stroked, + this much needs to be added around the path's bounding box to + actually contain the path. +\begin{codeexample}[] +\begin{tikzpicture} + \pgfsetlinewidth{2mm} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfsetfadingforcurrentpathstroked{fading}{} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + \subsection{Transparency Groups} Transparency groups are declared using the following commands. -\begin{environment}{{pgftransparencygroup}} +\begin{environment}{{pgftransparencygroup}\opt{\oarg{options}}} This environment should only be used inside a |{pgfpicture}|. It has the following effect: \begin{enumerate} - \item The \meta{environment contents} is stroked/filled + \item The \meta{environment contents} are stroked/filled ``ignoring any outside transparency.'' This means, all previous transparency settings are ignored (you can still set transparency inside the group, but never mind). This means that if in the @@ -279,7 +320,20 @@ Transparency groups are declared using the following commands. color will be blended with whatever is ``behind'' the group on the page. \end{enumerate} - + + The optional \meta{options} are keys that configure the transparency + group further. Two keys are currently defined: + \begin{itemize} + \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures + whether the group is a knockout group (if no argument is given, + |true| is assumed; initially the key is always false, even when + the command is used in a nested manner.) See + Section~\ref{section-transparency-groups} for details on knockout groups. + \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but + configures whether the group is an isolated group. Also see + Section~\ref{section-transparency-groups} for details on isolated groups. + \end{itemize} + Note that, depending on the driver, \pgfname\ may have to guess the size of the contents of the transparency group (because such a group is put in an XForm in \textsc{pdf} and a bounding box must be 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 a9483064435..3674f2f86d9 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 @@ -8,7 +8,7 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Input and Output Formats} +\section{Supported Formats} \label{section-formats} @@ -20,7 +20,7 @@ can be produced. -\subsection{Supported Input Formats} +\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 @@ -83,10 +83,6 @@ 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. -\pgfname\ was originally written for use with \LaTeX\ and this shows -in a number of places. Nevertheless, the plain \TeX\ support is -reasonably good. - Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex| also just include the correct |tikz.code.tex| file. @@ -94,9 +90,7 @@ also just include the correct |tikz.code.tex| file. \subsubsection{Using the Con\TeX t Format} -When using the Con\TeX t format\footnote{Note that \pgfname/\tikzname{} - is not supported by recent Con\TeX t versions (like mark IV, the - Lua\TeX-aware part of Con\TeX t).}, you say |\usemodule[pgf]| or +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| @@ -131,7 +125,8 @@ typeset. Producing the output is (conceptually) a two-stage process: \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. + 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 @@ -142,7 +137,7 @@ 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 +|.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| @@ -153,17 +148,17 @@ input and translates the letter--coordinate pairs therein into 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 where an intermediate stage. +view they behave exactly as if there was an intermediate stage. Normally, \TeX\ only produces letter--coordinate pairs as its -``output.'' This obviously makes is difficult to draw, say, a +``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 way'' the +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. @@ -204,9 +199,8 @@ exactly the same. |pdftex| or |pdflatex| command. It includes |pgfsys-common-pdf.def|. - This driver has the ``complete'' functionality. This means, - 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} @@ -221,21 +215,13 @@ exactly the same. inclusion and does not support masking. \item In plain \TeX\ mode it does not support image inclusion. - \item - For remembering of pictures (inter-picture connections) you need - to use a recent version of |pdftex| running in DVI-mode. - \item - Patterns are not (cannot) be supported. - \item - Functional shadings are not (cannot) be supported. \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 the same operations as the dvipdfm - driver, except that remembering of pictures (inter-picture - connections) always works. + |xdvipdfmx|. This driver supports largely the same operations as the + |dvipdfm| driver. \end{filedescription} \begin{filedescription}{pgfsys-vtex.def} @@ -311,17 +297,61 @@ produce Postscript output. -\subsubsection{Producing HTML / SVG Output} +\subsubsection{Producing SVG Output} + +\begin{filedescription}{pgfsys-dvisvgm.def} + This driver converts \textsc{dvi} files to \textsc{svg} file, + including text and fonts. When you select this driver, \pgfname\ + will output the required raw \textsc{svg} code for the pictures it + produces. + + Since the |graphics| package does not (yet?) support this driver + directly, there is special rule for this driver in \LaTeX: If the + option |dvisvgm| is given to the |tikz| package, this driver gets + selected (normally, the driver selected by |graphics| would be + used). For packages like |beamer| that load \pgfname\ + themselves, this means that the option |dvisvgm| should be given to + the document class. +\begin{codeexample}[code only] +% example.tex +\documentclass[dvisvgm]{minimal} + +\usepackage{tikz} + +\begin{document} +Hello \tikz [baseline] \fill [fill=blue!80!black] (0,.75ex) circle[radius=.75ex]; +\end{document} +\end{codeexample} + + And then run +\begin{codeexample}[code only] +latex example +dvisvgm example +\end{codeexample} + or better +\begin{codeexample}[code only] +lualatex --output-format=dvi example +dvisvgm example +\end{codeexample} + (This is ``better'' since it gives you access to the full power of + Lua\TeX\ inside your \TeX-file. In particular, \tikzname\ is able + to run graph drawing algorithms in this case.) + + Unlike the |tex4ht| driver below, this driver has full support of + text nodes. +\end{filedescription} -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. Using the following driver, you can ask -\pgfname\ to produce an \textsc{svg}-picture for each \pgfname\ -graphic in your text. \begin{filedescription}{pgfsys-tex4ht.def} - This is a driver file for use with the |tex4ht| program. It includes - |pgfsys-common-svg.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: @@ -338,7 +368,7 @@ graphic in your text. 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}, |Tikz| has then to guess what size the text + 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 @@ -364,7 +394,7 @@ graphic in your text. \textsc{svg} standard, you may wish to use the following options to modify the way text is handled: - \begin{key}{/tikz/tex4ht node/escape=\meta{boolean} (default |false|)} + \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 @@ -386,46 +416,46 @@ graphic in your text. simple as |$\alpha$|, this may corrupt the graphic. \begin{codeexample}[code only] -\tikz \node[draw,tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$}; +\tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$}; \end{codeexample} - When you write |node[tex4ht node/escape=true] {|\meta{text}|}|, - \tikzname\ escapes back to \textsc{html} to render the + 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 |{tikzpicture}|, should also + 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, - \tikzname\ has to guess the size of the text rendered by the + \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,tex4ht node/escape=true] +\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}{/tikz/tex4ht node/css=\meta{filename} (default |\string\jobname|)} + \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}{/tikz/tex4ht node/class=\meta{class name} (default foreignobject)} + \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}{/tikz/tex4ht node/id=\meta{id name} (default + \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|). + |tex4ht node/escape=true|). \end{key} \end{filedescription} @@ -447,7 +477,7 @@ graphic in your text. \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 hundred of small + horizontal or vertical, they are composed of hundreds of small rectangles. \item Lines of different width are supported. \item Transformations are supported. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex index bb7b9eb0400..f44b1b4ad4a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-axes.tex @@ -7,99 +7,800 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. - \section{Axes} \label{section-dv-axes} + \subsection{Overview} -To be written... +When a data point is visualized, the most obvious way of creating a +visual representation of its many attributes is to +vary \emph{where} the data point is shown. The data visualization +system uses \emph{axes} to turn data point attributes into positions +on a page. The simplest -- and most common -- use of axes is to vary +the horizontal position of data points according to one attribute and +to vary the vertical position according to another attribute. In +contrast, in a polar plot one attribute dictates the distance of the +data point from the origin and another attribute describes the +angle. From the data visualization engine's point of view, in both +cases two \emph{axes} are involved. + +In addition to specifying how the value of a certain attribute is +converted into a displacement on the page, an axis is also typically +(but not always) visualized (``drawn'') somewhere on the page. In this case, it is +also customary to add a visual representation on this axis of which +attribute values correspond to which positions on the page -- +something commonly known as \emph{ticks}. Similar to ticks, \emph{grid + lines} also indicate positions where a certain attribute has a +certain value, but instead of just indicating a single position on an +axis, a grid line goes through all points that share an attribute +value. + +In the following, in Section~\ref{section-dv-axes-main} we first have +a look at how axes can be defined and configured. As you will see, a +lot of powerful configurations are available, but you will rarely +define and configure an axis from scratch. Rather, it is more common +to use a preconfigured axis +instead. Section~\ref{section-dv-axis-systems} introduces \emph{axis + systems}, which are predefined bundles of axes. You can define your +own axis systems, but, again, in most cases it will suffice to just +use one of the many preconfigured axis systems and use a few options +to configure it so that it fits your +need. Section~\ref{section-dv-ticks-and-grids} explains how ticks and +grid lines can be configured. Again, several layers of +options allow you to configure the way ticks look and where they are +placed in great detail. + +This section documents the standard axis systems that are always +available. For polar axis systems, a special library needs to be +loaded, which is documented in Section~\ref{section-dv-polar}. + + + +\subsection{Basic Configuration of Axes} +\label{section-dv-axes-main} + +Inside the data visualization system, an \emph{axis} is roughly a +``systematic, named way of mapping an attribute to a +position on a page''. For instance, the classical ``$x$-axis'' is the +``systematic way of mapping the value of the |x| attribute of data +points to a horizontal position on the page''. An axis is \emph{not} +its visual representation (such as the horizontal line with the ticks +drawn to represent the $x$-axis), but a visual representation can be +created once an axis has been defined. + +The transformation of an attribute value (such as the value |1000000000| +for the |x| attribute) to a specific displacement of the corresponding +data point on the page involves two steps: +\begin{enumerate} +\item First, the range of possible values such as $[-5.6\cdot + 10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' + interval such as $[0\mathrm{cm},5\mathrm{cm}]$ or + $[0^\circ,180^\circ]$. \tikzname's drawing routines will only be + able to cope with values from such a ``reasonable'' interval. +\item Second, the values from the reasonable interval must be mapped + to a transformation. +\end{enumerate} +The first step is always the same for all axes, while the second +requires different strategies. For this reason, the command +|new axis base| is used to create a ``basic'' axis that has a +``scaling mapper'', whose job it is to map the range of values of a +specific attribute to a reasonable interval, but such a basic axis +does not define an actual transformation object. For this second step, +additional objects such as a |linear transformer| need to be created +separately. + + +\subsubsection{Usage} + +To create an axis, the key |new axis base| is used first. Since this key +does not create a transformation object, users typically do not use +this key directly. Rather, it is used internally by other keys +that create ``real'' axes. These keys are listed in +Section~\ref{section-dv-reference-axis-types}. + +\begin{key}{/tikz/data visualization/new axis base=\meta{axis name}} + This key defines a new axis for the current data visualization + called \meta{name}. This has two effects: + \begin{enumerate} + \item A so called \emph{scaling mapper} is created that will monitor + a certain attribute, rescale it, and map it to another + attribute. (This will be explained in detail in a moment.) + \item The \meta{axis name} is made available as a key that can be + used to configure the axis: + \begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}} + This key becomes available once |new axis base=|meta{axis name} has + been called. It will execute the \meta{options} with the path + prefix |/tikz/data visualization/axis options|. +\begin{codeexample}[code only] +[new axis base=my axis, + my axis={attribute=some attribute}] +\end{codeexample} + \end{key} + \item The \meta{axis name} becomes part of the current set of + axes. This set can be accessed through the following key: + \begin{key}{/tikz/data visualization/all axes=\meta{options}} + This key passes the \meta{options} to all axes inside the + current scope, just as if you had written \meta{some axis + name}|=|\meta{options} for each \meta{some axis name} in the + current scope, including the just-created name \meta{axis name}. + \end{key} + \end{enumerate} + There are many \meta{options} that can be passed to a newly created + axis. They are explained in the rest of this section. +\end{key} +Note the |new axis base| does \emph{not} cause attributes to be mapped to +positions on a page. Rather, special keys like |new Cartesian axis| +first use |new axis base| to create an axis and then create an internal +object that performs a linear mapping of the attribute to +positions along a vectors. + + +\subsubsection{The Axis Attribute} +\label{section-dv-axis-attribute} + +The first main job of an axis is to map the different values of some +attribute to a reasonable interval. To achieve this, the following +options are important (recall that these options are passed to the key +whose name is the name of the axis): + +\begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}} + Specifies that the axis is used to transform the data points + according the different values of the key + |/data point/|\meta{attribute}. For instance, when we create a + classical two-dimensional Cartesian coordinate system, then there + are two axes called |x axis| and |y axis| that monitor the values of + the attributes |/data point/x| and |/data point/y|, respectively: +\begin{codeexample}[code only] + [new axis base=x axis, + new axis base=y axis, + x axis={attribute=x}, + y axis={attribute=y}] +\end{codeexample} + In another example, we also create an |x axis| and a + |y axis|. However, this time, we want to plot the values of the + |/data point/time| attribute on the $x$-axis and, say, the value of + the |height| attribute on the $y$-axis: +\begin{codeexample}[code only] + [new axis base=x axis, + new axis base=y axis, + x axis={attribute=time}, + y axis={attribute=height}] +\end{codeexample} + During the data visualization, the \meta{attribute} will be + ``monitored'' during the survey phase. This means that for each data + point, the current value of |/data point/|\meta{attribute} is + examined and the minimum value of all of these values as well as the + maximum value is recorded internally. Note that this works even when + very large numbers like |100000000000| are involved. + + Here is a real-life example. The |scientific axes| create two axes, + called |x axis| and |y axis|, respectively. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + x axis={attribute=people, length=2.5cm, ticks=few}, + y axis={attribute=year}, + visualize as scatter] + data { + year, people + 1900, 100 + 1910, 200 + 1950, 200 + 1960, 250 + 2000, 150 + }; +\end{codeexample} +\end{key} -\subsection{Concepts} -\subsubsection{Axes} +\subsubsection{The Axis Attribute Range Interval} + +Once an attribute has been specified for an axis, the data +visualization engine will start monitoring this value. This means that +before anything actual visualization is done, a ``survey phase'' is +used to determine the range of values encountered for the attribute +for all data points. This range of values results in what is called +the \emph{attribute range interval}. Its minimum is the smallest value +encountered in the data and its maximum is the largest value. + +Even though the attribute range interval is computed automatically and +even though you typically do not need to worry about it, there are +some situations where you may wish to set or enlarge the attribute +range interval: +\begin{itemize} +\item You may wish to start the interval with $0$, even though the + range of values contains only positive values. +\item You may wish to slightly enlarge the interval so that, say, the + maximum is some ``nice'' value like |100| or |60|. +\end{itemize} + +The following keys can be used to influence the size of the attribute +range interval: +\begin{key}{/tikz/data visualization/axis options/include + value=\meta{list of value}} + This key ``fakes'' data points for which the attribute's values are + in the comma-separated \meta{list of values}. For instance, when you + write |include value=0|, then the attribute range interval is + guaranteed to contain |0| -- even if the actual data points are all + positive or all negative. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, all axes={length=3cm}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, all axes={length=3cm}, + visualize as line, + x axis={include value=20}, + y axis={include value=0}] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} +\end{key} -\subsubsection{Mayor, Minor, and Subminor Ticks} +\begin{key}{/tikz/data visualization/axis options/min value=\meta{value}} + This key allows you to simply set the minimum value, regardless of + which values are present in the actual data. This key should be used + with care: If there are data points for which the attribute's value + is less than \meta{value}, they will still be depicted, but + typically outside the normal visualization area. Usually, saying + |include value=|\meta{value} will achieve the same as saying + |min value=|\meta{value}, but with less danger of creating + ill-formed visualizations. +\end{key} -\subsubsection{Tick Placement Strategies} -\label{section-dv-concept-tick-placement-strategies} +\begin{key}{/tikz/data visualization/axis options/max value=\meta{value}} + Works like |min value|. +\end{key} -Consider the following problem: The data visualization engine -determines that in a -plot the $x$-values vary between $17.4$ and $34.5$. In this case, we -certainly do not want, say, ten ticks at exactly ten evenly spaced -positions starting with $17.4$ and ending with $34.5$, because this -would yield ticks at positions like $32.6$. Ticks should be placed at -``nice'' positions like $20$, $25$, and $30$. -Determining which positions are ``nice'' is somewhat difficult. In the -above example, the positions $20$, $25$, and $30$ are certainly nice, -but only three ticks may be a bit few of them. Better might be the -tick positions $17.5$, $20$, $22.5$, through to $32.5$. However, users -might prefer even numbers over fractions like $2.5$ as the stepping. +\subsubsection{Scaling: The General Mechanism} -A \emph{tick placement strategy} is a method of automatically deciding -which positions are \emph{good} for placing ticks. The data -visualization engine comes with a number of predefined strategies, see -Section~\ref{section-dv-tick-placement-strategies}, but you can also -define new ones yourself. When the data visualization is requested to -automatically determine -``good'' positions for the placement of ticks on an axis, it uses one -of several possible \emph{basic strategies}. These strategies differ -dramatically in which tick positions they will choose: For a range of -values between $5$ and $1000$, a |linear steps| strategy might place -ticks at positions $100$, $200$, through to $1000$, while an -|exponential steps| strategy would prefer the tick positions $10$, -$100$ and $1000$. The exact number and values of the tick positions -chosen by either strategy can be fine-tuned using additional options -like |step| or |about|. +The above key allows us specify which attribute should be +``monitored''. The next key is used to specify what should happen with +the observed values. -Here is an example of the different stepping chosen when one varies -the tick placement strategy: +\begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}} + The \meta{scaling spec} must have the following form: + \begin{quote} + \meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$} + \end{quote} + This means that monitored values in the interval $[s_1,s_2]$ should + be mapped to values the ``reasonable'' interval $[t_1,t_2]$, + instead. For instance, we might write +\begin{codeexample}[code only] +[y axis = {scaling = 1900 at 0cm and 2000 at 5cm}] +\end{codeexample} + in order to map dates between 1900 and 2000 to the dimension + interval $[0\mathrm{cm},5\mathrm{cm}]$. +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + x axis={attribute=people, length=2.5cm, ticks=few}, + y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm}, + visualize as scatter] + data { + year, people + 1900, 100 + 1910, 200 + 1950, 200 + 1960, 250 + 2000, 150 + }; +\end{codeexample} + So much for the basic idea. Let us now have a detailed look at what + happens. + \medskip + \textbf{Number format and the min and max keywords.} + The source values $s_1$ and $s_2$ are typically just numbers like + |3.14| or |10000000000|. However, as described in + Section~\ref{section-dv-expressions}, you can also specify + expressions like |(pi/2)|, provided that (currently) you put them in + parentheses. + + Instead of a number, you may alternatively also use the two key + words |min| and |max| for $s_1$ and/or $s_2$. In this case, |min| + evaluates to the smallest value observed for the attribute in the + data, symmetrically |max| evaluates to the largest values. For + instance, in the above example with the |year| attribute ranging + from |1900| to |2000|, the keyword |min| would stand for |1900| and + |max| for |2000|. Similarly, for the |people| attribute |min| stands + for |100| and |max| for |250|. Note that |min| and |max| can only be + used for $s_1$ and $s_2$, not for $t_1$ and $t_2$. + + A typical use of the |min| and |max| keywords is to say +\begin{codeexample}[code only] +scaling = min at 0cm and max at 5cm +\end{codeexample} + to map the complete range of values into an interval of length of + 5cm. + + The interval $[s_1,s_2]$ need not contain all values that the + \meta{attribute} may attain. It is permissible that values are less + than $s_1$ or more than $s_2$. + + \medskip + \textbf{Linear transformation of the attribute.} + As indicated earlier, the main job of an axis is to map values from + a ``large'' interval $[s_1,s_2]$ to a more reasonable interval + $[t_1,t_2]$. Suppose + that for the current data point the value of the key + |/data point/|\meta{attribute} is the number $v$. In the simplest + case, the following happens: A new value $v'$ is computed so that + $v' = t_1$ when $v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some + value in between $t_1$ and $t_2$ then $v$ is some value in between + $s_1$ and $s_2$. (Formally, in this basic case $v' = t_1 + + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.) + + Once $v'$ has been computed, it is stored in the key + |/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' + value $v'$ does not replace the value of the attribute, but it is + placed in a different key. This means that both the original value + and the more ``scaled'' values are available when the data point is + visualized. + + As an example, suppose you have written +\begin{codeexample}[code only] +[x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}] +\end{codeexample} + Now suppose that |/data point/x| equals |1200| for a data + point. Then the key |/data point/x/scaled| will be set to |22| when + the data point is being visualized. + + \medskip + \textbf{Nonlinear transformations of the attribute.} + By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the + linear transformation described above. However, in some case you may + be interested in a different kind of transformation: For example, in + a logarithmic plot, values of an attribute may range between, say, + |1| and |1000| and we want an axis of length |3cm|. So, we would + write + \begin{codeexample}[code only] +[x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}] + \end{codeexample} + Indeed, |1| will now be mapped to position |0cm| and |1000| will be + mapped to position |3cm|. Now, the value |10| will be mapped to + approximately |0.03cm| because it is (almost) at one percent between + |1| and |1000|. However, in a logarithmic plot we actually want |10| + to be mapped to the position |1cm| rather than |0.03cm| and we want + |100| to be mapped to the position |2cm|. Such a mapping a + \emph{nonlinear} mapping between the intervals. + + In order to achieve such a nonlinear mapping, the |function| key can + be used, whose syntax is described in a moment. The effect of this key is + to specify a function $f \colon \mathbb R \to \mathbb R$ like, say, + the logarithm function. When such a function is specified, the + mapping of $v$ to $v'$ is computed as follows: + \begin{align*} + v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}. + \end{align*} + + The syntax of the |function| key is described next, but you + typically will not call this key directly. Rather, you will use a + key like |logarithmic| that installs appropriate code for the + |function| key for you. + \begin{key}{/tikz/data visualization/axis options/function=\meta{code}} + The \meta{code} should specify a function $f$ that is applied + during the transformation of the interval $[s_1,s_2]$ to the + interval $[t_1,t_2]$ in the following way: When the \meta{code} is + called, the macro |\pgfvalue| will have been set to an internal + representation of the to-be-transformed value~$v$. You can then + call the commands of the math-micro-kernel of the data + visualization system, see Section~\ref{section-dv-math-kernel}, to + compute a new value. This new value must once more be stored in + |\pgfvalue|. + + The most common use of this key is to say +\begin{codeexample}[code only] +some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} +\end{codeexample} + This specifies that the function $f$ is the logarithm + function. \begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [scientific axes, visualize as smooth line] - data [format=function] { - var x : interval [1:11]; - func y = \value x*\value x; +\tikz \datavisualization + [scientific axes, + x axis={ticks={major={at={1,10,100,1000}}}, + scaling=1 at 0cm and 1000 at 3cm, + function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}, + visualize as scatter] + data [format=named] { + x={1,100,...,1000}, y={1,2,3} + }; +\end{codeexample} + Another possibility might be to use the square-root function, instead: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + x axis={ticks=few, + scaling=1 at 0cm and 1000 at 3cm, + function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}}, + visualize as scatter] + data [format=named] { + x={0,100,...,1000}, y={1,2,3} + }; +\end{codeexample} + \end{key} + + \medskip + \textbf{Default scaling.} + When no scaling is specified, it may seem natural to use $[0,1]$ + both as the source and the target interval. However, this would not + work when the logarithm function is used as transformations: In this + case the logarithm of zero would be computed, leading to an + error. Indeed, for a logarithmic axis it is far more natural to use + $[1,10]$ as the source interval and $[0,1]$ as the target interval. + + For these reasons, the default value for the |scaling| that is used + when no value is specified explicitly can be set using a special + key: + \begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}} + The \meta{text} is used as |scaling| whenever no other scaling is + specified. This key is mainly used when a transformation function + is set using |function|; normally, you will not use this key + directly. + \end{key} +\end{key} + +Most of the time, you will not use neither the |scaling| nor the +|function| key directly, but rather you will use one of the following +predefined styles documented in the following. + + +\subsubsection{Scaling: Logarithmic Axes} + +\begin{key}{/tikz/data visualization/axis options/logarithmic} + When this key is used with an axis, three things happen: + \begin{enumerate} + \item The transformation |function| of the axis is setup to the + logarithm. + \item The strategy for automatically generating ticks and grid lines + is set to the |exponential strategy|, see + Section~\ref{section-dv-exponential-strategy} for details. + \item The default scaling is setup sensibly. + \end{enumerate} + All told, to turn an axis into a logarithmic axis, you just need to + add this option to the axis. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [scientific axes, + x axis={logarithmic}, + y axis={logarithmic}, + visualize as line] + data [format=function] { + var x : interval [0.01:100]; + func y = \value x * \value x; + }; +\end{codeexample} + Note that this will work with any axis, + including, say, the degrees on a polar axis: +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes, + angle axis={logarithmic, scaling=1 at 0 and 90 at 90}, + radius axis={scaling=0 at 0cm and 100 at 3cm}, + visualize as scatter] + data [format=named] { + angle={1,10,...,90}, radius={1,10,...,100} + }; +\end{codeexample} +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes, + angle axis={degrees}, + radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm}, + visualize as scatter] + data [format=named] { + angle={1,10,...,90}, radius={1,10,...,100} + }; +\end{codeexample} +\end{key} + + + +\subsubsection{Scaling: Setting the Length or Unit Length} + +\begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}} + Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The + effect is that the range of all values of the axis's attribute will + be mapped to an interval of exact length \meta{dimension}. + +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + x axis={length=3cm}, + y axis={length=2cm}, + all axes={ticks=few}, + visualize as line] + data { + x, y + 10, 10 + 20, 20 + 15, 30 + 13, 20 }; -\end{tikzpicture} -\qquad -\begin{tikzpicture} - \datavisualization [scientific axes, visualize as smooth line, - y axis={exponential steps}, - x axis={ticks={quarter about strategy}}, - ] - data [format=function] { - var x : interval [1:11]; - func y = \value x*\value x; +\end{codeexample} +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + x axis={length=3cm}, + y axis={length=4cm}, + all axes={ticks=few}, + visualize as line] + data { + x, y + 10, 10 + 20, 20 + 15, 30 + 13, 20 + }; +\end{codeexample} + +\end{key} + +\begin{key}{/tikz/data visualization/axis + options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}} + Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other + words, this key allows you to specify how long a single unit should + be. This key is particularly useful when you wish to ensure that the + same scaling is used across multiple axes or pictures. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={ticks=few, unit length=1mm}, + visualize as line] + data { + x, y + 10, 10 + 40, 20 + 15, 30 + 13, 20 }; +\end{codeexample} + The optional |per |\meta{number}| units| allows you to apply more + drastic scaling. Suppose that you want to plot a graph where one + billion corresponds to one centimeter. Then the unit length would be + need to be set to a hundredth of a nanometer -- much too small for + \TeX\ to handle as a dimension. In this case, you can write + |unit length=1cm per 1000000000 units|: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + x axis={unit length=1mm per 1000000000 units, ticks=few}, + visualize as line] + data { + x, y + 10000000000, 10 + 40000000000, 20 + 15000000000, 30 + 13000000000, 20 + }; +\end{codeexample} +\end{key} +\begin{key}{/tikz/data visualization/axis + options/power unit length=\meta{dimension}} + This key is used in conjunction with the |logarithmic| setting. It + cases the |scaling| to be set to + |1 at 0cm and 10 at |\meta{dimension}. This causes a ``power unit,'' + that is, one power of ten in a logarithmic plot, to get a length of + \meta{dimension}. Again, this key is useful for ensuring that the + same scaling is used across multiple axes or pictures. +\begin{codeexample}[width=8cm] +\tikz \datavisualization + [scientific axes, + y axis={logarithmic, power unit length=1mm, grid}, + visualize as line] + data { + x, y + 0, 0.0000000001 + 1, 1 + 2, 100000 + 3, 100000000000 + 4, 10000000000000000000000000000000 + 5, 500000000 + 6, 5000000000000000000 + }; +\end{codeexample} +\end{key} + + + +\subsubsection{Axis Label} + +An axis can have a \emph{label}, which is a textual representation of +the attribute according to which the axis varies the position of the +page. You can set the attribute using the following key: + +\begin{key}{/tikz/data visualization/axis + options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|} + (default \normalfont axis's label in math mode)} + This key sets the label of an axis to \meta{text}. This text will + typically be placed inside a |node| and the \meta{options} can be + used to further configure the way this node is rendered. The + \meta{options} will be executed with the path prefix + |/tikz/data visualization/|, so you need to say |node style| to + configure the styling of a node, see Section~\ref{section-dv-style}. +\begin{codeexample}[] +\tikz \datavisualization [ + scientific axes, + x axis = {label, length=2.5cm}, + y axis = {label={[node style={fill=blue!20}]{$x^2$}}}, + visualize as smooth line] + data [format=function] { + var x : interval [-3:5]; + func y = \value x * \value x; + }; +\end{codeexample} +\end{key} + +Note that using the |label| key does not actually cause a node to be +created, because it is somewhat unclear where the label should be +placed. Instead, the |visualize label| key is used (typically +internally by an axis system) to show the label at some sensible +position. This key is documented in +Section~\ref{section-dv-visualize-label}. + + + +\subsubsection{Reference: Axis Types} + +\label{section-dv-reference-axis-types} + +As explained earlier, when you use |new axis base| to create a new axis, +a powerful scaling and attribute mapping mechanism is installed, but +no mapping of values to positions on the page is performed. For this, +a \emph{transformation object} must be installed. The following keys +take care of this for you. Note, however, that even these keys do not +cause a visual representation of the axis to be added to the +visualization -- this is the job of an axis system, see +Section~\ref{section-dv-axis-systems}. + +\begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}} + This key creates a new ``Cartesian'' axis, named \meta{name}. For + such an axis, the (scaled) values of the axis's attribute are + transformed into a displacement on the page along a straight + line. The following key is used to configure in which ``direction'' + the axis points: + \begin{key}{/tikz/data visualization/axis options/unit + vector=\meta{coordinate} (initially {(1pt,0pt)})} + Recall that an axis takes the values of an attribute and rescales + them so that they fit into a ``reasonable'' interval + $[t_1,t_2]$. Suppose that $v'$ is the rescaled dimension in (\TeX) + points. Then when the data point is visualized, the coordinate + system will be shifted by $v'$ times the \meta{coordinate}. + + As an example, suppose that you have said + |scaling=0 and 10pt and 50 and 20pt|. Then when the underlying + attribute has the value |25|, it will be mapped to a $v'$ of $15$ + (because |25| lies in the middle of |0| and |50| and |15pt| lies + in the middle of |10pt| and |20pt|). This, in turn, causes the + data point to be displaced by $15$ times the \meta{coordinate}. + + The bottom line is that the \meta{coordinate} should usually + denote a point that is at distance |1pt| from the origin and that + points into the direction of the axis. +\begin{codeexample}[] +\begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + + \datavisualization + [new Cartesian axis=x axis, x axis={attribute=x}, + new Cartesian axis=y axis, y axis={attribute=y}, + x axis={unit vector=(0:1pt)}, + y axis={unit vector=(60:1pt)}, + visualize as scatter] + data { + x, y + 0, 0 + 1, 0 + 2, 0 + 1, 1 + 2, 1 + 1, 1.5 + 2, 1.5 + }; \end{tikzpicture} \end{codeexample} +\end{key} +\end{key} -\subsubsection{Grids} +\subsection{Axis Systems} +\label{section-dv-axis-systems} -\subsection{Usage} +An \emph{axis system} is, as the name suggests, a whole family of axes +that act in concert. For example, in the ``standard'' axis system there +is a horizontal axis called the $x$-axis that monitors the |x| +attribute (by default, you can change this easily) and a vertical axis +called the $y$-axis. Furthermore, a certain number of ticks are added +and labels are placed at sensible positions. -\subsection{Reference: Standard Axis Systems} +\subsubsection{Usage} -In this section the axis system commonly used in data visualizations -are described. +Using an axis system is usually pretty easy: You just specify a key +like |scientific axes| and the necessary axes get initialized with +sensible default values. You can then start to modify these default +values, if necessary. -\subsubsection{Scientific Axis Systems} +First, you can (and should) set the attributes to which the difference +axes refer. For instance, if the |time| attribute is plotted along the +$x$-axis, you would write +\begin{codeexample}[code only] +x axis = {attribute = time} +\end{codeexample} + +Second, you may wish to modify the lengths of the axes. For this, you +can use keys like |length| or further keys as described in the +references later on. + +Third, you may often wish to modify how many ticks and grid lines are +shown. By default, no grid lines are shown, but you can say the +following in order to cause grid lines to be shown: +\begin{codeexample}[code only] +all axes={grid} +\end{codeexample} +Naturally, instead of |all axes| you can also specify a single axis, +causing only grid lines to be shown for this axis. +In order to change the number of ticks that are shown, you can say +\begin{codeexample}[code only] +all axes={ticks=few} +\end{codeexample} +or also |many| instead of |few| or even |none|. Far more fine-grained +control over the tick placement and rendering is possible, +see Section~\ref{section-dv-ticks-and-grids} for details. + +Fourth, consider adding units (like ``cm'' for centimeters or +``$\mathrm m/\mathrm s^2$'' for acceleration) to your ticks: +\begin{codeexample}[code only] +x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}} +\end{codeexample} + + +Finally, consider adding labels to your axes. For this, use the label +option: +\begin{codeexample}[code only] +x axes={time $t$ (ms)}, y axis={distance $d$ (mm)} +\end{codeexample} + +Here is an example that employs most of the above features: + +\begin{codeexample}[width=8.5cm] +\tikz \datavisualization [ + scientific axes=clean, + x axis={attribute=time, ticks={tick unit=ms}, + label={elapsed time}}, + y axis={attribute=v, ticks={tick unit=m/s}, + label={speed of disc}}, + all axes=grid, + visualize as line] +data { + time, v + 0, 0 + 1, 0.001 + 2, 0.002 + 3, 0.004 + 4, 0.0035 + 5, 0.0085 + 6, 0.0135 +}; +\end{codeexample} -\begin{key}{/tikz/data visualization/scientific axes} + + +\subsubsection{Reference: Scientific Axis Systems} + +\begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}} This key installs a two-dimensional coordinate system based on the attributes |/data point/x| and |/data point/y|. -\begin{codeexample}[] +\begin{codeexample}[width=7cm] \begin{tikzpicture} - \datavisualization [scientific axes, visualize as smooth line] + \datavisualization [scientific axes, + visualize as smooth line] data [format=function] { var x : interval [0:100]; func y = sqrt(\value x); @@ -113,7 +814,14 @@ are described. be. The name |scientific axes| is intended to indicate that this axis system is often used in scientific publications. - Note, however, that this axis system will always distort the + You can use the \meta{options} to fine tune the axis system. The + \meta{options} will be executed with the following path prefix: +\begin{codeexample}[code only] +/tikz/data visualization/scientific axes +\end{codeexample} + All keys with this prefix can thus be passed as \meta{options}. + + This axis system will always distort the relative magnitudes of the units on the two axis. If you wish the units on both axes to be equal, consider directly specifying the unit length ``by hand'': @@ -149,20 +857,45 @@ are described. origin. The maximum value is at the top of the axis. \item Lines (forming a frame) are depicted at the minimum and maximum values of the axes in 50\% black. - \item Ticks are drawn `` on the outside'' of the frame so that they - interfere as little as possible with the data. - \item Tick labels and axis labels (if present) are drawn left and - below. \end{itemize} + + The following keys are executed by default as options: |outer ticks| + and |standard labels|. + + You can use the following style to overrule the defaults: + + \begin{stylekey}{/tikz/data visualization/every scientific axes} + \end{stylekey} +\end{key} + +The keys described in the following can be used to fine-tune the way +the scientific axis system is rendered. + +\begin{key}{/tikz/data visualization/scientific axes/outer ticks} + This causes the ticks to be drawn `` on the outside'' of the frame + so that they interfere as little as possible with the data. It is + the default. + +\begin{codeexample}[width=7cm] +\begin{tikzpicture} + \datavisualization [scientific axes=outer ticks, + visualize as smooth line] + data [format=function] { + var x : interval [-12:12]; + func y = \value x*\value x*\value x; + }; +\end{tikzpicture} +\end{codeexample} \end{key} -\begin{key}{/tikz/data visualization/scientific inner axes} +\begin{key}{/tikz/data visualization/scientific axes/inner ticks} This axis system works like |scientific axes|, only the ticks are on the ``inside'' of the frame. -\begin{codeexample}[] +\begin{codeexample}[width=7cm] \begin{tikzpicture} - \datavisualization [scientific inner axes, visualize as smooth line] + \datavisualization [scientific axes=inner ticks, + visualize as smooth line] data [format=function] { var x : interval [-12:12]; func y = \value x*\value x*\value x; @@ -175,16 +908,17 @@ are described. seen in the following example: \begin{codeexample}[] \begin{tikzpicture} - \datavisualization [scientific inner axes, scientific axes/width=3.2cm, + \datavisualization [scientific axes={inner ticks, width=3.2cm}, + style sheet=cross marks, visualize as scatter/.list={a,b}] - data [a] { + data [set=a] { x, y 0, 0 1, 1 0.5, 0.5 2, 1 } - data [b] { + data [set=b] { x, y 0.05, 0 1.5, 1 @@ -196,20 +930,19 @@ are described. \end{key} -\begin{key}{/tikz/data visualization/scientific clean axes} - This axis system is another version of |scientific axes|. However, the - axes and the ticks are completely removed from the actual data, +\begin{key}{/tikz/data visualization/scientific axes/clean} + The axes and the ticks are completely removed from the actual data, making this axis system especially useful for scatter plots, but also for most other scientific plots. -\begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [scientific clean axes, visualize as smooth line] - data [format=function] { - var x : interval [-12:12]; - func y = \value x*\value x*\value x; - }; -\end{tikzpicture} +\begin{codeexample}[width=7.5cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as smooth line] +data [format=function] { + var x : interval [-12:12]; + func y = \value x*\value x*\value x; +}; \end{codeexample} The distance of the axes from the actual plot is given by the @@ -220,72 +953,68 @@ are described. For all scientific axis systems, different label placement strategies can be specified. They are discussed in the following. - -\begin{key}{/tikz/data visualization/scientific axes standard labels} +\begin{key}{/tikz/data visualization/scientific axes/standard labels} As the name suggests, this is the standard placement strategy. The label of the $x$-axis is placed below the center of the $x$-axis, the label of the $y$-axis is rotated by $90^\circ$ and placed left of the center of the $y$-axis. -\begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [scientific clean axes, - visualize as smooth line, - scientific axes standard labels, - x axis={label=degree $d$, ticks={tick unit=${}^\circ$}}, - y axis={label=$\sin d$}] - data [format=function] { - var x : interval [-10:10] samples 10; - func y = sin(\value x); - }; -\end{tikzpicture} +\begin{codeexample}[width=8cm] +\tikz \datavisualization + [scientific axes={clean, standard labels}, + visualize as smooth line, + x axis={label=degree $d$, + ticks={tick unit={}^\circ}}, + y axis={label=$\sin d$}] +data [format=function] { + var x : interval [-10:10] samples 10; + func y = sin(\value x); +}; \end{codeexample} \end{key} -\begin{key}{/tikz/data visualization/scientific axes upright labels} +\begin{key}{/tikz/data visualization/scientific axes/upright labels} Works like |scientific axes standard labels|, only the label of the $y$-axis is not rotated. -\begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [scientific clean axes, - visualize as smooth line, - scientific axes upright labels, - x axis={label=degree $d$, ticks={tick unit=${}^\circ$}}, - y axis={label=$\cos d$, - ticks={style={/pgf/number format/.cd,precision=4,fixed zerofill}}}] - data [format=function] { - var x : interval [-10:10] samples 10; - func y = cos(\value x); - }; -\end{tikzpicture} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes={clean, upright labels}, + visualize as smooth line, + x axis={label=degree $d$, + ticks={tick unit={}^\circ}}, + y axis={label=$\cos d$, include value=1, + ticks={style={ + /pgf/number format/precision=4, + /pgf/number format/fixed zerofill}}}] +data [format=function] { + var x : interval [-10:10] samples 10; + func y = cos(\value x); +}; \end{codeexample} \end{key} -\begin{key}{/tikz/data visualization/scientific axes end labels} +\begin{key}{/tikz/data visualization/scientific axes/end labels} Places the labels at the end of the $x$- and the $y$-axis, similar to the axis labels of a school book axis system. -\begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [scientific clean axes, - visualize as smooth line, - scientific axes end labels, - x axis={label=degree $d$, ticks={tick unit=${}^\circ$}}, - y axis={label=$\tan d$}] - data [format=function] { - var x : interval [-10:10] samples 10; - func y = tan(\value x); - }; -\end{tikzpicture} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes={clean, end labels}, + visualize as smooth line, + x axis={label=degree $d$, + ticks={tick unit={}^\circ}}, + y axis={label=$\tan d$}] +data [format=function] { + var x : interval [-80:80]; + func y = tan(\value x); +}; \end{codeexample} \end{key} +\subsubsection{Reference: School Book Axis Systems} - -\subsubsection{School Book Axis Systems} - -\begin{key}{/tikz/data visualization/school book axes} +\begin{key}{/tikz/data visualization/school book axes=\meta{options}} This axis system is intended to ``look like'' the coordinate systems often used in school books: The axes are drawn in such a way that they intersect to origin. Furthermore, no automatic @@ -313,21 +1042,39 @@ can be specified. They are discussed in the following. The stepping of the ticks is one unit by default. Using keys like |ticks=some| may help to give better steppings. -\end{key} - + + The \meta{options} are executed with the key itself as path + prefix. Thus, the following subkeys are permissible options: + \begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}} + Sets the scaling so that 1\,cm corresponds to \meta{value} + units. At the same time, the stepping of the ticks will also be + set to \meta{value}. +\begin{codeexample}[] +\begin{tikzpicture} + \datavisualization [school book axes={unit=10}, + visualize as smooth line, + clean ticks, + x axis={label=$x$}, + y axis={label=$f(x)$}] + data [format=function] { + var x : interval [-20:20]; + func y = \value x*\value x/10; + }; +\end{tikzpicture} +\end{codeexample} + \end{key} -\begin{key}{/tikz/data visualization/school book axes standard labels} - This key makes the label of the $x$-axis appear at the right end of - this axis and it makes the label of the $y$-axis appear at the top - of the $y$-axis. + \begin{key}{/tikz/data visualization/school book axes/standard labels} + This key makes the label of the $x$-axis appear at the right end of + this axis and it makes the label of the $y$-axis appear at the top + of the $y$-axis. - Currently, this is the only supported placement strategy for the - school book axis system. + Currently, this is the only supported placement strategy for the + school book axis system. \begin{codeexample}[] \begin{tikzpicture} - \datavisualization [school book axes, + \datavisualization [school book axes={standard labels}, visualize as smooth line, - school book axes standard labels, clean ticks, x axis={label=$x$}, y axis={label=$f(x)$}] @@ -337,13 +1084,12 @@ can be specified. They are discussed in the following. }; \end{tikzpicture} \end{codeexample} + \end{key} \end{key} - - -\subsubsection{Advanced: Underlying Cartesian Axis Systems} +\subsubsection{Advanced Reference: Underlying Cartesian Axis Systems} The axis systems described in the following are typically not used directly by the user. The systems setup \emph{directions} for several @@ -418,116 +1164,249 @@ positions. -\subsection{Reference: Tick Placement Strategies} -\label{section-dv-tick-placement-strategies} +\subsection{Ticks and Grids} +\label{section-dv-ticks-and-grids} + + +\subsubsection{Concepts} + +A \emph{tick} is a small visual indication on an axis of the value of +the axis's attribute at the position where the tick is shown. A tick +may be accompanied additionally by a textual representation, but it +need not. A \emph{grid line} is similar to a tick, but it is not an +indication on the axis, but rather a whole line that indicates all +positions where the attribute has a certain value. Unlike ticks, +grid lines (currently) are not accompanied by a textual +representation. + +Just as for axes, the data visualization system decouples the +specification of which ticks are present \emph{in principle} from +where they are visualized. In the following, I describe how you +specify which ticks and grid lines you would like to be drawn and how +they should look like (their styling). The axis system of your choice +will then visualize the ticks at a sensible position for the chosen +system. For details on how to change where whole axis is shown along +with its ticks, see Section~\ref{section-dv-visualize-ticks}. + +Specifying which ticks you are interested in is done as follows: +First, you use |ticks| key (or, for specifying which grid lines should +be present, the |grid| key). This key takes several possible options, +described in detail in the following, which have different effects: +\begin{enumerate} +\item Keys like |step=10| or |minor steps between steps| cause a + ``semi-automatic'' computation of possible steps. Here, you + explicitly specify the stepping of steps, but the first stepping and + their number are computed automatically according to the range of + possible values for the attribute. +\item Keys like |few|, |some|, or |many| can be passed to |ticks| in + order to have \tikzname\ compute good tick positions + automatically. This is usually what you want to happen, which is why + most axis system will implicitly say |ticks={some}|. +\item Keys like |at| or |also at| provide ``absolute control'' over + which ticks or grid lines are shown. For these keys, you can not only + specify at what value a tick should be shown, but also its styling + and also whether it is a major, minor, or subminor tick or grid line. +\end{enumerate} + +In the following, the main keys |ticks| and |grids| are documented +first. Then the different kinds of ways of specifying where ticks or +grid lines should be shown are explained. + + +\subsubsection{The Main Options: Tick and Grid} + +\begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} + (default some)} + This key can be passed to an axis in order to configure which ticks + are present for the axis. The possible \meta{options} include, for + instance, keys like |step|, which is used to specify a stepping for + the ticks, but also keys like |major| or |minor| for specifying the + positions of major and minor ticks in detail. The list of possible + options is described in the rest of this section. + + Note that the |ticks| option will only configure which ticks should + be shown in principle. The actual rendering is done only when the + |visualize ticks| key is used, documented in + Section~\ref{section-dv-visualize-ticks}, which is typically done + only internally by an axis system. + + The \meta{options} will be executed with the path prefix + |/tikz/data visualization/|. When the |ticks| key is used multiple + times for an axis, the \meta{options} accumulate. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, visualize as line, + x axis={ticks={step=24, minor steps between steps=3}, + label=hours}] + data { + x, y + 0, 0 + 10, 0 + 20, 0.5 + 30, 0.75 + 40, 0.7 + 50, 0.6 + 60, 0.5 + 70, 0.45 + 80, 0.47 + }; +\end{codeexample} +\end{key} -As described in \ref{section-dv-concept-tick-placement-strategies}, -it is not a trivial task for the data visualization engine to -correctly automatically determine good positions for the placement of -ticks on axes. When the values on an axis range between, say, $17.4$ -and $34.5$, it is somewhat unclear where ticks should be placed. +\begin{key}{/tikz/data visualization/axis options/grid=\meta{options} + (default at default ticks)} + This key is similar to |ticks|, only it is used to configure where + grid lines should be shown rather than ticks. In particular, the + options that can be passed to the |ticks| key can also be passed to + the |grid| key. Just like |ticks|, the \meta{options} only specify + which grid lines should be drawn in principle; it is the job of the + |visualize grid| key to actually cause any grid lines to be shown. + + If you do not specify any \meta{options}, the default text + |at default ticks| is used. This option causes grid lines to be + drawn at all positions where ticks are shown by default. Since this + usually exactly what you would like to happen, most of the time you + just need to |all axes=grid| to cause a grid to be shown. +\end{key} +\begin{key}{/tikz/data visualization/axis options/ticks and grid=\meta{options}} + This key passes the \meta{options} to both the |ticks| key and also + to the |grid| key. This is useful when you want to specify some + special points explicitly where you wish a tick to be shown and also + a grid line. +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + visualize as smooth line, + all axes= {grid, unit length=1.25cm}, + y axis={ ticks=few }, + x axis={ ticks=many, ticks and grid={ major also at={(pi/2) as $\frac{\pi}{2}$}}}] + data [format=function] { + var x : interval [-pi/2:3*pi] samples 50; + func y = sin(\value x r); + }; +\end{codeexample} +\end{key} -\subsubsection{Predefined Strategies} -The following strategies are always available: +\subsubsection{Semi-Automatic Computation of Tick and Grid Line Positions} +\label{section-dv-concept-tick-placement-strategies} -\begin{key}{/tikz/data visualization/axis options/linear steps} - This strategy placed ticks at positions that are evenly spaced by - the current value of |step|. +Consider the following problem: The data visualization engine +determines that in a plot the $x$-values vary between $17.4$ and +$34.5$. In this case, we +certainly do not want, say, ten ticks at exactly ten evenly spaced +positions starting with $17.4$ and ending with $34.5$, because this +would yield ticks at positions like $32.6$. Ticks should be placed at +``nice'' positions like $20$, $25$, and $30$. - In detail, the following happens: Let $a$ be the minimum value of the - data values along the axis and let $b$ be the maximum. Let the - current \emph{stepping} be $s$ (the stepping is set using the |step| - option, see below) and let the current \emph{phasing} be $p$ (set - using the |phase|) option. Then ticks are placed all positions - $i\cdot s + p$ that lie in the interval $[a,b]$, where $i$ ranges - over all integers. +Determining which positions are ``nice'' is somewhat difficult. In the +above example, the positions $20$, $25$, and $30$ are certainly nice, +but only three ticks may be a bit few of them. Better might be the +tick positions $17.5$, $20$, $22.5$, through to $32.5$. However, users +might prefer even numbers over fractions like $2.5$ as the stepping. - The tick positions computed in the way described above are - \emph{mayor} step positions. In addition to these, if the key - |minor steps between steps| is set to some number $n$, then $n$ many - minor ticks are introduced between each two mayor ticks (and also - before and after the last mayor tick, provided the values still lie - in the interval $[a,b]$). Note that is $n$ is $1$, then one minor tick - will be added in the middle between any two mayor ticks. Use a value - of $9$ (not $10$) to partition the interval between two mayor ticks - into ten equally sized minor intervals. +A \emph{tick placement strategy} is a method of automatically deciding +which positions are \emph{good} for placing ticks. The data +visualization engine comes with a number of predefined strategies, but +you can also define new ones yourself. When the data visualization is +requested to automatically determine +``good'' positions for the placement of ticks on an axis, it uses one +of several possible \emph{basic strategies}. These strategies differ +dramatically in which tick positions they will choose: For a range of +values between $5$ and $1000$, a |linear steps| strategy might place +ticks at positions $100$, $200$, through to $1000$, while an +|exponential steps| strategy would prefer the tick positions $10$, +$100$ and $1000$. The exact number and values of the tick positions +chosen by either strategy can be fine-tuned using additional options +like |step| or |about|. + +Here is an example of the different stepping chosen when one varies +the tick placement strategy: \begin{codeexample}[] \begin{tikzpicture} - \datavisualization - [scientific inner axes, scientific axes/width=3cm, - x axis={ticks={step=3, minor steps between steps=2}}, - y axis={ticks={step=.36}}, - visualize as scatter] - data { - x, y - 17, 30 - 34, 32 + \datavisualization [scientific axes, visualize as smooth line] + data [format=function] { + var x : interval [1:11]; + func y = \value x*\value x; }; \end{tikzpicture} -\end{codeexample} -\end{key} - -\begin{key}{/tikz/data visualization/axis options/exponential steps} - This strategy produces ticks at positions that are appropriate for - logarithmic plots. It is automatically selected when you use the - |logarithmic| option with an axis. - - In detail, the following happens: As for |linear steps| let numbers - $a$, $b$, $s$, and $p$ be given. Then, mayor ticks are placed at all - positions $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i - \in \mathbb Z$. - - The minor steps are added in the same way as for |linear steps|. In - particular, they interpolate \emph{linearly} between mayor steps. - -\begin{codeexample}[] +\qquad \begin{tikzpicture} - \datavisualization - [scientific axes, - x axis={logarithmic, length=2cm, ticks={step=1.5}}, - y axis={logarithmic, ticks={step=1, minor steps between steps=9}}, - visualize as scatter] - data { - x, y - 1, 10 - 1000, 1000000 + \datavisualization [scientific axes, visualize as smooth line, + y axis={exponential steps}, + x axis={ticks={quarter about strategy}}, + ] + data [format=function] { + var x : interval [1:11]; + func y = \value x*\value x; }; \end{tikzpicture} \end{codeexample} -\end{key} - - - -\subsubsection{Choosing a Stepping Explicitly} +Two strategies are always available: |linear steps|, which yields +(semi)automatic ticks are evenly spaced positions, and +|exponential steps|, which yields (semi)automatic steps at positions +at exponentially increasing positions -- which is exactly what is +needed for logarithmic plots. These strategies are details in +Section~\ref{section-dv-strategies}. The following options are used to configure tick placement strategies like |linear steps|. Unlike the basic choice of a placement strategy, which is an axis option, the following should be passed to the option -|ticks| or |grid| only.. So, you would write -things like |x axis={ticks={step=2}}|, but |x axis=linear steps|. +|ticks| or |grid| only. So, you would write +things like |x axis={ticks={step=2}}|, but |x axis={linear steps}|. \begin{key}{/tikz/data visualization/step=\meta{value} (initially 1)} The value of this key is used to determine the spacing of the major ticks. The key is used by the |linear steps| and |exponential steps| - strategies described above, see the explanations there. + strategies, see the explanations in + Section~\ref{section-dv-strategies} for details. Basically, all + ticks are placed at all multiples of \meta{value} that lie in the + attribute range interval. +\begin{codeexample}[] +\tikz \datavisualization [ + school book axes, visualize as smooth line, + y axis={ticks={step=1.25}}, + ] + data [format=function] { + var x : interval [0:3]; + func y = \value x*\value x/2; + }; +\end{codeexample} \end{key} \begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)} - As for |step|, see the explanation of |linear steps|. + Specifies that between any two major steps (whose positions are + specified by the |step| key), there should be \meta{number} many + minor steps. Note that the default of |9| is exactly the right + number so that each interval between two minor steps is exactly a + tenth of the size of a major step. See also + Section~\ref{section-dv-strategies} for further details. +\begin{codeexample}[] +\begin{tikzpicture} + \datavisualization [school book axes, visualize as smooth line, + x axis={ticks={minor steps between steps=3}}, + y axis={ticks={minor steps between steps}}, + ] + data [format=function] { + var x : interval [-1.5:1.5]; + func y = \value x*\value x; + }; +\end{tikzpicture} +\end{codeexample} \end{key} \begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)} - As for |step|, see the explanation of |linear steps|. + See Section~\ref{section-dv-strategies} for details on how the phase + of steps influences the tick placement. \end{key} -\subsubsection{Choosing a Stepping Automatically} +\subsubsection{Automatic Computation of Tick and Grid Line Positions} The |step| option gives you ``total control'' over the stepping of ticks on an axis, but you often do not know the correct stepping in @@ -599,8 +1478,8 @@ to request about four ticks to be placed on the $x$-axis. perpendicular={ attribute=perp, unit vector={(1pt,0pt)}, - include values=0, - include values=1 + include value=0, + include value=1 } } } @@ -617,8 +1496,8 @@ to request about four ticks to be placed on the $x$-axis. one dimensional axis, axis={ ticks={about=\about}, - include values=0, - include values=\max + include value=0, + include value=\max } ]; @@ -630,7 +1509,7 @@ to request about four ticks to be placed on the $x$-axis. \end{tikzpicture} } - The net effect of all this is that for the default strategy, the + The net effect of all this is that for the default strategy the only valid stepping are the values $1$, $2$, $2.5$ and $5$ and every value obtainable by multiplying one of these values by a power of ten. The following example shows the effects of, first, setting @@ -678,8 +1557,8 @@ to request about four ticks to be placed on the $x$-axis. axis={ logarithmic, ticks={about=3}, - include values=1, - include values=1e\max + include value=1, + include value=1e\max } ]; \end{scope} @@ -714,6 +1593,13 @@ to request about four ticks to be placed on the $x$-axis. \showstrategy{half about strategy} \end{key} + \begin{key}{/tikz/data visualization/decimal about strategy} + The only permissible value for $m'$ is $1$. This is an even more + radical version of the previous strategy. + + \showstrategy{decimal about strategy} + \end{key} + \begin{key}{/tikz/data visualization/quarter about strategy} Permissible values for $m'$ are: $1$, $2.5$, and $5$. @@ -747,10 +1633,947 @@ to request about four ticks to be placed on the $x$-axis. +\subsubsection{Manual Specification of Tick and Grid Line Positions} + +The automatic computation of ticks and grid lines will usually do a +good job, but not always. For instance, you might wish to have ticks +exactly at, say, prime numbers or at Fibonacci numbers or you might +wish to have an additional tick at $\pi$. In these cases you need more +direct control over the specification of tick positions. + +First, it is important to understand that the data visualization +system differentiates between three kinds of +ticks and grid lines: major, minor, and subminor. The major ticks are +the most prominent ticks where, typically, a textual representation of +the tick is shown; and the major grid lines are the thickest. The +minor ticks are smaller, more numerous, and lie between major +ticks. They are used, for instance, to indicate positions in the +middle between major ticks or at all integer positions between major +ticks. Finally, subminor ticks are even smaller than minor ticks and +they lie between minor ticks. + +Four keys are used to configure the different kinds: + +\begin{key}{/tikz/data visualization/major=\meta{options}} + The key can be passed as an option to the |ticks| key and also to + the |grid| key, which in turn is passed as an option to an axis. The + \meta{options} passed to |major| specify at which positions + major ticks/grid lines should be shown (using the |at| option and + |also at| option) and also any special styling. The different + possible options are described later in this section. +\begin{codeexample}[] +\tikz \datavisualization + [ school book axes, visualize as smooth line, + x axis={ticks={major={at={1, 1.5, 2}}}}] + data [format=function] { + var x : interval [-1.25:2]; + func y = \value x * \value x / 2; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/minor=\meta{options}} + Like |major|, only for minor ticks/grid lines. +\begin{codeexample}[] +\tikz \datavisualization + [ school book axes, visualize as smooth line, + x axis={grid={minor={at={1, 1.5, 2}}}}] + data [format=function] { + var x : interval [-1.25:2]; + func y = \value x * \value x / 2; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/subminor=\meta{options}} + Like |major|, only for subminor ticks/grid lines. +\end{key} + + +\begin{key}{/tikz/data visualization/common=\meta{options}} + This key allows you to specify \meta{options} that apply to |major|, + |minor| and |subminor| alike. It does not make sense to use |common| + to specify positions (since you typically do not want both a major + and a minor tick at the same position), but it can be useful to + configure, say, the size of all kinds of ticks: +\begin{codeexample}[] +\tikz \datavisualization + [ school book axes, visualize as smooth line, + x axis={ticks={minor steps between steps, common={low=0}}} ] + data [format=function] { + var x : interval [-1.25:2]; + func y = \value x * \value x / 2; + }; +\end{codeexample} +\end{key} + + +The following keys can now be passed to the |major|, |minor|, and +|subminor| keys to specify where ticks or grid lines should be shown: + +\begin{key}{/tikz/data visualization/at=\meta{list}} + Basically, the \meta{list} must be a list of values that is + processed with the |\foreach| macro (thus, it can contain ellipses + to specify ranges of value). Empty values are skipped. + + The effect of passing |at| to a |major|, |minor|, or |subminor| key + is that ticks or grid lines on the axis will be placed exactly at + the values in \meta{list}. Here is an example: +\begin{codeexample}[] +\tikz \datavisualization + [ school book axes, visualize as smooth line, + x axis={ticks={major={at={-1,0.5,(pi/2)}}}}] + data [format=function] { + var x : interval [-1.25:2]; + func y = \value x * \value x / 2; + }; +\end{codeexample} + When this option is used, any previously specified tick positions + are overwritten by the values in \meta{list}. Automatically computed + ticks are also overwritten. Thus, this option gives you complete + control over where ticks should be placed. + + Normally, the individual values inside the \meta{list} are just + numbers that are specified in the same way as an attribute + value. However, such a value may also contain the keyword |as|, + which allows you so specify the styling of the tick in + detail. Section~\ref{section-dv-ticks-styling} details how this + works. + + It is often a bit cumbersome that one has to write things like +\begin{codeexample}[code only] +some axis = {ticks = {major = {at = {...}}}} +\end{codeexample} + A slight simplification is given by the following keys, which can be + passed directly to |ticks| and |grid|: + \begin{key}{/tikz/data visualization/major at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} + \begin{key}{/tikz/data visualization/minor at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} + \begin{key}{/tikz/data visualization/subminor at=\meta{list}} + A shorthand for |major={at={|\meta{list}|}}|. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/also at=\meta{list}} + This key is similar to |at|, but it causes ticks or grid lines to be + placed at the positions in the \meta{list} \emph{in addition} to the + ticks that have already been specified either directly using |at| or + indirectly using keys like |step| or |some|. The effect of multiple + calls of this key accumulate. However, when |at| is used after an + |also at| key, the |at| key completely resets the positions where + ticks or grid lines are shown. +\begin{codeexample}[] +\tikz \datavisualization + [ school book axes, visualize as smooth line, + x axis={grid, ticks and grid={major={also at={0.5}}}}] + data [format=function] { + var x : interval [-1.25:2]; + func y = \value x * \value x / 2; + }; +\end{codeexample} + As for |at|, there are some shorthands available: + \begin{key}{/tikz/data visualization/major also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} + \begin{key}{/tikz/data visualization/minor also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} + \begin{key}{/tikz/data visualization/subminor also at=\meta{list}} + A shorthand for |major={also at={|\meta{list}|}}|. + \end{key} +\end{key} + + +\subsubsection{Styling Ticks and Grid Lines: Introduction} + +\label{section-dv-ticks-styling} + +When a tick, a tick label, or a grid line is visualized on the page, a +whole regiment of styles influences the appearance. The reason for +this large number of interdependent styles is the fact that we often +wish to influence only a very certain part of how a tick is rendered +while leaving the other aspects untouched: Sometimes we need to modify +just the font of the tick label; sometimes we wish to change the +length of the tick label and the tick label position at the same time; +sometimes we wish to change the color of grid line, tick, and tick +label; and sometimes we wish to generally change the thickness of all +ticks. + +Let us go over the different kinds of things that can be styled (grid +lines, ticks, and tick labels) one by one and let us have a look at +which styles are involved. We will start with the grid lines, since they +turn out to be the most simple, but first let us have a look at the +general |style| and |styling| mechanism that is used in many placed in +the following: + +\subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys} + +\label{section-dv-style} + +All keys of the data visualization system have the path prefix +|/tikz/data visualization|. This is not only true for the main keys +like |scientific axes| or |visualize as line|, but also for keys that +govern how ticks are visualized. In particular, a style like +|every major grid| has the path prefix |/tikz/data visualization| and +all keys stored in this style are also executed with this path +prefix. + +Normally, this does not cause any trouble since most of the keys and +even styles used in a data visualization are intended to configure +what is shown in the visualization. However, at some point, we may +also with to specify options that no longer configure the +visualization in general, but specify the appearance of a line or a +node on the \tikzname\ layer. + +Two keys are used to ``communicate'' with the \tikzname\ layer: + +\begin{key}{/tikz/data visualization/style=\meta{\tikzname\ options}} + This key takes options whose path prefix is |/tikz|, not + |/tikz/data visualization|. These options will be \emph{appended} to + a current list of such options (thus, multiple calls of this key + accumulate). The resulting list of keys is not executed + immediately, but it will be executed whenever the data visualization + engine calls the \tikzname\ layer to draw something (this placed + will be indicated in the following). +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + all axes={ticks={style=blue}, length=3cm}, + y axis={grid, grid={minor steps between steps, major={style=red}}}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/styling} + Executing this key will cause all ``accumulated'' \tikzname\ options + from previous calls to the key |/tikz/data visualization/style| to be + executed. Thus, you use |style| to set \tikzname\ options, but you + use |styling| to actually apply these options. Usually, you do not + call this option directly since this application is only done deep + inside the data visualization engine. +\end{key} + +Similar to |style| (and |styling|) there also exist the +|node style| (and |node styling|) key that takes \tikzname\ options that +apply to nodes only -- in addition to the usual |style|. + +\begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}} + This key works like |style|, only it has an effect only on nodes + that are created during a data visualization. This includes tick + labels and axis labels: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + all axes={ticks={node style=red}, length=3cm}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + Note that in the example the ticks themselves (the little thicker + lines) are not red. +\end{key} + +\begin{key}{/tikz/data visualization/node styling} + Executing this key will cause all ``accumulated'' node stylings to + be executed. +\end{key} + + +\subsubsection{Styling Ticks and Grid Lines: Styling Grid Lines} +\label{section-dv-styling-grid-lines} + +When a grid line is visualized, see +Section~\ref{section-dv-visualize-gridlines} for details on when this +happens, the following styles are executed in the specified order. + +\begin{enumerate} +\item + |grid layer|. +\item + |every grid|. +\item |every major grid| or |every minor grid| or + |every subminor grid|, depending on the kind of grid line. +\item + locally specified options for the individual grid line, see + Section~\ref{section-dv-local-styles}. +\item + |styling|, see Section~\ref{section-dv-style}. +\end{enumerate} + +All of these keys have the path prefix +|/tikz/data visualization|. However, the options stored in the first +style (|grid layer|) and also in the last (|styling|) are executed +with the path prefix |/tikz| (see Section~\ref{section-dv-style}). + +Let us now have a look at these keys in detail: + +\begin{stylekey}{/tikz/data visualization/grid layer (initially on background layer)} + \label{section-dv-grid-layer}% + This key is used to specified the \emph{layer} on which grid lines + should be drawn (layers are explained in + Section~\ref{section-tikz-backgrounds}). By default, all grid lines + are placed on the |background| layer and thus behind the data + visualization. This is a sensible strategy since it avoids obscuring + the more important data with the far less important grid + lines. However, you can change this style to ``get the grid lines to + the front'': +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + all axes={ + length=3cm, + grid, + grid={minor steps between steps} + }, + grid layer/.style=, % none, so on top of data (bad idea) + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + When this style is executed, the keys stored in the style will be + executed with the prefix |/tikz|. Normally, you should only set this + style to be empty or to |on background layer|. +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every grid} + This style provides overall configuration options for grid lines. By + default, it is set to the following: +\begin{codeexample}[code only] +low=min, high=max +\end{codeexample} + This causes grid lines to span all possible values when they are + visualized, which is usually the desired behaviour (the |low| and + |high| keys are explained in + Section~\ref{section-dv-visualize-ticks}. You can append + the |style| key to this style to configure the overall appearance of + grid lines. In the following example we cause all grid lines to be + dashed (which is not a good idea in general since it creates a + distracting background pattern). +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + all axes={length=3cm, grid}, + every grid/.append style={style=densely dashed}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every major grid} + This style configures the appearance of major grid lines. It does so + by calling the |style| key to setup appropriate \tikzname\ options + for visualizing major grid lines. The default definition of this + style is: +\begin{codeexample}[code only] +style = {help lines, thin, black!25} +\end{codeexample} + In the following example, we use thin major blue grid lines: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, + all axes={ + length=3cm, + grid, + grid={minor steps between steps} + }, + every major grid/.style = {style={blue, thin}}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + As can be seen, this is not exactly visually pleasing. The default + settings for the grid lines should work in most situations; you may + wish to increase the blackness level, however, when you experience + trouble during printing or projecting graphics. +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every minor grid} + Works like |every major grid|. The default is +\begin{codeexample}[code only] +style = {help lines, black!25} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every subminor grid} + Works like |every major grid|. The default is +\begin{codeexample}[code only] +style = {help lines, black!10} +\end{codeexample} +\end{stylekey} + + + +\subsubsection{Styling Ticks and Grid Lines: Styling Ticks and Tick Labels} + +\label{section-dv-styling-ticks} + +Styling ticks and tick labels is somewhat similar to styling grid +lines. Let us start with the tick \emph{mark}, that is, the small line +that represents the tick. When this mark is drawn, the following styles are applied: + +\begin{enumerate} +\item + |every ticks|. +\item |every major ticks| or |every minor ticks| or + |every subminor ticks|, depending on the kind of ticks to be + visualized. +\item + locally specified options for the individual tick, see + Section~\ref{section-dv-local-styles}. +\item + |tick layer| +\item + |every odd tick| or |every even tick|, see Section~\ref{section-dv-stacking}. +\item + |draw| +\item + |styling|, see Section~\ref{section-dv-style}. +\end{enumerate} + +For the tick label node (the node containing the textual +representation of the attribute's value at the tick position), the +following styles are applied: + +\begin{enumerate} +\item + |every ticks|. +\item |every major ticks| or |every minor ticks| or + |every subminor ticks|, depending on the kind of ticks to be + visualized. +\item + locally specified options for the individual tick, see + Section~\ref{section-dv-local-styles}. +\item + |tick node layer| +\item + |every odd tick| or |every even tick|, see Section~\ref{section-dv-stacking}. +\item + |styling|, see Section~\ref{section-dv-style}. +\item + |node styling|, see Section~\ref{section-dv-style}. +\end{enumerate} + +\begin{stylekey}{/tikz/data visualization/every ticks} + This style allows you to configure the appearance of ticks using the + |style| and |node style| key. Here is (roughly) the default + definition of this style: +\begin{codeexample}[code only] +node style={ + font=\footnotesize, + inner sep=1pt, + outer sep=.1666em, + rounded corners=1.5pt +} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every major ticks} + The default is +\begin{codeexample}[code only] + style={line cap=round}, tick length=2pt +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every minor ticks} + The default is +\begin{codeexample}[code only] + style={help lines,thin, line cap=round}, tick length=1.4pt +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/every subminor ticks} + The default is +\begin{codeexample}[code only] + style={help lines, line cap=round}, tick length=0.8pt +\end{codeexample} +\end{stylekey} + + +\begin{stylekey}{/tikz/data visualization/tick layer (initially on background layer)} + Like |grid layer|, this key specifies on which layer the ticks + should be placed. +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/tick node layer (initially + \normalfont empty)} + Like |tick layer|, but now for the nodes. By default, tick nodes are + placed on the main layer and thus on top of the data in case that + the tick nodes are inside the data. +\end{stylekey} + + +\subsubsection{Styling Ticks and Grid Lines: Exceptional Ticks} + +You may sometimes wish to style a few ticks differently from the other +ticks. For instance, in the axis system |school book axes| there +should be a tick label at the |0| position only on one axis and then +this label should be offset a bit. In many cases this is easy to +achieve: When you add a tick ``by hand'' using the |at| or |also at| +option, you can add any special options in square brackets. + +However, in some situations the special tick position has been +computed automatically for you, for instance by the |step| key or by +saying |tick=some|. In this case, adding a tick mark with the desired +options using |also at| would cause the tick mark with the correct +options to be shown in addition to the tick mark with the wrong +options. In cases like this one, the following option may be helpful: + +\begin{key}{/tikz/data visualization/options at=\meta{value} |as [|\meta{options}|]|} + This key causes the \meta{options} to be executed for any tick + mark(s) at \meta{value} in addition to any options given already for + this position: +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line, + x axis={ticks={major={ + options at = 3 as [no tick text], + also at = (pi) as + [{tick text padding=1ex}] $\pi$}}}] +data [format=function] { + var x : interval[0:2*pi]; + func y = sin(\value x r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/no tick text at=\meta{value}} + Shorthand for |options at=|\meta{value}| as [no tick text]|. +\end{key} + + + +\subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value} + +\label{section-dv-local-styles} +\label{section-dv-tick-labels} + + +The |at| and |also at| key allow you to provide a comma-separated +\meta{list} of \meta{value}s where ticks or grid lines should be +placed. In the simplest case, the \meta{value} is simply a +number. However, the general syntax allows three different kinds of +\meta{value}s: + +\begin{enumerate} +\item + \meta{value} +\item + \meta{value} |as| |[|\meta{local options}|]| +\item + \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text} +\end{enumerate} + +In the first case, the \meta{value} is just a number that is +interpreted like any other attribute value. + +In the second case, where the keyword |as| is present, followed by +some option in square brackets, but nothing following the closing +square bracket, when the tick or grid line at position \meta{value} is +shown, the \meta{local options} are executed first. These can use the +|style| key or the |node style| key to configure the appearance of +this single tick or grid line. You can also use keys like |low| or +|high| to influence how large the grid lines or the ticks are or keys +like |tick text at low| to explicitly hide or show a tick label. + +In the third case, which is only important for |ticks| and not for +|grid|, the same happens as in the second case, but the +text that is shown as tick label is \meta{text} rather than the +automatically generated tick label. This automatic generation of tick +labels is explained in the following. + +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes=clean, + x axis={length=2.5cm, ticks={major at={ + 5, + 6 as [style=red], + 7 as [{style=blue, low=-1em}], + 8 as [style=green] $2^3$, + 10 as ten + }}}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + + +A value like ``2'' or ``17'' could just be used as \meta{text} to be +displayed in the node of a tick label. However, things are more +difficult when the to-be-shown value is $0.0000000015$, because we +then would typically (but not always) prefer something like $1.5 \cdot +10^{-9}$ to be shown. Also, we might wish a unit to be added like +$23\mathrm{m}/\mathrm{s}$. Finally, we might wish a number like +$3.141$ to be replaced by $\pi$. For these reasons, the data +visualization system does not simply put the to-be-shown value in a +node as plain text. Instead, the number is passed to a +\emph{typesetter} whose job it is to typeset this number nicely using +\TeX's typesetting capabilities. The only exception is, as indicated +above, the third syntax version of the |at| and |also at| keys, where +\meta{text} is placed in the tick label's node, regardless of what the +typesetting would usually do. + +The text produced by the automatic typesetting is computed as follows: +\begin{enumerate} +\item The current contents of the key |tick prefix| is put into the node. +\item This is followed by a call of the key |tick typesetting| which + gets the \meta{value} of the tick as its argument in scientific + notation. +\item This is followed by the contents of the key |tick suffix|. +\end{enumerate} + +Let us have a look at these keys in detail: + +\begin{key}{/tikz/data visualization/tick prefix=\meta{text} + (initially \normalfont empty)} + The \meta{text} will be put in front of every typeset tick: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, all axes={ticks=few, length=2.5cm}, + x axis={ticks={tick prefix=$\langle$, tick suffix=$]$}}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/tick suffix=\meta{text} + (initially \normalfont empty)} + Works like |tick prefix|. This key is especially useful for adding + units like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick + label. For this reason, there is a (near) alias that is easier to memorize: + \begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}} + A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|: +\begin{codeexample}[] +\tikz \datavisualization + [scientific axes, all axes={length=3cm}, + x axis={ticks={tick unit=s}}, + y axis={ticks={tick unit=m/s^2}}, + visualize as line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/tick typesetting=\meta{value}} + The key gets called for each number that should be typeset. The + argument \meta{value} will be in scientific notation (like |1.0e1| + for $10$). By default, this key applies |\pgfmathprintnumber| to its + argument. This command is a powerful number printer whose + configuration is documented in + Section~\ref{pgfmath-numberprinting}. + + You are invited to code underlying this key so that a different + typesetting mechanism is used. Here is a (not quite finished) + example that shows how, say, numbers could be printed in terms of + multiples of $\pi$: +\begin{codeexample}[] +\def\mytypesetter#1{% + \pgfmathparse{#1/pi}% + \pgfmathprintnumber{\pgfmathresult}$\pi$% +} +\tikz \datavisualization + [school book axes, all axes={unit length=1.25cm}, + x axis={ticks={step=(0.5*pi), tick typesetter/.code=\mytypesetter{##1}}}, + y axis={include value={-1,1}}, + visualize as smooth line] + data [format=function] { + var x : interval [0.5:7]; + func y = sin(\value x r); + }; +\end{codeexample} +\end{key} + + + + +\subsubsection{Stacked Ticks} + +\label{section-dv-stacking} + + + +Sometimes, the text of tick labels are so long or so numerous that the +text of adjacent tick labels overlap (or have too little padding): +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} +There are two ways to address this problem: +\begin{itemize} +\item One can rotate the labels on horizontal axes: +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + x axis={ticks={node style={rotate=90, anchor=east}}}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} + This is often a good solution, but may be hard to read. Also + consider rotating labels only by $45^\circ$ or $30^\circ$. +\item One can specify different shifts of the nodes for the different + ticks, whereby the ticks text no longer overlap. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + x axis={ticks={major at={0,4000,8000, + 2000 as [node style={yshift=-1em}], + 6000 as [node style={yshift=-1em}], + 10000 as [node style={yshift=-1em}]}}}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} + However, specifying shifts ``by hand'' in the above way is not + always an option, especially when the tick positions should be + computed automatically. Instead, the |stack| option can be used, + which is much easier to use and gives better results: +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, x axis={ticks=stack}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} +\end{itemize} + + +The |stack| option is actually just a style that gives you access to +the general even/odd mechanism for ticks with labels. Whenever a tick +mark is created where a tick label is also to be drawn, two special +things happen: + +\begin{enumerate} +\item For every odd tick mark, the |every odd tick| style is executed, + for every even tick mark the |every even tick|. Here, ``odd'' and + ``even'' are with respect to the order in which the ticks have been + added to the list of |at| positions for each major, minor, or + subminor tick list, not with respect to the order in which they will + appear on the axis. Thus, when you write +\begin{codeexample}[code only] +ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}} +\end{codeexample} + then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key + |every odd tick| will be executed, while |every even tick| will be + executed for positions |2|, |4|, |-1|, and also |8|. +\item When a tick node label is shown at the |low| position of the + tick mark, the dimension stored in the key + |tick text low even padding| is added to the |low| value. Provided + that this padding is not zero (which is the default), the length of + the even tick marks will be increased and the tick label node will + be placed at a greater distance from the axis. + + Similar keys exist for padding ticks with labels at high positions + and also at even positions. +\end{enumerate} + + +\begin{key}{/tikz/data visualization/tick text low even + padding=\meta{dimension} (initially 0pt)} + When a tick label is shown at the low position of an even tick, the + \meta{distance} is added to the |low| value, see also + Section~\ref{section-dv-visualize-ticks}. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + x axis={ticks={tick text low even padding=-1em}}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} + Note that \meta{dimension} should usually be non-positive. +\end{key} + +The following keys work similarly: +\begin{key}{/tikz/data visualization/tick text low odd padding=\meta{dimension} (initially 0pt)} +\end{key} +\begin{key}{/tikz/data visualization/tick text high even padding=\meta{dimension} (initially 0pt)} +\end{key} +\begin{key}{/tikz/data visualization/tick text high odd padding=\meta{dimension} (initially 0pt)} +\end{key} + +\begin{key}{/tikz/data visualization/tick text odd + padding=\meta{dimension}} + A shorthand for setting |tick text odd low padding| and + |tick text odd high padding| at the same time. +\end{key} + +\begin{key}{/tikz/data visualization/tick text even + padding=\meta{dimension}} + A shorthand for setting |tick text even low padding| and + |tick text even high padding| at the same time. +\end{key} + +\begin{key}{/tikz/data visualization/tick text + padding=\meta{dimension}} + Sets all text paddings to \meta{dimension}. +\end{key} + +\begin{key}{/tikz/data visualization/stack=\meta{dimension} (default 1em)} + Shorthand for |tick text even padding=|\meta{dimension}. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + x axis={ticks={stack=1.5em}}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/stack'=\meta{dimension}} + Shorthand for |tick text odd padding=|\meta{dimension}. The + difference to |stack| is that the set of value that are + ``lowered'' is exactly exchanged with the set of value ``lowered'' + by |stack|. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, + all axes={length=2.5cm}, + x axis={ticks=stack'}, + visualize as smooth line] + data [format=function] { + var y : interval[-100:100]; + func x = \value y*\value y; + }; +\end{codeexample} +\end{key} + +Note that the above keys have an effect on all tick labels of an axis, +also on special ticks that you may have added using the |also at| +key. When using the |stack| key, you should specify a |tick text padding| +explicitly for such keys: + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes, + x axis={ticks={stack, many, major also at= + {(pi) as [{tick text padding=2.5em}] $\pi$}}}, + visualize as smooth line] + data [format=function] { + var x : interval[0:(2*pi)]; + func y = sin(\value x r); + }; +\end{codeexample} + + +\subsubsection{Reference: Basic Strategies} + +\label{section-dv-strategies} + +\begin{key}{/tikz/data visualization/axis options/linear steps} + This strategy places ticks at positions that are evenly spaced by + the current value of |step|. + + In detail, the following happens: Let $a$ be the minimum value of the + data values along the axis and let $b$ be the maximum. Let the + current \emph{stepping} be $s$ (the stepping is set using the |step| + option, see below) and let the current \emph{phasing} be $p$ (set + using the |phase|) option. Then ticks are placed all positions + $i\cdot s + p$ that lie in the interval $[a,b]$, where $i$ ranges + over all integers. + + The tick positions computed in the way described above are + \emph{mayor} step positions. In addition to these, if the key + |minor steps between steps| is set to some number $n$, then $n$ many + minor ticks are introduced between each two mayor ticks (and also + before and after the last mayor tick, provided the values still lie + in the interval $[a,b]$). Note that is $n$ is $1$, then one minor tick + will be added in the middle between any two mayor ticks. Use a value + of $9$ (not $10$) to partition the interval between two mayor ticks + into ten equally sized minor intervals. + +\begin{codeexample}[] +\begin{tikzpicture} + \datavisualization + [scientific axes={inner ticks, width=3cm}, + x axis={ticks={step=3, minor steps between steps=2}}, + y axis={ticks={step=.36}}, + visualize as scatter] + data { + x, y + 17, 30 + 34, 32 + }; +\end{tikzpicture} +\end{codeexample} +\end{key} + +\label{section-dv-exponential-strategy} + +\begin{key}{/tikz/data visualization/axis options/exponential steps} + This strategy produces ticks at positions that are appropriate for + logarithmic plots. It is automatically selected when you use the + |logarithmic| option with an axis. + + In detail, the following happens: As for |linear steps| let numbers + $a$, $b$, $s$, and $p$ be given. Then, mayor ticks are placed at all + positions $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i + \in \mathbb Z$. + + The minor steps are added in the same way as for |linear steps|. In + particular, they interpolate \emph{linearly} between mayor steps. + +\begin{codeexample}[] +\begin{tikzpicture} + \datavisualization + [scientific axes, + x axis={logarithmic, length=2cm, ticks={step=1.5}}, + y axis={logarithmic, ticks={step=1, minor steps between steps=9}}, + visualize as scatter] + data { + x, y + 1, 10 + 1000, 1000000 + }; +\end{tikzpicture} +\end{codeexample} +\end{key} + + -\subsubsection{Advanced: Defining New Placing Strategies} +\subsubsection{Advanced: Defining New Placement Strategies} -\begin{key}{/tikz/data visualization/axis options/tick placement strategy=\meta{macro}} +\begin{key}{/tikz/data visualization/axis options/tick placement + strategy=\meta{macro}} This key can be used to install a so-called \emph{tick placement strategy}. Whenever |visualize ticks| is used to request some ticks to be visualized, it is checked whether some automatic ticks @@ -777,9 +2600,10 @@ to request about four ticks to be placed on the $x$-axis. been set to the name of the axis for which default ticks need to be computed. This allows you to access the minimum and the maximum value stored in the |scaling mapper| of that axis. - \begin{codeexample}[] +\begin{codeexample}[width=7cm] \def\silly{ - \tikzdatavisualizationset{major={at={2,3,5,7,11,13}}} + \tikzdatavisualizationset{major={at={ + 2,3,5,7,11,13}}} } \begin{tikzpicture} \datavisualization [ @@ -795,6 +2619,1079 @@ to request about four ticks to be placed on the $x$-axis. \end{codeexample} \end{key} -\subsection{Advanced: Creating New Axes} + + + \subsection{Advanced: Creating New Axis Systems} + +The data visualization library comes with a number of predefined axis +systems, like |scientific axes=clean|, but it is also possible and +to define new axis systems. Doing so involves the following steps: + +\begin{enumerate} +\item Creating a number of axes. +\item Configuring attributes of these axes like their length or + default scaling. +\item Creating visual representations of the axes. +\item Creating visual representations of the ticks and grid lines. +\end{enumerate} + +The first step uses |new ... axis| keys to create new axes, the +last steps use |visualize ...| keys to create the visual +representations of the axes. + +Note that the axis system has no control over the actual attribute +value ranges and neither over which ticks need to be drawn. The axis +system can only provide good defaults and then specify \emph{how} the +ticks or labels should be drawn and \emph{where} on the page -- but +not at which values. + +In the following, as a running example let us develop an axis system +|our system| that does the following: For the $x$-axis is looks like a +normal scientific axis system, but there are actually two $y$-axes: +One at the left and one at the right, each using a different +attribute, but both coexisting in the same picture. + +\subsubsection{Creating the Axes} + +A new axis system is created as a style key with the prefix +|/tikz/data visualization|. Thus, we would write: +\begin{codeexample}[code only] +\tikzset{ + data visualization/our system/.style={ + ... + } +} +\end{codeexample} + +In our system we need three axis: The $x$-axis, the left axis and the +right axis. Since all of these axes are Cartesian axes, we write the +following: +\begin{codeexample}[code only] +\tikzset{ + data visualization/our system/.style={ + new Cartesian axis=x axis, + new Cartesian axis=left axis, + new Cartesian axis=right axis, + x axis={attribute=x}, + left axis={unit vector={(0cm,1pt)}}, + right axis={unit vector={(0cm,1pt)}}, + } +} +\end{codeexample} +As can be seen, we also configure things so that the $x$-axis will use +the |x| attribute by default (users can later change this by saying +|x axis={attribute=|\meta{some other attribute}|}|), but we do not +configure the attributes of the |left axis| nor the |right axis|. We +also make the left and right axis point upward (the |x axis| needs no +configuration here since a Cartesian axis points right by default). The +reason is the |left| would not be a particularly good attribute name +and this way we ensure that users have to pick names themselves +(hopefully good ones). + +The next step is to define a standard scaling for the axes. Here, we +can use the same as for |scientific axes|, so we would add the +following keys to the definition of |our system|: +\begin{codeexample}[code only] +x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, +left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, +right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} +\end{codeexample} + +We now already have enough to try our system, although we will not yet +see any axes or ticks, but we will see the correct scaling of the +attributes. Let us first define a data group: +\begin{codeexample}[] +\tikz \datavisualization data group {people and money} = { + data [set=people 1] { + time, people + 1900, 1000000000 + 1920, 1500000000 + 1930, 2000000000 + 1980, 3000000000 + } + data [set=people 2] { + time, people + 1900, 2000000000 + 1920, 2500000000 + 1940, 4000000000 + 2000, 5700000000 + } + data [set=money 1] { + time, money + 1910, 1.1 + 1920, 2 + 1930, 5 + 1980, 2 + } + data [set=money 2] { + time, money + 1950, 3 + 1960, 3 + 1970, 4 + 1990, 3.5 + } + }; +\end{codeexample} + +\tikzdatavisualizationset{ + our system/.style={ + new Cartesian axis=x axis, + new Cartesian axis=left axis, + new Cartesian axis=right axis, + x axis={attribute=x}, + left axis={unit vector={(0cm,1pt)}}, + right axis={unit vector={(0cm,1pt)}}, + x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, + left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} + } +} +\begin{codeexample}[] +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=4cm}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}, + people 1={style={visualizer color=blue}}, + people 2={style={visualizer color=blue!50}}, + money 1={style={visualizer color=red}}, + money 2={style={visualizer color=red!50}}] + data group {people and money}; +\end{codeexample} + + + +\subsubsection{Visualizing the Axes} + +\label{section-dv-visualize-axis} + +We must now show the axes themselves. For this we can use the +|visualize axis| key: + +\begin{key}{/tikz/data visualization/axis options/visualize axis=\meta{options}} + This key is passed to an axis as an option. It causes a visual + representation of the axis to be created during the data visualization. The + \meta{options} are used to determine where the axis should be drawn + and how long it should be. We can specify, for instance, that an + axis should be drawn at the minimum value of another axis or where + another axis has the value |0|. + + \medskip + \textbf{The goto, high, and low Keys.} + In our example, the |left axis| should be shown at the left hand + side. This is the position where the |x axis| has its minimum + value. To specify this, we would use the following code: +\begin{codeexample}[code only] +left axis={ visualize axis={ x axis={ goto=min } } +\end{codeexample} + As can be seen, we can pass another axis as an \meta{option} to + |visualize axis|, where we pass the following key to the axis in + turn: + \begin{key}{/tikz/data visualization/axis options/goto=\meta{value}} + The key can be passed to an axis. It will set the attribute + monitored by the axis to the given \meta{value}, which is usually + some number. However, \meta{value} may also be one of the + following, which causes a special behaviour: + \begin{itemize} + \item + |min|: The attribute is set to the minimal value that the + attribute has attained along this axis. + \item + |max|: Like |min|. + \item + |padded min|: This will also set the \meta{attribute} monitored + by the axis to the same value as |min|. Additionally, however, + the subkey |/data point/|\meta{attribute}|/offset| is set to the + current padding for the minimum, see the description of + |padding min| later on. The effect of this is that the actual + point ``meant'' by the attribute is offset by this padding along + the attribute's axis. + \item + |padded max|: Like |padded min|. + \end{itemize} + \end{key} + + The |right axis| would be visualized the same way, only at + |goto=max|. The $x$-axis actually need to be visualized + \emph{twice}: Once at the bottom and once at the top. Thus, we need + to call |visualize axis| twice for this axis: + +\tikzdatavisualizationset{ + our system/.style={ + new Cartesian axis=x axis, + new Cartesian axis=left axis, + new Cartesian axis=right axis, + x axis={attribute=x}, + left axis={unit vector={(0cm,1pt)}}, + right axis={unit vector={(0cm,1pt)}}, + x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, + left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}} + } +} +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + left axis= {visualize axis={x axis= {goto=min}}}, + right axis={visualize axis={x axis= {goto=max}}}, + x axis= {visualize axis={left axis={goto=min}}, + visualize axis={left axis={goto=max}}}, + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=4cm}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + + There is another key that is similar to |goto|, but has a slightly + different semantics: + \begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}} + The key works like |goto|, only the \meta{fraction} is not + interpreted as a value but as a fraction of the way between the + minimum and the maximum value for this axis. + + Suppose that for an axis the attribute range interval is + $[500,1000]$ and the reasonable interval is $[1,3]$. Then for a + \meta{fraction} of |0|, the mapping process would choose value + $1$ from the reasonable interval, for a \meta{fraction} of |1| the + position $3$ from the reasonable interval, and for a + \meta{fraction} or |0.25| the position $1.5$ since it is one + quarter at the distance from $1$ to $3$. + + Note that neither the attribute range interval nor the + transformation function for the attribute are important for the + |goto pos| option -- the \meta{fraction} is computed with respect + to the reasonable interval. Also note that the values of the + actual attribute corresponding to the fractional positions in the + reasonable interval are not computed. +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + x axis= {visualize axis={left axis={goto pos=0.25}}, + visualize axis={left axis={goto pos=0.5}}}, + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=4cm}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + \end{key} + + By default, when an axis is visualized, it spans the set of all + possible values for the monitored attribute, that is, from |min| to + |max|. However, there are actually two keys that allow you to adjust + this: + \begin{key}{/tikz/data visualization/low=\meta{value}} + This is the attribute value where the axis visualization + starts. The same special values as for |goto| are permissible + (like |min| or |padded min|, but also |0| or |1|). + \end{key} + \begin{key}{/tikz/data visualization/high=\meta{value}} + Like |low|, only for where the axis ends. + \end{key} + + By default, |low=min| and |high=max| are set for an axis + visualization. Another sensible setting is |low=padded min| and + |high=padded max|. The following key provides a shorthand for this: + \begin{key}{/tikz/data visualization/padded} + Shorthand for |low=padded min, high=padded max|. + \end{key} + As an example, consider the |scientific axes=clean|. Here, each axis + is actually drawn three times: Once at the minimum, once at the + maximum and then once more at the padded minimum. + + + \medskip + \textbf{The axis line.} + When an axis is drawn, \tikzname\ does not simply draw a straight + line from the |low| position to the |high| position. In reality, the + data visualization system uses the two commands |\pgfpathdvmoveto| + and |\pgfpathdvlineto| internally. These will replace the straight + line by a curve in certain situations. For instance, in a polar + coordinate system, if an axis should be drawn along an angle axis + for a fixed radius, an arc will be used instead of a straight line. + + \medskip + \textbf{Styling the axis.} + As can be seen, we now get the axis we want (but without the ticks, + visualizing them will be explained later). The axis is, however, + simply a black line. We can \emph{style} the axis in a manner + similar to styling ticks and grid lines, see + Section~\ref{section-dv-style}. In detail, the following styles get + executed: + \begin{enumerate} + \item |axis layer| + \item |every axis| + \item |styling| + \end{enumerate} + Additionally, even before |every axis| is executed, |low=min| and + |high=max| are executed. + + \begin{stylekey}{/tikz/data visualization/axis layer (initially on + background layer)} + The layer on which the axis is drawn. See the description of + |grid layer| on page~\ref{section-dv-grid-layer} for details. + \end{stylekey} + + \begin{stylekey}{/tikz/data visualization/every axis} + Put styling of the axis here. It is usually a good idea to set + this style to |style={black!50}|. + \end{stylekey} + + Recall that the |styling| key is set using the |style| key, see + Section~\ref{section-dv-style}. +\tikzset{ +} +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + every axis/.style={style=black!50}, % make this the default + left axis= {visualize axis={x axis= {goto=min}, style=red!75}}, + right axis={visualize axis={x axis= {goto=max}, style=blue!75}}, + x axis= {visualize axis={left axis={goto=min}}, + visualize axis={left axis={goto=max}}}, + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=4cm}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} +\tikzset{ + data visualization/our system/.append style={ + every axis/.style={style=black!50}, % make this the default + left axis= {visualize axis={x axis= {goto=min}, style=red!75}}, + right axis={visualize axis={x axis= {goto=max}, style=blue!75}}, + x axis= {visualize axis={left axis={goto=min}}, + visualize axis={left axis={goto=max}}}, + } +} + + \medskip + \textbf{Padding the Axis.} + When an axis is visualized, it is often a good idea to make it ``a + little bit longer'' or to ``remove it a bit from the border,'' because + the visualization of an axis should not interfere with the actual + data. For this reason, a \emph{padding} can be specified for axes: + + \begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}} + This is the dimension that is used whenever |goto=padded min| is + used. The \meta{dimension} is then put into the |offset| subkey of + the attribute monitored by the axis. When a data point is + transformed by a linear transformer and when this subkey is + nonzero, this offset is added. (For an angle axis of a polar + transformer, the \meta{dimension} is interpreted as an additional + angle rather than as an additional distance). Note that + \meta{dimension} should typically be negative since + ``adding the \meta{dimension}'' will then make the axis longer + (because it starts at a smaller value). The standard + axis systems set the padding to some default and take its value + into account: +\begin{codeexample}[width=8cm] +\begin{tikzpicture} + \datavisualization [scientific axes=clean, + x axis={padding min=-1cm}, + visualize as smooth line] + data [format=function] { + var x : interval [-3:5]; + func y = \value x * \value x; + }; +\end{tikzpicture} +\end{codeexample} + + Using padded and using the |padded| key, we can visualize our axis + ``a little removed from the actual data'': +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + all axes= {padding=.5em}, + left axis= {visualize axis={x axis= {goto=padded min}, padded}}, + right axis={visualize axis={x axis= {goto=padded max}, padded}}, + x axis= {visualize axis={left axis={goto=padded min}, padded}, + visualize axis={left axis={goto=padded max}, padded}}, + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=3cm}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + \end{key} + + \begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}} + Works like |padding min|, but \meta{dimension} should typically be positive. + \end{key} + + \begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}} + Sets both |padding min| to the negated value of \meta{dimension} and + |padding max| to \meta{dimension}. + \end{key} +\end{key} + + + +\subsubsection{Visualizing Grid Lines} + +\label{section-dv-visualize-gridlines} + +As explained earlier, the |grid| key is used to specify at which +positions grid lines should be drawn in principle. However, this key +does not actually cause any grid lines to be drawn. Instead, the +|visualize grid| key is used by the axis system to specify how grid +lines are drawn. + +\begin{key}{/tikz/data visualization/axis options/visualize grid=\meta{options}} + This key is passed to an axis. It causes grid lines to be drawn at + the positions specified by the |grid| key for this axis. The + \meta{options} govern where and how the grid lines will be drawn. + + \medskip + \textbf{The direction axis.} + At first sight, one might expect that the grid lines for an axis + should simply be drawn perpendicular to the axis between the minimum + and maximum value of the axis. However, things are somewhat more + difficult in reality: + \begin{enumerate} + \item A grid line is supposed to indicate all positions where a + certain attribute attains a fixed value. But, then, a grid line + does not really need to be a grid \emph{line}. Consider for + instance a three dimensional axis system. A ``grid line'' for the + $x$-coordinate |3| would actually be a ``grid plane.'' + \item For a polar coordinate system and a fixed radius, this set of + positions at a certain radius is not a straight line, but an + arc. For more complicated coordinate systems such as the one + arising from three-dimensional spherical projections, a grid line + may well be a fairly involved curve. + \end{enumerate} + The |visualize grid| command addresses these complications as + follows: + \begin{enumerate} + \item A grid line is always a line, not a plane or a volume. This + means that in the example of a three dimensional axis system and + the $x$-attribute being |3|, one would have to choose whether the + grid line should go ``along'' the $y$-axis or ``along'' the + $z$-axis for this position. One can, however, call the + |visualize grid| command twice, once for each direction, to cause + grid lines to be shown for both directions. + \item A grid line is created by moving to a start position and then + doing a lineto to the target position. However, the ``moveto'' + and ``lineto'' are done by calling special commands of the data + visualization system. These special commands allow coordinate + system to ``notice'' that the line is along an axis and will allow + them to replace the straight line by an appropriate curve. The + polar axes systems employ this strategy, for instance. + \end{enumerate} + + By the above discussion, in order to create a grid line for + attribute $a$ having value $v$, we need to specify an axis ``along'' + which the line should be drawn. When there are only two axes, this + is usually ``the other axis''. This ``other axis'' is specified using the following key: + \begin{key}{/tikz/data visualization/direction axis=\meta{axis name}} + You must pass this key as an \meta{option} each time you use + |visualize axis|. When the grid line is drawn, the attribute $a$ + is set to $v$ and the axis \meta{axis name}'s attribute is set + once to the current value of |low| and once to |high|. Then a line + is drawn between these two positions using |\pgfpathdvlineto|. + \end{key} + The |low| and |high| keys are the same as the ones used in the + |visualize axis| key. + +\begin{codeexample}[] +\tikz \datavisualization [ + xyz Cartesian cabinet, + all axes={visualize axis={low=0, style=->}}, + x axis={visualize grid={direction axis=y axis}, grid=many}, + visualize as scatter] + data { + x, y, z + 0, 0, 1 + 0, 1, 0 + 2, 2, 2 + }; +\end{codeexample} +\begin{codeexample}[] +\tikz \datavisualization [ + xyz Cartesian cabinet, + all axes={visualize axis={low=0, style=->}, grid=many}, + x axis={visualize grid={direction axis=z axis}}, + z axis={visualize grid={direction axis=x axis}, + visualize grid={direction axis=y axis},}, + visualize as scatter] + data { + x, y, z + 0, 0, 1 + 0, 1, 0 + 2, 2, 2 + }; +\end{codeexample} + + \medskip + \textbf{Styling the grid lines.} + When a grid line is draw, styles are applied as described in + Section~\ref{section-dv-styling-grid-lines}. + + \medskip + \textbf{The major, minor, and subminor grid lines.} + The |grid| option allows you to specify for each kind of grid line + (major, minor, or subminor) a set of different values for which + these grid lines should be drawn. Correspondingly, it is also + possible to configure for each kind of grid line how it should be + drawn. For this, the |major|, |minor|, |subminor|, and also the + |common| keys can be used inside the \meta{options} of + |visualize grid|. While as option to |grid| these keys are used to + specify |at| values, as options of |visualize grid| they are used to + configure the different kinds of grid lines. + + Most of the time, no special configuration is necessary since all + styling is best done by configuring keys like + |every major grid|. You need to use a key like |major| only if you + wish to configure for instance the |low| or |high| values of a + |major| grid line differently from those of |minor| grid lines -- + are rather unlikely setting -- or when the styling should deviate + from the usual settings. +\begin{codeexample}[] +\tikz \datavisualization [ + xy Cartesian, + all axes={visualize axis={low=0, style=->}, + grid={some, minor steps between steps}}, + x axis= {visualize grid={ + direction axis=y axis, + minor={low=0.25, high=1.75, style=red!50}}}, + visualize as scatter] + data { + x, y + 0, 0 + 3, 3 + }; +\end{codeexample} +\end{key} + +Returning to the example of |our system| with the two axis systems, it +is straight-forward to configure the grid lines of the $x$-axis: The +direction axis is either of the other two axis (they point in the same +direction and they have the same range). For the other two axes, we +visualize one grid independently of the other, using different colors. + + +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + x axis= {visualize grid={direction axis=left axis}}, + left axis= {visualize grid={direction axis=x axis, + common={style=red!50}}}, + right axis={visualize grid={direction axis=x axis, + common={style=blue!50}}}, + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=3cm, grid=many}, + left axis ={attribute=money, grid=some}, + right axis={attribute=people, grid=few}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + + + +\subsubsection{Visualizing the Ticks and Tick Labels} + +\label{section-dv-visualize-ticks} + +\begin{key}{/tikz/data visualization/axis options/visualize ticks=\meta{options}} + Visualizing a tick involves (possibly) drawing a tick mark and + adding (possibly) the tick node. The process is similar to + |visualize grid|: Users use the |ticks| key to configure how many + ticks they would like for an axis and at which positions. The axis + system uses the |visualize ticks| key to specify where these ticks + should actually be shown. + + Unlike grid lines, which are typically only visualized once for each + combination of an axis and a direction axis, tick marks might be + visualized at different places for the same axis. Consider for + instance the |scientific axes|: +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, all axes={length=3cm}, + x axis={ticks={stack}}, + visualize as smooth line] + data [format=function] { + var x : interval [0:2]; + func y = \value x*\value x; + }; +\end{codeexample} + Have a look at the ticks on the $y$-axis: There are ticks at values |0|, + |1|, |2|, |3|, and~|4|. These are visualized both at the left + side (where the tick nodes are also shown) and additionally also at + the right side, but only as small marks. Similarly, the ticks on the + $x$-axis appear at the bottom, but also (in much simpler versions) + at the top. Both for the $x$-axis and for the $y$-axis the + |visualize ticks| key was called twice. + + \medskip + \textbf{The tick marks.} + Drawing a tick mark is quite similar to visualizing a grid line; + indeed a tick mark can be thought of as a ``mini grid line'': Just + like a grid line it ``points a long an axis.'' However, a tick will + always be a short straight line -- even when the coordinate system + is actually twisted (experimentation has shown that ticks that + follow the curvature of the coordinate system like grid lines are + hard to recognize). For this reason, the |low| and |high| keys have + a different meaning from the one used with the |visualize grid| + key. In detail to configure the size and position of a tick mark for + the value $v$ of attribute $a$, proceed as follows: + \begin{itemize} + \item The |visualize ticks| key will have setup attribute $a$ to be + equal to $v$. + \item You should now use the |goto| or |goto pos| key together with all + \emph{other} axes to configure at which position with respect to + these other options the tick mark should be shown. For instance, + suppose we want tick marks in |our system| for the $x$-axis at the + bottom and at the top. This corresponds to once setting the + |left axis| to its minimal value and once to its maximal value: + +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + x axis={visualize ticks={direction axis=left axis, left axis={goto=min}}, + visualize ticks={direction axis=left axis, left axis={goto=max}}, + } + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=3cm, ticks=many}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + \item In the above example, we may wish to shorten the ticks a bit + at the bottom and at the top. For this, we use the |low| and + |high| key: + \begin{key}{/tikz/data visualization/low=\meta{dimension}} + When used with the |visualize ticks| option, the |low| key + contains a dimension that specifies the extend of the tick going + ``toward the minimum'' of the direction axis. More precisely, when a tick + mark is visualized, a unit tangent vector at the current data point + in the direction of the |direction axis| is computed and this + vector is multiplied by \meta{dimension} to compute the start + position of the tick line. The end position is given by this + vector times the |high| value. + + Note that the \meta{dimension} should usually be negative for + the |low| key and positive for the |high| key. + + For tick marks where a tick label node is shown, the + \meta{dimension} is increased by the current values of keys like + |tick text even low padding|, see + Section~\ref{section-dv-stacking} for details. + \end{key} + \begin{key}{/tikz/data visualization/high=\meta{dimension}} + Like |low|. + \end{key} + \begin{key}{/tikz/data visualization/tick length=\meta{dimension}} + Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}. + \end{key} + + What we want to happen is that in the upper visualization of the + ticks the |low| value is |0pt|, while in the lower one the |high| + value is |0pt|: +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + x axis={ + visualize ticks={direction axis=left axis,high=0pt,left axis={goto=min}}, + visualize ticks={direction axis=left axis,low=0pt,left axis={goto=max}}, + } + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=3cm, ticks=many}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} +\end{itemize} + In order to style the tick mark, use the styling mechanism that is + detailed in Section~\ref{section-dv-styling-ticks}. + + \medskip + \textbf{The tick label node.} + At certain tick positions, we may wish to add a node indicating the + value of the attribute at the given position. The |visualize ticks| + command has no influence over which text should be shown at a node + -- the text is specified and typeset as explained in + Section~\ref{section-dv-tick-labels}. + + Each time |visualize ticks|, for each tick position up to two tick + label nodes will be created: One at the |low| position and one at + the |high| position. The following keys are used to configure which + of these cases happen: + \begin{key}{/tikz/data visualization/tick text at + low=\opt{\meta{true or false}} (default true)} + Pass this option to |visualize ticks| when you want tick label + nodes to be placed at the |low| position of each tick mark. +\begin{codeexample}[] +\tikzset{ + data visualization/our system/.append style={ + x axis={ + visualize ticks={direction axis=left axis, left axis={goto=min}, + high=0pt, tick text at low, stack}, + visualize ticks={direction axis=left axis, left axis={goto=max}, + low=0pt, tick text at high, stack} + } + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, length=3cm, ticks=some}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/tick text at + high=\opt{\meta{true or false}} (default true)} + Like |tick text at low|. + \end{key} + + \begin{key}{/tikz/data visualization/no tick text} + Shorthand for |tick text at low=false, tick text at high=false|. +\begin{codeexample}[] +\tikz \datavisualization [scientific axes, all axes={length=3cm}, + x axis={ticks={ + major also at={6.5 as [no tick text]}}}, + visualize as smooth line] + data [format=function] { + var x : interval [5:10]; + func y = \value x * \value x; + }; +\end{codeexample} + \end{key} + + When a tick label node is to be placed at the low or the high + position, the next step is to determine the exact position and the + correct anchor of the node. This is done as follows: + \begin{itemize} + \item In order to compute an appropriate |anchor|, the tick mark is + considered: This is a short line pointing in a certain + direction. For a tick label node at the |low| position, the + |anchor| attribute is setup in such a way that the node label will + be below the |low| position when the tick mark direction points + up, it will be to the right when the direction points left, above + when it points down, and so on also for diagonal + directions. Similarly, for the |high| position, when the direction + points up, the node will be placed above the tick mark and so on. + + This computation is done automatically. + \item The tick label node is styled. The styles that are applied are + described in Section~\ref{section-dv-styling-ticks}. + \item A tick label node for the |low| position is usually anchored + at this |low| position, but an additional padding will be + added as described in Section~\ref{section-dv-stacking}. + \end{itemize} +\end{key} + + + + +\subsubsection{Visualizing the Axis Labels} + +\label{section-dv-visualize-label} + +The |label| option can be used with an axis to specify a text should +be shown next to the axis to indicates which attribute this axis +refers to. Like |ticks| or |grid|, the |label| option does not +actually draw the label, this is the job of the |visualize label| key, +which is configured by the axis system. + +\begin{key}{/tikz/data visualization/axis options/visualize label=\meta{options}} + The \meta{options} should be used to configure a ``good place'' for + the axis label. Usually, you will use the |goto| or the |goto pos| + key. + + For the example of |our system|, we would like the label of the + |x axis| to be placed below at the middle of the axis, so we use + |goto pos=.5| to determine this position. Concerning the other axes, + we want it to be placed at the minimum position of the |left axis| + with a lot of padding. +\begin{codeexample}[width=7cm] +\tikzdatavisualizationset{ + our system/.append style={ + x axis={visualize label={ + x axis={goto pos=.5}, + left axis={padding=1.5em, goto=padded min}}} + } +} +\tikz \datavisualization [ + our system, + x axis={attribute=time, ticks=some, label}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={ + people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + + In the above example, the |padding| of |1.5em| was rather arbitrary + and ``suboptimal''. It would be outright wrong if the labels on the |x axis| were larger or + if they were missing. It would be better if the vertical position of + the |x axis| label were always ``below'' all other options. For such + cases a slightly strange approach is useful: You position the node + using |node style={at=...}| where |at| + is now the normal \tikzname\ option that is used to specify the + position of a node. Inside the |...|, you specify that the + horizontal position should be the bottom of up-to-now-constructed + data visualization and the vertical position should be at the + ``origin,'' which is, however, the position computed by the |goto| + keys for the axes: +\begin{codeexample}[width=7cm] +\tikzdatavisualizationset{ + our system/.append style={ + x axis={visualize label={ + x axis={goto pos=.5}, + node style={ + at={(0,0 |- data visualization bounding box.south)}, + below +} } } } } +\tikz \datavisualization [ + our system, + x axis={attribute=time, ticks=some, label=Year}, + left axis ={attribute=money}, + right axis={attribute=people}, + visualize as line/.list={ + people 1, people 2, money 1, money 2}] + data group {people and money}; +\end{codeexample} + + Two additional keys are useful for positioning axis labels: + \begin{key}{/tikz/data visualization/axis option/anchor at min} + When passed to an axis, this key sets the |anchor| so that a node + positioned at either the |min| or the |padded min| value of the + axis will be placed ``nicely'' with respect to the axis. For + instance, if the axis points upwards from the |min| value to the + |max| value, the |anchor| would be set to |north| since this gives + a label below the axis's start. Similarly, if the axis points + right, the anchor would be set to |east|, and so on. + \end{key} + \begin{key}{/tikz/data visualization/axis option/anchor at max} + Like |anchor at min|. + \end{key} +\end{key} + + +\subsubsection{The Complete Axis System} + +Here is the code for the complete axis system developed above and an +example of how it is used: + +\begin{codeexample}[code only] +\tikzdatavisualizationset{ our system/.style={ + % The axes + new Cartesian axis=x axis, new Cartesian axis=left axis, new Cartesian axis=right axis, + % The directions of the axes + all axes={padding=.5em}, left axis={unit vector={(0cm,1pt)}}, right axis={unit vector={(0cm,1pt)}}, + % The default attributes, other attributes must be configured + x axis={attribute=x}, + % The lengths of the axes + x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, + left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + % The styling of the axes + every axis/.style={style=black!50}, % make this the default + % Visualizing the axes themselves + left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}}, + right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}}, + x axis= {visualize axis={left axis={goto=padded min}, padded}, + visualize axis={left axis={goto=padded max}, padded}}, + % Visualizing the grid, when requested + x axis= {visualize grid={direction axis=left axis}}, + left axis= {visualize grid={direction axis=x axis, common={style=red!50}}}, + right axis={visualize grid={direction axis=x axis, common={style=blue!50}}}, + % Visualizing the ticks, when requested + left axis={visualize ticks={style={red!50!black}, direction axis=x axis, + x axis={goto=padded min}, high=0pt, tick text at low}}, + right axis={visualize ticks={style={blue!80!black}, direction axis=x axis, + x axis={goto=padded max}, low=0pt, tick text at high}}, + x axis={visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, + tick text at low}, + visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}}, + % By default, there are ticks on all axes + all axes={ticks}, + % Visualizing the axis labels, when requested + x axis={visualize label={x axis={goto pos=.5}, node style={ + at={(0,0 |- data visualization bounding box.south)}, below}}}, + left axis={visualize label={left axis={goto pos=.5}, node style={ + at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}}, + right axis={visualize label={right axis={goto pos=.5}, node style={ + at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}}, +}} +\end{codeexample} + + +\tikzdatavisualizationset{ + our system/.style={ + % The axes + new Cartesian axis=x axis, + new Cartesian axis=left axis, + new Cartesian axis=right axis, + % The default attributes, other attributes must be configured + x axis={attribute=x}, + % The directions of the axes + all axes={padding=.5em}, + left axis={unit vector={(0cm,1pt)}}, + right axis={unit vector={(0cm,1pt)}}, + % The lengths of the axes + x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}}, + left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}, + % The styling of the axes + every axis/.style={style=black!50}, % make this the default + % Visualizing the axes themselves + left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}}, + right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}}, + x axis= {visualize axis={left axis={goto=padded min}, padded}, + visualize axis={left axis={goto=padded max}, padded}}, + % Visualizing the grid, when requested + x axis= {visualize grid={direction axis=left axis, padded}}, + left axis= {visualize grid={direction axis=x axis, padded, common={style=red!50}}}, + right axis={visualize grid={direction axis=x axis, padded, common={style=blue!50}}}, + % Visualizing the ticks, when requested + left axis={ + visualize ticks={style={red!50!black}, direction axis=x axis, x axis={goto=padded min}, high=0pt, tick text at low}}, + right axis={ + visualize ticks={style={blue!80!black}, direction axis=x axis, x axis={goto=padded max}, low=0pt, tick text at high}}, + x axis={ + visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, tick text at low}, + visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt} + }, + % By default, there are ticks on all axes + all axes={ticks}, + % Visualizing the axis labels, when requested + x axis={visualize label={ + x axis={goto pos=.5}, node style={at={(0,0 |- data visualization bounding box.south)}, below}}}, + left axis={visualize label={ + left axis={goto pos=.5}, node style={ + at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}}, + right axis={visualize label={ + right axis={goto pos=.5}, node style={ + at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}}, + } +} + +\begin{codeexample}[] +\tikz \datavisualization [ + our system, + x axis={attribute=time, label=Year, + ticks={tick text padding=2pt, style={/pgf/number format/set thousands separator=}}}, + left axis={attribute=money, label=Spending, + padding min=0, include value=0, grid, + ticks={tick prefix=\$, style={/pgf/number format/fixed, + /pgf/number format/fixed zerofill, /pgf/number format/precision=2}}}, + right axis={attribute=people, + label=Population, + padding min=0, include value=0, + ticks={style=/pgf/number format/fixed}}, + visualize as line/.list={ + people 1, people 2, money 1, money 2}, + people 1={style={visualizer color=blue}}, + people 2={style={visualizer color=blue!50}}, + money 1={style={visualizer color=red}}, + money 2={style={visualizer color=red!50}} ] +data group {people and money}; +\end{codeexample} + + + +\subsubsection{Using the New Axis System Key} + +The axis system |our system| that we developed in the course of the +previous section is not yet ``configurable.'' The only configuration +that was possible was to ``misuse'' the |width| and |height| keys of +the |scientific axes|. + +In order to make |our system| configurable so that we can say +|our system=|\meta{options}, where \meta{options} are executed with +the path prefix +\begin{codeexample}[code only] +/tikz/data visualization/our system +\end{codeexample} +we can use the following key: + +\begin{key}{/tikz/data visualization/new axis system=\marg{axis system + name}\marg{axis setup}\marg{default options}\\ \marg{application + options}} + The |new axis system| key takes four parameters. The first one, + \meta{system name}, is the name of the to-be-created axis system, + |our system| in our case. The |new axis system| will create the + following new key: + \begin{key}{/tikz/data visualization/\meta{axis system + name}=\opt{\meta{options}}} + When the key \meta{axis system name} is used, the following keys + will be executed in the following order: + \begin{enumerate} + \item + The \meta{axis setup} with the path prefix |/tikz/data visualization/|. + \item + The \meta{default options} with the same path prefix. + \item + The following style: + \begin{stylekey}{/tikz/data visualization/every \meta{axis system name}} + Even though this style has the path prefix + |/tikz/data visualization| itself, the keys stored in this + style will be executed with the path prefix + |/tikz/data visualization/|\meta{axis system name}. + \end{stylekey} + \item + The \meta{options} with the path prefix + |/tikz/data visualization/|\meta{axis system name}. + \item + The \meta{application options} with the path prefix |/tikz/data visualization/| + \end{enumerate} + \end{key} + + Let us now have a look at what all of this means. First, the + \meta{axis setup} will contain all options that setup the axis + system in all ways that need not be configured. For instance, the + \meta{axis setup} for the |scientific axes| will create an |x axis| + and also a |y axis| (because these are always present), but will not + setup the label visualization (because this can be configured in + different ways). For |our system|, which cannot be configured at + all, we would place all of our configuration in the \meta{axis + setup}. + + The \meta{default options} can be used to pick default values that + would usually be passed to the \meta{options} of the newly created + axis system. For instance, for |scientific axis|, the + \meta{default options} are set to |outer ticks,standard labels|, + because these are the defaults. + + Finally, the \meta{application options} can be used to actually + apply the configuration that has been chosen by the + \meta{options}. The idea is that \meta{default options}, + \meta{options}, and also |every| \meta{axis system name} all have a + chance of changing, re-changing and re-setting all sorts of styles + and keys. Then, with the last change ``winning,'' the resulting + setting of a style can be executed, which may then cause a label + visualization to be installed. +\end{key} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-backend.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-backend.tex index ef7f0be25f1..23ffe87eb89 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-backend.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-backend.tex @@ -16,7 +16,19 @@ The present section explains the mechanisms behind the data visualization engine. +Until it is documented properly, we will have to make do with the +documentation in the source code. + + \subsection{The Rendering Pipeline} +To be written... + \subsection{Usage} +To be written... + +\subsection{The Mathematical Micro-Kernel} + +\label{section-dv-math-kernel} +To be written... diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-examples.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-examples.tex index fa6ea38fcbb..ce4c95a5e38 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-examples.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-examples.tex @@ -18,7 +18,7 @@ A first example: clean ticks, all axes={grid={step=1,minor steps between steps=1}}, x axis={ - ticks={some, + ticks={ major={ also at={(0.5*pi) as $\pi/2$}, also at={(pi) as $\pi$}, @@ -40,15 +40,15 @@ A first example: \begin{codeexample}[] \begin{tikzpicture}[baseline] \datavisualization [ - scientific clean axes, + scientific axes=clean, visualize as line, all axes={padding=4pt}, x axis={logarithmic, ticks={many, tick unit={ms}, node style={rotate=45,anchor=north east}}, label={time}, - grid=many}, - y axis={ticks={some},label={distance}}, + grid}, + y axis={label={distance}}, ] data { x, y, z @@ -63,7 +63,7 @@ A first example: \begin{codeexample}[] \begin{tikzpicture}[baseline,mark=*] \datavisualization [ - scientific inner axes, + scientific axes=inner ticks, all axes={padding=4pt}, euro about strategy, visualize as scatter, diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex index 2afb9568a2b..f7a6e54eb09 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-formats.tex @@ -157,22 +157,43 @@ angle, radius \end{dataformat} -\begin{dataformat}{key value pairs} - Each line of the data is simply passed to the |\pgfkeys| command - with the path set to |/data point/|. This means that each data line - will typically consist of comma-separated assignments of the form - \meta{attribute}|=|\meta{value}. - \begin{codeexample}[] +\begin{dataformat}{named} + Basically, each line of the data must consist of a comma-separated + sequence of attribute--values pairs like |x=5, lo=500|. This will + cause the attribute |/data point/x| to be set to |5| and + |/data point/lo| to be set to |500|. +\begin{codeexample}[] \begin{tikzpicture} \datavisualization [school book axes, visualize as line] - data [format=key value pairs] { + data [format=named] { x=0, y=0 x=1, y=1 x=2, y=1 x=3, y=0 }; \end{tikzpicture} - \end{codeexample} +\end{codeexample} + However, instead of just specifying a single value for an attribute + as in |x=5|, you may also specify a whole set of values as in + |x={1,2,3}|. In this case, three data points will be created, one + for each value in the list. Indeed, the |\foreach| statement is used + to iterate over the list of values, so you can write things like + |x={1,...,5}|. + + It is also permissible to specify lists of values for more than one + attribute. In this case, a data point is created for each possible + combination of values in the different lists: +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as scatter/.list={a,b,c}, + style sheet=cross marks] +data [format=named] { + x=0, y={1,2,3}, set=a + x={2,3,4}, y={3,4,5,7}, set=b + x=6, y={5,7,...,15}, set=c +}; +\end{codeexample} \end{dataformat} \begin{dataformat}{TeX code} @@ -196,6 +217,8 @@ angle, radius \end{dataformat} + + \subsection{Reference: Advanced Formats} \begin{tikzlibrary}{datavisualization.formats.functions} @@ -215,20 +238,25 @@ angle, radius variable declaration signals that a certain attribute will range over a given interval. The function declarations will then, later, be evaluated for values inside this interval. The syntax for a - variable declaration is as follows: - \begin{quote} + variable declaration is one of the following: + \begin{enumerate} + \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]| - \opt{|samples |\meta{number}} \opt{|step |\meta{step}}|;| - \end{quote} - The |samples| and |step| options cannot be given both at the same - time. If both are missing, |samples| is used with the value stored - in the following key: + \opt{|samples |\meta{number}}|;| + \item + |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}% + |] step |\meta{step}|;| + \item + |var |\declare{\meta{variable}}| : {|\meta{values}|};| + \end{enumerate} + In the first case, if the optional |samples| part is missing, the + number of |samples| is taken from the value stored in the following key: \begin{key}{/pgf/data/samples=\meta{number} (initially 25)} Sets the number of samples to be used when no sample number is specified. \end{key} - The meaning of a declaration like the above is the following: The - attribute named \meta{variable}, that is, the key + The meaning of declaring a variable declaration to range over an + |interval| is that the attribute named \meta{variable}, that is, the key |/data point/|\meta{variable}, will range over the interval $[\meta{low},\meta{high}]$. If the number of |samples| is given (directly or indirectly), the interval is evenly divided into @@ -237,6 +265,10 @@ angle, radius stepping is used to increase \meta{low} iteratively up to the largest value that is still less or equal to \meta{high}. + The meaning of declaring a variable using a list of \meta{values} + is that the variable will simply iterate over the values using + |\foreach|. + You can specify more than one variable. In this case, each variable is varied independently of the other variables. For instance, if you declare an $x$-variable to range over the @@ -268,28 +300,43 @@ angle, radius specification. In this case, all of these functions will be evaluated for each setting of input variables. - \begin{codeexample}[] -\begin{tikzpicture} +\begin{codeexample}[] +\tikz \datavisualization [school book axes, visualize as smooth line] data [format=function] { var x : interval [-1.5:1.5]; func y = \value x * \value x; }; -\end{tikzpicture} - \end{codeexample} - \begin{codeexample}[] -\begin{tikzpicture} - \datavisualization [school book axes, visualize as smooth line, - all axes={ticks={few},unit length=3mm}] - data [format=function] { - var t : interval [0:2*pi]; - - func x = \value t * cos(\value t r); - func y = \value t * sin(\value t r); - }; -\end{tikzpicture} - \end{codeexample} +\end{codeexample} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, + all axes={unit length=5mm, ticks={step=2}}, + visualize as smooth line] +data [format=function] { + var t : interval [0:2*pi]; + + func x = \value t * cos(\value t r); + func y = \value t * sin(\value t r); +}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + visualize as smooth line/.list={1,2,3,4,5,6}, + style sheet=vary hue] +data [format=function] { + var set : {1,...,6}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); +}; +\end{codeexample} \end{dataformat} \end{tikzlibrary} @@ -331,16 +378,16 @@ Let us now have a look at how |\pgfdata| works. The first important option is \meta{source}, which governs which of these two alternatives applies: - \begin{key}{/pgf/data/source=\meta{filename} (initially \normalfont empty)} - If you set the |source| attribute to a non-empty \meta{filename}, + \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)} + If you set the |read from file| attribute to a non-empty \meta{filename}, the data will be read from this file. In this case, no \meta{inline data} may be present, not even empty curly braces - should be provided. If |source| is empty, the data must directly - follow as \meta{inline data}. + should be provided. If |read from file| is empty, the data must + directly follow as \meta{inline data}. \begin{codeexample}[code only] % Data is read from two external files: -\pgfdata[format=table,source=file1.csv] -\pgfdata[format=table,source=file2.csv] +\pgfdata[format=table, read from file=file1.csv] +\pgfdata[format=table, read from file=file2.csv] \end{codeexample} \begin{codeexample}[code only] % Data is given inline: @@ -352,6 +399,10 @@ Let us now have a look at how |\pgfdata| works. } \end{codeexample} \end{key} + \begin{key}{/pgf/data/inline} + This is a shorthand file |read from file={}|. You can add this to + make it clear(er) to the reader that data follows inline. + \end{key} The second important key is |format|, which is used to specify the data format: \begin{key}{/pgf/data/format=\meta{format} (initially table)} @@ -440,6 +491,33 @@ Let us now have a look at how |\pgfdata| works. \end{enumerate} For an example of how this works, see the description of the |\pgfdeclaredataformat| command. + + \medskip + \textbf{Data sets.} + There are three options that allow you to create \emph{data + sets}. Such a data set is essentially a macro that stores a + pre-parsed set of data that can be used multiple times in subsequent + visualizations (or even in the same visualization). + \begin{key}{/pgf/data/new set=\meta{name}} + Creates an empty data set called \meta{name}. If a data set of the + same name already exists, it is overwritten and made empty. Data + sets are global. + \end{key} + \begin{key}{/pgf/data/store in set=\meta{name}} + When this key is set to any non-empty \meta{name} and if this + \meta{name} has previously been used with the |new set| key, then + the following happens: For the current |\pgfdata| command, all + parsed data is not passed to the rendering pipeline. Instead, the + parsed data is appended to the data set \meta{name}. This includes + all options parsed to the |\pgfdata| command, which is why neither + this key nor the previous key should be passed as options to a + |\pgfdata| command. + \end{key} + \begin{key}{/pgf/data/use set=\meta{name}} + This works similar to |read from file|. When this key is used with + a |\pgfdata| command, no inline data may follow. Instead, the data + stored in the data set \meta{name} is used. + \end{key} \end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex index a2743a9fb57..1efb972e439 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-main.tex @@ -111,7 +111,7 @@ since the default format is the one used for the data following the represents a data point. \medskip -\textbf{Number accuracy.} +\textbf{Number accuracy.}\label{section-dv-expressions} Data visualizations typically demand a much higher accuracy and range of values than \TeX\ provides: \TeX\ numbers are limited to 13 bits for the integer part and 16 bits for the fractional part. Because of @@ -202,7 +202,7 @@ predefined styles take care of this for you: \begin{codeexample}[] \begin{tikzpicture} \datavisualization [ - scientific clean axes, + scientific axes=clean, x axis={length=3cm, ticks=few}, all axes={grid}, visualize as smooth line @@ -232,7 +232,7 @@ visualizers or pie chart visualizers. \begin{codeexample}[] \begin{tikzpicture} \datavisualization [ - scientific clean axes, + scientific axes=clean, x axis={length=3cm, ticks=few}, visualize as smooth line ] @@ -245,7 +245,7 @@ visualizers or pie chart visualizers. \begin{codeexample}[] \begin{tikzpicture} \datavisualization [ - scientific clean axes, + scientific axes=clean, x axis={length=3cm, ticks=few}, visualize as scatter ] @@ -291,24 +291,24 @@ coloring and the dashing is varied. \begin{codeexample}[] \begin{tikzpicture}[baseline] - \datavisualization [ scientific clean axes, + \datavisualization [ scientific axes=clean, y axis=grid, visualize as smooth line/.list={sin,cos,tan}, - visualizer style sheet=strong colors, - visualizer style sheet=vary dashing, + style sheet=strong colors, + style sheet=vary dashing, sin={label in legend={text=$\sin x$}}, cos={label in legend={text=$\cos x$}}, tan={label in legend={text=$\tan x$}}, data/format=function ] - data [sin] { + data [set=sin] { var x : interval [-0.5*pi:4]; func y = sin(\value x r); } - data [cos] { + data [set=cos] { var x : interval [-0.5*pi:4]; func y = cos(\value x r); } - data [tan] { + data [set=tan] { var x : interval [-0.3*pi:.3*pi]; func y = tan(\value x r); }; @@ -384,17 +384,17 @@ visualizations. The \meta{options} are executed with the prefix |/pgf/data|. The following options are always available: - \begin{key}{/pgf/data/source=\meta{filename} (initially \normalfont empty)} + \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)} If you set the |source| attribute to a non-empty \meta{filename}, the data will be read from this file. In this case, no \meta{inline data} may be present, not even empty curly braces should be provided. \begin{codeexample}[code only] \datavisualization ... - data [source=file1.csv] - data [source=file2.csv]; + data [read from file=file1.csv] + data [read from file=file2.csv]; \end{codeexample} - The other way round, if |source| is empty, the data must directly + The other way round, if |read from file| is empty, the data must directly follow as \meta{inline data}. \begin{codeexample}[code only] \datavisualization ... @@ -434,12 +434,12 @@ visualizations. command: \begin{codeexample}[code only] \datavisualization... - data [/data point/experiment=7, source=experiment007.csv] - data [/data point/experiment=23, source=experiment023.csv]; + data [/data point/experiment=7, read from file=experiment007.csv] + data [/data point/experiment=23, read from file=experiment023.csv]; \end{codeexample} - \begin{codeexample}[] -\begin{tikzpicture} +\begin{codeexample}[] +\tikz \datavisualization [school book axes, visualize as line] data [/data point/x=1] { y @@ -451,7 +451,6 @@ visualizations. 2 0.5 }; -\end{tikzpicture} \end{codeexample} \medskip @@ -490,6 +489,86 @@ visualizations. \end{datavisualizationoperation} +\begin{datavisualizationoperation}{data point}{\opt{\oarg{options}}} + This command is used to specify data a single data point. The + \meta{options} are simply executed with the path |/data point| and + then a data point is created. This means that inside the + \meta{options} you just specify the values of all attributes in + key-value syntax. +\begin{codeexample}[] +\tikz \datavisualization [school book axes, visualize as line] + data point [x=1, y=1] data point [x=1, y=2] + data point [x=2, y=2] data point [x=2, y=0.5]; +\end{codeexample} +\end{datavisualizationoperation} + +\begin{key}{/tikz/data visualization/data point=\meta{options}} + This key is the ``key version'' of the previous command. The + difference is that this key can be used internally inside styles. +\begin{codeexample}[] +\tikzdatavisualizationset{ + horizontal/.style={ + data point={x=#1, y=1}, data point={x=#1, y=2}}, +} +\tikz \datavisualization +[ school book axes, visualize as line, + horizontal=1, + horizontal=2 ]; +\end{codeexample} +\end{key} + +\begin{datavisualizationoperation}{data group}{\opt{\oarg{options}}\marg{name}\opt{|+=|\marg{data specifications}}} + You can store a whole \meta{data specification} in a \emph{data + group}. This allows you to reuse data in multiple places without + having to write the data to an external file. + + The syntax of this command comes in the following three variants: + \begin{itemize} + \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data specifications} + \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data specifications} + \item |data group| \opt{\oarg{options}} \marg{name} + \end{itemize} + In the first case, a new data group called \meta{name} is created (an + existing data group of the same name will be erased) and the following + \meta{data specifications} is stored in this data group. The data group + will not be fed to the rendering pipeline, but it is parsed at this + point as if it were. The defined data group is defined globally, so + you can used it in subsequent visualizations. The \meta{options} are + saved with the parsed \meta{data specifications}. + + In the second case, an already existing data group is extended by + adding the \meta{data specifications} to it. + + In the third case (detected by noting that the \meta{name} is + neither followed by an equal sign nor a plus sign), the contents of + the previously defined data group \meta{name} is inserted. The + \meta{options} are also executed. + + Let is now first create a data group. Note that nothing is drawn since + the ``dummy'' data visualization is empty and used only for the + definition of the data group. +\begin{codeexample}[] +\tikz \datavisualization data group {points} = { + data { + x, y + 0, 1 + 1, 2 + 2, 2 + 5, 1 + 2, 0 + 1, 1 + } +}; +\end{codeexample} + + We can now use this data in different plots: +\begin{codeexample}[] +\tikz \datavisualization [school book axes, visualize as line] data group {points}; +\qquad +\tikz \datavisualization [scientific axes=clean, visualize as line] data group {points}; +\end{codeexample} +\end{datavisualizationoperation} + \begin{datavisualizationoperation}{scope}{\opt{\oarg{options}}\marg{data specification}} @@ -501,14 +580,14 @@ visualizations. \datavisualization... scope [/data point/experiment=7] { - data [source=experiment007-part1.csv] - data [source=experiment007-part2.csv] - data [source=experiment007-part3.csv] + data [read from file=experiment007-part1.csv] + data [read from file=experiment007-part2.csv] + data [read from file=experiment007-part3.csv] } scope [/data point/experiment=23, format=foo] { - data [source=experiment023-part1.foo] - data [source=experiment023-part2.foo] + data [read from file=experiment023-part1.foo] + data [read from file=experiment023-part2.foo] }; \end{codeexample} \end{datavisualizationoperation} @@ -535,7 +614,7 @@ visualizations. func y = sin(\value x r); } info { - \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle (1pt) + \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=1pt] node [above,font=\footnotesize] {extremal point}; }; \end{tikzpicture} @@ -556,14 +635,40 @@ visualizations. \end{coordinatesystem} \end{datavisualizationoperation} -In order to put information \emph{behind} the data visualization, -you should usually use the |background| library and the background -layer. However, it is also possible to execute code at other points -during the data visualization process. Since this is potentially -more disruptive, special keys documented in -Section~\ref{section-dv-user-code} must be used. +\begin{datavisualizationoperation}{info'}{\opt{\oarg{options}}\marg{code}} + This command works like |info|, only the \meta{code} will be + executed just before the visualization is done. This allows you to + draw things \emph{behind} the visualization. + +\begin{codeexample}[] +\begin{tikzpicture}[baseline] + \datavisualization [ school book axes, visualize as line ] + data [format=function] { + var x : interval [-0.1*pi:2]; + func y = sin(\value x r); + } + info' { + \fill [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=2mm]; + }; +\end{tikzpicture} +\end{codeexample} +\end{datavisualizationoperation} + +\label{section-dv-bounding-box} +\begin{predefinednode}{data visualization bounding box} + This rectangle node stores a bounding box of the data visualization + that is currently being constructed. This node can be useful inside + |info| commands or when labels need to be added. +\end{predefinednode} +\begin{predefinednode}{data bounding box} + This rectangle node is similar to |data visualization bounding box|, + but it keeps track only of the actual data. The spaces needed for + grid lines, ticks, axis labels, tick labels, and other all other + information that is not part of the actual data is not part of this + box. +\end{predefinednode} \subsection{Advanced: Executing User Code During a Data Visualization} \label{section-dv-user-code} @@ -606,7 +711,7 @@ pipeline as you would normally do. In the following it is assumed that you are familiar with the concepts of Section~\ref{section-dv-backend}. \begin{key}{/tikz/data visualization/new object=\meta{options}} - This key servers two purposes: + This key serves two purposes: \begin{enumerate} \item This method makes it easy to create a new object as part of the diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-polar.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-polar.tex new file mode 100644 index 00000000000..7eb15fde505 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-polar.tex @@ -0,0 +1,433 @@ +% Copyright 2010 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + + + +\section{Polar Axes} + +\label{section-dv-polar} + + +\subsection{Overview} + +\begin{tikzlibrary}{datavisualization.polar} + This library contains keys that allow you to create plots in a polar + axis system is used. +\end{tikzlibrary} + +In a \emph{polar axis system} two attributes are visualized by +displacing a data point as follows: One attribute is used to compute a +an angle (a direction) while a second attribute is used as a radius (a +distance). The angle can be measured in degrees, radians, or can be +scaled arbitrarily. + + +\begin{codeexample}[width=8.5cm] +\tikz \datavisualization [ + scientific polar axes={0 to pi, clean}, + all axes=grid, + style sheet=vary hue, + legend=below + ] + [visualize as smooth line=sin, + sin={label in legend={text=$1+\sin \alpha$}}] + data [format=function] { + var angle : interval [0:pi]; + func radius = sin(\value{angle}r) + 1; + } + [visualize as smooth line=cos, + cos={label in legend={text=$1+\cos\alpha$}}] + data [format=function] { + var angle : interval [0:pi]; + func radius = cos(\value{angle}r) + 1; + }; +\end{codeexample} + +Most of the time, in order to create a polar axis system, you will +just use the |scientific polar axes| key, which takes a number of +options that allow you to configure the axis system in greater +detail. This key is documented in +Section~\ref{section-dv-sci-polar-axes}. Internally, this key uses +more low level keys which are documented in the en suite sections. + +It is worthwhile to note that the axes of a polar axis system are, +still, normal axes of the data visualization system. In particular, +all the configurations possible for, say, Cartesian axes also apply to +the ``angle axis'' and the ``radius axis'' of a polar axis system. For +instance, you can could make both axes logarithmic or style their +ticks: + +\begin{codeexample}[] +\tikz[baseline] \datavisualization [ + scientific axes={clean}, + x axis={attribute=angle, ticks={minor steps between steps=4}}, + y axis={attribute=radius, ticks={some, style=red!80!black}}, + all axes=grid, + visualize as smooth line=sin] + data [format=function] { + var t : interval [-3:3]; + func angle = exp(\value t); + func radius = \value{t}*\value{t}; + }; +\qquad +\tikz[baseline] \datavisualization [ + scientific polar axes={right half clockwise, clean}, + angle axis={logarithmic, + ticks={ + minor steps between steps=8, + major also at/.list={2,3,4,5,15,20}}}, + radius axis={ticks={some, style=red!80!black}}, + all axes=grid, + visualize as smooth line=sin] + data [format=function] { + var t : interval [-3:3]; + func angle = exp(\value t); + func radius = \value{t}*\value{t}; + }; +\end{codeexample} + + +\subsection{Scientific Polar Axis System} +\label{section-dv-sci-polar-axes} + +\begin{key}{/tikz/data visualization/scientific polar axes=\meta{options}} + This key installs a polar axis system that can be used in a + ``scientific'' publication. Two axes are created called the + |angle axis| and the |radius axis|. Unlike ``normal'' Cartesian + axes, these axes do not point in a specific direction. Rather, the + |radius axis| is used to map the values of one attribute to a + distance from the origin while the |angle axis| is used to map the + values of another attribute to a rotation angle. + + The \meta{options} will be executed with the path prefix +\begin{codeexample}[code only] +/tikz/data visualization/scientific polar axes +\end{codeexample} + The permissible keys are documented in the later subsections of this + section. + + Let us start with the configuration of the radius axis since it is + easier. Firstly, you should specify which attribute is linked to the + radius. The default is |radius|, but you will typically wish to + change this. As with any other axis, the |attribute| key is used to + configure the axis, see Section~\ref{section-dv-axis-attribute} for + details. You can also apply all other configurations to the radius + axis like, say, |unit length| or |length| or |style|. Note, however, + that the |logarithmic| key will not work with the radius axis for a + |scientific polar axes| system since the attribute value zero is + always placed at the center -- and for a logarithmic plot the value + |0| cannot be mapped. +\begin{codeexample}[width=8.8cm] +\tikz \datavisualization [ + scientific polar axes, + radius axis={ + attribute=distance, + ticks={step=5000}, + padding=1.5em, + length=3cm, + grid + }, + visualize as smooth line] +data [format=function] { + var angle : interval [0:100]; + func distance = \value{angle}*\value{angle}; +}; +\end{codeexample} + + For the |angle axis|, you can also specify an attribute using the + |attribute| key. However, for this axis the mapping of a value to an + actual angle is a complicated process involving many considerations + of how the polar axis system should be visualized. For this reason, + there are a large number of predefined such mappings documented in + Section~\ref{section-dv-angle-ranges}. + + Finally, as for a |scientific plot|, you can configure where the + ticks should be shown using the keys |inner ticks|, |outer ticks|, + and |clean|, documented below. +\end{key} + + +\subsubsection{Tick Placements} + +\begin{key}{/tikz/data visualization/scientific polar axes/outer ticks} + This key, which is the default, causes ticks to be drawn + ``outside'' the outer ``ring'' of the polar axes: +\begin{codeexample}[width=8.8cm] +\tikz \datavisualization [ + scientific polar axes={outer ticks, 0 to 180}, + visualize as smooth line] +data [format=function] { + var angle : interval [0:100]; + func radius = \value{angle}; +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/scientific polar axes/inner ticks} + This key causes the ticks to be ``turned to the inside.'' I do not + recommend using this key. +\begin{codeexample}[width=8.8cm] +\tikz \datavisualization [ + scientific polar axes={inner ticks, 0 to 180}, + visualize as smooth line] +data [format=function] { + var angle : interval [0:100]; + func radius = \value{angle}; +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/scientific polar axes/clean} + This key separates the area where the data is shown from the area + where the ticks are shown. Usually, this is the best choice for the + tick placement since it avoids a collision of data and + explanations. +\begin{codeexample}[width=8.8cm] +\tikz \datavisualization [ + scientific polar axes={clean, 0 to 180}, + visualize as smooth line] +data [format=function] { + var angle : interval [0:100]; + func radius = \value{angle}; +}; +\end{codeexample} +\end{key} + + +\subsubsection{Angle Ranges} +\label{section-dv-angle-ranges} + +Suppose you create a polar plot in which the radius values vary +between, say, $567$ and $1234$. Then the normal axis scaling mechanisms +can be used to compute a good scaling for the ``radius axis'': Place +the value $1234$ at a distance of , say, $5\,\mathrm{cm}$ from the +origin and place the value $0$ at the origin. Now, by comparison, +suppose that the values of the angle axis's attribute ranged between, +say, $10$ and $75.7$. In this case, we may wish the angles to be +scaled so that the minimum value is horizontal and the maximum value is +vertical. But we may also wish the a value of $0$ is horizontal and a +value of $90$ is vertical. + +Since it is unclear which interpretation is the right one, you have to +use an option to select which should happen. The applicable options +fall into three categories: + +\begin{itemize} +\item Options that request the scaling to be done in such a way that + the attribute is interpreted as a value in degrees and such that the + minimum and maximum of the depicted range is a multiple of + $90^\circ$. For instance, the option |0 to 180| causes the angle + axis to range from $0^\circ$ to $180^\circ$, independently of the + actual range of the values. +\item Options that work as above, but use radians rather than + degrees. An example is the option |0 to pi|. +\item Options that map the minimum value in the data to a horizontal + or vertical line and the maximum value to another such line. This is + useful when the values neither directly correspond to degrees or + radians. In this case, the angle axis may also be a logarithmic + axis. +\end{itemize} + +In addition to the above categories, all of the option documented in +the following implicitly also select quadrants that are used to depict +the data. For instance, the |0 to 90| key and also the |0 to pi half| +key setup the polar axis system in such a way that only first (upper +right) quadrant is used. No check is done whether the data fill +actually lie in this quadrant -- if it does not, the data will ``bleed +outside'' the range. Naturally, with a key like |0 to 360| or +|0 to 2pi| this cannot happen. + +In order to save some space in this manual, in the following the +different possible keys are only given in a table together with a +small example for each key. The examples were created using the +following code: + +\begin{codeexample}[] +\tikz \datavisualization [ + scientific polar axes={ + clean, + 0 to 90 % the option + }, + angle axis={ticks={step=30}}, + radius axis={length=1cm, ticks={step=1}}, + visualize as scatter] +data point [angle=20, radius=0.5] +data point [angle=30, radius=1] +data point [angle=40, radius=1.5]; +\end{codeexample} + +For the options on radians, the angle values have been replaced by +|0.2|, |0.3|, and |0.4| and the stepping has been changed by setting +|step=(pi/6)|. For the quadrant options, no stepping is set at all (it +is computed automatically). + +\def\polarexample#1#2#3#4#5{% + \texttt{#1}% + \indexkey{/tikz/data visualization/scientific polar axes/#1}& + \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [ + scientific polar axes={clean, #1}, + angle axis={ticks={#2}}, + radius axis={length=1cm, ticks={step=1}}, + visualize as scatter + ] + data point [angle=#3, radius=0.5] + data point [angle=#4, radius=1] + data point [angle=#5, radius=1.5]; + \path ([yshift=-1em]current bounding box.south); + }& + \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [ + scientific polar axes={outer ticks, #1}, + angle axis={ticks={#2}}, + radius axis={length=1cm, ticks={step=1}}, + visualize as scatter + ] + data point [angle=#3, radius=0.5] + data point [angle=#4, radius=1] + data point [angle=#5, radius=1.5]; + \path ([yshift=-1em]current bounding box.south); + } + \\ +} + +\begin{tabular}{lcc} + \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\ + \polarexample{0 to 90}{step=30}{20}{30}{40} + \polarexample{-90 to 0}{step=30}{20}{30}{40} + \polarexample{0 to 180}{step=30}{20}{30}{40} + \polarexample{-90 to 90}{step=30}{20}{30}{40} + \polarexample{0 to 360}{step=30}{20}{30}{40} + \polarexample{-180 to 180}{step=30}{20}{30}{40} +\end{tabular} + +\begin{tabular}{lcc} + \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\ + \polarexample{0 to pi half}{step=(pi/6)}{0.2}{0.3}{0.4} + \polarexample{-pi half to 0}{step=(pi/6)}{0.2}{0.3}{0.4} + \polarexample{0 to pi}{step=(pi/6)}{0.2}{0.3}{0.4} + \polarexample{-pi half to pi half}{step=(pi/6)}{0.2}{0.3}{0.4} + \polarexample{0 to 2pi}{step=(pi/6)}{0.2}{0.3}{0.4} + \polarexample{-pi to pi}{step=(pi/6)}{0.2}{0.3}{0.4} +\end{tabular} + +\begin{tabular}{lcc} + \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\ + \polarexample{quadrant}{}{20}{30}{40} + \polarexample{quadrant clockwise}{}{20}{30}{40} + \polarexample{fourth quadrant}{}{20}{30}{40} + \polarexample{fourth quadrant clockwise}{}{20}{30}{40} + \polarexample{upper half}{}{20}{30}{40} + \polarexample{upper half clockwise}{}{20}{30}{40} + \polarexample{lower half}{}{20}{30}{40} + \polarexample{lower half clockwise}{}{20}{30}{40} +\end{tabular} + +\begin{tabular}{lcc} + \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\ + \polarexample{left half}{}{20}{30}{40} + \polarexample{left half clockwise}{}{20}{30}{40} + \polarexample{right half}{}{20}{30}{40} + \polarexample{right half clockwise}{}{20}{30}{40} +\end{tabular} + + + +\subsection{Advanced: Creating a New Polar Axis System} + +\begin{key}{/tikz/data visualization/new polar axes=|\char`\{|\meta{angle axis + name}|\char`\}||\char`\{|\meta{radius axis name}|\char`\}|} + This key actually creates two axes, whose names are give as + parameters: An \emph{angle axis} and a \emph{radius axis}. These two + axes work in concert in the following way: Suppose a data point has two + attributes called |angle| and |radius| (these attribute names can be + changed by changing the |attribute| of the \meta{angle axis name} or + the \meta{radius axis name}, respectively). These two attributes are + then scaled as usual, resulting in two ``reasonable'' values $a$ + (for the angle) and $r$ (for the radius). Then, the data point gets + visualized (in principle, details will follow) at a position on the + page that is at a distance of $r$ from the origin and at an angle + of~$a$. +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes={angle axis}{radius axis}, + radius axis={length=2cm}, + visualize as scatter] + data [format=named] { + angle={0,20,...,160}, radius={0,...,5} + }; +\end{codeexample} + In detail, the \meta{angle axis} keeps track of two vectors $v_0$ + and $v_{90}$, each of which will usually have unit length (length + |1pt|) and which point in two different directions. Given a radius + $r$ (measured in \TeX\ |pt|s, so if the + radius attribute |10pt|, then $r$ would be $10$) and an angle $a$, + let $s$ be the sine of $a$ and let $c$ be the cosine + of $a$, where $a$ is a number is degrees (so $s$ + would be $1$ for $a = 90$). Then, the current page position is + shifted by $c \cdot r$ times $v_0$ and, additionally, by $s \cdot r$ + times $v_{90}$. This means that in the + ``polar coordinate system'' $v_0$ is the unit vector along the + ``$0^\circ$-axis'' and $v_{90}$ is the unit vector along + ``$90^\circ$-axis''. The values of $v_0$ and $v_{90}$ can be changed + using the following key on the \meta{angle axis}: + \begin{key}{/tikz/data visualization/axis options/unit + vectors=|\char`\{|\meta{unit vector 0 + degrees}|\char`\}\char`\{|\meta{unit vector 90 + degrees}|\char`\}| (initially {\char`\{(1pt,0pt)\char`\}\char`\{(0pt,1pt)\char`\}})} + Both the \meta{unit vector 0 degrees} and the \meta{unit vector 90 + degrees} are \tikzname\ coordinates: +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes={angle axis}{radius axis}, + radius axis={unit length=1cm}, + angle axis={unit vectors={(10:1pt)}{(60:1pt)}}, + visualize as scatter] + data [format=named] { + angle={0,90}, radius={0.25,0.5,...,2} + }; +\end{codeexample} + \end{key} +\end{key} + +Once created, the |angle axis| can be scaled conveniently using the +following keys: + +\begin{key}{/tikz/data visualization/axis options/degrees} + When this key is passed to the angle axis of a polar axis system, it + sets up the scaling so that a value of |360| on this axis + corresponds to a complete circle. +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes={angle axis}{radius axis}, + radius axis={unit length=1cm}, + angle axis={degrees}, + visualize as scatter] + data [format=named] { + angle={10,90}, radius={0.25,0.5,...,2} + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/axis options/radians} + In contrast to |degrees|, this option sets up things so that a value + of |2*pi| on this axis corresponds to a complete circle. +\begin{codeexample}[] +\tikz \datavisualization + [new polar axes={angle axis}{radius axis}, + radius axis={unit length=1cm}, + angle axis={radians}, + visualize as scatter] + data [format=named] { + angle={0,1.5}, radius={0.25,0.5,...,2} + }; +\end{codeexample} +\end{key} + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex index 44c866cd04b..43682ca38e3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-stylesheets.tex @@ -13,17 +13,2430 @@ \subsection{Overview} -To be written... +In many data visualizations, different sets of data need to be +visualized in a single visualization. For instance, in a plot there +might be a line for the sine of~$x$ and another line for the cosine +of~$x$; in another visualization there might be a set of points +representing data from a first experiment and another set of points +representing data from a second experiment; and so on. In order to +indicate to which data set a data point belongs, one might plot the +curve of the sine in, say, black, and the curve of the cosine in red; +we might plot the data from the fist experiment using stars and the +data from the second experiment using circles; and so on. Finally, at +some place in the visualization -- either inside the data or in a +legend next to it -- the meaning of the colors or symbols need to be +explained. + +Just as you would like \tikzname\ to map the data points automatically +onto the axes, you will also typically wish \tikzname\ to choose for +instance the coloring of the lines automatically for you. This is done +using \emph{style sheets}. There are at least two good reasons why you +should prefer style sheets over configuring the styling of each +visualizer ``by hand'' using the |style| key: +\begin{enumerate} +\item It is far more convenient to just say + |style sheet=strong colors| than having to individually + picking the different colors. +\item The style sheets were chosen and constructed rather + carefully. + + For instance, the |strong colors| style sheet does not + pick colors like pure green or pure yellow, which have very low + contrast with respect to a white background and which often lead to + unintelligible graphics. Instead, opposing primary colors with + maximum contrast on a white background were picked that are visually + quite pleasing. + + Similarly, the different dashing style sheets are + constructed in such a way that there are only few and small gaps in + the dashing so that no data points get lost because the dashes are + spaced too far apart. Also dashing patterns were chosen that have a + maximum optical difference. + + As a final example, style sheets for + plot marks are constructed in such a way that even when two plot + marks lie directly on top of each other, they are still easily + distinguishable. +\end{enumerate} +The bottom line is that whenever possible, you should use one of the +predefined style sheets rather than picking colors or dashings at +random. \subsection{Concepts: Style Sheets} +A \emph{style sheet} is a predefined list of styles such as a list of +colors, a list of dashing pattern, a list of plot marks, or a +combinations thereof. A style sheet can be \emph{attached} to a data +point attribute. Then, the value of this attribute is used with data +points to choose which style in the list should be chosen to visualize +the data point. + +In most cases, there is just one attribute to which style sheets get +attached: the |/data point/visualizer| attribute. The effect of +attaching a style sheet to this attribute is that each visualizer is +styled differently. + +For the following examples, let us first define a simple data set: +\begin{codeexample}[] +\tikz \datavisualization data group {function classes} = { + data [set=log, format=function] { + var x : interval [0.2:2.5]; + func y = ln(\value x); + } + data [set=lin, format=function] { + var x : interval [-2:2.5]; + func y = 0.5*\value x; + } + data [set=squared, format=function] { + var x : interval [-1.5:1.5]; + func y = \value x*\value x; + } + data [set=exp, format=function] { + var x : interval [-2.5:1]; + func y = exp(\value x); + } +}; +\end{codeexample} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + + + \subsection{Concepts: Legends} +\label{section-dv-labels-in} + +A \emph{legend} is a box that is next to a data visualization (or +inside it at some otherwise empty position) that contains a textual +explanation of the different colors or styles used in a data +visualization. + +Just as it is difficult to get colors and dashing patterns right ``by +hand,'' it is also difficult to get a legend right. For instance, when +a small line is shown in the legend that represents the actual line in +the data visualization, if the line is too short and the dashing is +too large, it may be impossible to discern which dashing is actually +meant. Similarly, when plot marks are shown on such a short line, +using a simple straight line may make it hard to read the plot marks +correctly. + +The data visualization engine makes some effort to make it easy to +create high-quality legends. Additionally, it also offers ways of +easily adding labels for visualizers directly inside the data +visualization, which is even better than adding a legend, in general. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {pin in data={text'=$\log x$, when=y is -1}}, + lin= {pin in data={text=$x/2$, when=x is 2, + pin length=1ex}}, + squared={pin in data={text=$x^2$, when=x is 1.1, + pin angle=230}}, + exp= {label in data={text=$e^x$, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + + +\subsection{Usage: Style Sheets} + +\subsubsection{Picking a Style Sheet} + +To use a style sheet, you need to \emph{attach} it to an +attribute. You can attach multiple style sheets to an attribute and +in this case all of these style sheets can influence the appearance of +the data points. + +Most of the time, you will attach a style sheet to the |set| +attribute. This has the effect that each different data set inside the +same visualization is rendered in a different way. Since this use of +style sheets is the most common, there is a special, easy-to-remember +option for this: + +\begin{key}{/tikz/data visualization/style sheet=\meta{style sheet}} + Adds the \meta{style sheet} to the list of style sheets attached to + the |set| attribute. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, all axes={unit length=7.5mm}, + visualize as smooth line/.list={log, lin, squared, exp}, + style sheet=vary thickness and dashing, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} +\end{key} + +While the |style sheet| key will attach a style sheet only to the +|set| attribute, the following key handler can be used to attach a +style sheet to an arbitrary attribute: + + +\begin{handler}{{.style sheet}=\meta{style sheet}} + Inside a data visualization you can use this key handler together + with an attribute, that is, with a key having the path prefix + |/data point|. For instance, in order to attach the \meta{style + sheet} |strong colors| to the attribute |set|, you could write +\begin{codeexample}[code only] +/data point/set/.style sheet=strong colors +\end{codeexample} + Indeed, the |style sheet| key is just a shorthand for the above. + + The effect of attaching a style sheet is the following: + \begin{itemize} + \item A new object is created that will monitor the attribute. + \item Each time a special \emph{styling key} is emitted by the data + visualization engine, this object will inspect the current value + of the attribute to which it is attached. + \item Depending on this value, one of the styles stored in the style + sheet is chosen (how this works, exactly, will be explained in a + moment). + \item The chosen style is then locally applied. + \end{itemize} + + In reality, things are a bit more complicated: If the attribute of + the data point happens to have a subkey named in the same way as the + value, then the value of is this subkey is used instead of the value + itself. This allows you to ``rename'' a value. + + In a sense, a style sheet behaves much like a visualizer (see + Section~\ref{section-dv-visualizers}): In accordance with the value + of a certain attribute, the appearance of data points + change. However, there are a few differences: First, the styling of + a data point needs to be triggered explicitly and this triggering is + not necessarily done for each data point individually, but only for + a whole visualizer. Second, styles can be computed even when no data + point is present. This is useful for instance in a legend since, + here, a visual representation of a visualizer needs to be created + independently of the actual data points. +\end{handler} + +\subsubsection{Creating a New Style Sheet} + +Creating a style sheet works as follows: For each +possible value that an attribute can attain we must specify a +style. This is done by creating a style key for each such possible +value with a special path prefix and setting this style key to the +desired value. The special path prefix is +|/pgf/data visualization/style sheets| followed by the name of the +style sheet. + +As an example, suppose we wish to create a style sheet |test| that makes +styled data points |red| when the attribute has value |foo| and +|green| when the attribute has value |bar| and |dashed, blue| when the +attribute is |foobar|. We could then write +\begin{codeexample}[code only] +/pgf/data visualization/style sheets/test/foo/.style={red}, +/pgf/data visualization/style sheets/test/bar/.style={green}, +/pgf/data visualization/style sheets/test/foobar/.style={dashed, blue}, +\end{codeexample} + +We could then attach this style sheet to the attribute |code| as +follows: +\begin{codeexample}[code only] +/data point/code/.style sheet=test +\end{codeexample} + +Then, when |/data point/code=foobar| holds when the styling signal is +raised, the style |dashed, blue| will get executed. + +A natural question arises concerning the situation that the value of +the attribute is not defined as a subkey of the style sheet. In this +case, a special key gets executed: + +\begin{stylekey}{/pgf/data visualization/style sheets/\meta{style + sheet}/default style=\meta{value}} + This key gets during styling whenever + |/pgf/data visualization/style sheet/|\meta{style + sheet}|/|\meta{value} is not defined. +\end{stylekey} + +Let us put all of this together in a real-life example. Suppose we +wish to create a style sheet that makes the first data set |green|, the +second |yellow| and the third one |red|. Further data sets should be, +say, |black|. The attribute that we intend to style is the |set| +attribute. For the moment, we assume that the data sets will be named +|1|, |2|, |3|, and so on (instead of, say, |experiment 1| or |sin| or +something more readable -- we will get rid of this restriction in a +minute). + +We would now write: + +\begin{codeexample}[] +\pgfkeys{ + /pgf/data visualization/style sheets/traffic light/.cd, + % All these styles have the above prefix. + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} +\tikz \datavisualization [ + school book axes, + visualize as line=1, + visualize as line=2, + visualize as line=3, + style sheet=traffic light] +data point [x=0, y=0, set=1] +data point [x=2, y=2, set=1] +data point [x=0, y=1, set=2] +data point [x=2, y=1, set=2] +data point [x=0.5, y=1.5, set=3] +data point [x=2.25, y=1.75, set=3]; +\end{codeexample} + +In the above example, we have to name the visualizers |1|, |2|, |3| +and so one since the value of the |set| attribute is used both assign +data points to visualizers and also pick a style sheet. However, it +would be much nicer if we could name any way we want. To achieve this, +we use the special rule for style sheets that says that if there is a +subkey of an attribute whose name is the same name as the value, then +the value of this key is used instead. This slightly intimidating +definition is much easier to understand when we have a look at an +example: + +\pgfkeys{ + /pgf/data visualization/style sheets/traffic light/.cd, + % All these styles have the above prefix. + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} + +\begin{codeexample}[] +% Definition of traffic light keys as above +\begin{tikzpicture} + \datavisualization data group {lines} = { + data point [x=0, y=0, set=normal] + data point [x=2, y=2, set=normal] + data point [x=0, y=1, set=heated] + data point [x=2, y=1, set=heated] + data point [x=0.5, y=1.5, set=critical] + data point [x=2.25, y=1.75, set=critical] + }; + \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + /data point/set/normal/.initial=1, + /data point/set/heated/.initial=2, + /data point/set/critical/.initial=3, + style sheet=traffic light] + data group {lines}; +\end{tikzpicture} +\end{codeexample} + +Now, it is a bit bothersome that we have to set all these +|/data point/set/...| keys by hand. It turns out that this is not +necessary: Each time a visualizer is created, a subkey of +|/data point/set| with the name of the visualizer is created +automatically and a number is stored that is increased for each new +visualizer in a data visualization. This means that the three lines +starting with |/data point| are inserted automatically for you, so +they can be left out. However, you would need them for instance when +you would like several different data sets to use the same styling: + + +\begin{codeexample}[] +% Definition of traffic light keys as above +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + /data point/set/critical/.initial=1, % same styling as first set + style sheet=traffic light] +data group {lines}; +\end{codeexample} + +We can a command that slightly simplifies the definition of style +sheets: + +\begin{command}{\pgfdvdeclarestylesheet\marg{name}\marg{keys}} + This command executes the \meta{keys} with the path prefix + |/pgf/data visualization/style sheets/|\penalty0\meta{name}. The above + definition of the traffic light style sheet could be rewritten as + follows: +\begin{codeexample}[code only] +\pgfdvdeclarestylesheet{traffic light}{ + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} +} +\end{codeexample} +\end{command} + +As a final example, let us create a style sheet that changes the +dashing pattern according to the value of the attribute. We do not +need to define an large number of styles in this case, but can use the +|default style| key to ``calculate'' the correct dashing. + +\begin{codeexample}[] +\pgfdvdeclarestylesheet{my dashings}{ + default style/.style={dash pattern={on #1pt off 1pt}} +} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=my dashings] +data group {lines}; +\end{codeexample} + +\subsubsection{Creating a New Color Style Sheet} + +Creating a style sheet that varies colors according to an attribute +works the same way as creating a normal style sheet: Subkeys lies |1|, +|2|, and so on use the |style| attribute to setup a color. However, +instead of using the |color| attribute to set the color, you should +use the |visualizer color| key to set the color: + +\begin{key}{/tikz/visualizer color=\meta{color}} + This key is used to set the color |visualizer color| to + \meta{color}. This color is used by visualizers to color the data + they visualize, rather than the current ``standard color.'' The + reason for not using the normal current color is simply that it + makes many internals of the data visualization engine a bit + simpler. +\begin{codeexample}[] +\pgfdvdeclarestylesheet{my colors} +{ + default style/.style={visualizer color=black}, + 1/.style={visualizer color=black}, + 2/.style={visualizer color=red!80!black}, + 3/.style={visualizer color=blue!80!black}, +} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=my colors] +data group {lines}; +\end{codeexample} +\end{key} + +There is an additional command that makes it easy to define a style +sheet based on a \emph{color series}. Color series are a concept from +the |xcolor| package: The idea is that we start with a certain color +for the first data set and then add a certain ``color offset'' for +each next data point. Please consult the documentation of the |xcolor| +package for details. + +\begin{command}{\tikzdvdeclarestylesheetcolorseries\marg{name}\marg{color + model}\marg{initial color}\marg{step}} + This command creates a new style sheet using + |\pgfdvdeclarestylesheet|. This style sheet will only have a default + style setup that maps numbers to the color in the color series + starting with \meta{initial color} and having a stepping of + \meta{step}. Note that when the value of the attribute is |1|, which + it is the first data set, the \emph{second} color in the color + series is used (since counting starts at |0| for color + series). Thus, in general, you need to start the \meta{initial + color} ``one early.'' +\begin{codeexample}[] +\tikzdvdeclarestylesheetcolorseries{greens}{hsb}{0.3,1.3,0.8}{0,-.4,-.1} +\tikz \datavisualization [ + school book axes, + visualize as line=normal, + visualize as line=heated, + visualize as line=critical, + style sheet=greens] +data group {lines}; +\end{codeexample} + +\end{command} + -\subsection{Usage: Selecting Style Sheets} -\subsection{Usage: Labeling Visualizations} \subsection{Reference: Style Sheets for Lines} +The following style sheets can be applied to visualizations that use +the |visualize as line| and related keys. For the examples, the +following style and data set are used: + +\begin{codeexample}[code only] +\tikzdatavisualizationset { + example visualization/.style={ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + 1={label in legend={text=$\frac{1}{6}\sin 11x$}}, + 2={label in legend={text=$\frac{1}{7}\sin 12x$}}, + 3={label in legend={text=$\frac{1}{8}\sin 13x$}}, + 4={label in legend={text=$\frac{1}{9}\sin 14x$}}, + 5={label in legend={text=$\frac{1}{10}\sin 15x$}}, + 6={label in legend={text=$\frac{1}{11}\sin 16x$}}, + 7={label in legend={text=$\frac{1}{12}\sin 17x$}}, + 8={label in legend={text=$\frac{1}{13}\sin 18x$}} + } +} +\end{codeexample} +\tikzdatavisualizationset { + example visualization/.style={ + scientific axes=clean, + y axis={ticks={style={ + /pgf/number format/fixed, + /pgf/number format/fixed zerofill, + /pgf/number format/precision=2}}}, + x axis={ticks={tick suffix=${}^\circ$}}, + 1={label in legend={text=$\frac{1}{6}\sin 11x$}}, + 2={label in legend={text=$\frac{1}{7}\sin 12x$}}, + 3={label in legend={text=$\frac{1}{8}\sin 13x$}}, + 4={label in legend={text=$\frac{1}{9}\sin 14x$}}, + 5={label in legend={text=$\frac{1}{10}\sin 15x$}}, + 6={label in legend={text=$\frac{1}{11}\sin 16x$}}, + 7={label in legend={text=$\frac{1}{12}\sin 17x$}}, + 8={label in legend={text=$\frac{1}{13}\sin 18x$}} + } +} + +\begin{codeexample}[code only] +\tikz \datavisualization data group {sin functions} = { + data [format=function] { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } +}; +\end{codeexample} +\tikz \datavisualization data group {sin functions} = { + data [format=function] { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } +}; + +\begin{stylesheet}{vary thickness} + This style varies the thickness of lines. It should be used only + when there are only two or three lines, and even then it is not + particularly pleasing visually. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{vary dashing} + This style varies the dashing of lines. Although it is not + particularly pleasing visually and although visualizations using + this style sheet tend to look ``excited'' (but not necessarily + ``exciting''), this style sheet is often the best choice when the + visualization is to be printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} + As can be seen, there are only seven distinct dashing patterns. The + eighth and further lines will use a solid line once more. You will + then have to specify the dashing ``by hand'' using the |style| + option together with the visualizer. +\end{stylesheet} + +\begin{stylesheet}{vary dashing and thickness} + This style alternates between varying the thickness and the dashing + of lines. The + difference to just using both the |vary thickness| and + |vary dashing| is that too thick lines are avoided. Instead, this + style creates clearly distinguishable line styles for many lines (up + to 14) with a minimum of visual clutter. This style is the most + useful for visualizations when many different lines (ten or more) + should be printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness + and dashing] +data group {sin functions}; +\end{codeexample} + For comparison, here is the must-less-than-satisfactory result of + combining the two independent style sheets: +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary thickness, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\subsection{Reference: Style Sheets for Scatter Plots} + +The following style sheets can be used both for scatter plots and also +with lines. In the latter case, the marks are added to the lines. + +\begin{stylesheet}{cross marks} + This style uses different crosses to distinguish between the data + points of different data sets. The crosses were chosen in such a way + that when two different cross marks lie at the same coordinate, + their overall shape allows one to still uniquely determine which + marks are on top of each other. + + This style supports only up to six different data sets. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as scatter/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=cross marks] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=cross marks] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + \subsection{Reference: Color Style Sheets} +Color style sheets are very useful for creating visually pleasing data +visualizations that contain multiple data sets. However, there are two +things to keep in mind: + +\begin{itemize} +\item At some point, every data visualization is printed or photo + copied in black and white by someone. In this case, data sets can + often no longer be distinguished. +\item A few people are color blind. They will not be able to + distinguish between red and green lines (and some people are not + even able to distinguish colors at all). +\end{itemize} + +For these reasons, if there is any chance that the data visualization +will be printed in black and white at some point, consider combining +color style sheets with style sheets like |vary dashing| to make data +sets distinguishable in all situations. + + +\begin{stylesheet}{strong colors} + This style sheets uses pure primary colors that can very easily be + distinguished. Although not as visually pleasing as the |vary hue| + style sheet, the visualizations are easier to read when this style + sheet is used. Up to six different data sets are supported. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=strong colors] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=strong colors, + style sheet=vary dashing] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +Unlike |strong colors|, the following style sheets support, in +principle, an unlimited number of data set. In practice, as always, +more than four or five data sets lead to nearly indistinguishable data +sets. + +\begin{stylesheet}{vary hue} + This style uses a different hue for each data set. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=vary hue] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + +\begin{stylesheet}{shades of blue} + As the name suggests, different shades of blue are used for different + data sets. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=shades of blue] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{shades of red} +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=shades of red] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\begin{stylesheet}{gray scale} + For once, this style sheet can also be used when the visualization + is printed in black and white. +\begin{codeexample}[width=10cm] +\tikz \datavisualization [ + visualize as smooth line/.list= + {1,2,3,4,5,6,7,8}, + example visualization, + style sheet=gray scale] +data group {sin functions}; +\end{codeexample} +\end{stylesheet} + + +\subsection{Usage: Labeling Data Sets Inside the Visualization} + +In a visualization that contains multiple data sets, it is often +necessary to clearly point out which line or mark type corresponds to +which data set. This can be done in the main text via a sentence like +``the normal data (black) lies clearly below the critical values +(red),'' but it often a good idea to indicate data sets ideally +directly inside the data visualization or directly next to it in a +so-called legend. + +The data visualization engine has direct support both for indicating +data sets directly inside the visualization and also for indicating +them in a legend. + +The ``best'' way of indicating where a data set lies or which color is +used for it is to put a label directly inside the data +visualization. The reason this is the ``best'' way is that people do +not have to match the legend entries against the data, let alone +having to look up the meaning of line styles somewhere in the +text. However, adding a label directly inside the visualization is +also the most tricky way of indicating data sets since it is hard to +compute good positions for the labels automatically and since there +needs to be some empty space where the label can be put. + +\subsubsection{Placing a Label Next to a Data Set} + +The following key is used to create a label inside the data +visualization for a data set: + +\begin{key}{/tikz/data visualization/visualizer options/label in data=\meta{options}} + This key is passed to a visualizer that has previously been created + using keys starting |visualize as ...|. It will create a label + inside the data visualization ``next'' to the visualizer (the + details are explained in a moment). You can use this key multiple + times with a visualizer to create multiple labels at different + points with different texts. + + The \meta{options} determine which text is shown and where it is + shown. They are executed with the following path prefix: +\begin{codeexample}[code only] +/tikz/data visualization/visualizer label options +\end{codeexample} + + In order to configure which text is shown and where, use the + following keys inside the \meta{options}: + + \begin{key}{/tikz/data visualization/visualizer label options/text=\meta{text}} + This is the text that will be displayed next to the data. It will + be to the ``left'' of the data, see the description below. + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/text'=\meta{text}} + Like |text|, only the text will be to the ``right'' of the data. + \end{key} + + The following keys are used to configure where the label will be + shown. They use different strategies to specify one data point where + the label will be anchored. The coordinate of this data point will + be stored in |(label| |visualizer| |coordinate)|. Independently of + the strategy, once the data point has been chosen, the coordinate of + the next data point is stored in |(label| |visualizer| + |coordinate')|. Then, a (conceptual) line is created from the first + coordinate to the second and a node is placed at the beginning of + this line to its ``left'' or, for the |text'| option, on its + ``right.'' More precisely, an automatic anchor is computed for a + node placed implicitly on this line using the |auto| option or, for + the |text'| option, using |auto,swap|. + + The node placed at the position computed in this way will have the + \meta{text} set by the |text| or |text'| option and its styling is + determined by the current |node style|. + + Let us now have a look at the different ways of determining the data + point at which the label in anchored: + \begin{key}{/tikz/data visualization/visualizer label + options/when=\meta{attribute}| is|\meta{number}} + This key causes the value of the \meta{attribute} to be monitored + in the stream of data points. The chosen is data point is the + first data point where the \meta{attribute} is at least + \meta{number} (if this never happens, the last data point is used). +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + log= {label in data={text'=$\log x$, when=y is -1, + text colored}}, + lin= {label in data={text=$x/2$, when=x is 2}}, + squared={label in data={text=$x^2$, when=x is 1.1}}, + exp= {label in data={text=$e^x$, when=x is -2, + text colored}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label + options/index=\meta{number}} + This key chooses the \meta{number}th data point belonging to the + visualizer's data set. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={exp}, + exp= {label in data={text=$5$, index=5}, + label in data={text=$10$, index=10}, + label in data={text=$20$, index=20}, + style={mark=x}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/pos=\meta{fraction}} + This key chooses the first data point belonging to the data set + whose index is at least \meta{fraction} times the number of all + data points in the data set. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line=exp, + exp= {label in data={text=$.2$, pos=0.2}, + label in data={text=$.5$, pos=0.5}, + label in data={text=$.95$, pos=0.95}, + style={mark=x}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/data visualization/visualizer label options/auto} + This key is executed automatically by default. It works like the + |pos| option, where the \meta{fraction} is set to $(\meta{data set's + index}-1/2)/\meta{number of data sets}$. For instance, when + there are $10$ data sets, the fraction for the first one will be + $5\%$, the fraction for the second will be $15\%$, for the third + it will be $25\%$, ending with $95\%$ for the last one. + + The net effect of all this is that when there are several lines, + labels will be placed at different positions along the lines with + hopefully only little overlap. +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as smooth line/.list={linear, squared, cubed}, + linear ={label in data={text=$2x$}}, + squared={label in data={text=$x^2$}}, + cubed ={label in data={text=$x^3$}}] +data [set=linear, format=function] { + var x : interval [0:1.5]; + func y = 2*\value x; +} +data [set=squared, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x; +} +data [set=cubed, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x * \value x; +}; +\end{codeexample} + As can be seen in the example, the result is not always + satisfactory. In this case, the |pin in data| option might be + preferable, see below. + \end{key} + + The following keys allow you to style labels. + + \begin{key}{/tikz/data visualization/visualizer label + options/node style=\meta{options}} + Just passes the options to |/tikz/data visualization/node style|. + \end{key} + \begin{key}{/tikz/data visualization/visualizer label + options/text colored} + Causes the |node style| to set the text color to + |visualizer color|. The effect of this is that the label's text + will have the same color as the data set to which it is attached. + \end{key} + + \begin{stylekey}{/tikz/data visualization/every data set label} + This style is executed with every label that represents a + data set. Inside this style, use |node style| to change the + appearance of nodes. This style has a default definition, usually + you should just append things to this style. + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {label in data={text'=$\log x$, when=y is -1}}, + lin= {label in data={text=$x/2$, + node style=sloped, when=x is 2}}, + squared={label in data={text=$x^2$, when=x is 1.1}}, + exp= {label in data={text=$e^x$, + node style=sloped, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} + \end{stylekey} + + \begin{stylekey}{/tikz/data visualization/every label in data} + Like |every data set label|, this key is also executed with + labels. However, this key is executed after the style sheets have + been executed, giving you a chance to overrule their styling. + \end{stylekey} +\end{key} + +\subsubsection{Connecting a Label to a Data Set via a Pin} + +\begin{key}{/tikz/data visualization/visualizer options/pin in data=\meta{options}} + This key is a variant of the |label in data| key and takes the same + options, plus two additional ones. The difference to |label in data| + is that the label node is shown a bit removed from the data set, but + connected to it via a small line (this is like the difference + between the |label| and |pin| options). +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as smooth line/.list={linear, squared, cubed}, + linear ={pin in data={text=$2x$}}, + squared={pin in data={text=$x^2$}}, + cubed ={pin in data={text=$x^3$}}] +data [set=linear, format=function] { + var x : interval [0:1.5]; + func y = \value x; +} +data [set=squared, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x; +} +data [set=cubed, format=function] { + var x : interval [0:1.5]; + func y = \value x * \value x * \value x; +}; +\end{codeexample} + The following keys can be used additionally: + \begin{key}{/tikz/data visualization/visualizer label options/pin angle=\meta{angle}} + The position of the label of a |pin in data| is mainly computed in + the same way as for a |label in data|. However, once the position + has been computed, the label is shifted as follows: + \begin{itemize} + \item When an \meta{angle} is specified using the present key, the + shift is by the current value of |pin length| in the direction + of \meta{angle}. + \item When \meta{angle} is empty (which is the default), then the + shift is also by the current value of |pin length|, but now in + the direction that is orthogonal and to the left of the line + between the coordinate of the data point and the coordinate of + the next data point. When |text'| is used, the direction is to + the right instead of the left. + \end{itemize} + \end{key} + + \begin{key}{/tikz/data visualization/visualizer label options/pin length=\meta{dimension}} + See the description of |pin angle|. + \end{key} + +\begin{codeexample}[width=6.3cm] +\tikz \datavisualization [ + school book axes, + x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + every data set label/.append style={text colored}, + log= {pin in data={text'=$\log x$, when=y is -1}}, + lin= {pin in data={text=$x/2$, when=x is 2, + pin length=1ex}}, + squared={pin in data={text=$x^2$, when=x is 1.1, + pin angle=230}}, + exp= {label in data={text=$e^x$, when=x is -2}}, + style sheet=vary hue] +data group {function classes}; +\end{codeexample} +\end{key} + + + +\subsection{Usage: Labeling Data Sets Inside a Legend} + +The ``classical'' way of indicating the style used for the different +data sets inside a visualization is a \emph{legend}. It is a +description next to or even inside the visualization that contains one +line for each data set and displays an iconographic version of the +data set next to some text labeling the data set. Note, however, that +even though legend are quite common, also +consider using a |label in data| or a |pin in data| instead. + +Creating a high-quality legend is by no means simple. A legend should +not distract the reader, so aggressive borders should definitively be +avoided. A legend should make it easy to match the actual +styling of a data set (like, say, using a red, dashed line) to +the ``iconographic'' representation of this styling. An example of +what can go wrong here is using short lines to represent lines dashed +in different way where the lines are so short that the differences in +the dashing cannot be discerned. Another example is showing straight +lines with plot marks on them where the plot marks are obscured by the +horizontal line itself, while the plot marks are clearly visible in +the actual visualization since no horizontal lines occur. + +The data visualization engine comes with a large set of options for +creating and placing high-quality legends next or inside data +visualizations. + +\subsubsection{Creating Legends and Legend Entries} + +A data visualization can be accompanied by one or more legends. In +order to create a legend, the following key can be used (although, in +practice, you will usually use the |legend| key instead, see below): + +\begin{key}{/tikz/data visualization/new legend=\meta{legend name} + (default main legend)} + This key is used to create a new legend named \meta{legend name}. The + legend is empty by default and further options are needed to add + entries to it. When the key is called a second time for the same + \meta{legend name} nothing happens. + + When a legend is created, a new key is created that can + subsequently be used to configure the legend: + \begin{key}{/tikz/data visualization/\meta{legend name}=\meta{options}} + When this key is used, the \meta{options} are executed with the + path prefix +\begin{codeexample}[code only] +/tikz/data visualization/legend options +\end{codeexample} + The different keys with this path prefix allow you to change the + position where the legend is shown and how it is organised (for + instance, whether legend entries are shown in a row or in a column + or in a square). + + The different possible keys will be explained in the course of + this section. + \end{key} + + In the end, the legend is just a \tikzname\ node, a |matrix| node, + to be precise. The following key is used to style this node: + + + \begin{key}{/tikz/data visualization/legend options/matrix node style=\meta{options}} + Adds the \meta{options} to the list of options that will be + executed when the legend's node is created. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={matrix node style={fill=black!25}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + \end{key} + + + The following style allows you to configure the default appearance + of every newly created legend: + \begin{stylekey}{/tikz/data visualization/legend options/every new legend} + This key defaults to |east outside, label style=text right|. This means + that by default a legend is placed to the right of the data + visualization and that in the individual legend entries the text + is to the right of the data set visualization. + \end{stylekey} + +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + new legend={upper legend}, + new legend={lower legend}, + upper legend=above, + lower legend=below, + log= {label in legend={text=$\log x$, legend=upper legend}}, + lin= {label in legend={text=$x/2$, legend=upper legend}}, + squared={label in legend={text=$x^2$, legend=lower legend}}, + exp= {label in legend={text=$e^x$, legend=lower legend}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend=\meta{options}} + This is a shorthand for |new legend=main legend, main legend=|\meta{options}. + In other words, this key creates a new |main legend| and immediately + passes the configuration \meta{options} to this legend. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list={log, lin, squared, exp}, + legend=below, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} +\end{key} + +As pointed out above, a legend is empty by default. In particular, +the different data sets are not automatically inserted into the +legend. Instead, the key |label in legend| must be used together +with a data set: + +\begin{key}{/tikz/data visualization/visualizer options/label in legend=\meta{options}} + This key is passed to a data set, similar to options like + |pin in data| or |smooth line|. The \meta{options} are used to + configure the following: + \begin{itemize} + \item The legend in which the data set should be visualized. + \item The text that is to be shown in the legend for the data set. + \item The appearance of the legend entries. + \end{itemize} + In detail, the \meta{options} are executed with the path prefix +\begin{codeexample}[code only] +/tikz/data visualization/legend entry options +\end{codeexample} + To configure in which legend the label should appear, use the + following key: + \begin{key}{/tikz/data visualization/legend entry + options/legend=\meta{name} (initially main legend)} + Set this key to the name of a legend that has previously been + created using |new legend|. The label will then be shown in this + legend. + + In most cases, there is only one legend (namely |main legend|) and + there is no need to set this key since it defaults to the main + legend. + + Also note that the legend \meta{name} is automatically created if + it nodes not yet exist. + \end{key} + + \begin{key}{/tikz/data visualization/legend entry options/text=\meta{text}} + Use this key to setup the \meta{text} that is shown as the label + of the data set. + +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={pin in data ={text=$x^2$, pos=0.1}}, + exp= {label in data ={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + \end{key} + + In addition to the two keys described above, there are further + keys that are described in + Section~\ref{section-dv-label-legend-entry-options}. +\end{key} + + +\subsubsection{Rows and Columns of Legend Entries} + +In a legend, the different legend entries are arranged in a matrix, +which typically has only one row or one column. For the impatient +reader: Say |rows=1| to get everything in a row, say |columns=1| to +get everything in a single column, and skip the rest of this section. + +The more patient reader will appreciate that when there are very many +different data sets in a single visualization, it may be +necessary to use more than one row or column inside the legend. +\tikzname\ comes with a rather powerful mechanism for distributing the +multiple legend entries over the matrix. + +The first thing to decide is in which ``direction'' the entries should +be inserted into the matrix. Suppose we have a $3 \times 3$ matrix and +our entries are $a$, $b$, $c$, and so on. Then, one might place the +$a$ in the upper left corner of the matrix, $b$ in the upper middle +position, $c$ in the upper right position, and $d$ in the middle left +position. This is a ``first right, then down'' strategy. A different +strategy might be to place the $a$ in the upper left corner, but $b$ +in the middle left position, $c$ in the lower left position, and $d$ +then in the upper middle position. This is a ``first down, then +right'' strategy. In certain situations it might even make sense to +place $a$ in the lower right corner and then go ``first up, then +left''. + +All of these strategies are supported by the |legend| command. You can +configure which strategy is used using the following keys: + +\tikzdatavisualizationset { + legend example/.style={ + scientific axes, all axes={length=1cm, ticks=none}, + 1={label in legend={text=1}}, + 2={label in legend={text=2}}, + 3={label in legend={text=3}}, + 4={label in legend={text=4}}, + 5={label in legend={text=5}}, + 6={label in legend={text=6}}, + 7={label in legend={text=7}}, + 8={label in legend={text=8}} + } +} + + +\begin{key}{/tikz/data visualization/legend options/down then right} + Causes the legend entries to fill the legend matrix first downward + and, once a column is full, the next column is begun to the right of + the previous one. This is the default. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={down then right, columns=3}] +data group {sin functions}; +\end{codeexample} + In the example, the |legend example| is the following style: +\begin{codeexample}[code only] +\tikzdatavisualizationset { + legend example/.style={ + scientific axes, all axes={length=1cm, ticks=none}, + 1={label in legend={text=1}}, + 2={label in legend={text=2}}, + 3={label in legend={text=3}}, + 4={label in legend={text=4}}, + 5={label in legend={text=5}}, + 6={label in legend={text=6}}, + 7={label in legend={text=7}}, + 8={label in legend={text=8}} + } +} +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/down then left} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={down then left, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/up then right} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={up then right, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/up then left} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={up then left, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/left then up} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={left then up, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/left then down} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={left then down, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right then up} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then up, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right then down} +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down, columns=3}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +Having configured the directions in which the matrix is being filled, +you must next setup the number of rows or columns that are to be +shown. There are actually two different ways of doing so. The first +way is to specify a maximum number of rows or columns. For instance, +you might specify that there should be at most ten rows to a column +and when there are more, a new column should be begun. This is +achieved using the following keys: + +\begin{key}{/tikz/data visualization/legend options/max rows=\meta{number}} + As the legend matrix is being filled, whenever the number of rows in + the current column would exceed \meta{number}, a new column is + started. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=3}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=5}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/max columns=\meta{number}} + This key works like |max rows|, only now the number of columns is + monitored. Note that this strategy only really makes sense when the + when you use this key with a strategy that first goes left or right + and then up or down. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down, max columns=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down,max columns=3}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={right then down,max columns=4}] +data group {sin functions}; +\end{codeexample} +\end{key} + + +The second way of specifying the number of entries in a row or column +is to specify an ``ideal number of rows or columns.'' The idea is as +follows: Suppose that we use the standard strategy and would like to +have everything in two columns. Then if there are eight entries, the +first four should go to the first column, while the next four should +go to the second column. If we have 20 entries, the first ten should +go the first column and the next ten to the second, and so on. So, in +general, the objective is to distribute the entries evenly so the this +``ideal number of columns'' is reached. Only when there are too few +entries to achieve this or when the number of entries per column would +exceed the |max rows| value, will the number of columns deviate from +this ideal value. + + + +\begin{key}{/tikz/data visualization/legend options/ideal number of columns=\meta{number}} + Specifies, that the entries should be split into \meta{number} + different columns, whenever possible. However, when there would be + more than the |max rows| value of rows per column, more columns than + the ideal number are created. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of columns=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of columns=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max rows=3,ideal number of columns=2}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/rows=\meta{number}} + Shorthand for |ideal number of rows=|\meta{number}. +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/ideal number of rows=\meta{number}} + Works like |ideal number of columns|. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of rows=2}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={ideal number of rows=4}] +data group {sin functions}; +\end{codeexample} +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + visualize as smooth line/.list={1,2,3,4,5,6,7,8}, + legend example, style sheet=vary hue, + main legend={max columns=3,ideal number of rows=2}] +data group {sin functions}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/columns=\meta{number}} + Shorthand for |ideal number of columns=|\meta{number}. +\end{key} + + +\subsubsection{Legend Placement: The General Mechanism} + +A legend can either be placed next to the data visualization or inside +the data visualization at some place where there are no data +entries. Both approached have advantages: Placing the legend next to +the visualization minimises the ``cluttering'' by keeping all the +extra information apart from the actual data, while placing the legend +inside the visualization minimises the distance between the data sets +and their explanations, making it easier for the eye to connect them. + +For both approaches there are options that make the placement easier, +see Sections \ref{section-dv-legend-outside} +and~\ref{section-dv-legend-inside}, but these options internally just +map to the following two options: + +\begin{key}{/tikz/data visualization/legend + options/anchor=\meta{anchor}} + The whole legend is a \tikzname-matrix internally. Thus, + in particular, it is stored in a node, which has anchors. Like for + any other node, when the node is shown, the node is shifted in such + a way that the \meta{anchor} of the node lies at the current |at| + position. +\end{key} + +\begin{key}{/tikz/data visualization/legend + options/at=\meta{coordinate}} + Configures the \meta{coordinate} at which the \meta{anchor} of the + legend's node should lie. + + It may seem hard to predict a good \meta{coordinate} for a legend + since, depending of the size of the axis, different positions need + to the chosen for the legend. However, it turns out that one + can often use the coordinates of the special nodes + |data bounding box| and |data visualization bounding box|, + documented in Section~\ref{section-dv-bounding-box}. + + As an example, let us put a legend to the right of the + visualization, but so that the first entry starts at the top of the + visualization: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, x axis={label=$x$}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={anchor=north west, at= + (data visualization bounding box.north east)}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=vary dashing] +data group {function classes}; +\end{codeexample} + As can be seen, a bit of an additional shift might have been in + order, but the result is otherwise quite satisfactory. +\end{key} + + +\subsubsection{Legend Placement: Outside to the Data Visualization} +\label{section-dv-legend-outside} + +The following keys make it easy to place a legend outside the data +visualization. + +\begin{key}{/tikz/data visualization/legend options/east outside} + Placing the legend to the right of the data visualization is the default: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + + \begin{key}{/tikz/data visualization/legend options/right} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north east outside} + A variant, where the legend is to the right, but aligned with the + northern end of the data visualization: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south east outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/west outside} + The legend is placed left. Note that the text also swaps its + position. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/left} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north west outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south west outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south west outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend options/north outside} + The legend is placed above the data. Note that the legend entries + now for a row rather than a column. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/above} + This is an easier-to-remember alias. + \end{key} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/south outside} +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=south outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + \begin{key}{/tikz/data visualization/legend options/below} + This is an easier-to-remember alias. + \end{key} +\end{key} + + + +\subsubsection{Legend Placement: Inside to the Data Visualization} +\label{section-dv-legend-inside} + +There are two sets of options for placing a legend directly inside a +data visualization: First, there are options for placing it inside, +but next to some part of the border. Second, there are options for +positioning it relative to a coordinate given by a certain data point. + + + +\begin{key}{/tikz/data visualization/legend options/south east inside} + Puts the legend in the upper right corner of the data. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin}, + legend=south east inside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} + + Note that the text is now a little smaller since there tends to be + much less space inside the data visualization than next to it. Also, + the legend's node is filled in white by default to ensures that the + legend is clearly legible even in the presence of, say, a grid or + data points behind it. This behaviour is triggered by the following + style key: + + \begin{stylekey}{/tikz/data visualization/legend options/every legend inside} + Executed the keys |opaque| by default and sets the text size to + the size of footnotes. + \end{stylekey} +\end{key} + +In order to further configure the default appearance of an inner +legend, the following keys might be useful: + +\begin{key}{/tikz/data visualization/legend + options/opaque=\meta{color} (default white)} + When this key is used, the legend's node will be filled with the + \meta{color} and its corners will be rounded. Additionally, the + inner and outer separations will be set to sensible values. +\end{key} +\begin{key}{/tikz/data visualization/legend + options/transparent} + Sets the filling of the legend node to |none|. +\end{key} + +The following keys work much the same way as |south east inside|: + +\begin{key}{/tikz/data visualization/legend options/east inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/north east inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/south west inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/west inside} +\end{key} +\begin{key}{/tikz/data visualization/legend options/north west inside} +\end{key} + +The keys |south inside| and |north inside| are a bit different: They use a row +rather than a column for the legend entries: + +\begin{key}{/tikz/data visualization/legend options/south inside} + Puts the legend in the upper right corner of the data. Note that the + text is now a little smaller since there tends to be much less space + inside the data visualization than next to it. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend=south inside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/north inside} + As above. +\end{key} + +The above keys do not always give you as fine a control as you may +need over the placement of the legend. In such cases, the following +keys may help (or you can revert to directly setting the |at| and the +|anchor| keys): + +\begin{key}{/tikz/data visualization/legend options/at + values=\meta{data point}} + This key allows you to specify the desired center of the legend in + terms of a data point. The \meta{data point} should be a list of + comma-separated key--value pairs that specify a data point. The + legend will then be centered at this data point. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend={at values={x=-1, y=2}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend options/right + of=\meta{data point}} + Works like |at values|, but the anchor is set to |west|: +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list={log, lin}, + legend={right of={x=-1, y=2}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +The following keys work similarly: +\begin{key}{/tikz/data visualization/legend options/above right of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/above of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/above left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below left of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below of=\meta{data point}} +\end{key} +\begin{key}{/tikz/data visualization/legend options/below right of=\meta{data point}} +\end{key} + + + + +\subsubsection{Legend Entries: General Styling} + +\label{section-dv-label-legend-entry-options} + +The entries in a legend can be styled in several ways: + +\begin{itemize} +\item + You can configure the styling of the text node. +\item + You can configure the relative placement of the text node and the + little picture depicting the data set's styling. +\item + You can configure how the data set's styling is depicted. +\end{itemize} + +Before we have look at how each of these are configured, in detail, +let us first have a look at the keys that allow us to save a set of +such styles: + +\begin{stylekey}{/tikz/data visualization/every label in legend} + This key is executed with every label in a legend. However, the + options stored in this style are executed with the path prefix + |/tikz/data visualization/legend entry options|. Thus, this key can + use keys like |node style| to configure the styling of all text + nodes: +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + every label in legend/.style={node style= + {fill=red!30}}, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{stylekey} + +\begin{key}{/tikz/data visualization/legend options/label style=\meta{options}} + This key can be used with a legend. It will simply add the + \meta{options} to the |every label in legend| style for the given + legend. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style={node style=draw}}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\subsubsection{Legend Entries: Styling the Text Node} + +The appearance of the text nodes is easy to configure. + +\begin{key}{/tikz/data visualization/legend entry options/node style=\meta{options}} + This key adds \meta{options} to the styling of the text nodes of the + label. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend=north east outside, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$, + node style={circle, draw=red}}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/text colored} + Causes the |node style| to set the text color to + |visualizer color|. The effect of this is that the label's text + will have the same color as the data set to which it is attached. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style=text colored}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + +\subsubsection{Legend Entries: Text Placement} + +Three keys govern where the text will be placed relative to the data +set style visualization. + +\begin{key}{/tikz/data visualization/legend entry options/text right} + Placed the text node to the right of the data set style + visualization. This is the default for most, but not all, legends. +\end{key} +\begin{key}{/tikz/data visualization/legend entry options/text left} + Placed the text node to the left of the data set style + visualization. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={label style=text left}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/data visualization/legend entry options/text only} + Shows only the text nodes and no data set style visualization at + all. This options only makes sense in conjunction with the + |text colored| options, which is why this options is also selected + implicitly. +\begin{codeexample}[width=8cm] +\tikz \datavisualization [ + scientific axes, + visualize as smooth line/.list= + {log, lin, squared, exp}, + legend={south east inside, rows=2, + label style=text only}, + log= {label in legend={text=$\log x$}}, + lin= {label in legend={text=$x/2$}}, + squared={label in legend={text=$x^2$}}, + exp= {label in legend={text=$e^x$}}, + style sheet=strong colors] +data group {function classes}; +\end{codeexample} +\end{key} + + + + + +\subsubsection{Advanced: Labels in Legends and Their Visualizers} + +\label{section-dv-legend-entries} + +The following explanations are important only for you if you intend to +create a new visualizer and an accompanying label in legend +visualizer; otherwise you can safely proceed with the next section. + +A legend entry consists not only of some explaining text, but, even +more importantly, of a visual representation of the style used for the +data points, created by a \emph{label in legend visualizer}. For +instance, when data points are visualized as lines in +different colors, the legend entry for the first line might consist of +the text ``first experiment'' and a short line in black and the second +entry might consist of ``failed experiment'' and a short line in red +-- assuming, of course, that the style sheet makes the first line +black and the second line blue. As another example, when data sets are +visualized as clouds of plot marks, the texts in the legend would be +accompanied by the plot marks used to visualize the data sets. + +For every visualizer, the \emph{label in legend visualizer} creates an +appropriate visualization of the data set's styling. There may be more +than one possible such label in legend visualizer that is appropriate, +in which case options are used to choose between them. + +Let us start with the key for creating a new legend entry. This key +gets called for instance by |label in legend|: + +\begin{key}{/tikz/data visualization/new legend entry=\meta{options}} + This key will add a new entry to the legend that is identified by + the \meta{options}. For this, the \meta{options} are executed once + with the path prefix |/tikz/data visualization/legend entry options| + and the resulting setting of the |legend| key is used to pick which + legend the new entry should belong to. Then, the \meta{options} are + stored away for the time being. + + Later, when the legend is created, the \meta{options} get executed + once more. This time, however, the |legend| key is no longer + important. Instead, the \meta{options} that setup keys like + |text| or |visualizer in legend| now play a role. + + In detail, the following happens: + \begin{itemize} + \item For the legend entry, a little cell picture is created in the + matrix of the legend (see Section~\ref{section-tikz-cell-pictures} + for details on cell pictures). + \item Inside this picture, a node is created whose text is taken + from the key +\begin{codeexample}[code only] +/tikz/data visualization/legend entry options/text +\end{codeexample} + \item Also inside the picture, the code stored in the following key + gets executed: + \begin{key}{/tikz/data visualization/legend entry options/visualizer in legend} + Set this key to some code that paints something in the cell + picture. Typically, this will be a visual representation of the + data set styling, but it could also be something different. +\begin{codeexample}[width=6cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a}}, + new legend entry={ + text=spacer, + visualizer in legend={\draw[solid] (0,0) circle[radius=2pt];} + }, + b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + \end{key} + \end{itemize} + The following styles are applied in the following order before the + cell picture is filled: + \begin{enumerate} + \item |/tikz/data visualization/every data set label| with path + |/tikz/data visualization| + \item |/tikz/data visualization/every label in legend| with path\\ + |/tikz/data visualization/legend entry options|. + \item The \meta{options}. + \item The code in the following key: + \begin{key}{/tikz/data visualization/legend entry options/setup} + Some code to be executed at this point. Mostly, it is used to + setup attributes for style sheets. + \end{key} + \item A styling signal is emitted. + \item Only for the node: The current value of |node style|. + \item Only for the visualizer in legend: The styling that has been + accumulated by calls to the following key: + \begin{stylekey}{/tikz/data visualization/legend entry + options/visualizer in legend style=\\\marg{options}} + Calls to this key accumulate \meta{options} that will be + executed with the path prefix |/tikz| at this point. + \end{stylekey} + \end{enumerate} +\end{key} + +As indicated earlier, the |new legend entry| key is called by the +|label in legend=|\meta{options} key internally. In this case, the +following extra \meta{extra options} are passed to |new legend entry| +key: +\begin{itemize} +\item The styling of the visualizer. +\item The |/tikz/data visualization/every label in legend| style. +\item The |/tikz/every label| style with path |/tikz|. +\item Setting |setup| to |/data point/set=|\meta{name of the visualizer}. +\item The value of the |label legend options| that are stored in the + visualizer. These options can be changed using the following key: + \begin{key}{/tikz/data visualization/visualizer options/label in + legend options=\meta{options}} + Use this key with a visualizer to configure the label in legend + options. Typically, this key is used only internally by a + visualizer upon its creating to set the \meta{options} to setup + the |visualizer in legend| key. + \end{key} +\end{itemize} + + +\subsubsection{Reference: Label in Legend Visualizers for Lines and Scatter Plots} + +Visualizers like |visualize as line| or |visualize as smooth line| +use a label in legend visualizer that draws a short line to represent +the data set inside the legend. However, this line needs not be a +simple straight line, but can be a little curve or a small circle -- +indeed, even the default line is not a simple straight line but rather +a small zig-zag curve. To configure this line, the two keys +are used, although you will only rarely use them directly, but +rather use one of the predefined styles mentioned later on. + +Before we go into the glorious details of all of these keys, let us +first have a look at the keys you are most likely to use in practice: +The keys for globally reconfiguring the default label in legend +visualizers: +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend path} + This style is set, by default, to |zig zag label in legend line|. It + is installed by the styles |straight line|, |smooth line|, and + |gap line|, so changing this style will change the appearance of lines in + legends. The main other sensible option for this key is + |straight label in legend line|. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a}}, b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend entry options/default label in legend path/.style= + straight label in legend line, + style sheet=vary dashing, + a={label in legend={text=a}}, b={label in legend={text=b}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{stylekey} +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend closed path} + This style is executed by |smooth cycle| and |straight cycle|. There + are (currently) no other predefined sets of coordinates that can be + used instead of the default value |circular label in legend line|. +\end{stylekey} + +\begin{stylekey}{/tikz/data visualization/legend entry options/default + label in legend mark} + This style is executed by |no lines| and, implicitly, by scatter + plots. The default is to use + |label in legend line one mark|. Another possible value is + |label in legend line three marks|. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + legend entry options/default label in legend mark/.style= + label in legend three marks, + a={label in legend={text=example a}}, + b={label in legend={text=example b}}, + c={label in legend={text=example c}}]; +\end{codeexample} +\end{stylekey} + +\begin{key}{/tikz/data visualization/legend entry options/label in + legend line coordinates=\\\marg{list of coordinates}} + This key takes a \meta{list of coordinates}, which are + \tikzname-coordinates separated by commas like |(0,0),|\penalty0|(1,1)|. The + effect of setting the key is the following: The label in legend + visualizer used by, for instance, |visualize as line| will draw a + path going through these points. When the line is drawn, the exact + same style will be used as was used for the data set. For instance, + if the |smooth line| key was used and also the |style=red| key, the + line through the \meta{list of coordinates} will also be red and + smooth. When the |straight cycle| key was used, the coordinates will + also be connected by a cycle, and so on. + + When the line connecting the \meta{list of coordinates} is drawn, + the coordinate system will have been shifted and transformed in such + a way that |(0,0)| lies to the left of the text and at half the + height of the character ``x''. This means that the right-most-point + in the list should usually be |(0,0)| and all other $x$-coordinates + should usually be negative. When the |text left| options is used, + the coordinate system will have been flipped, so the \meta{list of + coordinates} is independent of whether the text is to the right or + to the left of the line. + + Let us now have a look at a first, simple example. We create a + legend entry that is just a straight line, so it should start + somewhere to the left of the origin at height $0$ and go to the + origin: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={(-1em,0), (0,0)}}}, + b={label in legend={text=b, + label in legend line coordinates={(-2em,0), (0,0)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + + Now let us make this a bit more fancy and useful by using shifted lines: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={(-2em,-.25ex), (0,0)}}}, + b={label in legend={text=b, + label in legend line coordinates={(-2em,.25ex), (0,0)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} + + In the final example, we use a little ``hat'' to represent lines: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, style sheet=vary dashing, + a={label in legend={text=a, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}, + b={label in legend={text=b, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/label in + legend mark coordinates=\\\marg{list of coordinates}} + This key is similar to |label in legend line coordinates|, but now + the \meta{list of coordinates} is used as the positions where plot + marks are shown. Naturally, plot marks are only shown there if they + are also shown by the visualizer in the actual data -- just like the + line through the coordinates of the previous key is only shown when + there is a line. + + The \meta{list of coordinates} may be the same as the one used for + lines, but usually it is not. In general, it is better to have marks + for instance not at the ends of the line. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + school book axes, visualize as line/.list={a,b}, + legend={up then right}, + style sheet=vary dashing, + style sheet=cross marks, + a={label in legend={text=a, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}, + label in legend mark coordinates={ + (-1em,.2ex)}}}, + b={label in legend={text=b, + label in legend line coordinates={ + (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}, + label in legend mark coordinates={ + (-2em,-.2ex), (0,-.2ex)}}}] +data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a] +data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b]; +\end{codeexample} +\end{key} + + + +Naturally, you typically will not give coordinates explicitly for each +label, but use one of the following styles: + +\begin{key}{/tikz/data visualization/legend entry options/straight label in legend line} + Just gives a straight line and two plot marks. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as line, + line={style={mark=x}, label in legend={text=example, + straight label in legend line}}]; +\end{codeexample} + This style might seem like a good idea to use in general, but it + does have a huge drawback: Some commonly used plot marks will be impossible to + distinguish -- even though there is no problem distinguishing them + in a graph. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as line/.list={a,b,c}, + legend entry options/default label in legend path/.style= + straight label in legend line, + a={style={mark=+}, label in legend={text=bad example a}}, + b={style={mark=-}, label in legend={text=bad example b}}, + c={style={mark=|}, label in legend={text=bad example c}}]; +\end{codeexample} + For this reason, this option is not the default, but rather the next one. +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/zig zag label in legend line} + Uses a small up-down-up line as the label in legend visualizer. The + two plot marks are at the extremal points of the line. It works + pretty well in almost all situations and is the default. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as line=a, + visualize as smooth line/.list={b,c}, + a={style={mark=+}, label in legend={text=better example a}}, + b={style={mark=-}, label in legend={text=better example b}}, + c={style={mark=|}, label in legend={text=better example c}}]; +\end{codeexample} + Even though the above example shows that the marks are easier to + distinguish than with a straight line, the chosen marks are still + not optimal. This is the reason that the |cross marks| style uses + different crosses: +\begin{codeexample}[width=5cm] +\tikz \datavisualization [ + visualize as line/.list={a,b}, + visualize as smooth line=c, + style sheet=cross marks, + a={label in legend={text=good example a}}, + b={label in legend={text=good example b}}, + c={gap line, label in legend={text=good example c}}]; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend entry options/circular label in legend line} + This style is especially tailored to represent lines that are + closed. It is automatically selected for instance by the |polygon| + or the |smooth cycle| styles. +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes={clean}, all axes={length=3cm}, + visualize as line/.list={a,b,c}, + a={polygon}, b={smooth cycle}, + style sheet=cross marks, + a={label in legend={text=polygon}}, + b={label in legend={text=circle}}, + c={label in legend={text=line}}] +data [format=function, set=a] { + var t : {0,72,...,359}; + func x = cos(\value t); + func y = sin(\value t); +} +data [format=function, set=b] { + var t : [0:2*pi]; + func x = .8*cos(\value t r); + func y = .8*sin(\value t r); +} +data point [x=-1, y=0.5, set=c] +data point [x=1, y=0.25, set=c]; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/data visualization/legend entry options/gap circular label in legend line} + This style is especially tailored to for the |gap cycle| style and + automatically selected by it: +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes={clean}, all axes={length=3cm}, + visualize as line/.list={a,b,c}, + a={gap cycle}, b={smooth cycle}, c={gap line}, + a={style={mark=*, mark size=0.5pt}, + label in legend={text=polygon}}, + b={label in legend={text=circle}}, + c={style={mark=*, mark size=0.5pt, mark options=red}, + label in legend={text=line}}] +data [format=function, set=a] { + var t : {0,72,...,359}; + func x = cos(\value t); + func y = sin(\value t); +} +data [format=function, set=b] { + var t : [0:352]; + func x = .8*cos(\value t); + func y = .8*sin(\value t); +} +data point [x=-1, y=0.5, set=c] +data point [x=1, y=0.25, set=c]; +\end{codeexample} +\end{key} + + + +\begin{key}{/tikz/data visualization/legend entry options/label in legend one mark} + To be used with scatter plots, since no line is drawn. Just displays + a single mark (this is the default with a scatter plot or when the + |no line| is selected. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + a={label in legend={text=example a}}, + b={label in legend={text=example b}}, + c={label in legend={text=example c}}]; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/legend entry options/label in legend three marks} + An alternative to the previous style, where several marks are + shown. +\begin{codeexample}[width=5cm] +\tikz \datavisualization [visualize as scatter/.list={a,b,c}, + style sheet=cross marks, + a={label in legend={text=example a, label in legend three marks}}, + b={label in legend={text=example b, label in legend three marks}}, + c={label in legend={text=example c, label in legend three marks}}]; +\end{codeexample} +\end{key} + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex index f7633ceae70..784e838baee 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-dv-visualizers.tex @@ -13,10 +13,772 @@ \subsection{Overview} -To be written... +In a data visualization a long stream of data points is +\emph{visualized} using \emph{visualizers}. Recall that it is the job +of the axis systems as described in Section~\ref{section-dv-axes} to +determine \emph{where} data points are visualized. It is the job of +the visualizers to determine \emph{how} they are visualized. + +The most basic and common visualizer is the \emph{line visualizer}. It +simply connects subsequent data points by straight lines to indicate +either that the points on these lines interpolate between the real +data points or the straight lines are used to indicate the order in +which the data points appear. A different, more ``conservative'' +visualizer is the \emph{scatter visualizer} or \emph{mark visualizer}, +which just places a small mark at each data point. Such a visualizer +does not imply any interpolation or ordering between the data points. + +Visualizers may, however, also be more complicated. For instance, a +visualizer used for a box plot could visualize a data point as a box +with a median value, standard deviation, outliers, and other +information; a rectangle visualizer might visualize data points as +larger areas; a projection visualizer might visualize the projection +of data points onto different axes; and so. + +Creating a new visualizer is not quite trivial since a new \pgfname\ +class needs to be implemented. Fortunately, using visualizers is much +simpler: For each kind of visualizer there is a key that allows you to +create such a visualizer. You can then use further keys to configure +the visualizer and to connect it to the data. + +In a data visualization multiple visualizers may exist at the same +time. This happens in different situations: +\begin{itemize} +\item A data visualization may contain several independent data sets + that are to be visualized. There might be a line plot, for which a + line visualizer is used, and also a scatter plot, for which a + scatter visualizer would be used. + + In this case, for each data point only one visualizer will do + anything. To achieve this, each data point has an attribute called + |visualizer| which tells the visualizer objects whether they should + ``react'' to the data point or not. +\item A single data point might be visualized several times. For + instance, a scatter visualizer might draw a mark at the data point's + position on the page and a projection visualizer might draw, + additionally, a mark at the projected position. +\end{itemize} -\subsection{Concepts} \subsection{Usage} +\subsubsection{Using a Single Visualizer} + +The simplest scenario for using visualizers are data visualizations in +which there is only a single data set that is visualized in one +style. In this case, all that needs to be done in order to choose a +visualizer is use one of the options starting with |visualize as ...| +together with the |\datavisualization| command: + +\begin{codeexample}[] +% Define a data set: +\tikz \datavisualization data group {example} = { +data { + x, y + 0, 0 + 0.5, 2 + 1, 2 + 1.5, 1.5 + 2, 0.5 +}}; +\tikz \datavisualization [school book axes, visualize as line] data group {example}; +\qquad +\tikz \datavisualization [school book axes, visualize as smooth line] data group {example}; +\qquad +\tikz \datavisualization [school book axes, visualize as scatter] data group {example}; +\end{codeexample} + +Methods for styling visualizers are discussed in Section~\ref{section-dv-visualizer-styling}. + + +\subsubsection{Using Multiple Visualizers} + +A data visualization may contain multiple data groups and for each data +set we might wish to use a different visualizer. In this case, we need +some way of telling the data visualization engine to which visualizer +should be used with the different data points. + +To solve this problem, you can \emph{name} a visualizer. The +visualizer's name can then both be used to configure the visualizer +and also to indicate that data points ``belong'' to the visualizer. + +Naming a visualizer is quite simple: The |visualize as ...| keys +actually take a single parameter, which is the name of the +visualizer. For instance, the following code creates three +visualizers, named |sin|, |cos|, and |tan|: + +\begin{codeexample}[code only] +visualize as line=sin, +visualize as line=cos, +visualize as scatter=tan +\end{codeexample} + +(When you just say |visualize as line| without providing a name, the +name |line| is chosen as a default, for |visualize as scatter| the +name |scatter| is the default and so.) + +In order to indicate which data points should be visualized by which +of these visualizers, the following key is important: + +\begin{key}{/data point/set} + A visualizer will only act on a data point when its name matches the + value of this key. Initially, this key is set to the last visualizer + created, so if there is only one, there is no need to set or worry + about this key. +\end{key} + +Since the |set| key has the path prefix |/data point|, it can +be set like any other attribute of a data key: + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as line=sin, + visualize as line=cos, + visualize as scatter=tan] +data { + x, y, set + 0, 0, sin + 1, 1, sin + 2, 0, sin + 3, -1, sin + 4, 0, sin + 0, 1, cos + 1, 0, cos + 0, 0, tan + 1, 1, tan + 2, 2, tan + 3, 4, tan + 2, -1, cos + 3, 0, cos + 4, 1, cos +}; +\end{codeexample} + +As can be seen, the data points with the same |set| attribute +do not need to be consecutive. + +The above method of specifying the visualizer works nicely, but in +most cases it would be more natural to keep the |set| attribute +out of the table. This is easy to achieve by using multiple |data| and +using the following key: + +\begin{key}{/pgf/data/set=\meta{name}} + Shorthand for |/data point/set=|\meta{name}. +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as line=sin, + visualize as line=cos] +data [set=sin] { + x, y + 0, 0 + 1, 1 + 2, 0 + 3, -1 + 4, 0 +} +data [set=cos] { + x, y + 0, 1 + 1, 0 + 2, -1 + 3, 0 + 4, 1 +}; +\end{codeexample} +\end{key} + +When you need to visualize several similar things in a single plot +(like ten lines that all get visualized by |visualize as line|), it is +somewhat cumbersome having to write this ten times. In this case you +can shorten your code by making use of the |.list| key handler: When +you add it to a key, the ``value'' passed to the key is parsed as a +list of values. The key is then executed once for each of these +values: + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as line/.list={sin, cos, tan}] +data [set=sin, format=function] { + var x : interval[0:3*pi]; + func y = sin(\value x r); +} +data [set=cos, format=function] { + var x : interval[0:3*pi]; + func y = cos(\value x r); +} +data [set=tan, format=function] { + var x : interval[0:pi/2.2]; + func y = tan(\value x r); +}; +\end{codeexample} + + + +\subsubsection{Styling a Visualizer} +\label{section-dv-visualizer-styling} + +In order to style a visualizer that has been created using for +instance |visualize as line=|\meta{visualizer name}, you can use the +following key: + +\begin{key}{/tikz/data visualization/\meta{visualizer + name}=\meta{options}} + For each visualizer, a key of the same name is created with the path + prefix |/tikz/data visualization|. This key takes the \meta{options} + and executes them with the path prefix +\begin{codeexample}[code only] +/tikz/data visualization/visualizer options/ +\end{codeexample} + These options are then used to configure the appearance of the + current visualizer. (This is quite similar to the way options are + passed to an axis in order to configure the axis.) + Possible options include |style|, but also |label in legend| and + |label in data|. The latter two options are discussed in + Section~\ref{section-dv-labels-in}, the first option below. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as smooth line/.list={sin, cos}, + sin={style=red}, + cos={style=blue}] +data [set=sin, format=function] { + var x : interval[0:3*pi]; + func y = sin(\value x r); +} +data [set=cos, format=function] { + var x : interval[0:3*pi]; + func y = cos(\value x r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer + options/style=\meta{options}} + The \meta{options} given to this key should be normal \tikzname\ + options. They will be executed when the visualizer is used. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as smooth line=sin, + sin={style={red, densely dotted}}, + visualize as smooth line=cos, + cos={style={mark=x}}, +] +data [set=sin, format=function] { + var x : interval[0:3*pi]; + func y = sin(\value x r); +} +data [set=cos, format=function] { + var x : interval[0:3*pi]; + func y = cos(\value x r); +}; +\end{codeexample} + + When you have multiple visualizers in a single data visualization, + you can use the |style| option with each visualizer to configure + their different appearances as in the above example. However, it is + usually much better (and easier) to use a style sheet, see + Section~\ref{section-dv-style-sheets}. + + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes={clean, end labels}, + x axis={label=$x$}, y axis={grid={major also at=0}}, + visualize as smooth line/.list={sin,cos,sin 2,cos 2}, + legend={below, rows=2}, + sin={label in legend={text=$\sin x$}}, + cos={label in legend={text=$\cos x$}}, + sin 2={label in legend={text=$\sin 2x$}}, + cos 2={label in legend={text=$\cos 2x$}}, + style sheet=strong colors] +data [set=sin, format=function] { + var x : interval[0:3*pi]; + func y = sin(\value x r); +} +data [set=cos, format=function] { + var x : interval[0:3*pi]; + func y = cos(\value x r); +} +data [set=sin 2, format=function] { + var x : interval[0:3*pi]; + func y = sin(2*\value x r); +} +data [set=cos 2, format=function] { + var x : interval[0:3*pi]; + func y = cos(2*\value x r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/ignore style + sheets} + This option, which should be passed to a visualizer after its + creation before another visualizer is created, causes style sheets + \emph{not} to apply to the visualizer (but the |style| option will + still have an effect). This allows you to create visualizers that + are used for special purposes and that do not ``take part'' in the + usual styling. For instance, a visualizer might be used internally + to depict a regression line, even though the regression line itself + should not participate in the usual styling by, say, dashing or + different coloring. +\end{key} + +In addition to the options passed to a visualizer via |style|, the +following also gets executed when a visualizer is used: + +\begin{stylekey}{/tikz/data visualization/every visualizer} + This style is used with every visualizer. Note that it should + contain normal \tikzname\ keys. + +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + every visualizer/.style={dashed}, + visualize as smooth line] +data [format=function] { + var x : interval[0:3*pi]; + func y = sin(\value x r); +}; +\end{codeexample} +\end{stylekey} + + \subsection{Reference: Basic Visualizers} + +\subsubsection{Visualizing Data Points Using Lines} + +\begin{key}{/tikz/data visualizers/visualize as line=\meta{visualizer + name} (default line)} + Creates a new visualizer named \meta{visualizer name}. Basically, + this visualizer connects all data points for which the + |/data point/set| attribute equals \meta{visualizer name} by + a line that is styled by the visualizer's style. + + In more detail, the following happens: + \begin{enumerate} + \item A new object is created (of class |plot handler visualizer|) + that is configured to collect the canvas positions of all data + points whose |set| attribute equals \meta{visualizer name}. + \item During the end of the data visualization, \pgfname's plotting + mechanism (see Section~\ref{section-plots}) is used to plot the + stream of recorded data points. + + This means that, in principle, all of the plot handlers available + in \tikzname\ could be used for the visualization (such as the + |smooth| handler). However, some plot handlers such as, say, the + |xcomb| are unsuitable as plot handlers since they do not support + the advanced axis handling done by the data visualization + engine. Because of this (and also for other reasons), you cannot + set the plot handler directly, but must use one of the options + like |straight line|, |smooth line| and others, documented in a + moment. + \item Additionally, plot marks can be drawn at the collected data + points. Here, all of the options available to \tikzname\ for + drawing plot marks are available. To configure them, all options + offered by \tikzname\ for configuring marks are available such as + |mark repeat|: +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as line=my data, + my data={style={mark=x, mark repeat=3}}] +data [format=function] { + var x : interval [0:pi] samples 10; + func y = sin(\value x r); +}; +\end{codeexample} + \end{enumerate} + + The line visualizer also provides a method of dealing with gaps in a + line. Take for instance the function $f(x) = \tan x$. When this + function is plotted over the interval $[0,\pi]$, then the function + will go to $\pm \infty$ at $\pi/2$. When we plot this, we might plot + the function in the interval $[0,\frac{\pi}{2}-\epsilon]$ and then + continue in the interval $[\frac{\pi}{2}+\epsilon,\pi]$. However, we + do not want the point at coordinate $\bigl(\frac{\pi}{2}- \epsilon, + \tan(\frac{\pi}{2}- \epsilon)\bigr)$ to be connected to the + coordinate $\bigl(\frac{\pi}{2}+ \epsilon, \tan(\frac{\pi}{2}+ + \epsilon)\bigr)$ by a line. Rather, there should be a ``gap'' or a + ``jump'' between these coordinates. To achieve this, the following + key can be used: + \begin{key}{/data point/outlier=\meta{value} (default true, initially \normalfont empty)} + When this key is set to anything non-empty value, a visualizer + will consider this data point to be an ``outlier.'' For a line + visualizer this means that the point is not shown and that the + current line ends at the previous data point and a new line starts + at the next data point. +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, x axis={grid={major at=(pi/2)}}, + visualize as smooth line] +data [format=function] { + var x : interval[0:pi/2-0.1]; + func y = tan(\value x r); +} +data point [outlier] +data [format=function] { + var x : interval[pi/2+0.1:pi]; + func y = tan(\value x r); +}; +\end{codeexample} + \end{key} +\end{key} + + +\begin{key}{/tikz/data visualizers/visualize as smooth line=\meta{visualizer + name} (default line)} + A shorthand |visualize as line=|\meta{visualizer name} + followed \meta{visualizer name}|=smooth line|. +\end{key} + + +\begin{key}{/tikz/data visualization/visualizer options/straight line} + Causes the data points to be connected by straight lines. +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={straight line}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/straight cycle} + Causes the data points to be connected by a polygon. +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={straight cycle}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/polygon} + This is an alias for |straight cycle|. +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/smooth line} + Causes the data points to be connected by a line that is smoothed + at the joins: +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={smooth line}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/smooth cycle} + Causes the data points to be connected by a circular line that is + smoothed at the joins: +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={smooth cycle}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/gap line} + This key causes the data points to be connected by lines that ``do + not quite touch'' the data points. This is implemented by using the + |\pgfplothandlergaplineto|, see Section~\ref{section-plot-gapped}. +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={gap line}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/gap cycle} + Like |gapped line|, only with a cycle: +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={gap cycle}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/data visualization/visualizer options/no lines} + Suppresses the line. This option only makes sense when the |mark| + option is used. +\begin{codeexample}[] +\tikz [scale=.55] \datavisualization + [scientific axes=clean, all axes={ticks=few}, + visualize as smooth line=my data, my data={no lines, style={mark=x}}] +data [format=function] { + var t : interval [0:4] samples 5; + func x = cos(\value t r); + func y = sin(\value t r); +}; +\end{codeexample} +\end{key} + + + +\subsubsection{Visualizing Data Points Using Marks} + +\begin{key}{/tikz/data visualizers/visualize as scatter=\meta{visualizer + name} (default scatter)} + A shorthand |visualize as line=|\meta{visualizer name} + followed \meta{visualizer name}|=no lines| and setting + the |style| of the visualizer so that is will use |mark=x| (plus + some size adjustments) to draw marks at the data points. +\begin{codeexample}[width=7cm] +\tikz \datavisualization + [scientific axes=clean, + visualize as scatter] +data [format=function] { + var x : interval [0:pi] samples 10; + func y = sin(\value x r); +}; +\end{codeexample} +\end{key} + + +\subsection{Advanced: Creating New Visualizers} + +Creating a new visualizer is a two-stage process that does, +unfortunately, require in-depth knowledge of the data +visualization backend: +\begin{enumerate} +\item First, you need to create a new class using |\pgfooclass| whose + instances react to the signal |visualize datapoint signal|. This requires + detailed knowledge of the data visualization engine, see + Section~\ref{section-dv-backend}. +\item Second, you should provide keys on the \tikzname\ level for + creating the necessary objects. These keys invoke the key + |new visualizer| internally. +\end{enumerate} + +\begin{key}{/tikz/data visualization/new + visualizer=\marg{name}\marg{options}\marg{legend entry options}} + This key configures a new visualizer named \meta{name}. This entails + the following actions: + \begin{itemize} + \item The key |/tikz/data visualization/|\meta{name} is + created. As described earlier, this key can be used to pass + for instance |style| options to the visualizer. + \item The style key |/tikz/data visualization/visualizers/|\meta{name}|/styling| + is created and made empty. This is the key in which the |style| + key will store the options passed to the visualizer. + \item The style key |/tikz/data visualization/visualizers/|\meta{name}|/label in legend options| + is set to \meta{legend entry options}. These options are used to + configure how the visualizer should be rendered in a legend, see + Section~\ref{section-dv-legend-entries} for details. + \item The key |/data point/set/|\meta{name} is set to a + number that is increased for each visualizer in the current data + visualization. This number is important for style sheets, see + Section~\ref{section-dv-style-sheets}. + \item The key |/data point/|\meta{name}|/execute at begin| is set to + code that creates a |{scope}| that executes the following styles + as options: + \begin{enumerate} + \item The \meta{options} passed to the |new visualizer| key. + \item The |every visualizer| style. + \item The styling from the currently active style sheets, see + Section~\ref{section-dv-style-sheets}. + \item The styling stored in the |styling| key mentioned above. + \end{enumerate} + \item The key |/data point/|\meta{name}|/execute at end| is set to + code that will finish all paths that may have been created by the + visualizer and closes the scope. + \end{itemize} + + All of the above mean the following in practice: + \begin{itemize} + \item Inside a new |visualize as ...| key, you pass the name of + the to-be-created to |new visualizer| as the first parameter and + any special default styling setup of the visualizer as the second + parameter. + \item The new |visualize as ...| key should also create a visualizer + object using |new object|. + \item When this object finally is about to create the actual + visualization, it should surround the code by invoking the code + stored in the |execute at begin| and the |execute at end| keys of + the visualizer. + \end{itemize} + + Everything else is usually taken care of by the |new visualizer| key + automatically. +\end{key} + + +As an example, let us create a simple visualizer that creates a +circle whose radius is dictated by the |radius| attribute. To keep +things simple in this example, this attribute cannot be configured. + +First, we need the visualizer class. For this example I have boiled it +down to a minimum: + +\begin{codeexample}[code only] +\pgfooclass{circle visualizer} +{ + % Stores the name of the visualizer. This is needed for filtering and configuration + \attribute name; + + % The constructor. Just setup the attribute. + \method circle visualizer(#1) { \pgfooset{name}{#1} } + + % Connect to visualize signal. + \method default connects() { + \pgfoothis.get handle(\me) + \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal) + } + + % This method is invoked for each data point. It checks whether the data point belongs to the correct + % visualizer and, if so, calls the macro \dovisualization to do the actual visualization. + \method visualize() { + \pgfdvfilterpassedtrue + \pgfdvnamedvisualizerfilter + \ifpgfdvfilterpassed + \dovisualization + \fi + } +} +\end{codeexample} + +The |\dovisualization| method must now do the correct +visualization. + +\begin{codeexample}[code only] +\def\dovisualization{ + \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin} + \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}} + % \pgfusepath is done by |execute at end| + \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end} +} +\end{codeexample} + +Finally, we create a |visualize as| key: + +\begin{codeexample}[code only] +\tikzdatavisualizationset{ + visualize as circle/.style={ + new object={ + when=after survey, + store=/tikz/data visualization/visualizers/#1, + class=circle visualizer, + arg1=#1 + }, + new visualizer={#1}{% + color=visualizer color, % a color setup by the style sheet + every path/.style={fill,draw}, % fill and draw the circle by default, + }{}, % let's ignore legends in this example + /data point/set=#1 + }, + visualize as circle/.default=circle +} +\end{codeexample} + +Now, let's see how this works: + + +\pgfooclass{circle visualizer} +{ + % Stores the name of the visualizer. This is needed for filtering + % and configuration + \attribute name; + + % The constructor. Just setup the attribute. + \method circle visualizer(#1) { \pgfooset{name}{#1} } + + % Connect to visualize signal. + \method default connects() { + \pgfoothis.get handle(\me) + \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal) + } + + % This method is invoked for each data point. It checks whether the + % data point belongs to the correct visualizer and, if so, calls the + % macro \dovisualization to do the actual visualization. + \method visualize() { + \pgfdvfilterpassedtrue + \pgfdvnamedvisualizerfilter + \ifpgfdvfilterpassed + \dovisualization + \fi + } +} + +\def\dovisualization{ + \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin} + \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}} + % \pgfusepath is done by |execute at end| + \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end} +} + +\tikzdatavisualizationset{ + visualize as circle/.style={ + new object={ + when=after survey, + store=/tikz/data visualization/visualizers/#1, + class=circle visualizer, + arg1=#1 + }, + new visualizer={#1}{% + color=visualizer color, % a color setup by the style sheet + every path/.style={fill,draw}, % fill and draw the circle by default, + }{}, + /data point/set=#1 + }, + visualize as circle/.default=circle +} + + +\begin{codeexample}[width=7cm] +\tikz \datavisualization [ + scientific axes=clean, + visualize as circle/.list={a, b, c}, + style sheet=strong colors] +data [set=a] { + x, y, radius + 0, 0, 2pt + 1, 1, 3pt + 1, 2, 3pt + 2, 0, 1pt +} +data [set=b] { + x, y, radius + 0.5, 0.5, 5pt + 1, 1.5, 2pt + 1, 2.5, 3pt + 0, 2, 4pt +} +data [set=c] { + x, y, radius + 3, 2, 3pt + 2.5, 0.5, 4pt +}; +\end{codeexample} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithm-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithm-layer.tex new file mode 100644 index 00000000000..b02a61319cb --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithm-layer.tex @@ -0,0 +1,851 @@ +% Copyright 2010 by Renée Ahrens, Olof Frahm, Jens Kluttig, Matthias Schulz, Stephan Schuster +% Copyright 2011 by Till Tantau +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{The Algorithm Layer} + +\label{section-gd-algorithm-layer} + +\noindent{\emph{by Till Tantau}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\subsection{Overview} + +The present section is addressed at readers interested in implementing +new graph drawing algorithms for the graph drawing system. Obviously, +in order to do so, you need to have an algorithm in mind and also some +programming skills; but fortunately only in the Lua programming +language: Even though the graph drawing system was originally +developed as an extension of \tikzname, is has been restructured so +that the ``algorithm layer'' where you define algorithms is +scrupulously separated from \tikzname. In particular, an algorithm +declared and implemented on this layer can be used in with every ``display +layers,'' see Section~\ref{section-gd-display-layer}, without change. Nevertheless, in +the following we will use the \tikzname\ display layer and syntax in +our examples. + +Normally, new graph drawing algorithms can and must be implemented in +the Lua programming language, which is a small, easy-to-learn (and +quite beautiful) language integrated into current versions of +\TeX. However, as explained in Section~\ref{section-algorithms-in-c}, +you can also implement algorithms in C or C++ (and, possibly, in the +future also in other languages), but this comes at a great cost +concerning portability. In the present section, I assume that you are +only interested in writing an algorithm using Lua. + +In the following, after a small ``hello world'' example of graph +drawing and a discussion of technical details like +how to name files so that \TeX\ will find them, we have a look at the +main parts of the algorithm layer: + +\begin{itemize} +\item Section~\ref{section-gd-namespaces} gives and overview of the + available namespaces and also of naming conventions used in the + graph drawing system. +\item Section~\ref{section-gd-gd-scope} explores what graph + drawing scopes ``look like on the algorithm layer.'' As the graph + of a graph drawing scope is being parsed on the display layer, a lot + of information is gathered: The nodes and edges of the graph are + identified and the + object-oriented model is built, but other information is also + collected. For instance, a sequence of \emph{events} is created + during the parsing process. As another example, numerous kinds of + \emph{collections} may be identified by the parser. The parsed graph + together with the event sequence and the collections are all + gathered in a single table, called the \emph{scope table} of the + current graph drawing scope. Algorithms can access this table to + retrieve information that goes beyond the ``pure'' graph model. + + One entry in this table is of particular importance: The + \emph{syntactic digraph.} While most graph drawing + algorithms are not really interested in the ``details'' of how a + graph was specified, for some algorithms it makes a big difference + whether you write |a -> b| or |b <- a| in your specification of the + graph. These algorithms can access the ``fine details'' of how the + input graph was specified through the syntactic digraph; all other + algorithms can access their |digraph| or |ugraph| fields and do not + have to worry about the difference between |a -> b| and |b <- a|. +\item Section~\ref{section-gd-models} explains the object-oriented + model of graphs used throughout the graph drawing system. Graph + drawing algorithms do not get the ``raw'' specification used by the + user to specify a graph (like |{a -> {b,c}}| in the |graph| + syntax). Instead, what a graph drawing algorithm sees is ``just'' a + graph object that provides methods for accessing the vertices and + arcs. +\item Section~\ref{section-gd-transformations} explains how the + information in the graph drawing scope is processed. One might + expect that we simply run the algorithm selected by the user; + however, things are more involved in practice. When the layout of a + graph needs to be computed, only very few algorithms will actually + be able to compute positions for the nodes of \emph{every} + graph. For instance, most algorithms implicitly assume that the + input graph is connected; algorithms for computing layouts for trees + assume that the input is, well, a tree; and so on. For this reason, + graph drawing algorithms will not actually need the original input + graph as their input, but some \emph{transformed} version of + it. Indeed, \emph{all} graph drawing algorithms are treated as graph + transformations by the graph drawing engine. + + This section explains how transformations are chosen and which + transformations are applied by default. +\item Section~\ref{section-gd-interface-to-algorithms} documents the + interface-to-algorithm class. This interface encapsulates all that + an algorithm ``sees'' of the graph drawing system (apart from the + classes in |model| and |lib|). +\item Section~\ref{section-gd-examples} provides a number of complete + examples that show how graph drawing algorithms can, actually, be + implemented. +\item Section~\ref{section-gd-libs} documents the different + libraries functions that come with the graph drawing engine. For + instance, there are library functions for computing the (path) + distance of nodes in a graph; a parameter that is needed by some + algorithms. +\end{itemize} + + + +\subsection{Getting Started} + +In this section, a ``hello world'' example of a graph +drawing algorithm is given, followed by an overview of the +organization of the whole engine. + + +\subsubsection{The Hello World of Graph Drawing} + +Let us start our tour of the algorithm layer with a ``hello world'' +version of graph drawing: An algorithm that simply places all nodes of +a graph in a circle of a fixed radius. Naturally, this is not a +particularly impressive or intelligent graph drawing algorithm; but +neither is the classical ``hello world''$\dots$\ Here is a minimal +version of the needed code (this is not the typical way of formulating +the code, but it is the shortest; we will have a look at the more +standard and verbose way in a moment): + +\begin{codeexample}[code only, tikz syntax=false] +pgf.gd.interface.InterfaceToAlgorithms.declare { + key = "very simple demo layout", + algorithm = { + run = + function (self) + local alpha = (2 * math.pi) / #self.ugraph.vertices + for i,vertex in ipairs(self.ugraph.vertices) do + vertex.pos.x = math.cos(i * alpha) * 25 + vertex.pos.y = math.sin(i * alpha) * 25 + end + end + } +} +\end{codeexample} +\directlua{ +pgf.gd.interface.InterfaceToAlgorithms.declare { + key = "very simple demo layout", + algorithm = { + run = + function (self) + local alpha = (2 * math.pi) / \luaescapestring{#}self.ugraph.vertices + for i,vertex in ipairs(self.ugraph.vertices) do + vertex.pos.x = math.cos(i * alpha) * 25 + vertex.pos.y = math.sin(i * alpha) * 25 + end + end + } +} +} + +This code \emph {declares} a new algorithm (|very simple demo layout|) +and includes an implementation of the algorithm (through the |run| +field of the |algorithm| field). When the |run| method is called, the +|self| parameter will contain the to-be-drawn graph in its |ugraph| +field. It is now the job of the code to modify the positions of the +vertices in this graph (in the example, this is done by assigning +values to |vertex.pos.x| and |vertex.pos.y|). + +In order to actually \emph{use} the algorithm, the above code first +needs to be executed somehow. For \tikzname, one can just call +|\directlua| on it or put it in a file and then use |\directlua| plus +|require| (a better alternative) or you put it in a file like +|simpledemo.lua| and use |\usegdlibrary{simpledemo}| (undoubtedly the +``best'' way). For another display layer, like a graphical editor, the +code could also be executed through the use of |require|. + +Executing the code ``just'' declares the algorithm, this is what the +|declare| function does. Inside some internal tables, the algorithm +layer will store the fact that a |very simple demo layout| is now +available. The algorithm layer will also communicate with the display +layer through the binding layer to advertise this fact to the +``user.'' In the case of \tikzname, this means that the option key +|very simple demo layout| becomes available at this point and we can +use it like this: + +\begin{codeexample}[] +\tikz [very simple demo layout] + \graph { f -> c -> e -> a -> {b -> {c, d, f}, e -> b}}; +\end{codeexample} + +It turns out, that our little algorithm is already more powerful than +one might expect. Consider the following example: +\begin{codeexample}[] +\tikz [very simple demo layout, componentwise] + \graph { + 1 -> 2 ->[orient=right] 3 -> 1; + a -- b --[orient=45] c -- d -- a; + }; +\end{codeexample} + +Note that, in our algorithm, we ``just'' put all nodes on a circle +around the origin. Nevertheless, the graph gets decomposed into two +connected components, the components are rotated so that the edge from +node |2| to node |3| goes from left to right and the edge from |b| to +|c| goes up at an angle of $45^\circ$, and the components are placed +next to each other so that some spacing is achieved. + +The ``magic'' that achieves all this behind the scenes is called +``graph transformations.'' They will heavily pre- and postprocess the +input and output of graph drawing algorithms to achieve the above +results. + +Naturally, some algorithms may not wish their inputs and/or +outputs to be ``tampered'' with. An algorithm can easily configure +which transformations should be applied, by passing appropriate options +to |declare|. + + +\subsubsection{Declaring an Algorithm} + +Let us now have a look at how one would ``really'' implement the +example algorithm. First of all, we place our algorithm in a +separate file called, say, |ExampleLayout.lua|. This way, by putting +it in a separate file, all display layers can easily install the +algorithm at runtime by saying |require "ExampleLayout"|. + +Next, the |declare| function is needed quite often, so it makes sense +to create a short local name for it: + +\begin{codeexample}[code only, tikz syntax=false] +-- This is the file ExampleLayout.lua +local declare = require "pgf.gd.interface.InterfaceToAlgorithms".declare +\end{codeexample} + +The |declare| function is the work-horse of the algorithm layer. It +takes a table that contains at least a |key| field, which must be a +unique string, and some other fields that specify in more detail what +kind of key is declared. Once declared through a call of |declare|, +the ``key'' can be used on the display layer. + +For declaring an algorithm, the table passed to |declare| must contain +a field |algorithm|. This field, in turn, must (normally) be set to a +table that will become the algorithm class. In the above example, our +algorithm was so simple that we could place the whole definition of +the class inside the call of |declare|, but normally the class is +defined in more detail after the call to |declare|: + +\begin{codeexample}[code only, tikz syntax=false] +local ExampleClass = {} -- A local variable holding the class table + +declare { + key = "very simple demo layout", + algorithm = ExampleClass +} + +function ExampleClass:run () + local alpha = (2 * math.pi) / #self.ugraph.vertices + ... +end +\end{codeexample} + +The effect of the |declare| will be that the table stored in +|ExampleClass| is setup to form a class in the sense of +object-oriented programming. In particular, a static |new| function +is installed. + +Now, whenever the user uses the key |very simple demo layout| on a +graph, at some point the graph drawing engine will create a new +instance of the |ExampleClass| using |new| and will then call the +|run| method of this class. The class can have any number of other +methods, but |new| and |run| are the only ones directly called by the +graph drawing system. + + +\subsubsection{The Run Method} + +The |run| method of an algorithm classes lies at the heart of any +graph drawing algorithm. This method will be called whenever a graph +needs to be laid out. Upon this call, the |self| object will have +some important fields set: +\begin{itemize} +\item |ugraph| This stands for ``undirected graph'' and is the + ``undirected'' version of the to-be-laid out graph. In this graph, + whenever there is an arc between $u$ and $v$, there is also an arc + between $v$ and $u$. It is obtained by considering the syntactic + digraph and then ``forgetting'' about the actual direction of the + edges. + + When you have set certain |preconditions| in your algorithm class, + like |connected=true|, the |ugraph| will satisfy these + conditions. In particular, the |ugraph| typically will not be the + underlying undirected graph of the complete syntactic digraph, but + rather of some part of it. The use of (sub)layouts will also modify + the syntactic digraph is fancy ways. + + Refer to this graph whenever your algorithm is ``most comfortable'' + with an undirected graph, as is the case for instance for most + force-base algorithms. +\item |digraph| This stands for ``directed graph'' and is the + ``semantically directed'' version of the to-be-laid out + graph. Basically, when happens is that reverse edges in the + syntactic digraph (an edge like |b <- a|) will yield an |Arc| from + |a| to |b| in the |digraph| while they yield a |b| to |a| arc and + edge in the syntactic digraph. Also, undirected edges like |a -- b| + are replaced by directed edges in both directions between the + vertices. +\item |scope| The graph drawing scope. +\item |layout| The layout object for this graph. This is a collection + of kind |layout|. +\end{itemize} + + +\subsubsection{Loading Algorithms on Demand} + +In order to use the |very simple demo layout| on the display layer, +|declare| must have been called for this key. However, we just saw +that the |declare| function takes the actual class table as parameter +and, thus, whenever an algorithm is declared, it is also completely +loaded and compiled at this point. + +This is not always desirable. A user may wish to include a number of +libraries in order to declare a large number of potentially useful +algorithms, but will not actually use all of them. Indeed, at least +for large, complex algorithms, it is preferable that the algorithm's +code is loaded only when the algorithm is used for the first time. + +Such a ``loading of algorithms on demand'' is supported through the +option of setting the |algorithm| field in a |declare| to a +string. This string must now be the file name of a Lua file that +contains the code of the actual algorithm. When the key is actually +used for the first time, this file will be loaded. It must return a +table that will be plugged into the |algorithm| field; so subsequent +usages of the key will not load the file again. + +The net effect of all this is that you can place implementations of +algorithms in files separate from interface files that just contain +the |declare| commands for these algorithms. You will typically do +this only for rather large algorithms. + +For our example, the code would look like this: + +\begin{codeexample}[code only, tikz syntax=false] +-- File ExampleLayout.lua +local declare = require "pgf.gd.interface.InterfaceToAlgorithms".declare +declare { + key = "very simple demo layout", + algorithm = "ExampleLayoutImplementation" +} +\end{codeexample} + +\begin{codeexample}[code only, tikz syntax=false] +-- File ExampleLayoutImplementation.lua +local ExampleClass = {} +function ExampleClass:run () + local alpha = (2 * math.pi) / #self.ugraph.vertices + ... +end +return ExampleClass +\end{codeexample} + + +\subsubsection{Declaring Options} + +Let us now make our example algorithm a bit more ``configurable''. For +this, we use |declare| once more, but instead of the |algorithm| +field, we use a |type| field. This tells the display layer that the +key is not used to select an algorithm, but to configure ``something'' +about the graph or about nodes or edges. + +In our example, we may wish to configure the radius of the graph. So, +we introduce a |radius| key (actually, this key already exists, so we +would not need to declare it, but let us do so anyway for example +purposes): + +\begin{codeexample}[code only, tikz syntax=false] +declare { + key = "radius", + type = "length", + initial = "25pt" +} +\end{codeexample} + +This tells the display layer that there is now an option called +|radius|, that users set it to some ``length'', and that if it is not +set at all, then the 25pt should be used. + +To access what the user has specified for this key, an algorithm can +access the |options| field of a graph, vertex, or arc at the +key's name: + +\begin{codeexample}[code only, tikz syntax=false] + vertex.pos.x = math.cos(i * alpha) * vertex.options.radius + vertex.pos.y = math.sin(i * alpha) * vertex.options.radius +\end{codeexample} + + + +\subsubsection{Adding Inline Documentation} + +You should always document the keys you |declare|. For this, the +|declare| function allows you to add three fields to its argument +table: +\begin{itemize} +\item |summary| This should be a string that succinctly summarizes the + effect this key has. The idea is that this text will be shown as a + ``tooltip'' in a graphical editor or will be printed out by a + command line tool when a user requests help about the key. + You can profit from using Lua's |[[| and |]]| syntax for specifying + multi-line strings. + + Also, when the file containing the key is parsed for + this manual, this text will be shown. +\item |documentation| When present, this field contains a more + extensive documentation of the key. It will also be shown in this + manual, but typically not as a tool tip. +\item |examples| This should either be a single string or an array of + strings. Each string should be an example demonstrating how the key + is used in \tikzname. They will all be included in the manual, each + surrounded by a |codeexample| environment. +\end{itemize} + +Let us augment our |radius| key with some documentation. The three +dashes before the |declare| are only needed when the declaration is +part of this manual and they will trigger an inclusion of the key in +the manual. + +\begin{codeexample}[code only, tikz syntax=false] +--- +declare { + key = "radius", + type = "length", + initial = "25pt", + summary = [[ + Specifies the radius of a circle on which the nodes are placed when + the |very simple example layout| is used. Each vertex can have a + different radius. + ]], + examples = [[ + \tikz \graph [very simple example layout, radius=2cm] { + a -- b -- c -- d -- e; + }; + ]] +} +\end{codeexample} + +As a courtesy, all of the strings given in the documentation can start +and end with quotation marks, which will be removed. (This helps +syntax highlighting with editors that do not recognize the |[[| to |]]| +syntax.) Also, the indentation of the strings is removed (we compute +the minimum number of leading spaces on any line and remove this many +spaces from all lines). + + + +\subsubsection{Adding External Documentation} +\label{section-gd-documentation-in} + +As an alternative to inlining documentation, you can also store the +documentation of keys in a separate file that is loaded only when the +documentation is actually accessed. Since this happens only rarely +(for instance, not at all, when \tikzname\ is run, except for this +manual), this will save time and space. Also, for C code, it is +impractical to store multi-line documentation strings directly in the C +file. + +In order to store documentation externally, instead of the |summary|, +|documentation|, and |examples| keys, you provide the key +|documentation_in|. The |documentation_in| key must be set +to a string that is input using |require|. + +In detail, when someone tries to access the |summary|, |documentation|, or +|examples| field of a key and these keys are not (yet) defined, the +system checks whether the |documentation_in| key is set. If so, we +apply |require| to the string stored in this field. The file loaded in +this way can now setup the missing fields of the current key and, +typically, also of all other keys defined in the same file as the +current key. For this purpose, it is advisable to use the |pgf.gd.doc| +class: + +\includeluadocumentationof{pgf.gd.doc} + +As a longer example, consider the following declarations: + +\begin{codeexample}[code only, tikz syntax=false] +--- +declare { + key = "very simple demo layout", + algorithm = ExampleClass, + documentation_in = "documentation_file" +} + +--- +declare { + key = "radius", + type = "length", + initial = "25", + documentation_in = "documentation_file" +} +\end{codeexample} + +The file |documentation_file.lua| would look like this: + +\begin{codeexample}[code only, tikz syntax=false] +-- File documentation_file.lua +local key = require 'pgf.gd.doc'.key +local documentation = require 'pgf.gd.doc'.documentation +local summary = require 'pgf.gd.doc'.summary +local example = require 'pgf.gd.doc'.example + +key "very simple demo layout" +documentation "This layout is a very simple layout that, ..." + +key "radius" +summary "Specifies the radius of a circle on which the nodes are placed." +documentation +[[ +This key can be used together with |very simple example layout|. An +important feature ist that... +]] +example +[[ +\tikz \graph [very simple example layout, radius=2cm] +{ a -- b -- c -- d -- e; }; +]] +\end{codeexample} + + + + +\subsection{Namespaces and File Names} + +\label{section-gd-namespaces} + +\subsubsection{Namespaces} + +All parts of the graph drawing library reside in the Lua ``namespace'' +|pgf.gd|, which is itself a ``sub-namespace'' of |pgf|. For your own +algorithms, you are free to place them in whatever namespace you like; +only for the official distribution of \pgfname\ everything has been +put into the correct namespace. + +Let us now have a more detailed look at these namespaces. A namespace +is just a Lua table, and sub-namespaces are just subtables of +namespace tables. Following the Java convention, namespaces are in +lowercase letters. The following namespaces are part of the core of +the graph drawing engine: +\begin{itemize} +\item |pgf| This namespace is the main namespace of \pgfname. Other + parts of \pgfname\ and \tikzname\ that also employ Lua should put an + entry into this table. Since, currently, only the graph drawing + engine adheres to this rule, this namespace is declared inside the + graph drawing directory, but this will change. + + The |pgf| table is the \emph{only} entry into the global table of + Lua generated by the graph drawing engine (or, \pgfname, for that + matter). If you intend to extend the graph drawing engine, do not + even \emph{think} of polluting the global namespace. You will be + fined. +\item |pgf.gd| This namespace is the main namespace of the graph drawing + engine, including the object-oriented models of graphs and the + layout pipeline. Algorithms that are part of the + distribution are also inside this namespace, but if you write your + own algorithms you do not need place them inside this + namespace. (Indeed, you probably should not before they are made + part of the official distribution.) +\item |pgf.gd.interface| This namespace handles, on the one hand, the + communication between the algorithm layer and the binding layer and, + on the other hand, the communication between the display layer + (\tikzname) and the binding layer. +\item |pgf.gd.binding| So-called ``bindings'' between display layers + and the graph drawing system reside in this namespace. +\item |pgf.gd.lib| Numerous useful classes that ``make an algorithm's + your life easier'' are collected in this namespace. Examples are a + class for decomposing a graph into connected components or a class + for computing the ideal distance between two sibling nodes in a + tree, taking all sorts of rotations and separation parameters into + account. +\item |pgf.gd.model| This namespace contains all Lua classes that are + part of the object-oriented model of graphs employed + throughout the graph drawing engine. For readers familiar with the + model--view--controller pattern: This is the namespace containing + the model-part of this pattern. +\item |pgf.gd.control| This namespace contains the ``control logic'' + of the graph drawing system. It will transform graphs according to + rules, disassemble layouts and sublayouts and will call the + appropriate algorithms. For readers still familiar with the + model--view--controller pattern: This is the namespace containing + the control-part of this pattern. +\item |pgf.gd.trees| This namespace contains classes that are useful + for dealing with graphs that are trees. In particular, it contains a + class for computing a spanning tree of an arbitrary connected graph; + an operation that is an important preprocessing step for many + algorithms. + + In addition to providing ``utility functions for trees,'' the + namespace \emph{also} includes actual algorithms for computing graph + layouts like |pgf.gd.trees.ReingoldTilford1981|. It may seem to be a + bit of an ``impurity'' that a namespace mixes utility classes and + ``real'' algorithms, but experience has shown that it is better to + keep things together in this way. + + Concluding the analogy to the model--view--controller pattern, a + graph drawing algorithm is, in a loose sense, the ``view'' part of + the pattern. +\item |pgf.gd.layered| This namespace provides classes and functions + for ``layered'' layouts; the Sugiyama layout method being the most + well-known one. Again, the namespace contains both algorithms to be + used by a user and utility functions. +\item |pgf.gd.force| Collects force-based algorithms and, again, also + utility functions and classes. +\item |pgf.gd.examples| Contains some example algorithms. They are + \emph{not} intended to be used directly, rather they should serve as + inspirations for readers wishing to implement their own algorithms. +\end{itemize} + +There are further namespaces that also reside in the |pgf.gd| +namespace, these namespaces are used to organize different graph +drawing algorithms into categories. + +In Lua, similarly to Java, when a class |SomeClass| is part of, say, +the namespace |pgf.gd.example|, it is customary to put the class's +code in a file |SomeClass.lua| and then put this class in a directory +|example|, that is a subdirectory of a directory |gd|, which is in +turn a subdirectory of a directory |pgf|. When you write +\texttt{require "pgf.gd.example.SomeClass"} the so-called +\emph{loader} will turn this into a request for the file +\texttt{pgf/gd/example/SomeClass.lua} (for Unix systems). + + + +\subsubsection{Defining and Using Namespaces and Classes} + +There are a number of rules concerning the structure and naming of +namespaces as well as the naming of files. Let us start with the +rules for naming namespaces, classes, and functions. They follow the +``Java convention'': + +\begin{enumerate} +\item A namespace is a short lowercase |word|. +\item A function in a namespace is in |lowercase_with_underscores_between_words|. +\item A class name is in |CamelCaseWithAnUppercaseFirstLetter|. +\item A class method name is in |camelCaseWithALowercaseFirstLetter|. +\end{enumerate} + +From Lua's point of view, every namespace and every class is just a +table. However, since these tables will be loaded using Lua's +|require| function, each namespace and each class must be placed +inside a separate file (unless you modify the |package.loaded| table, +but, then, you know what you are doing anyway). Inside such a file, you +should first declare a local variable whose name is the name of the +namespace or class that you intend to define and then assign a +(possibly empty) table to this variable: +\begin{codeexample}[code only, tikz syntax=false] +-- File pgf.gd.example.SomeClass.lua: +local SomeClass = {} +\end{codeexample} +Next, you should add your class to the encompassing namespace. This is +achieved as follows: +\begin{codeexample}[code only, tikz syntax=false] +require("pgf.gd.example").SomeClass = SomeClass +\end{codeexample} +The reason this works is that the |require| will return the table that +is the namespace |pgf.gd.example|. So, inside this namespace, the +|SomeClass| field will be filled with the table stored in the local +variable of the same name -- which happens to be the table +representing the class. + +At the end of the file, you must write +\begin{codeexample}[code only, tikz syntax=false] +return SomeClass +\end{codeexample} +This ensures that the table that is defined in this file gets stored +by Lua in the right places. Note that you need and should not use +Lua's |module| command. The reason is that this command has +disappeared in the new version of Lua and that it is not really +needed. + +Users of your class can import and use your class by writing: +\begin{codeexample}[code only, tikz syntax=false] +... +local SomeClass = require "pgf.gd.examples.SomeClass" +... +\end{codeexample} + + + + +\subsection{The Graph Drawing Scope} + +\label{section-gd-gd-scope} + +\includeluadocumentationof{pgf.gd.interface.Scope} + + + +\subsection{The Model Classes} + +\label{section-gd-models} + +All that a graph drawing algorithm will ``see'' of the graph specified +by the user is a ``graph object.'' Such an object is an +object-oriented model of the user's graph that no longer encodes the +specific way in which the user specified the graph; it only encodes +which nodes and edges are present. For instance, the \tikzname\ graph +specification +\begin{codeexample}[code only] +graph { a -- {b, c} } +\end{codeexample} +\noindent and the graph specification +\begin{codeexample}[code only] +node (a) { a } +child { node (b) {b} } +child { node (c) {c} } +\end{codeexample} +will generate exactly the same graph object. + +\begin{luanamespace}{pgf.gd.}{model} + This namespace contains the classes modeling graphs, + nodes, and edges. Also, the |Coordinate| class is found here, since + coordinates are also part of the modeling. +\end{luanamespace} + + +\subsubsection{Directed Graphs (Digraphs)} + +Inside the graph drawing engine, the only model of a graph that is +available treats graphs as +\begin{enumerate} +\item directed (all edges have a designated head and a designated + tail) and +\item simple (there can be at most one edge between any pair of + nodes). +\end{enumerate} +These two properties may appear to be somewhat at odds with what users +can specify as graphs and with what some graph drawing algorithms +might expect as input. For instance, suppose a user writes +\begin{codeexample}[code only] +graph { a -- b --[red] c, b --[green, bend right] c } +\end{codeexample} +In this case, it seems that the input graph for a graph drawing +algorithm should actually be an \emph{undirected} graph in which there +are \emph{multiple} edges (namely $2$) between |b| and~|c|. +Nevertheless, the graph drawing engine will turn the user's input a +directed simple graph in ways described later. You do not need to +worry that information gets lost during this process: The +\emph{syntactic digraph,} which is available to graph drawing +algorithms on request, stores all the information about which edges +are present in the original input graph. + +The main reasons for only considering directed, simple graphs are speed +and simplicity: The implementation of these graphs has been optimized so +that all operations on these graphs have a guaranteed running time +that is small in practice. + +\includeluadocumentationof{pgf.gd.model.Digraph} + +\subsubsection{Vertices} + +\includeluadocumentationof{pgf.gd.model.Vertex} + +\subsubsection{Arcs} +\label{section-gd-arc-model} + +\includeluadocumentationof{pgf.gd.model.Arc} + +\subsubsection{Edges} + +\includeluadocumentationof{pgf.gd.model.Edge} + +\subsubsection{Collections} + +\includeluadocumentationof{pgf.gd.model.Collection} + +\subsubsection{Coordinates and Transformations} + +\includeluadocumentationof{pgf.gd.model.Coordinate} +\includeluadocumentationof{pgf.gd.lib.Transform} + +\subsubsection{Options and Data Storages for Vertices, Arcs, and Digraphs} + +\includeluadocumentationof{pgf.gd.lib.Storage} + +\subsubsection{Events} + + +\includeluadocumentationof{pgf.gd.lib.Event} + + + +\subsection{Graph Transformations} + +\label{section-gd-transformations} + +\includeluadocumentationof{pgf.gd.control.LayoutPipeline} + + + +\subsection{The Interface To Algorithms} + +\label{section-gd-interface-to-algorithms} + +\includeluadocumentationof{pgf.gd.interface.InterfaceToAlgorithms} + + + + + +\subsection{Examples of Implementations of Graph Drawing Algorithms} +\label{section-gd-examples} + +\includeluadocumentationof{pgf.gd.examples.library} +\includeluadocumentationof{pgf.gd.examples.SimpleDemo} +\includeluadocumentationof{pgf.gd.examples.SimpleEdgeDemo} +\includeluadocumentationof{pgf.gd.examples.SimpleHuffman} + + + + +\subsection{Support Libraries} + +\label{section-gd-libs} + +The present section lists a number of general-purpose libraries that +are used by different algorithms. + +\subsubsection{Basic Functions} + +\includeluadocumentationof{pgf} + +\includeluadocumentationof{pgf.gd.lib} + +\subsubsection{Lookup Tables} + +\includeluadocumentationof{pgf.gd.lib.LookupTable} + +\subsubsection{Computing Distances in Graphs} + +\emph{Still needs to be ported to digraph classes!} + +%\includeluadocumentationof{pgf.gd.lib.PathLengths} + +\subsubsection{Priority Queues} + +\includeluadocumentationof{pgf.gd.lib.PriorityQueue} + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithms-in-c.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithms-in-c.tex new file mode 100644 index 00000000000..09dfc3c4f09 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-algorithms-in-c.tex @@ -0,0 +1,898 @@ +% Copyright 2012 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + + +\section{Writing Graph Drawing Algorithms in C} +\label{section-algorithms-in-c} + +\noindent{\emph{by Till Tantau}} +\bigskip +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\ifgdccodebasic\else +In order to typeset this section, LuaTeX\ must be able to link C code +at runtime and the graph drawing C libraries must be installed on your +system. You will find the sources in the |c| subdirectory of the +installation, where you will also find example Makefiles. +\expandafter\endinput +\fi + +In the present section we have a look at how graph drawing +algorithms written in the C programming language (or in C++) can be +used in the graph drawing framework. + +\begin{quote} + \emph{Warning:} Graph drawing algorithms written in C can be + incredibly fast if you use the facilities of C + correctly. \emph{However,} C code is much less portable than Lua + code in the sense that it has to be compiled for the specific + platform used by the user and that it has to be linked dynamically + during a run of the \TeX\ program. All of this in possible (and + works, as demonstrated by the linking of the \textsc{ogdf} + framework), but it is \emph{much} harder to get right than writing + Lua code. + + Bottom line, \emph{you really should be using this method + only if it is really necessary (namely, when Lua code is simply not + fast enough).} +\end{quote} + +In the following, I first explain how the link between \TeX\ and C +code works, in general. Then, in the subsequent sections, we go over +the different kinds of programming languages and frameworks for which +there is direct support for such a link. + + +\subsection{How C and \TeX\ Communicate} + +In order to use C code for graph drawing algorithms during a run of +the \TeX\ program, there is no need to build a new version of +\TeX. Rather, it is possible that C code is linked into the \TeX\ +executable at runtime. This is made possible by the fact that Lua +(which part of Lua\TeX$\dots$) is able to link C libraries at runtime -- +provided a strict regime of rules is adhered to: + +\begin{enumerate} +\item When you say |require| in Lua, it will normally look for a + |.lua| file; but it will also try to find a |.so| file (a shared C + library) as a fallback. +\item If it finds such a shared library, Lua(\TeX) will try to link + this library dynamically at runtime. +\item Inside the library, there must be a function (called an entry + point) with a special name (it must start with |luaopen_| and it + must otherwise be the path and name of the library with slashes replaced by + underscores). +\item This function gets called by Lua, once. Its job is to setup the + library so that it can be used by Lua. Mainly, this means that + certain C functions get registered in such a way that Lua can call + them. +\item At this point, control returns to Lua and, now, certain + functions have become available on the Lua layer that, when called, + actually invoke the C code of our linked library. +\end{enumerate} + +For each of the above points, there are some bells and whistles: + +\begin{enumerate} +\item Lua\TeX\ looks at slightly inconvenient places for shared + libraries: By default, (currently, 2013) it looks in a |lib| + subdirectory of the directory containing the Lua\TeX\ + executable. The logic behind is that the shared libraries depend on + the specific architecture of the executable. Thus, unlike normal Lua + files, the library needs to be installed ``far away'' from the actual + package of which it is part. +\item Certain vesions of Lua\TeX\ have a broken handling of filenames + of libraries written in C. The TL2013 version of Lua\TeX, for + instance, crashes when the filename of a shared library does not + contain the complete path (while this works for normal + file). Hopefully, this, too, will be fixed in future versions. +\item On certain platforms, the support for dynamic linking against + Lua\TeX\ is broken since the symbol table of the Lua library has been + stripped away. Hopefully, this will be fixed soon; in the meantime, a + highly fragile workaround is to link in another copy of the Lua + library. +\item The entry point that is called by Lua requires a certain + signature (it takes a Lua state as its only parameter) and must + return the number of objects it returns on the Lua stack. +\item The registration process of C functions is somewhat tricky and + changes from Lua version to Lua version. +\item C functions that get called by Lua must follow all sorts of + tricky rules in order to communicate with Lua correctly. +\end{enumerate} + +Despite the above obstacles, one can use graph drawing algorithms +written in C inside Lua, in principle, as follows: One loads an +appropriately prepared and located C library using |require| and this +library uses commands like |declare| to register its own functions +into the graph drawing system so that when the |run| method is called, +a C functions gets called instead. + +Unfortunately, the above approach is extremely tedious and error-prone +and it is ``no fun'' to access Lua data structures (such as the +syntactic digraph) from C. For this reason, I have written some +libraries that encapsulate (as much as possible) of this communication +between C and Lua. Indeed, when you use these libraries, you can focus +entirely on the graph drawing issues and you will not even notice that +your code ``is talking to Lua.'' (Except for the name of the entry +point, which is fixed to start with |luaopen_| and it is impossible to +change this without disrupting a lot inside Lua's module system). + +There are libraries available for simplifying the communication +between the graph drawing system and graph drawing algorithms written +in + +\begin{itemize} +\item C, see Section~\ref{section-gd-c}, +\item C++, see Section~\ref{section-gd-c++}, +\item Open Graph Drawing Framework, see Section~\ref{section-gd-ogdf-interface}. +\end{itemize} + + + +\subsection{Writing Graph Drawing Algorithms in C} + +\label{section-gd-c} + +\subsubsection{The Hello World of Graph Drawing in C} + +As our first example, as always, the ``hello world'' of graph drawing +simply places nodes on a circle. For this, we implement a +function |fast_hello_world| in a file |SimpleDemoC.c|. It starts as +follows: + +\begin{codeexample}[code only, tikz syntax=false] +#include <pgf/gd/interface/c/InterfaceFromC.h> +#include <math.h> + +static void fast_hello_world (pgfgd_SyntacticDigraph* graph) { + ... +} +\end{codeexample} + +As we can see, we first include a special header file of a rather small +library that does all the hard work of translating between Lua and C +for us (|InterfaceFromC|). These header files reside in the |c| +subdirectory of the |pgf| package. Note that we do \emph{not} have to +include the headers of the Lua library; indeed, you do not need access +to the source of Lua to use the interface headers. As a side effect, +we will, however, have to write |struct lua_State| instead of the more common +|lua_State| once in our code, namely in the declaration of the entry +point; but that is the only downside. + +The library |InterfaceFromC| declares the type +|pgfgd_SyntacticDigraph|. In a moment, we will +see that we can setup a key |fast simple demo layout| such that when +this key is used on the display layer, the function +|fast_hello_world| gets called. When it is called, the |graph| +parameter will be a full representation of the to-be-laid-out +graph. We can access the fields of the graph and even directly modify +some of its fields (in particular, we can modify the |pos| fields of +the vertices). Here is the complete code of the algorithm: + +\begin{codeexample}[code only, tikz syntax=false] +static void fast_hello_world (pgfgd_SyntacticDigraph* graph) { + double angle = 6.28318530718 / graph->vertices.length; + double radius = pgfgd_tonumber(graph->options, "fast simple demo radius"); + + int i; + for (i = 0; i < graph->vertices.length; i++) { + pgfgd_Vertex* v = graph->vertices.array[i]; + v->pos.x = cos(angle*i) * radius; + v->pos.y = sin(angle*i) * radius; + } +} +\end{codeexample} + +That is all that is needed; the C library will take care of both +creating the |graph| object as all well as of deleting it and of +copying back the computed values of the |pos| fields of the vertices. + +Our next task is to setup the key |fast simple demo layout|. We can +(and must) also do this from C, using the following code: + +\begin{codeexample}[code only, tikz syntax=false] +int luaopen_pgf_gd_examples_c_SimpleDemoC (struct lua_State *state) { + + pgfgd_Declaration* d = pgfgd_new_key ("fast simple demo layout"); + pgfgd_key_summary (d, "The C version of the hello world of graph drawing"); + pgfgd_key_algorithm (d, fast_hello_world); + pgfgd_key_add_precondition (d, "connected"); + pgfgd_key_add_precondition (d, "tree"); + pgfgd_declare (state, d) + pgfgd_free_key (d); +\end{codeexample} + +The function |luaopen_pgf_gd_examples_c_SimpleDemoC| is the +function that will be called by Lua (we will come to that). More +important for us, at the moment, is the declaration of the key: We use +|pgfgd_new_key| to create a declaration record and then fill the +different fields using appropriate function calls. In particular, the +call |pgfgd_key_algorithm| allows us to link the key with a particular +C function. The |pgfgd_declare| will then pass the whole declaration +back to Lua, so the effect of the above is essentially the same as if +you had written in Lua: +\begin{codeexample}[code only, tikz syntax=false] +declare { + key = "fast simple demo layout", + summary = "The C version of the hello world of graph drawing", + preconditions = { + connected = true, + tree = true, + }, + algorithm = { + run = -- something magic we cannot express in Lua + } +} +\end{codeexample} + +In our algorithm, in addition to the above key, we also use the +|fast simple demo radius| key, which is a simple length key. This key, too, can be +declared on the C layer: + +\begin{codeexample}[code only, tikz syntax=false] + d = pgfgd_new_key ("fast simple demo radius"); + pgfgd_key_summary (d, "A radius value for the hello world of graph drawing"); + pgfgd_key_type (d, "length"); + pgfgd_key_initial (d, "1cm"); + pgfgd_declare (state, d); + pgfgd_free_key (d); + + return 0; +} +\end{codeexample} + +We simply add this code to the startup function above. + +Now it is time to compile and link the code. For this, you must, well, +compile it, link it against the library |InterfaceFromC|, and build a +shared library out of it. Also, you must place it somewhere where +Lua\TeX\ will find it. You will find a Makefile that should be able to +achieve all of this in the directory |pgf/c/graphdrawing/pgf/gd/examples/c|, +where you will also find the code of the above example. + +Now, all you need to do to use it is to write in Lua (after you have +loaded the |pgf.gd| library, of course), would normally be the call + +\begin{codeexample}[code only, tikz syntax=false] +require 'pgf.gd.examples.c.SimpleDemoC' +\end{codeexample} +or in \tikzname +\begin{codeexample}[code only] +\usegdlibrary {examples.c.SimpleDemoC} +\end{codeexample} + +This should cause Lua\TeX\ to find the shared library, load it, and then +call the function in that library with the lengthy name (the name is +always |luaopen_| followed by the path and filename with slashes +replaced by underscores). + +\emph{Remark:} Unfortunately, the above does not work with the \TeX +Live 2013 versions of Lua\TeX\ due to a bugs that causes the ``replace +dots by slashes'' to fail. For this reason, we currently need to +rename our sharded library file to +\begin{codeexample}[code only, tikz syntax=false] +pgf_gd_examples_c_SimpleDemoC.so +\end{codeexample} +and then say +\begin{codeexample}[code only, tikz syntax=false] +require 'pgf_gd_examples_c_SimpleDemoC' +\end{codeexample} +or in \tikzname +\begin{codeexample}[code only] +\usegdlibrary {pgf_gd_examples_c_SimpleDemoC} +\end{codeexample} + +In future versions of Lua\TeX, things should be ``back to normal'' in +this regard. Also, the bug only concerns shared libraries; you can +still create a normal Lua file with a nice name and place at a nice +location and the only contents of this file is then the above +|require| command. + +Anyway, once we have loaded the shared library we can say: + +\begin{codeexample}[] +\tikz \graph [fast simple demo layout, fast simple demo radius=1.25cm] +{ a -> b -> c -> d -> e -> a }; +\end{codeexample} + +\subsubsection{Documenting Algorithms Written in C} +\label{section-gd-documenting-c-algos} + +In our above example, we included a summary with the keys in the C +code. It would be even better if we added a longer documentation and +some examples that show how the key works; but this is a bit +impracticable in C since multi-line strings are hard to write down +in~C. The trick is to use the |documentation_in| field of a key: It +allows us to specify the name of a Lua file that should be loaded +(using |require|) to install the missing documentation fields. As +explained in Section~\ref{section-gd-documentation-in}, this Lua file +may make good use the |pgf.gd.doc| package. Note, also, that for keys +documented in this way the documentation can easily be included in +this manual through the use of the |\includedocumentationof| command. + +In our example, we would first add the following line twice in the +C code (once for each key), assuming that the documentation resides in +the file |pgf/gd/doc/examples/SimpleDemoC.lua|: + +\begin{codeexample}[code only, tikz syntax=false] + pgfgd_key_documentation_in (d, "pgf.gd.doc.examples.SimpleDemoC"); +\end{codeexample} + +Note that since the documentation is a normal Lua file, it will be +searched in the usual places Lua files are located (in the texmf +trees) and not, like the C shared library, in the special |lib| +subdirectory of the Lua\TeX\ binary. + +Here are typical contents of the documentation file: + +\begin{codeexample}[code only, tikz syntax=false] +-- File pgf/gd/doc/examples/SimpleDemoC.lua +local key = require 'pgf.gd.doc'.key +local documentation = require 'pgf.gd.doc'.documentation +local summary = require 'pgf.gd.doc'.summary +local example = require 'pgf.gd.doc'.example + +key "fast simple demo layout" +documentation +[[ +This layout is used... +]] +example +[[ +\tikz \graph [fast simple example layout] +{ a -- b -- c -- d -- e; }; +]] + +key "fast simple demo radius" +documentation +[[ +The radius parameter is used to ... +]] +example +[[ +\tikz \graph [fast simple demo layout, fast simple demo radius=1.25cm] +{ a -> b -> c -> d -> e -> a }; +]] +\end{codeexample} + + + +\subsubsection{The Interface From C} + +In the above example, we already saw some of the functions from the +library |InterfaceFromC| that translated from Lua to C for us. For a +complete list of all functions available, currently please see +|graphdrawing/c/pgf/gd/interface/c/InterfaceFromC.h| directly. + +Currently, the library provides C functions to directly access all +aspects of the syntactic digraph and also of the graphs computed by +the preprocessing of the layout pipeline. What is missing, however, is +access to the tree of (sub)layouts and to collections. Hopefully, these will +be added in the future. + + + + +\subsection{Writing Graph Drawing Algorithms in C++} + +\label{section-gd-c++} + +Built on top of the C interface presented in the previous section, +there is also a C++ interface available. It encapsulates as much of +the C functions as possible in C++ classes. Thus, this interface is +mostly there for convenience, it does not offer fundamentally new +functionality. + + +\subsubsection{The Hello World of Graph Drawing in C++} + +Let us have a look at how our beloved hello world of graph drawing +looks in C++. Although it is still possible to put graph drawing +algorithms inside functions, it is more natural in C++ to turn them +into methods of a class. Thus, we start the code of +|SimpleDemoCPlusPlus.c++| as follows: + +\begin{codeexample}[code only, tikz syntax=false] +#include <pgf/gd/interface/c/InterfaceFromC++.h> +#include <pgf/gd/interface/c/InterfaceFromC.h> + +#include <math.h> + +struct FastLayout : scripting::declarations, scripting::runner { + ... +} +\end{codeexample} + +As can be seen, we do not only include the interface from C++, but +also that from C (since, currently, not all functionality of the C +library is encapsulated in C++). + +The interesting part is the |struct FastLayout|, which will contain our +algorithm (you could just as well have used a |class| instead of a +|struct|). It is derived from two classes: First, from a +|declarations| class and, secondly, from a |runner| class. Both of +them, just like everything else from the interface, reside in the +namespace |scripting|. This name was chosen since the main purpose of +the interface is to provide ``scripting facilities'' to C code through +the use of Lua. + +We are currently interested in the class |runner|. This class has a +virtual function |run| that gets called when, on the Lua side, someone +has selected the algorithm represented by the class. Thus, we place +our algorithm in this method: + +\begin{codeexample}[code only, tikz syntax=false] +void run () { + pgfgd_SyntacticDigraph* graph = parameters->syntactic_digraph; + + double angle = 6.28318530718 / graph->vertices.length; + double radius = parameters->option<double>("fast simple demo radius c++"); + + for (int i = 0; i < graph->vertices.length; i++) { + pgfgd_Vertex* v = graph->vertices.array[i]; + v->pos.x = cos(angle*i) * radius; + v->pos.y = sin(angle*i) * radius; + } +} +\end{codeexample} + +The |run| method has access to the member variable |parameters|, which +contains all sorts of information concerning the to-be-drawn graph. In +particular, the |syntactic_digraph| field gives us access to the +syntactic digraph structure that was already available in the +interface from plain~C. However, we can also see that a template +function like |option| allows us to access the graph's option table in +a simple way. + +As for C code, our next task is to setup a key that, when used on the +\tikzname\ layer, will run our algorithm. For this, we can use an +object derived from a |declarations|. In our example, the |FastLayout| +is both derived from a |runner| (since it contains an algorithm) and +also from |declarations| (since it also contains the code necessary for +declaring this algorithm). If you prefer, you can split this into two +classes. A |declarations| object must override the |declare| +method. This method gets a |script| object as input, which is the +``representation'' of Lua inside the C++ code: + +\begin{codeexample}[code only, tikz syntax=false] +void declare(scripting::script s) { + using namespace scripting; + + s.declare(key ("fast simple demo layout c++") + .summary ("The C++ version of the hello world of graph drawing") + .precondition ("connected") + .precondition ("tree") + .algorithm (this)); + + s.declare(key ("fast simple demo radius c++") + .summary ("A radius value for the hello world of graph drawing") + .type ("length") + .initial ("1cm")); +} +\end{codeexample} + +For each key that we wish to declare, we call the script's |declare| +method once. This method takes a |key| object as input, which can be +configured through a sequence of calls to different member functions +(like |summary| or |algorithm|). Most of these member functions are +rather self-explaining; only |algorithm| is a bit trickier: It does +not take a function as input, but rather an object of type |runner| +and it will call the |run| method of this object whenever the +algorithm is run. + +Lastly, we also need to write the entry point: + +\begin{codeexample}[code only, tikz syntax=false] +extern "C" int luaopen_pgf_gd_examples_c_SimpleDemoCPlusPlus (struct lua_State *state) { + scripting::script s (state); + s.declare (new FastLayout); + return 0; +} +\end{codeexample} + +Note that it is the job of the interface classes to free the passed +|declarations| object. For this reason, you really need to call |new| +and cannot pass the address of a temporary object. + +As before, because of the bug in some Lua\TeX\ versions, to actually +load the library at runtime, we need to rename it to +\begin{codeexample}[code only, tikz syntax=false] +pgf_gd_examples_c_SimpleDemoCPlusPlus.so +\end{codeexample} +and then say +\begin{codeexample}[code only, tikz syntax=false] +require 'pgf_gd_examples_c_SimpleDemoCPlusPlus' +\end{codeexample} +or in \tikzname +\begin{codeexample}[code only] +\usegdlibrary {pgf_gd_examples_c_SimpleDemoCPlusPlus} +\end{codeexample} + +We can now use it: + +\begin{codeexample}[] +\tikz \graph [fast simple demo layout c++, fast simple demo radius c++=1.25cm] +{ a -> b -> c -> d -> e -> a }; +\end{codeexample} + + +\subsubsection{The Interface From C++} + +The header |graphdrawing/c/pgf/gd/interface/c/InterfaceFromC++.h| +contains, as the name suggest, the interface from C++. A complete +documentation is still missing, but let us go over the main ideas: + +\medskip +\noindent\textbf{Runners.} +Algorithms are represented by objects of type |runner|. An +algorithm will overwrite the |run| method, as we saw in the +example, and it should modify the |parameters| of the runner +object. + +In addition to the |run| method, there are also two more virtual +methods, called |bridge| and |unbrigde|. The first is called before +the |run| method is called and the second afterwards. The idea is that +another framework, such as \textsc{ogdf}, can implement a new class +|ogdf_runner| that overrides these two methods in order to transform +the Lua/C representation of the input graph into an \textsc{ogdf} +representation prior to the |run| method being called. The |run| +method can then access additional member variables that store the +graph representations in \textsc{ogdf} form (or another form, +depending on the framework). The |unbridge| method allows the +framework to translate back. + +Although a |runner| object must be created for every algorithm, an +algorithm can also reside in a function. The class |function_runner| +is a simple wrapper that turns a function into such an object. + + +\medskip +\noindent\textbf{Keys.} +A key object is a temporary object that is passed to the |declare| +method of a script. It represents the table that is passed to the Lua +function |declare|. In order to make setting its field easy, for each +field name there is a corresponding function (like |summary|) that +takes the string that should be set to this field and returns the key +object once more, so that we can chain calls. + +The |algorithm| method gets a runner object as parameter and will +store a pointer to this object inside Lua. Each time the algorithm is +used, this object will be used to ``run'' the algorithm, that is, the +methods |prepare|, |bridge|, |run|, and |unbridge| will be called in +that order. Since the object is reused each time, only one object is +needed; but this object may not be freed prematurely. Indeed, you will +normally create the object using |new| once and will then never delete +it. + +A typical idiom you may find in the code is +\begin{codeexample}[code only, tikz syntax=false] +s.declare (key (...) + .algorithm(this) + ...); +\end{codeexample} +This code is seen inside the |declare| method of objects that are both +declarations and runners. They register ``themselves'' via the above +code. Note, however, that this requires that the |this| pointer is not +a temporary object. (The typing rules of C++ make it hard for this +situation to happen, but it can be achieved.) + + +\medskip +\noindent\textbf{Reading options.} +Once options have been declared, your C++ algorithms will wish to read +them back. For this, the |parameters| field of a runner object +provides a number of templated methods: +\begin{itemize} +\item The |option_is_set| method returns |true| if the passed option + has been set \emph{and} can be cast to the type of the template. So, + |option_is_set<double>("node distance")| will return true if the + |node distance| key has been set for the graph as a whole + (currently, there is no way to read the options of a vertex or an + edge from C++, use the C methods instead). +\item The |option| function comes in two flavours: First, it takes a + single option name and just returns the option's value. If, however, + the option has not been set or has another type, some sort of null + value is returned. So, |option<double>("node distance")| will return + the configured node distance as a double. When an option has an + initial value, this call will always return a sensible value. + + The second flavour of |option| allows you to pass a reference to an + object in which the option's value should be stored and the function + will return true if the option is set (and, thus, something was + written into the reference). This is the ``safest'' way to access + an option: +\begin{codeexample}[code only, tikz syntax=false] +double dist; +if (parameters->option ("node distance", dist)) + ... +\end{codeexample} + + Caution must be taken for |char*| options: The returned string must + be explicitly freed; it will be a copy of the string stored in the + Lua table. +\item + The |configure_option| method is used to set a member of an object + based on the value of a certain option. For this, you must pass a + pointer to a member function that sets the member. Here is an + example: +\begin{codeexample}[code only, tikz syntax=false] +class MyClass { +public: + void setMyDistance (double distance); +... +}; +... + +MyClass m; +parameters->configure_option("node distance", &MyClass::setMyDistance, m); +\end{codeexample} + If the option has not been set or does not have the correct type, + the member function is not called. +\end{itemize} + + +\medskip +\noindent\textbf{Factories and modules.} +A Lua key is normally either a Boolean, a double, or a +string. However, in C++, we may also sometimes wish Lua users to +configure which C function is used to achieve something. One could do +this using strings or numbers and then use search algorithms or a long +|switch|, but this would neither be flexible nor elegant. + +Instead, it is possible to store \emph{factories} in Lua keys. A +factory is a class derived from |factory| that implements the virtual +function |make|. This function will return a new object of a template +type. You can store such a factory in a key. + +The |make| method of a parameters object allows you to invoke the +factory stored in a key. (If no factory is stored in it, |null| is +returned). + +The |configure_module| method is akin to |configure_option|, only +the result of applying the factory is passed to the member function of +the class. + + + +\medskip +\noindent\textbf{Scripts.} +A ``script'' is the abstraction of the communication between Lua and +C++. From C++'s point of view, the script object offers different +|declare| methods that allow us to ``make objects and function +scriptable'' in the sense that they can then be called and configured +from Lua. The script must be initialized with a Lua state and will be +bound to that state (basically, the script only stores this single +pointer). + +When you call |declare|, you either pass a single key object (which is +then declared on the Lua layer) or you pass a |declarations| object, +whose virtual |declare| method is then called. The |declarations| +objects are used to bundle several declarations into a single one. + + + +\subsection{Writing Graph Drawing Algorithms Using OGDF} + +\label{section-gd-ogdf-interface} + +Built on top of the C++ interface, a small interface allows you to +easily link algorithms written for the \textsc{ogdf} (Open Graph +Drawing Framework) with graph drawing in Lua. + + +\subsubsection{The Hello World of Graph Drawing in OGDF -- From Scratch} + +We start with some startup code: + +\begin{codeexample}[code only, tikz syntax=false] +#include <pgf/gd/ogdf/c/InterfaceFromOGDF.h> +#include <math.h> + +using namespace ogdf; +using namespace scripting; +\end{codeexample} + +Note that the interface from \textsc{ogdf} resides in the |ogdf| +folder, not in the |interface| folder. + +Like in the plain C++ interface, we must now subclass the |runner| +class and the |declarations| class. Also like the plain C++ interface, +we can use multiple inheritance. The difference lies in the fact that +we do not directly subclass form |runner|, but rather from +|ogdf_runner|. This class implements the complicated ``bridging'' or +``translation'' process between the world of |InterfaceFromC++| and +\textsc{ogdf}: + +\begin{codeexample}[code only, tikz syntax=false] +struct FastLayoutOGDF : declarations, ogdf_runner { + + void run () { + double angle = 6.28318530718 / graph.numberOfNodes(); + double radius = parameters->option<double>("my radius ogdf"); + + int i = 0; + for (node v = graph.firstNode(); v; v=v->succ(), i++) { + graph_attributes.x(v) = cos(angle*i) * radius; + graph_attributes.y(v) = sin(angle*i) * radius; + } + } +\end{codeexample} + +As can be seen, in a subclass of |ogdf_runner|, the |run| method will +have access to a member called |graph| and to another member called +|graph_attributes|. These will have been setup with the graph from the +Lua layer and, after the algorithm has run, the information stored in +the |x| and |y| fields of the graph attributes and also the bend +information of the edges will be written back automatically. + +Next, we need to declare the algorithm. This is done as in the plain +C++ interface: + +\begin{codeexample}[code only, tikz syntax=false] + void declare(script s) { + using namespace scripting; + + s.declare(key ("fast simple demo layout ogdf") + .summary ("The OGDF version of the hello world of graph drawing") + .precondition ("connected") + .algorithm (this)); + + s.declare(key ("my radius ogdf") + .summary ("A radius value for the hello world of graph drawing") + .type ("length") + .initial ("1cm")); + } +}; +\end{codeexample} + +Finally, we need the entry point, which is also ``as usual'': + +\begin{codeexample}[code only, tikz syntax=false] +extern "C" int luaopen_pgf_gd_examples_c_SimpleDemoOGDF (struct lua_State *state) { + script (state).declare (new FastLayoutOGDF); + return 0; +} +\end{codeexample} + +Yet again, we need to rename the resulting shared library and then say +|require| on it. We can now use it: + +\begin{codeexample}[] +\tikz \graph [fast simple demo layout ogdf, my radius ogdf=1cm] +{ a -> b -> c -> d -> e -> a }; +\end{codeexample} + + + +\subsubsection{The Hello World of Graph Drawing in OGDF -- Adapting Existing Classes} + +In the previous example we implemented a graph drawing algorithm using +\textsc{ogdf} for use with Lua ``from scratch.'' In particular, the +whole algorithm was contained in the |run| method of our main +class. In practice, however, graph drawing algorithms are typically +placed in classes that ``know nothing about scripting.'' For instance, +our hello world of graph drawing might actually be implemented like this: + +\begin{codeexample}[code only, tikz syntax=false] +// File HelloWorldLayout.h +#include <ogdf/module/LayoutModule.h> + +class HelloWorldLayout : puplic ogdf::LayoutModule { +public: + + virtual void call(ogdf::GraphAttributes &GA) + { + using namespace ogdf; + + const Graph &graph = GA.constGraph(); + double angle = 6.28318530718 / graph.numberOfNodes(); + int i = 0; + for (node v = graph.firstNode(); v; v=v->succ(), i++) { + GA.x(v) = cos(angle*i) * radius; + GA.y(v) = sin(angle*i) * radius; + } + } + + void setRadius (double r) { radius = r; } + +private: + + double radius; +}; +\end{codeexample} + +Now, what we actually want to do is to ``make this class +scriptable''. For this, we setup a new class whose |run| method will +produce a new |HelloWorldLayout|, configure it, and then run it. Here +is this run method: + + +\begin{codeexample}[code only, tikz syntax=false] +void run () +{ + HelloWorldLayout layout; + parameters->configure_option("HelloWorldLayout.radius", &HelloWorldLayout::setRadius, layout); + layout.call(graph_attributes); +} +\end{codeexample} + +Next, we need to write the declarations code. This is very similar to the +``from scratch'' version: + +\begin{codeexample}[code only, tikz syntax=false] +void declare(script s) { + using namespace scripting; + + s.declare(key ("HelloWorldLayout") + .summary ("The OGDF version of the hello world of graph drawing") + .precondition ("connected") + .algorithm (this)); + + s.declare(key ("HelloWorldLayout.radius") + .summary ("A radius value for the hello world of graph drawing") + .type ("length") + .alias ("radius")); +} +\end{codeexample} + +Two remarks are in order: First, it is customary to name the keys for +the display system the same way as the classes. Second, the different +configuration options of the algorithm are named with the class name +followed by the option name. This makes it clear who, exactly, is +being configured. However, these keys should then also get an |alias| +field set, which will cause an automatic forwarding of the key to +something more ``user friendly'' like just |radius|. + +It remains to put the above methods in a ``script'' file. It is this +file that, when compiled, must be linked at runtime against Lua\TeX. + +\begin{codeexample}[code only, tikz syntax=false] +// File HelloWorldLayout_script.c++ + +#include <pgf/gd/ogdf/c/InterfaceFromOGDF.h> +#include <HelloWorldLayout.h> + +using namespace ogdf; +using namespace scripting; + +struct HelloWorldLayout_script : declarations, ogdf_runner { + void run () { ... see above ... } + void declare (script s) { ... see above ... } +}; + +extern "C" int luaopen_my_path_HelloWorldLayout_script (struct lua_State *state) { + script (state).declare (new HelloWorldLayout_script); + return 0; +} +\end{codeexample} + + +\subsubsection{Documenting OGDF Algorithms} + +As explained in Section~\ref{section-gd-documenting-c-algos}, we can +add external documentation to algorithms written in C and, using the +|documentation_in| method of the |key| class, we can use the exact +same method to document \textsc{ogdf} algorithms. + +I strongly recommend making use of this feature since, currently, the +documentation of many \textsc{ogdf} classes is sketchy at best and +using \tikzname\ examples seems to be a good way of explaining the +effect of the different parameters algorithms offer. + + + +\subsubsection{The Interface From OGDF} + +The support for \textsc{ogdf} offered inside |InterfaceFromOGDF.h| is +just the class |ogdf_runner| we saw already +in the example. In addition, there is also a wrapper class +|ogdf_function_runner| that allows you to wrap an algorithm +implemented in a function that uses \textsc{ogdf}, but I expect this +to be the case only rarely. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex new file mode 100644 index 00000000000..422d7d8d0a2 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex @@ -0,0 +1,289 @@ +% Copyright 2010-2011 by Renée Ahrens +% Copyright 2010-2011 by Olof Frahm +% Copyright 2010-2011 by Jens Kluttig +% Copyright 2010-2011 by Matthias Schulz +% Copyright 2010-2011 by Stephan Schuster +% Copyright 2011 by Jannis Pohlmann +% Copyright 2011 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{The Binding Layer} + +\label{section-gd-binding-layer} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\subsection{Overview} + +This section explains how the \emph{binding} of the graph drawing +system to a particular display layer works. Let me stress +that all of this is important only for readers who +\begin{itemize} +\item either wish to write new display system (see + Section~\ref{section-gd-display-layer}) +\item or wish to know more about how the graph drawing system works on + the pure \pgfname\ layer (this is were the binding occurs). +\end{itemize} + +\emph{Bindings} are used to encapsulate the details of the +communication between the graph drawing system and a display system +(see Section~\ref{section-gd-display-layer} for an introduction to +display systems). + +Consider a display system that communicates with the graph drawing +system. At some point, the display system would like to run an +algorithm to lay out a graph. To achieve this, it will call different +functions from the class |InterfaceToDisplay| and the effect of this +is that a representation of the to-be-drawn graph is constructed +internally and that the appropriate algorithms are run. All of this is +in some sense independent of the actual display system, the class +|InterfaceToDisplay| offers the same standard interface to all display +systems. + +At some point, however, the graph drawing system may need to ``talk +back'' to the display system. For instance, once the graph has been +laid out, to trigger the actual rendering of the graph, the graph +drawing system must ``tell'' the display layer where the vertices +lie. For some display systems this is easy: if the display system +itself is written in Lua, it could just access the syntactic digraph +directly. However, for systems like \tikzname\ or systems written in +another language, the graph drawing system needs a set of functions +that it can call that will tell the display system what is going +on. This is were bindings come in. + +The class |Binding| is an interface that defines numerous methods that +will be called by the graph drawing system in different situations (see +the documentation below for details). For instance, there is a +function |renderVertex| that is called by the graph drawing system +whenever a vertex should be rendered by the display system. The class +is really just an interface in the sense of object-oriented +programming. For each display system you need to create a subclass of +|Binding| like |BindingToPGF| or |BindingToASCII| that implement the +methods declared by |Binding|. The number of methods that need to be +implemented depends on the display system. + +In the following, you will find the documentation of the |Binding| +class in Section~\ref{section-gd-binding-doc}. Following this, we +first have a quick look at how the |BindingToPGF| works and then go +over a simple example of a binding to a more or less imaginary +display system. This example should help readers interested in +implementing their own bindings. + + +\subsection{The Binding Class and the Interface Core} +\label{section-gd-binding-doc} + +\includeluadocumentationof{pgf.gd.bindings.Binding} +\includeluadocumentationof{pgf.gd.interface.InterfaceCore} + + +\subsection{The Binding To PGF} + +\includeluadocumentationof{pgf.gd.bindings.BindingToPGF} + + +\subsection{An Example Binding Class} + +\label{section-gd-binding-layer-example} + +In the present section a complete binding is presented to an imaginary +``\textsc{ascii} art display system'' is presented. The idea is that +this display system will depict graphs using just normal letters and +spaces so that, when the text is typeset in a monospace font, a +visualization of the graph results. For instance: + +\bigskip +\noindent +\begin{minipage}[t]{.5\textwidth} +\emph{Graph rendered by |BindingToPGF|:} +\medskip + +\tikz [anchor=base]\graph [layered layout,level distance=2.35cm,sibling +distance=1.2cm,edges={rounded corners,>=spaced stealth'}] { + Alice; + Bob; + Charly; + Dave; + Eve; + Fritz; + George; + Alice -> Bob; + Alice -> Charly; + Charly -> Dave; + Bob -> Dave; + Dave -> Eve; + Eve -> Fritz; + Fritz -> Alice; + George -> Eve; + George -> Fritz; + Alice -> George; +}; +\end{minipage}% +\begin{minipage}[t]{.49\textwidth} +\emph{Graph rendered by |BindingToASCII|:} + +\begin{verbatim} + Alice + ....... + .. . . . + ... . . . + ... .. . .. + .. . . . + Charly Bob . . + .. . . . + . . . . + . . . . + .. . . . + .. . . + Dave George . + .. . ... . + . . .. . + . . ... + .. . . ... + .. . .. + Eve . .. + .. . .. + . . . + . . . + .. . .. + ... + Fritz +\end{verbatim} +\end{minipage} +\bigskip + +The binding will reside in a file |BindingToASCII.lua|, whose contents +is detailed below, and which is used by calling the |bind| function of +|InterfaceToDisplay|, see its documentation for details. + +The binding's code starts with some initializations: + +\begin{codeexample}[code only] +-- File BindingToASCII.lua + +-- Imports +local lib = require "pgf.gd.lib" + +-- Subclass the Binding class: +local BindingToASCII = lib.class { base_class = require "pgf.gd.bindings.Binding" } +\end{codeexample} + +The interesting code is the code for +``rendering'' a graph. The graph drawing system will invoke the +binding's methods |renderStart| and |renderStop| to signal that the +graph drawing algorithms have finished and that the vertices and edges +can now be drawn. + +In our \textsc{ascii} renderer, we use a two-dimensional field holding +characters that severs as the ``drawing canvas''. At the beginning of +the rendering, we initialize it with blanks: + +\begin{codeexample}[code only] +local canvas + +function BindingToASCII:renderStart() + canvas = {} + -- Clear the canvas + for x=-30,30 do + canvas [x] = {} + for y=-30,30 do + canvas[x][y] = ' ' + end + end +end +\end{codeexample} + +In order to ``render'' a vertex, the graph drawing system will call +the |renderVertex| method. The binding of \tikzname\ does a lot of +complicated things in this method to retrieve the underlying node's +box from internal table and to somehow reinstall the box in \TeX's +output stream; for our \textsc{ascii} binding things are much simpler: +We simply put the vertex's name at the canvas position corresponding +to the vertex's |pos| coordinate. Note that this simple version of an +\textsc{ascii} renderer does not try to scale things; thus, array out +of bounds might occur here. + +\begin{codeexample}[code only] +function BindingToASCII:renderVertex(v) + canvas [math.floor(v.pos.x)][math.floor(v.pos.y)] = v.name +end +\end{codeexample} + +The rendering of edges is a more complicated process. Given two +vertices, we put dots at the canvas positions between them; provided +there are no vertices (so edges are behind the nodes). Here is the +essential part of the code (for the complete code, have a look at +|pgf/gd/examples/BindingToASCII.lua|): + + +\begin{codeexample}[code only] +function BindingToASCII:renderEdge(e) + local function connect (p,q) + -- Connect the points p and q + local x1, y1, x2, y2 = math.floor(p.x+0.5), math.floor(p.y+0.5), math.floor(q.x+0.5), math.floor(q.y+0.5) + ... + local delta_x = x2-x1 + local delta_y = y2-y1 + ... + local slope = delta_y/delta_x + for i=x1,x2 do + local x,y = i, math.floor(y1 + (i-x1)*slope + 0.5) + + if canvas[x][y] == " " then + canvas[x][y] = '.' + end + end + ... + end + + -- Iterate over all points on the path from tail to head: + local p = e.tail.pos + for i=1,#e.path do + connect(p, e.tail.pos + e.path[i]) + p = e.tail.pos + e.path[i] + end + connect(p, e.head.pos) +end +\end{codeexample} + + +The methods |renderVertex| and |renderEdge| will be called once for +each vertex and edge of the to-be-rendered graph. At the end, the +|renderStop| method is called. In our case, this method will output +the canvas using |print|. A slight complication arises when node names +are longer than just one character. In this case, the following code +``centers'' them on their coordinate and makes sure that they do not +get overwritten by the dots forming edges: + +\begin{codeexample}[code only] +function BindingToASCII:renderStop() + for y=10,-30,-1 do + local t = {} + for x=-30,30 do + local s = canvas[x][y] + for i=1,#s do + pos = x+30+i-math.floor(#s/2) + if not t[pos] or t[pos] == " " or t[pos] == "." then + t[pos] = string.sub(s,i,i) + end + end + end + print(table.concat(t)) + end +end +\end{codeexample} + +At the end, we need to return the created object: + +\begin{codeexample}[code only] +return BindingToASCII +\end{codeexample} + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-circular.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-circular.tex new file mode 100644 index 00000000000..85c27dd2c73 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-circular.tex @@ -0,0 +1,27 @@ +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Graph Drawing Algorithms: Circular Layouts} + +{\noindent {\emph{by Till Tantau}}} + +\label{section-last-graphdrawing-library-in-manual} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + + +\includeluadocumentationof{pgf.gd.circular.library} +\includeluadocumentationof{pgf.gd.circular.Tantau2012} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex new file mode 100644 index 00000000000..d5848375067 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex @@ -0,0 +1,292 @@ +% Copyright 2010-2011 by Renée Ahrens +% Copyright 2010-2011 by Olof Frahm +% Copyright 2010-2011 by Jens Kluttig +% Copyright 2010-2011 by Matthias Schulz +% Copyright 2010-2011 by Stephan Schuster +% Copyright 2011 by Jannis Pohlmann +% Copyright 2011 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{The Display Layer} + +{\noindent {\itshape{by Till Tantau}}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\label{section-gd-display-layer} + +\begin{quote} + \itshape You do not need to read this section in order to write new + graph drawing algorithms. It is of interest only to those wishing to + write programs that wish to ``use'' the graph drawing system in a + similar way that \tikzname\ does for laying out graphs that are + generated and then passed down from the program to the graph drawing + system. +\end{quote} + + +\subsection{Introduction: The Interplay of the Different Layers} + +The job of the graph drawing system is to run graph drawing algorithms +on graphs. Since graph drawing is useful in many different contexts, +not only in the context of \tikzname\ for which the present system was +originally developed, the graph drawing system was designed in such a +way that it can be used independently of \tikzname. To achieve this, +the \emph{display layer} provides an interface via which an arbitrary +program (\tikzname, a graph editor, a command line interface, etc.) +``talk'' to the graph drawing system. + +To better understand how this works, let us consider the following +setup: + +\begin{itemize} +\item A program would like to communicate with the graph + drawing system. It is written in Java and its job is to analyse social + networks. This software would like to use graph drawing to produce + drawings of some ``social graphs'' arising from its analyses. This + software will be called ``the display system'' in the following. +\item There are two algorithms that the display system would like to apply to + the graphs its produces. Let us call these algorithms ``A'' and + ``B''. However, the display system would also, ideally, wish to make it + possible that its user chooses other algorithms ``C'' that are not + necessarily part of its binary. +\item The display system has internally generated a ``social graph'' that it + would now like to draw. +\end{itemize} + +For this setup, the communication between the different layers of the +graph drawing system is as follows: + +\begin{enumerate} +\item The display system, being written in Java, must embed Lua to use the + graph drawing system. +\item The display system must initialize the graph drawing system. For this, + it must use |require| on the file |InterfaceToDisplay|, which, as + the name suggests, contains the interface between the display + system and the graph drawing system. + + It must also create a so-called ``binding'' between the + graph drawing system and the display layer. See + Section~\ref{section-gd-binding-layer} for more information on + bindings. +\item The display system now needs to load the declarations of the + algorithms A and B. For this, it just needs to apply |require| to + the files in which the algorithms reside. This will cause the + |declare| function to be called. This function is declared by + |InterfaceToAlgorithms| and allows files to declare that certain + algorithms and options are now available. + + Once this is done, the graph drawing system is fully initialized and + can be used. +\item Later on, the display system wishes to lay out a social graph. Note + that this is known as ``drawing the graph'' in the graph drawing + community, even though this only means the coordinates are computed + for the nodes of the graph. The actual ``rendering'' of the graph on + the display is the job of the display system (hence the name ``display + layer''). +\item To start the layout process, the display system calls the function + |beginGraphDrawingScope| of the class |InterfaceToDisplay|. +\item Next, for each vertex the function |createVertex| of the + interface class must be called and similarly for each edge. These + calls will cause an internal model of the graph to be created on the + algorithm layer. Options that are attached to nodes and edges are + also communicated to the graph drawing system through function calls + like |pushOption|. +\item When the graph is fully specified, the method + |runGraphDrawingAlgorithm| must be called, which is once more a + method of the interface class. This function will internally discern + which algorithms have been chosen (via options) and invoke the code + of the appropriate algorithms. +\item Next, the function |renderGraph| must be called. Its job is to + ``communicate back'' which coordinates have been computed. It will + use the binding for this communication, see + Section~\ref{section-gd-binding-layer}. +\item Finally, by calling |endGraphDrawingScope|, the resources needed + for the layout process for the social graph are freed once more. +\end{enumerate} + +A few points may be noteworthy: +\begin{itemize} +\item The whole communication between the display system and the graph + drawing system goes through the interface class via function + calls. This makes it easy to communicate with display system whose + internal model of graphs is quite different from the one used in Lua + (as is certainly the case for \TeX, but also the ``social graph'' + mentioned above need not even exist as a separate entity inside the + display system). + + \emph{The display system should only rely on the interface + class. All communication has to go through this class, the + display system may not access the internals of the internally + constructed graphs directly.} +\item New algorithms can be loaded at runtime, as long as the + |require| method is supported. +\item The display system can also use the interface class to query which + algorithms and which options are available in principle (and display + this information to the user). The display system can even get access the + documentation of the options at runtime since the documentation is + stored in fields of the declared options. +\end{itemize} + + +In the following, we first present a simple display system other than +\tikzname. The remainder of the section then encompasses a +documentation of the different functions of the class +|InterfaceToDisplay|. + + + +\subsection{An Example Display System} + +In the following, we present the code of a very simple display system +written in Lua (another such display system is \tikzname\ itself, but +the minimal system will allow us to focus on what is really +needed). You will also find it in |pgf.gd.examples.ASCIIDisplayer|. + +The job of this display system is to parse a string that encodes a graph +and to call the appropriate functions of |InterfaceToDisplay| to lay +out the graph. The actual calls for rendering the graph are part of +the binding, which is documented in +Section~\ref{section-gd-binding-layer-example}. + +The syntax of the to-be-laid-out graph is a reduced version of +\tikzname's |graph| syntax: The string must start with +|graph[|\meta{algorithm's name}|]{| and end with |}|. Between the +braces, all lines must either be of the form \meta{node name}|;| or +\meta{name 1}|->|\meta{name 2}|;| with optional spaces around the node +names. + +Let us now have a look at what we must do to use the graph drawing +system. First, we load some libraries and initialize the binding (see +Section~\ref{section-gd-binding-layer-example} for details on the +binding; we can ignore it for now). + +\begin{codeexample}[code only] +local InterfaceToDisplay = require "pgf.gd.interface.InterfaceToDisplay" +InterfaceToDisplay.bind(require "pgf.gd.examples.BindingToASCII") + +-- Load two libraries that define graph drawing algorithms. We can do this only *after* the binding +-- has been created since they call the declare function internally. +require "pgf.gd.layered.library" +require "pgf.gd.force.library" +\end{codeexample} + +Now comes some preparation code that starts a graph drawing scope and +sets up the algorithm to the string provided between the square +brackets: + +\begin{codeexample}[code only] +local algorithm = io.read():match("%s*graph%s*%[(.-)%]") + +InterfaceToDisplay.pushPhase(algorithm, "main", 1) +InterfaceToDisplay.pushOption("level distance", 6, 2) +InterfaceToDisplay.pushOption("sibling distance", 8, 3) +InterfaceToDisplay.beginGraphDrawingScope(3) +InterfaceToDisplay.pushLayout(4) +\end{codeexample} + +The numbers |1| to |4| are the positions on the options stack at which +the options should be placed. See the description of |pushOption| for +more details. + +We are now ready to create the vertices and edges via a very simple +parser: + +\begin{codeexample}[code only] +for line in io.lines() do + if line:match("}") then + break + elseif line:find("-") then + local n1, dir, n2 = string.match(line, "^%s*(.-)%s*(-.)%s*(.-)%s*;") + InterfaceToDisplay.createEdge(n1, n2, dir, 4) + else + local n1 = string.match(line, "^%s*(.-)%s*;") + InterfaceToDisplay.createVertex(n1, "rectangle", nil, 4) + end +end +\end{codeexample} + +The graph is now completely constructed inside the graph drawing +system. We can now invoke the algorithms: + +\begin{codeexample}[code only] +InterfaceToDisplay.runGraphDrawingAlgorithm() +InterfaceToDisplay.renderGraph() +InterfaceToDisplay.endGraphDrawingScope() +\end{codeexample} + +We can now run the resulting file using the Lua interpreter. If we +provide the input shown on the left, we get the output shown on the +right: + +\bigskip +\noindent +\begin{minipage}[t]{.5\textwidth} +\emph{Input given to ASCIIDisplayer:} + +\begin{verbatim} +graph [layered layout] { + Alice; + Bob; + Charly; + Dave; + Eve; + Fritz; + George; + Alice -> Bob; + Alice -> Charly; + Charly -> Dave; + Bob -> Dave; + Dave -> Eve; + Eve -> Fritz; + Fritz -> Alice; + George -> Eve; + George -> Fritz; + Alice -> George; +} +\end{verbatim} +\end{minipage}% +\begin{minipage}[t]{.49\textwidth} +\emph{Output produced by ASCIIDisplayer:} + +\begin{verbatim} + Alice + ....... + .. . . . + ... . . . + ... .. . .. + .. . . . + Charly Bob . . + .. . . . + . . . . + . . . . + .. . . . + .. . . + Dave George . + .. . ... . + . . .. . + . . ... + .. . . ... + .. . .. + Eve . .. + .. . .. + . . . + . . . + .. . .. + ... + Fritz +\end{verbatim} +\end{minipage} + + +\subsection{The Interface to Display Systems} + +\includeluadocumentationof{pgf.gd.interface.InterfaceToDisplay} + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-examples.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-examples.tex new file mode 100644 index 00000000000..bba5c540ade --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-examples.tex @@ -0,0 +1,14 @@ +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-force.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-force.tex new file mode 100644 index 00000000000..1925de99765 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-force.tex @@ -0,0 +1,43 @@ +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Graph Drawing Algorithms: Force-Based Methods} +\label{section-library-graphdrawing-force-based} + +{\emph{by Till Tantau and Jannis Pohlmann}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + + +\includeluadocumentationof{pgf.gd.force.library} + +\includeluadocumentationof{pgf.gd.force.Control} +\includeluadocumentationof{pgf.gd.force.ControlStart} +\includeluadocumentationof{pgf.gd.force.ControlIteration} +\includeluadocumentationof{pgf.gd.force.ControlSprings} +\includeluadocumentationof{pgf.gd.force.ControlElectric} +\includeluadocumentationof{pgf.gd.force.ControlCoarsening} + + + + +\includeluadocumentationof{pgf.gd.force.SpringLayouts} +\includeluadocumentationof{pgf.gd.force.SpringHu2006} + +\includeluadocumentationof{pgf.gd.force.SpringElectricalLayouts} +\includeluadocumentationof{pgf.gd.force.SpringElectricalHu2006} +\includeluadocumentationof{pgf.gd.force.SpringElectricalWalshaw2000} + + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-layered.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-layered.tex new file mode 100644 index 00000000000..f4c1704b827 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-layered.tex @@ -0,0 +1,28 @@ +% Copyright 2012 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Graph Drawing Algorithms: Layered Layouts} + +{\emph{by Till Tantau and Jannis Pohlmann}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\includeluadocumentationof{pgf.gd.layered.library} +\includeluadocumentationof{pgf.gd.layered.Sugiyama} +\includeluadocumentationof{pgf.gd.layered.cycle_removal} +\includeluadocumentationof{pgf.gd.layered.node_ranking} +\includeluadocumentationof{pgf.gd.layered.crossing_minimization} +\includeluadocumentationof{pgf.gd.layered.node_positioning} +\includeluadocumentationof{pgf.gd.layered.edge_routing} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-misc.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-misc.tex new file mode 100644 index 00000000000..8c88238eb39 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-misc.tex @@ -0,0 +1,30 @@ +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Graph Drawing Layouts: Miscellaneous} + + +\begin{tikzlibrary}{graphdrawing.misc} + Load this package when you wish to use the graph drawing algorithms + defined in this library. You should load the |graphdrawing| library first. +\end{tikzlibrary} + + +\begin{gdalgorithm}{simple demo layout}{Simple Demo} + The algorithm used in the examples of this manual for demonstrating + how a trivial graph drawing can be implemented. +\end{gdalgorithm} + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-ogdf.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-ogdf.tex new file mode 100644 index 00000000000..83868fa380c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-ogdf.tex @@ -0,0 +1,110 @@ +% Copyright 2012 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section[Graph Drawing Algorithms: The Open Graph Drawing Framework]{Graph Drawing Algorithms:\\ The Open Graph Drawing Framework} + +{\emph{by Till Tantau (who copied much of the text from + the source documentation of \textsc{ogdf})}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\ifgdccodeogdf +\else +In order to typeset this section, LuaTeX\ must be able to link C code +at runtime and the \textsc{ogdf} graph drawing C libraries must be +installed on your system. You will find the sources in the |c| +subdirectory of the installation, where you will also find example +Makefiles. +\expandafter\endinput +\fi + +\emph{Remark:} The integration of the \textsc{ogdf} library is still under +construction and the examples in this section are more a +proof-of-concept. So, use at your own risk. + +\includeluadocumentationof{pgf.gd.ogdf.library} + +\includeluadocumentationof{pgf.gd.doc.ogdf.layered} + +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SugiyamaLayout} + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.RankingModule} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.CoffmanGrahamRanking} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.LongestPathRanking} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.OptimalRanking} + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.TwoLayerCrossMin} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.BarycenterHeuristic} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.GreedyInsertHeuristic} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.MedianHeuristic} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SiftingHeuristic} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SplitHeuristic} + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.AcyclicSubgraphModule} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.DfsAcyclicSubgraph} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.GreedyCycleRemoval} + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.HierarchyLayoutModule} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.FastHierarchyLayout} +\includeluadocumentationof{pgf.gd.doc.ogdf.layered.FastSimpleHierarchyLayout} + + + + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderFR} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderFRExact} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderKK} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.FMMMLayout} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.MultilevelLayout} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.GEMLayout} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.FastMultipoleEmbedder} + + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.InitialPlacer} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.BarycenterPlacer} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.CirclePlacer} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.MedianPlacer} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.RandomPlacer} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.SolarPlacer} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.ZeroPlacer} + +\includeluadocumentationof{pgf.gd.doc.ogdf.module.MultilevelBuilder} + +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.EdgeCoverMerger} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.IndependentSetMerger} +\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.LocalBiconnectedMerger} +%\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.MatchingMerger} +% \includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.RandomMerger} +% \includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.SolarMerger} + + + +\includeluadocumentationof{pgf.gd.doc.ogdf.planarity} + +\includeluadocumentationof{pgf.gd.doc.ogdf.planarity.PlanarizationLayout} +%\includeluadocumentationof{pgf.gd.ogdf.planarity.LayoutPlanRepModule} + + +\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout} + +\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout.BalloonLayout} +\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout.CircularLayout} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-overview.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-overview.tex new file mode 100644 index 00000000000..cae05728476 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-overview.tex @@ -0,0 +1,317 @@ +% Copyright 2010 by Renée Ahrens, Olof Frahm, Jens Kluttig, Matthias Schulz, Stephan Schuster +% Copyright 2011 by Till Tantau +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + + +\section{Introduction to Algorithmic Graph Drawing} + +\emph{by Till Tantau} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + + +\subsection{What Is Algorithmic Graph Drawing?} + + + +\emph{Algorithmic graph drawing} (or just \emph{graph drawing} in the +following) is the process of computing algorithmically where the nodes of +a graph are positioned on a page so that the graph ``looks nice.'' The +idea is that you, as human (or you, as a machine, if you happen to be +a machine and happen to be reading this document) just specify which +nodes are present in a graph and which edges are +present. Additionally, you may add some ``hints'' like ``this node +should be near the center'' or ``this edge is pretty important.'' You +do \emph{not} specify where, exactly, the nodes and edges should +be. This is something you leave to a \emph{graph drawing + algorithm}. The algorithm gets your description of the graph as an +input and then decides where the nodes should go on the page. + +\begin{codeexample}[] +\tikz \graph [binary tree layout, level distance=5mm] { + 4 -- { + 3 -- 0 -- 1[second], + 10 -- { + 8 -- { + 6 -- {5,7}, + 9 + } } } +}; +\end{codeexample} + +\begin{codeexample}[] +\tikz \graph [spring layout, + edge quotes mid, + edges={nodes={font=\scriptsize, fill=white, sloped, inner sep=1pt}}] +{ + 1 ->["Das"] 2 ->["ist"] 3 ->["das"] 4 ->["Haus"] + 2 ->["vom" near start] 5 ->["Ni"] 4 ->["ko" near start] + 1 ->["laus", orient=right] 5; +}; +\end{codeexample} + +Naturally, graph drawing is a bit of a (black?) art. There is no +``perfect'' way of drawing a graph, rather, depending on the +circumstances there are several different ways of drawing the same +graph and often it will just depend on the aesthetic sense of the +reader which layout he or she would prefer. For this reason, there are +a huge number of graph drawing algorithms ``out there'' and there are +scientific conference devoted to such algorithms, where each +year dozens of new algorithms are proposed. + +Unlike the rest of \pgfname\ and \tikzname, which is implemented +purely in \TeX, the graph drawing algorithms are simply too complex to +be implemented directly in \TeX. Instead, the programming language Lua is used +by the graph drawing library -- a programming language that has been +integrated into recent versions of \TeX. This means that (a) as a user +of the graph drawing engine you run \TeX\ on your documents +in the usual way, no external programs are called since Lua is already +integrated into \TeX, and (b) it is pretty easy to implement new graph +drawing algorithms for \tikzname\ since Lua can be used and no \TeX\ +programming knowledge is needed. + + +\subsection{Using the Graph Drawing System} + +``Users'' of the graph drawing engine can invoke the graph +drawing algorithms often by just adding a single option to their +picture. Here is a typical example, where the |layered layout| option +tells \tikzname\ that the graph should be drawn (``should be layed +out'') using a so-called ``layered graph drawing algorithm'' (what +these are will be explained later): +\begin{codeexample}[] +\tikz [>=spaced stealth'] + \graph [layered layout, components go right top aligned, nodes=draw, edges=rounded corners] + { + first root -> {1 -> {2, 3, 7} -> {4, 5}, 6 }, 4 -- 5; + second root -> x -> {a -> {u,v}, b, c -> d -> {w,z} }; + third root -> child -> grandchild -> youngster -> third root; + }; +\end{codeexample} +Here is another example, where a different layout method is used +that is more appropriate for trees: +\begin{codeexample}[] +\tikz [grow'=up, binary tree layout, nodes={circle,draw}] + \node {1} + child { node {2} + child { node {3} } + child { node {4} + child { node {5} } + child { node {6} } + } + } + child { node {7} + child { node {8} + child[missing] + child { node {9} } + } + }; +\end{codeexample} +A final example, this time using a ``spring electrical layout'' +(whatever that might be\dots): +\begin{codeexample}[] +\tikz [spring electrical layout, node distance=1.3cm, + every edge/.style={ + decoration={coil, aspect=-.5, post length=1mm, + segment length=1mm, pre length=2mm}, + decorate, draw}] +{ + \foreach \i in {1,...,6} + \node (node \i) [fill=blue!50, text=white, circle] {\i}; + + \draw (node 1) edge (node 2) + (node 2) edge (node 3) + edge (node 4) + (node 3) edge (node 4) + edge (node 5) + edge (node 6); +} +\end{codeexample} +In all of the example, the positions of the nodes have only been +computed \emph{after} all nodes have been created and the edges have +been specified. For instance, in the last example, without the +option |spring electrical layout|, all of the nodes would have been +placed on top of each other. + + +\subsection{Extending the Graph Drawing System} + +The graph drawing engine is also intended to make is +(relatively) easy to implement new graph drawing algorithms. These +algorithms can either be implemented in the Lua programming +language (which is \emph{much} easier to program than \TeX\ +itself) or in C/C++ (but at a great cost regarding portability). The +Lua code for a graph drawing algorithm gets an +object-oriented model of the input graph as an input and must just +compute the desired new positions of the nodes. The complete +handling of passing options and configurations back-and-forth +between the different \tikzname\ and \pgfname\ layers is handled by +the graph drawing engine. + +As a caveat, the graph drawing engine comes with a library of +functions and methods that simplify the writing of new +graph drawing algorithms. As a typical example, when you implement a +graph drawing algorithm for trees, you typically require that your +input is a tree; but you can bet that users will feed all sorts of +graphs to your algorithm, including disjoint unions of cliques. The +graph drawing engine offers you to say that a precondition to running +your algorithm is that the graph is a |tree| and instead of the original graph your +algorithm will be provided with a spanning tree of the graph on +which it can work. There are numerous further automatic pre- and +postprocessing steps that include orienting, anchoring, and packing +of components, to name a few. + +The bottom line is that the graph drawing engine makes it easy +to try out new graph drawing algorithms for medium sized graphs (up +to a few hundred nodes) in Lua. For larger graphs, C/C++ code must be +used. + + + +\subsection{The Layers of the Graph Drawing System} + +\label{section-gd-layers} + +Even though the graph drawing system presented in the following +sections was developed as part of \pgfname, it can be used +independently of \pgfname\ and \tikzname: It was (re)designed so that +it can be used by arbitrary programs as long as they are able to run +Lua. To achieve this, the graph drawing system consists of three +layers: + +\begin{enumerate} +\item At the ``bottom'' we have the \emph{algorithmic layer}. This + layer, written in Lua, contains all graph drawing + algorithms. Interestingly, options must also be declared on this + layer, so an algorithm together with all options it uses can and + must be specified entirely on this layer. + If you intend to implement a new graph drawing algorithm, you will + only be interested in the functionality of this layer. + + Algorithm ``communicate'' with the graph drawing system through + a well-defined interface, encapsulated in the class + |InterfaceToAlgorithms|. +\item At the ``top'' we have the \emph{display layer}. This layer is + not actually part of the graph drawing system. Rather, it is a piece + of software that ``displays'' graphs and \tikzname\ is just one + example of such a software. Another example might be a graph + editor that uses the graph drawing system to lay out the graph it + displays. Yet another example might be a command line tool for + drawing graphs described in a file. Finally, you may also wish to + use the graph drawing system as a simple subroutine for rendering + graphs produced in a larger program. + + Since the different possible instantiations of the display layer are + quite heterogeneous, all display layers must communicate with the + graph drawing system through a special interface, encapsulated in + the class |InterfaceToDisplay|. + + The main job of this class is to provide a set of methods for + specifying that a graph has certain nodes and edges and that certain + options have been set for them. However, this interface also allows + you to query all options that have been declared by algorithms, + including their documentation. This + way, an editor or a command line tool can display a list of all + graph drawing algorithms and how they can be configured. +\item + The algorithm layer and the display layer are ``bound together'' + through the \emph{binding layer}. Most of the bookkeeping concerning + the to-be-drawn graphs is done by the graph drawing system + independently of which algorithm is used and also independently of + which display layer is used, but some things are still specific to + each display layer. For instance, some algorithms may create new + nodes and the algorithms may then need to know how large these nodes + will be. For this, the display layer must be ``queried'' during a + run of the algorithm -- and it is the job of the binding layer to + achieve this callback. + + As a rule, the binding layer implements the ``backward'' + communication from the graph drawing system back to the display + layer, while the display layer's interface class provides only + functions that are called from the display layer but which will not + ``talk back''. +\end{enumerate} + +All of the files concerned with graph drawing reside in the +|graphdrawing| subdirectory of |generic/pgf|. + +\subsection{Organisation of the Graph Drawing Documentation} + +The documentation of the graph drawing engine is structured as +follows: +\begin{enumerate} +\item Following this overview section, the next section documents + the graph drawing engine from ``the \tikzname\ user's point of + view''. No knowledge of Lua or algorithmic graph drawing is needed + for this section, everyone who intends to use algorithmic graph + drawing in \tikzname\ may be interested in reading it. +\item You will normally only use \tikzname's keys and + commands in order to use the graph drawing system, but, internally, + these keys call more basic \pgfname\ commands that do the ``hard + work'' of binding the world of \TeX\ boxes and macros to the + object-oriented world of Lua. Section~\ref{section-gd-pgf} explains + how this works and which commands are available for authors of + packages that directly need to use the graph drawing system inside + \pgfname, avoiding the overhead incurred by \tikzname. + + Most readers can safely skip this section. +\item The next sections detail which graph drawing algorithms are + currently implemented as part of the \tikzname\ distribution, see + Sections~\ref{section-first-graphdrawing-library-in-manual} + to~\ref{section-last-graphdrawing-library-in-manual}. +\item + Section~\ref{section-gd-algorithm-layer} is addressed at readers + who wish to implement their own graph drawing + algorithms. For this, \emph{no knowledge at all} of \TeX\ + programming is needed. The section explains the graph model used in + Lua, the available libraries, the graph drawing pipeline, and everything + else that is part of the Lua side of the engine. +\item + Section~\ref{section-gd-display-layer} details the + display layer of the graph drawing system. You should read this + section if you wish to implement a new display system (that is, a + non-\TeX-based program) that intends to use the graph drawing system. +\item + Section~\ref{section-gd-binding-layer} explains how binding layers + can be implemented. This section, too, is of interest only to + readers who wish to write new display systems. +\end{enumerate} + + + +\subsection{Acknowledgements} + +Graph drawing in \tikzname\ began as a student's project under my +supervision. Ren\'ee Ahrens, Olof-Joachim Frahm, Jens +Kluttig, Matthias Schulz, and Stephan Schuster wrote the first +prototype of a graph drawing system inside \tikzname\ that uses +Lua\TeX\ for the implementation of graph drawing algorithms. + +This first, early version was greatly extended on the algorithmic side +by Jannis Pohlmann who wrote his Diploma thesis on graph drawing under +my supervision. He implemented, in particular, the Sugiyama method +(|layered layout|) and force based algorithms. Also, he rewrote some +of the code of the prototype. + +At some point it became apparent that the first implementation had a +number of deficiencies, both concerning the structure, the interfaces, +and (in particular) the performance. Because of this, I rewrote +the code of the graph drawing system, both on the \TeX\ side +and on the Lua side in its current form. However, I would like to +stress that without the work of the people mentioned above graph +drawing in \tikzname\ would not exist. + +The documentation was written almost entirely by myself, though I did +copy some paragraphs from Jannis's Diploma thesis, which I can highly +recommend everyone to read. + +In the future, I hope that other people will contribute algorithms, +which will be available as libraries.
\ No newline at end of file diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-phylogenetics.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-phylogenetics.tex new file mode 100644 index 00000000000..28906ec17b5 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-phylogenetics.tex @@ -0,0 +1,82 @@ +% Copyright 2013 by Sarah Mäusle and Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Graph Drawing Layouts: Phylogenetic Trees} +\label{section-library-graphdrawing-phylogenetics} + +{\noindent {\emph{by Sarah M\"ausle and Till Tantau}}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\tikzset{/graph drawing/phylogenetic inner node/.style={ + /tikz/.cd, + draw, circle, inner sep=0pt, minimum size=5pt} +} +\tikzset{/graph drawing/phylogenetic edge/.style={ + /tikz/.cd, + thick, rounded corners,edge node={node[auto,font=\tiny, inner sep=2pt]{}}} +} + + +\includeluadocumentationof{pgf.gd.phylogenetics.library} +\includeluadocumentationof{pgf.gd.phylogenetics.PhylogeneticTree} + + +\subsection{Generating a Phylogenetic Tree} + +... + +When a phylogenetic tree is generated, new nodes and edges get +created. In order to give you a chance at styling them, the following +styles are executed: + +\begin{stylekey}{/graph drawing/phylogenetic inner node} + The style is added every newly created inner node. In this manual, + this key is set to: +\begin{codeexample}[code only] +\pgfgdset{phylogenetic inner node/.style={ + /tikz/.cd, draw, circle, inner sep=0pt, minimum size=5pt + } +} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/graph drawing/phylogenetic edge=\meta{length}} + The style is added every newly created phylogenetic edge. The + \meta{length} will be set to the computed evolutionary length of the + edge. In this manual, this key is set to: +\begin{codeexample}[code only] +\pgfgdset{phylogenetic edge/.style={ + /tikz/.cd, thick, rounded corners + } +} +\end{codeexample} +\end{stylekey} + + +\includeluadocumentationof{pgf.gd.phylogenetics.AuthorDefinedPhylogeny} +\includeluadocumentationof{pgf.gd.phylogenetics.SokalMichener1958} +\includeluadocumentationof{pgf.gd.phylogenetics.BalancedMinimumEvolution} +\includeluadocumentationof{pgf.gd.phylogenetics.BalancedNearestNeighbourInterchange} + + +\subsection{Laying out the Phylogram} + +\includeluadocumentationof{pgf.gd.phylogenetics.Maeusle2012} + + + +\endinput + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-trees.tex new file mode 100644 index 00000000000..edfbcdeba4e --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-trees.tex @@ -0,0 +1,34 @@ +% Copyright 2012 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Graph Drawing Layouts: Trees} +\label{section-first-graphdrawing-library-in-manual} +\label{section-library-graphdrawing-trees} + +{\noindent {\emph{by Till Tantau}}} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\includeluadocumentationof{pgf.gd.trees.library} + +\subsection{The Tree Layouts} +\includeluadocumentationof{pgf.gd.trees.ReingoldTilford1981} + +% Other subsections: +\includeluadocumentationof{pgf.gd.trees.ChildSpec} +\includeluadocumentationof{pgf.gd.trees.SpanningTreeComputation} + +\endinput + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex new file mode 100644 index 00000000000..095e3f771a4 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex @@ -0,0 +1,721 @@ +% Copyright 2010-2011 by Renée Ahrens +% Copyright 2010-2011 by Olof Frahm +% Copyright 2010-2011 by Jens Kluttig +% Copyright 2010-2011 by Matthias Schulz +% Copyright 2010-2011 by Stephan Schuster +% Copyright 2011 by Jannis Pohlmann +% Copyright 2011 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + + +\section{Using Graph Drawing in PGF} + +\label{section-gd-pgf} + +{\noindent {\emph{by Till Tantau}}} + +\begin{purepgflibrary}{graphdrawing} + This package provides the core support for graph drawing inside + \pgfname. It does so by providing \pgfname\ macros for controlling + the graph drawing system, but also implements the binding to the + graph drawing system (see Section~\ref{section-gd-binding-layer} for + details on bindings). +\end{purepgflibrary} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + +\subsection{Overview} + +Just like everywhere else in \pgfname, \tikzname\ is ``just a +convenient syntax'' in the context of graph drawing. The ``hard work'' +of binding the internal representations of nodes and edges with the graph +drawing system written in Lua is not done by \tikzname, but rather by +a set of macros that are part of the basic \pgfname\ layer. + +The documentation of the \pgfname\ part of the graph drawing system +that is presented in the following includes only those macros that +other \TeX\ packages could conceivably call in order to use the graph +drawing system without using \tikzname; for instance, for efficiency +reasons. (The internal callback functions defined in the graph drawing +library that are part of the binding between \pgfname\ and the graph +drawing system are not documented, should not be called, and may +change in the future.) + + + +\subsection{How Graph Drawing in PGF Works} + +The core idea behind graph drawing in \pgfname\ is that inside special +\emph{graph drawing scopes} whenever \pgfname\ creates a node, we +intercept this node creation and \emph{do not} immediately place the +node. Rather, we pass it down to Lua part of the graph drawing system +via calls to appropriate methods of the (Lua) class +|InterfaceToDisplay|. The effect will be that the nodes are ``tucked +away'' in some internal tables. For edges, we introduce a +special command called |\pgfgdedge| that tells the graph drawing +system that there is an edge between two tucked-away nodes. Then, +at the end of the graph drawing scope, a graph drawing algorithm +written in Lua starts to work on the graph by computing new positions +for the nodes. Once the algorithm has finished, the graph drawing +system starts sending back the nodes and edges to \pgfname\ via the +methods of the class |BindingToPGF|. These methods reinsert some code +into the \TeX\ output stream that finally places the nodes at +their final positions. Note that graph drawing algorithms are +perfectly oblivious to all of this; indeed, the graph drawing +algorithms can even be used independently of \TeX. + +Let us have a look at a simple example to see what happens when a +graph is specified: + +\begin{codeexample}[] +\tikz[tree layout] + \graph {root [as=Hello] -> World[fill=blue!20]}; +\end{codeexample} + +The key |tree layout| internally calls the key |request scope and layout|, +which in turn calls the macro |\pgfgdbeginscope|, which starts a graph +drawing scope inside the graph drawing system. Once this macro has been +called, until the next call of |\pgfgdendscope|, all nodes that are +created actually get passed down to the graph drawing engine. This is +implemented on the lowest layer, namely by directly intercepting +nodes freshly created using |\pgfnode|. In our example, this happens +in two places: For the |root| node and for the |World| node. The +|graph| library and \tikzname\ internally call the |\pgfnode| macro +for these two nodes (after a large number of internal syntax +translations, but the graph drawing system does not care about them). + +Note that the node boxes will have been fully created before they are +passed down to the graph drawing engine -- only their final position +is not yet fixed. It is not possible to modify the size of nodes +inside the graph drawing engine, but you can create new nodes in +certain situations. + +In contrast, the single edge of the graph that is created by the |->| +command is not fully created before it is passed down to the +graph drawing system. This would not really make sense since before the final +positions of the nodes are fixed, we cannot even begin to compute the +length of this edge, let alone where it should start or end. For this +reason, on the upper \tikzname\ layer, the normal edge creation that +would be caused by |->| via |new ->| is suppressed. Instead, the +command |\pgfgdedge| is called. Similarly, inside a graph drawing +scope, \tikzname\ will suppress both the |edge| and the +|edge from parent| command and cause |\pgfgdedge| to be called +instead. + +An overview of what happens is illustrated by the following call graph: + +\bigskip + +\begin{tikzpicture}[ + class name/.style={draw,minimum size=20pt, fill=blue!20}, + object node/.style={draw,minimum size=15pt, fill=yellow!20}, + p/.style={->,>=spaced stealth'}, + livespan/.style={very thick}, + xscale=0.8] + % class names above + \node (tikz) at (0,4) [class name] {\tikzname\ layer (\TeX)}; + \node (tex) at (6,4) [class name] {\pgfname\ layer (\TeX)}; + \node (interface) at (13,4) [class name] {Display layer (Lua)}; + % lines from the class names to the bottom of the picture + \draw[livespan] (tikz) -- (0,-6.5); + \draw[livespan] (tex) -- (6,-6.5); + \draw[livespan] (interface) -- (13,-6.5); + % first command: \graph{ -- generates new graph in lua interface + \node (tikz-begin-graph) at (0,3) [object node] {|\graph[... layout]{|}; %} + \node (tex-begin-graph) at (6,3) [object node] {|\pgfgdbeginscope|}; + \node (interface-new-graph) at (13,3) [object node] {|beginGraphDrawingScope(|...|)|}; + \draw [p] (tikz-begin-graph.east) -- (tex-begin-graph.west); + \draw [p] (tex-begin-graph.east) -- (interface-new-graph.west); + % second command: a -> b -- generates two nodes in lua + % and one edge + \node (tikz-node) at (0,2) [object node] {|a -> b;|}; + \node (tex-node) at (6,2) [object node, double copy shadow] {|\pgfnode|}; + \draw[p] (tikz-node.east) -- (tex-node.west); + + \node (interface-add-node) at (13,2) [object node, double copy shadow] {|createVertex(|...|)|}; + \draw[p] (tex-node.east) -- (interface-add-node.west); + + \node (tex-add-edge) at (6,1) [object node, double copy shadow] {|\pgfgdedge|}; + \node (interface-add-edge) at (13,1) [object node, double copy shadow] {|createEdge(|...|)|}; + \draw[p] (tikz-node.east) -- (1.5,2) -- (1.5,1) -- (tex-add-edge.west); + \draw[p] (tex-add-edge.east) -- (interface-add-edge.west); + + % scope ends -- cloes graph, layouts it and draws it + \node (tikz-end) at (0,0) [object node] {|};|}; + \node (tex-end) at (6,0) [object node] {|\pgfgdendscope|}; + \node (interface-draw-graph) at (13,0) [object node] {|runGraphDrawingAlgorithm()|}; + \node (interface-finish-graph) at (13,-2) [object node] {|endGraphDrawingScope()|}; + + \node (invoke-algorithm) at (15.5,-1) [object node] {invoke algorithm}; + \draw[p] (tikz-end.east) -- (tex-end.west); + \draw[p] (tex-end.east) -- (interface-draw-graph.west); + \draw[p] (interface-draw-graph.east) -| (invoke-algorithm.20); + \draw[p] (tex-end.east) -- (9.5,0) -- (9.5,-2) -- (interface-finish-graph.west); + + % begin shipout + \node (tex-begin-shipout) at (6,-3) [object node] {|\pgfgdcallbackbeginshipout|}; + + \node (tex-puttexbox) at (6,-4) [object node, double copy shadow] {|\pgfgdcallbackrendernode|}; + \node (tex-putedge) at (6,-5) [object node, double copy shadow] {|\pgfgddefaultedgecallback|}; + + \node (tex-end-shipout) at (6,-6) [object node] {|\pgfgdcallbackendshipout|}; + + \draw [p] (interface-finish-graph.-170) |- (tex-begin-shipout.east); + \draw [p] (interface-finish-graph.-170) |- (tex-puttexbox.east); + \draw [p] (interface-finish-graph.-170) |- (tex-putedge.east); + \draw [p] (interface-finish-graph.-170) |- (tex-end-shipout.east); + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-4) -- (sys-puttexbox.west); + + % put edge + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-5) -- (sys-put-edge.west); + % end shipout + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-6) -- (sys-end-shipout.west); +\end{tikzpicture} +\medskip + +The above diagram glosses over the fact that the display layer does +not actually call any of the macros of \TeX\ directly, but uses a so +called \emph{binding} (see the class |BindingToPGF|). However, this +will not be important for the present section since you cannot access +the binding directly. + + + +\subsubsection{Graph Drawing Scopes} + +\label{section-gd-scopes} + +When the graph drawing system is active, some pretty basic things +inside \pgfname\ change -- such as the fact that nodes are no longer +created in the normal manner. For this reason, the graph drawing +system must be switched on and of explicitly through opening and +closing a so called \emph{graph drawing scope}. These scopes can, in +principle, be nested, namely a graph contains a node that +contains some text that in turn contains a subpicture that contains a +drawing of a graph. However, this is \emph{not} the same as subgraphs +nodes and sublayouts, which are all part of the same graph drawing +scope. Normally, graph drawing scopes are not nested. + +Graph drawing scopes are created using the following commands: + +\begin{command}{\pgfgdbeginscope} + This macro starts a \TeX\ scope inside which the following things + happen: + \begin{enumerate} + \item The display layer method |beginGraphDrawingScope| is + called, which created a new graph drawing scope inside the graph + drawing system and places it on top of an internal stack. From now + on, all subsequent interface calls will refer to this scope until + |\pgfgdendscope| is called, which will pop the scope once more. + \item Inside the \TeX\ scope, nodes are not placed + immediately. Rather, |\pgfpositionnodelater|, see + Section~\ref{section-shapes-deferred-node-positioning}, is used to + call |InterfaceToDisplay.createVertex| for all nodes created + inside the scope. This will cause them to be put inside some internal + table. + \item Some additional \meta{code} is executed, which has been set + using the following command: + \begin{command}{\pgfgdaddspecificationhook\marg{code}} + This command adds the \meta{code} to the code that is executed + whenever a graph drawing scope starts. For instance, the + \tikzname\ library |graphdrawing| uses this macro to add some + \meta{code} that will redirect the |edge| and |edge from parent| + path commands to |\pgfgdedge|. + \end{command} + \item |\pgftransformreset| is called. + \item The following \TeX-if is set to true: + { + \let\ifpgfgdgraphdrawingscopeactive=\relax + \begin{textoken}{\ifpgfgdgraphdrawingscopeactive} + Will be true inside a graph drawing scope. + \end{textoken} + } + \end{enumerate} + The above has a number of consequences for what can happen inside a + graph drawing scope: + \begin{itemize} + \item Since nodes are not actually created before the end of the + scope, you cannot reference these nodes. Thus, you cannot write +\begin{codeexample}[code only] +\tikz [spring layout] { + \node (a) {a}; + \node (b) {b}; + \draw (a) -- (b); +} +\end{codeexample} + The problem is that we cannot connect |(a)| and |(b)| via a + straight line since these nodes do not exist at that point (they + are available only deeply inside the Lua). + \item In order to create edges between nodes inside a graph drawing + scope, you need to call the |\pgfgdedge| command, described below. + \end{itemize} + + Additionally, when \tikzname\ is used, the following things also + happen: + \begin{itemize} + \item If the |graphs| library has been loaded, the default + positioning mechanisms of this library are switched off, leaving + the positioning to the graph drawing engine. Also, when an edge is + created by the |graphs| library, this is signalled to the graph + drawing library. (To be more precise: The keys |new ->| and so on + are redefined so that they call |\pgfgdedge| instead of creating + an edge. + \item The |edge| path command is modified so that it also calls + |\pgfgdedge| instead of immediately creating any edges. + \item The |edge from parent| path command is modified so that is + also calls |\pgfgdedge|. + \item The keys |append after command| and |prefix after command| + keys are modified so that they are executed only via + |late options| when the node has ``reached its final parking + position''. + \end{itemize} + + Note that inside a graph drawing scope you first have to open a + (main) layout scope (using the |\pgfgdbeginlayout| command described + later on) before you can add nodes and edges to the scope. +\end{command} + + +\begin{command}{\pgfgdendscope} + This macro is used to end a graph drawing scope. It must be given on + the same \TeX\ grouping level as the corresponding + |\pgfgdbeginscope|. When the macro is called, it triggers a lot of + new calls: + \begin{enumerate} + \item The special treatment of newly created boxes is ended. Nodes + are once more created normally. + \item The effects of the \meta{code} that was inserted via the + specification hook command also ends (provided it had no global + effects). + \item We call |InterfaceToDisplay.runGraphDrawingAlgorithm|. This + will cause the algorithm(s) for the graph to be executed (since a + graph can have sublayouts, several algorithms may be run). See + Section~\ref{section-gd-layout-scopes} below. + \item Next, we call |InterfaceToDisplay.endGraphDrawingScope|. + This causes all nodes that were intercepted during the + graph drawing scope to be reinserted into the output stream at the + positions that were computed for them. Also, for each edge that + was requested via |\pgfgdedge|, the callback macro is + called (see below). + \end{enumerate} +\end{command} + + +Inside a graph drawing scope, nodes are +automatically passed down to the graph drawing engine, while for edges +a command has to be called explicitly: + +\begin{command}{\pgfgdedge\marg{first node}\marg{second + node}\marg{edge direction}\marg{edge options}\marg{edge nodes}} + This command is used to tell the graph drawing engine that there is + an edge between \meta{first node} and \meta{second node} in your + graph. The ``kind'' of connection is indicated by \meta{direction}, + which may be one of the following: + \begin{itemize} + \item + |->| indicates a directed edge (also known as an arc) from + \meta{first node} to \meta{second node}. + \item |--| indicates an undirected edge between \meta{first node} + and \meta{second node}, + \item |<-| indicates a directed edge from \meta{second node} to + \meta{first node}, but with the ``additional hint'' that this is a + ``backward'' edge. A graph drawing algorithm may or may not take + this hint into account. + \item |<->| indicates a bi-directed edge between \meta{first node} + and \meta{second node}. + \item |-!-| indicates that the edge from \meta{first node} to + \meta{second node} is ``missing''. + \end{itemize} + Note that in all cases, the syntatic digraph will contain an arc + from \meta{first node} to \meta{second node}, regardless of the + value of \meta{direction}. The \meta{direction} is ``just'' a + ``semantic annotation''. + + The parameters \meta{edge options} and \meta{edge nodes} are a bit + more tricky. When an edge between two vertices of a graph is created + via |\pgfgdedge|, nothing is actually done immediately. After all, + without knowing the final positions of the nodes \meta{first node} + and \meta{second node}, there is no way of creating the actual + drawing commands for the edge. Thus, the actual drawing of the edge + is done only when the graph drawing algorithm is done (namely in the + macro |\pgfgdedgecallback|, see later). + + Because of this ``delayed'' drawing of edges, options that influence + the edge must be retained until the moment when the edge is actually + drawn. Parameters \meta{edge options} and \meta{edge nodes} store such + options. + + Let us start with \meta{edge options}. This parameter should be set + to a list of key-value pairs like +\begin{codeexample}[code only] +/tikz/.cd, color=red, very thick, orient=down +\end{codeexample} + Some of these options may be of interest to the graph drawing + algorithm (like the last option) while others will + only be important during the drawing of edge (like the first + option). The options that are important for the graph drawing + algorithm must be pushed onto the graph drawing system's option + stack. + + The tricky part is that options that are of interest to the graph + drawing algorithm must be executed \emph{before} the algorithm starts, + but the options as a whole are usually only executed during the + drawing of the edges, which is \emph{after} the algorithm has finished. + To overcome this problem, the following happens: + + The options in \meta{edge options} are executed ``tentatively'' inside + |\pgfgdedge|. However, this execution is done in a ``heavily guarded + sandbox'' where all effects of the options (like changing the + color or the line width) do not propagate beyond the sandbox. Only + the changes of the graph drawing edge parameters leave the + sandbox. These parameters are then passed down to the graph drawing + system. + + Later, when the edge is drawn using |\pgfgdedgecallback|, the + options \meta{edge options} are available once more and then they + are executed normally. + + Note that when the options in \meta{edge options} are executed, no + path is preset. Thus, you typically need to start it with, say, + |/tikz/.cd|. Also note that the sandbox is not perfect and changing + global values will have an effect outside the sandbox. Indeed, + ``putting things in a sandbox'' just means that the options are + executed inside a \TeX\ scope inside an interrupted path inside a + \TeX\ box that is thrown away immediately. + + The text in \meta{edge nodes} is some ``auxilliary'' text that is + simply stored away and later directed to |\pgfgdedgecallback|. This + is used for instance by \tikzname\ to store its node labels. +\end{command} + + +\begin{command}{\pgfgdsetedgecallback\marg{macro}} + This command allows you to change the \meta{macro} that gets called + form inside the graph drawing system at the end of the creation of a + graph, when the nodes have been positioned. The \meta{macro} will be + called once for each edge with the following parameters: + \begin{quote} + \meta{macro}\marg{first node}\marg{second + node}\marg{direction}\marg{edge options}\marg{edge + nodes}\\ + \marg{algorithm-generated options}\marg{bend information} + \end{quote} + + The first five parameters are the original values that were passed + down to the |\pgfgdedge| command. + + The \meta{algorithm-generated options} have been ``computed by the + algorithm''. For instance, an algorithm might have determined, say, + flow capacities for edges and it might now wish to communicate this + information back to the upper layers. These options should be + executed with the path |/graph drawing|. + + The parameter \meta{bend information} contains + algorithmically-computed information concerning how the + edge should bend. This will be a text like + |(10pt,20pt)--(30pt,40pt)| in \tikzname-syntax and may include the + path commands |--|, |..| (followed by B\'ezier coordintes), and + |--cycle|. + + The default \meta{macro} simply draws a line between the nodes. When + the |graphdrawing| library of the \tikzname\ layer is loaded, a more + fancy \meta{macro} is used that takes all of the parameters into + account. +\end{command} + + + +\subsection{Layout Scopes} +\label{section-gd-layout-scopes} + +As described in Section~\ref{section-gd-sublayouts}, the graph drawing +engine does not always apply only a single algorithm. Rather, several +different algorithm may be applied to different parts of the +graph. How this happens, exactly, is goverened by a hierarchy of +layouts, which are setup using the commands |\pgfgdbeginlayout| and +|\pgfgdendlayout|. + + +\begin{command}{\pgfgdbeginlayout} + This command first starts a new \TeX\ scope and then informs the + display layer that a new (sub)layout should be started. For each + graph there may be a hierarchy of layouts, each of which contains a + certain number of vertices and edges. This hierarchy is created + through calls to this macros and the corresponding calls of + |\pgfgdendlayout|. For each graph drawing scope there has to be + exactly one main layout that encompasses all nodes and edges and + also all sublayouts. Thus, after a graph drawing scope has been + opened, a layout scope also needs to be opened almost immediately. + + For each layout created via this macro, a graph drawing algorithm + will be run later on on the subgraph of all nodes that make up the + layout. Which algorithm is run for the layout is dictated by which + layout key (one of the |... layout| keys) is ``in force'' when the + macro is called. Thus, using a layout key for selecting an algorithm + must always be done \emph{before} the layout is started. (However, + see the discussion of layout keys in the next subsection for more + details on what really happens.) + + A vertex can be part of several layouts, either because they are + nested or because they overlap (this happens when a node is later on + added to another layout by calling |\pgfgdsetlatenodeoption|). This + means that it is not immediately obvious how conflicts arising from + the different ways different algorithms ``would like to place + nodes'' should be resolved. The method for this resolving is + detailed in Section~\ref{section-gd-layout-resolve}. +\end{command} + +\begin{command}{\pgfgdendlayout} + This command ends the \TeX\ scope of the current layout. Once + closed, no nodes or edges can be added to a layout. +\end{command} + + +\begin{command}{\pgfgdsetlatenodeoption\marg{node name}} + This command can only be called when the node named \meta{node name} + has already been created inside the current graph drawing scope. The + effect of calling this macro will be that all options currently on + the graph drawing system's option stack will be added to the node's + option, possibly overwriting the original option + settings. Furthermore, the node will become part of all layouts + currently on the option stack. This means that you can use this + command to add a node to several layouts that are not included in + one another. +\end{command} + + + +\subsection{Layout Keys} + +\emph{Layout keys} are keys like |tree layout| +or |layered layout| that are used to select a specific graph drawing +algorithm. From the graph drawing system's point of view, these keys +``just'' select an algorithm and when several layout keys are used in +a row, the last one would ``win''; just as when you say |orient=90| directly +followed by |orient=0|, the result is that the |orient| key is set to +|0| because the last key ``wins.'' + +Unfortunately, if keys like |tree layout| were ``just'' to select an +algorithm, we would still need a key or some special syntax to +actually start a (sub)layout. In early versions of the system this was +exactly what people had to do and this was somewhat awkward. Because +of this problem, the behaviour of the layout keys in \pgfname\ (and +only there, other display layers need to implement their own +behaviour) is now a bit more involved. When you use a key like +|tree layout| (more precisely, any key that +was declared as an algorithm key on the algorithm layer of the graph +drawing system) in any scope in \pgfname, the following happens: +\begin{enumerate} +\item The graph drawing system is told that a specific algorithm has + been selected (the Reingold--Tilford-algorithm in this case; this + information was communicated to the graph drawing system during the + declaration of the algorithm). Being ``told'' about this means that + a special entry is pushed onto the current options stack of the + graph drawing system. +\item An internal ``request'' for a ``scope and a layout'' is + made. This has several effects: +\item + We first test whether we are already inside a layout scope. If not, + we use |\pgfgdbeginscope| to open a graph drawing scope. This + scope will be closed appropriately (see |\pgfgdsetrequestcallback| + for details). +\item + Next, a layout scope is opened using |\pgfgdbeginlayout|. It will + also be closed appropriately. +\end{enumerate} + +The net effect of the above is that the first use of a layout key in a +picture starts both a graph drawing scope and also a main layout, +while subsequent uses of layout keys inside a picture will only open +sublayouts. + +\begin{command}{\pgfgdsetrequestcallback\marg{macro}} + This command sets up \meta{macro} as the macro that is called + whenever a layout key ``requests'' that a layout and, possibly, a + graph drawing scope is opened. When \meta{macro} is called, it gets + two parameters, the \meta{begin code} and the \meta{end code}. In + addition to whatever setup the \meta{macro} would like to do, it + should execute the \meta{begin code} at the beginning of a \TeX\ + scope (the code will open graph drawing and layout scopes) and the + \meta{end code} at the end of the same \TeX\ scope. + + The need for this slightly strange macro arises from the fact that + in \tikzname\ we often write things like + |[spring layout,node sep=2cm]|. The point is that when the + |spring layout| key is executed, we do \emph{not} wish to open a + layout scope immediately. Rather, this should happen only after the + option |nodes sep=2cm| has been executed. For this reason, \tikzname\ + sets up a special \meta{macro} that ``delays'' the execution of the + \meta{begin code} until the end of the opening of the next scope. + + Because of this, in \tikzname\ layout keys can only be used as an + option when a \tikzname\ scope is started. Thus, you can + pass them to |\tikz|, to |{tikzpicture}|, to |\scoped|, to |{scope}|, + to |graph|, and to |{graph}|. For instance, the |tree layout| option can + be used in the following ways: +\begin{codeexample}[] +\tikz [tree layout] \graph {1 -> {b,c}}; +\tikz \graph [tree layout] {2 -> {b,c}}; +\tikz \path graph [tree layout] {3 -> {b,c}}; + +\begin{tikzpicture}[tree layout] + \graph {4 -> {b,c}}; +\end{tikzpicture} + +\begin{tikzpicture} + \scoped [tree layout] \graph {5 -> {b,c}}; + + \begin{scope}[tree layout, xshift=1.5cm] + \graph {6 -> {b,c}}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + You can \emph{not} use layout keys with a single + node or on a path. In particular, to typeset a tree given in the + |child| syntax somewhere inside a |{tikzpicture}|, you must prefix + it with the |\scoped| command: +\begin{codeexample}[] +\begin{tikzpicture} + \scoped [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; +\end{tikzpicture} +\end{codeexample} + Naturally, the above could have been written more succinctly as +\begin{codeexample}[] +\tikz [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; +\end{codeexample} + Or even more succinctly: +\begin{codeexample}[] +\tikz \graph [tree layout] { root -- {left child, right child} }; +\end{codeexample} +\end{command} + + + +\subsection{Parameters} +\label{section-gd-parameters} + +When a graph drawing algorithm starts working, a set of options, +called ``graph drawing parameters'' or just ``parameters'' can influence +the way the algorithm works. For instance, a graph drawing parameter +might be the average distance between vertices which the algorithm +should take into account. Another example might be the fact the +certain nodes are special nodes and that a certain edge should have +a large label. + +These graph drawing parameters are different from ``usual'' \pgfname\ +options: An alogrithmic parameter influences the way the algorithm +works, while usual options influence the way the result +looks like. For instance, the fact that a node is red is not a +graph drawing parameter, while the shape of a node might be an graph +drawing parameter. + +The possible graph parameters are declared by the algorithmic layer +through the |declare| method; you cannot declare parameters on the +\pgfname\ layer since this would not be compatible across different +display systems. + +Users use a graph parameter in the same way as a normal key. The +difference is that each time a key representing a graph drawing +parameter is used, a special function of the graph drawing system's +interface is called to ``push'' the parameter onto an internal option +stack (and elements are popped from this stack whenever the \TeX\ +scope closes in which the key was used). + +The net effect of all of this is that the graph drawing system keeps +track of a stack of option in parallel to \TeX. You cannot, however, +access the current values of graph drawing parameters from \TeX\ since +they are tucked away deep inside the graph drawing system. + + + +\subsection{Events} + +\emph{Events} are used to pass information from the parser about the +syntactic structure of a graph to graph drawing algorithms. Consider, +for instance, a graph that is actually a tree in which some node +``misses'' its first child. In this case, the information that the +child is missing is neither part of any node (because the node is +missing, after all) nor is it an option of the whole graph. However, +events are created by the parser the allow an algorithm to reconstruct +the fact that the child is missing. Naturally, graph drawing +algorithms may choose to ignore events and most will. + +Most of the creation and handling of events is done automatically. The +only reason you might wish to use the following commands is when you +write a ``parser extension'' together with a new graph drawing +algorithm. For instance, you might come up with new options that, when +used, trigger events. + +\begin{command}{\pgfgdevent\marg{kind}\marg{parameter}} + Calls |createEvent| of the graph drawing system's interface + class. This creates a new |Event| object on the Lua layer whose + |kind| field is set to \meta{kind} and the |parameters| field to + \meta{parameter}. You must be inside a graph drawing scope to use + this command. +\end{command} + +\begin{command}{\pgfgdbegineventgroup\marg{parameter}} + Starts an event group. This just means that an |Event| of kind + |begin| is created with the given \meta{parameter}. +\end{command} + +\begin{command}{\pgfgdendeventgroup} + Ends an event group. This is done by adding an event of kind |end| + without any parameters to the event string. +\end{command} + +\begin{command}{\pgfgdeventgroup\marg{parameters}} + Starts an event group just like |\pgfgdbegineventgroup|, but adds a + corresponding closing |end| event at the end of the current \TeX\ + group (using |\aftergroup|). +\end{command} + + +\subsection{Subgraph Nodes} + +\begin{command}{\pgfgdsubgraphnode\marg{name}\marg{node options}\marg{node text}} + A subgraph node is a node that ``surrounds'' the nodes of a + subgraph. The special property of a subgraph node opposed to a + normal node is that it is created only after the subgraph has been + laid out. However, the difference to a collection like |hyper| is + that the node is availble immediately as a normal node in the sense + that you can connect edges to it. + + What happens internally is that subgraph nodes get ``registered'' + immediately both on the \pgfname\ level and on the Lua level, but the + actual node is only created inside the layout pipeline using a + callback. The actual node creation happens when the innermost layout + in which the subgraph node is declared has finished. + + When you create a subgraph node using this macro, you also start a + collection (of an internal kind) that stores the subgraph. All + following nodes in the current \TeX\ scope will become part of this + collection. + + The \meta{name} is the node name by which you can refer to this node + in the following. The \meta{node options} are normal \pgfname\ + options (like |red| or |draw| or |circle|) that will influence the + appearance when it is created later on. The \meta{node text} is the + text that will be passed to |\pgfnode| upon creation of the node. + + See |InterfaceToDisplay.pushSubgraphVertex| for more details. +\end{command} + + + + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex new file mode 100644 index 00000000000..222898b66e7 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex @@ -0,0 +1,545 @@ +% Copyright 2012 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Using Graph Drawing in \tikzname} + +{\noindent {\emph{by Till Tantau}}} + +\begin{tikzlibrary}{graphdrawing} + This package provides capabilities for automatic graph drawing. It + requires that the document is typeset using Lua\TeX. This package + should work with Lua\TeX\ 0.54 or higher. +\end{tikzlibrary} + +\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi + + +\subsection{Choosing a Layout and a Library} + +The graph drawing engine is initialized when you load the library +|graphdrawing|. This library provides the basic framework for graph +drawing, including all options and keys described in the present +section. However, this library does \emph{not} load any actual +algorithms for drawing graphs. For this, you need to use the following +command, which is defined by the |graphdrawing| library: + +\begin{command}{\usegdlibrary\marg{list of libraries}} + This command is used to load the special graph drawing libraries + (the |gd| in the name of the command stands for ``graph + drawing''). The \meta{list of libraries} is a comma-separated list + of library written in the Lua programming language (which is why a + special command is needed). + + In detail, this command does the following. For each \meta{name} in + the \meta{list of libraries} we do: + \begin{enumerate} + \item Check whether Lua\TeX\ can call |require| on the library file + |pgf.gd.|\meta{name}|.library|. Lua\TeX's usual file search + mechanism will search the texmf-trees in the usual manner and the + dots in the file name get converted into directory slashes. + \item If the above failed, try to |require| the string + |pgf.gd.|\meta{name}. + \item If this fails, try to |require| the string + \meta{name}|.library|. + \item If this fails, try to |require| the string \meta{name}. If + this fails, print an error message. + \end{enumerate} + The net effect of the above is the following: Authors of graph + drawing algorithms can bundle together multiple algorithms in a + library by creating a |...xyz/library.lua| file that internally just + calls |require| for all files containing declarations. On the other + hand, if a graph drawing algorithm completely fits inside a single + file, it can also be read directly using |\usegdlibrary|. +\begin{codeexample}[code only] +\usetikzlibrary{graphdrawing} +\usegdlibrary{trees,force} +\end{codeexample} + + The different graph drawing libraries are documented in the following + Sections~\ref{section-first-graphdrawing-library-in-manual} to + \ref{section-last-graphdrawing-library-in-manual}. +\end{command} + +Note that in addition to the graph \emph{drawing} libraries, you may +also wish to load the normal \tikzname\ library |graphs|. It provides +the powerful |graph| path command with its easy-to-use syntax for +specifying graphs, but you can use the graph drawing engine +independently of the |graphs| library, for instance in conjunction +with the |child| or the |edge| syntax. Here is a typical setup: + +\begin{codeexample}[code only] +\usetikzlibrary{graphs, graphdrawing} +\usegdlibrary{trees, layered} +\end{codeexample} + +Having set things up, you must then specify for which scopes the +graph drawing engine should apply a layout algorithm to the nodes in +the scope. Typically, you just add an option ending with |... layout| +to the |graph| path operation and then let the graph drawing do its +magic: + +\begin{codeexample}[] +\tikz [rounded corners] + \graph [layered layout, sibling distance=8mm, level distance=8mm] + { + a -> { + b, + c -> { d, e } + } -> + f -> + a + }; +\end{codeexample} + +Whenever you use such an option, you can: +\begin{itemize} +\item Create nodes in the usual way. The nodes will be created + completely, but then tucked away in an internal table. This means + that all of \tikzname's options for nodes can be applied. You can + also name a node and reference it later. +\item Create edges using either the syntax of the |graph| command + (using |--|, |<-|, |->|, or |<->|), or using the |edge| command, + or using the |child| command. These edges will, however, not be + created immediately. Instead, the basic layer's command + |\pgfgdedge| will be called, which stores ``all the information + concerning the edge.'' The actual drawing of the edge will only + happen after all nodes have been positioned. +\item Most of the keys that can be passed to an edge will work as + expected. In particular, you can add labels to edges using the + usual |node| syntax for edges. +\item The |label| and |pin| options can be used in the usual manner + with nodes inside a graph drawing scope. Only, the labels and + nodes will play no role in the positioning of the nodes and they + are added when the nodes are finally positioned. +\item Similarly, nodes that are placed ``on an edge'' using the + implicit positioning syntax can be used in the usual manner. +\end{itemize} +Here are some things that will \emph{not} work: +\begin{itemize} +\item Only edges created using the graph syntax, the |edge| command, + or the |child| command will correctly pass their connection + information to the basic layer. When you write |\draw (a)--(b);| + inside a graph drawing scope, where |a| and |b| are nodes that + have been created inside the scope, you will get an error + message / things will look wrong. The reason is that the usual + |--| is not ``caught'' by the graph drawing engine and, thus, + tries to immediately connect two nodes that do not yet exist + (except inside some internal table). +\item The options of edges are executed twice: Once when the edge is + ``examined'' by the |\pgfgdedge| command (using some magic to shield + against the side effects) and then once more when the edge is + actually created. Fortunately, in almost all cases, this will not be + a problem; but if you do very evil magic inside your edge options, + you must roll a D100 to see what strange things will happen. (Do no + evil, by the way.) +\end{itemize} + +If you are really interested in the ``fine print'' of what happens, +please see Section~\ref{section-gd-pgf}. + + +\subsection{Graph Drawing Parameters} + +Graph drawing algorithms can typically be configured in some way. For +instance, for a graph drawing algorithm that visualizes its nodes as a +tree, it will typically be useful when the user can change the +so-called \emph{level distance} and the \emph{sibling distance}. For +other algorithms, like force-based algorithms, a large number of +parameters influence the way the algorithms work. +Options that influence graph drawing algorithms will be called +\emph{(graph drawing) parameters} in the following. From the user's +point of view, these parameters look like normal \tikzname\ keys and +you set them in the usual way. Internally, they are treated a bit +differently from normal keys since their ``effect'' becomes apparent +only later on, namely during the run of the graph drawing algorithm. + +A graph drawing algorithm may or may not take different graph +parameters into account. After all, these options may even outright +contradict each other, so an algorithm can only try to ``do its +best''. While many graph parameters are very specific to a single +algorithm, a number of graph parameters will be important for many +algorithms and they are documented in the course of the present +section. Here is an example of an option the ``always works'': + +\begin{codeexample}[] +\tikz \graph [spring layout, vertical=1 to 2] { 1--2--3--1 }; +\end{codeexample} + + +\includeluadocumentationof{pgf.gd.control.Distances} +\includeluadocumentationof{pgf.gd.control.Anchoring} +\includeluadocumentationof{pgf.gd.control.Orientation} + + + +\includeluadocumentationof{pgf.gd.control.FineTune} + +\includeluadocumentationof{pgf.gd.control.Components} +\includeluadocumentationof{pgf.gd.control.ComponentOrder} +\includeluadocumentationof{pgf.gd.control.ComponentDirection} +\includeluadocumentationof{pgf.gd.control.ComponentAlign} +\includeluadocumentationof{pgf.gd.control.ComponentDistance} + +\includeluadocumentationof{pgf.gd.control.NodeAnchors} + +\includeluadocumentationof{pgf.gd.model.Hyperedge} + + +\subsection{Using Several Different Layouts to Draw a Single Graph} + +\label{section-gd-sublayouts} + +Inside each graph drawing scope, a main algorithm is used to perform +the graph drawing. However, parts of the graph may be drawn using +different algorithms: For instance, a graph might consist of +several, say, cliques that are arranged in a tree-like fashion. In +this case, it might be useful to layout each clique using a circular +layout, but then lay out all laid out cliques using a tree drawing +algorithm. + +In order to lay out a graph using multiple algorithms, we need two +things: First, we must be able to \emph{specify} which algorithms +should be used where and, second, we must be able to \emph{resolve} +conflicts that may result from different algorithms ``having different +ideas'' concerning where nodes should be placed. + + +\subsubsection{Sublayouts} + +Specifying different layouts for a graph is easy: Inside a graph +drawing scope, simply open scopes, in which you use an option like +|tree layout| for the nodes mentioned in this scope. Inside these +scopes, you can open even subscopes for sublayouts, and so +on. Furthermore, the |graphs| library has special support for +sublayouts. + +Let us start with the ``plain'' syntax for opening sublayouts: You +pass a key for creating layouts to a |scope|: + +\begin{codeexample}[] +\tikz [spring layout] { + \begin{scope}[tree layout] + \node (a) {a}; + \node (b) {b}; + \node (c) {c}; + \draw (a) edge (b) edge (c); + \end{scope} + + \begin{scope}[tree layout] + \node (1) {1}; + \node (2) {2}; + \draw (1) edge (2); + \end{scope} + + \draw (a) edge (1); +} +\end{codeexample} + +Let us see, what is going on here. The main layout (|spring layout|) +contains two sublayouts (the two |tree layouts|). Both of them are +laid out independently (more on the details in a moment). Then, from +the main layout's point of view, the sublayouts behave like ``large +nodes'' and, thus, the edge between |a| and |1| is actually the only +edge that is used by the |spring layout| -- resulting in a simple +layout consisting of one big node at the top and a big node at the +bottom. + +The |graphs| library has a special support for sublayouts: The syntax +is as follows: wherever a normal node would go, you can write + +\begin{quote} + |//| \opt{\oarg{layout options}} |{|\meta{sublayout}|}| +\end{quote} + +Following the double slash, you may provide +\meta{layout options} in square brackets. However, you \emph{must} +provide a sublayout in braces. The contents of \meta{sublayout} will +be parsed using the usual |graph| syntax, but will form a sublayout. + +\begin{codeexample}[] +\tikz \graph [spring layout] { + // [tree layout] { a -- {b, c} }; + // [tree layout] { 1 -- 2 }; + a -- 1; +}; +\end{codeexample} + + +In the above example, there is no node before the double slash, which +means that the two sublayouts will be part of the main graph, but will +not be indicated otherwise. + +\begin{codeexample}[] +\tikz \graph [simple necklace layout] { + // [simple necklace layout] { a -> b -> c -> d -> e -> f -> a }; + + // [tree layout] { % first tentacle + a -> {1, 2}; + }; + + // [tree layout] {% second tentacle + d -> {3, 4 -> {5, 6}} + }; +}; +\end{codeexample} + +In the above example, the first sublayout is the one for the nodes +with letter names. These nodes are arranged using a simple necklace layout +as the sublayout inherits this option from the main layout. The two +small trees (|a -> {1, 2}| and the tree starting at the |d| node) +are also sublayouts, triggered by the |tree layout| option. They are +also arranged. Then, all of the layouts are merged (as described +later). The result is actually a single node, so the main layout +does nothing here. + +Compare the above to the following code: + +\begin{codeexample}[] +\tikz \graph [simple necklace layout] { + // [tree layout] { % first ``giant node'' + a -> {1, 2}; + }; + + a -> b -> c -> d; + + // [tree layout] {% second ``giant node'' + d -> {3, 4 -> {5, 6}} + }, + + d -> e -> f -> a; +}; +\end{codeexample} + +Here, only the two trees are laid out first. They are then +contracted into ``giant nodes'' and these are then part of the set +of nodes that are arranged by the |simple necklace layout|. For details of +how this contracting works, see below. + + +\subsubsection{Subgraph Nodes} + +A \emph{subgraph node} is a special kind of node that ``surrounds'' +the vertices of a subgraph. The special property of a subgraph node +opposed to a normal node is that it is created only after the subgraph +has been laid out. However, the difference to a collection like +|hyper| is that the node is available immediately as a normal node in +the sense that you can connect edges to it. + +The syntax used to declare a subgraph node in a |graph| specification +is as follows: + +\begin{quote} + \opt{|"|}\meta{node + name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} + \opt{\oarg{node options}} + |//| \opt{\oarg{layout options}} |{|\meta{subgraph}|}| +\end{quote} + +The idea ist that a subgraph node is declared like a normal node +specification, but is followed by a double slash and a subgraph: + +\begin{codeexample}[width=5cm] +\tikz \graph [simple necklace layout] { + tree 1[draw, circle] // [tree layout] { a -> {1, 2}; } + -> b + -> c + -> tree 2[draw] // [tree layout] { d -> {3, 4 -> {5, 6} } } + -> e + -> f + -> tree 1; +}; +\end{codeexample} + +Note how the two subgraph nodes |tree 1| and |tree 2| surround the two +smaller trees. In the example, both had trees as contents and these +trees were rendered using a sublayout. However, a subgraph layout does +not need to have its own layout: If you do \emph{not} provide a layout +name after the double slash, the subgraph node will simply surround +all nodes that were placed by the main layout wherever they were +placed: + +\begin{codeexample}[] +\tikz [subgraph text bottom=text centered, + subgraph nodes={font=\itshape}] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw] // { b, c, d }; + right [draw] // { e, f, g, h}; + + left <-> right; + }; +\end{codeexample} + + + +Every time a subgraph node is created, the following style is execute: + +\begin{key}{/tikz/every subgraph node} + Set a subgraph node style. +\end{key} + +\begin{key}{/tikz/subgraph nodes=\meta{style}} + Sets the |every subgraph node| style to \meta{style}. +\begin{codeexample}[] +\tikz [subgraph text bottom=text centered, + subgraph nodes=red] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw] // { b, c, d }; + right [draw] // { e, f, g, h}; + + left <-> right; + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/subgraph text none} + When this option is used, the text of a subgraph node is not + shown. Adding a slash after the node name achieves roughly the same + effect, but this option is useful in situations when subgraph nodes + generally should not have any text inside them. +\begin{codeexample}[] +\tikz [subgraph text none] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw] // { b, c, d }; + right [draw] // { e, f, g, h}; + + left <-> right; + }; +\end{codeexample} + +\end{key} + +\begin{key}{/tikz/subgraph text top=\meta{text alignment + options} (default text ragged right)} + Specifies that the text of a subgraph node should be placed at the + top of the subgraph node: Still inside the node, but above all nodes + inside the subgraph node. +\begin{codeexample}[] +\tikz [subgraph text top=text ragged left] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw] // { b, c, d }; + right [draw] // { e, f, g, h}; + + left <-> right; + }; +\end{codeexample} + You can pass any of the \meta{text alignment options} understood by + \tikzname, such as |text centered|: +\begin{codeexample}[width=5cm] +\tikz [subgraph text top=text centered] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw, circle] // { b, c, d }; + }; +\end{codeexample} + To place a label \emph{outside} the subgraph node, use a label, + typically defined using the |quotes| library: +\begin{codeexample}[] +\tikz \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + / ["left", draw] // { b, c, d } <-> + / ["right", draw] // { e, f, g, h}; + }; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/subgraph text bottom=\meta{text alignment + options} (default ragged right)} + Works like |subgraph text top|, only the text placed at the bottom. +\end{key} + +Note that there are no keys |subgraph text left| or |... right|, +for somewhat technical reasons. + +\begin{key}{/tikz/subgraph text sep=\meta{dimension} (initially .1em)} + Some space added between the inner nodes of a subgraph node and the + text labels. +\end{key} + + +\subsubsection{Overlapping Sublayouts} + +\label{section-gd-layout-resolve} + +Nodes and edges can be part of several layouts. This +will inevitably lead to conflicts because algorithm will disagree on +where a node should be placed on the canvas. For this reason, there +are some rules governing how such conflicts are resolved: Given a +layout, starting with the main layout, the graph drawing system does +the following: + +\begin{enumerate} +\item We start by first processing the (direct) sublayouts of the + current layout (recursively). Sublayouts may overlap (they may share + one or more nodes), but we run the specified layout algorithm for + each sublayout independently on a ``fresh copy'' of all the nodes + making up the sublayout. In particular, different, conflicting + positions may be computed for nodes when they are present in several + sublayouts. +\item Once all nodes in the sublayouts have been laid out in this way, + we \emph{join} overlapping elements. The idea is that if two layouts + share exactly one vertex, we can shift them around so that his + vertex is at the same position in both layouts. In more detail, the + following happens: + + We build a (conceptual) graph whose nodes are the sublayouts and in + which there is an edge between two nodes if the sublayouts + represented by these elements have a node in common. + Inside the resulting graph, we treat each connected component + separately. Each component has the property that the sublayouts + represented by the nodes in the component overlap by at least one + node. We now \emph{join} them as follows: We start with the first + sublayout in the component (``first'' with respect to the order in + which they appear in the input graph) and ``mark'' this + sublayout. We loop the following instructions as long as possible: + Search for the first sublayout (again, with respect to the order in + which they appear in the input) that is connect by an edge to a + marked sublayout. The sublayout will now have at least one node in + common with the marked sublayouts (possibly, even more). We + consider the first such node (again, first respect to the input + ordering) and shift the whole sublayout is such a way that this + particular node is at the position is has in the marked + sublayouts. Note that after the shift, other nodes that are also + present in the marked sublayouts may lie at a different position in + the current sublayout. In this case, the position in the marked + sublayouts ``wins.'' We then mark the sublayout. +\item When the above algorithm has run, we will have computed + positions for all nodes in all sublayouts of each of the + components. For each component, we contract all + nodes of the component to a single node. This new + node will be ``large'' in the sense that its convex hull is the + convex hull of all the nodes in the component. All nodes that used + to be part of the component are removed and the new large node is + added (with arcs adjusted appropriately). +\item We now run the layout's algorithm on the resulting nodes + (the remaining original nodes and the contracted nodes). +\item In a last step, once the graph has been laid out, we expand the + nodes that were previously contracted. For this, the + nodes that were deleted earlier get reinserted, but shifted by + whatever amount the contraction node got shifted. +\end{enumerate} + + +\subsection{Miscellaneous Options} + +\includeluadocumentationof{pgf.gd.control.library} + +\endinput + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex index 4436a3ab3fb..5a5a7b75957 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-guidelines.tex @@ -26,13 +26,13 @@ repeat them in the following guidelines. The first thing you should ask yourself when someone presents a bunch of guidelines is: Should I really follow these guidelines? This is an -important questions, because there are good reasons not to follow -general guidelines. The person who setup the guidelines may have had other +important question, because there are good reasons not to follow +general guidelines. The person who set up the guidelines may have had other objectives than you do. For example, a guideline might say ``use the color red for emphasis.'' While this guideline makes perfect sense for, say, a presentation using a projector, red ``color'' has the \emph{opposite} effect of ``emphasis'' when printed using a -black-and-white printer. Guidelines were almost always setup to +black-and-white printer. Guidelines were almost always set up to address a specific situation. If you are not in this situation, following a guideline can do more harm than good. @@ -40,7 +40,7 @@ The second thing you should be aware of is the basic rule of typography is: ``Every rule can be broken, as long as you are \emph{aware} that you are breaking a rule.'' This rule also applies to graphics. Phrased differently, the basic rule states: ``The only -mistakes in typography are things done is ignorance.'' When you are +mistakes in typography are things done in ignorance.'' When you are aware of a rule and when you decide that breaking the rule has a desirable effect, break the rule. @@ -129,7 +129,7 @@ be inlined, meaning they are somewhere ``in the middle of the text'' or they can be placed in stand-alone ``figures.'' Since printers (the people) like to have their pages ``filled,'' (both for aesthetic and economic reasons) stand-alone figures may traditionally be placed on -pages in the document far removed from the main text that refers to +pages in the document far away from the main text that refers to them. \LaTeX\ and \TeX\ tend to encourage this ``drifting away'' of graphics for technical reasons. @@ -269,7 +269,7 @@ following guidelines: \item Labels should be legible. They should not only have a reasonably large size, they also should not be obscured by lines or other - text. This also applies to of lines and text \emph{behind} the + text. This also applies to labels of lines and text \emph{behind} the labels. \item Labels should be ``in place.'' Whenever there is enough space, @@ -297,7 +297,7 @@ default settings of programs like \textsc{gnuplot} or Excel are to blame for this since these programs make it very convenient to create bad plots. -The first question you should ask yourself when creating a plot is, +The first question you should ask yourself when creating a plot is: Are there enough data points to merit a plot? If the answer is ``not really,'' use a table. @@ -377,7 +377,7 @@ the graphic: Sadly, the graphic does not allow us to answer \emph{a single one of these questions}. The table answers all of them directly, except for the last one. In essence, the information density of the graphic is very -nearly zero. The table has a much higher information density; despite +close to zero. The table has a much higher information density; despite the fact that it uses quite a lot of white space to present a few numbers. Here is the list of things that went wrong with the 3D-bar diagram: \begin{itemize} @@ -707,7 +707,7 @@ Here is a non-exhaustive list of things that can distract readers: should be avoided in general. Do not use different dashing patterns to differentiate curves in - plots. You loose data points this way and the eye is not + plots. You lose data points this way and the eye is not particularly good at ``grouping things according to a dashing pattern.'' The eye is \emph{much} better at grouping things according to colors. @@ -716,7 +716,7 @@ Here is a non-exhaustive list of things that can distract readers: horizontal and vertical lines or just dots are almost always distracting and, usually, serve no real purpose. \item - Background images and shadings distract and only seldom add + Background images and shadings distract and only seldomly add anything of importance to a graphic. \item Cute little clip arts can easily draw attention away from the diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex index 97c2968088b..af964feedac 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-installation.tex @@ -11,7 +11,7 @@ There are different ways of installing \pgfname, depending on your system and needs, and you may need to install other -packages as well as, see below. Before installing, you may wish to +packages as well, see below. Before installing, you may wish to review the licenses under which the package is distributed, see Section~\ref{section-license}. @@ -37,18 +37,24 @@ get its (full) functionality. Currently, \pgfname\ supports the following backend drivers: \begin{itemize} \item + |luatex| version 0.76 or higher. Most earlier versions also work. +\item |pdftex| version 0.14 or higher. Earlier versions do not work. \item |dvips| version 5.94a or higher. Earlier versions may also work. - For inter-picture connections, you need process pictures using + For inter-picture connections, you need to process pictures using |pdftex| version 1.40 or higher running in DVI mode. \item |dvipdfm| version 0.13.2c or higher. Earlier versions may also work. - For inter-picture connections, you need process pictures using + For inter-picture connections, you need to process pictures using |pdftex| version 1.40 or higher running in DVI mode. \item + |dvipdfmx| version 0.13.2c or higher. Earlier versions may also work. +\item + |dvisvgm| version 1.2.2 or higher. Earlier versions may also work. +\item |tex4ht| version 2003-05-05 or higher. Earlier versions may also work. \item |vtex| version 8.46a or higher. Earlier versions may also work. @@ -66,9 +72,7 @@ Currently, \pgfname\ supports the following formats: |plain| with complete functionality, except for graphics inclusion, which works only for pdf\TeX. \item - |context| with complete functionality\footnote{Note that - \pgfname/\tikzname{} is not supported by recent Con\TeX t versions - (like mark IV, the Lua\TeX-aware part of Con\TeX t).}, except for + |context| with complete functionality, except for graphics inclusion, which works only for pdf\TeX. \end{itemize} @@ -89,12 +93,7 @@ MiK\TeX\ page first. \subsubsection{Debian} The command ``|aptitude install pgf|'' should do the trick. Sit back -and relax. In detail, the following packages are installed: -\begin{verbatim} -http://packages.debian.org/pgf -http://packages.debian.org/latex-xcolor -\end{verbatim} - +and relax. \subsubsection{MiKTeX} @@ -187,6 +186,6 @@ with the files of the new version (or in all the directories where |pgf| was installed, if you chose a \textsc{tds}-compliant installation). The easiest way to do this is to first delete the old version and then proceed as described above. Sometimes, there are -changes in the syntax of certain command from version to version. If +changes in the syntax of certain commands from version to version. If things no longer work that used to work, you may wish to have a look at the release notes and at the change log. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex index 7db4aa68733..ece53e719e6 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-introduction.tex @@ -10,29 +10,48 @@ \section{Introduction} -The \pgfname\ package, where ``\pgfname'' is supposed to mean ``portable -graphics format'' (or ``pretty, good, functional'' if you -prefer\dots), is a package for creating graphics in an ``inline'' -manner. It defines a number of \TeX\ commands that draw +Welcome to the documentation of \tikzname\ and the underlying +\pgfname\ system. What began as a small La\TeX\ style for creating the +graphics in my (Till Tantau's) PhD thesis directly with pdf\LaTeX\ has now +grown to become a full-flung graphics language with a manual of over a +thousand pages. The wealth of options offered by \tikzname\ is often +daunting to beginners; but fortunately this documentation comes with a +number slowly-paced tutorials that will teach you almost all you +should know about \tikzname\ without your having to read the rest. + +I wish to start with the questions ``What is \tikzname?'' +Basically, it just defines a number of \TeX\ commands that draw graphics. For example, the code |\tikz \draw (0pt,0pt) -- (20pt,6pt);| yields the line \tikz \draw (0pt,0pt) -- (20pt,6pt); and the code |\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields \tikz -\fill[orange] (1ex,1ex) circle (1ex);. - -In a sense, when you use \pgfname\ you ``program'' your graphics, just -as you ``program'' your document when you use \TeX. You get all -the advantages of the ``\TeX-approach to typesetting'' 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 \textsc{wysiwyg}, small -changes require a long recompilation time, and the code does not -really ``show'' how things will look like. - - - -\subsection{Structure of the System} - -The \pgfname\ system consists of different layers: +\fill[orange] (1ex,1ex) circle (1ex);. In a sense, when you use +\tikzname\ you ``program'' your graphics, just as you ``program'' your +document when you use \TeX. This also explains the name: \tikzname\ +is a recursive accronym in the tradition of ``\textsc{gnu} is not +unix'' and means ``\tikzname\ ist \emph{kein} Zeichenprogramm,'' which +translates to ``\tikzname\ is not a drawing program,'' cautioning the +reader as to what to expect. With \tikzname\ you get all the advantages of the +``\TeX-approach to typesetting'' 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 \textsc{wysiwyg}, small changes require a long +recompilation time, and the code does not really ``show'' how things +will look like. + +Now that we know what \tikzname\ is, what about ``\pgfname''? +As mentioned earlier, \tikzname\ started out as a project to implement +\TeX\ graphics macros that can be used both with pdf\LaTeX\ and also +with the classical (PostScript-based) \LaTeX. In other words, I wanted +to implement a ``portable graphics format'' for \TeX\ -- hence the +name \pgfname. These early macros are still around and they form the +``basic layer'' of the system described in this manual, but most of +the interaction an author has theses days is with \tikzname\ -- which +has become a whole language of its own. + + +\subsection{The Layers Below \tikzname} + +It turns out that there are actually \emph{two} layers below \tikzname: \begin{description} \item[System layer:] This layer provides a complete abstraction of what is @@ -59,74 +78,62 @@ The \pgfname\ system consists of different layers: you to produce complex graphics in a much easier manner 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 + the more basic B\'ezier 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 + B\'ezier curve support coordinates. Thus, the basic layer provides a command |\pgfpathcircle| that generates the necessary curve coordinates for you. - The basic layer is consists of a \emph{core}, which consists of + The basic layer consists of a \emph{core}, which consists of several interdependent packages that can only be loaded \emph{en bloc,} and additional \emph{modules} that extend the core by more special-purpose commands like node management or a plotting interface. For instance, the \textsc{beamer} package uses only the core and not, say, the |shapes| modules. -\item[Frontend layer:] - 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 |tikz| frontend - all this boils down to a single simple \textsc{metafont}-like - command: +\end{description} + +In theory, \tikzname itself is just one of several possible +``frontends,'' which are sets 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 \tikzname\ frontend +all this boils down to a single simple \textsc{metafont}-like +command: \begin{verbatim} \draw (0,0) -- (1,0) -- (1,1) -- cycle; \end{verbatim} - There are different frontends: - \begin{itemize} - \item - The \tikzname\ frontend is the ``natural'' frontend for \pgfname. It gives - you access to all features of \pgfname, but it is intended to be - easy to use. The syntax is a mixture of \textsc{metafont} and - \textsc{pstricks} and some ideas of myself. This frontend is % TODOsp: change all `pstricks' to `PStricks'? (ff) - \emph{neither} a complete \textsc{metafont} compatibility layer nor - a \textsc{pstricks} compatibility layer and it is not intended to - become either. - \item - The |pgfpict2e| frontend reimplements the standard \LaTeX\ - |{picture}| environment and commands like |\line| or |\vector| - using the \pgfname\ basic layer. This layer is not really ``necessary'' - since the |pict2e.sty| package does at least as good a job at - reimplementing the |{picture}| environment. Rather, the idea - behind this package is to have a simple demonstration of how a - frontend can be implemented. - \end{itemize} - - It would be possible to implement a |pgftricks| frontend that maps - \textsc{pstricks} commands to \pgfname\ commands. However, I have not - done this and even if fully implemented, many things that work in - \pstricks\ will not work, namely whenever some \pstricks\ command - relies too heavily on PostScript trickery. Nevertheless, such a - package might be useful in some situations. -\end{description} - -As a user of \pgfname\ 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. - +In practice, \tikzname\ is the only ``serious'' frontend for \pgfname. It +gives you access to all features of \pgfname, but it is intended to be +easy to use. The syntax is a mixture of \textsc{metafont} and +\textsc{pstricks} and some ideas of myself. There are other frontends +besides \tikzname, but they are more intended as ``technology +studies'' and less as serious alternatives to \tikzname. In +particular, the |pgfpict2e| frontend reimplements the standard +\LaTeX\ |{picture}| environment and +commands like |\line| or |\vector| +using the \pgfname\ basic layer. This layer is not really ``necessary'' +since the |pict2e.sty| package does at least as good a job at +reimplementing the |{picture}| environment. Rather, the idea +behind this package is to have a simple demonstration of how a +frontend can be implemented. + +Since most users will only use \tikzname\ and almost no one will use +the system layer directly, this manual is mainly about \tikzname\ in +the first parts; the basic layer and the system layer are explained at +the end. \subsection{Comparison with Other Graphics Packages} -\pgfname\ is not the only graphics package for \TeX. In the following, -I try to give a reasonably fair comparison of the \pgfname-system and +\tikzname\ is not the only graphics package for \TeX. In the following, +I try to give a reasonably fair comparison of \tikzname\ and other packages. \begin{enumerate} \item @@ -138,48 +145,38 @@ other packages. backend drivers. \item The |pstricks| package is certainly powerful enough to create - any conceivable kind of graphic, but it is not portable at all. Most + any conceivable kind of graphic, but it is not really portable. Most importantly, it does not work with |pdftex| nor with any other driver that produces anything but PostScript code. - Compared to \pgfname, |pstricks| has a broader support base. There + Compared to \tikzname, |pstricks| has a similar support base. There are many nice extra packages for special purpose situations that have been contributed by users over the last decade. - The \tikzname\ syntax is more consistent than the |pstricks| syntax as \tikzname\ was developed ``in a more centralized manner'' and also ``with the shortcomings on |pstricks| in mind.'' - - Note that a number of neat tricks that |pstricks| can do are - impossible in \pgfname. In particular, |pstricks| has access to the - powerful PostScript programming language, which allows trickery - such as inline function plotting. \item The |xypic| package is an older package for creating graphics. However, it is more difficult to use and to learn because the syntax and the documentation are a bit cryptic. \item The |dratex| package is a small graphic package for creating a - graphics. Compared to the other package, including \pgfname, it is + graphics. Compared to the other package, including \tikzname, it is very small, which may or may not be an advantage. \item - The |metapost| program is a very powerful alternative to - \pgfname. However, it is an external program, which entails a - bunch of problems. The time needed both to create a small graphic - and also to compile it is much greater than in \pgfname. - The main problem with |metapost|, however, is the inclusion of - labels. This is \emph{much} easier to achieve using \pgfname. + The |metapost| program is a powerful alternative to + \tikzname. It used to be an external program, which entailed a + bunch of problems, but in Lua\TeX\ it is now build in. An obstacle + with |metapost| is the inclusion of labels. This is \emph{much} + easier to achieve using \pgfname. \item The |xfig| program is an important alternative to \tikzname\ for users who do not wish to ``program'' their graphics as is necessary - with \tikzname\ and the other packages above. Their is a conversion - program that will convert |xfig| graphics to both \tikzname\ and - for \pgfname, but it is still under construction. + with \tikzname\ and the other packages above. There is a conversion + program that will convert |xfig| graphics to \tikzname. \end{enumerate} - - \subsection{Utility Packages} The \pgfname\ package comes along with a number of utility package that @@ -215,20 +212,20 @@ closely intertwined with \pgfname. These utility packages are: \subsection{How to Read This Manual} -This manual describes both the design of the \pgfname\ system and -its usage. The organization is very roughly according to +This manual describes both the design of \tikzname\ 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. -If you have not yet installed \pgfname, please read the installation +If you have not yet installed \tikzname, 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 \tikzname. 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 \pgfname\ to a new driver. -The ``public'' commands and environments provided by the |pgf| package +The ``public'' commands and environments provided by the system 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. @@ -289,7 +286,4 @@ following: somewhat higher if you mail to the \pgfname\ mailing list (naturally, I read this list and answer questions when I have the time). -\item - Please, do not phone me in my office (unless, of course, you attend - one of my lectures). \end{enumerate} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-angles.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-angles.tex new file mode 100644 index 00000000000..c46a6e4204b --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-angles.tex @@ -0,0 +1,89 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Angle Library} + +\label{section-angle} + +\begin{tikzlibrary}{angles} + This library defines pic types for drawing angles. +\end{tikzlibrary} + +\begin{pictype}{angle}{\opt{|=|\meta{A}|--|\meta{B}|--|\meta{C}}} + This pic adds a drawing of an angle to the current path. This + ``drawing of an angle'' consist of a ``sector'' or ``wedge'' or + ``slice'' whose pointed end is at point \meta{B} and whose straight + sides lie on the lines form \meta{B} to \meta{A} and from \meta{B} + to \meta{C}. The length of these lines is governed by the following + key: + \begin{key}{/tikz/angle radius=\meta{dimension} (initially 5mm)} + The length of the sides of the angle's wedge: +\begin{codeexample}[] +\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (-1,-1) coordinate (C) + pic [fill=black!50] {angle = A--B--C} + pic [draw,->,red,thick,angle radius=1cm] {angle = C--B--A}; +\end{codeexample} + \end{key} + + The three points \meta{A}, \meta{B}, and \meta{C} \emph{must} be the + names of nodes or coordinates; you cannot use direct coordinates like + ``|(1,1)|'' here. + + You can leave out the three points, in this case the text |A--B--C| + is used; so in the above examples we could just have written + |{angle}| in the first pic. + + Concerning the sector that makes up the drawing of the angle, the + angular part of this sector is drawn in front of the path if the + |draw| option is given to the |pic|, while filled sector is drawn + behind the |pic|, provided an option like |fill| or |shade| is + passed to the pic. The following example shows the difference: + +\begin{codeexample}[] +\tikz \draw [line width=2mm] + (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic [draw=blue, fill=blue!50, angle radius=1cm] {angle}; +\end{codeexample} + + When |pic text| is set (which you typically do by using the quotes + syntax), a node will be created whose name is empty + (and, thus, inherits the pic's name) and which will be at the + half-way angle between the lines to \meta{A} and \meta{C} and whose + distance from \meta{B} is |angle radius| times the following factor: + \begin{key}{/tikz/angle eccentricity=\meta{factor} (initially 0.6)} +\begin{codeexample}[] +\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic ["$\alpha$", draw, ->] {angle}; +\end{codeexample} +\begin{codeexample}[] +\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic ["$\alpha$", draw, angle eccentricity=1] {angle}; +\end{codeexample} +\begin{codeexample}[] +\tikz { + \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic (alpha) ["$\alpha$", draw] {angle}; + + \draw (alpha) circle [radius=5pt]; +} +\end{codeexample} + \end{key} +\end{pictype} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-arrows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-arrows.tex index da4523a9ff1..6db5b1002ac 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-arrows.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-arrows.tex @@ -11,147 +11,235 @@ \section{Arrow Tip Library} \label{section-library-arrows} -\begin{pgflibrary}{arrows} - The package defines additional arrow tips, which are described - below. Note that neither the standard packages nor - this package defines an arrow name containing |>| or |<|. These are - left for the user to defined as he or she sees fit. -\end{pgflibrary} - -The arrow tips |to|, |stealth|, |latex|, |space|, their reversed -forms, and \verb!|! are predefined, but listed below for completeness, -nevertheless. - - -\subsection{Mathematical Arrow Tips} - -\begin{tabular}{ll} - \symarrow{to} \\ - \symarrow{to reversed} \\ - \symarrowdouble{implies} \\ -\end{tabular} - - -\subsection{Triangular Arrow Tips} - -\begin{tabular}{ll} - \symarrowdouble{latex} \\ - \symarrowdouble{latex reversed} \\ - \symarrow{latex'} \\ - \symarrow{latex' reversed} \\ - \symarrowdouble{stealth} \\ - \symarrowdouble{stealth reversed} \\ - \symarrow{stealth'} \\ - \symarrow{stealth' reversed}\\ - \symarrow{triangle 90} \\ - \symarrow{triangle 90 reversed} \\ - \symarrow{triangle 60} \\ - \symarrow{triangle 60 reversed} \\ - \symarrow{triangle 45} \\ - \symarrow{triangle 45 reversed} \\ - \symarrow{open triangle 90} \\ - \symarrow{open triangle 90 reversed} \\ - \symarrow{open triangle 60} \\ - \symarrow{open triangle 60 reversed} \\ - \symarrow{open triangle 45} \\ - \symarrow{open triangle 45 reversed} \\ -\end{tabular} - - -\subsection{Barbed Arrow Tips} - -\begin{tabular}{ll} - \symarrow{angle 90} \\ - \symarrow{angle 90 reversed} \\ - \symarrow{angle 60} \\ - \symarrow{angle 60 reversed} \\ - \symarrow{angle 45} \\ - \symarrow{angle 45 reversed} \\ - \symarrow{hooks} \\ - \symarrow{hooks reversed} \\ -\end{tabular} - - -\subsection{Bracket-Like Arrow Tips} - -{ -\bigskip -\catcode`\|=12 -\begin{tabular}{ll} - \sarrow{[}{]} \\ - \sarrow{]}{[} \\ - \sarrow{(}{)} \\ - \sarrow{)}{(} \\ - \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}% - \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}} - \texttt{\char`\|-\char`\|} & yields thick - \begin{tikzpicture}[arrows={|-|},thick] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); - \draw (0,0) -- (1,0); - \end{tikzpicture} and thin - \begin{tikzpicture}[arrows={|-|},thin] - \useasboundingbox (0pt,-0.5ex) rectangle (1cm,2ex); - \draw (0,0) -- (1,0); - \end{tikzpicture} -\end{tabular} -} - -\subsection{Circle, Diamond and Square Arrow Tips} - - -\begin{tabular}{ll} - \symarrow{o} \\ - \symarrow{*} \\ - \symarrow{diamond} \\ - \symarrow{open diamond} \\ - \symarrow{square} \\ - \symarrow{open square} \\ -\end{tabular} - - - -\subsection{Serif-Like Arrow Tips} - -\begin{tabular}{ll} - \symarrow{serif cm} -\end{tabular} - - -\subsection{Partial Arrow Tips} - -\begin{tabular}{ll} - \symarrow{left to} \\ - \symarrow{left to reversed} \\ - \symarrow{right to} \\ - \symarrow{right to reversed} \\ - \symarrow{left hook} \\ - \symarrow{left hook reversed} \\ - \symarrow{right hook} \\ - \symarrow{right hook reversed} -\end{tabular} - - - -\subsection{Line Caps} - -\begin{tabular}{ll} - \carrow{round cap} \\ - \carrow{butt cap} \\ - \carrow{triangle 90 cap} \\ - \carrow{triangle 90 cap reversed} \\ - \carrow{fast cap} \\ - \carrow{fast cap reversed} \\ -\end{tabular} - - -\subsection{Spacing Tips} - -The spacing arrow tips are useful for combining them with other arrows -to get arrows that do not touch the end of the line. - -\begin{tabular}{ll} - \symarrow{space} \\ -\end{tabular} +The libraries |arrows| and |arrows.spaced| from older +versions of \pgfname\ are still available for compatibility, but they +are considered deprecated. + +The standard arrow tips, which are loaded by the library +|arrows.meta|, are documented in Section~\ref{section-arrows-meta}. + +\endinput + + +% \subsection{Mathematical Arrow Tips} + +% \begin{tabular}{ll} +% \symarrow{to} \\ +% \symarrow{to reversed} \\ +% \symarrowdouble{implies} \\ +% \symarrow{spaced to} \\ +% \symarrow{spaced to reversed} \\ +% \symarrowdouble{spaced implies} \\ +% \end{tabular} + + +% \subsection{Triangular Arrow Tips} + +% \begin{tabular}{ll} +% \symarrowdouble{latex} \\ +% \symarrowdouble{latex reversed} \\ +% \symarrow{latex'} \\ +% \symarrow{latex' reversed} \\ +% \symarrowdouble{stealth} \\ +% \symarrowdouble{stealth reversed} \\ +% \symarrow{stealth'} \\ +% \symarrow{stealth' reversed}\\ +% \symarrow{triangle 90} \\ +% \symarrow{triangle 90 reversed} \\ +% \symarrow{triangle 60} \\ +% \symarrow{triangle 60 reversed} \\ +% \symarrow{triangle 45} \\ +% \symarrow{triangle 45 reversed} \\ +% \symarrow{open triangle 90} \\ +% \symarrow{open triangle 90 reversed} \\ +% \symarrow{open triangle 60} \\ +% \symarrow{open triangle 60 reversed} \\ +% \symarrow{open triangle 45} \\ +% \symarrow{open triangle 45 reversed} \\ +% \end{tabular} + +% \medskip +% \noindent +% \begin{tabular}{ll} +% \symarrowdouble{spaced latex} \\ +% \symarrowdouble{spaced latex reversed} \\ +% \symarrow{spaced latex'} \\ +% \symarrow{spaced latex' reversed} \\ +% \symarrowdouble{spaced stealth} \\ +% \symarrowdouble{spaced stealth reversed} \\ +% \symarrow{spaced stealth'} \\ +% \symarrow{spaced stealth' reversed}\\ +% \end{tabular} + +% \medskip +% \noindent +% \begin{tabular}{ll} +% \symarrow{spaced triangle 90} \\ +% \symarrow{spaced triangle 90 reversed} \\ +% \symarrow{spaced triangle 60} \\ +% \symarrow{spaced triangle 60 reversed} \\ +% \symarrow{spaced triangle 45} \\ +% \symarrow{spaced triangle 45 reversed} \\ +% \symarrow{spaced open triangle 90} \\ +% \symarrow{spaced open triangle 90 reversed} \\ +% \symarrow{spaced open triangle 60} \\ +% \symarrow{spaced open triangle 60 reversed} \\ +% \symarrow{spaced open triangle 45} \\ +% \symarrow{spaced open triangle 45 reversed} \\ +% \end{tabular} + + +% \subsection{Barbed Arrow Tips} + +% \begin{tabular}{ll} +% \symarrow{angle 90} \\ +% \symarrow{angle 90 reversed} \\ +% \symarrow{angle 60} \\ +% \symarrow{angle 60 reversed} \\ +% \symarrow{angle 45} \\ +% \symarrow{angle 45 reversed} \\ +% \symarrow{hooks} \\ +% \symarrow{hooks reversed} \\ +% \end{tabular} + +% \medskip +% \noindent +% \begin{tabular}{ll} +% \symarrow{spaced angle 90} \\ +% \symarrow{spaced angle 90 reversed} \\ +% \symarrow{spaced angle 60} \\ +% \symarrow{spaced angle 60 reversed} \\ +% \symarrow{spaced angle 45} \\ +% \symarrow{spaced angle 45 reversed} \\ +% \symarrow{spaced hooks} \\ +% \symarrow{spaced hooks reversed} \\ +% \end{tabular} + + +% \subsection{Bracket-Like Arrow Tips} + +% { +% \bigskip +% \catcode`\|=12 +% \begin{tabular}{ll} +% \sarrow{[}{]} \\ +% \sarrow{]}{[} \\ +% \sarrow{(}{)} \\ +% \sarrow{)}{(} \\ +% \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}% +% \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}}% +% \texttt{\char`\|-\char`\|} & yields thick +% \begin{tikzpicture}[arrows={|-|},thick] +% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); +% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; +% \draw (0pt,.5ex) -- (1cm,.5ex); +% \end{tikzpicture} and thin +% \begin{tikzpicture}[arrows={|-|},thin] +% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); +% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; +% \draw (0pt,.5ex) -- (1cm,.5ex); +% \end{tikzpicture}\\ +% \sarrow{spaced [}{spaced ]} \\ +% \sarrow{spaced ]}{spaced [} \\ +% \sarrow{spaced (}{spaced )} \\ +% \sarrow{spaced )}{spaced (} \\ +% \index{*spaced vbar@\protect\texttt{spaced \protect\myvbar} arrow tip}% +% \index{Arrow tips!*spaced vbar@\protect\texttt{spaced \protect\myvbar}}% +% \texttt{spaced \char`\|-spaced \char`\|} & yields thick +% \begin{tikzpicture}[arrows={spaced |-spaced |},thick] +% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); +% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; +% \draw (0pt,.5ex) -- (1cm,.5ex); +% \end{tikzpicture} and thin +% \begin{tikzpicture}[arrows={spaced |-spaced |},thin] +% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex); +% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ; +% \draw (0pt,.5ex) -- (1cm,.5ex); +% \end{tikzpicture} +% \end{tabular} +% } + +% \subsection{Circle, Diamond and Square Arrow Tips} + + +% \begin{tabular}{ll} +% \symarrow{o} \\ +% \symarrow{*} \\ +% \symarrow{diamond} \\ +% \symarrow{open diamond} \\ +% \symarrow{square} \\ +% \symarrow{open square} \\ +% \end{tabular} + + +% \medskip +% \noindent +% \begin{tabular}{ll} +% \symarrow{spaced o} \\ +% \symarrow{spaced *} \\ +% \symarrow{spaced diamond} \\ +% \symarrow{spaced open diamond} \\ +% \symarrow{spaced square} \\ +% \symarrow{spaced open square} \\ +% \end{tabular} + + +% \subsection{Serif-Like Arrow Tips} + +% \begin{tabular}{ll} +% \symarrow{serif cm} \\ +% \symarrow{spaced serif cm} +% \end{tabular} + + +% \subsection{Partial Arrow Tips} + +% \begin{tabular}{ll} +% \symarrow{left to} \\ +% \symarrow{left to reversed} \\ +% \symarrow{right to} \\ +% \symarrow{right to reversed} \\ +% \symarrow{left hook} \\ +% \symarrow{left hook reversed} \\ +% \symarrow{right hook} \\ +% \symarrow{right hook reversed}\\ +% \symarrow{spaced left to} \\ +% \symarrow{spaced left to reversed} \\ +% \symarrow{spaced right to} \\ +% \symarrow{spaced right to reversed} \\ +% \symarrow{spaced left hook} \\ +% \symarrow{spaced left hook reversed} \\ +% \symarrow{spaced right hook} \\ +% \symarrow{spaced right hook reversed} +% \end{tabular} + + +% \subsection{Line Caps} + +% \begin{tabular}{ll} +% \carrow{round cap} \\ +% \carrow{butt cap} \\ +% \carrow{triangle 90 cap} \\ +% \carrow{triangle 90 cap reversed} \\ +% \carrow{fast cap} \\ +% \carrow{fast cap reversed} \\ +% \carrow{spaced round cap} \\ +% \carrow{spaced butt cap} \\ +% \carrow{spaced triangle 90 cap} \\ +% \carrow{spaced triangle 90 cap reversed} \\ +% \carrow{spaced fast cap} \\ +% \carrow{spaced fast cap reversed} \\ +% \end{tabular} + + +% \subsection{Spacing Tips} + +% The spacing arrow tips are useful for combining them with other arrows +% to get arrows that do not touch the end of the line. + +% \begin{tabular}{ll} +% \symarrow{space} \\ +% \end{tabular} %%% Local Variables: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-automata.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-automata.tex index 2684d96c71d..48afc09ca87 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-automata.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-automata.tex @@ -41,7 +41,7 @@ To draw an automaton, proceed as follows: \end{enumerate} Let us now see how this works for a real example. Let us consider a -nondeterministic four state automaton that checks whether an contains +nondeterministic four state automaton that checks whether an input contains the sequence $0^*1$ or the sequence $1^*0$. \begin{codeexample}[] \begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid,auto] @@ -71,7 +71,7 @@ desired kind of styles. By default, the following state styles are defined: \begin{stylekey}{/tikz/state without output} - This node style causes nodes to be drawn circles. Also, this style + This node style causes nodes to be drawn as circles. Also, this style calls |every state|. \end{stylekey} @@ -147,7 +147,7 @@ Let us start with the initial states. Set the place where the text should be shown. Allowed values are |above|, |below|, |left|, and |right|. \end{key} - \begin{key}{/tikz/intial distance=\meta{distance} (initially 3ex)} + \begin{key}{/tikz/initial distance=\meta{distance} (initially 3ex)} Sets the length of the arrow leading from the text to the state node. \end{key} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-backgrounds.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-backgrounds.tex index ed7ed14b624..2b79d042e58 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-backgrounds.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-backgrounds.tex @@ -23,21 +23,23 @@ The first use of this library is to make the following key available: -\begin{key}{/tikz/on background layer} - This key can be used with a |{scope}|. It will cause everything - inside the scope to be typeset on a background layer. Note that the - scope should not be ``deeply nested'' inside the picture since - changes to the graphic state (like the color or the transformation - matrix) ``do not survive a layer switch.'' For more details on - layers see Section~\ref{section-layers}. +\begin{key}{/tikz/on background layer=\meta{options}} + This key can (only) be used with a |{scope}| or |\scoped|. It will + cause everything inside the scope to be typeset on a background + layer. + + The \meta{options} will be executed \emph{inside} background + scope. This is useful since \emph{other} options passed to the + |{scope}| environment will be executed \emph{before} the actual + background material starts and, thus, will have no effect on it. \begin{codeexample}[] \begin{tikzpicture} % On main layer: \fill[blue] (0,0) circle (1cm); - \begin{scope}[on background layer] - \fill[yellow] (-1,-1) rectangle (1,1); + \begin{scope}[on background layer={color=yellow}] + \fill (-1,-1) rectangle (1,1); \end{scope} \begin{scope}[on background layer] @@ -48,6 +50,34 @@ The first use of this library is to make the following key available: \fill[blue!50] (-.5,-1) rectangle (.5,1); \end{tikzpicture} \end{codeexample} + + A scope with this option set should not be ``deeply nested'' inside + the picture since changes to the graphic state (like the color or + the transformation matrix) ``do not survive a layer switch,'' see + also Section~\ref{section-layers} for details. In particular, + setting, say, the line width at the beginning of a picture will not + have an effect on the background picture. + + For this reason, it may be useful to setup the following style: + \begin{stylekey}{/tikz/every on background layer} + This style is executed at the beginning of each background + layer. If you have a global setup in |every picture|, you should + consider putting that part of it that concerns the graphics state + into this style. + +\begin{codeexample}[] +\tikzset{ + every picture/.style={line width=1ex}, + every on background layer/.style={every picture} +} +\begin{tikzpicture} + \draw [->] (0,0) -- (2,1); + + \scoped[on background layer] + \draw[red] (0,1) -- (2,0); +\end{tikzpicture} +\end{codeexample} + \end{stylekey} \end{key} When this package is loaded, the following styles become available: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex index a61feb19de7..f0e2e8c8e1c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-calendar.tex @@ -107,7 +107,7 @@ environments (similar to, say, the |\draw| command). \medskip \textbf{Changing the spacing.} In the above calendar, the spacing between the days is determined by - the numerous options. Most arrangement do not use all of these + numerous options. Most arrangements do not use all of these options, but only those that apply naturally. \begin{key}{/tikz/day xshift=\meta{dimension} (initially 3.5ex)} Specifies the @@ -178,7 +178,7 @@ environments (similar to, say, the |\draw| command). \textbf{Changing the appearance of days.} As mentioned before, each day in the above calendar is produced by an execution of the |\tikzdaycode|. Each time this code is executed, - the coordinate system will have been setup appropriately to place + the coordinate system will have been set up appropriately to place the day of the month correctly. You can change both the code and its appearance using the following options. \begin{key}{/tikz/day code=\meta{code} (initially \normalfont see below)} @@ -246,7 +246,7 @@ environments (similar to, say, the |\draw| command). \end{codeexample} \end{key} - \begin{stylekey}{/tikz/every day (initially anchor=base east)} + \begin{key}{/tikz/every day (initially anchor=base east)} This style is executed by the default node code for each day. The |every day| style is useful for changing the way days look. For example, let us make all days red: @@ -254,7 +254,7 @@ environments (similar to, say, the |\draw| command). \tikz[every day/.style=red] \calendar[dates=2000-01-01 to 2000-01-31,week list]; \end{codeexample} - \end{stylekey} + \end{key} \medskip @@ -468,7 +468,7 @@ arrangements. \subsubsection{Creating a Simple List of Days} -We start with a list the days of the calendar, one day below the +We start with a list of the days of the calendar, one day below the other. For this, we simply shift the coordinate system downward at the end of the code for each day. This shift must be \emph{outside} the day scope as we want day shifts to accumulate. Thus, we use the @@ -677,7 +677,7 @@ The following arrangement gives a very compact view of a whole year. \subsection{Month Labels} -For many calendars you may wish to add a labels to each month. We have +For many calendars you may wish to add a label to each month. We have already covered how month nodes are created and rendered in the description of the |\calendar| command: use |month text|, |every month|, and also |month code| (if necessary) to change the @@ -867,7 +867,7 @@ The following example is a futuristic calendar that is all about circles: {1/winter,2/winter,3/spring,4/spring,5/spring,6/summer, 7/summer,8/summer,9/fall,10/fall,11/fall,12/winter} { - % Computer angle: + % Compute angle: \mycount=\month \advance\mycount by -1 \multiply\mycount by 30 @@ -893,7 +893,7 @@ The following example is a futuristic calendar that is all about circles: \end{tikzpicture} \end{codeexample} -Next, lets us have a whole year in a tight column: +Next, let's us have a whole year in a tight column: \begin{codeexample}[leave comments] \begin{tikzpicture} \small\sffamily diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex index 25f0c1f3433..0c02a736efe 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex @@ -20,7 +20,7 @@ \subsection{Overview} \emph{Chains} are sequences of nodes that are -- typically -- arranged -in an o row or a column and that are -- typically -- connected by +in a row or a column and that are -- typically -- connected by edges. More generally, they can be used to position nodes of a branching network in a systematic manner. For the positioning of nodes in rows and columns you can also use matrices, see @@ -35,7 +35,7 @@ connections. \subsection{Starting and Continuing a Chain} Typically, you construct one chain at a time, but it is -permissible to have construct multiple chains simultaneously. In this +permissible to construct multiple chains simultaneously. In this case, the chains must be named differently and you must specify for each node which chain it belongs to. @@ -51,7 +51,7 @@ option. used instead. The key starts a chain named \meta{chain name} and makes it - \emph{active}, which means that is currently being constructed. The + \emph{active}, which means that it is currently being constructed. The |start chain| can be issued only once to activate a chain, inside a scope in which a chain is active you cannot use this option once more (for the same chain name). The chain stops being active at the @@ -129,7 +129,7 @@ option. Let us have a look at the two different applications of this option. The first is to change the direction of a chain as it is - begin constructed. For this, just give this option somewhere inside + being constructed. For this, just give this option somewhere inside the scope of the chain. \begin{codeexample}[] \begin{tikzpicture}[start chain=going right,node distance=5mm] @@ -178,7 +178,7 @@ option. last invocation ``wins.'' (To place a node on several chains, use the |\chainin| command repeatedly.) - The \meta{direction} part is optional. If present it sets the + The \meta{direction} part is optional. If present, it sets the direction used for this node, otherwise the \meta{direction} that was given to the original |start chain| option is used (or of the last |continue chain| option, which allows you to change this @@ -186,12 +186,12 @@ option. The effects of this option are the following: \begin{enumerate} - \item An internal counter (there is one, local, counter + \item An internal counter (there is one local counter for each chain) is increased. This counter reflects the current number of the node in the chain, where the first node is node 1, the second is node 2, and so on. - This value of this internal counter is globally stored in the + The value of this internal counter is globally stored in the macro \declare{|\tikzchaincount|}. \item If the node does not yet have a name, (having been given using the |name| option or the name-syntax), the name of the node is set to @@ -248,12 +248,12 @@ option. \item The following style is executed: \begin{stylekey}{/tikz/every on chain} - This key is executed for every node of a chain, including the + This key is executed for every node on a chain, including the first one. \end{stylekey} \end{enumerate} - Recall that the standard replacement rule has a form like + Recall that the standard placement rule has a form like |right=of (\tikzchainprevious)|. This means that each new node is placed to the right of the previous one, spaced by the current value of |node distance|. @@ -387,7 +387,7 @@ following command, which is only defined inside scopes where a This style is executed each time this command is used. \end{stylekey} - Note that is makes sense to call this option several times for a + Note that it makes sense to call this option several times for a node, in order to connect it to several nodes. This is especially useful for joining in branches, see the next section. \begin{codeexample}[] diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-circuits.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-circuits.tex index 496eac52179..9478ed33ad3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-circuits.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-circuits.tex @@ -144,7 +144,7 @@ current values of parameters like |minimum height| or |inner xsep|. For these reasons, the circuit libraries introduce the concept of a \emph{symbol graphic}. This is a style that causes a |\node| to not only have the correct shape, but also the correct size and the -correct path usage. More generally, this style may setup things in any +correct path usage. More generally, this style may set up things in any way so that the ``symbol looks correct''. When you write, for instance, |\node[diode]|, then the style called |diode graphic| is used, which in turn is set to something like @@ -196,9 +196,8 @@ symbols, use |circuits.logic.IEC|. If you cannot decide, include both: \usetikzlibrary{circuits.logic.US,circuits.logic.IEC} \end{codeexample} To create a picture that contains a US-style circuit you can now use -the option |circuit logic US|. This will setup keys like |and gate| to -create use an appropriate symbol graphic for rendering an and -gate. Using the |circuit logic IEC| instead will setup |and gate| to +the option |circuit logic US|. This will set up keys like |and gate| to +create use an appropriate symbol graphic for rendering an |and gate|. Using the |circuit logic IEC| instead will set up |and gate| to use another symbol graphic. \begin{codeexample}[] @@ -368,7 +367,7 @@ annotation as a parameter to the symbol as in the following example: \end{codeexample} However, in the above example we would not actually see anything - since we have not yet setup the graphic to be used by |foo|. For + since we have not yet set up the graphic to be used by |foo|. For this, we must use a key called |set foo graphic| or, generally, |set| \meta{name} |graphic|. This key gets graphic options as parameter that will be set when a symbol |foo| should be shown: @@ -388,7 +387,7 @@ annotation as a parameter to the symbol as in the following example: \item The |inner sep| is set to |0.5pt|. \item The following style is executed: \begin{stylekey}{/tikz/every circuit symbol} - Use this style to setup things in general. + Use this style to set up things in general. \end{stylekey} \item The graphic options that have been set using |set| \meta{name} |graphic| are set. @@ -434,9 +433,9 @@ annotation as a parameter to the symbol as in the following example: \item This node gets \meta{options} as its option list. \item The node is added by virtue of a special |markings| decoration. This means that a |mark| command is executed that - causes the node to placed as a mark on the path. + causes the node to be placed as a mark on the path. \item The marking decoration will automatically subdivide the path - and cause a line to be drawn to from the start of the path to the + and cause a line to be drawn from the start of the path to the node's border (at the position that lies on a line from the node's center to the start of the path) and then from the node's border (at a position on the other side of the node) to the end of the @@ -484,7 +483,7 @@ rotated. There are two ways of achieving such rotations: \begin{enumerate} \item When you place a symbol on a |to| path, the graphic symbol is automatically rotated such that it ``points along the path.'' Here - is an examples that show how the inductor shape (which looks, + is an examples that shows how the inductor shape (which looks, unrotated, like this: \tikz[circuit ee IEC]\node[inductor]{};) is automatically rotated around: \begin{codeexample}[] @@ -529,10 +528,10 @@ rotated. There are two ways of achieving such rotations: Info labels are used to add text to a circuit symbol. Unlike normal nodes like a rectangle, circuit symbols typically do not have text ``on'' them, but the text is placed next to them (like the text -``$3\Omega$'' next to a resistor). +``$3\,\Omega$'' next to a resistor). \tikzname\ already provides the |label| option for this purpose. The -|info| option is build on top of this option, but it comes in some +|info| option is built on top of this option, but it comes in some predefined variants that are especially useful in conjunction with circuits. @@ -773,7 +772,7 @@ in several ways: black rectangle. \end{stylekey} \begin{stylekey}{/tikz/circuit symbol lines (initially draw)} - This style is used with symbols that consist only of lines the do + This style is used with symbols that consist only of lines that do not surround anything. Examples are a capacitor. \begin{codeexample}[] \tikz [circuit ee IEC, @@ -805,7 +804,7 @@ in several ways: \end{itemize} All circuit environments like |circuit logic IEC| mainly use options -like |set and gate graphic=...| to setup the graphics used for a certain +like |set and gate graphic=...| to set up the graphics used for a certain symbol. It turns out that graphic hidden in the ``|...|'' part is also always available as a separate style, whose name contains the library's initials. For instance, the |circuit logic IEC| option @@ -857,7 +856,7 @@ saying |set resistor graphic| yourself: \subsubsection{Overview} A \emph{logical circuit} is a circuit that contains what we call -\emph{logical gates} like an and-gate or an xor-gate. The logical +\emph{logical gates} like an |and gate| or an |xor gate|. The logical libraries are intended to make it easy to draw such circuits. In the following, we first have a look at the different libraries that @@ -898,7 +897,7 @@ you need to use one of the following libraries, instead: This library provides graphics based on gates recommended by the International Electrotechnical Commission. When you include this library, you can use the following key to - setup a scope that contains a logical circuit where the gates are + set up a scope that contains a logical circuit where the gates are shown in this style. \begin{key}{/tikz/circuit logic IEC} @@ -991,7 +990,7 @@ one of them, all the other work the same way: \begin{key}{/tikz/and gate} This key should be passed to a |node| command. It will cause the - node to ``look like'' an and-gate, where the exact appearance of the + node to ``look like'' an |and gate|, where the exact appearance of the gate is dictated by the which circuit environment is used. To further configure the appearance of the |and gate|, see Section~\ref{section-theming-symbols}. @@ -1011,7 +1010,7 @@ one of them, all the other work the same way: Multiple inputs can be specified for a logic gate (provided they support multiple inputs: a not gate---also known as an inverter---does not). However, there is an upper limit for the - number of inputs which has been set at 1024, which should be \emph{way} + number of inputs which has been set to 1024, which should be \emph{way} more than would ever be needed. The following key is used to configure the inputs. It is available @@ -1273,6 +1272,9 @@ centers of the inputs can be customized using the following keys: node[\placement] {\scriptsize\texttt{(s.\anchor)}}; \end{tikzpicture} \end{codeexample} + + (For the definition of the |shape example| style, see + Section~\ref{section-libs-shapes}.) \end{shape} \end{pgflibrary} @@ -1330,7 +1332,7 @@ centers of the inputs can be customized using the following keys: Set the symbol for the |xor gate|. Note the necessity for braces, as the symbol contains |=|. In \tikzname, when the |use IEC style logic gates| key has been - used, this key can be replaced by |or gate symbol|. + used, this key can be replaced by |xor gate symbol|. \end{key} \begin{key}{/pgf/xnor gate IEC symbol=\meta{text} (initially \char`\{\char`\$=1\char`\$\char`\})} @@ -1399,7 +1401,7 @@ centers of the inputs can be customized using the following keys: This shape is a nand gate. It supports two or more inputs. If less than two inputs are specified an error will result. The anchors for this gate with two - non-inverted inputs are + inverted inputs are shown below. Anchor |30| is an example of a border anchor. \begin{codeexample}[] @@ -1441,7 +1443,7 @@ Just as for logical gates, there are different ways of drawing ee-symbols. Currently, there is one main library for drawing circuits, which uses the graphics from the International Electrotechnical Commission, but you can add your own libs. This is why, just as for -logical gates, there are a base library and more specific libraries. +logical gates, there is a base library and more specific libraries. \begin{tikzlibrary}{circuits.ee} This library declares the ee symbols, but (mostly) does not @@ -1473,7 +1475,7 @@ include |circuits.ee.IEC|. Inside the |circuit ee IEC| scope, you can now use the keys for symbols, units, and annotations listed in the later sections. We have -a more detailed look at one of each of them, all the other work the +a more detailed look at one of each of them, all the others work the same way. Let us start with an example of a symbol: the resistor symbol. The @@ -1555,8 +1557,8 @@ Section~\ref{section-circuits-ee-symbols} and later sections. \medskip\textbf{Inputs, Outputs, and Anchors.} Like the logical gates, all ee-symbols have an |input| - and an |output| anchor. Special purpose nodes may have even more - anchors of this type. Furthermore, the ee-symbols nodes also for + and an |output| anchor. Special-purpose-nodes may have even more + anchors of this type. Furthermore, the ee-symbols-nodes also have four standard compass direction anchors. \medskip\textbf{Changing the Appearance.} @@ -1866,23 +1868,23 @@ directly. happen: \begin{enumerate} \item The size of the shape is computed according to the following - rules: The width of the shape is setup so that the left border of + rules: The width of the shape is set up so that the left border of the shape is at the left end of the arrow tip and the right border is at the right end of the arrow tip. These left and right - ``ends'' of the arrow are the left and right extends specified by + ``ends'' of the arrow are the left and right extents specified by the arrow itself (see the documentation of the |\pgfarrowsdeclare| for details). You usually need not worry about this width setting. - By comparison, the height of the arrow is given my the current - setting of |minimum height|. Thus, this key must have been setup + By comparison, the height of the arrow is given by the current + setting of |minimum height|. Thus, this key must have been set up correctly to reflect the ``real'' height of the arrow tip. The reason is that the height of an arrow is not specified when arrows are declared and is, thus, not available, here. Possibly, the height computation will change in the future to reflect the real height of the arrow, so you should generally - setup the |minimum height| to be the same as the real height. + set up the |minimum height| to be the same as the real height. \item A straight line from left to right inside the shape's boundaries is added to the background path. \item The arrow tip, pointing right, is drawn before the background @@ -1930,7 +1932,7 @@ directly. \begin{shape}{generic circle IEC} This shape inherits from |circle ee|, which in turn is just a normal |circle| with additional |input| and |output| anchors at the left - and right ends. However, additionally, this shapes allows you to + and right ends. However, additionally, this shape allows you to specify a path that should be added before the background path using the following key: \begin{key}{/pgf/generic circle IEC/before background=\meta{code}} @@ -1963,7 +1965,7 @@ directly. \begin{shape}{generic diode IEC} This shape is used to depict diodes. The main shape is taken up by a - ``right pointing'' triangle. The anchors are positioned on border of + ``right pointing'' triangle. The anchors are positioned on the border of a rectangle around the diode, see the below example. The diode's size is based on the current settings of |minimum width| and |minimum height|. @@ -2036,7 +2038,7 @@ directly. This shape is used to depict a variant version of a resistor. Its size is computed as for a rectangle (thus, its size depends things like the |minimum height|). Then, inside this rectangle, a - background path is setup according to the following rule: Starting + background path is set up according to the following rule: Starting from the left end, zigzag segments are added to the path. Each segment consists of a line at a 45 degree angle going up to the top of the rectangle, then going down to the bottom, then going up to @@ -2109,7 +2111,7 @@ directly. \end{shape} \begin{shape}{battery IEC} - This shape is similar to a |capacitor IEC|, only the right line is + This shape is similar to a |capacitor IEC|, however, the right line is only half the height of the left line. \begin{codeexample}[] \tikz \node[shape=battery IEC,shape example,minimum size=2cm, diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex index bb0e6cadad9..4496bc06f4d 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex @@ -1,4 +1,4 @@ -% Copyright 2008 by Mark Wibrow +% Copyright 2013 by Mark Wibrow and Till Tantau % % This file may be distributed and/or modified % @@ -40,27 +40,27 @@ stored in \TeX\ dimension registers while others are stored in macros. value of |2.5pt| means that deforming decorations should deform a path by up to 2.5pt away from the original path. - This key set the \TeX-dimension |\pgfdecorationsegmentamplitude|. + This key sets the \TeX-dimension |\pgfdecorationsegmentamplitude|. \end{key} \begin{key}{/pgf/decoration/meta-amplitude=\meta{dimension} (initially 2.5pt)} This key determines the amplitude for a meta-decoration. - The key set the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|. + The key sets the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|. \end{key} \begin{key}{/pgf/decoration/segment length=\meta{dimension} (initially 10pt)} Many decorations are made up of small segments. This key determines the desired length of such segments. - This key set the \TeX-dimension |\pgfdecorationsegmentlength|. + This key sets the \TeX-dimension |\pgfdecorationsegmentlength|. \end{key} \begin{key}{/pgf/decoration/meta-segment length=\meta{dimension} (initially 1cm)} This determined the length of the meta-segments from which a meta-decoration is made up. - This key set the \TeX-macro (!) |\pgfmetadecorationsegmentlength|. + This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|. \end{key} \begin{key}{/pgf/decoration/angle=\meta{degree} (initially 45)} @@ -68,7 +68,7 @@ stored in \TeX\ dimension registers while others are stored in macros. instance, a |wave| decoration consists of arcs and the opening angle of these arcs is given by the |angle|. - This key set the \TeX-macro |\pgfdecorationsegmentangle|. + This key sets the \TeX-macro |\pgfdecorationsegmentangle|. \end{key} \begin{key}{/pgf/decoration/aspect=\meta{factor} (initially 0.5)} @@ -76,7 +76,7 @@ stored in \TeX\ dimension registers while others are stored in macros. for a |brace| decoration the aspect ratio determines where the brace point will be. - This key set the \TeX-macro |\pgfdecorationsegmentaspect|. + This key sets the \TeX-macro |\pgfdecorationsegmentaspect|. \end{key} \begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)} @@ -86,7 +86,7 @@ stored in \TeX\ dimension registers while others are stored in macros. \end{key} \begin{key}{/pgf/decoration/end radius=\meta{dimension} (initially 2.5pt)} - For some decorations there is a natural radius (of some circle, presumably). + For some decorations there is a natural end radius (of some circle, presumably). This key stores the value directly inside the key. \end{key} @@ -111,13 +111,13 @@ stored in \TeX\ dimension registers while others are stored in macros. \subsection{Path Morphing Decorations} \begin{pgflibrary}{decorations.pathmorphing} - A \emph{path morphing decorations} ``morphs'' or ``deforms'' the + A \emph{path morphing decoration} ``morphs'' or ``deforms'' the to-be-decorated path. This means that what used to be a straight line might afterwards be a snaking curve and have bumps. However, a - line is still and a line and path deforming decorations do not + line is still a line and path deforming decorations do not change the number of subpaths. For instance, if the path used to - consist of two circles and an open arc, the path will after the - decoration process still consist of two closed subpath and one open + consist of two circles and an open arc, the path will, after the + decoration process, still consist of two closed subpaths and one open subpath. \end{pgflibrary} @@ -138,7 +138,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=lineto] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -152,18 +152,18 @@ the paths. the decoration: \begin{itemize} \item |amplitude| - determines how much the zigzag lines raises above and falls below + determines how much the zigzag line raises above and falls below a straight line to the target point. \item |segment length| determines the length of a complete ``up-down'' cycle. - \item |meta-segment length| + \item |meta-segment length| determines the length of the |curveto| and the |zigzag| decorations. \end{itemize} \begin{codeexample}[] \begin{tikzpicture}[decoration={straight zigzag,meta-segment length=1.1cm}] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -186,7 +186,7 @@ the paths. \begin{tikzpicture} [decoration={random steps,segment length=2mm}] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -205,7 +205,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=saw] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -217,7 +217,7 @@ the paths. influence the decoration: \begin{itemize} \item |amplitude| - determines how much the zigzag lines raises above and falls below + determines how much the zigzag line raises above and falls below a straight line to the target point. \item |segment length| determines the length of a complete ``up-down'' cycle. @@ -225,7 +225,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=zigzag] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -237,13 +237,13 @@ the paths. \begin{decoration}{bent} This decoration adds a slightly bent line from the start to the - target. The amplitude of the bent is given |amplitude| + target. The amplitude of the bend is given |amplitude| (an amplitude of zero gives a straight line). \begin{itemize} \item |amplitude| - determines the amplitude of the bent. + determines the amplitude of the bend. \item |aspect| - determines how tight the bent is. A good value is around |0.3|. + determines how tight the bend is. A good value is around |0.3|. \end{itemize} Note that this decoration makes only little sense for curves. You should apply it only to straight lines. @@ -255,7 +255,7 @@ the paths. \end{codeexample} \begin{codeexample}[] \begin{tikzpicture}[decoration={bent,aspect=.3}] - \draw [decorate,fill=examplefill] (0,0) rectangle (3.5,2); + \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2); \node[circle,draw] (A) at (.5,.5) {A}; \node[circle,draw] (B) at (3,1.5) {B}; \draw[->,decorate] (A) -- (B); @@ -277,7 +277,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=bumps] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -307,7 +307,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=coil] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -315,7 +315,7 @@ the paths. \begin{tikzpicture} [decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -338,7 +338,7 @@ the paths. \begin{codeexample}[] \begin{tikzpicture}[decoration=curveto] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -355,12 +355,12 @@ the paths. \item |amplitude| determines the sine wave's amplitude. \item |segment length| - determines the sine wave's wave length. + determines the sine wave's wavelength. \end{itemize} \begin{codeexample}[] \begin{tikzpicture}[decoration=snake] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle; \end{tikzpicture} \end{codeexample} @@ -382,9 +382,9 @@ the paths. \end{pgflibrary} \begin{decoration}{border} - This decoration adds straight lines the path that are at a specific + This decoration adds straight lines to the path that are at a specific angle to the line toward the target. The idea is to add these little - lines to indicate the ``border'' or an area. The following + lines to indicate the ``border'' of an area. The following parameters influence the decoration: \begin{itemize} \item |segment length| @@ -499,11 +499,11 @@ the paths. \begin{decoration}{show path construction} - This decoration allows ``something different'' to be done - for each \emph{type} of input segment (i.e., moveto, lineto, - curveto or closepath). Typically, each segment will be replaced - with another path, but this need not necessarily be the case. - + This decoration allows ``something different'' to be done + for each \emph{type} of input segment (i.e., moveto, lineto, + curveto or closepath). Typically, each segment will be replaced + with another path, but this need not necessarily be the case. + \begin{codeexample}[] \begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny}, decoration={show path construction, @@ -533,10 +533,10 @@ the paths. for each type of input segment. \begin{key}{/pgf/decoration/moveto code=\meta{code} (initially \char`\{\char`\})} - Set the code to be executed for every moveto input segment. - It is important to remember that the transformations applied - by the decoration automaton are turned \emph{off} when \meta{code} - is executed. + Set the code to be executed for every moveto input segment. + It is important to remember that the transformations applied + by the decoration automaton are turned \emph{off} when \meta{code} + is executed. \end{key} \begin{key}{/pgf/decoration/lineto code=\meta{code} (initially \char`\{\char`\})} @@ -544,7 +544,7 @@ the paths. \end{key} \begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})} - Set the code to be executed for every curveto input segment. + Set the code to be executed for every curveto input segment. \end{key} \begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})} @@ -563,19 +563,19 @@ In \tikzname, you can use the following macros inside a \tikzname{} coordinate. \begin{command}{\tikzinputsegmentfirst} - The first point on the current input segment path. + The first point on the current input segment path. \end{command} \begin{command}{\tikzinputsegmentlast} - The last point on the current input segment path. + The last point on the current input segment path. \end{command} \begin{command}{\tikzinputsegmentsupporta} - The first support on the curveto input segment path. + The first support on the curveto input segment path. \end{command} \begin{command}{\tikzinputsegmentsupportb} - The second support on the curveto input segment path. + The second support on the curveto input segment path. \end{command} {\tikzexternaldisable @@ -585,7 +585,7 @@ inside a \tikzname{} coordinate. decoration={ show path construction, curveto code={ - \draw [blue, dashed] + \draw [blue, dashed] (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta) node [at end, cross out, draw, solid, red, inner sep=2pt]{}; \draw [blue, dashed] @@ -693,8 +693,8 @@ a path. We start with the most general and most useful of these libraries. \end{codeexample} The |mark| decoration option is used to specify a marking. It comes - in two version: - \begin{key}{/pgf/decoration/mark=|at position| + in two versions: + \begin{key}{/pgf/decoration/mark=\texttt{at position} \meta{pos}| with |\meta{code}} The options specifies that when a |marking| decoration is applied, there should be a marking at position \meta{pos} on the path whose @@ -704,10 +704,10 @@ a path. We start with the most general and most useful of these libraries. \begin{enumerate} \item It can be a non-negative dimension like |0pt| or |2cm| or |5cm/2|. In this case, it refers to the position along the path - that is this far removed from the start. + that is this far displaced from the start. \item It can be a negative dimension like |-1cm-2pt| or |-1sp|. In this case, the position is taken from the end of the path. Thus, - |-1cm| is the position that is $-1$cm removed from the end of + |-1cm| is the position that is $-1$cm displaced from the end of the path. \item It can be a dimensionless non-negative number like |1/2| or |0.333+2*0.1|. In this case, the \meta{pos} is interpreted as a @@ -722,7 +722,7 @@ a path. We start with the most general and most useful of these libraries. is applied, the (high level) coordinate system will have been transformed so that the origin lies at this position and the positive $x$-axis points along the path. For this coordinate - system, the \meta{code} is executed. It can contains all sorts of + system, the \meta{code} is executed. It can contain all sorts of graphic drawing commands, including (even named) nodes. If the position lies past the end of the path (for @@ -767,8 +767,8 @@ a path. We start with the most general and most useful of these libraries. \end{tikzpicture} \end{codeexample} - When the \meta{code} is begin executed, two special keys will have - been setup, whose value may be of interest: + When the \meta{code} is being executed, two special keys will have + been set up, whose value may be of interest: \begin{key}{/pgf/decoration/mark info/sequence number} This key can only be read. Its value (which can be obtained using the |\pgfkeysvalueof| command) is a ``sequence number'' of @@ -825,6 +825,7 @@ a path. We start with the most general and most useful of these libraries. Using the key |sequence number| we can also ``number'' the nodes and even refer to them later on. + % FIXME : the automatic key highlighting fails here! \begin{codeexample}[] \begin{tikzpicture}[decoration={markings, mark=between positions 0 and 1 step 1cm with { @@ -869,9 +870,9 @@ a path. We start with the most general and most useful of these libraries. path. However, this is no longer the case when the following key is set: \begin{key}{/pgf/decoration/mark connection node=\meta{node name} (initially empty)} - When this key is set to a nonempty \meta{node name} while the + When this key is set to a non-empty \meta{node name} while the decoration is being processed, the following happens: The marking - code should, among possibly other things, define node named + code should, among possibly other things, define a node named \meta{node name}. Then, the output path of this decoration will contain a line-to to ``one end'' of this node, followed by a moveto to the ``other end'' of the node. More precisely, the first @@ -914,7 +915,7 @@ a path. We start with the most general and most useful of these libraries. Frequent markings that are hard to create correctly are arrow tips. For them, two special commands are available when the \meta{code} of -a |mark| option is execute. (They are only defined in this code): +a |mark| option is executed. (They are only defined in this code): \begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}} This command simply draws the \meta{arrow end tip} at the origin, @@ -1001,7 +1002,7 @@ a |mark| option is execute. (They are only defined in this code): \end{codeexample} \end{key} \begin{key}{/pgf/decoration/foot angle (initially 10)} - Footprints are rotate by this much. + Footprints are rotated by this much. \begin{codeexample}[] \begin{tikzpicture}[decoration={footprints,foot angle=60}] \fill [decorate] (0,0) -- (3,0); @@ -1086,7 +1087,7 @@ reasons, using the |markings| library is usually preferable. \item |segment length| determines the distance between consecutive triangles. \item |shape height| - determines height of the triangle side that is orthogonal + determines the height of the triangle side that is orthogonal to the path. \item |shape width| determines the width of the triangle. @@ -1094,7 +1095,7 @@ reasons, using the |markings| library is usually preferable. \begin{codeexample}[] \begin{tikzpicture}[decoration=triangles] \draw [help lines] grid (3,2); - \draw [decorate,fill=examplefill] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1); \end{tikzpicture} \end{codeexample} \end{decoration} @@ -1103,14 +1104,14 @@ reasons, using the |markings| library is usually preferable. \begin{decoration}{shape backgrounds} This is a general decoration that replaces the to-be-decorated path by repeated copies of the background path of an arbitrary shape that has - previously defined using the |\pgfdeclareshape| command (that is, + previously been defined using the |\pgfdeclareshape| command (that is, you can use any shape in the shape libraries). Please note that the background path of the shapes is used, but \emph{no nodes are created}. This means that \emph{you cannot have text inside the shapes of this path, you cannot name them, or refer to them.} Finally, this decoration \emph{will not work with - shapes that depend strongly of the size of the text box (like the + shapes that depend strongly on the size of the text box (like the arrow shapes).} If any of these restrictions pose a problem, use the |markings| library instead. @@ -1137,13 +1138,13 @@ reasons, using the |markings| library is usually preferable. |anchor| decoration option: \begin{key}{/pgf/decoration/anchor=\meta{anchor} (initially center)} - The anchor used to position the shapes backgrounds. + The anchor used to position the shape backgrounds. \end{key} A shape background path is added at the start point of the path and, if the distance between the shapes is appropriate, at the end point of the path. - + \begin{codeexample}[] \begin{tikzpicture}[decoration={ shape backgrounds,shape=regular polygon,shape size=4mm}] @@ -1190,10 +1191,10 @@ reasons, using the |markings| library is usually preferable. Set the spacing between the shapes on the decorations path. This can be just a distance on its own, but the additional keywords |between centers|, and |between borders| (which must be preceded by a - comma), specify that the distance is between the center anchors of + comma), specify that the distance is between the center anchors of the shapes or between the edges of the \emph{boundaries} of the shape borders. - + \begin{codeexample}[] \begin{tikzpicture}[ decoration={shape backgrounds,shape size=.5cm,shape=signal}, @@ -1202,7 +1203,7 @@ reasons, using the |markings| library is usually preferable. \draw [help lines] grid (3,2); \draw [paint=red, decoration={shape sep=.5cm}] (0,2) -- (3,2); - \draw [paint=green, decoration={shape sep={1cm, between center}}] + \draw [paint=green, decoration={shape sep={1cm, between centers}}] (0,1) -- (3,1); \draw [paint=blue, decoration={shape sep={1cm, between borders}}] (0,0) -- (3,0); @@ -1245,7 +1246,7 @@ reasons, using the |markings| library is usually preferable. By default, shapes are rotated to the slope of the decorations path. If \meta{boolean} is the value |false|, then this rotation is turned off. Internally this sets the \TeX-if |\ifpgfshapedecorationsloped| - appropriately. + accordingly. \begin{codeexample}[] \tikzset{ @@ -1263,11 +1264,11 @@ reasons, using the |markings| library is usually preferable. \end{codeexample} \end{key}% - It is possible to scale the width and height of the shapes across the + It is possible to scale the width and height of the shapes along the length of the decorations path. The shapes are scaled between the starting size and the ending size. The following keys customize the way the decoration shapes are scaled: - + \begin{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)} \begin{codeexample}[] \tikzset{ @@ -1297,11 +1298,11 @@ reasons, using the |markings| library is usually preferable. \end{key}% \begin{stylekey}{/pgf/decoration/shape start size=\meta{length}} - Set both the start height and start width simultaneously. + Sets both the start height and start width simultaneously. \end{stylekey}% \begin{key}{/pgf/decoration/shape end width=\meta{length} (initially 2.5pt)} - The recommended ending width of the shape. Note, that this is the + The recommended ending width of the shape. Note that this is the width that a shape will take only if it is drawn exactly at the end of the path. @@ -1351,9 +1352,9 @@ reasons, using the |markings| library is usually preferable. This decoration decorates the path with text. This drawing of the text is a ``side effect'' of the decoration. The to-be-decorated path is only used to determine where the characters should be put - and it is thrown away after the decoration is done. This is why in - the following example no line is shown. - + and it is thrown away after the decoration is done. This is why no line is shown in + the following example. + \begin{codeexample}[] \catcode`\|12 \begin{tikzpicture}[decoration={text along path, @@ -1377,36 +1378,36 @@ reasons, using the |markings| library is usually preferable. transform key should be used. \item No attempt is made to ensure characters do not overlap when - the angle between segments is considerably less than 180\textdegree{} + the angle between segments is considerably less than 180$^\circ$ (this is tricky to do in \TeX{} without a huge processing overhead). In general this should not be too much of a problem, but, once again, kerning can be used in most cases to overcome any undesirable effects. - \item + \item It is only possible to typeset text in math mode under considerable - restrictions. Math mode is entered and exited using any character + restrictions. Math mode is entered and exited using any character of category code 3 (e.g., in plain \TeX{} this is |$|). %$ - Math subscripts and superscripts need to be contained within braces + Math subscripts and superscripts need to be contained within braces (e.g., |{^y_i}|) as do commands like |\times| or |\cdot|. - However, even modestly complex mathematical typesetting is unlikely + However, even modestly complex mathematical typesetting is unlikely to be successful along a path (or even desirable). \item Some inaccuracies in positioning may be particularly apparent at input segment boundaries. This can (unfortunately) only be solved - on case by case basis by individually kerning the offending + on a case-by-case basis by individually kerning the offending characters within a group. \end{itemize} The following keys are used by the |text| decoration: \begin{key}{/pgf/decoration/text=\meta{text} (initially \normalfont empty)} - Set the text to typeset along the curve. + Sets the text to typeset along the curve. Consecutive spaces are ignored, so |\ | (or |\space| in \LaTeX) - should be used to insert multiple spaces. It is possible to + should be used to insert multiple spaces. It is possible to format the text using normal formatting commands, such as |\it|, |\bf| and |\color|, within customizable delimiters. Initially these delimiters are both {\tt\char`\|} (however, care will be needed - regarding the category codes of delimiters --- see below). + regarding the category codes of delimiters --- see below). {\catcode`\|12 \begin{codeexample}[] @@ -1433,7 +1434,7 @@ reasons, using the |markings| library is usually preferable. \end{tikzpicture} \end{codeexample} } - + Internally, the text is stored in the macro |\pgfdecorationtext|. Any characters that have not been typeset when the end of the path has been reached will be stored in |\pgfdecorationrestoftext|. @@ -1444,15 +1445,15 @@ reasons, using the |markings| library is usually preferable. \begin{key}{/pgf/decoration/text format delimiters=\marg{before}\marg{after} (initially \char`\{|\char`\}\char`\{\char`\})} \catcode`\|13 - + Set the characters that the text decoration will use to parse formatting commands. If \meta{after} is empty, then \meta{before} will be used for both delimiters. - In general you should stick to characters whose category codes are + In general you should stick to characters whose category codes are |11| or |12|. As |+| is used to indicate that the specified format commands - are added to any existing ones, you should avoid using |+| as + are added to any existing ones, you should avoid using |+| as a delimiter. \begin{codeexample}[] @@ -1524,12 +1525,12 @@ reasons, using the |markings| library is usually preferable. \end{stylekey} \begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)} - Specify a distance which the automaton should move along + Specifies a distance which the automaton should move along before it starts typesetting the text. \end{key} \begin{key}{/pgf/decoration/text align/right indent=\meta{length} (initially 0pt)} - Specify a distance before the end of the path, where + Specifies a distance before the end of the path, where the automaton should stop typesetting the text. \end{key} @@ -1575,6 +1576,664 @@ reasons, using the |markings| library is usually preferable. +\begin{decoration}{text effects along path} + + This decoration is similar to the |text along path| decoration + except that each character is inserted into the picture + as a \tikzname\ node, and node options (such as |text|, |scale| and |opacity|) + can be used to create `text effects'. + +\begin{codeexample}[] +\bfseries\large +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, text align=center, + text effects/.cd, + character count=\i, character total=\n, + characters={evaluate={\c=\i/\n*100;}, text along path, text=red!\c!orange}, + character widths={text along path, xslant=0, yscale=1}}] + +\path [postaction={decorate}, preaction={decorate, + text effects={characters/.append={yscale=-1.5, opacity=0.5, + text=gray, xslant=(\i/\n-0.5)*3}}}] + (0,0) .. controls ++(2,1) and ++(-2,-1) .. (3,4); +\end{tikzpicture} +\end{codeexample} + + + There are some important differences between this decoration and the + |text along path| decoration: + + \begin{itemize} + \item + formatting (e.g., font and color) + cannot be specified in the decoration text. They can only be specified + using the keys described below. + \item + as a consequence of using the \tikzname\ node options, this + decoration is only available in \tikzname. + \item + due to the number of computations involved, this is + quite a slow decoration. + + \end{itemize} + + The following keys are shared with the |text along path| + decoration: + +\begin{key}{/pgf/decoration/text=\marg{text}} + + + Set the text this decoration will use. Braces can be + used to group multiple characters together, + or commands that should not be expanded until they are typset, for example + |gr{\"o}{\ss}eren|. You should \emph{not} use the formatting + delimiters or math mode characters + that the |text along path| decoration supports. + +\end{key} + + + +\begin{key}{/pgf/decoration/text align=\meta{align}} + + This sets the alignment of the text along the path. + The \meta{align} argument should be |left|, |right| or |center|. + Spreading the text out, or stretching the spaces between + words is \emph{not} supported. + +\end{key} + + The decoration text can be thought of as consisting + of \emph{characters} arranged in to sequences of \emph{letters} + to make \emph{words} which are separated by a \emph{word separator}. + This, however, does not mean that you are limited to using only + natural language as the decoration text. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={000-001-010-011-100-101-110-111}, + text effects/.cd, + path from text, + word separator=-, + every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} + + In addition, it is possible to replace characters + with \tikzname\ code: + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={000-001-010-011-100-101-110-111}, text align=center, + text effects/.cd, + word separator=-, + replace characters=0 with {\fill [purple] circle [radius=2pt]; }, + replace characters=1 with {\fill [orange] circle [radius=2pt]; }, + replace characters=- with {\path circle [radius=2pt]; }, + every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}] + +\path [decorate] (0,0) .. controls ++(2,0) and ++(-2,0) .. (3,4); +\end{tikzpicture} +\end{codeexample} + + + There are many keys and styles that can be used to add effects + to the decoration text. + Many of these keys have the parent path |/pgf/decoration/text effects/|, + but for convenience, these keys can be accessed using the following + key: + +\begin{key}{/tikz/text effects=\marg{options}} + + Execute every option in \marg{options} with the + key path for each option temporarily set to |/pgf/decoration/text effects/|. + +\end{key} + + + The following keys can be used to customise the + appearance of text in the |text effects along path| + decoration. + + + + +\begin{stylekey}{/pgf/decoration/text effects/every character} + + Set the effects that will be applied to + every character in the decoration text. The effects + will typically be \tikzname\ node options. + Initially, this style is empty so the decoration simply positions + nodes at the appropriate position along the path. In order to + make the text `follow the path' like the |text along path| decoration + the following key can be added to the |every character| style. + +\end{stylekey} + + +\begin{stylekey}{/pgf/decoration/text effects/text along path} + + This style automatically sets the \tikzname\ keys + |transform shape| (to make the character slope with the path), + |anchor=baseline| (to make the baseline of the characters `sit' on + the path) and |inner xsep=0pt| (to horizontally fit each node to the character + it contains, reducing the spacing between characters). + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}}] + +\path [draw=red, dotted, postaction={decorate}] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); +\path [draw=blue, dotted, yshift=1cm, postaction={decorate}, + text effects={text along path}] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); +\end{tikzpicture} +\end{codeexample} +\end{stylekey} + + +\begin{key}{/pgf/decoration/text effects/characters=\marg{effects}} + + Shorthand for the |every character|. + +\end{key} + +\begin{stylekey}{/pgf/decoration/text effects/character \meta{number}} + + Specify additional effects for the character \meta{number}. + +\end{stylekey} + + +\begin{stylekey}{/pgf/decoration/text effects/every letter} + + Specify additional effects for every letter (i.e., every character + that isn't the word separator) in the decoration text. + +\end{stylekey} + +\begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}} + + Specify the effects for letter \meta{number} in \emph{every} word. + +\end{stylekey} + + +\begin{stylekey}{/pgf/decoration/text effects/every first letter} + + Specify additional effects for the first letter in \emph{every} word. + +\end{stylekey} + + +\begin{stylekey}{/pgf/decoration/text effects/every last letter} + + Specify additional effects for the last letter in \emph{every} word. + +\end{stylekey} + + +\begin{stylekey}{/pgf/decoration/text effects/every word} + + Specify additional effects for every word in the decoration text. + +\end{stylekey} + + + +\begin{stylekey}{/pgf/decoration/text effects/word \meta{number}} + + Specify additional effects for word \meta{number} in the decoration text. + +\end{stylekey} + + + +\begin{stylekey}{/pgf/decoration/text effects/word \meta{m} letter \meta{n}} + + Specify additional effects for letter \meta{n} in word \meta{m} in the decoration text. + +\end{stylekey} + + + +\begin{stylekey}{/pgf/decoration/text effects/every word separator} + + Specify additional effects for every character that is a word separator. + +\end{stylekey} + + + +\begin{key}{/pgf/decoration/text effects/word separator=\meta{character} (initially space)} + + Specify the character that is to be used as the word separator. + This \emph{must} be a single character such as |a| or |-| or + the special value |space| (which should be used to indicate that + spaces should be used as the separator). + +\end{key} + + By default, the width for each character is calculated according + to the bounding box of the node in which it is contained. + However, if the node is rotated or slanted, or has a substantial + |inner sep|, this bounding box + will be quite big. The following key enables different effects + to be applied to the node that is used to calculate the + width. + + + + +\begin{stylekey}{/pgf/decoration/text effects/every character width} + + This style is appplied to the (invisible) nodes used for calculating + the width of a character node. + +\end{stylekey} + + + +\begin{key}{/pgf/decoration/text effects/character widths=\marg{effects}} + + Shorthand for the |every character width| style. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, text align=center, + text effects/.cd, + character count=\i, + characters={xslant=0.5, text along path, name=c-\i}}] + +\path [decorate] (0,0) -- (3,2); +\path [decorate, + text effects={character widths={inner xsep=0pt, xslant=0}}] + (0,1) -- (3,3); +\end{tikzpicture} +\end{codeexample} +\end{key} + + It is possible to parametrize effects, perhaps for doing + calculations, or labelling nodes based on the number of the + character in the decoration text. To access the number + of the character, and the total number of characters + the following keys can be used. + However, these keys should \emph{not} + be used inside the style keys given above. + +\begin{key}{/pgf/decoration/text effects/character count=\meta{macro}} + Store the number of the character being typeset in \meta{macro}. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, + character count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + +\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + +\begin{key}{/pgf/decoration/text effects/character total=\meta{macro}} + Store the total number of the characters in the decoration text + in \meta{macro}. + This key can be used with the |character count| key to produce + some quite pleasing effects: + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + character count=\i, character total=\n, + characters={text along path, evaluate={\c=\i/\n*100;}, + text=orange!\c!blue, scale=\i/\n+0.5}}] + +\path [decorate] + (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); +\end{tikzpicture} +\end{codeexample} + +\end{key} + +\begin{key}{/pgf/decoration/text effects/letter count=\meta{macro}} + + Store the number of letter being typeset (i.e., the position of the character + in the word) in \meta{macro}. Numbering starts at |1| and + the character acting as a word separator is numbered |0|. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, letter count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + +\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + +\begin{key}{/pgf/decoration/text/effetcs/letter total=\meta{macro}} + + Store the number of letters in the current word in \meta{macro}. + When the character is the word separator, this value is |0|. + +\end{key} + +\begin{key}{/pgf/decoration/text effects/word count=\meta{macro}} + Store the number of words in the decoration text in \meta{macro}. + Numbering starts at |1|. + When the character is the word separator, \meta{macro} + takes the number of the previous word. If the decoration text + starts with a word separator \meta{macro} will be |0|. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, word count=\i, every word separator/.style={fill=red!30}, + characters={text along path, shape=circle, fill=gray!50}}] + + \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0); +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/decoration/text effects/word total=\meta{macro}} + + Store the total number of words in the decoration text in \meta{macro}. + +\end{key} + + + It is also possible to apply effects to specific + characters such as coloring every instance of the + character |a|, + or changing the font of every |T| in the decoration text: + +\begin{key}{/pgf/decoration/text effects/style characters=\marg{characters} with \marg{effects}} + + This key enables \meta{effects} to be applied to every character + in the decoration text that is specified in \meta{characters}. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg}, + text effects/.cd, + path from text, + style characters=aeiou{\"U}{\"a}{\"o} with {text=blue}, + characters={text along path}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + +\begin{key}{/pgf/decoration/text effects/path from text=\opt{\marg{true or false}} (default true)} + When this key is set to |true| and the decorated path + consists only of a single point, the decoration will calculate + the width of the decoration text using all the specified parameters + as if the decorated path was actually a straight line + starting from the given point. This `virtual' + straight line is then decorated with the text. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + + +\begin{key}{/pgf/decoration/text effects/path from text angle=\meta{angle}} + + When used in conjunction with the |path from text| key, + the straight line that is used as the decorated path + is rotated by \meta{angle} around the starting point. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + +\begin{key}{/pgf/decoration/text effects/fit text to path=\opt{\meta{true or false}} (default true)} + + This key will make the decoration increase the space between + characters so that the entire path is used by the decoration. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/every character/.style={text along path}}] + +\path [draw=gray, postaction={decorate}, rotate=90] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); +\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm, + text effects={fit text to path}] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/decoration/text effects/scale text to path=\opt{\meta{true or false}} (default true)} + + This key will make the decoration scale the text + so that the entire path is used by the decoration. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/every character/.style={text along path}}] + +\path [draw=gray, postaction={decorate}, rotate=90] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); +\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm, + text effects={scale text to path}] + (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1); +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/decoration/text effects/reverse text} + + Reverse the order of the characters in the decoration text. + This may be useful if using `right-to-left` languages. + Unfortunately, any + leading `soft' spaces in the original text will be lost. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + reverse text, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + +\path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2); +\end{tikzpicture} +\end{codeexample} + + It is important to note that the |reverse text| key reverses the + text \emph{before} doing anything else. This means that the + numbering of characters, letters and words will still + still be in the normal order, so any parametrized effects + will have to take this into account. + Alternatively, to get the numbering + to follow the reversed text, it is possible to reverse the path and then + invert the scale: + +\begin{codeexample}[] + +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + +\path [decorate, text effects={reverse text}] (0,0); +\path [blue, decorate, decoration={reverse path}, + text effects={characters/.append={scale=-1}}] (1,0); +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/decoration/text effects/group letters} + + Group sequences of letters together so they are treated + as a single `character'. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + every word separator/.style={fill=none}, + character count=\i, character total=\n, + characters={text along path, fill=gray!50, scale=\i/\n+0.5}}] + +\path [decorate] (0,0); +\path [decorate, text effects={group letters, + characters/.append={fill=red!20}}] + (1,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + The order in which the |reverse text| and |group letters| keys + are applied is important: + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + every word separator/.style={fill=none}, + character count=\i, character total=\n, + characters={text along path, fill=gray!50, scale=\i/\n+0.5}}] + +\path [decorate, text effects={reverse text, group letters}] (0,0); +\path [decorate, text effects={group letters, reverse text, + characters/.append={fill=red!20}}] (1,0); +\end{tikzpicture} +\end{codeexample} + +\begin{key}{/pgf/decoration/text effects/repeat text=\opt{\meta{times}}} + + Usually, when the decoration runs out of text, it simply stops. + This key will make the decoration repeat the decoration text + for the specified number of \meta{times}. If no value is given + the text will be repeated until the path is finished. + There are two points to remember however. + Firstly the numbering of characters, letters and words + will be restarted each time the text is repeated. + Secondly, the options for alignment, scaling or fitting + the text to the path, fitting the path to the text, + and so on, are computed using the decoration text before the + decoration starts. If any of these options are given + the behaviour of the |repeat text| key is undefined, but + typically it will be ignored. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!\ }, + text effects/.cd, + repeat text, + character count=\m, character total=\n, + characters={text along path, scale=0.5+\m/\n/2}}] + +\path [draw=gray, ultra thin, postaction=decorate] + (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) }; +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/decoration/text effects/character command=\meta{macro}} + + This key specifies a command that is executed when + each character is placed in the node. The \meta{macro} should + be an ordinary \TeX\ macro which takes one argument. The + argument will be a macro which when expanded will + contain the current character. + +\begin{codeexample}[] +\def\mycommand#1{#1$_\n$} +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, group letters, + word count=\n, + every word/.style={character command=\mycommand}, + characters={text along path}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/decoration/text effects/replace characters=\meta{characters} with \marg{code}} + + Replace the node for each character in \meta{characters} with \meta{code}. + The \meta{code} can be thought of as describing + a little picture or marking which will be + used instead of the character node. + The origin will be the current point along the + decoration path. + Any transformations associated with + the \meta{characters} (e.g., applied with the |every character| + or |every letter| styles) will also be applied to \meta{code}. + +\begin{codeexample}[] +\begin{tikzpicture}[decoration={text effects along path, + text={text effects along path!}, + text effects/.cd, + path from text, path from text angle=60, + replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];}, + replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];}, + character count=\i, character total=\n, + characters={text along path, scale=\i/\n+0.5}}] + +\path [decorate] (0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} +\end{decoration} + + + \subsection{Fractal Decorations} \begin{pgflibrary}{decorations.fractals} @@ -1613,7 +2272,7 @@ reasons, using the |markings| library is usually preferable. \begin{decoration}{Koch snowflake} This decoration replaces a straight line by a ``line with a spike.'' - Koch's snowflake's Hausdorff dimension is $\log 4/\log 3$. + The Hausdorff dimension of Koch's snowflake's is $\log 4/\log 3$. \begin{codeexample}[] \begin{tikzpicture}[decoration=Koch snowflake] \draw decorate{ (0,0) -- (3,0) }; @@ -1625,7 +2284,7 @@ reasons, using the |markings| library is usually preferable. \end{decoration} \begin{decoration}{Cantor set} - This decoration replaces a straight line by a ``line with a whole in + This decoration replaces a straight line by a ``line with a gap in the middle.'' The Hausdorff dimension of the Cantor set is $\log 2/\log 3$. \begin{codeexample}[] diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-edges.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-edges.tex index 5a280cd94a9..3fbb14ca195 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-edges.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-edges.tex @@ -183,11 +183,11 @@ exact way this curve looks can be influenced via a number of options. \end{key} \begin{key}{/tikz/out looseness=\meta{number}} - specifies the looseness factor for the out distance only. + Specifies the looseness factor for the out distance only. \end{key} \begin{key}{/tikz/in looseness=\meta{number}} - specifies the looseness factor for the in distance only. + Specifies the looseness factor for the in distance only. \end{key} \begin{key}{/tikz/min distance=\meta{distance}} If the computed distance for the start and target coordinates are @@ -204,13 +204,13 @@ exact way this curve looks can be influenced via a number of options. The maximum distance set only for the start coordinate. \end{key} \begin{key}{/tikz/in min distance=\meta{distance}} - The min distance set only for the target coordinate. + The minimum distance set only for the target coordinate. \end{key} \begin{key}{/tikz/in max distance=\meta{distance}} - The max distance set only for the target coordinate. + The maximum distance set only for the target coordinate. \end{key} \begin{key}{/tikz/distance=\meta{distance}} - Set the min and max distance to the same value \meta{distance}. Note + Set the minimum and maximum distance to the same value \meta{distance}. Note that this causes any computed distance $d$ to be ignored and \meta{distance} to be used instead. \begin{codeexample}[] @@ -222,10 +222,10 @@ exact way this curve looks can be influenced via a number of options. \end{codeexample} \end{key} \begin{key}{/tikz/out distance=\meta{distance}} - Sets the min and max out distance. + Sets the minimum and maximum out distance. \end{key} \begin{key}{/tikz/in distance=\meta{distance}} - Sets the min and max in distance. + Sets the minimum and maximum in distance. \end{key} \begin{key}{/tikz/out control=\meta{coordinate}} This option causes the \meta{coordinate} to be used as the start diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-er.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-er.tex index 177a9611d39..c896037c584 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-er.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-er.tex @@ -16,7 +16,7 @@ \end{tikzlibrary} This library is intended to help you in creating E/R-diagrams. It defines -only very little new styles, but using these style |entity| instead of +only few new styles, but using the style |entity| instead of saying |rectangle,draw| makes the code more expressive. @@ -122,7 +122,7 @@ styles for entities. \begin{stylekey}{/tikz/every attribute} - This style is used with every (key) attribute. + This style is used with every attribute, and therefore also for every key attribute. \begin{codeexample}[] \begin{tikzpicture} [text depth=1pt, diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex index 7399ed6f185..7d2130b035b 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-external.tex @@ -41,7 +41,7 @@ The library always searches for the \emph{next} picture's end, |\end{tikzpicture Consider using the |\tikzexternaldisable| method in case you'd like to skip selected pictures which do not meet the requirements. \subsection{A Word About Con\TeX t And Plain \TeX} -Currently, the basic layer backend |\beginpgfgraphicnamed| $\dotsc$ |\endpgfgraphicnamed| relies on \LaTeX\ only, so externalization is only supported for \LaTeX\ yet. +Currently, the basic layer backend |\beginpgfgraphicnamed| $\dotsc$ |\endpgfgraphicnamed| relies on \LaTeX\ only, so externalization is currently only supported for \LaTeX. %The library comes in three different versions, one for \LaTeX, one for Con\TeX t and one for plain \TeX. For reasons of simplicity, examples in this manual only refer to \LaTeX\ (especially |pdflatex|). \subsection{Externalizing Graphics} @@ -70,7 +70,7 @@ A simple image is \tikz \fill (0,0) circle(5pt);. The method works as follows: if the document is typeset normally, the library searches for replacement images for every picture. Filenames are generated automatically in the default configuration. In our case, the two file names will be |main-figure0| and |main-figure1|. If they exist, those images are simply included and the pictures as such are not processed. If graphics files do not exist, steps are taken to generate the missing ones. Since (currently) only one output file can be set, each missing image needs to be generated by a separate run of \LaTeX\ in which the |\jobname| is set to the desired image file name. In the default configuration |mode=convert with system call|, these commands are issued automatically by using the |\write18| method to call system commands. It is also possible to output every required file name or to generate a |makefile|; users will need to issue the required commands manually (or with |make|). The probably most comfortable way is to use the default configuration with -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex -shell-escape main \end{codeexample} \noindent which authorizes |pdflatex| to call itself recursively to generate the images. When it finishes, all images are generated and the document already includes them. @@ -114,7 +114,7 @@ From this point on, successive runs of \LaTeX\ will use the final graphics files if and only if the current document has been typeset with |-shell-escape|\footnote{Note that this is always true for the default configuration. This security consideration applies mainly for \texttt{mode=list and make} which will also work \emph{without} shell escapes.}. For |eps| output, you can (and need to) use -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] \tikzset{external/system call={latex \tikzexternalcheckshellescape -halt-on-error -interaction=batchmode -jobname "\image" "\texsource"; dvips -o "\image".ps "\image".dvi}} @@ -128,11 +128,11 @@ From this point on, successive runs of \LaTeX\ will use the final graphics files \end{key} \subsubsection{Support for Labels and References In External Files} -The |external| library comes with extra support for |\label| and |\ref| (and other commands which usually store information in the |.aux| file) inside of external files. +The |external| library comes with extra support for |\label| and |\ref| (and other commands which usually store information in the |.aux| file) inside an external files. There are, however, some points which need your attention when you try to use \begin{enumerate} - \item[a)] |\ref| to something in the main document inside of an externalized graphics or + \item[a)] |\ref| to something in the main document inside an externalized graphics or \item[b)] |\label| in the externalized graphics which is referenced in the main document. \end{enumerate} @@ -142,9 +142,14 @@ Point b) is realized automatically by the external library. In detail, a |\label \begin{enumerate} \item The external graphics needs to be generated together with its |.dpth| (usually automatically by \tikzname). \item The main document includes the external graphics and copies the |.dpth| content into its main |.aux| file. - \item The main document needs to be translated one further time to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}. + \item The main document needs to be translated once again to re-read its |.aux| file\footnote{Note that it is not possible to activate the content of an auxiliary file after \texttt{\textbackslash begin\{document\}} in \LaTeX.}. \end{enumerate} There is just one special case: if a |\label|/|\ref| combination is realized itsself by a |tikzpicture| which should be externalized, you need to proceed as for case a) since |mode=convert with system call| can't handle that stuff on its own. Thus, |\label| works automatically, just translate the main document often enough. +\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)} + Allows to disable the feature. Disabling it will safe one |\newwrite| command, i.e.\ a write register. + + Also see the |disable dependency files| feature. +\end{key} @@ -204,7 +209,7 @@ A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/ \end{tikzpicture} \end{document} \end{codeexample} -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex -shell-escape main \end{codeexample} \end{command} @@ -276,6 +281,11 @@ pdflatex -shell-escape main \begin{command}{\tikzexternalfiledependsonfile\marg{external graphics}\marg{file name}} A variant of |\tikzpicturedependsonfile| which adds a dependency for an \meta{external graphics}. The argument \meta{external graphics} must be the path as it would have been generated by the external library, i.e.\ without file extension but including any prefixes. \end{command} +\begin{key}{/tikz/external/disable dependency files} + Allows to (irreversibly) disable the generation of file dependencies. Disabling it will safe one |\newwrite| command, i.e.\ a write register. Note that the write register is only allocated if the feature has been used at all. This key needs to be provided as argument to |\tikzexternalize| (or it needs to be set before calling |\tikzexternalize|). + + Also see the |aux in dpth| key. +\end{key} \begin{key}{/tikz/external/force remake=\marg{boolean} (default true)} A boolean which is used to customize the up-to-date checks of all following figures. Every up-to-date check will fail, resulting in automatic regeneration of every following figure. @@ -337,6 +347,25 @@ pdflatex -shell-escape main For \LaTeX, the feature lasts until the next |\end|\marg{$\cdot$} (this holds for every call to |\tikzset|). \end{key} +\begin{key}{/tikz/external/up to date check=\marg{choice} (initially md5)} + The |external| lib has to decide when some existing figure is up-to-date. In such a case, it can be used without remaking it. Outdated pictures will be remade. + + The key |up to date check| allows to choose among a couple of heuristics which are supposed to catch the most important reasons to remake a figure. + + The |up to date check| can be overrule by any of the |force remake| or |remake next| keys: if one of them is true, the figure is not up-to-date. + + The choice \declare{simple} is based on the existence of the file: the file is + up-to-date if and only if it exists. + + The choice \declare{md5} generates an MD5 checksum of the picture for which the up-to-date check is running. The MD5 is compared against the MD5 of the previous run, which, in turn, will be written into an extra file with the extension |.md5|. This file will be modified if and only if the MD5 comparison indicates a difference. The MD5 computation is based on the pdf\TeX\ method |\pdfmdfivesum|. If it is unavailable for some reason, the choice |diff| will be used instead. + + The choice \declare{diff} is the same as MD5 -- except that it compares the picture content as-is instead of a hash. The |.md5| file will be used to compare an old version with the current one -- but its content is some ``normalized'' version of the picture for internal use. + + \paragraph{Attention:} the content--based strategies |md5| and |diff| operate on the picture content -- and only on the picture content. Here, ``picture content'' only includes the top--level tokens; no expansion is applied and no included files are part of the strategies. If you change preamble styles, you have to rebuild the figures manually (for example by deleting the generated graphics files). If you have include files, consider using |\tikzpicturedependsonfile| and its variants. Since this key provides heuristics, you should always remake your figures before you finally publish your document. + + The |up to date check| is applied for |mode=convert with system call| and |mode=list and make|. +\end{key} + \begin{command}{\tikzexternaldisable} Allows to disable the complete externalization. While |export next| will still collect the contents of picture environments, this command uninstalls the hooks for the external library completely. Thus, nested picture environments or environments where |\end{tikzpicture}| is not directly reachable won't produce compilation failures -- although it is not possible to externalize them automatically. @@ -352,7 +381,7 @@ pdflatex -shell-escape main \begin{key}{/tikz/external/figure list=\marg{boolean} (initially true)} A boolean which configures whether a figure list shall be generated. A figure list is an output file named \marg{jobname}|.figlist| which is filled with file names of each figure, one per line. - This file is not used by \TeX\ anymore, its purpose is to issue the required conversion commands |pdflatex -jobname |\marg{picture file name} \marg{main file} manually (or in a script). See section~\ref{sec:external:detail} for the details about the expected system call (or activate |mode=convert with system call| and inspect you log file). + This file is not used by \TeX\ anymore, its purpose is to issue the required conversion commands |pdflatex -jobname |\marg{picture file name} \marg{main file} manually (or in a script). See section~\ref{sec:external:detail} for the details about the expected system call (or activate |mode=convert with system call| and inspect your log file). \begin{codeexample}[code only] \documentclass{article} @@ -386,11 +415,11 @@ A simple image is \tikz \fill (0,0) circle(5pt);. \end{document} \end{codeexample} -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex main \end{codeexample} generates |main.figlist| containing -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] figures/trees figures/simple figures/main-figure0 @@ -400,10 +429,11 @@ figures/main-figure0 \begin{key}{/tikz/external/mode=\marg{choice} (initially convert with system call)} Configures what to do with \tikzname\ pictures (unless we are currently externalizing one particular image, in that case, these modes are ignored). - The preconfigured mode |convert with system call| checks whether external graphics files are up-to-date and includes them if that is the case. Any picture which is not up-to-date will be generated automatically using a system call. The system call can be configured using the |system call| template. The up-to-date check is simple: if the file does not exist, it is not up-to-date. Furthermore, if one of the |force remake| or |remake next| keys is true, the figure is not up-to-date. In all other case, the file is considered to be up-to-date. As soon as |convert with system call| is set, the |figure list| will be disabled -- such a file is not required. In case you still need or want it, you can enable it after setting |mode|. + The preconfigured mode |convert with system call| checks whether external graphics files are up-to-date and includes them if that is the case. Any picture which is not up-to-date will be generated automatically using a system call. The system call can be configured using the |system call| template. The up-to-date check is applied according to the |up to date check| key. +As soon as |convert with system call| is set, the |figure list| will be disabled -- such a file is not required. In case you still need or want it, you can enable it after setting |mode|. Please note that system calls may be disabled for security reasons. For pdflatex, they can be enabled using -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex -shell-escape \end{codeexample} while other \TeX\ variants may need other switches. The feature is sometimes called |\write18|. @@ -417,7 +447,7 @@ pdflatex -shell-escape Mode |list only| skips every \tikzname\ picture; it only generates the file \marg{main file}|.figlist| containing file names for every picture, the contents of any picture environment is thrown away and a replacement text is shown. This implies |figure list=true|. See also the |list and make| mode which includes available graphics. The mode |list and make| is similar to |list only|: it generates the same file \marg{main file}|.figlist|, but any images which exist already are included as graphics instead of ignoring them. Furthermore, this mode generates an additional file: \marg{main file}.makefile. This allows to use a work flow like -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] % step 1: generate main.makefile: pdflatex main % step 2: generate ALL graphics on 2 processors: @@ -425,7 +455,7 @@ make -j 2 main.makefile % step 3: include the graphics: pdflatex main \end{codeexample} - \noindent This last make method is, however unnecessary: |list and make| just assumes that images are generated somehow (not necessarily with the generated makefile). The generated makefile allows parallel externalization of graphics on multi-core systems and it supports any file dependencies configured with |\tikzpicturedependsonfile|. Furthermore, it respects the |force remake| and |remake next| keys. + \noindent This last make method is optional: |list and make| just assumes that images are generated somehow (not necessarily with the generated makefile). The generated makefile allows parallel externalization of graphics on multi-core systems and it supports any file dependencies configured with |\tikzpicturedependsonfile|. Furthermore, it respects the |force remake| and |remake next| keys. \end{key} @@ -454,7 +484,7 @@ pdflatex main \begin{key}{/tikz/external/optimize command away=\meta{\textbackslash command}\marg{required argument count}} Installs commands to optimize \meta{\textbackslash command} away. As is described above, optimization applies to the case when single pictures are converted: one usually doesn't need to process (probably expensive) commands which do not contribute to the selected picture. - The argument \marg{required argument count} is either empty or a non-negativ integer between $0$ and $9$. It denotes the number of arguments which should be consumed after \meta{\textbackslash command}. In any case, one argument in square brackets after the command will be recognized as well. To be more precise, the following cases for arguments of \meta{\textbackslash command} are supported: + The argument \marg{required argument count} is either empty or a non-negative integer between $0$ and $9$. It denotes the number of arguments which should be consumed after \meta{\textbackslash command}. In any case, one argument in square brackets after the command will be recognized as well. To be more precise, the following cases for arguments of \meta{\textbackslash command} are supported: \begin{enumerate} \item If \marg{required argument count} is empty (the default), \meta{\textbackslash command} may take one optional argument in square brackets and one in curly braces (which is also optional). \item If \marg{required argument count} is not empty, \marg{\textbackslash command} may take one optional argument in square brackets. Furthermore, it expects exactly \marg{required argument count} following arguments. @@ -556,7 +586,7 @@ And this here: \myExpensiveMacro{Argument} also. The standard run |pdflatex |\meta{main document} causes the |external| library to check every occurrence of |\begin{tikzpicture}| and every |\tikz| shortcommand. If it finds a picture which shall be exported, it queries the respective file name and checks whether the file exists already. If so, it includes the external graphics. If not, it requires an externalization which can be done automatically (the default), semi--automatically (with |mode=list and make|) or manually (by issuing the requires system calls somehow). The library can detect whether it runs in ``conversion mode'', i.e.\ if it should only process a single image. To do so, it checks whether the internal macro \declareandlabel{\tikzexternalrealjob} exists. If so, its contents is assumed to be \meta{main document} (without the suffix |.tex|). Usually, this macro is set by the conversion system call, -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex -jobname "main-figure0" "\def\tikzexternalrealjob{main}\input{main}" \end{codeexample} \noindent where |main-figure0| is the picture we are currently externalizing and |main.tex| is the main document. @@ -565,7 +595,7 @@ As soon as ``conversion mode'' has been detected, \pgfname\ changes the output r Eventually, the call |\input{main}| returns and the picture is ready. From this point on, the external graphics will be used. There is another possibility to communicate \meta{main document} to the subprocess performing the externalization: namely to write `|\tikzexternalize{main}|' into the document. In this case, the conversion system call will be -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pdflatex -jobname "main-figure0" "main" \end{codeexample} \noindent and the contents of |\tikzexternalrealjob| is set automatically. This case is detected by |\tikzexternalize|, and the |system call| is updated automatically (by patching its |\texsource| template argument). It is not necessary to change the |system call| manually. @@ -577,7 +607,7 @@ The sequence in which system calls are performed and the decision whether they a \subsection{Using External Graphics Without \textmd{\pgfname}\ Installed} \label{section-libs-external-nopgf} Given that every picture has been exported correctly, one may want to compile a file without \pgfname\ and \tikzname\ installed. \tikzname\ comes with a minimal package which contains just enough commands to replace every |tikzpicture| environment and the |\tikz| short command with the appropriate external graphics. It can be found at -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] latex/pgf/utilities/tikzexternal.sty \end{codeexample} \noindent and needs to be used instead of |\usepackage{tikz}|. So, we uncomment |\usepackage{tikz}| and our example from the beginning becomes @@ -608,14 +638,14 @@ Furthermore, we might want to draw \tikz[baseline]\draw (0,-1) rectangle (1,1); \end{document} \end{codeexample} \noindent where the following files are necessary to compile the document: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] tikzexternal.sty main.tex main-figure0.pdf main-figure1.pdf main-figure2.pdf \end{codeexample} -\noindent If there are any `|.dpth|' files, for example |main-figure2.dpth|, these files are also required. They contain information for the \tikzname\ |baseline| option (or |\label|s inside of external graphics). +\noindent If there are any `|.dpth|' files, for example |main-figure2.dpth|, these files are also required. They contain information for the \tikzname\ |baseline| option (or |\label|s inside external graphics). Just copy the |.sty| file into the directory of your |main.tex| file and use it as part of your document. @@ -623,7 +653,7 @@ Please keep in mind, that only |tikzpicture| environments and |\tikz| short imag \paragraph{Attention:} Since the simple replacement |\usepackage{tikzexternal}| doesn't support the key--value interface, you \emph{need} to use |\tikzsetexternalprefix| instead of the |prefix| option and |\tikzsetfigurename| instead of the |figure name| option since |\tikzset| is not available in such a context. -\paragraph{Remark:} Some of the features of this library are mainly useful to improve the speed of successive document compilations. In other words: you can't use all features in this context, Keep it simple. +\paragraph{Remark:} Some of the features of this library are mainly useful to improve the speed of successive document compilations. In other words: you can't use all features in this context, keep it simple. \subsection{\eps\ Graphics Export} It is also possible to use \eps\ graphics instead of \pdf\ files. There are different ways to produce them, for example to use |pdflatex| and call |pdftops -eps |\marg{pdf file} \marg{eps file} afterwards. You could add this command to the |system call| option. @@ -655,11 +685,11 @@ The |external| library can be customized to export bitmap images -- with the hel } } \end{codeexample} -\noindent The example above defines a new style called `|png export|' which, when it is set with |\tikzset{png export}| somewhere in the document, modifies the configuration for both, file generation and file input. The file generation is modified by appending the ImageMagick command to |system call| (separated by `|;|' as usual on Linux). This is, in principle, enough to generate a |.png| file. The |include external| command is overwritten such that it uses the |.png| file instead of the |.pdf| file (which exists as well in the configuration above). But since a |.png| file can have a much higher resolution than the desired image dimensions, we have to add |width| and |height| explicitly. Usually, the |external| library does not provide size information (it is unnecessary for |.pdf| or |.eps| since these formats have their bounding box information). To enable size information, the style uses the |external info| key which, in turn, provides the |\pgfexternalwidth| and |\pgfexternalheight| commands. +\noindent The example above defines a new style called `|png export|' which, when it is set with |\tikzset{png export}| somewhere in the document, modifies the configuration for both file generation and file input. The file generation is modified by appending the ImageMagick command to |system call| (separated by `|;|' as usual on Linux). This is, in principle, enough to generate a |.png| file. The |include external| command is overwritten such that it uses the |.png| file instead of the |.pdf| file (which exists as well in the configuration above). But since a |.png| file can have a much higher resolution than the desired image dimensions, we have to add |width| and |height| explicitly. Usually, the |external| library does not provide size information (it is unnecessary for |.pdf| or |.eps| since these formats have their bounding box information). To enable size information, the style uses the |external info| key, which, in turn, provides the |\pgfexternalwidth| and |\pgfexternalheight| commands. -Now, we can use |\tikzset{png export}| either document--wide or just for one particular image. The configuration remains in effect until the end of the actual environment (or until the next closing curly brace `|}|'). +Now we can use |\tikzset{png export}| either document-wide or just for one particular image. The configuration remains in effect until the end of the current environment (or until the next closing curly brace `|}|'). -\begin{key}{/pgf/images/external info=\mchoice{true,false} (initially false)} +\begin{key}{/pgf/images/external info=\marg{boolean} (initially false)} If this key is activated, the size for any externalized image will be stored explicitly into the associated |.dpth| file. When the file is included by |\pgfincludeexternalgraphics| (or automatically by the |external| library), the width is available as \declareandlabel{\pgfexternalwidth} and the height as \declareandlabel{\pgfexternalheight}. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fit.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fit.tex index 5e0dab698db..2a521518498 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fit.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fit.tex @@ -23,19 +23,19 @@ When you load this library, the following options become available: \meta{coordinates or nodes} should be a sequence of \tikzname\ coordinates or node names, one directly after the other without commas (like with the |plot coordinates| path operation). Examples - as |(1,0) (2,2)| or |(a) (1,0) (b)|, where |a| and |b| are nodes. + are |(1,0) (2,2)| or |(a) (1,0) (b)|, where |a| and |b| are nodes. For this sequence of coordinates, a minimal bounding box is computed that encompasses all the listed \meta{coordinates or nodes}. For coordinates in the list, the bounding box is guaranteed to contain this coordinate, for nodes it is guaranteed to contain the |east|, |west|, |north| and |south| anchors of the node. In principle (the - details will be explained in a moment), things are now setup such + details will be explained in a moment), things are now set up such that the text box of the node will be exactly this bounding box. Here is an example: We fit several points in a rectangular node. By setting the |inner sep| to zero, we see exactly the text box of the - node. Then we fit these points again in circular node. Note how + node. Then we fit these points again in a circular node. Note how the circle encompasses exactly the same bounding box. \begin{codeexample}[] \begin{tikzpicture}[inner sep=0pt,thick, @@ -63,7 +63,7 @@ When you load this library, the following options become available: \begin{enumerate} \item A minimal bounding box containing all coordinates is computed. Note that if a coordinate like |(a)| is used that - contain a node name, this has the same effect as explicitly + contains a node name, this has the same effect as explicitly providing the |(a.north)| and |(a.south)| and |(a.west)| and |(a.east)|. If you wish to refer only to the center of the |a| node, use |(a.center)| instead. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex index 335bac3ed2d..1be2d41e7b8 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fixedpoint.tex @@ -13,7 +13,7 @@ \begin{pgflibrary}{fixedpointarithmetic} This library provides an interface to the \LaTeX{} package |fp| for fixed point arithmetic. In addition to loading this - library you must ensure |fp| is loaded otherwise errors + library you must ensure |fp| is loaded, otherwise errors will occur. \end{pgflibrary} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex index ce23c8a4026..93f832f826c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-folding.tex @@ -13,19 +13,45 @@ \label{section-calender-folding} \begin{tikzlibrary}{folding} - This library defines commands for creating paper folding - diagrams. Currently, it just contains a single command for creating - a single diagram, but that one is really useful for creating - calendars for your (real) desktop. + This library defines pic types for creating paper folding + diagrams. Many thanks to Nico van Cleemput for providing most of the + code. \end{tikzlibrary} -\begin{command}{\tikzfoldingdodecahedron|[|\meta{options}|];|} - This command draws a folding diagram for a dodecahedron. The syntax - is intended to remind of the |\path| command, but (currently) you - must specify the \meta{options} and nothing else may be specified - between the command name and the closing semicolon. +Here is a big example that produces a diagram for a calendar: + +\begin{codeexample}[leave comments] +\sffamily\scriptsize +\tikz \pic [ + transform shape, + every calendar/.style={ + at={(-8ex,4ex)}, + week list, + month label above centered, + month text=\bfseries\textcolor{red}{\%mt} \%y0, + if={(Sunday) [black!50]} + }, + folding line length=2.5cm, + face 1={ \calendar [dates=\the\year-01-01 to \the\year-01-last];}, + face 2={ \calendar [dates=\the\year-02-01 to \the\year-02-last];}, + face 3={ \calendar [dates=\the\year-03-01 to \the\year-03-last];}, + face 4={ \calendar [dates=\the\year-04-01 to \the\year-04-last];}, + face 5={ \calendar [dates=\the\year-05-01 to \the\year-05-last];}, + face 6={ \calendar [dates=\the\year-06-01 to \the\year-06-last];}, + face 7={ \calendar [dates=\the\year-07-01 to \the\year-07-last];}, + face 8={ \calendar [dates=\the\year-08-01 to \the\year-08-last];}, + face 9={ \calendar [dates=\the\year-09-01 to \the\year-09-last];}, + face 10={\calendar [dates=\the\year-10-01 to \the\year-10-last];}, + face 11={\calendar [dates=\the\year-11-01 to \the\year-11-last];}, + face 12={\calendar [dates=\the\year-12-01 to \the\year-12-last];} +] {dodecahedron folding}; +\end{codeexample} + +The foldings are sorted by number of faces. - The following keys may be used in the \meta{options}: +\begin{pictype}{tetrahedron folding}{} + This pic type draws a folding diagram for a tetrahedron. + The following keys influence the pic: \begin{key}{/tikz/folding line length=\meta{dimension}} Sets the length of the base line for folding. For the dodecahedron this is the length of all the sides of the pentagons. @@ -40,31 +66,22 @@ Same as |face 1|, but for the second face. \end{key} \begin{key}{/tikz/face 3=\meta{code}} - Same as |face 1|, but for the third face. \end{key} - There are further similar options, ending with the following: - \begin{key}{/tikz/face 12=\meta{code}} - Same as |face 1|, but for the last face. + \begin{key}{/tikz/face 4=\meta{code}} \end{key} + There are further similar options for more faces (for commands + shown later). Here is a simple example: \begin{codeexample}[] -\begin{tikzpicture}[transform shape] - \tikzfoldingdodecahedron - [folding line length=6mm, +\tikz \pic [ + transform shape, + folding line length=6mm, face 1={ \node[red] {1};}, face 2={ \node {2};}, face 3={ \node {3};}, - face 4={ \node {4};}, - face 5={ \node {5};}, - face 6={ \node {6};}, - face 7={ \node {7};}, - face 8={ \node {8};}, - face 9={ \node {9};}, - face 10={\node {10};}, - face 11={\node {11};}, - face 12={\node {12};}]; -\end{tikzpicture} + face 4={ \node {4};} +] {tetrahedron folding}; \end{codeexample} The appearance of the cut and folding lines can be influenced using @@ -76,47 +93,141 @@ Executed for every line that should be folded. \begin{codeexample}[] -\begin{tikzpicture}[every cut/.style=red,every fold/.style=dotted] - \tikzfoldingdodecahedron[folding line length=6mm]; -\end{tikzpicture} +\tikz \pic[ + every cut/.style=red, + every fold/.style=dotted, + folding line length=6mm +] { tetrahedron folding }; \end{codeexample} \end{stylekey} -\end{command} + + There is one style that is mainly useful for the present + documentation: + \begin{stylekey}{/tikz/numbered faces} + Sets |face |\meta{i} to |\node {|\meta{i}|};| for all~$i$. + \end{stylekey} + +\end{pictype} -Here is a big example that produces a diagram for a calendar: +\begin{pictype}{tetrahedron truncated folding}{} + A folding of a truncated tetrahedron. +\begin{codeexample}[width=5cm] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { tetrahedron truncated folding }; +\end{codeexample} +\end{pictype} -\begin{codeexample}[leave comments] -\sffamily\scriptsize -\begin{tikzpicture} - [transform shape, - every calendar/.style= - { - at={(-8ex,4ex)}, - week list, - month label above centered, - month text=\bfseries\textcolor{red}{\%mt} \%y0, - if={(Sunday) [black!50]} - }] - \tikzfoldingdodecahedron - [ - folding line length=2.5cm, - face 1={ \calendar [dates=\the\year-01-01 to \the\year-01-last];}, - face 2={ \calendar [dates=\the\year-02-01 to \the\year-02-last];}, - face 3={ \calendar [dates=\the\year-03-01 to \the\year-03-last];}, - face 4={ \calendar [dates=\the\year-04-01 to \the\year-04-last];}, - face 5={ \calendar [dates=\the\year-05-01 to \the\year-05-last];}, - face 6={ \calendar [dates=\the\year-06-01 to \the\year-06-last];}, - face 7={ \calendar [dates=\the\year-07-01 to \the\year-07-last];}, - face 8={ \calendar [dates=\the\year-08-01 to \the\year-08-last];}, - face 9={ \calendar [dates=\the\year-09-01 to \the\year-09-last];}, - face 10={\calendar [dates=\the\year-10-01 to \the\year-10-last];}, - face 11={\calendar [dates=\the\year-11-01 to \the\year-11-last];}, - face 12={\calendar [dates=\the\year-12-01 to \the\year-12-last];} - ]; -\end{tikzpicture} + +\begin{pictype}{cube folding}{} + A folding of a cube. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { cube folding }; \end{codeexample} +\end{pictype} + + +\begin{pictype}{cube truncated folding}{} + A folding of a truncated cube. +\begin{codeexample}[width=5cm] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { cube truncated folding }; +\end{codeexample} +\end{pictype} + +\begin{pictype}{octahedron folding}{} + A folding of an octahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { octahedron folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{octahedron folding}{} + A folding of a truncated octahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { octahedron truncated folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{dodecahedron folding}{} + A folding of a dodecahedron. + +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { dodecahedron folding }; +\end{codeexample} +\end{pictype} + +\begin{pictype}{dodecahedron' folding}{} + This is an alternative folding of a dodecahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { dodecahedron' folding }; +\end{codeexample} +\end{pictype} + + + + +\begin{pictype}{cuboctahedron folding}{} + A folding of a cuboctahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { cuboctahedron folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{cuboctahedron truncated folding}{} + A folding of a truncated cuboctahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { cuboctahedron truncated folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{icosahedron folding}{} + A folding of an icosahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { icosahedron folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{rhombicuboctahedron folding}{} + A folding of an rhombicuboctahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { rhombicuboctahedron folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{snub cube folding}{} + A folding of a snub cube. +\begin{codeexample}[width=5cm] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { snub cube folding }; +\end{codeexample} +\end{pictype} + + +\begin{pictype}{icosidodecahedron folding}{} + A folding of an icosidodecahedron. +\begin{codeexample}[] +\tikz \pic [folding line length=6mm, numbered faces, transform shape] + { icosidodecahedron folding }; +\end{codeexample} +\end{pictype} + %%% Local Variables: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex index 88784f3b9be..7177e771b95 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex @@ -18,23 +18,53 @@ \pgfkeys{/pgf/fpu} \begin{pgflibrary}{fpu} - The floating point unit (fpu) allows the full data range of scientific computing for use in \pgfname. Its core is the \pgfname\ math routines for mantissa operations, leading to a reasonable trade--of between speed and accuracy. It does not require any third--party packages or external programs. + The floating point unit (fpu) allows the full data range of + scientific computing for use in \pgfname. Its core is the \pgfname\ + math routines for mantissa operations, leading to a reasonable + trade--of between speed and accuracy. It does not require any + third--party packages or external programs. \end{pgflibrary} \subsection{Overview} -The fpu provides a replacement set of math commands which can be installed in isolated placed to achieve large data ranges at reasonable accuracy. It provides at least\footnote{To be more precise, the FPU's exponent is currently a 32 bit integer. That means it supports a significantly larger data range than an IEEE double precision number -- but if a future \TeX\ version may provide lowlevel access to doubles, this may change.} the IEEE double precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc, \pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than zero is $\pgfmathprintnumber{1e-324}$. The FPU's relative precision is at least $\pgfmathprintnumber{1e-4}$ although operations like addition have a relative precision of $\pgfmathprintnumber{1e-6}$. - -Note that the library has not really been tested together with any drawing operations. It should be used to work with arbitrary input data which is then transformed somehow into \pgfname\ precision. This, in turn, can be processed by \pgfname. +The fpu provides a replacement set of math commands which can be +installed in isolated placed to achieve large data ranges at +reasonable accuracy. It provides at least\footnote{To be more precise, + the FPU's exponent is currently a 32 bit integer. That means it + supports a significantly larger data range than an IEEE double + precision number -- but if a future \TeX\ version may provide + lowlevel access to doubles, this may change.} the IEEE double +precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc, +\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than +zero is $\pgfmathprintnumber{1e-324}$. The FPU's relative precision is +at least $\pgfmathprintnumber{1e-4}$ although operations like addition +have a relative precision of $\pgfmathprintnumber{1e-6}$. + +Note that the library has not really been tested together with any +drawing operations. It should be used to work with arbitrary input +data which is then transformed somehow into \pgfname\ precision. This, +in turn, can be processed by \pgfname. \subsection{Usage} \begin{key}{/pgf/fpu=\marg{boolean} (default true)} - This key installs or uninstalls the FPU. The installation exchanges any routines of the standard math parser with those of the FPU: |\pgfmathadd| will be replaced with |\pgfmathfloatadd| and so on. Furthermore, any number will be parsed with |\pgfmathfloatparsenumber|. + This key installs or uninstalls the FPU. The installation exchanges + any routines of the standard math parser with those of the FPU: + |\pgfmathadd| will be replaced with |\pgfmathfloatadd| and so + on. Furthermore, any number will be parsed with + |\pgfmathfloatparsenumber|. \begin{codeexample}[] \pgfkeys{/pgf/fpu} \pgfmathparse{1+1}\pgfmathresult \end{codeexample} -\noindent The FPU uses a lowlevel number representation consisting of flags, mantissa and exponent\footnote{Users should \emph{always} use high level routines to manipulate floating point numbers as the format may change in a future release.}. To avoid unnecessary format conversions, |\pgfmathresult| will usually contain such a cryptic number. Depending on the context, the result may need to be converted into something which is suitable for \pgfname\ processing (like coordinates) or may need to be typeset. The FPU provides such methods as well. + \noindent The FPU uses a lowlevel number representation consisting + of flags, mantissa and exponent\footnote{Users should \emph{always} + use high level routines to manipulate floating point numbers as + the format may change in a future release.}. To avoid unnecessary + format conversions, |\pgfmathresult| will usually contain such a + cryptic number. Depending on the context, the result may need to be + converted into something which is suitable for \pgfname\ processing + (like coordinates) or may need to be typeset. The FPU provides such + methods as well. %-------------------------------------------------- % \begin{codeexample}[] @@ -44,29 +74,40 @@ Note that the library has not really been tested together with any drawing opera % \end{codeexample} %-------------------------------------------------- - Use |fpu=false| to deactivate the FPU. This will restore any change. Please note that this is not necessary if the FPU is used inside of a \TeX\ group -- it will be deactivated afterwards anyway. + Use |fpu=false| to deactivate the FPU. This will restore any + change. Please note that this is not necessary if the FPU is used + inside of a \TeX\ group -- it will be deactivated afterwards + anyway. - It does not hurt to call |fpu=true| or |fpu=false| multiple times. + It does not hurt to call |fpu=true| or |fpu=false| multiple times. - Please note that if the |fixed point arithmetics| library of \pgfname\ will be activated after the FPU, the FPU will be deactivated automatically. + Please note that if the |fixed point arithmetics| library of + \pgfname\ will be activated after the FPU, the FPU will be + deactivated automatically. \end{key} \begin{key}{/pgf/fpu/output format=\mchoice{float,sci,fixed} (initially float)} - This key allows to change the number format in which the FPU assigns |\pgfmathresult|. - - The predefined choice |float| uses the low-level format used by the FPU. This is useful for further processing inside of any library. + This key allows to change the number format in which the FPU assigns + |\pgfmathresult|. + + The predefined choice |float| uses the low-level format used by the + FPU. This is useful for further processing inside of any library. \begin{codeexample}[] \pgfkeys{/pgf/fpu,/pgf/fpu/output format=float} \pgfmathparse{exp(50)*42}\pgfmathresult \end{codeexample} - The choice |sci| returns numbers in the format \meta{mantissa}|e|\meta{exponent}. It provides almost no computational overhead. + The choice |sci| returns numbers in the format + \meta{mantissa}|e|\meta{exponent}. It provides almost no + computational overhead. \begin{codeexample}[] \pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci} \pgfmathparse{4.22e-8^-2}\pgfmathresult \end{codeexample} - The choice |fixed| returns normal fixed point numbers and provides the highest compatibility with the \pgfname\ engine. It is activated automatically in case the FPU scales results. + The choice |fixed| returns normal fixed point numbers and provides + the highest compatibility with the \pgfname\ engine. It is activated + automatically in case the FPU scales results. \begin{codeexample}[] \pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed} \pgfmathparse{sqrt(1e-12)}\pgfmathresult @@ -74,48 +115,77 @@ Note that the library has not really been tested together with any drawing opera \end{key} \begin{key}{/pgf/fpu/scale results=\marg{scale}} - A feature which allows semi--automatic result scaling. Setting this key has two effects: first, the output format for \emph{any} computation will be set to |fixed| (assuming results will be processed by \pgfname's kernel). Second, any expression which starts with a star, |*|, will be multiplied with \marg{scale}. + A feature which allows semi-automatic result scaling. Setting this + key has two effects: first, the output format for \emph{any} + computation will be set to |fixed| (assuming results will be + processed by \pgfname's kernel). Second, any expression which starts + with a star, |*|, will be multiplied with \meta{scale}. \end{key} \begin{keylist}{ - /pgf/fpu/scale file plot x=\marg{scale},% - /pgf/fpu/scale file plot y=\marg{scale},% - /pgf/fpu/scale file plot z=\marg{scale}}% - These keys will patch \pgfname's |plot file| command to automatically scale single coordinates by \marg{scale}. - - The initial setting does not scale |plot file|. + /pgf/fpu/scale file plot x=\marg{scale},% + /pgf/fpu/scale file plot y=\marg{scale},% + /pgf/fpu/scale file plot z=\marg{scale}}% + These keys will patch \pgfname's |plot file| command to + automatically scale single coordinates by \meta{scale}. + + The initial setting does not scale |plot file|. \end{keylist} \begin{command}{\pgflibraryfpuifactive\marg{true-code}\marg{false-code}} - This command can be used to execute dependent on whether the FPU has been activated or not. + This command can be used to execute either \meta{true-code} or + \meta{false-code}, depending on whether the FPU has been activated + or not. \end{command} \subsection{Comparison to the fixed point arithmetics library} -There are other ways to increase the data range and/or the precision of \pgfname's math parser. One of them is the |fp| package, preferable combined with \pgfname's |fixed point arithmetic| library. The differences between the FPU and |fp| are: +There are other ways to increase the data range and/or the precision +of \pgfname's math parser. One of them is the |fp| package, preferable +combined with \pgfname's |fixed point arithmetic| library. The +differences between the FPU and |fp| are: \begin{itemize} - \item The FPU supports at least the complete IEEE double precision number range, while |fp| covers only numbers of magnitude $\pm\pgfmathprintnumber{1e17}$. - \item The FPU has a uniform relative precision of about 4--5 correct digits. The fixed point library has an absolute precision which may perform good in many cases -- but will fail at the ends of the data range (as every fixed point routines does). - \item The FPU has potential to be faster than |fp| as it has access to fast mantissa operations using \pgfname's math capabilities (which use \TeX\ registers). +\item The FPU supports at least the complete IEEE double precision + number range, while |fp| covers only numbers of magnitude + $\pm\pgfmathprintnumber{1e17}$. +\item The FPU has a uniform relative precision of about 4--5 correct + digits. The fixed point library has an absolute precision which may + perform good in many cases -- but will fail at the ends of the data + range (as every fixed point routines does). +\item The FPU has potential to be faster than |fp| as it has access to + fast mantissa operations using \pgfname's math capabilities (which + use \TeX\ registers). \end{itemize} \subsection{Command Reference and Programmer's Manual} \subsubsection{Creating and Converting Floats} \begin{command}{\pgfmathfloatparsenumber\marg{x}} - Reads a number of arbitrary magnitude and precision and stores its result into |\pgfmathresult| as floating point number $m \cdot 10^e$ with mantissa and exponent base~$10$. + Reads a number of arbitrary magnitude and precision and stores its + result into |\pgfmathresult| as floating point number $m \cdot 10^e$ + with mantissa and exponent base~$10$. - The algorithm and the storage format is purely text-based. The number is stored as a triple of flags, a positive mantissa and an exponent, such as + The algorithm and the storage format is purely text-based. The + number is stored as a triple of flags, a positive mantissa and an + exponent, such as \begin{codeexample}[] \pgfmathfloatparsenumber{2} \pgfmathresult \end{codeexample} - Please do not rely on the low-level representation here, use |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| if you want to work with these components. + Please do not rely on the low-level representation here, use + |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| + if you want to work with these components. - The flags encoded in |\pgfmathresult| are represented as a digit where `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands for a positive sign, `$2$' means a negative sign, `$3$' stands for `not a number', `$4$' means $+\infty$ and `$5$' stands for $-\infty$. + The flags encoded in |\pgfmathresult| are represented as a digit + where `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands + for a positive sign, `$2$' means a negative sign, `$3$' stands for + `not a number', `$4$' means $+\infty$ and `$5$' stands for + $-\infty$. - The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m < 10$. It always contains a period and at least one digit after the period. The exponent is an integer. + The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le + m < 10$. It always contains a period and at least one digit after + the period. The exponent is an integer. - Examples: + Examples: \begin{codeexample}[] \pgfmathfloatparsenumber{0} \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} @@ -151,31 +221,47 @@ Flags: \F; Mantissa \M; Exponent \E. \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} Flags: \F; Mantissa \M; Exponent \E. \end{codeexample} - The argument \marg{x} may be given in fixed point format or the scientific `e' (or `E') notation. The scientific notation does not necessarily need to be normalized. The supported exponent range is (currently) only limited by the \TeX-integer range (which uses 31 bit integer numbers). + The argument \meta{x} may be given in fixed point format or the + scientific ``e'' (or ``E'') notation. The scientific notation does not + necessarily need to be normalized. The supported exponent range is + (currently) only limited by the \TeX-integer range (which uses 31 + bit integer numbers). \end{command} \begin{key}{/pgf/fpu/handlers/empty number=\marg{input}\marg{unreadable part}} - This command key is invoked in case an empty string is parsed inside of |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement |\pgfmathresult| (in float!). + This command key is invoked in case an empty string is parsed inside + of |\pgfmathfloatparsenumber|. You can overwrite it to assign a + replacement |\pgfmathresult| (in float!). - The initial setting is to invoke |invalid number|, see below. + The initial setting is to invoke |invalid number|, see below. \end{key} \begin{key}{/pgf/fpu/handlers/invalid number=\marg{input}\marg{unreadable part}} - This command key is invoked in case an invalid string is parsed inside of |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement |\pgfmathresult| (in float!). + This command key is invoked in case an invalid string is parsed + inside of |\pgfmathfloatparsenumber|. You can overwrite it to assign + a replacement |\pgfmathresult| (in float!). - The initial setting is to generate an error message. + The initial setting is to generate an error message. \end{key} \begin{key}{/pgf/fpu/handlers/wrong lowlevel format=\marg{input}\marg{unreadable part}} - This command key is invoked whenever |\pgfmathfloattoregisters| or its variants encounter something which is no properly formatted lowlevel floating point number. As for |invalid number|, this key may assign a new |\pgfmathresult| (in floating point) which will be used instead of the offending \marg{input}. + This command key is invoked whenever |\pgfmathfloattoregisters| or + its variants encounter something which is not a properly formatted + lowlevel floating point number. As for |invalid number|, this key + may assign a new |\pgfmathresult| (in floating point) which will be + used instead of the offending \meta{input}. - The initial setting is to generate an error message. + The initial setting is to generate an error message. \end{key} \begin{command}{\pgfmathfloatqparsenumber\marg{x}} - The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking. + The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking. \end{command} \begin{command}{\pgfmathfloattofixed{\marg{x}}} - Converts a number in floating point representation to a fixed point number. It is a counterpart to |\pgfmathfloatparsenumber|. The algorithm is purely text based and defines |\pgfmathresult| as a string sequence which represents the floating point number \marg{x} as a fixed point number (of arbitrary precision). + Converts a number in floating point representation to a fixed point + number. It is a counterpart to |\pgfmathfloatparsenumber|. The + algorithm is purely text based and defines |\pgfmathresult| as a + string sequence which represents the floating point number \meta{x} + as a fixed point number (of arbitrary precision). \begin{codeexample}[] \pgfmathfloatparsenumber{0.00052} @@ -197,30 +283,35 @@ $\to$ \end{command} \begin{command}{\pgfmathfloattoint\marg{x}} - Converts a number from low-level floating point representation to an integer (by truncating the fractional part). + Converts a number from low-level floating point representation to an + integer (by truncating the fractional part). \begin{codeexample}[] \pgfmathfloatparsenumber{123456} \pgfmathfloattoint{\pgfmathresult} \pgfmathresult \end{codeexample} - See also |\pgfmathfloatint| which returns the result as float. +See also |\pgfmathfloatint| which returns the result as float. \end{command} \begin{command}{\pgfmathfloattosci\marg{float}} - Converts a number from low-level floating point representation to scientific format, $1.234e4$. The result will be assigned to the macro |\pgfmathresult|. + Converts a number from low-level floating point representation to + scientific format, $1.234e4$. The result will be assigned to the + macro |\pgfmathresult|. \end{command} + \begin{command}{\pgfmathfloatvalueof\marg{float}} - Expands a number from low-level floating point representation to scientific format, $1.234e4$. + Expands a number from low-level floating point representation to + scientific format, $1.234e4$. - Use |\pgfmathfloatvalueof| in contexts where only expandable macros are allowed. + Use |\pgfmathfloatvalueof| in contexts where only expandable macros are allowed. \end{command} \begin{command}{\pgfmathfloatcreate{\marg{flags}}{\marg{mantissa}}{\marg{exponent}}} - Defines |\pgfmathresult| as the floating point number encoded by - \marg{flags}, \marg{mantissa} and \marg{exponent}. + Defines |\pgfmathresult| as the floating point number encoded by + \meta{flags}, \meta{mantissa} and \meta{exponent}. - All arguments are characters and will be expanded using |\edef|. + All arguments are characters and will be expanded using |\edef|. \begin{codeexample}[] \pgfmathfloatcreate{1}{1.0}{327} \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} @@ -229,19 +320,20 @@ Flags: \F; Mantissa \M; Exponent \E \end{command} \begin{command}{\pgfmathfloatifflags\marg{floating point number}\marg{flag}\marg{true-code}\marg{false-code}} - Invokes \marg{true-code} if the flag of \marg{floating point number} equals \marg{flag} and \marg{false-code} otherwise. - - The argument \marg{flag} can be one of - \begin{description} - \item[0] to test for zero, - \item[1] to test for positive numbers, - \item[+] to test for positive numbers, - \item[2] to test for negative numbers, - \item[-] to test for negative numbers, - \item[3] for ``not-a-number'', - \item[4] for $+\infty$, - \item[5] for $-\infty$. - \end{description} + Invokes \meta{true-code} if the flag of \meta{floating point number} + equals \meta{flag} and \meta{false-code} otherwise. + + The argument \meta{flag} can be one of + \begin{description} + \item[0] to test for zero, + \item[1] to test for positive numbers, + \item[+] to test for positive numbers, + \item[2] to test for negative numbers, + \item[-] to test for negative numbers, + \item[3] for ``not-a-number'', + \item[4] for $+\infty$, + \item[5] for $-\infty$. + \end{description} \begin{codeexample}[] \pgfmathfloatparsenumber{42} @@ -257,50 +349,73 @@ Flags: \F; Mantissa \M; Exponent \E \begin{command}{\pgfmathfloattomacro{\marg{x}}{\marg{flagsmacro}}{\marg{mantissamacro}}{\marg{exponentmacro}}} - Extracts the flags of a floating point number \marg{x} to \marg{flagsmacro}, the mantissa to \marg{mantissamacro} and the exponent to \marg{exponentmacro}. + Extracts the flags of a floating point number \meta{x} to + \meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the + exponent to \meta{exponentmacro}. \end{command} \begin{command}{\pgfmathfloattoregisters{\marg{x}}{\marg{flagscount}}{\marg{mantissadimen}}{\marg{exponentcount}}} - Takes a floating point number \marg{x} as input and writes flags to count - register \marg{flagscount}, mantissa to dimen register \marg{mantissadimen} and exponent to count - register \marg{exponentcount}. + Takes a floating point number \meta{x} as input and writes flags to + count register \meta{flagscount}, mantissa to dimen register + \meta{mantissadimen} and exponent to count register \meta{exponentcount}. - Please note that this method rounds the mantissa to \TeX-precision. + Please note that this method rounds the mantissa to \TeX-precision. \end{command} \begin{command}{\pgfmathfloattoregisterstok{\marg{x}}{\marg{flagscount}}{\marg{mantissatoks}}{\marg{exponentcount}}} - A variant of |\pgfmathfloattoregisters| which writes the mantissa into a token register. It maintains the full input precision. + A variant of |\pgfmathfloattoregisters| which writes the + mantissa into a token register. It maintains the full input + precision. \end{command} \begin{command}{\pgfmathfloatgetflags{\marg{x}}{\marg{flagscount}}} - Extracts the flags of \marg{x} into the count register \marg{flagscount}. + Extracts the flags of \meta{x} into the count register + \meta{flagscount}. \end{command} -\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{\textbackslash macro}}} - Extracts the flags of \marg{x} into the macro \meta{\textbackslash macro}. +\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{macro}}} + Extracts the flags of \meta{x} into the macro \meta{macro}. \end{command} \begin{command}{\pgfmathfloatgetmantissa{\marg{x}}{\marg{mantissadimen}}} - Extracts the mantissa of \marg{x} into the dimen register \marg{mantissadimen}. + Extracts the mantissa of \meta{x} into the dimen register + \meta{mantissadimen}. \end{command} + \begin{command}{\pgfmathfloatgetmantissatok{\marg{x}}{\marg{mantissatoks}}} - Extracts the mantissa of \marg{x} into the token register \marg{mantissatoks}. + Extracts the mantissa of \meta{x} into the token register + \meta{mantissatoks}. \end{command} + \begin{command}{\pgfmathfloatgetexponent{\marg{x}}{\marg{exponentcount}}} - Extracts the exponent of \marg{x} into the count register \marg{exponentcount}. + Extracts the exponent of \meta{x} into the count register + \meta{exponentcount}. \end{command} \subsubsection{Symbolic Rounding Operations} -Commands in this section constitute the basic level implementations of the rounding routines. They work symbolically, i.e.\ they operate on text, not on numbers and allow arbitrarily large numbers. + +Commands in this section constitute the basic level implementations of +the rounding routines. They work symbolically, i.e.\ they operate on +text, not on numbers and allow arbitrarily large numbers. \begin{command}{\pgfmathroundto{\marg{x}}} - Rounds a fixed point number to prescribed precision and writes the result to |\pgfmathresult|. + Rounds a fixed point number to prescribed precision and writes the + result to |\pgfmathresult|. - The desired precision can be configured with |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. This section does also contain application examples. + The desired precision can be configured with + |/pgf/number format/precision|, see + section~\ref{pgfmath-numberprinting}. This section does also contain + application examples. - Any trailing zeros after the period are discarded. The algorithm is purely text based and allows to deal with precisions beyond \TeX's fixed point support. - - As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will be set to true if and only if the resulting mantissa has a period. Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will be set to true if and only if the rounding result's floating point representation would have a larger exponent than \marg{x}. + Any trailing zeros after the period are discarded. The algorithm is + purely text based and allows to deal with precisions beyond \TeX's + fixed point support. + + As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| + will be set to true if and only if the resulting mantissa has a + period. Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will + be set to true if and only if the rounding result's floating point + representation would have a larger exponent than \meta{x}. \begin{codeexample}[] \pgfmathroundto{1} \pgfmathresult @@ -316,7 +431,8 @@ Commands in this section constitute the basic level implementations of the round \end{command} \begin{command}{\pgfmathroundtozerofill{\marg{x}}} - A variant of |\pgfmathroundto| which always uses a fixed number of digits behind the period. It fills missing digits with zeros. + A variant of |\pgfmathroundto| which always uses a fixed number of + digits behind the period. It fills missing digits with zeros. \begin{codeexample}[] \pgfmathroundtozerofill{1} \pgfmathresult @@ -332,13 +448,19 @@ Commands in this section constitute the basic level implementations of the round \end{command} \begin{command}{\pgfmathfloatround{\marg{x}}} - Rounds a normalized floating point number to a prescribed precision and writes the result to |\pgfmathresult|. + Rounds a normalized floating point number to a prescribed precision + and writes the result to |\pgfmathresult|. - The desired precision can be configured with |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. + The desired precision can be configured with + |/pgf/number format/precision|, see + section~\ref{pgfmath-numberprinting}. - This method employs |\pgfmathroundto| to round the mantissa and applies renormalization if necessary. + This method employs |\pgfmathroundto| to round the mantissa and + applies renormalization if necessary. - As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will be set to true if and only if the resulting mantissa has a period. + As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| + will be set to true if and only if the resulting mantissa has a + period. \begin{codeexample}[] \pgfmathfloatparsenumber{52.5864} \pgfmathfloatround{\pgfmathresult} @@ -354,7 +476,8 @@ Commands in this section constitute the basic level implementations of the round \end{command} \begin{command}{\pgfmathfloatroundzerofill{\marg{x}}} - A variant of |\pgfmathfloatround| produces always the same number of digits after the period (it includes zeros if necessary). + A variant of |\pgfmathfloatround| produces always the same number of + digits after the period (it includes zeros if necessary). \begin{codeexample}[] \pgfmathfloatparsenumber{52.5864} \pgfmathfloatroundzerofill{\pgfmathresult} @@ -369,94 +492,139 @@ Commands in this section constitute the basic level implementations of the round \end{codeexample} \end{command} + + \subsubsection{Math Operations Commands} -This sections describes some of the replacement commands in more details. -Please note that these commands can be used even if the |fpu| as such has not been activated -- it is sufficient to load the library. +This section describes some of the replacement commands in more +detail. + +Please note that these commands can be used even if the |fpu| as such +has not been activated -- it is sufficient to load the library. \begin{command}{\pgfmathfloat\meta{op}} - Methods of this form constitute the replacement operations where \meta{op} can be any of the well--known math operations. + Methods of this form constitute the replacement operations where + \meta{op} can be any of the well-known math operations. - Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart for |\pgfmathadd| and so on. The semantics and number of arguments is the same, but all input and output arguments are \emph{expected} to be floating point numbers. + Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart + for |\pgfmathadd| and so on. The semantics and number of + arguments is the same, but all input and output arguments are + \emph{expected} to be floating point numbers. \end{command} \begin{command}{\pgfmathfloattoextentedprecision{\marg{x}}} -Renormalizes \marg{x} to extended precision mantissa, meaning -$100 \le m < 1000$ instead of $1 \le m < 10$. - -The `extended precision' means we have higher accuracy when we apply pgfmath operations to mantissas. - -The input argument is expected to be a normalized floating point number; the output argument is a non-normalized floating point number (well, normalized to extended precision). - -The operation is supposed to be very fast. + Renormalizes \meta{x} to extended precision mantissa, meaning + $100 \le m < 1000$ instead of $1 \le m < 10$. + + The ``extended precision'' means we have higher accuracy when we apply + pgfmath operations to mantissas. + + The input argument is expected to be a normalized floating point + number; the output argument is a non-normalized floating point number + (well, normalized to extended precision). + + The operation is supposed to be very fast. \end{command} \begin{command}{\pgfmathfloatsetextprecision\marg{shift}} - Sets the precision used inside of |\pgfmathfloattoextentedprecision| to \marg{shift}. - - The different choices are - - \begin{tabular}{llrll} - 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision)\\ - 1 & normalization to & $10$ & $\le m < 100$ \\ - 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|)\\ - 3 & normalization to & $1000$ & $\le m < 10000$ \\ - \end{tabular} + Sets the precision used inside of |\pgfmathfloattoextentedprecision| to \meta{shift}. + + The different choices are + + \begin{tabular}{llrll} + 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision)\\ + 1 & normalization to & $10$ & $\le m < 100$ \\ + 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|)\\ + 3 & normalization to & $1000$ & $\le m < 10000$ \\ + \end{tabular} \end{command} \begin{command}{\pgfmathfloatlessthan{\marg{x}}{\marg{y}}} - Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but $0.0$ otherwise. It also sets the global \TeX-boolean |\pgfmathfloatcomparison| accordingly. The arguments \marg{x} and \marg{y} are expected to be numbers which have already been processed by |\pgfmathfloatparsenumber|. Arithmetics is carried out using \TeX-registers for exponent- and mantissa comparison. + Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but + $0.0$ otherwise. It also sets the global \TeX-boolean + |\pgfmathfloatcomparison| accordingly. The arguments \meta{x} and + \meta{y} are expected to be numbers which have already been + processed by |\pgfmathfloatparsenumber|. Arithmetic is carried out + using \TeX-registers for exponent- and mantissa comparison. \end{command} \begin{command}{\pgfmathfloatmultiplyfixed\marg{float}\marg{fixed}} - Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ where \meta{float} is a floating point number and \meta{fixed} is a fixed point number. The computation is performed in floating point arithmetics, that means we compute $m \cdot \meta{fixed}$ and renormalizes the result where $m$ is the mantissa of \meta{float}. + Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ + where \meta{float} is a floating point number and \meta{fixed} is a + fixed point number. The computation is performed in floating point + arithmetics, that means we compute $m \cdot \meta{fixed}$ and + renormalize the result where $m$ is the mantissa of \meta{float}. - This operation renormalizes \meta{float} with |\pgfmathfloattoextentedprecision| before the operation, that means it is intended for relatively small arguments of \meta{fixed}. The result is a floating point number. + This operation renormalizes \meta{float} with + |\pgfmathfloattoextentedprecision| before the operation, that means + it is intended for relatively small arguments of \meta{fixed}. The + result is a floating point number. \end{command} \begin{command}{\pgfmathfloatifapproxequalrel\marg{a}\marg{b}\marg{true-code}\marg{false-code}} - Computes the relative error between \meta{a} and \meta{b} (assuming \meta{b}$\neq 0$) and - invokes \meta{true-code} if the relative error is below |/pgf/fpu/rel thresh| and - \meta{false-code} if that is not the case. + Computes the relative error between \meta{a} and \meta{b} (assuming + \meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error + is below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not + the case. - The input arguments will be parsed with |\pgfmathfloatparsenumber|. + The input arguments will be parsed with |\pgfmathfloatparsenumber|. - \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)} - A threshold used by |\pgfmathfloatifapproxequalrel| to decide whether numbers are approximately equal. - \end{key} + \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)} + A threshold used by |\pgfmathfloatifapproxequalrel| to decide + whether numbers are approximately equal. + \end{key} \end{command} \begin{command}{\pgfmathfloatshift{\marg{x}}{\marg{num}}} - Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The operation is an arithmetic shift base ten and modifies only the exponent of \marg{x}. The argument \marg{num} is expected to be a (positive or negative) integer. + Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The + operation is an arithmetic shift base ten and modifies only the + exponent of \meta{x}. The argument \meta{num} is expected to be a + (positive or negative) integer. \end{command} \begin{command}{\pgfmathfloatabserror\marg{x}\marg{y}} - Defines |\pgfmathresult| to be the absolute error between two floating point numbers $x$ and $y$, $\lvert x - y\rvert $ and returns the result as floating point number. + Defines |\pgfmathresult| to be the absolute error between two + floating point numbers $x$ and $y$, $\lvert x - y\rvert $ and + returns the result as floating point number. \end{command} \begin{command}{\pgfmathfloatrelerror\marg{x}\marg{y}} - Defines |\pgfmathresult| to be the relative error between two floating point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert $ and returns the result as floating point number. + Defines |\pgfmathresult| to be the relative error between two + floating point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y + \rvert $ and returns the result as floating point number. \end{command} \begin{command}{\pgfmathfloatint\marg{x}} -Returns the integer part of the floating point number \marg{x}, by truncating any digits after the period. This methods is applied to the absolute value $\rvert x \lvert$, so negative numbers are treated in the same way as positive ones. + Returns the integer part of the floating point number \meta{x}, by + truncating any digits after the period. This methods truncates the + absolute value $\rvert x \lvert$ to the next smaller integer and + restores the original sign afterwards. -The result is returned as floating point number as well. + The result is returned as floating point number as well. -See also |\pgfmathfloattoint| which returns the number in integer format. + See also |\pgfmathfloattoint| which returns the number in integer + format. \end{command} \begin{command}{\pgfmathlog{\marg{x}}} - Defines |\pgfmathresult| to be the natural logarithm of \marg{x}, $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, but it applies floating point arithmetics to read number \marg{x} and employs the logarithm identity - \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] - to get the result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with $1 \le m < 10$ needs to be computed. This is done using standard pgf math operations. - - Please note that \marg{x} needs to be a number, expression parsing is not possible here. - - If \marg{x} is \emph{not} a bounded positive real number (for example $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no error message will be generated. + Defines |\pgfmathresult| to be the natural logarithm of \meta{x}, + $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, + but it applies floating point arithmetics to read number \meta{x} + and employs the logarithm identity + \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] + to get the result. The factor $\ln(10)$ is a constant, so only + $\ln(m)$ with $1 \le m < 10$ needs to be computed. This is done + using standard pgf math operations. + + Please note that \meta{x} needs to be a number, expression parsing + is not possible here. + + If \meta{x} is \emph{not} a bounded positive real number (for + example $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no + error message will be generated. \begin{codeexample}[] \pgfmathlog{1.452e-7} \pgfmathresult @@ -468,10 +636,16 @@ See also |\pgfmathfloattoint| which returns the number in integer format. \end{command} \subsubsection{Accessing the Original Math Routines for Programmers} -As soon as the library is loaded, every private math routine will be copied to a new name. -This allows library and package authors to access the \TeX-register based math routines even if the FPU is activated. And, of course, it allows the FPU as such to perform its own mantissa computations. -The private implementations of \pgfname\ math commands, which are of the form |\pgfmath|\meta{name}|@|, will be available as|\pgfmath@basic@|\meta{name}|@| as soon as the library is loaded. +As soon as the library is loaded, every private math routine will be +copied to a new name. This allows library and package authors to +access the \TeX-register based math routines even if the FPU is +activated. And, of course, it allows the FPU as such to perform its +own mantissa computations. + +The private implementations of \pgfname\ math commands, which are of +the form |\pgfmath|\meta{name}|@|, will be available +as|\pgfmath@basic@|\meta{name}|@| as soon as the library is loaded. \endgroup diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-lsystems.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-lsystems.tex index 0aeb8113b01..75462b19720 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-lsystems.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-lsystems.tex @@ -126,13 +126,13 @@ only defined when the \meta{specification} argument is executed. The symbols |[| and |]| act like a stack: |[| pushes the state of the L-system on to the stack, and |]| pops a state off the stack. - When \meta{code} is executed the transformation matrix is set up + When \meta{code} is executed, the transformation matrix is set up so that the origin is at the current position and the positive x-axis ``points forward'', so |\pgfpathlineto{\pgfpoint{1cm}{0cm}}| draws a line 1cm forward. The following keys can alter the production of an L-system. However, -thy do not store values in themselves. +they do not store values in themselves. \begin{key}{/pgf/lindenmayer system/step=\meta{length} (initially 5pt)} How far the L-system moves forward if required. This key sets the @@ -161,7 +161,7 @@ thy do not store values in themselves. The value is stored in the \TeX{} macro |\pgflsystemrandomizeanglepercent|. \end{key} -For speed and convenience, when the code for a symbol is executed the +For speed and convenience, when the code for a symbol is executed, the following commands are available. \begin{command}{\pgflsystemcurrentstep} @@ -189,18 +189,18 @@ The following commands may be useful if you wish to define your own symbols. \begin{command}{\pgflsystemrandomizestep} - Randomizes the value in |\pgflsystemcurrentstep| according to the - value of the |randomize| |step| |percent| key. + Randomizes the value in |\pgflsystemcurrentstep| according to the + current value of the key |randomize step percent|. \end{command} \begin{command}{\pgflsystemrandomizeleftangle} Randomizes the value in |\pgflsystemcurrentleftangle| according to - the value of the |randomize| |angle| |percent| key. + the value of the |randomize angle percent| key. \end{command} \begin{command}{\pgflsystemrandomizerightangle} Randomizes the value in |\pgflsystemcurrentrightangle| according - to the value of the |randomize| |angle| key. + to the value of the |randomize angle| key. \end{command} \begin{command}{\pgflsystemdrawforward} @@ -252,17 +252,15 @@ symbols. need not have been declared using |\symbol| or exist as a default symbol (in fact, the more interesting L-systems depend on using symbols with no corresponding code, to control the ``growth'' of the - system). - \meta{body} consists of a string of symbols, which again need not - necessarily have any code associated with them. - + system). \meta{body} consists of a string of symbols, which again + need not necessarily have any code associated with them. \end{command} - As an example, the following shows an L-system that uses - some of these commands. This example illustrates the point - that some symbols, in this case |A| and |B|, do not have to - have code associated with them. They simply control the - growth of the system. +As an example, the following shows an L-system that uses +some of these commands. This example illustrates the point +that some symbols, in this case |A| and |B|, do not have to +have code associated with them. They simply control the +growth of the system. \begin{codeexample}[pre={\nullfont\expandafter\let\csname pgf@lsystem@Hilbert curve\endcsname=\relax}] \pgfdeclarelindenmayersystem{Hilbert curve}{ @@ -286,11 +284,11 @@ The following command is used to run an L-system in \pgfname: \begin{command}{\pgflindenmayersystem\marg{name}\marg{axiom}\marg{order}} Runs the L-system called \meta{name} using the input string \meta{axiom} for \meta{order} iterations. - In general, prior to calling this command the + In general, prior to calling this command, the transformation matrix should be set appropriately for shifting and rotating, and a move-to to the (transformed) origin should be executed. This origin will be where the L-system starts. - In addition the relevant keys should be set appropriately. + In addition, the relevant keys should be set appropriately. \begin{codeexample}[] \begin{tikzpicture} @@ -305,7 +303,7 @@ The following command is used to run an L-system in \pgfname: \end{tikzpicture} \end{codeexample} - Note that, it is perfectly feasible for an L-system to define + Note that it is perfectly feasible for an L-system to define special symbols which perform the move-to and use-path operations. @@ -346,9 +344,7 @@ The following command is used to run an L-system in \pgfname: This library adds some additional keys for specifying L-systems. These keys only work in \tikzname{} and all -have the same path, namely, |/pgf/lindenmayer| |system|, but so -you do not have to keep repeating this path the following keys are -provided: +have the same path, namely, |/pgf/lindenmayer| |system|, but the following keys are provided for convenience, so that you do not have to keep repeating this path: \begin{stylekey}{/pgf/lindenmayer system=\marg{keys}} \keyalias{tikz} @@ -362,15 +358,15 @@ A more compact version of the previous key. \end{stylekey} \begin{key}{/pgf/lindenmayer system/name=\marg{name}} - Set the name for the L-system. + Sets the name for the L-system. \end{key} \begin{key}{/pgf/lindenmayer system/axiom=\marg{string}} - Set the axiom (or input string) for the L-system. + Sets the axiom (or input string) for the L-system. \end{key} \begin{key}{/pgf/lindenmayer system/order=\marg{integer}} - Set the number of iterations the L-system will perform. + Sets the number of iterations the L-system will perform. \end{key} \begin{key}{/pgf/lindenmayer system/rule set=\marg{list}} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-math.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-math.tex new file mode 100644 index 00000000000..7d30a93c9d3 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-math.tex @@ -0,0 +1,547 @@ +% Copyright 2013 by Mark Wibrow +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + + +\section{Math Library} +\label{section-library-math} + +\begin{tikzlibrary}{math} + This library defines a simple mathematical language + to define simple functions and perform sequences of basic mathematical + operations. +\end{tikzlibrary} + + +\subsection{Overview} + + \pgfname\ and \tikzname\ both use the \pgfname\ mathematical engine + which provides many commands for parsing expressions. Unfortunately + the \pgfname\ math engine is somewhat cumbersome for long sequences + of mathematical + operations, particularly when assigning values to multiple variables. + The \tikzname\ |calc| library + provides some additional ``convenience'' operations for doing calculations + (particularly with coordinates), but this can only be used inside + \tikzname\ path commands. + + This |math| library provides a means to + perform sequences of mathematical operations in a more `user friendly' + manner than the \pgfname\ math engine. In addition, the coordinate calculations of the |calc| library + can be accessed (provided it is loaded). + % + However as the |math| library uses the \pgfname\ math engine -- which uses pure \TeX\ + to perform all its calculations -- it is subject to the same speed + and accuracy limitations. It is worth bearing this in mind, before + trying to implement algorithms requiring intensive and highly + accurate computation. You can, of course use the |fp| or the |fpu| + libraries to increase the accuracy (but not necessarily the speed) + of computations. + + For most purposes, the features provided by this library are accessed + using the following command: + +\begin{command}{\tikzmath\texttt{\{}\meta{statements}\texttt{\}}} + + This command process a series of \meta{statements} which can + represent assignments, function definitions, conditional evaluation, + and iterations. It provides, in effect, a miniature mathematical + language to perform basic mathematical operations. + Perhaps the most important thing to remember is that \emph{every + statement should end with a semi-colon}. This is + likely to be the most common reason why the |\tikzmath| command fails. + +\begin{codeexample}[] +\tikzmath{ + % Adapted from http://www.cs.northwestern.edu/academics/courses/110/html/fib_rec.html + function fibonacci(\n) { + if \n == 0 then { + return 0; + } else { + return fibonacci2(\n, 0, 1); + }; + }; + function fibonacci2(\n, \p, \q) { + if \n == 1 then { + return \q; + } else { + return fibonacci2(\n-1, \q, \p+\q); + }; + }; + int \f, \i; + for \i in {0,1,...,20}{ + \f = fibonacci(\i); + print {\f, }; + }; +} +\end{codeexample} + +\end{command} + +In addition to this command the following key is provided: + +\begin{key}{/tikz/evaluate={\meta{statements}}} + This key simply executes |\tikzmath{|\meta{statements}|}|. + +\begin{codeexample}[] +\tikz[x=0.25cm,y=0.25cm, + evaluate={ + int \i, \j; + for \i in {0,...,10}{ + for \j in {0,...,10}{ + \a{\i,\j} = (\i+\j)*5; + }; + }; + } +] +\foreach \i in {0,...,10} + \foreach \j in {0,...,10} + \fill [red!\a{\i,\j}!yellow] (\i,\j) rectangle ++(1, 1); + +\end{codeexample} + + +\end{key} + + + The following sections describe the miniature language that this + library provides and can be used in the |\tikzmath| command and the |evaluate| key. + The language consists only of simple keywords and expressions but + the mini-parser allows you to format code in a reasonably versatile + way (much like the |tikz| parser) except that + \emph{all the keywords must be followed by at least one space}. + This is the second most important thing to remember (after + remembering to insert semi-colons at the end of every statement). + + +\subsection{Assignment} + + In the simplest case, you will want to evaluate an expression + and assign it to a macro, or a \TeX\ count or dimension register. + In this case, use of the |math| library is straightforward: + +\begin{codeexample}[] +\newcount\mycount +\newdimen\mydimen +\tikzmath{ + \a = 4*5+6; + \b = sin(30)*4; + \mycount = log10(2048) / log10(2); + \mydimen = 15^2; +} +\a, \b, \the\mycount, \the\mydimen +\end{codeexample} + + + In addition, \TeX-macros (\emph{not} \TeX\ registers) + can be suffixed with an index, similar to + indices in mathematical notation, for example, $x_1$, $x_2$, $x_3$: + +\begin{codeexample}[] +\tikzmath{ + \x1 = 3+4; \x2 = 30+40; \x3 = 300+400; +} +\x1, \x2, \x3 +\end{codeexample} + + The index does not have to be a number. By using braces |{}|, + more sophisticated indices can be created: + +\begin{codeexample}[] +\tikzmath{ + \c{air} = 340; \c{water} = 1435; \c{steel} = 6100; +} +\foreach \medium in {air,steel}{The speed of sound in \medium\ is \c{\medium} m/s. } +\end{codeexample} + + You should not, however, try to mix indexed and non-indexed variables. Once + an assignment is made using an index, the |math| library expects + all instances of the variable on the right hand side of an assignment + to be followed by an index. This effect is reversed if you + subsequently make an assignment to the variable without an index: the |math| library + (or to be precise the \pgfname\ math-engine) + will then ignore any index following the variable on the right hand side + of an assignment. + + In some cases, you may wish to assign a value or expression to a variable + without evaluating it with the \pgfname\ math-engine. In this case, you + can use the following keyword: + +\begin{math-keyword}{{let} \meta{variable} \texttt{=} \meta{expression}\texttt{;}} + + This keyword assigns \meta{expression} to \meta{variable} + without evaluation. The \meta{expression} is however fully + expanded using |\edef|. Any spaces preceding \meta{expression} + are removed, but any trailing spaces (before the semi-colon) + are included. + +\begin{codeexample}[] +\tikzmath{ + let \x = (5*4)+1; + let \c1 = blue; +} +\x, ``\c1'' +\end{codeexample} +\end{math-keyword} + +\subsection{Integers, ``Real'' Numbers, and Coordinates} + + By default, assignments are made by evaluating expressions + using the \pgfname\ math-engine and + results are usually returned as number with a decimal point (unless you + are assigning to a count register or use the |int| function). + % + As this is not always desirable, the |math| library allows + variables -- which \emph{must} be \TeX\ macros -- to be `declared' + as being a particular `type'. The library recognizes three types: + integers (numbers without a decimal point), + real numbers (numbers with a decimal point\footnote{Strictly speaking, due to the + finite range and precision of \TeX\ numerical capabilities, the term ``real'' is + not correct.}), and coordinates. + + To declare a variable as being one of the three types, + you can use the keywords shown below. It is important to remember + that by telling the |math| library you want it to do a + particular assignment for a variable, it will also do the same + assignment when the variable is indexed. + +\begin{codeexample}[] +\tikzmath{ + integer \x; + \x1 = 3+4; \x2 = 30+40; \x3 = 300+400; +} +\x1, \x2, \x3 +\end{codeexample} + + +% But, if you want integer results without using a count register or the +% |int| function, you can use a keyword to indicate this: + +\begin{math-keyword}{{integer} \meta{variable}\opt{\texttt{,} +\meta{additional variables}}\texttt{;}} + + The |integer| keyword indicates that assignments to the \meta{variable} or + the comma separated list of \meta{additional variables} should be + truncated (not rounded) to integers. The variables should be ordinary + macros -- \emph{not} \TeX\ registers. In addition the variables + should \emph{not} be indexed. + +\begin{codeexample}[] +\tikzmath{ + integer \x, \y, \z; + \x = 4*5+6; + \y = sin(30)*4; + \z = log10(512) / log10(2); + print {$x=\x$, $y=\y$, $z=\z$}; +} +\end{codeexample} + +\end{math-keyword} + +\begin{math-keyword}{{int} \meta{variable}\opt{\texttt{,} +\meta{additional variables}}\texttt{;}} + Short version of the |integer| keyword. +\end{math-keyword} + + Having declared a variable as an integer, the |math| library will + continue to assign only integers to that variable within the + current \TeX\ scope. If you wish to assign non-integer (i.e., \emph{real}) + numbers to the same variable, the following keyword can be used. + +\begin{math-keyword}{{real} \meta{variable}\opt{\texttt{,} +\meta{additional variables}}\texttt{;}} + The |real| keyword ensures that assignments \meta{variable} + (and \meta{additional variables}) will not be truncated to integers. +\end{math-keyword} + + In order to take advantage of |math| library interface to the + |calc| library you must indicate that a variable is to be assigned + coordinates, using the following keyword. + +\begin{math-keyword}{{coordinate} +\meta{variable}\opt{\texttt{,} +\meta{additional variables}}\texttt{;}}% + + This keyword enables \tikzname-style coordinates such as |(2cm,3pt)| or + |(my node.east)| to be parsed and + assigned to \meta{variable} in the form $x,y$, which can then be used + in a |tikzpicture|: + +\begin{codeexample}[] +\tikzmath{ + coordinate \c; + \c = (45:10pt); +} +\tikz\draw (0,0) -- (\c); +\end{codeexample} + + If the \tikzname\ |calc| library is loaded, + coordinate calculations can be performed; + the coordinate expression does not have to be + surrounded by |($|\ldots|$)|. + +\begin{codeexample}[] +\tikzmath{ + coordinate \c, \d; + \c = (-1,2)+(1,-1); + \d = (4,1)-(2,-1); +} +\tikz\draw (\c) -- (\d); +\end{codeexample} + + In addition to assigning the $x$ and $y$ coordinates to \meta{variable} + (possibly with an optional index), two further + variables are defined. The first takes the name of \meta{variable} + (e.g., |\c|) suffixed with |x| (i.e., |\cx|) and is assigned the + $x$ coordinate of |\c|. + The second takes the name of \meta{variable} + suffixed with |y| (i.e., |\cy|) and is assigned the + $y$ coordinate of |\c|. + +\begin{codeexample}[] +\tikzmath{ + coordinate \c; + \c1 = (30:20pt); + \c2 = (210:20pt); +} +\tikz\draw (\cx1,\cy1) -- (\cx2,\cy1) -- (\cx2,\cy2) -- (\cx1,\cy2); +\end{codeexample} + +\end{math-keyword} + +%\begin{math-keyword}{{point} +%\meta{variable}\opt{\texttt{,} +%\meta{additional variables}}\texttt{;}}% +% +% The |point| keyword is a synonym for the |coordinate| keyword +% and performs the same function. +%\end{math-keyword} + + +\subsection{Repeating Things} + +\begin{math-keyword}{{for} \meta{variable} \texttt{in +\{}\meta{list}\texttt{\}\{}\meta{expressions}\texttt{\};}} + + This is a ``trimmed down'' version of the |\foreach| command available + as part of \pgfname\ and \tikzname, but cannot currently be used + outside of the |\tikzmath| command. + It is important to note the following: + +\begin{itemize} + +\item + Every value in \meta{list} is evaluated using the \pgfname\ mathematical + engine. However, if an item in \meta{list} contains a comma, it \emph{must} be + surrounded + by braces, for example, |{mod(5, 2)}|. + +\begin{codeexample}[] +\tikzmath{ + int \x, \v; + \v=1; + for \x in {1,...,{random(3,10)}}{ + \v=\v*2; + }; + print {$x=\x, v=\v$}; +} +\end{codeexample} + +\item + Because each item is evaluated, you cannot + use \tikzname\ coordinates in \meta{list}. + +\item + Only single variable assignment is supported. + +\item + The ``dots notation'' (e.\,g., |1,2,...,9|) can be used in \meta{list}, + but is not as sophisticated as the \pgfname\ |\foreach| command. + In particular, contextual replacement is not possible. + +\item + Assignments that occur in the loop body \emph{are not scoped}. + They last beyond the body of each iteration and the end of the |for| + statement. This includes the values assigned to the \meta{variable}. + +\begin{codeexample}[] +\tikzmath{ + int \x, \y; + \y = 0; + for \x1 in {1,...,5}{ + for \x2 in {10,20,...,50}{ + \y = \y+\x1*\x2; + }; + }; +} +$x_1=\x1, x_2=\x2, y=\y$ +\end{codeexample} + + + + + +\end{itemize} + +\end{math-keyword} + + + + + + + + +\subsection{Branching Statements} + + Sometimes you may wish to execute different statements + depending on the value of an expression. In this + case the following keyword can be used: + +\begin{math-keyword}{{if} \meta{condition} \texttt{then \{}\meta{if-non-zero-statements}\texttt{\};}} + + This keyword executes \meta{if-non-zero-statements} if the expression in \meta{condition} + evaluates to any value other than zero. + +\end{math-keyword} + +\begin{math-keyword}{{if} \meta{condition} \texttt{then \{}\meta{if-non-zero-statements}\texttt{\}} \texttt{else} \texttt{\{}\meta{if-zero-statements}\texttt{\}}\texttt{;}} + + This keyword executes \meta{if-non-zero-statements} if the expression in \meta{condition} + evaluates to any value other than zero and the \meta{if-zero-statements} are executed if + the expression in \meta{condition} evaluates to zero. + +\begin{codeexample}[] + \begin{tikzpicture} + \tikzmath{ + int \x; + for \k in {0,10,...,350}{ + if \k>260 then { let \c = orange; } else { + if \k>170 then { let \c = blue; } else { + if \k>80 then { let \c = red; } else { + let \c = green; }; }; }; + { + \path [fill=\c!50, draw=\c] (\k:0.5cm) -- (\k:1cm) -- + (\k+5:1cm) -- (\k+5:0.5cm) -- cycle; + }; + }; + } + \end{tikzpicture} +\end{codeexample} +\end{math-keyword} + +\subsection{Declaring Functions} + + You can add functions by using the following keywords: + +\begin{math-keyword}{{function} \meta{name}\texttt{(}\meta{arguments}\texttt{) \{} \meta{definition} \texttt{\};}} + + This keyword works much like the |declare function| provided by the + \pgfname\ math-engine. + The function \meta{name} can be any name that is not already a + function name in the current scope. The list of \meta{arguments} are + comma separated \TeX\ macros such as |\x|, or |\y| (it is not + possible to declare functions that take variable numbers of arguments). + If the function + takes no arguments then the parentheses need not be used. + It is very important to note that the arrays that the + \pgfname\ math engine supports + \emph{cannot currently be passed as arguments to functions}. + + + The function \meta{definition} should be a sequence of statements + that can be parsed by the |\tikzmath| command and + should use the commands specified in the \meta{arguments}. + The |return| keyword (described below) should be used to indicate + the value returned by the function. + % + Although \meta{definition} can take any statements accepted by + |\tikzmath|, it is not advisable try to define functions inside other + functions. + +\begin{codeexample}[] +\tikzmath{ + function product(\x,\y) { + return \x*\y; + }; + int \i, \i, \k; + \i = random(1,10); + \j = random(20, 40); + \k = product(\i, \j); + print { $\i\times \j = \k$ }; +} +\end{codeexample} + +\end{math-keyword} + +\begin{math-keyword}{{return} \meta{expression}\texttt{;}} + + This keyword should be used as the last executed statement + in a function definition to indicate the value that should be + returned. + +\end{math-keyword} + + +\subsection{Executing Code Outside the Parser} + + Sometimes you may wish to do ``something'' outside the parser, + perhaps display some intermediate result or execute some code. + In this case + you have two options. Firstly, the following keyword can be used: + +\begin{math-keyword}{{print} \texttt{\{}\meta{code}\texttt{\};}} + + Execute \meta{code} immediately. This is intended as convenience + keyword for displaying information in a document (analogous to + the |print| command in real programming languages). + The \meta{code} is executed inside a \TeX\ group. + +\begin{codeexample}[] +\tikzmath{ + int \x, \y, \z; + \x = random(2, 5); + for \y in {0,...,6}{ + \z = \x^\y; + print {$\x^\y=\z$, }; + }; +} +\end{codeexample} + +\end{math-keyword} + + Secondly, if a statement begins with a brace |{|, then + everything up to the closing brace |}| is collected + and executed (the closing brace \emph{must} + be followed by a semi-colon). + Like the |print| keyword, the contents of the braces + is executed inside a \TeX\ group. + Unlike the |print| keyword, the brace notation can be used in + functions so that |tikz| path commands can be safely executed + inside a |tikzpicture|. + +\begin{codeexample}[] +\begin{tikzpicture} +\draw [help lines] grid (3,2); +\tikzmath{ + coordinate \c; + for \x in {0,10,...,360}{ + \c = (1.5cm, 1cm) + (\x:1cm and 0.5cm); + { \fill (\c) circle [radius=1pt]; }; + }; +} +\end{tikzpicture} +\end{codeexample} + + + + + + +\endinput diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex index a50f1179d7b..2a697d768e7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-matrices.tex @@ -11,7 +11,7 @@ \section{Matrix Library} \begin{tikzlibrary}{matrix} - This library packages defines additional styles and options for + This library package defines additional styles and options for creating matrices. \end{tikzlibrary} @@ -48,7 +48,7 @@ cell. The following key simplifies typesetting such matrices. be achieved in three ways. \begin{enumerate} \item You can modify, say, the - |row 2 column 5| style to pass special options to this particular + |row 2 column 3| style to pass special options to this particular cell. \begin{codeexample}[] @@ -98,7 +98,7 @@ cell. The following key simplifies typesetting such matrices. expands to |\path|, which includes |\draw|, |\node|, |\fill| and others, the |\node{| startup code and the |};| code are suppressed. This means that for this particular cell you can - provide a totally different contents. + provide totally different contents. \begin{codeexample}[] \begin{tikzpicture} @@ -132,7 +132,7 @@ cell. The following key simplifies typesetting such matrices. \end{key} \begin{key}{/tikz/nodes in empty cells=\meta{true or false} (default true)} - When set to |true|, a node (with an empty contents) is put in empty + When set to |true|, a node (with empty contents) is put in empty cells. Normally, empty cells are just, well, empty. The style can be used together with both a |matrix of nodes| and a |matrix of math nodes|. @@ -288,7 +288,7 @@ some after node magic. \begin{key}{/tikz/above delimiter=\meta{delimiter}} This option allows you to add a delimiter above the node. It is - implementing by rotating a left delimiter. + implemented by rotating a left delimiter. \begin{codeexample}[] \begin{tikzpicture} \matrix [matrix of math nodes,% diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-mindmaps.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-mindmaps.tex index 4a88719792c..0288319b757 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-mindmaps.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-mindmaps.tex @@ -65,7 +65,7 @@ Every mindmap should be put in a scope or a picture where the \end{codeexample} \end{stylekey} - \paragraph{Remark:} Note that |mindmap| re-defines |font| sizes and |sibling angle| depending on the current concept level (i.e. inside of |level 1 concept|, |level 2 concept| etc.). Thus, if you need to redefine these variables, use + \paragraph{Remark:} Note that |mindmap| redefines |font| sizes and |sibling angle| depending on the current concept level (i.e. inside of |level 1 concept|, |level 2 concept| etc.). Thus, if you need to redefine these variables, use |\tikzset{level 1 concept/.append style={font=\small}}| @@ -141,9 +141,9 @@ The following styles influence how isolated concepts are rendered: \begin{stylekey}{/tikz/extra concept} This style is intended for concepts that are not part of the ``mindmap tree,'' but stand beside it. Typically, they will have a - subdued color are be smaller. In order to have these concepts appear + subdued color or be smaller. In order to have these concepts appear in a uniform way and in order to indicate in the code that these - concepts are extra, you can use this style. + concepts are additional, you can use this style. \begin{codeexample}[] \begin{tikzpicture}[mindmap,concept color=blue!80] \node [concept] {Root concept}; @@ -158,7 +158,7 @@ The following styles influence how isolated concepts are rendered: \subsubsection{Concepts in Trees} -As pointed out earlier, \tikzname\ assumes that your mindmap is build +As pointed out earlier, \tikzname\ assumes that your mindmap is built using the |child| facilities of \tikzname. There are numerous options that influence how concepts are rendered at the different levels of a tree. @@ -199,7 +199,7 @@ tree. Works like |level 1 concept|. \end{stylekey} \begin{stylekey}{/tikz/level 4 concept} - Works like |level 1 concept|. Note that there are not fifth and + Works like |level 1 concept|. Note that there are no fifth and higher level styles, you need to modify |level 5| directly in such cases. \end{stylekey} @@ -222,8 +222,9 @@ tree. child[concept color=orange,grow=0] {node[concept] {Child concept}}; \end{codeexample} - In order to have all children of a certain level have a different - concept color, a tiny bit of magic is needed: + In order to have a concept color which changes with the hierarchy level, a tiny bit of magic is needed: + % FIXME : is this a bug in the software!? The root concept is + % black!? \begin{codeexample}[] \tikz[mindmap,text=white, root concept/.style={concept color=blue}, @@ -331,12 +332,12 @@ in the mindmap library: In the above example you may notice the small white line between the circles and the decorated path. This is due to rounding - errors. Unfortunately, for larger distances, there errors can + errors. Unfortunately, for larger distances, the errors can accumulate quite strongly, especially since \tikzname\ and \TeX\ are not very good at computing square roots. For this reason, it is a good idea to make the circles slightly larger to cover up such problems. When using nodes of shape |circle|, you can just add the - |draw| option with a |line width| or one or two points (for very + |draw| option with a |line width| of one or two points (for very large distances you may need line width up to 4pt). \begin{codeexample}[] \begin{tikzpicture} @@ -349,11 +350,12 @@ in the mindmap library: \end{tikzpicture} \end{codeexample} - Note the slightly strange |outer sep=0pt|. This is needed so that - the decorated path lies on the border of the filled circle, not on the - border of the stroked circle (which is slightly larger and this - slightly larger size is exactly what we wish to use to cover up the - rounding errors). + % FIXME : this paragraph appears to be deprecated: + %Note the slightly strange |outer sep=0pt|. This is needed so that + %the decorated path lies on the border of the filled circle, not on the + %border of the stroked circle (which is slightly larger and this + %slightly larger size is exactly what we wish to use to cover up the + %rounding errors). \end{decoration} @@ -363,7 +365,7 @@ in the mindmap library: The |circle connection bar| decoration is a bit complicated to use. Especially specifying the radii is quite bothersome (the amplitude and the angle can be set once and for all). For this reason, -the mindmap library defines a special to-path, that performs the +the mindmap library defines a special to-path that performs the necessary computations for you. \begin{stylekey}{/tikz/circle connection bar} @@ -392,7 +394,7 @@ necessary computations for you. \end{tikzpicture} \end{codeexample} Note that it is not a good idea to have more than one |to| operation - together this the option |circle connection bar| in a single + together with the option |circle connection bar| in a single |\path|. Use the |edge| operation, instead, for creating multiple connections and this operation creates a new scope for each edge. \end{stylekey} @@ -422,9 +424,8 @@ library provides a special option for facilitating this procedure. \subsubsection{Tree Edges} Most of the time, concepts in a mindmap are connected automatically -when the mindmap is build as a tree. The reason is that the |mindmap| -installs a |circle connection bar| path as the edge from parent -path. Also, the |mindmap| option takes care of things like setting the +when the mindmap is built as a tree. The reason is that the |mindmap| +installs a |circle connection bar| path as the |edge from parent path|. Also, the |mindmap| option takes care of things like setting the correct |draw| and |outer sep| settings and some other stuff. In detail, the |mindmap| option sets the |edge from parent path| to a @@ -436,7 +437,7 @@ set to the new (child's) concept color. This means that when you provide the |concept color| option to a |child| command, the color will change from the parent's concept color to the specified color. -Here is an example of a tree build in this way: +Here is an example of a tree built in this way: \begin{codeexample}[] \begin{tikzpicture} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-petri.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-petri.tex index befc36b9e0f..9807c3542d3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-petri.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-petri.tex @@ -198,10 +198,10 @@ The Petri net library offers a solution to this problem: The \end{key} \end{stylekey} -The |children are tokens| options gives you a lot of flexibility, but +The |children are tokens| option gives you a lot of flexibility, but it is a bit cumbersome to use. For this reason there are some options that help in standard situations. They all use |children are tokens| -internally, so any change to, say, the |every tokens| style will +internally, so any change to, say, the |every token| style will affect how these options depict tokens. \begin{key}{/tikz/tokens=\meta{number}} @@ -236,15 +236,14 @@ affect how these options depict tokens. \begin{key}{/tikz/colored tokens=\meta{color list}} This option, which must also be given when a place node is being created, gets a list of colors as parameter. It will then add as - many tokens to the place are in this list, each colored with the - corresponding color in the list. + many tokens to the place as there are colors in this list, each filled correspondingly. \begin{codeexample}[] \tikz \node[place,colored tokens={black,black,red,blue}] {}; \end{codeexample} \end{key} \begin{key}{/tikz/structured tokens=\meta{token texts}} - This option, which must again be passed to a place, gets a list - texts for tokens. For each text, another token will be added to the place. + This option, which must again be passed to a place, gets a list of + texts for tokens. For each text, a new token will be added to the place. \begin{codeexample}[] \tikz \node[place,structured tokens={$x$,$y$,$z$}] {}; \end{codeexample} @@ -284,8 +283,8 @@ affect how these options depict tokens. \node[token] at (h1) {}; \node[transition] at (1.5,1.5) {} edge [pre] (p1) edge [post] (p2); - \node[transition] at (1.5,2.5) {} edge[pre] (p2) edge[pre] (m1f) - edge[post] (p3) edge[post] (m1t); + \node[transition] at (1.5,2.5) {} edge [pre] (p2) edge[pre] (m1f) + edge [post](p3) edge[post] (m1t); \node[transition] at (1.5,3.3) {} edge [pre] (p3) edge [post] (p4) edge [pre and post] (h1); \node[transition] at (1.5,3.7) {} edge [pre] (p3) edge [pre] (h2) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex index fd58176b7a2..127aa229972 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-handlers.tex @@ -98,7 +98,7 @@ \end{command} \subsection{Constant Plot Handlers} -There are three plot handlers which produce piecewise constant interpolations between successive points. +There are several plot handlers which produce piecewise constant interpolations between successive points: \begin{command}{\pgfplothandlerconstantlineto} This handler works like the line-to plot handler, only it will @@ -134,6 +134,24 @@ the right line ends. \end{codeexample} \end{command} +\begin{command}{\pgfplothandlerconstantlinetomarkmid} +A variant of |\pgfplothandlerconstantlineto| which places its mark on +the center of the line. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlinetomarkmid + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + The plot handler always connects two data points by a horizontal line starting from the previous data points, followed by a vertical line in the middle between the two data points, followed by a horizontal line between the middle and the current data point. This results in a symmetric constant plot handler for constant mesh width. +\end{command} + \begin{command}{\pgfplothandlerjumpmarkleft} This handler works like the line-to plot handler, only it will produce a non-connected, piecewise constant path to connect the points. If there are any plot marks, they will be placed on the left open pieces. @@ -168,9 +186,27 @@ the right line ends. \end{codeexample} \end{command} +\begin{command}{\pgfplothandlerjumpmarkmid} + This handler works like the |\pgfplothandlerconstantlinetomarkmid|, but it will + produce a non-connected, piecewise constant path to connect the points. If there are any plot marks, they will be placed in the center of the horizontal line segment.. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkmid + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} + See |\pgfplothandlerconstantlinetomarkmid| for details. +\end{command} + \subsection{Comb Plot Handlers} -There are three ``comb'' plot handlers. There name stems from the fact +There are three ``comb'' plot handlers. Their name stems from the fact that the plots they produce look like ``combs'' (more or less). \begin{command}{\pgfplothandlerxcomb} @@ -377,10 +413,10 @@ interval). The $y$~value of the last point will be ignored. \end{command} \label{key-bar-interval-shift}% -\begin{key}{/pgf/bar interval shift=\marg{shift} (initially 0.5)} +\begin{key}{/pgf/bar interval shift=\marg{factor} (initially 0.5)} \keyalias{tikz} Sets the \emph{relative} shift of |\pgfplothandlerxbarinterval| and - |\pgfplothandlerybarinterval| to \marg{shift}. As + |\pgfplothandlerybarinterval| to \meta{factor}. As |/pgf/bar interval width|, the argument is relative to the interval length of the input coordinates. @@ -428,6 +464,49 @@ interval). The $y$~value of the last point will be ignored. $0.25$ and $0.75$ instead of $0$ and $0.5$. \end{key} +\subsection{Gapped Plot Handlers} + +\label{section-plot-gapped} + + +\begin{command}{\pgfplothandlergaplineto} + This handler will connect the points of the plots by straight line + segments. However, at the start and the end of the lines there will + be a small gap, given by the following key: + \begin{key}{/pgf/gap around stream point=\meta{dimension} (initially 1.5pt)} + The \meta{dimension} by which the lines between consecutive stream + points are shortened at the beginning and end. + \end{key} +\begin{codeexample}[] +\begin{tikzpicture} + \pgfplothandlergaplineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfplothandlergapcycle} + Works like |\pgfplothandlergaplineto|, but the last point is + connected to the first in the same fashion: +\begin{codeexample}[] +\begin{tikzpicture} + \pgfplothandlergapcycle + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + \subsection{Mark Plot Handler} \label{section-plot-marks} @@ -435,7 +514,7 @@ interval). The $y$~value of the last point will be ignored. \begin{command}{\pgfplothandlermark\marg{mark code}} This command will execute the \meta{mark code} for some points of the plot, but each time the coordinate transformation matrix will be - setup such that the origin is at the position of the point to be + set up such that the origin is at the position of the point to be plotted. This way, if the \meta{mark code} draws a little circle around the origin, little circles will be drawn at some point of the plot. @@ -500,7 +579,7 @@ interval). The $y$~value of the last point will be ignored. \begin{command}{\pgfuseplotmark\marg{plot mark name}} Draws the given \meta{plot mark name} at the origin. The \meta{plot - mark name} must previously have been declared using + mark name} must have been previously declared using |\pgfdeclareplotmark|. \begin{codeexample}[] diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-marks.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-marks.tex index b953be6a25e..8dbef923854 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-marks.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-plot-marks.tex @@ -80,6 +80,11 @@ Note that each of the provided marks can be rotated freely by means of |mark opt There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \marg{text}, including images. \end{key} +\begin{key}{/pgf/text mark as node=\marg{boolean} (initially false)} + Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|. + + The first choice is highly flexible and possibly slow, the second is very fast and usually enough. +\end{key} \begin{key}{/pgf/text mark style=\marg{options for \texttt{mark=text}}} Defines a set of options which control the appearance of |mark=text|. @@ -87,11 +92,6 @@ Note that each of the provided marks can be rotated freely by means of |mark opt If |/pgf/text mark as node=true|, \marg{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc. \end{key} -\begin{key}{/pgf/text mark as node=\mchoice{true,false} (initially false)} - Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|. - - The first choice is highly flexible and possibly slow, the second is very fast and usually enough. -\end{key} } diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-profiler.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-profiler.tex index 74fbea14558..9bc9b6fd57f 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-profiler.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-profiler.tex @@ -13,7 +13,9 @@ \begin{pgflibrary}{profiler} A library to simplify the optimization of runtime speed of \TeX\ programs. - It relies on the |pdftex| primitive \declareandlabel{\pdfelapsedtime} to count (fractional) seconds and counts total time and self time for macro invocations. + It relies on the |pdftex| primitive + \declareandlabel{\pdfelapsedtime}\footnote{The primitive is + emulated in lua\TeX.} to count (fractional) seconds and counts total time and self time for macro invocations. \end{pgflibrary} \subsection{Overview} @@ -28,22 +30,23 @@ The work flow for the optimization is simple: the preamble contains configuratio \noindent and then, the time between |\begin{tikzpicture}| and |\end{tikzpicture}| and the time required to call |\pgfkeys| will be collected. At the end, a short usage summary like -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] pgflibraryprofiler(main job) {total time=1.07378sec; (100.0122%) self time=0.034sec; (3.1662%)} pgflibraryprofiler(<ENV>tikzpicture) {total time=1.03978sec; (96.84601%) self time=1.00415sec; (93.52722%)} pgflibraryprofiler(<CS>pgfkeys) {total time=0.03563sec; (3.31726%) self time=0.03563sec; (3.31726%)} \end{codeexample} \noindent will be provided in the log file, furthermore, the same information is available in a text table called |\jobname.profiler.|\meta{datetime}|.dat| which is of the form: -\begin{codeexample}[code only] +\begin{codeexample}[code only, tikz syntax=false] profilerentry totaltime[s] totaltime[percent] selftime[s] selftime[percent] main job 1.07378 100.0122 0.034 3.1662 <ENV>tikzpicture 1.03978 96.84601 1.00415 93.52722 <CS>pgfkeys 0.03563 3.31726 0.03563 3.31726 \end{codeexample} -Here, the |totaltime| means the time used for all invocations of the respective profiler entry (one row in the table). The |selftime| measures time which is not already counted for in another profiler entry which has been invoked within the current one. The example above is not very exiting: the main job consists only of several (quite complex) pictures and nothing else. Thus, its total time is large. However, the self time is very small because the |tikzpicture|s are counted separately, and they have been invoked within the |main job|. The |\pgfkeys| control sequence has been invoked within the |tikzpicture|, that's why the |selftime| for the |tikzpicture| is a little bit smaller than its |totaltime|. +Here, the |totaltime| means the time used for all invocations of the respective profiler entry (one row in the table). The |selftime| measures time which is not already counted for in another profiler entry which has been invoked within the current one. The example above is not very exciting: the main job consists only of several (quite complex) pictures and nothing else. Thus, its total time is large. However, the self time is very small because the |tikzpicture|s are counted separately, and they have been invoked within the |main job|. The |\pgfkeys| control sequence has been invoked within the |tikzpicture|, that's why the |selftime| for the |tikzpicture| is a little bit smaller than its |totaltime|. \subsection{Requirements} -The library doesn't work without |pdftex|. Furthermore, it requires a more or less recent version which supports the |\pdfelapsedtime| directive. +The library works with |pdftex| and |luatex|. Furthermore, it requires +a more or less recent version of |pdftex| which supports the |\pdfelapsedtime| directive. \subsection{Defining Profiler Entries} Unlike profilers for C/C++ or java, this library doesn't extract information about every \TeX\ macro automatically, nor does it collect information for each of them. Instead, every profiler entry needs to be defined explicitly. Only defined profiler entries will be processed. @@ -104,7 +107,7 @@ Note that |\pgfprofilenewforcommand| is a special case of |\pgfprofilenewforcomm \begin{command}{\pgfprofileshowinvocationsfor\marg{profiler entry name}} Enables verbose output for \emph{every} invocation of \meta{profiler entry name}. - This is only available for profiler entries for commands (those created by |\pgfprofilenewforcommand| for example). It will also show any arguments. + This is only available for profiler entries for commands (those created by |\pgfprofilenewforcommand| for example). It will also show all given arguments. \end{command} \begin{command}{\pgfprofileshowinvocationsexpandedfor\marg{profiler entry name}} A variant of |\pgfprofileshowinvocationsfor| which will expand all arguments for \meta{profiler entry name} before showing them. The invocation as such is not affected by this expansion. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadings.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadings.tex index cf4a008aebe..2d7d9648ef5 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadings.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadings.tex @@ -32,7 +32,7 @@ even when this library is not used. bottom line is at the bottom of the path. \begin{key}{/tikz/top color=\meta{color}} - This option prescribes the color to be used at the top in an |axis| + This option sets the color to be used at the top in an |axis| shading. When this option is given, several things happen: \begin{enumerate} \item @@ -130,13 +130,13 @@ even when this library is not used. \end{key} \begin{key}{/tikz/upper left=\meta{color} (initially white)} - Like |lower left|. + Works like |lower left|. \end{key} \begin{key}{/tikz/upper right=\meta{color} (initially white)} - Like |lower left|. + Works like |lower left|. \end{key} - \begin{key}{/tikz/lower left=\meta{color} (initially white)} - Like |lower left|. + \begin{key}{/tikz/lower right=\meta{color} (initially white)} + Works like |lower left|. \end{key} \end{shading} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadows.tex index 2ca29e963f0..94e7487b1d7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadows.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shadows.tex @@ -7,7 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Shadow Library} +\section{Shadows Library} \label{section-libs-shadows} \begin{pgflibrary}{shadows} @@ -19,7 +19,7 @@ \subsection{Overview} A \emph{shadow} is usually a black or gray area that is drawn behind a -path or a node, thereby adding visual depth to a picture. The shadows +path or a node, thereby adding visual depth to a picture. The |shadows| library defines options that make it easy to add shadows to paths. Internally, these options are based on using the |preaction| option to use a path twice: Once for drawing the shadow (slightly @@ -31,7 +31,7 @@ scopes. In addition to the general |shadow| option, there exist special options like |circular shadow|. These can only (sensibly) be used with a special kind of path (for |circular shadow|, a circle) and, thus, -there are not as general. The advantage is, however, that they are +they are not as general. The advantage is, however, that they are more visually pleasing since these shadows blend smoothly with the background. Note that these special shadows use fadings, which few printers will support. @@ -59,7 +59,7 @@ circumstances. \meta{shadow options} are used for painting this path. Typically, the \meta{shadow options} will contain options like |fill=black| to create, say, a black shadow. Furthermore, after the \meta{shadow - options} have been setup, the following extra canvas + options} have been set up, the following extra canvas transformations are applied to the path: It is scaled by |shadow scale| (with the origin of scaling at the path's center) and it is shifted by |shadow xshift| and |shadow yshift|. @@ -73,23 +73,23 @@ circumstances. \end{codeexample} \begin{key}{/tikz/shadow scale=\meta{factor} (initially 1)} - Shadows are scaled by this amount. + Shadows are scaled by \meta{factor}. \begin{codeexample}[] \tikz [even odd rule] \draw [general shadow={fill=red,shadow scale=1.25}] (0,0) circle (.5) (0.5,0) circle (.5); \end{codeexample} \end{key} - \begin{key}{/tikz/shadow xshift=\meta{factor} (initially 0pt)} - Shadows are shifted horizontally by this amount. + \begin{key}{/tikz/shadow xshift=\meta{dimension} (initially 0pt)} + Shadows are shifted horizontally by \meta{dimension}. \begin{codeexample}[] \tikz [even odd rule] \draw [general shadow={fill=red,shadow xshift=-5pt}] (0,0) circle (.5) (0.5,0) circle (.5); \end{codeexample} \end{key} - \begin{key}{/tikz/shadow yshift=\meta{factor} (initially 0pt)} - Shadows are shifted vertically by this amount. + \begin{key}{/tikz/shadow yshift=\meta{dimension} (initially 0pt)} + Shadows are shifted vertically by \meta{dimension}. \end{key} \end{key} @@ -100,9 +100,9 @@ circumstances. \subsubsection{Drop Shadows} \begin{key}{/tikz/drop shadow=\meta{shadow options} (default \normalfont empty)} - This option adds a drop shadow to a path or node. |\path| or a + This option adds a drop shadow to a |\path| or a |node|. It uses the |general shadow| and passes the \meta{shadow - options} to it plus, before them, the following extra options: + options} to it, plus, before them, the following extra options: \begin{codeexample}[code only] shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, opacity=.5, fill=black!50, every shadow @@ -122,11 +122,11 @@ circumstances. \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); - \filldraw [drop shadow={opacity=0.25},fill=white] - (1,.5) circle (.5) (1.5,.5) circle (.5); - \filldraw [drop shadow={opacity=1},fill=white] (1,2) circle (.5) (1.5,2) circle (.5); + + \filldraw [drop shadow={opacity=0.25},fill=white] + (1,.5) circle (.5) (1.5,.5) circle (.5); \end{tikzpicture} \end{codeexample} \end{key} @@ -183,7 +183,7 @@ of the path/object present. \begin{key}{/tikz/double copy shadow=\meta{shadow options} (default \normalfont empty)} This shadow works like a |copy shadow|, only the shadow is added - twice, the first time with the double |xshift| and |yshift|. + twice, the second time with the double |xshift| and |yshift|. \begin{codeexample}[] \begin{tikzpicture} \node [double copy shadow,fill=blue!20,draw=blue,thick] {Hello World!}; diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex index 4c99d465083..3beaf544170 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-shapes.tex @@ -26,6 +26,18 @@ The appearance of shapes is influenced by numerous parameters like |minimum height| or |inner xsep|. These general parameters are documented in Section~\ref{section-shape-common-options} +In all of the examples presented in this section, the following +|shape example| style is used: +\begin{codeexample}[code only] +\tikzset{ + shape example/.style= {color = black!30, + draw, + fill = yellow!30, + line width = .5cm, + inner xsep = 2.5cm, + inner ysep = 0.5cm} +} +\end{codeexample} \subsection{Predefined Shapes} \label{section-predefined-shapes} @@ -163,9 +175,9 @@ shapes define a standard set of anchors. \begin{tikzpicture} \tikzstyle{every node}=[trapezium, draw] \node at (0,2) {A}; - \node[trapezium left angle=75, trapezium right angle=45pt] + \node[trapezium left angle=75, trapezium right angle=45] at (0,1) {B}; - \node[trapezium left angle=120, trapezium right angle=60pt] + \node[trapezium left angle=120, trapezium right angle=60] at (0,0) {C}; \end{tikzpicture} \end{codeexample} @@ -176,11 +188,11 @@ shapes define a standard set of anchors. To use these keys in \tikzname, simply remove the \declare{|/pgf/|} path. \begin{key}{/pgf/trapezium left angle=\meta{angle} (initially 60)} - Set the lower internal angle of the left side. + Sets the lower internal angle of the left side. \end{key} \begin{key}{/pgf/trapezium right angle=\meta{angle} (initially 60)} - Set the lower internal angle of the right side. + Sets the lower internal angle of the right side. \end{key} \begin{stylekey}{/pgf/trapezium angle=\meta{angle}} @@ -374,7 +386,7 @@ shapes define a standard set of anchors. Section~\ref{section-rotating-shape-borders}, but the border of the star is \emph{always} constructed using the incircle. - A star should be thought of as having an set of ``inner points'' + A star should be thought of as having a set of ``inner points'' and ``outer points''. The inner points of the border are based on the radius of the circle which tightly fits the node contents, and the outer points are based @@ -463,7 +475,7 @@ shapes define a standard set of anchors. To use these keys in \tikzname, simply remove the \declare{|/pgf/|} path. - \begin{key}{/pgf/isosceles triangle apex angle=\meta{angle} (initially 45)} + \begin{key}{/pgf/isosceles triangle apex angle=\meta{angle} (initially 30)} Sets the angle of the apex of the isosceles triangle. \end{key} @@ -545,11 +557,11 @@ shapes define a standard set of anchors. path. \begin{key}{/pgf/kite upper vertex angle=\meta{angle} (initially 120)} - Set the upper internal angle of the kite. + Sets the upper internal angle of the kite. \end{key} \begin{key}{/pgf/kite lower vertex angle=\meta{angle} (initially 60)} - Set the lower internal angle of the kite. + Sets the lower internal angle of the kite. \end{key} \begin{key}{/pgf/kite vertex angles=\meta{angle specification}} @@ -622,11 +634,11 @@ shapes define a standard set of anchors. \end{codeexample} \begin{key}{/pgf/dart tip angle=\meta{angle} (initially 45)} - Set the angle at the tip of the dart. + Sets the angle at the tip of the dart. \end{key} \begin{key}{/pgf/dart tail angle=\meta{angle} (initially 135)} - Set the angle between the tails of the dart. + Sets the angle between the tails of the dart. \end{key} The anchors for the |dart| shape are shown below (note that the @@ -678,7 +690,7 @@ shapes define a standard set of anchors. path. \begin{key}{/pgf/circular sector angle=\meta{angle} (initially 60)} - Set the central angle of the sector. + Sets the central angle of the sector. \end{key} The anchors for the circular sector shape are shown below. @@ -735,7 +747,7 @@ shapes define a standard set of anchors. width will stretch the curved ends. \begin{codeexample}[] -\begin{tikzpicture}[>=stealth, shape aspect=.5] +\begin{tikzpicture}[shape aspect=.5] \tikzset{every node/.style={cylinder, shape border rotate=90, draw}} \node [minimum height=1.5cm] {A}; \node [minimum width=1.5cm] at (1.5,0) {B}; @@ -751,7 +763,7 @@ shapes define a standard set of anchors. to some minimum width. \begin{codeexample}[] -\begin{tikzpicture}[>=stealth] +\begin{tikzpicture}[] \tikzset{every node/.style={cylinder, shape border rotate=90, draw}} \node [aspect=1.0] {A}; \node [aspect=0.5] at (1,0) {B}; @@ -771,22 +783,22 @@ shapes define a standard set of anchors. \end{key} \begin{codeexample}[] -\begin{tikzpicture}[>=stealth, aspect=0.5] +\begin{tikzpicture}[aspect=0.5] \node [cylinder, cylinder uses custom fill, cylinder end fill=red!50, cylinder body fill=red!25] {Cylinder}; \end{tikzpicture} \end{codeexample} \begin{key}{/pgf/cylinder end fill=\meta{color} (initially white)} - Set the color for the end of the cylinder. + Sets the color for the end of the cylinder. \end{key} \begin{key}{/pgf/cylinder body fill=\meta{color} (initially white)} - Set the color for the body of the cylinder. + Sets the color for the body of the cylinder. \end{key} - The anchors this shape are shown below (anchor |160| is an - example of a border anchor). Note the cylinder shape does not + The anchors of this shape are shown below (anchor |160| is an + example of a border anchor). Note that the cylinder shape does not distinguish between |outer xsep| and |outer ysep|. Only the larger of the two values is used for the shape. Note also the difference between the |center| and |shape center| anchors: |center| is the @@ -831,14 +843,28 @@ shapes define a standard set of anchors. -\begin{shape}{forbidden sign} +\begin{shape}{correct forbidden sign} This shape places the node inside a circle with a diagonal from the - lower left to the upper right added. The circle is part of the + upper left to the lower right added. The circle is part of the background, the diagonal line part of the foreground path; thus, the diagonal line is on top of the text. \begin{codeexample}[] \begin{tikzpicture} + \node [correct forbidden sign,line width=1ex,draw=red,fill=white] {Smoking}; +\end{tikzpicture} +\end{codeexample} + + The shape inherits all anchors from the |circle| shape. +\end{shape} + +\begin{shape}{forbidden sign} + This shape is like |correct forbidden sign|, only the line goes from + the lower left to the upper right. The strange naming of these + shapes is for historical reasons. + +\begin{codeexample}[] +\begin{tikzpicture} \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking}; \end{tikzpicture} \end{codeexample} @@ -888,17 +914,17 @@ shapes define a standard set of anchors. \tikzname{}, simply remove the \declare{|/pgf/|} path). \begin{key}{/pgf/cloud puffs=\meta{integer} (initially 10)} - Set the number of puffs for the cloud. + Sets the number of puffs for the cloud. \end{key} \begin{key}{/pgf/cloud puff arc=\meta{angle} (initially 135)} - Set the length of the puff arc (in degrees). A shorter arc can + Sets the length of the puff arc (in degrees). A shorter arc can produce better looking joins between puffs for larger line widths. \end{key} Like the diamond shape, the cloud shape also uses the - \declare{|aspect|} key, to determine the ratio of the width and the - height of the cloud. However there may be circumstances where it may + \declare{|aspect|} key to determine the ratio of the width and the + height of the cloud. However, there may be circumstances where it may be undesirable to continually specify the |aspect| for the cloud. Therefore, the following key is implemented: @@ -961,7 +987,7 @@ shapes define a standard set of anchors. \begin{shape}{starburst} This shape is a randomly generated elliptical star, - which supports the rotating of the shape border as described in + which supports the rotation of the shape border as described in Section~\ref{section-rotating-shape-borders}. \begin{codeexample}[] \begin{tikzpicture} @@ -974,7 +1000,7 @@ shapes define a standard set of anchors. Using a specified `starburst point height' value, the outer points are generated randomly between this value and one quarter of this - value. For a given starburst shape the angle between each point is + value. For a given starburst shape, the angle between each point is fixed, and is determined by the number of points specified for the starburst. @@ -996,15 +1022,15 @@ shapes define a standard set of anchors. \declare{|/pgf/|} path. \begin{key}{/pgf/starburst points=\meta{integer} (initially 17)} - Set the number of points for the starburst. + Sets the number of outer points for the starburst. \end{key} \begin{key}{/pgf/starburst point height=\meta{length} (initially .5cm)} - Set the \emph{maximum} distance between the inner point radius + Sets the \emph{maximum} distance between the inner point radius and the outer point radius. \end{key} \begin{key}{/pgf/random starburst=\meta{integer} (initially 100)} - Set the seed for the random number generator for creating the + Sets the seed for the random number generator for creating the starburst. The maximum value for \meta{integer} is |16383|. If \meta{integer}|=0|, the random number generator will not be used, and the maximum point height will be used for all outer @@ -1056,13 +1082,13 @@ shapes define a standard set of anchors. keys in \tikzname{}, simply remove the \declare{|/pgf/|} path): \begin{key}{/pgf/signal pointer angle=\meta{angle} (initially 90)} - Set the angle for the pointed sides of the shape. This angle is + Sets the angle for the pointed sides of the shape. This angle is maintained when enforcing any minimum size requirements, so any adjustment to the width will affect the height, and vice versa. \end{key} \begin{key}{/pgf/signal from=\meta{direction}\space\opt{and \meta{opposite direction}} (initially nowhere)} - Set which sides take an inward pointer (i.e., that points towards the + Sets which sides take an inward pointer (i.e., that points towards the center of the shape). The possible values for \meta{direction} and \meta{opposite direction} are the compass point directions |north|, |south|, |east| and |west| (or |above|, |below|, |right| and |left|). @@ -1074,8 +1100,8 @@ shapes define a standard set of anchors. \end{key} \begin{key}{/pgf/signal to=\meta{direction}\space\opt{and \meta{opposite direction}} (initially east)} - Set which sides take an outward pointer (i.e., that points away from - the the shape). + Sets which sides take an outward pointer (i.e., that points away from + the shape). \end{key} Note that \pgfname{} will ignore any instruction to use directions @@ -1130,7 +1156,7 @@ shapes define a standard set of anchors. \declare{|/pgf/|} path): \begin{key}{/pgf/tape bend top=\meta{bend style} (initially in and out)} - Specify how the top side bends. The \meta{bend style} is either + Specifies how the top side bends. The \meta{bend style} is either |in and out|, |out and in| or |none| (i.e., a straight line). The bending sides are drawn in a clockwise direction, and using the bend style |in and out| will mean @@ -1164,11 +1190,11 @@ shapes define a standard set of anchors. \end{key} \begin{key}{/pgf/tape bend bottom=\meta{bend style} (initially in and out)} - Specify how the bottom side bends. + Specifies how the bottom side bends. \end{key}% \begin{key}{/pgf/tape bend height=\meta{length} (initially 5pt)} - Set the total height for a side with a bend. + Sets the total height for a side with a bend. \begin{codeexample}[] \begin{tikzpicture}[>=stealth] @@ -1207,6 +1233,74 @@ shapes define a standard set of anchors. +\begin{shape}{magnetic tape} + + This shape represents a `magnetic tape' or any sequential data store + that is sometimes used in flowcharts. It is essentially a circle with a + little tail: + +\begin{codeexample}[] +\tikz\node [magnetic tape, draw] (A) {A}; +\end{codeexample} + + The following keys can be used to customise the |magnetic tape| + shape: + + +\begin{key}{/pgf/magnetic tape tail extend=\meta{distance} (initially 0cm)} + + This key sets how far the tail extends beyond the radius of + the tape. Negative values will be ignored. + +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style={magnetic tape, draw}] + \node [magnetic tape tail extend=0cm] at (0,0) {A}; + \node [magnetic tape tail extend=0.25cm] at (0,1) {B}; +\end{tikzpicture} +\end{codeexample} +\end{key} + + + +\begin{key}{/pgf/magnetic tape tail=\meta{proportion} (initially 0.15)} + + This key sets the thickness of the `tail' to be \meta{proportion} + times the radius of the shape. The \meta{proportion} should be + between |0.0| and |1.0|. + +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style={magnetic tape, draw}] + \node [magnetic tape tail=0.5, magnetic tape tail extend=0.5cm] {A}; + \node [magnetic tape tail=0.25] at (0,1) {B}; +\end{tikzpicture} +\end{codeexample} +\end{key} + + + The following figure shows the anchors this shape defines; + the anchors 10 and 130 are example of border anchors. + +\begin{codeexample}[] +\Huge +\begin{tikzpicture} +\node[name=s,shape=magnetic tape,shape example,inner sep=0.75cm, +magnetic tape tail extend=0.5cm] + {Magnetic Tape\vrule width 1pt height 2cm}; +\foreach \anchor/\placement in + {north west/above left, north/above, north east/above right, + west/left, center/above, east/right, + mid west/right, mid/right, mid east/left, + base west/below, base/below, base east/right, + south west/below left, south/below, south east/left, + text/left, 10/right, 130/above, + tail east/right, tail south east/below, tail north east/above} + \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)} + node[\placement] {\scriptsize\texttt{(s.\anchor)}}; +\end{tikzpicture} +\end{codeexample} +\end{shape} + + \subsection{Arrow Shapes} \begin{pgflibrary}{shapes.arrows} @@ -1217,11 +1311,11 @@ shapes define a standard set of anchors. \end{pgflibrary} \begin{shape}{single arrow} - This shape is an arrow, which tightly fits the note contents + This shape is an arrow, which tightly fits the node contents (including any |inner sep|). This shape supports the rotation of the shape border, as described in Section~\ref{section-rotating-shape-borders}. - The angle of rotation determines which direction the arrow + The angle of rotation determines in which direction the arrow points (provided no other rotational transformations are applied). \begin{codeexample}[] @@ -1255,7 +1349,7 @@ shapes define a standard set of anchors. path). \begin{key}{/pgf/single arrow tip angle=\meta{angle} (initially 90)} - Set the angle for the arrow tip. Enlarging the arrow to some + Sets the angle for the arrow tip. Enlarging the arrow to some minimum width may increase the height of the shape to maintain this angle. \end{key} @@ -1315,7 +1409,7 @@ shapes define a standard set of anchors. \begin{shape}{double arrow} - This shape is a double arrow, which tightly fits the note contents + This shape is a double arrow, which tightly fits the node contents (including any |inner sep|), and supports the rotation of the shape border, as described in Section~\ref{section-rotating-shape-borders}. @@ -1349,7 +1443,7 @@ shapes define a standard set of anchors. path). \begin{key}{/pgf/double arrow tip angle=\meta{angle} (initially 90)} - Set the angle for the arrow tip. Enlarging the arrow to some + Sets the angle for the arrow tip. Enlarging the arrow to some minimum width may increase the height of the shape to maintain this angle. \end{key} @@ -1429,25 +1523,25 @@ There are various \pgfname{} keys for drawing this shape (to use these keys in \tikzname, simply remove the \declare{/pgf/} path). \begin{key}{/pgf/arrow box tip angle=\meta{angle} (initially 90)} - Set the angle at the arrow tip for all four arrows. + Sets the angle at the arrow tip for all four arrows. \end{key} \begin{key}{/pgf/arrow box head extend=\meta{length} (initially .125cm)} - Set the distance the arrow head extends away from the shaft + Sets the distance the arrow head extends away from the shaft of the arrow. This applies to all arrows. \end{key} \begin{key}{/pgf/arrow box head indent=\meta{length} (initially 0cm)} - Move the point where the arrow head joins the shaft of the arrow + Moves the point where the arrow head joins the shaft of the arrow \emph{towards} the arrow tip. This applies to all arrows. \end{key} \begin{key}{/pgf/arrow box shaft width=\meta{length} (initially .125cm)} - Set the width of the shaft of all arrows. + Sets the width of the shaft of all arrows. \end{key} \begin{key}{/pgf/arrow box north arrow=\meta{distance} (initially .5cm)} - Set distance the north arrow extends from the node. By default this + Sets the distance the north arrow extends from the node. By default this is from the border of the shape, but by using the additional keyword |from center|, the distance will be measured from the center of the shape. If \meta{distance} is |0pt| or a negative distance, the arrow @@ -1455,19 +1549,19 @@ keys in \tikzname, simply remove the \declare{/pgf/} path). \end{key} \begin{key}{/pgf/arrow box south arrow=\meta{distance} (initially .5cm)} - Set distance the south arrow extends from the node. + Sets the distance the south arrow extends from the node. \end{key} \begin{key}{/pgf/arrow box east arrow=\meta{distance} (initially .5cm)} - Set distance the east arrow extends from the node. + Sets the distance the east arrow extends from the node. \end{key} \begin{key}{/pgf/arrow box west arrow=\meta{distance} (initially .5cm)} - Set distance the west arrow extends from the node. + Sets the distance the west arrow extends from the node. \end{key} \begin{key}{/pgf/arrow box arrows={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}}} - Set the distance that all arrows extend from the node. The + Sets the distance that all arrows extend from the node. The specification in \meta{list} consists of the four compass points |north|, |south|, |east| or |west|, separated by commas (so the list must be contained within braces). @@ -1479,7 +1573,7 @@ keys in \tikzname, simply remove the \declare{/pgf/} path). Any sides not specified will not be drawn with an arrow. \end{key} -The anchors for this shape are shown below (unfortunately due to its +The anchors for this shape are shown below (unfortunately, due to its size, this example must be rotated). Anchor |75| is an example of a border anchor. If a side is drawn without an arrow, the anchors for that arrow should @@ -1616,7 +1710,7 @@ to the center of the appropriate side. \begin{shape}{rectangle split} - This shape is a rectangle which can be either split horizontally + This shape is a rectangle which can be split either horizontally or vertically into several parts. \begin{codeexample}[] @@ -1652,15 +1746,15 @@ these extra boxes, the following key is provided: \begin{key}{/pgf/rectangle split allocate boxes=\meta{number}} This key checks if \meta{number} boxes have been allocated, and if - not allocates the required boxes using |\newbox| (some ``magic'' is + not, it allocates the required boxes using |\newbox| (some ``magic'' is performed to get around the fact that |\newbox| is declared |\outer| in plain \TeX). \end{key} - When split vertically, the rectangle split will observe any - |minimum width| requirements but any |minimum height| will be ignored. + When split vertically, the rectangle split will meet any + |minimum width| requirements, but any |minimum height| will be ignored. Conversely when split horizontally, |minimum height| requirements - will be observed, but any |minimum width| will be ignored. + will be met, but any |minimum width| will be ignored. In addition, |inner sep| is applied to every part that is used, so it cannot be specified independently for a particular part. @@ -1672,7 +1766,7 @@ these extra boxes, the following key is provided: \begin{key}{/pgf/rectangle split parts=\meta{number} (initially 4)} Split the rectangle into \meta{number} parts, which should be in the range |1| to |20|. If more than four parts - are need, the boxes should be allocated in advance as + are needed, the boxes should be allocated in advance as described above. \begin{codeexample}[] @@ -1711,25 +1805,25 @@ these extra boxes, the following key is provided: \end{key} % \begin{key}{/pgf/rectangle split empty part width=\meta{length} (initially 1ex)} - Set the default width for a node part box if it is empty and + Sets the default width for a node part box if it is empty and empty parts are not ignored. \end{key} \begin{key}{/pgf/rectangle split empty part height=\meta{length} (initially 1ex)} - Set the default height for a node part box if it is empty and + Sets the default height for a node part box if it is empty and empty parts are not ignored. \end{key} \begin{key}{/pgf/rectangle split empty part depth=\meta{length} (initially 0ex)} - Set the default depth for a node part box if it is empty and + Sets the default depth for a node part box if it is empty and empty parts are not ignored. \end{key} \begin{key}{/pgf/rectangle split part align={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}} (initially center)} - Set the alignment of the boxes inside the node parts. + Sets the alignment of the boxes inside the node parts. Each item in \meta{list} should be separated by commas (so if there is more than one item in - \meta{list} it must be surrounded by braces). + \meta{list}, it must be surrounded by braces). When the rectangle is split vertically, the entries in \meta{list} must be one of |left|, |right|, or |center|. If \meta{list} has less @@ -1752,7 +1846,7 @@ these extra boxes, the following key is provided: When the rectangle is split horizontally, the entries in \meta{list} must be one of |top|, |bottom|, |center| or |base|. Note that using - the value |base| will only makes sense if all the node part boxes are + the value |base| will only make sense if all the node part boxes are being aligned in this way. This is because the |base| value aligns the boxes in relation to each other, whereas the other values align the boxes in relation to the part of the shape they occupy. @@ -1774,7 +1868,7 @@ these extra boxes, the following key is provided: \end{key} \begin{key}{/pgf/rectangle split draw splits=\opt{\meta{boolean}} (default true)} - Set whether the line or lines between node parts will be drawn. + Sets whether the line or lines between node parts will be drawn. Internally, this sets the \TeX-if |\ifpgfrectanglesplitdrawsplits| appropriately. \end{key} @@ -1790,12 +1884,12 @@ these extra boxes, the following key is provided: \end{key} \begin{key}{/pgf/rectangle split part fill={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}} (initially white)} - Set the custom fill color for each node part shape. - Each item in \meta{list} should be separated by commas (so if - there is more than one item in \meta{list} it must be surrounded + Sets the custom fill color for each node part shape. + The items in \meta{list} should be separated by commas (so if + there is more than one item in \meta{list}, it must be surrounded by braces). If \meta{list} has less entries than node - parts then the remaining node parts use the color from + parts, then the remaining node parts use the color from the last entry in the list. This key will automatically set |/pgf/rectangle split use custom fill|. @@ -1813,7 +1907,7 @@ these extra boxes, the following key is provided: The anchors for the |rectangle split| shape split vertically into four, are shown below (anchor |70| is an example of a border angle). When a - node part is missing, the anchors prefixed with name of that node part + node part is missing, the anchors prefixed with the name of that node part should be considered unavailable. They are (unavoidably) defined, but default to other anchor positions. @@ -1859,7 +1953,7 @@ these extra boxes, the following key is provided: \end{pgflibrary} Callouts consist of a -main shape, and a pointer (which is part of the shape) which points +main shape and a pointer (which is part of the shape) which points to something in (or outside) the picture. The position on the border of the main shape to which the pointer is connected is determined automatically. However, the pointer is ignored when calculating the @@ -1903,14 +1997,14 @@ on whether they are being used in \pgfname{} or \tikzname{}. \begin{key}{/pgf/callout relative pointer=\meta{coordinate} (initially {\ttfamily\char`\\pgfpointpolar\char`\{315\char`\}\char`\{.5cm\char`\}})} - Set the vector of the callout pointer `relative' to the callout + Sets the vector of the callout pointer `relative' to the callout shape. \end{key} \begin{key}{/pgf/callout absolute pointer=\meta{coordinate}} - Set the vector of the callout pointer absolutely within the picture. + Sets the vector of the callout pointer absolutely within the picture. \end{key} @@ -1932,7 +2026,7 @@ on whether they are being used in \pgfname{} or \tikzname{}. the following key: \begin{key}{/pgf/callout pointer shorten=\meta{distance} (initially 0cm)} - Move the callout pointer towards the center of the callouts main + Moves the callout pointer towards the center of the callout's main shape by \meta{distance}. \begin{codeexample}[] @@ -1957,14 +2051,14 @@ on whether they are being used in \pgfname{} or \tikzname{}. \begin{key}{/pgf/callout pointer width=\meta{length} (initially .25cm)} - Set the width of the pointer at the border of the rectangle. + Sets the width of the pointer at the border of the rectangle. \end{key} The anchors for this shape are shown below (anchor |60| is an example of a border anchor). The pointer direction is ignored when placing anchors. Additionally, when using an absolute pointer, the |pointer| - anchor should not be used to used to position the shape as it is + anchor should not to be used to used to position the shape as it is calculated whilst the shape is being drawn. \begin{codeexample}[] @@ -1991,7 +2085,7 @@ on whether they are being used in \pgfname{} or \tikzname{}. \begin{shape}{ellipse callout}% - This shape is a callout whose main shape is a ellipse, which + This shape is a callout whose main shape is an ellipse, which tightly fits the node contents (including any |inner sep|). It uses the |absolute callout pointer|, |relative callout pointer| and |callout pointer shorten| keys, and @@ -1999,7 +2093,7 @@ on whether they are being used in \pgfname{} or \tikzname{}. \begin{key}{/pgf/callout pointer arc=\meta{angle} (initially 15)} - Set the width of pointer at the border of the ellipse according + Sets the width of the pointer at the border of the ellipse according to an arc of length \meta{angle}. \end{key} @@ -2053,7 +2147,7 @@ The main shape can be modified using the same keys as the |cloud| shape. The following keys are also supported: \begin{key}{/pgf/callout pointer start size=\meta{value} (initially .2 of callout)} - Set the size of the first segment in the pointer (i.e., the segment + Sets the size of the first segment in the pointer (i.e., the segment nearest the main cloud shape). There are three possible forms for \meta{value}: \begin{itemize} @@ -2072,11 +2166,11 @@ shape. The following keys are also supported: \end{key} \begin{key}{/pgf/callout pointer end size=\meta{value} (initially .1 of callout)} - Set the size of the last ellipse in the pointer. + Sets the size of the last ellipse in the pointer. \end{key} \begin{key}{/pgf/callout pointer segments=\meta{number} (initially 2)} - Set the number of segments in the pointer. Note that \pgfname{} will + Sets the number of segments in the pointer. Note that \pgfname{} will happily overlap segments if too many are specified. \end{key} @@ -2116,13 +2210,13 @@ of the last segment is drawn at the |pointer| anchor. \subsection{Miscellaneous Shapes} \begin{pgflibrary}{shapes.misc} - This library defines general-purpose shapes that do not fit in the + This library defines general-purpose shapes that do not fit into the previous categories. \end{pgflibrary} \begin{shape}{cross out} This shape ``crosses out'' the node. Its foreground path are simply - two diagonal lines that between the corners of the node's bounding + two diagonal lines between the corners of the node's bounding box. Here is an example: \begin{codeexample}[] @@ -2172,7 +2266,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \begin{shape}{rounded rectangle} - This shape is a rectangle which can be optionally round sides. + This shape is a rectangle which can have optionally rounded sides. \begin{codeexample}[] \begin{tikzpicture} @@ -2186,7 +2280,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \begin{key}{/pgf/rounded rectangle arc length=\meta{angle} (initially 180)} - Set the length of the arcs for the rounded ends. Recommended values + Sets the length of the arcs for the rounded ends. Recommended values for \meta{angle} are between |90| and |180|. \begin{codeexample}[] @@ -2201,7 +2295,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \end{key} \begin{key}{/pgf/rounded rectangle west arc=\meta{arc type} (initially convex)} - Set the style of the rounding for the left side. The permitted values + Sets the style of the rounding for the left side. The permitted values for \meta{arc type} are |concave|, |convex|, or |none|. \begin{codeexample}[] @@ -2219,7 +2313,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \end{stylekey} \begin{key}{/pgf/rounded rectangle east arc=\meta{arc type} (initially convex)} - Set the style of the rounding for the east side. + Sets the style of the rounding for the east side. \end{key} \begin{stylekey}{/pgf/rounded rectangle right arc=\meta{arc type}} @@ -2265,7 +2359,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! these keys in \tikzname{} simply remove the \declare{|/pgf/|} path). \begin{key}{/pgf/chamfered rectangle angle=\meta{angle} (initially 45)} - Set the angle \emph{from the vertical} for the chamfer. + Sets the angle \emph{from the vertical} for the chamfer. \begin{codeexample}[] \begin{tikzpicture} @@ -2277,7 +2371,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \end{key} \begin{key}{/pgf/chamfered rectangle xsep=\meta{length} (initially .666ex)} - Set the distance that the chamfer extends horizontally beyond the node + Sets the distance that the chamfer extends horizontally beyond the node contents (which includes the |inner sep|). If \meta{length} is large, such that the top and bottom chamfered edges would cross, then @@ -2295,7 +2389,7 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \end{key} \begin{key}{/pgf/chamfered rectangle ysep=\meta{length} (initially .666ex)} - Set the distance that the chamfer extends vertically beyond the node + Sets the distance that the chamfer extends vertically beyond the node contents. If \meta{length} is large, such that the left and right chamfered edges would cross, then \meta{length} is ignored and the chamfered @@ -2303,11 +2397,11 @@ Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out! \end{key} \begin{key}{/pgf/chamfered rectangle sep=\meta{length} (initially .666ex)} - Set both the |xsep| and |ysep| simultaneously. + Sets both the |xsep| and |ysep| simultaneously. \end{key} \begin{key}{/pgf/chamfered rectangle corners=\meta{list} (initially chamfer all)} - Specify which corners are chamfered. The corners are identified by + Specifies which corners are chamfered. The corners are identified by their ``compass point'' directions (i.e. |north east|, |north west|, |south west|, and |south east|), and must be separated by commas (so if there is more than one corner in the list, it must be surrounded diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex index dc6f163929f..3f4aad69293 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex @@ -69,7 +69,7 @@ make this possible: implicitly set the |spy scope|. \item Inside this scope you may then use the command |\spy|, which is - only available inside such scopes (so there is no danger of your + only available inside such scopes (so there is no danger of you inadvertently using this command outside such a scope). This command has a special syntax and will (at some point) create two nodes: One node that shows the magnified picture (called the \emph{spy-in @@ -118,7 +118,7 @@ computed automatically. following effects: \begin{itemize} \item It resets a number of graphic state parameters, including the - color, line style, and other. This is necessary for technical + color, line style, and others. This is necessary for technical reasons. \item It tells \tikzname\ that the content of the scope should be saved internally in a special box. @@ -130,13 +130,13 @@ computed automatically. |\spy| is used, these \meta{options} will be used. \item Three keys are defined that provide useful shortcuts: \begin{key}{/tikz/size=\meta{dimension}} - Inside a |spy scope|, |size| this is a shortcut for |minimum size|. + Inside a |spy scope|, this is a shortcut for |minimum size|. \end{key} \begin{key}{/tikz/height=\meta{dimension}} - Inside a |spy scope|, |height| this is a shortcut for |minimum height|. + Inside a |spy scope|, this is a shortcut for |minimum height|. \end{key} \begin{key}{/tikz/width=\meta{dimension}} - Inside a |spy scope|, |width| this is a shortcut for |minimum width|. + Inside a |spy scope|, this is a shortcut for |minimum width|. \end{key} \end{itemize} It is permissible to nest |spy scopes|. In this case, all |\spy| @@ -172,7 +172,7 @@ computed automatically. \subsection{The Spy Command} \begin{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate} - |in node| \meta{node options}|;|} + \texttt{in node} \meta{node options}|;|} This command can only be used inside a |spy scope|. Let us start with the syntax: \begin{itemize} \item The |\spy| command is not a special case of |\path|. Rather, @@ -207,7 +207,7 @@ computed automatically. To be precise, the picture of the |spy scope| is scaled by a certain factor, specified by the |lens| or |magnification| options - discussed below, and the shifted in such a way that the + discussed below, and is shifted in such a way that the \meta{coordinate} lies at the center of the spy-on node. \item The \emph{spy-on node} is a node that is centered on the \meta{coordinate} and whose size reflects exactly the area shown @@ -230,7 +230,7 @@ computed automatically. effect caused by the \meta{options} and the options of the |{spy scope}|. Additionally, the following style is used: \begin{stylekey}{/tikz/every spy in node} - This style is used with every spy in node. + This style is used with every spy-in node. \end{stylekey} The position of the node (the |at| option) is set to the \meta{coordinate} by default, so that it will cover the @@ -270,7 +270,7 @@ computed automatically. size. Note that the key |size| is an abbreviation for |minimum size| inside a spy scope. - You can name the spy on node in the usual ways. Additionally, the + You can name the spy-on node in the usual ways. Additionally, the node is (also) always named |tikzspyinnode|. Following the spy scope, you can use this node like any other node: \begin{codeexample}[] @@ -326,7 +326,7 @@ computed automatically. Like for the spy-in node, a style can be used to format the spy-on node: \begin{stylekey}{/tikz/every spy on node} - This style is used with every spy on node. + This style is used with every spy-on node. \end{stylekey} The spy-on node is named |tikzspyonnode| (but, as always, this node is only available after the spy scope). If you have multiple @@ -344,7 +344,7 @@ computed automatically. There are some predefined styles that make using the |spy| library easier. The following two styles can be used instead of |spy scope|, they pass their \meta{options} directly to |spy scope|. They -additionally setup the graphic styles to be used for the spy-in nodes +additionally set up the graphic styles to be used for the spy-in nodes and the spy-on nodes in some special way. \begin{key}{/tikz/spy using outlines=\meta{options} (default diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-svg-path.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-svg-path.tex index cafe102caad..ea6b2a73263 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-svg-path.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-svg-path.tex @@ -13,7 +13,7 @@ \begin{pgflibrary}{svg.path} This library defines a command that allows you to specify a path - using the svg-syntax. + using the \textsc{svg}-syntax. \end{pgflibrary} \begin{command}{\pgfpathsvg\marg{path}} @@ -24,16 +24,16 @@ In principle, the complete syntax is supported and the library just provides a parser and a mapping to basic layer commands. For instance, |M 0 10| is mapped to - |\pgfpathmoveto{\pgfpoint{0pt}{10pt}}|. There, however, a few things + |\pgfpathmoveto{\pgfpoint{0pt}{10pt}}|. There are, however, a few things to be aware of: \begin{itemize} \item The computation underlying the arc commands |A| and |a| are not numerically stable, which may result in quite imprecise arcs. B\'ezier curves, both quadratic and cubic, are not affected, - and also not arcs spanning degrees that are multiples of - $90^\circ$. + neither are arcs spanning degrees that are multiples of + $90^{\circ}$. \item The dimensionless units of \textsc{svg} are always interpreted - at points (|pt|). This is a problem with paths like |M 20000 0|, + as points (|pt|). This is a problem with paths like |M 20000 0|, which will raise an error message since \TeX\ cannot handle dimensions larger than about 16000 points. \item diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-trees.tex index d95dd5e2106..7fd7974023c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-trees.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-trees.tex @@ -22,8 +22,8 @@ The package |trees| defines two new growth functions. They are installed using the following options: -\begin{key}{/tikz/grow via three points=|one child at (|\meta{x}% - |) and two children at (|\meta{y}|) and (|\meta{z}|)|} +\begin{key}{/tikz/grow via three points=\texttt{one child at (}\meta{x}% + \texttt{) and two children at (}\meta{y}\texttt{) and (}\meta{z}|)|} This option installs a growth function that works as follows: If a parent node has just one child, this child is placed at \meta{x}. If the parent node has two children, these are placed at \meta{y} and @@ -82,7 +82,7 @@ functions. They are installed using the following options: \begin{key}{/tikz/grow cyclic} This style causes the children to be arranged ``on a circle.'' For this, the children are placed at distance |\tikzleveldistance| from - the parent node, but not on a straight line, but points on a + the parent node, but not on a straight line, but on points on a circle. Instead of a sibling distance, there is a |sibling angle| that denotes the angle between two given children. \begin{key}{/tikz/sibling angle=\meta{angle}} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-turtle.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-turtle.tex index ffb35b231d4..46198942e5a 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-turtle.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-turtle.tex @@ -28,7 +28,7 @@ Even though the |turtle| keys looks like an option, it uses the The basic drawing model behind the turtle graphics is very simple: There is a (virtual) \emph{turtle} that crawls around the page, thereby extending the path. The turtle always heads in a certain -direction. When you move the turtle forward you extend the path in +direction. When you move the turtle forward, you extend the path in that direction; turning the turtle just changes the direction, it does not cause anything to be drawn. @@ -63,7 +63,7 @@ independently of other path commands. the operation |to[turtle/how]| is used to extend the path to this point. \begin{stylekey}{/tikz/turtle/how (initially \normalfont empty)} - This style can setup the |to path| used by turtles. By setting + This style can set up the |to path| used by turtles. By setting this style you can change the to-path: \begin{codeexample}[] \tikz \draw [turtle={how/.style={bend left},home,forward,right,forward}]; diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-body.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-body.tex new file mode 100644 index 00000000000..1fdda1c63d9 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-body.tex @@ -0,0 +1,838 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\begin{document} + +% The titlepage + +\newbox\mybox +{ + \parindent0pt + \null + \colorlet{mintgreen}{green!50!black!50} + + \thispagestyle{empty} + \vskip3cm + \vfill + \hfil + \begin{tikzpicture}[overlay] + \coordinate (front) at (0,0); + \coordinate (horizon) at (0,.31\paperheight); + \coordinate (bottom) at (0,-.6\paperheight); + \coordinate (sky) at (0,.57\paperheight); + \coordinate (left) at (-.51\paperwidth,0); + \coordinate (right) at (.51\paperwidth,0); + + \shade [bottom color=blue!30!black!10,top color=blue!30!black!50] + ([yshift=-5mm]horizon -| left) rectangle (sky -| right); + \shade [bottom color=black!70!green!25,top color=black!70!green!10] + (front -| left) -- (horizon -| left) + decorate [decoration=random steps] { -- (horizon -| right) } + -- (front -| right) -- cycle; + \shade [top color=black!70!green!25,bottom color=black!25] + ([yshift=-5mm-1pt]front -| left) rectangle ([yshift=1pt]front -| right); + \fill [black!25] (bottom -| left) rectangle ([yshift=-5mm]front -| right); + + \def\nodeshadowed[#1]#2;{\node[scale=2,above,#1]{\global\setbox\mybox=\hbox{#2}\copy\mybox}; + \node[scale=2,above,#1,yscale=-1,scope fading=south,opacity=0.4]{\box\mybox};} + + \nodeshadowed [at={(-5,5 )},yslant=0.05] {\Huge Ti\textcolor{orange}{\emph{k}}Z}; + \nodeshadowed [at={( 0,5.3)}] {\huge \textcolor{mintgreen}{\&}}; + \nodeshadowed [at={( 5,5 )},yslant=-0.05] {\Huge \textsc{PGF}}; + \nodeshadowed [at={( 0,2 )}] {Manual for Version \pgftypesetversion}; + + \foreach \where in {-9cm,9cm} + {\nodeshadowed [at={(\where,5cm)}] { + \tikz \draw [green!20!black, rotate=90] + [l-system={rule set={F -> FF-[-F+F]+[+F-F]}, axiom=F, order=4, + step=2pt, randomize step percent=50, angle=30, randomize angle percent=5}] + lindenmayer system;};} + + \foreach \i in {0.5,0.6,...,2} + \fill [white,decoration=Koch snowflake,opacity=.9] + [shift=(horizon),shift={(rand*11,rnd*7)},scale=\i] + [double copy shadow={opacity=0.2,shadow xshift=0pt,shadow + yshift=3*\i pt,fill=white,draw=none}] + decorate { + decorate { + decorate { + (0,0) -- ++(60:1) -- ++(-60:1) -- cycle + } + } + }; + + \node (left text) [text width=.5\paperwidth-2cm,below right,at={(-.5\paperwidth+1cm,-1.5cm)}] + { + \fontfamily{pcr} + \def\textbraceleft{\char`\{} + \def\textbraceright{\char`\}} + \def\textbackslash{\char`\\} + \begin{lstlisting}[basicstyle=\scriptsize\color{black}, + keywordstyle=\bfseries\color{white}, + identifierstyle=\bfseries\color{black}, + keywords={tikzpicture,shade,fill,draw,path,node}, + literate={-}{{-}}1] +\begin{tikzpicture} + \coordinate (front) at (0,0); + \coordinate (horizon) at (0,.31\paperheight); + \coordinate (bottom) at (0,-.6\paperheight); + \coordinate (sky) at (0,.57\paperheight); + \coordinate (left) at (-.51\paperwidth,0); + \coordinate (right) at (.51\paperwidth,0); + + \shade [bottom color=white, + top color=blue!30!black!50] + ([yshift=-5mm]horizon -| left) + rectangle (sky -| right); + + \shade [bottom color=black!70!green!25, + top color=black!70!green!10] + (front -| left) -- (horizon -| left) + decorate [decoration=random steps] { + -- (horizon -| right) } + -- (front -| right) -- cycle; + + \shade [top color=black!70!green!25, + bottom color=black!25] + ([yshift=-5mm-1pt]front -| left) + rectangle ([yshift=1pt]front -| right); + + \fill [black!25] + (bottom -| left) + rectangle ([yshift=-5mm]front -| right); + + \def\nodeshadowed[#1]#2;{ + \node[scale=2,above,#1]{ + \global\setbox\mybox=\hbox{#2} + \copy\mybox}; + \node[scale=2,above,#1,yscale=-1, + scope fading=south,opacity=0.4]{\box\mybox}; + } +\end{lstlisting} +}; + + \node (right text) [text width=.5\paperwidth-2cm,below right,at={(1cm,-1.5cm)}] + { + \fontfamily{pcr} + \def\textbraceleft{\char`\{} + \def\textbraceright{\char`\}} + \def\textbackslash{\char`\\} + \begin{lstlisting}[basicstyle=\scriptsize\color{black}, + keywordstyle=\bfseries\color{white}, + identifierstyle=\bfseries\color{black}, + keywords={tikzpicture,shade,fill,draw,path,node}, + literate={-}{{-}}1] + \nodeshadowed [at={(-5,8 )},yslant=0.05] + {\Huge Ti\textcolor{orange}{\emph{k}}Z}; + \nodeshadowed [at={( 0,8.3)}] + {\huge \textcolor{green!50!black!50}{\&}}; + \nodeshadowed [at={( 5,8 )},yslant=-0.05] + {\Huge \textsc{PGF}}; + \nodeshadowed [at={( 0,5 )}] + {Manual for Version \pgftypesetversion}; + + \foreach \where in {-9cm,9cm} { + \nodeshadowed [at={(\where,5cm)}] { \tikz + \draw [green!20!black, rotate=90, + l-system={rule set={F -> FF-[-F+F]+[+F-F]}, + axiom=F, order=4,step=2pt, + randomize step percent=50, angle=30, + randomize angle percent=5}] l-system; }} + + \foreach \i in {0.5,0.6,...,2} + \fill + [white,opacity=\i/2, + decoration=Koch snowflake, + shift=(horizon),shift={(rand*11,rnd*7)}, + scale=\i,double copy shadow={ + opacity=0.2,shadow xshift=0pt, + shadow yshift=3*\i pt,fill=white,draw=none}] + decorate { + decorate { + decorate { + (0,0)- ++(60:1) -- ++(-60:1) -- cycle + } } }; + + \node (left text) ... + \node (right text) ... + + \fill [decorate,decoration={footprints,foot of=gnome}, + opacity=.5,brown] (rand*8,-rnd*10) + to [out=rand*180,in=rand*180] (rand*8,-rnd*10); +\end{tikzpicture} + \end{lstlisting} + }; + + \fill [decorate,decoration=footprints, + decoration={footprints,foot of=gnome}, + opacity=.5,brown] (rand*8,-rnd*10) + to [out=rand*180,in=rand*180] (rand*8,-rnd*10); +\end{tikzpicture} +\vfill +\vbox{} +\clearpage +} + +{ + \vbox{} + \vskip0pt plus 1fill + F\"ur meinen Vater, damit er noch viele sch\"one \TeX-Graphiken + erschaffen kann. + \vskip1em + \hfill\emph{Till} + \vskip0pt plus 3fill + + \parindent=0pt + Copyright 2007 to 2013 by Till Tantau + + \medskip + Permission is granted to copy, distribute and/or modify \emph{the documentation} + under the terms of the \textsc{gnu} Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled \textsc{gnu} + Free Documentation License. + + \medskip + Permission is granted to copy, distribute and/or modify \emph{the + code of the package} under the terms of the \textsc{gnu} Public License, Version 2 + or any later version published by the Free Software Foundation. + A copy of the license is included in the section entitled \textsc{gnu} + Public License. + + \medskip + Permission is also granted to distribute and/or modify \emph{both + the documentation and the code} under the conditions of the LaTeX + Project Public License, either version 1.3 of this license or (at + your option) any later version. A copy of the license is included in + the section entitled \LaTeX\ Project Public License. + + \vbox{} + \clearpage +} + + +\title{\bfseries The \tikzname\ and {\Large PGF} Packages\\ + \large Manual for version \pgfversion\\[1mm] +\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}} +\author{Till Tantau\footnote{Editor of this documentation. Parts of + this documentation have been written by other authors as indicated + in these parts or chapters and in Section~\ref{section-authors}.}\\ + \normalsize Institut f\"ur Theoretische Informatik\\[-1mm] + \normalsize Universit\"at zu L\"ubeck} + +\maketitle + +\tableofcontents + +\clearpage + + +\include{pgfmanual-en-introduction} + + +\part{Tutorials and Guidelines} + +{\Large \emph{by Till Tantau}} + +\bigskip +\noindent +To help you get started with \tikzname, instead of a long installation +and configuration section, this manual starts with tutorials. They +explain all the basic and some of the more advanced features of the +system, without going into all the details. This part also contains +some guidelines on how you should proceed when creating graphics using +\tikzname. + +\vskip3cm + +\begin{codeexample}[graphic=white,width=0pt] +\tikz \draw[thick,rounded corners=8pt] + (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0); +\end{codeexample} + +\include{pgfmanual-en-tutorial} +\include{pgfmanual-en-tutorial-nodes} +\include{pgfmanual-en-tutorial-Euclid} +\include{pgfmanual-en-tutorial-chains} +\include{pgfmanual-en-tutorial-map} +\include{pgfmanual-en-guidelines} + + + +\part{Installation and Configuration} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +This part explains how the system is installed. Typically, someone has +already done so for your system, so this part can be skipped; but if +this is not the case and you are the poor fellow who has to do the +installation, read the present part. + + +\vskip1cm + +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[->,>=stealth',shorten >=1pt,auto,node distance=2.8cm,on grid,semithick, + every state/.style={fill=red,draw=none,circular drop shadow,text=white}] + + \node[initial,state] (A) {$q_a$}; + \node[state] (B) [above right=of A] {$q_b$}; + \node[state] (D) [below right=of A] {$q_d$}; + \node[state] (C) [below right=of B] {$q_c$}; + \node[state] (E) [below=of D] {$q_e$}; + + \path (A) edge node {0,1,L} (B) + edge node {1,1,R} (C) + (B) edge [loop above] node {1,1,L} (B) + edge node {0,1,L} (C) + (C) edge node {0,1,L} (D) + edge [bend left] node {1,0,R} (E) + (D) edge [loop below] node {1,1,R} (D) + edge node {0,1,R} (A) + (E) edge [bend left] node {1,0,R} (A); + + \node [right=1cm,text width=8cm] at (C) + { + The current candidate for the busy beaver for five states. It is + presumed that this Turing machine writes a maximum number of + $1$'s before halting among all Turing machines with five states + and the tape alphabet $\{0, 1\}$. Proving this conjecture is an + open research problem. + }; +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-en-installation} +\include{pgfmanual-en-license} +\include{pgfmanual-en-drivers} + + +\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} +\label{part-tikz} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +\vskip3cm +\begin{codeexample}[graphic=white] + +\begin{tikzpicture}[angle radius=.75cm] + + \node (A) at (-2,0) [red,left] {$A$}; + \node (B) at ( 3,.5) [red,right] {$B$}; + \node (C) at (-2,2) [blue,left] {$C$}; + \node (D) at ( 3,2.5) [blue,right] {$D$}; + \node (E) at (60:-5mm) [below] {$E$}; + \node (F) at (60:3.5cm) [above] {$F$}; + + \coordinate (X) at (intersection cs:first line={(A)--(B)}, second line={(E)--(F)}); + \coordinate (Y) at (intersection cs:first line={(C)--(D)}, second line={(E)--(F)}); + + \path + (A) edge [red, thick] (B) + (C) edge [blue, thick] (D) + (E) edge [thick] (F) + pic ["$\alpha$", draw, fill=yellow] {angle = F--X--A} + pic ["$\beta$", draw, fill=green!30] {angle = B--X--F} + pic ["$\gamma$", draw, fill=yellow] {angle = E--Y--D} + pic ["$\delta$", draw, fill=green!30] {angle = C--Y--E}; + + \node at ($ (D)!.5!(B) $) [right=1cm,text width=6cm,rounded corners,fill=red!20,inner sep=1ex] + { + When we assume that $\color{red}AB$ and $\color{blue}CD$ are + parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$, + then $\alpha = \delta$ and $\beta = \gamma$. + }; +\end{tikzpicture} +\end{codeexample} + + + +\include{pgfmanual-en-tikz-design} +\include{pgfmanual-en-tikz-scopes} +\include{pgfmanual-en-tikz-coordinates} +\include{pgfmanual-en-tikz-paths} +\include{pgfmanual-en-tikz-actions} +\include{pgfmanual-en-tikz-arrows} +\include{pgfmanual-en-tikz-shapes} +\include{pgfmanual-en-tikz-pics} +\include{pgfmanual-en-tikz-graphs} +\include{pgfmanual-en-tikz-matrices} +\include{pgfmanual-en-tikz-trees} +\include{pgfmanual-en-tikz-plots} +\include{pgfmanual-en-tikz-transparency} +\include{pgfmanual-en-tikz-decorations} +\include{pgfmanual-en-tikz-transformations} + + +\part{Graph Drawing} +\label{part-gd} + +{\Large \emph{by Till Tantau et al.}} + +\bigskip +\noindent +\emph{Graph drawing algorithms} do the tough work of computing a +layout of a graph for you. \tikzname\ comes with powerful +such algorithms, but you can also implement new algorithms in the +Lua programming language. +\vskip1cm + +\ifluatex +\begin{codeexample}[graphic=white] +\tikz [nodes={text height=.7em, text depth=.2em, + draw=black!20, thick, fill=white, font=\footnotesize}, + >=spaced stealth', rounded corners, semithick] + \graph [layered layout, level distance=1cm, sibling sep=.5em, sibling distance=1cm] { + "5th Edition" -> { "6th Edition", "PWB 1.0" }; + "6th Edition" -> { "LSX" [>child anchor=45], "1 BSD", "Mini Unix", "Wollongong", "Interdata" }; + "Interdata" -> { "Unix/TS 3.0", "PWB 2.0", "7th Edition" }; + "7th Edition" -> { "8th Edition", "32V", "V7M", "Ultrix-11", "Xenix", "UniPlus+" }; + "V7M" -> "Ultrix-11"; + "8th Edition" -> "9th Edition"; + "1 BSD" -> "2 BSD" -> "2.8 BSD" -> { "Ultrix-11", "2.9 BSD" }; + "32V" -> "3 BSD" -> "4 BSD" -> "4.1 BSD" -> { "4.2 BSD", "2.8 BSD", "8th Edition" }; + "4.2 BSD" -> { "4.3 BSD", "Ultrix-32" }; + "PWB 1.0" -> { "PWB 1.2" -> "PWB 2.0", "USG 1.0" -> { "CB Unix 1", "USG 2.0" }}; + "CB Unix 1" -> "CB Unix 2" -> "CB Unix 3" -> { "Unix/TS++", "PDP-11 Sys V" }; + { "USG 2.0" -> "USG 3.0", "PWB 2.0", "Unix/TS 1.0" } -> "Unix/TS 3.0"; + { "Unix/TS++", "CB Unix 3", "Unix/TS 3.0" } -> "TS 4.0" -> "System V.0" -> "System V.2" -> "System V.3"; + }; +\end{codeexample} + +\else +You need to use Lua\TeX\ to typeset this part of the manual (and, +also, to use algorithmic graph drawing). +\fi + +\include{pgfmanual-en-gd-overview} +\include{pgfmanual-en-gd-usage-tikz} +\include{pgfmanual-en-gd-usage-pgf} +\include{pgfmanual-en-gd-trees} +\include{pgfmanual-en-gd-layered} +\include{pgfmanual-en-gd-force} +\include{pgfmanual-en-gd-circular} +\include{pgfmanual-en-gd-phylogenetics} +\include{pgfmanual-en-gd-ogdf} +\include{pgfmanual-en-gd-algorithm-layer} +\include{pgfmanual-en-gd-algorithms-in-c} +\include{pgfmanual-en-gd-display-layer} +\include{pgfmanual-en-gd-binding-layer} + + +\part{Libraries} +\label{part-libraries} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +In this part the library packages are documented. They +provide additional predefined graphic objects like new arrow heads or +new plot marks, but sometimes also extensions of the basic \pgfname\ +or \tikzname\ system. The libraries are not loaded by default since +many users will not need them. + +\medskip +\noindent +\begin{codeexample}[graphic=white] +\tikzset{ + ld/.style={level distance=#1},lw/.style={line width=#1}, + level 1/.style={ld=4.5mm, trunk, lw=1ex ,sibling angle=60}, + level 2/.style={ld=3.5mm, trunk!80!leaf a,lw=.8ex,sibling angle=56}, + level 3/.style={ld=2.75mm,trunk!60!leaf a,lw=.6ex,sibling angle=52}, + level 4/.style={ld=2mm, trunk!40!leaf a,lw=.4ex,sibling angle=48}, + level 5/.style={ld=1mm, trunk!20!leaf a,lw=.3ex,sibling angle=44}, + level 6/.style={ld=1.75mm,leaf a, lw=.2ex,sibling angle=40}, +} +\pgfarrowsdeclare{leaf}{leaf} + {\pgfarrowsleftextend{-2pt} \pgfarrowsrightextend{1pt}} +{ + \pgfpathmoveto{\pgfpoint{-2pt}{0pt}} + \pgfpatharc{150}{30}{1.8pt} + \pgfpatharc{-30}{-150}{1.8pt} + \pgfusepathqfill +} + +\newcommand{\logo}[5] +{ + \colorlet{border}{#1} + \colorlet{trunk}{#2} + \colorlet{leaf a}{#3} + \colorlet{leaf b}{#4} + \begin{tikzpicture} + \scriptsize\scshape + \draw[border,line width=1ex,yshift=.3cm, + yscale=1.45,xscale=1.05,looseness=1.42] + (1,0) to [out=90, in=0] (0,1) to [out=180,in=90] (-1,0) + to [out=-90,in=-180] (0,-1) to [out=0, in=-90] (1,0) -- cycle; + + \coordinate (root) [grow cyclic,rotate=90] + child { + child [line cap=round] foreach \a in {0,1} { + child foreach \b in {0,1} { + child foreach \c in {0,1} { + child foreach \d in {0,1} { + child foreach \leafcolor in {leaf a,leaf b} + { edge from parent [color=\leafcolor,-#5] } + } } } + } edge from parent [shorten >=-1pt,serif cm-,line cap=butt] + }; + + \node [align=center,below] at (0pt,-.5ex) + { \textcolor{border}{T}heoretical \\ \textcolor{border}{C}omputer \\ + \textcolor{border}{S}cience }; + \end{tikzpicture} +} +\begin{minipage}{3cm} + \logo{green!80!black}{green!25!black}{green}{green!80}{leaf}\\ + \logo{green!50!black}{black}{green!80!black}{red!80!green}{leaf}\\ + \logo{red!75!black}{red!25!black}{red!75!black}{orange}{leaf}\\ + \logo{black!50}{black}{black!50}{black!25}{} +\end{minipage} +\end{codeexample} + +\include{pgfmanual-en-library-angles} +\include{pgfmanual-en-library-arrows} +\include{pgfmanual-en-library-automata} +\include{pgfmanual-en-library-babel} +\include{pgfmanual-en-library-backgrounds} +\include{pgfmanual-en-library-calc} +\include{pgfmanual-en-library-calendar} +\include{pgfmanual-en-library-chains} +\include{pgfmanual-en-library-circuits} +\include{pgfmanual-en-library-decorations} +\include{pgfmanual-en-library-er} +\include{pgfmanual-en-library-external} +\include{pgfmanual-en-library-fadings} +\include{pgfmanual-en-library-fit} +\include{pgfmanual-en-library-fixedpoint} +\include{pgfmanual-en-library-fpu} +\include{pgfmanual-en-library-lsystems} +\include{pgfmanual-en-library-math} +\include{pgfmanual-en-library-matrices} +\include{pgfmanual-en-library-mindmaps} +\include{pgfmanual-en-library-folding} +\include{pgfmanual-en-library-patterns} +\include{pgfmanual-en-library-petri} +\include{pgfmanual-en-library-plot-handlers} +\include{pgfmanual-en-library-plot-marks} +\include{pgfmanual-en-library-profiler} +\include{pgfmanual-en-library-shadings} +\include{pgfmanual-en-library-shadows} +\include{pgfmanual-en-library-shapes} +\include{pgfmanual-en-library-spy} +\include{pgfmanual-en-library-svg-path} +\include{pgfmanual-en-library-edges} +\include{pgfmanual-en-library-through} +\include{pgfmanual-en-library-trees} +\include{pgfmanual-en-library-turtle} + + +\part{Data Visualization} +\label{part-dv} + +{\Large \emph{by Till Tantau}} + +\bigskip +\noindent + +\begin{codeexample}[graphic=white] +\tikz \datavisualization [scientific axes=clean] +[ + visualize as smooth line=Gaussian, + Gaussian={pin in data={text={$e^{-x^2}$},when=x is 1}} +] +data [format=function] { + var x : interval [-7:7] samples 51; + func y = exp(-\value x*\value x); +} +[ + visualize as scatter, + legend={south east outside}, + scatter={ + style={mark=*,mark size=1.4pt}, + label in legend={text={ + $\sum_{i=1}^{10} x_i$, where $x_i \sim U(-1,1) $}}} +] +data [format=function] { + var i : interval [0:1] samples 20; + func y = 0; + func x = (rand + rand + rand + rand + rand + + rand + rand + rand + rand + rand); +}; +\end{codeexample} + +\include{pgfmanual-en-dv-introduction} +\include{pgfmanual-en-dv-main} +\include{pgfmanual-en-dv-formats} +\include{pgfmanual-en-dv-axes} +\include{pgfmanual-en-dv-visualizers} +\include{pgfmanual-en-dv-stylesheets} +\include{pgfmanual-en-dv-polar} +\include{pgfmanual-en-dv-backend} + + +\part{Utilities} +\label{part-utilities} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +The utility packages are not directly involved in creating graphics, +but you may find them useful nonetheless. All of them either directly +depend on \pgfname\ or they are designed to work well together with +\pgfname\ even though they can be used in a stand-alone way. + +\vskip2cm +\medskip +\noindent +\begin{codeexample}[graphic=white] +\begin{tikzpicture}[scale=2] + \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0); + \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$}; + + \draw[help lines] (0,0) grid (3.9,3.9) + [step=0.25cm] (1,2) grid +(1,1); + + \draw[->] (-0.2,0) -- (4,0) node[right] {$x$}; + \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$}; + + \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3} + \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$}; + + \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3} + \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$}; + + \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$}; +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-en-pgfkeys} +\include{pgfmanual-en-pgffor} +\include{pgfmanual-en-pgfcalendar} +\include{pgfmanual-en-pages} +\include{pgfmanual-en-xxcolor} +\include{pgfmanual-en-module-parser} + + +\part{Mathematical and Object-Oriented Engines} + +{\Large \emph{by Mark Wibrow and Till Tantau}} + + +\bigskip +\noindent +\pgfname\ comes with two useful engines: One for doing mathematics, +one for doing object-oriented programming. Both engines can be used +independently of the main \pgfname. + +The job of the mathematical +engine is to support mathematical operations like addition, +subtraction, multiplication and division, using both integers and +non-integers, but also functions such as square-roots, sine, cosine, +and generate pseudo-random numbers. +Mostly, you will use the mathematical facilities of \pgfname\ +indirectly, namely when you write a coordinate like |(5cm*3,6cm/4)|, +but the mathematical engine can also be used independently of +\pgfname\ and \tikzname. + +The job of the object-oriented engine is to support simple +object-oriented programming in \TeX. It allows the definition of +\emph{classes} (without inheritance), \emph{methods}, +\emph{attributes} and \emph{objects}. + +\vskip1cm +\begin{codeexample}[graphic=white] +\pgfmathsetseed{1} +\foreach \col in {black,red,green,blue} +{ + \begin{tikzpicture}[x=10pt,y=10pt,ultra thick,baseline,line cap=round] + \coordinate (current point) at (0,0); + \coordinate (old velocity) at (0,0); + \coordinate (new velocity) at (rand,rand); + + \foreach \i in {0,1,...,100} + { + \draw[\col!\i] (current point) + .. controls ++([scale=-1]old velocity) and + ++(new velocity) .. ++(rand,rand) + coordinate (current point); + \coordinate (old velocity) at (new velocity); + \coordinate (new velocity) at (rand,rand); + } + \end{tikzpicture} +} +\end{codeexample} + +\include{pgfmanual-en-math-design} +\include{pgfmanual-en-math-parsing} +\include{pgfmanual-en-math-commands} +\include{pgfmanual-en-math-algorithms} +\include{pgfmanual-en-math-numberprinting} +\include{pgfmanual-en-oo} + + +\part{The Basic Layer} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9) + [step=0.25cm] (-1,-1) grid (1,1); + \draw[blue] (1,-2.1) -- (1,4.1); % asymptote + + \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$}; + \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$}; + + \foreach \pos in {-1,2} + \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$}; + + \foreach \pos in {-1,1,2,3} + \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$}; + + \fill (0,0) circle (0.064cm); + \draw[thick,parametric,domain=0.4:1.5,samples=200] + % The plot is reparameterised such that there are more samples + % near the center. + plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))} + node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$}; + + \fill[red] (0.63662,0) circle (2pt) + node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$}; +\end{tikzpicture} +\end{codeexample} + + +\include{pgfmanual-en-base-design} +\include{pgfmanual-en-base-scopes} +\include{pgfmanual-en-base-points} +\include{pgfmanual-en-base-paths} +\include{pgfmanual-en-base-decorations} +\include{pgfmanual-en-base-actions} +\include{pgfmanual-en-base-arrows} +\include{pgfmanual-en-base-nodes} +\include{pgfmanual-en-base-matrices} +\include{pgfmanual-en-base-transformations} +\include{pgfmanual-en-base-patterns} +\include{pgfmanual-en-base-images} +\include{pgfmanual-en-base-external} +\include{pgfmanual-en-base-plots} +\include{pgfmanual-en-base-layers} +\include{pgfmanual-en-base-shadings} +\include{pgfmanual-en-base-transparency} +\include{pgfmanual-en-base-internalregisters} +\include{pgfmanual-en-base-quick} + + + + +\part{The System Layer} +\label{part-system} + +{\Large \emph{by Till Tantau}} + + +\bigskip +\noindent +This part describes the low-level interface of \pgfname, called the +\emph{system layer}. This interface provides a complete abstraction of +the internals of the underlying drivers. + +Unless you intend to port \pgfname\ to another driver or unless you intend +to write your own optimized frontend, you need not read this part. + +In the following it is assumed that you are familiar with the basic +workings of the |graphics| package and that you know what +\TeX-drivers are and how they work. + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + [shorten >=1pt,->, + vertex/.style={circle,fill=black!25,minimum size=17pt,inner sep=0pt}] + + \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16} + \node[vertex] (G-\name) at (\x,0) {$\name$}; + + \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9} + \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14} + \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; + + \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t} + \draw (G-\from) -- (G-\to); + + \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2} + { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); } + + \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1); + \draw (Q-5) -- (G-15); +\end{tikzpicture} +\end{codeexample} + +\include{pgfmanual-en-pgfsys-overview} +\include{pgfmanual-en-pgfsys-commands} +\include{pgfmanual-en-pgfsys-paths} +\include{pgfmanual-en-pgfsys-protocol} + + + +\part{References and Index} + +\vskip1cm +\begin{codeexample}[graphic=white] +\begin{tikzpicture} + \draw[line width=0.3cm,color=red!30,line cap=round,line join=round] (0,0)--(2,0)--(2,5); + \draw[help lines] (-2.5,-2.5) grid (5.5,7.5); + \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)-- + (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)-- + (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5) + (3,3)--(4,3)--(4,5)--(3,5)--(3,6) + (3,-1)--(4,-1); + \draw[below left] (0,0) node(s){$s$}; + \draw[below left] (2,5) node(t){$t$}; + \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm); + \draw[->,rounded corners=0.2cm,shorten >=2pt] + (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)-- + ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)-- + ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)-- + ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)-- + ++(0,-1)-- ++(1,0); +\end{tikzpicture} +\end{codeexample} + +\printindex + +%\typeout{Examples: \the\codeexamplecount}% +\end{document} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "~/pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual" +%%% coding: iso-latin-1-unix +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-preamble.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-preamble.tex new file mode 100644 index 00000000000..9922ac79219 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main-preamble.tex @@ -0,0 +1,223 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\def\xcolorversion{2.00} + +\usepackage[version=latest]{pgf} + +\usepackage{xkeyval,calc,listings,tikz,fp} + +\usepackage{hyperref} +\hypersetup{% + colorlinks=false, % use true to enable colors below: + linkcolor=blue,%red, + filecolor=blue,%magenta, + urlcolor=blue,%cyan, + citecolor=blue, + pdfborder=0 0 0, +} + +% We need lots of libraries... +\usetikzlibrary{ + arrows, + arrows.spaced, + arrows.meta, + bending, + babel, + calc, + fit, + patterns, + plotmarks, + shapes.geometric, + shapes.misc, + shapes.symbols, + shapes.arrows, + shapes.callouts, + shapes.multipart, + shapes.gates.logic.US, + shapes.gates.logic.IEC, + circuits.logic.US, + circuits.logic.IEC, + circuits.logic.CDH, + circuits.ee.IEC, + datavisualization, + datavisualization.polar, + datavisualization.formats.functions, + er, + automata, + backgrounds, + chains, + topaths, + trees, + petri, + mindmap, + matrix, + calendar, + folding, + fadings, + shadings, + spy, + through, + turtle, + positioning, + scopes, + decorations.fractals, + decorations.shapes, + decorations.text, + decorations.pathmorphing, + decorations.pathreplacing, + decorations.footprints, + decorations.markings, + shadows, + lindenmayersystems, + intersections, + fixedpointarithmetic, + fpu, + svg.path, + external, + graphs, + graphs.standard, + quotes, + math, + angles +} + +\usepackage{ifluatex} +\newif\ifgdccodebasic +\newif\ifgdccodeogdf + +\ifluatex + + \usetikzlibrary{graphdrawing} + \usegdlibrary{trees,circular,layered,examples,force,phylogenetics} + + % Test whether C code is available: + \directlua{ + if pcall(require,'pgf_gd_examples_c_SimpleDemoC') then + tex.print('\string\\gdccodebasictrue') + end + } + + \ifgdccodebasic + \usegdlibrary{pgf_gd_examples_c_SimpleDemoC,pgf_gd_examples_c_SimpleDemoCPlusPlus} + + % Test whether OGDF code is available: + \directlua{ + if pcall(require,'pgf_gd_ogdf_c_SimpleDemoOGDF') then + tex.print('\string\\gdccodeogdftrue') + end + } + + \ifgdccodeogdf + \usegdlibrary{pgf_gd_ogdf_c_SimpleDemoOGDF,ogdf} + \fi + + \fi + +\fi + +\def\LuaTeX{Lua\TeX}% + + + +\iffalse +%\iftrue + \tikzexternalize[ + mode=list only,export=true,% simply skips EVERY picture -> good for debugging the text. + ]{pgfmanual} + + \tikzifexternalizing{% + \pgfkeys{/pdflinks/codeexample links=false}% + }{}% +\fi + + +\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} +\usepackage{amsmath,amssymb} +\usepackage{xxcolor} +\usepackage{pifont} +\usepackage{makeidx} + +\ifluatex +% \usepackage[no-math]{fontspec} +% \usepackage{luatextra} + + % TT: I have commented luatextra since it loads fontspec, which + % currently breaks "$\mathrm{\Omega}$" (nothing is + % shown). Also, fontspec loads so much stuff, I'm not really sure + % any of it is needed... + + % \filedescription is defined in expl3, required by fontspec, + % required by luatextra. Needs to be \relaxed since + % pgfmanual-en-macros.tex defines an environment named filedescription + \let\filedescription\relax + \usepackage[utf8]{luainputenc} +\else + \usepackage[utf8]{inputenc} +\fi +\usepackage{amsmath} + +\graphicspath{{../../images/}} % TODOsp: under windows this would go up 2 directories, but the file is only one directory up +\input{../../macros/pgfmanual-en-macros} % TODOsp: same here + +\makeindex + +\makeatletter +\renewcommand*\l@section[2]{% + \ifnum \c@tocdepth >\z@ + \addpenalty\@secpenalty + \addvspace{1.0em \@plus\p@}% + \setlength\@tempdima{2.5em}% + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \bfseries + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par + \endgroup + \fi} +\renewcommand*\l@subsection{\@dottedtocline{2}{2.5em}{3.3em}} +\renewcommand*\l@subsubsection{\@dottedtocline{3}{5.8em}{4.2em}} +\def\@pnumwidth{2.2em} +\makeatother + +%\includeonly{pgfmanual-en-library-profiler} + +% Global styles: +\tikzset{ + every plot/.style={prefix=plots/pgf-}, + shape example/.style={ + color=black!30, + draw, + fill=yellow!30, + line width=.5cm, + inner xsep=2.5cm, + inner ysep=0.5cm} +} + +\index{Options for graphics|see{Graphic options and styles}} +\index{Styles for graphics|see{Graphic options and styles}} +\index{Options for packages|see{Package options}} +\index{Handlers for keys|see{Key handlers}} +\index{File|see{Packages and files}} +\index{Layout|see{Page layout}} +\index{Node|see{Predefined node}} +\index{Data formats|see{Formats}} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "~/pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual" +%%% coding: iso-latin-1-unix +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex index 9b4ba330dd4..55df7111ae1 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-main.tex @@ -7,890 +7,9 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. - -% pgf version is defined in \pgfversion in file -% generic/pgf/utilities/pgfrcs.code.tex - -\def\xcolorversion{2.00} - -\usepackage[version=latest]{pgf} - -\usepackage{xkeyval,calc,listings,tikz,fp} - -\usepackage{hyperref} -\hypersetup{% - colorlinks=true, % use true to enable colors below: - linkcolor=blue,%red, - filecolor=blue,%magenta, - pagecolor=blue,%red, - urlcolor=blue,%cyan, - citecolor=blue, - pdfborder=0 0 0, -} - -% We need lots of libraries... -\usetikzlibrary{ - arrows, - calc, - fit, - patterns, - plotmarks, - shapes.geometric, - shapes.misc, - shapes.symbols, - shapes.arrows, - shapes.callouts, - shapes.multipart, - shapes.gates.logic.US, - shapes.gates.logic.IEC, - circuits.logic.US, - circuits.logic.IEC, - circuits.logic.CDH, - circuits.ee.IEC, - datavisualization, - datavisualization.formats.functions, - er, - automata, - backgrounds, - chains, - topaths, - trees, - petri, - mindmap, - matrix, - calendar, - folding, - fadings, - shadings, - spy, - through, - turtle, - positioning, - scopes, - decorations.fractals, - decorations.shapes, - decorations.text, - decorations.pathmorphing, - decorations.pathreplacing, - decorations.footprints, - decorations.markings, - shadows, - lindenmayersystems, - intersections, - fixedpointarithmetic, - fpu, - svg.path, - external, -} - -\iffalse -%\iftrue - \tikzexternalize[ - mode=list only,export=true,% simply skips EVERY picture -> good for debugging the text. - ] - {pgfmanual} - - \tikzifexternalizing{% - \pgfkeys{/pdflinks/codeexample links=false}% - }{}% -\fi - - -\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} -\usepackage{amsmath,amssymb} -\usepackage{xxcolor} -\usepackage{pifont} -\usepackage{makeidx} -\usepackage[latin1]{inputenc} -\usepackage{amsmath} - -\graphicspath{{../../images/}} % TODOsp: under windows this would go up 2 directories, but the file is only one directory up -\input{../../macros/pgfmanual-en-macros} % TODOsp: same here - -\makeindex - -\makeatletter -\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.8em}} -\renewcommand*\l@subsubsection{\@dottedtocline{3}{4.3em}{3.2em}} -\makeatother - -%\includeonly{pgfmanual-en-library-profiler} - -% Global styles: -\tikzset{ - every plot/.style={prefix=plots/pgf-}, - shape example/.style={ - color=black!30, - draw, - fill=yellow!30, - line width=.5cm, - inner xsep=2.5cm, - inner ysep=0.5cm} -} - -\index{Options for graphics|see{Graphic options and styles}} -\index{Styles for graphics|see{Graphic options and styles}} -\index{Options for packages|see{Package options}} -\index{Handlers for keys|see{Key handlers}} -\index{File|see{Packages and files}} -\index{Layout|see{Page layout}} -\index{Node|see{Predefined node}} -\index{Data formats|see{Formats}} - -\begin{document} - - -%\include{pgfmanual-en-dv-introduction} -%\include{pgfmanual-en-dv-main} -%\include{pgfmanual-en-dv-axes} -%\include{pgfmanual-en-dv-visualizers} -%\include{pgfmanual-en-dv-examples} -%\include{pgfmanual-en-dv-formats} -%\include{pgfmanual-en-dv-backend} - -%\end{document} - -% The titlepage - -\newbox\mybox -{ - \parindent0pt - \null - \colorlet{mintgreen}{green!50!black!50} - - \thispagestyle{empty} - \vskip3cm - \vfill - \hfil - \begin{tikzpicture}[overlay] - \coordinate (front) at (0,0); - \coordinate (horizon) at (0,.31\paperheight); - \coordinate (bottom) at (0,-.6\paperheight); - \coordinate (sky) at (0,.57\paperheight); - \coordinate (left) at (-.51\paperwidth,0); - \coordinate (right) at (.51\paperwidth,0); - - \shade [bottom color=blue!30!black!10,top color=blue!30!black!50] - ([yshift=-5mm]horizon -| left) rectangle (sky -| right); - \shade [bottom color=black!70!green!25,top color=black!70!green!10] - (front -| left) -- (horizon -| left) - decorate [decoration=random steps] { -- (horizon -| right) } - -- (front -| right) -- cycle; - \shade [top color=black!70!green!25,bottom color=black!25] - ([yshift=-5mm-1pt]front -| left) rectangle ([yshift=1pt]front -| right); - \fill [black!25] (bottom -| left) rectangle ([yshift=-5mm]front -| right); - - \def\nodeshadowed[#1]#2;{\node[scale=2,above,#1]{\global\setbox\mybox=\hbox{#2}\copy\mybox}; - \node[scale=2,above,#1,yscale=-1,scope fading=south,opacity=0.4]{\box\mybox};} - - \nodeshadowed [at={(-5,5 )},yslant=0.05] {\Huge Ti\textcolor{orange}{\emph{k}}Z}; - \nodeshadowed [at={( 0,5.3)}] {\huge \textcolor{mintgreen}{\&}}; - \nodeshadowed [at={( 5,5 )},yslant=-0.05] {\Huge \textsc{PGF}}; - \nodeshadowed [at={( 0,2 )}] {Manual for Version \pgftypesetversion}; - - \foreach \where in {-9cm,9cm} - {\nodeshadowed [at={(\where,5cm)}] { - \tikz \draw [green!20!black, rotate=90] - [l-system={rule set={F -> FF-[-F+F]+[+F-F]}, axiom=F, order=4, - step=2pt, randomize step percent=50, angle=30, randomize angle percent=5}] - lindenmayer system;};} - - \foreach \i in {0.5,0.6,...,2} - \fill [white,decoration=Koch snowflake,opacity=.9] - [shift=(horizon),shift={(rand*11,rnd*7)},scale=\i] - [double copy shadow={opacity=0.2,shadow xshift=0pt,shadow - yshift=3*\i pt,fill=white,draw=none}] - decorate { - decorate { - decorate { - (0,0) -- ++(60:1) -- ++(-60:1) -- cycle - } - } - }; - - \node (left text) [text width=.5\paperwidth-2cm,below right,at={(-.5\paperwidth+1cm,-1.5cm)}] - { - \fontfamily{pcr} - \def\textbraceleft{\char`\{} - \def\textbraceright{\char`\}} - \def\textbackslash{\char`\\} - \begin{lstlisting}[basicstyle=\scriptsize\color{black}, - keywordstyle=\bfseries\color{white}, - identifierstyle=\bfseries\color{black}, - keywords={tikzpicture,shade,fill,draw,path,node}, - literate={-}{{-}}1] -\begin{tikzpicture} - \coordinate (front) at (0,0); - \coordinate (horizon) at (0,.31\paperheight); - \coordinate (bottom) at (0,-.6\paperheight); - \coordinate (sky) at (0,.57\paperheight); - \coordinate (left) at (-.51\paperwidth,0); - \coordinate (right) at (.51\paperwidth,0); - - \shade [bottom color=white, - top color=blue!30!black!50] - ([yshift=-5mm]horizon -| left) - rectangle (sky -| right); - - \shade [bottom color=black!70!green!25, - top color=black!70!green!10] - (front -| left) -- (horizon -| left) - decorate [decoration=random steps] { - -- (horizon -| right) } - -- (front -| right) -- cycle; - - \shade [top color=black!70!green!25, - bottom color=black!25] - ([yshift=-5mm-1pt]front -| left) - rectangle ([yshift=1pt]front -| right); - - \fill [black!25] - (bottom -| left) - rectangle ([yshift=-5mm]front -| right); - - \def\nodeshadowed[#1]#2;{ - \node[scale=2,above,#1]{ - \global\setbox\mybox=\hbox{#2} - \copy\mybox}; - \node[scale=2,above,#1,yscale=-1, - scope fading=south,opacity=0.4]{\box\mybox}; - } -\end{lstlisting} -}; - - \node (right text) [text width=.5\paperwidth-2cm,below right,at={(1cm,-1.5cm)}] - { - \fontfamily{pcr} - \def\textbraceleft{\char`\{} - \def\textbraceright{\char`\}} - \def\textbackslash{\char`\\} - \begin{lstlisting}[basicstyle=\scriptsize\color{black}, - keywordstyle=\bfseries\color{white}, - identifierstyle=\bfseries\color{black}, - keywords={tikzpicture,shade,fill,draw,path,node}, - literate={-}{{-}}1] - \nodeshadowed [at={(-5,8 )},yslant=0.05] - {\Huge Ti\textcolor{orange}{\emph{k}}Z}; - \nodeshadowed [at={( 0,8.3)}] - {\huge \textcolor{green!50!black!50}{\&}}; - \nodeshadowed [at={( 5,8 )},yslant=-0.05] - {\Huge \textsc{PGF}}; - \nodeshadowed [at={( 0,5 )}] - {Manual for Version \pgftypesetversion}; - - \foreach \where in {-9cm,9cm} { - \nodeshadowed [at={(\where,5cm)}] { \tikz - \draw [green!20!black, rotate=90, - l-system={rule set={F -> FF-[-F+F]+[+F-F]}, - axiom=F, order=4,step=2pt, - randomize step percent=50, angle=30, - randomize angle percent=5}] l-system; }} - - \foreach \i in {0.5,0.6,...,2} - \fill - [white,opacity=\i/2, - decoration=Koch snowflake, - shift=(horizon),shift={(rand*11,rnd*7)}, - scale=\i,double copy shadow={ - opacity=0.2,shadow xshift=0pt, - shadow yshift=3*\i pt,fill=white,draw=none}] - decorate { - decorate { - decorate { - (0,0)- ++(60:1) -- ++(-60:1) -- cycle - } } }; - - \node (left text) ... - \node (right text) ... - - \fill [decorate,decoration={footprints,foot of=gnome}, - opacity=.5,brown] (rand*8,-rnd*10) - to [out=rand*180,in=rand*180] (rand*8,-rnd*10); -\end{tikzpicture} - \end{lstlisting} - }; - - \fill [decorate,decoration=footprints, - decoration={footprints,foot of=gnome}, - opacity=.5,brown] (rand*8,-rnd*10) - to [out=rand*180,in=rand*180] (rand*8,-rnd*10); -\end{tikzpicture} -\vfill -\vbox{} -\clearpage -} - -{ - \vbox{} - \vskip0pt plus 1fill - Für meinen Vater, damit er noch viele schöne \TeX-Graphiken - erschaffen kann. - \vskip1em - \hfill\emph{Till} - \vskip0pt plus 3fill - - \parindent=0pt - Copyright 2007 by Till Tantau - - \medskip - Permission is granted to copy, distribute and/or modify \emph{the documentation} - under the terms of the \textsc{gnu} Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled \textsc{gnu} - Free Documentation License. - - \medskip - Permission is granted to copy, distribute and/or modify \emph{the - code of the package} under the terms of the \textsc{gnu} Public License, Version 2 - or any later version published by the Free Software Foundation. - A copy of the license is included in the section entitled \textsc{gnu} - Public License. - - \medskip - Permission is also granted to distribute and/or modify \emph{both - the documentation and the code} under the conditions of the LaTeX - Project Public License, either version 1.3 of this license or (at - your option) any later version. A copy of the license is included in - the section entitled \LaTeX\ Project Public License. - - \vbox{} - \clearpage -} - - -\title{\bfseries The \tikzname\ and {\Large PGF} Packages\\ - \large Manual for version \pgfversion\\[1mm] -\large\href{http://sourceforge.net/projects/pgf}{\texttt{http://sourceforge.net/projects/pgf}}} -\author{Till Tantau\footnote{Editor of this documentation. Parts of - this documentation have been written by other authors as indicated - in these parts or chapters and in Section~\ref{section-authors}.}\\ - \normalsize Institut f\"ur Theoretische Informatik\\[-1mm] - \normalsize Universit\"at zu L\"ubeck} - -\maketitle - -\tableofcontents - -\clearpage - - -\include{pgfmanual-en-introduction} - - -\part{Tutorials and Guidelines} - -{\Large \emph{by Till Tantau}} - -\bigskip -\noindent -To help you get started with \tikzname, instead of a long installation -and configuration section, this manual starts with tutorials. They -explain all the basic and some of the more advanced features of the -system, without going into all the details. This part also contains -some guidelines on how you should proceed when creating graphics using -\tikzname. - -\vskip3cm - -\begin{codeexample}[graphic=white,width=0pt] -\tikz \draw[thick,rounded corners=8pt] - (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0); -\end{codeexample} - -\include{pgfmanual-en-tutorial} -\include{pgfmanual-en-tutorial-nodes} -\include{pgfmanual-en-tutorial-Euclid} -\include{pgfmanual-en-tutorial-chains} -\include{pgfmanual-en-tutorial-map} -\include{pgfmanual-en-guidelines} - - - -\part{Installation and Configuration} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -This part explains how the system is installed. Typically, someone has -already done so for your system, so this part can be skipped; but if -this is not the case and you are the poor fellow who has to do the -installation, read the present part. - - -\vskip1cm - -\begin{codeexample}[graphic=white] -\begin{tikzpicture}[->,>=stealth',shorten >=1pt,auto,node distance=2.8cm,on grid,semithick, - every state/.style={fill=red,draw=none,circular drop shadow,text=white}] - - \node[initial,state] (A) {$q_a$}; - \node[state] (B) [above right=of A] {$q_b$}; - \node[state] (D) [below right=of A] {$q_d$}; - \node[state] (C) [below right=of B] {$q_c$}; - \node[state] (E) [below=of D] {$q_e$}; - - \path (A) edge node {0,1,L} (B) - edge node {1,1,R} (C) - (B) edge [loop above] node {1,1,L} (B) - edge node {0,1,L} (C) - (C) edge node {0,1,L} (D) - edge [bend left] node {1,0,R} (E) - (D) edge [loop below] node {1,1,R} (D) - edge node {0,1,R} (A) - (E) edge [bend left] node {1,0,R} (A); - - \node [right=1cm,text width=8cm] at (C) - { - The current candidate for the busy beaver for five states. It is - presumed that this Turing machine writes a maximum number of - $1$'s before halting among all Turing machines with five states - and the tape alphabet $\{0, 1\}$. Proving this conjecture is an - open research problem. - }; -\end{tikzpicture} -\end{codeexample} - -\include{pgfmanual-en-installation} -\include{pgfmanual-en-license} -\include{pgfmanual-en-drivers} - - -\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} -\label{part-tikz} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -\vskip3cm -\begin{codeexample}[graphic=white] -\begin{tikzpicture} - \draw[fill=yellow] (0,0) -- (60:.75cm) arc (60:180:.75cm); - \draw(120:0.4cm) node {$\alpha$}; - - \draw[fill=green!30] (0,0) -- (right:.75cm) arc (0:60:.75cm); - \draw(30:0.5cm) node {$\beta$}; - - \begin{scope}[shift={(60:2cm)}] - \draw[fill=green!30] (0,0) -- (180:.75cm) arc (180:240:.75cm); - \draw (30:-0.5cm) node {$\gamma$}; - - \draw[fill=yellow] (0,0) -- (240:.75cm) arc (240:360:.75cm); - \draw (-60:0.4cm) node {$\delta$}; - \end{scope} - - \begin{scope}[thick] - \draw (60:-1cm) node[fill=white] {$E$} -- (60:3cm) node[fill=white] {$F$}; - \draw[red] (-2,0) node[left] {$A$} -- (3,0) node[right]{$B$}; - \draw[blue,shift={(60:2cm)}] (-3,0) node[left] {$C$} -- (2,0) node[right]{$D$}; - - \draw[shift={(60:1cm)},xshift=4cm] - node [right,text width=6cm,rounded corners,fill=red!20,inner sep=1ex] - { - When we assume that $\color{red}AB$ and $\color{blue}CD$ are - parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$, - then $\alpha = \delta$ and $\beta = \gamma$. - }; - \end{scope} -\end{tikzpicture} -\end{codeexample} - - - -\include{pgfmanual-en-tikz-design} -\include{pgfmanual-en-tikz-scopes} -\include{pgfmanual-en-tikz-coordinates} -\include{pgfmanual-en-tikz-paths} -\include{pgfmanual-en-tikz-actions} -\include{pgfmanual-en-tikz-shapes} -\include{pgfmanual-en-tikz-matrices} -\include{pgfmanual-en-tikz-trees} -\include{pgfmanual-en-tikz-plots} -\include{pgfmanual-en-tikz-transparency} -\include{pgfmanual-en-tikz-decorations} -\include{pgfmanual-en-tikz-transformations} - - - -\part{Libraries} -\label{part-libraries} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -In this part the library packages are documented. They -provide additional predefined graphic objects like new arrow heads or -new plot marks, but also sometimes extensions of the basic \pgfname\ -or \tikzname\ system. The libraries are not loaded by default since -many users will not need them. - -\medskip -\noindent -\begin{codeexample}[graphic=white] -\tikzset{ - ld/.style={level distance=#1},lw/.style={line width=#1}, - level 1/.style={ld=4.5mm, trunk, lw=1ex ,sibling angle=60}, - level 2/.style={ld=3.5mm, trunk!80!leaf a,lw=.8ex,sibling angle=56}, - level 3/.style={ld=2.75mm,trunk!60!leaf a,lw=.6ex,sibling angle=52}, - level 4/.style={ld=2mm, trunk!40!leaf a,lw=.4ex,sibling angle=48}, - level 5/.style={ld=1mm, trunk!20!leaf a,lw=.3ex,sibling angle=44}, - level 6/.style={ld=1.75mm,leaf a, lw=.2ex,sibling angle=40}, -} -\pgfarrowsdeclare{leaf}{leaf} - {\pgfarrowsleftextend{-2pt} \pgfarrowsrightextend{1pt}} -{ - \pgfpathmoveto{\pgfpoint{-2pt}{0pt}} - \pgfpatharc{150}{30}{1.8pt} - \pgfpatharc{-30}{-150}{1.8pt} - \pgfusepathqfill -} - -\newcommand{\logo}[5] -{ - \colorlet{border}{#1} - \colorlet{trunk}{#2} - \colorlet{leaf a}{#3} - \colorlet{leaf b}{#4} - \begin{tikzpicture} - \scriptsize\scshape - \draw[border,line width=1ex,yshift=.3cm, - yscale=1.45,xscale=1.05,looseness=1.42] - (1,0) to [out=90, in=0] (0,1) to [out=180,in=90] (-1,0) - to [out=-90,in=-180] (0,-1) to [out=0, in=-90] (1,0) -- cycle; - - \coordinate (root) [grow cyclic,rotate=90] - child { - child [line cap=round] foreach \a in {0,1} { - child foreach \b in {0,1} { - child foreach \c in {0,1} { - child foreach \d in {0,1} { - child foreach \leafcolor in {leaf a,leaf b} - { edge from parent [color=\leafcolor,-#5] } - } } } - } edge from parent [shorten >=-1pt,serif cm-,line cap=butt] - }; - - \node [align=center,below] at (0pt,-.5ex) - { \textcolor{border}{T}heoretical \\ \textcolor{border}{C}omputer \\ - \textcolor{border}{S}cience }; - \end{tikzpicture} -} -\begin{minipage}{3cm} - \logo{green!80!black}{green!25!black}{green}{green!80}{leaf}\\ - \logo{green!50!black}{black}{green!80!black}{red!80!green}{leaf}\\ - \logo{red!75!black}{red!25!black}{red!75!black}{orange}{leaf}\\ - \logo{black!50}{black}{black!50}{black!25}{} -\end{minipage} -\end{codeexample} - -\include{pgfmanual-en-library-arrows} -\include{pgfmanual-en-library-automata} -\include{pgfmanual-en-library-backgrounds} -\include{pgfmanual-en-library-calc} -\include{pgfmanual-en-library-calendar} -\include{pgfmanual-en-library-chains} -\include{pgfmanual-en-library-circuits} -\include{pgfmanual-en-library-decorations} -\include{pgfmanual-en-library-er} -\include{pgfmanual-en-library-external} -\include{pgfmanual-en-library-fadings} -\include{pgfmanual-en-library-fit} -\include{pgfmanual-en-library-fixedpoint} -\include{pgfmanual-en-library-fpu} -\include{pgfmanual-en-library-lsystems} -\include{pgfmanual-en-library-matrices} -\include{pgfmanual-en-library-mindmaps} -\include{pgfmanual-en-library-folding} -\include{pgfmanual-en-library-patterns} -\include{pgfmanual-en-library-petri} -\include{pgfmanual-en-library-plot-handlers} -\include{pgfmanual-en-library-plot-marks} -\include{pgfmanual-en-library-profiler} -\include{pgfmanual-en-library-shadings} -\include{pgfmanual-en-library-shadows} -\include{pgfmanual-en-library-shapes} -\include{pgfmanual-en-library-spy} -\include{pgfmanual-en-library-svg-path} -\include{pgfmanual-en-library-edges} -\include{pgfmanual-en-library-through} -\include{pgfmanual-en-library-trees} -\include{pgfmanual-en-library-turtle} - - - -\iffalse -\part{Data Visualization} -\label{part-dv} - -{\Large \emph{by Till Tantau}} - -\bigskip -\noindent -The documentation of the data visualization is still missing. This -stuff is still ``heavily under construction.'' - -\include{pgfmanual-en-dv-introduction} -\include{pgfmanual-en-dv-main} -\include{pgfmanual-en-dv-axes} -\include{pgfmanual-en-dv-visualizers} -\include{pgfmanual-en-dv-examples} -\include{pgfmanual-en-dv-formats} -\include{pgfmanual-en-dv-backend} - -\fi - - -\part{Utilities} -\label{part-utilities} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -The utility packages are not directly involved in creating graphics, -but you may find them useful nonetheless. All of them either directly -depend on \pgfname\ or they are designed to work well together with -\pgfname\ even though they can be used in a stand-alone way. - -\vskip2cm -\medskip -\noindent -\begin{codeexample}[graphic=white] -\begin{tikzpicture}[scale=2] - \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0); - \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$}; - - \draw[help lines] (0,0) grid (3.9,3.9) - [step=0.25cm] (1,2) grid +(1,1); - - \draw[->] (-0.2,0) -- (4,0) node[right] {$x$}; - \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$}; - - \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3} - \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$}; - - \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3} - \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$}; - - \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$}; -\end{tikzpicture} -\end{codeexample} - -\include{pgfmanual-en-pgfkeys} -\include{pgfmanual-en-pgffor} -\include{pgfmanual-en-pgfcalendar} -\include{pgfmanual-en-pages} -\include{pgfmanual-en-xxcolor} -\include{pgfmanual-en-module-parser} - - -\part{Mathematical and Object-Oriented Engines} - -{\Large \emph{by Mark Wibrow and Till Tantau}} - - -\bigskip -\noindent -\pgfname\ comes with two useful engines: One for doing mathematics, -one for doing object-oriented programming. Both engines can be used -independently of the main \pgfname. - -The job of the mathematical -engine is to support mathematical operations like addition, -subtraction, multiplication and division, using both integers and -non-integers, but also functions such as square-roots, sine, cosine, -and generate pseudo-random numbers. -Mostly, you will use the mathematical facilities of \pgfname\ -indirectly, namely when you write a coordinate like |(5cm*3,6cm/4)|, -but the mathematical engine can also be used independently of -\pgfname\ and \tikzname. - -The job of the object-oriented engine is to support simple -object-oriented programming in \TeX. It allows the definition of -\emph{classes} (without inheritance), \emph{methods}, -\emph{attributes} and \emph{objects}. - -\vskip1cm -\begin{codeexample}[graphic=white] -\pgfmathsetseed{1} -\foreach \col in {black,red,green,blue} -{ - \begin{tikzpicture}[x=10pt,y=10pt,ultra thick,baseline,line cap=round] - \coordinate (current point) at (0,0); - \coordinate (old velocity) at (0,0); - \coordinate (new velocity) at (rand,rand); - - \foreach \i in {0,1,...,100} - { - \draw[\col!\i] (current point) - .. controls ++([scale=-1]old velocity) and - ++(new velocity) .. ++(rand,rand) - coordinate (current point); - \coordinate (old velocity) at (new velocity); - \coordinate (new velocity) at (rand,rand); - } - \end{tikzpicture} -} -\end{codeexample} - -\include{pgfmanual-en-math-design} -\include{pgfmanual-en-math-parsing} -\include{pgfmanual-en-math-commands} -\include{pgfmanual-en-math-algorithms} -\include{pgfmanual-en-math-numberprinting} -\include{pgfmanual-en-oo} - - -\part{The Basic Layer} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -\vskip1cm -\begin{codeexample}[graphic=white] -\begin{tikzpicture} - \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9) - [step=0.25cm] (-1,-1) grid (1,1); - \draw[blue] (1,-2.1) -- (1,4.1); % asymptote - - \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$}; - \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$}; - - \foreach \pos in {-1,2} - \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$}; - - \foreach \pos in {-1,1,2,3} - \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$}; - - \fill (0,0) circle (0.064cm); - \draw[thick,parametric,domain=0.4:1.5,samples=200] - % The plot is reparameterised such that there are more samples - % near the center. - plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))} - node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$}; - - \fill[red] (0.63662,0) circle (2pt) - node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$}; -\end{tikzpicture} -\end{codeexample} - - -\include{pgfmanual-en-base-design} -\include{pgfmanual-en-base-scopes} -\include{pgfmanual-en-base-points} -\include{pgfmanual-en-base-paths} -\include{pgfmanual-en-base-decorations} -\include{pgfmanual-en-base-actions} -\include{pgfmanual-en-base-arrows} -\include{pgfmanual-en-base-nodes} -\include{pgfmanual-en-base-matrices} -\include{pgfmanual-en-base-transformations} -\include{pgfmanual-en-base-patterns} -\include{pgfmanual-en-base-images} -\include{pgfmanual-en-base-external} -\include{pgfmanual-en-base-plots} -\include{pgfmanual-en-base-layers} -\include{pgfmanual-en-base-shadings} -\include{pgfmanual-en-base-transparency} -\include{pgfmanual-en-base-internalregisters} -\include{pgfmanual-en-base-quick} - - - - -\part{The System Layer} -\label{part-system} - -{\Large \emph{by Till Tantau}} - - -\bigskip -\noindent -This part describes the low-level interface of \pgfname, called the -\emph{system layer}. This interface provides a complete abstraction of -the internals of the underlying drivers. - -Unless you intend to port \pgfname\ to another driver or unless you intend -to write your own optimized frontend, you need not read this part. - -In the following it is assumed that you are familiar with the basic -workings of the |graphics| package and that you know what -\TeX-drivers are and how they work. - -\vskip1cm -\begin{codeexample}[graphic=white] -\begin{tikzpicture} - [shorten >=1pt,->, - vertex/.style={circle,fill=black!25,minimum size=17pt,inner sep=0pt}] - - \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16} - \node[vertex] (G-\name) at (\x,0) {$\name$}; - - \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9} - \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; - - \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14} - \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$}; - - \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t} - \draw (G-\from) -- (G-\to); - - \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2} - { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); } - - \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1); - \draw (Q-5) -- (G-15); -\end{tikzpicture} -\end{codeexample} - -\include{pgfmanual-en-pgfsys-overview} -\include{pgfmanual-en-pgfsys-commands} -\include{pgfmanual-en-pgfsys-paths} -\include{pgfmanual-en-pgfsys-protocol} - - - -\part{References and Index} - -\vskip1cm -\begin{codeexample}[graphic=white] -\begin{tikzpicture} - \draw[line width=0.3cm,color=red!30,line cap=round,line join=round] (0,0)--(2,0)--(2,5); - \draw[help lines] (-2.5,-2.5) grid (5.5,7.5); - \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)-- - (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)-- - (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5) - (3,3)--(4,3)--(4,5)--(3,5)--(3,6) - (3,-1)--(4,-1); - \draw[below left] (0,0) node(s){$s$}; - \draw[below left] (2,5) node(t){$t$}; - \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm); - \draw[->,rounded corners=0.2cm,shorten >=2pt] - (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)-- - ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)-- - ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)-- - ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)-- - ++(0,-1)-- ++(1,0); -\end{tikzpicture} -\end{codeexample} - -\printindex - -%\typeout{Examples: \the\codeexamplecount}% -\end{document} - - +\input pgfmanual-en-main-preamble.tex +\input pgfmanual-en-main-body.tex %%% Local Variables: %%% mode: latex -%%% TeX-master: "~/texmf/tex/generic/pgf/doc/pgf/version-for-pdftex/en/pgfmanual" %%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex index 8f6f1639b0c..5441b9e101f 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-algorithms.tex @@ -28,11 +28,11 @@ recommended for adventurous users. To add a new function to the math engine the following command can be used: -\begin{command}{\pgfmathdeclarefunction\marg{function name}\marg{number of arguments}\marg{code}} +\begin{command}{\pgfmathdeclarefunction\marg{name}\marg{number of arguments}\marg{code}} This will set up the parser to recognize a function called \meta{name}. The name of the function can consist of, uppercase or - lower case letters, numbers or the underscore |_|. In line with + lowercase letters, numbers or the underscore |_|. In line with many programming languages, a function name cannot begin with a number or contain any spaces. @@ -40,7 +40,7 @@ used: or the value |...|, which indicates a variable number of arguments. \pgfname{} treats constants, such as |pi| and |e|, as functions with zero arguments. Functions with more than nine - arguments or with variable arguments are a ``bit special'' and + arguments or with a variable number of arguments are a ``bit special'' and are discussed below. The effect of \meta{code} should be to set the macro @@ -85,7 +85,7 @@ used: \item |\pgfmath|\meta{function name} - This macro will provide ``public'' interface for the function + This macro will provide a ``public'' interface for the function \meta{function name} allowing the function to be called independently of the parser. All arguments passed to this macro are evaluated using |\pgfmathparse| and then passed on to the following @@ -94,11 +94,11 @@ used: \item |\pgfmath|\meta{function name}|@| - This macro is the ``private'' implementation of the functions + This macro is the ``private'' implementation of the function's algorithm (but note that, for speed, the parser calls this macro rather than the ``public'' one). Arguments passed to this macro are expected to be numbers without units. It is defined using - \meta{code}, but need not be self contained. + \meta{code}, but need not be self-contained. \end{itemize} @@ -123,7 +123,7 @@ used: This means that some ``extra work'' will be required to access each argument (although it is a fairly simple task). - Note, that there are, two exceptions to this arrangement: + Note that there are two exceptions to this arrangement: the public versions of the |min| and |max| functions still take two arguments for compatibility with older versions, but each of these arguments can take several comma separated values. @@ -147,7 +147,7 @@ used: \pgfname{} uses the last known definition of a function within the prevailing scope, so it is possible for a function to be redefined locally. You should also remember that any |.sty| or |.tex| file - containing any re-implementations should be loaded after pgf-Math. + containing any re-implementations should be loaded after |pgfmath|. In addition to the above commands, the following key is provided to quickly create simple ad hoc functions which can greatly improve @@ -171,13 +171,13 @@ used: Each definition in \meta{function definitions} takes the form \meta{name}|(|\meta{arguments}|)=|\meta{definition}|;| (note the semicolon at the end, this is very important). If multiple - functions are being defined the semicolon is used to separate + functions are being defined, the semicolon is used to separate them (\emph{not} a comma). The function \meta{name} can be any name that is not already a function name in the current scope. The list of \meta{arguments} are commands such as |\x|, or |\y| (it is not possible to declare functions that take variable numbers of arguments using this key). - If the function takes no arguments then the parentheses need not + If the function takes no arguments, then the parentheses need not be used. The \meta{definition} should be an expression that can be parsed by the mathematical engine and should use the commands diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex index b1be68267d7..fe42eacac4c 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-commands.tex @@ -26,7 +26,7 @@ Section~\ref{pgfmath-functions-basic}, the following command is provided: \begin{command}{\pgfmathreciprocal\marg{x}} - Defines |\pgfmathresult| as $1\div\meta{x}$. This is provides + Defines |\pgfmathresult| as $1\div\meta{x}$. This provides greatest accuracy when \mvar{x} is small. \end{command} @@ -52,12 +52,12 @@ the following commands are provided: \begin{command}{\pgfmathgeneratepseudorandomnumber} Defines |\pgfmathresult| as a pseudo-random integer between 1 and $2^{31}-1$. This uses a linear congruency generator, based on ideas - due to Erich Janka. + of Erich Janka. \end{command} -\begin{command}{\pgfmathrandominteger\marg{macro}\marg{maximum}\marg{minimum}} +\begin{command}{\pgfmathrandominteger\marg{macro}\marg{minimum}\marg{maximum}} This defines \meta{macro} as a pseudo-randomly generated integer from - the range \meta{maximum} to \meta{minimum} (inclusive). + the range \meta{minimum} to \meta{maximum} (inclusive). \begin{codeexample}[] \begin{pgfpicture} @@ -99,7 +99,7 @@ the following commands are provided: \end{codeexample} \begin{command}{\pgfmathsetseed\marg{integer}} - Explicitly set seed for the pseudo-random number generator. By + Explicitly sets the seed for the pseudo-random number generator. By default it is set to the value of |\time|$\times$|\year|. \end{command} @@ -129,6 +129,8 @@ the following commands are provided: \begin{codeexample}[] \pgfmathbasetodec\mynumber{107f}{16} \mynumber \end{codeexample} + + \noindent Note that, as usual in \TeX, the braces around an argument can be omitted if the argument is just a single token (a macro name is a single token). \begin{codeexample}[] @@ -187,14 +189,62 @@ the following commands are provided: \begin{command}{\pgfmathsetbasenumberlength\marg{integer}} - Set the number of digits in the result of a base conversion to + Sets the number of digits in the result of a base conversion to \meta{integer}. If the result of a conversion has less digits - than this number it is prefixed with zeros. + than this number, it is prefixed with zeros. \begin{codeexample}[] \pgfmathsetbasenumberlength{8} \pgfmathdectobase\mynumber{15}{2} \mynumber \end{codeexample} +\end{command} + +\begin{command}{\pgfmathtodigitlist\marg{macro}\marg{number}} + + This command converts \meta{number} into a comma-separated + list of digits and stores the result in \meta{macro}. + The \marg{number} is \emph{not} parsed before processing. + +\begin{codeexample}[] +\pgfmathsetbasenumberlength{8} +\begin{tikzpicture}[x=0.25cm, y=0.25cm] + \foreach \n [count=\y] in {0, 60, 102, 102, 126, 102, 102, 102, 0}{ + \pgfmathdectobase{\binary}{\n}{2} + \pgfmathtodigitlist{\digitlist}{\binary} + \foreach \digit [count=\x, evaluate={\c=\digit*50+15;}] in \digitlist + \fill [fill=black!\c] (\x, -\y) rectangle ++(1,1); + } +\end{tikzpicture} +\end{codeexample} + +\end{command} + +\subsection{Angle Computations} + +Unlike the rest of the math engine, which is a ``standalone'' package, +the following commands only work in conjunction with the core of +\pgfname. + + + +\begin{command}{\pgfmathanglebetweenpoints\marg{p}\marg{q}} + Returns the angle of a line from \meta{p} to \meta{q} relative to a + line going straight right from \meta{p}. + +\begin{codeexample}[] +\pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} +\pgfmathresult +\end{codeexample} \end{command} +\begin{command}{\pgfmathanglebetweenlines\marg{$p_1$}\marg{$q_1$}\marg{$p_2$}\marg{$q_2$}} + Returns the clockwise angle between a line going through $p_1$ and + $q_1$ and a line going through $p_2$ and $q_2$. + +\begin{codeexample}[] +\pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} + {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}} +\pgfmathresult +\end{codeexample} +\end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex index e12380bd8ae..59295dc7c9d 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-design.tex @@ -47,7 +47,7 @@ not need \pgfname\ itself, you can load the following package: \begin{package}{pgfmath} This command will load the mathematical engine of \pgfname, but not - \pgfname itself. It defines commands like |\pgfmathparse|. + \pgfname{} itself. It defines commands like |\pgfmathparse|. \end{package} @@ -88,7 +88,7 @@ This poses some intriguing programming challenges as \TeX{} is a language for typesetting, rather than for general mathematics, and as with any programming language, there is a trade-off between accuracy and efficiency. -If you find the level of accuracy insufficient for you +If you find the level of accuracy insufficient for your purposes, you will have to replace the algorithms in the implementation layer. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-numberprinting.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-numberprinting.tex index 9deedd2e504..f86b6f59187 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-numberprinting.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-numberprinting.tex @@ -9,17 +9,23 @@ \pgfname\ supports number printing in different styles and rounds to arbitrary precision. \begin{command}{\pgfmathprintnumber\marg{x}} -Generates pretty-printed output for the (real) number \marg{x}. The input number \marg{x} is parsed using |\pgfmathfloatparsenumber| which allows arbitrary precision. + Generates pretty-printed output for the (real) number \meta{x}. The + input number \meta{x} is parsed using |\pgfmathfloatparsenumber| + which allows arbitrary precision. -Numbers are typeset in math mode using the current set of number printing options, see below. Optional arguments can also be provided using |\pgfmathprintnumber[|\meta{options}|]|\marg{x}. + Numbers are typeset in math mode using the current set of number + printing options, see below. Optional arguments can also be provided + using |\pgfmathprintnumber[|\meta{options}|]|\meta{x}. \end{command} -\begin{command}{\pgfmathprintnumberto\marg{x}\marg{\textbackslash macro}} - Returns the resulting number into \marg{\textbackslash macro} instead of typesetting it directly. +\begin{command}{\pgfmathprintnumberto\marg{x}\marg{macro}} + Returns the resulting number into \meta{macro} + instead of typesetting it directly. \end{command} \begin{key}{/pgf/number format/fixed} -Configures |\pgfmathprintnumber| to round the number to a fixed number of digits after the period, discarding any trailing zeros. + Configures |\pgfmathprintnumber| to round the number to a fixed + number of digits after the period, discarding any trailing zeros. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,fixed,precision=2} @@ -30,11 +36,13 @@ Configures |\pgfmathprintnumber| to round the number to a fixed number of digits \pgfmathprintnumber{123456.12345} \end{codeexample} -See section~\ref{sec:number:styles} for how to change the appearance. + See section~\ref{sec:number:styles} for how to change the + appearance. \end{key} \begin{key}{/pgf/number format/fixed zerofill=\marg{boolean} (default true)} -Enables or disables zero filling for any number drawn in fixed point format. + Enables or disables zero filling for any number drawn in fixed point + format. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2} @@ -44,7 +52,8 @@ Enables or disables zero filling for any number drawn in fixed point format. \pgfmathprintnumber{24415.98123}\hspace{1em} \pgfmathprintnumber{123456.12345} \end{codeexample} -This key affects numbers drawn with |fixed| or |std| styles (the latter only if no scientific format is chosen). + This key affects numbers drawn with |fixed| or |std| styles (the + latter only if no scientific format is chosen). \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2} \pgfmathprintnumber{4.568}\hspace{1em} @@ -53,11 +62,15 @@ This key affects numbers drawn with |fixed| or |std| styles (the latter only if \pgfmathprintnumber{123456.12345} \end{codeexample} -See section~\ref{sec:number:styles} for how to change the appearance. + See section~\ref{sec:number:styles} for how to change the + appearance. \end{key} \begin{key}{/pgf/number format/sci} -Configures |\pgfmathprintnumber| to display numbers in scientific format, that means sign, mantissa and exponent (basis~$10$). The mantissa is rounded to the desired |precision| (or |sci precision|, see below). + Configures |\pgfmathprintnumber| to display numbers in scientific + format, that means sign, mantissa and exponent (basis~$10$). The + mantissa is rounded to the desired |precision| (or |sci precision|, + see below). \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,precision=2} @@ -68,11 +81,13 @@ Configures |\pgfmathprintnumber| to display numbers in scientific format, that m \pgfmathprintnumber{123456.12345} \end{codeexample} -See section~\ref{sec:number:styles} for how to change the exponential display style. +See section~\ref{sec:number:styles} for how to change the exponential +display style. \end{key} \begin{key}{/pgf/number format/sci zerofill=\marg{boolean} (default true)} -Enables or disables zero filling for any number drawn in scientific format. + Enables or disables zero filling for any number drawn in scientific + format. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2} @@ -82,19 +97,25 @@ Enables or disables zero filling for any number drawn in scientific format. \pgfmathprintnumber{24415.98123}\hspace{1em} \pgfmathprintnumber{123456.12345} \end{codeexample} -As with |fixed zerofill|, this option does only affect numbers drawn in |sci| format (or |std| if the scientific format is chosen). + As with |fixed zerofill|, this option does only affect numbers drawn + in |sci| format (or |std| if the scientific format is chosen). -See section~\ref{sec:number:styles} for how to change the exponential display style. + See section~\ref{sec:number:styles} for how to change the + exponential display style. \end{key} \begin{stylekey}{/pgf/number format/zerofill=\marg{boolean} (default true)} - Sets both, |fixed zerofill| and |sci zerofill| at once. + Sets both |fixed zerofill| and |sci zerofill| at once. \end{stylekey} \begin{keylist}{/pgf/number format/std,% /pgf/number format/std=\meta{lower e}, /pgf/number format/std=\meta{lower e}:\meta{upper e}} -Configures |\pgfmathprintnumber| to a standard algorithm. It chooses either |fixed| or |sci|, depending on the order of magnitude. Let $n=s \cdot m \cdot 10^e$ be the input number and $p$ the current precision. If $-p/2 \le e \le 4$, the number is displayed using |fixed| format. Otherwise, it is displayed using |sci| format. + Configures |\pgfmathprintnumber| to a standard algorithm. It chooses + either |fixed| or |sci|, depending on the order of magnitude. Let + $n=s \cdot m \cdot 10^e$ be the input number and $p$ the current + precision. If $-p/2 \le e \le 4$, the number is displayed using + |fixed| format. Otherwise, it is displayed using |sci| format. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,std,precision=2} @@ -104,12 +125,168 @@ Configures |\pgfmathprintnumber| to a standard algorithm. It chooses either |fix \pgfmathprintnumber{24415.98123}\hspace{1em} \pgfmathprintnumber{123456.12345} \end{codeexample} -The parameters can be customized using the optional integer argument(s): if $\text{\meta{lower e}} \le e \le \text{\meta{upper e}}$, the number is displayed in |fixed| format, otherwise in |sci| format. Note that \meta{lower e} should be negative for useful results. The precision used for scientific format can be adjusted with |sci precision| if necessary. + The parameters can be customized using the optional integer + argument(s): if $\text{\meta{lower e}} \le e \le \text{\meta{upper + e}}$, the number is displayed in |fixed| format, otherwise in + |sci| format. Note that \meta{lower e} should be negative for useful + results. The precision used for the scientific format can be + adjusted with |sci precision| if necessary. +\end{keylist} + +\begin{keylist}{/pgf/number format/relative*=\meta{exponent base 10}} + Configures |\pgfmathprintnumber| to format numbers relative to an + order of magnitude, $10^r$, where $r$ is an integer number. + + This key addresses different use-cases. + + \paragraph{First use-case:} provide a unified format for a + \emph{sequence} of numbers. Consider the following test: +\begin{codeexample}[] +\pgfkeys{/pgf/number format/relative*={1}} +\pgfmathprintnumber{6.42e-16}\hspace{1em} +\pgfmathprintnumber{1.2}\hspace{1em} +\pgfmathprintnumber{6}\hspace{1em} +\pgfmathprintnumber{20.6}\hspace{1em} +\pgfmathprintnumber{87} +\end{codeexample} + \noindent With any other style, the |6.42e-16| would have been + formatted as an isolated number. Here, it is rounded to |0| because + when viewed relative to $10^1$ (the exponent $1$ is the argument for + |relative|), it has no significant digits. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/relative*={2}} +\pgfmathprintnumber{123.345}\hspace{1em} +\pgfmathprintnumber{0.0012}\hspace{1em} +\pgfmathprintnumber{0.0014}\hspace{1em} +\end{codeexample} + \noindent The example above applies the initial |precision=2| to + |123.345| -- relative to $100$. Two significant digits of |123.345| + relative to $100$ are |123|. Note that the ``$2$ significant digits + of |123.345|'' translates to ``round |1.2345| to $2$ digits'', which + would yield |1.2300|. Similarly, the other two numbers are |0| + compared to $100$ using the given |precision|. + +\begin{codeexample}[] +\pgfkeys{/pgf/number format/relative*={-3}} +\pgfmathprintnumber{123.345}\hspace{1em} +\pgfmathprintnumber{0.0012}\hspace{1em} +\pgfmathprintnumber{0.0014}\hspace{1em} +\end{codeexample} + + \paragraph{Second use-case:} improve rounding in the presence of + \emph{inaccurate} numbers. Let us suppose that some + limited-precision arithmetics resulted in the result |123456999| + (like the |fpu| of \pgfname). You know that its precision is about + five or six significant digits. And you want to provide a fixed + point output. In this case, the trailing digits |....999| are a + numerical artifact due to the limited precision. Use + |relative*=3,precision=0| to eliminate the artifacts: +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0} +\pgfmathprintnumber{123456999}\hspace{1em} +\pgfmathprintnumber{123456999.12} +\end{codeexample} + \noindent Here, |precision=0| means that we inspect |123456.999| and + round that number to $0$ digits. Finally, we move the period back to + its initial position. Adding |relative style=fixed| results in fixed + point output format: +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0,relative style=fixed} +\pgfmathprintnumber{123456999}\hspace{1em} +\pgfmathprintnumber{123456999.12} +\end{codeexample} + \noindent Note that there is another alternative for this use-case + which is discussed later: the |fixed relative| style. +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed relative,precision=6} +\pgfmathprintnumber{123456999}\hspace{1em} +\pgfmathprintnumber{123456999.12} +\end{codeexample} + + You might wonder why there is an asterisk in the key's name. The + short answer is: there is also a \declareandlabel{/pgf/number + format/relative} number printer which does unexpected things. The + key |relative*| repairs this. Existing code will still use the old + behavior. + + Technically, the key works as follows: as already explained above, + |relative*=3| key applied to |123456999.12| moves the period by + three positions and analyzes |123456.99912|. Mathematically + speaking, we are given a number $x = \pm m \cdot 10^e$ and we + attempt to apply |relative*=|$r$. The method then rounds $x / 10^r$ + to |precision| digits. Afterwards, it multiplies the result by + $10^r$ and typesets it. +\end{keylist} + +\begin{stylekey}{/pgf/number format/every relative} + A style which configures how the |relative| method finally displays + its results. + + The initial configuration is +\begin{codeexample}[code only] +\pgfkeys{/pgf/number format/every relative/.style=std} +\end{codeexample} + + Note that rounding is turned off when the resulting style is being + evaluated (since |relative| already rounded the number). + + Although supported, I discourage from using |fixed zerofill| or + |sci zerofill| in this context -- it may lead to a suggestion of higher + precision than is actually used (because |fixed zerofill| might + simply add |.00| although there was a different information before + |relative| rounded the result). +\end{stylekey} + +\begin{key}{/pgf/number format/relative style=\marg{options}} + The same as |every relative/.append style=|\marg{options}. +\end{key} + +\begin{keylist}{/pgf/number format/fixed relative} + Configures |\pgfmathprintnumber| to format numbers in a similar way + to the |fixed| style, but the |precision| is interpreted relatively + to the number's exponent. + The motivation is to get the same rounding effect as for |sci|, but + to display the number in the |fixed| style: +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd,fixed relative,precision=3} +\pgfmathprintnumber{1000.0123}\hspace{1em} +\pgfmathprintnumber{100.0567}\hspace{1em} +\pgfmathprintnumber{0.000010003452}\hspace{1em} +\pgfmathprintnumber{0.010073452}\hspace{1em} +\pgfmathprintnumber{1.23567}\hspace{1em} +\pgfmathprintnumber{1003.75}\hspace{1em} +\pgfmathprintnumber{1006.75}\hspace{1em} +\end{codeexample} + + The effect of |fixed relative| is that the number is rounded to + \emph{exactly} the first \meta{precision} non-zero digits, no matter + how many leading zeros the number might have. + + Use |fixed relative| if you want |fixed| and if you know that only + the first $n$ digits are correct. Use |sci| if you need a scientific + display style and only the first $n$ digits are correct. + + Note that |fixed relative| ignores the |fixed zerofill| flag. + + See also the |relative*| key. Note that the + |relative=|\marg{exponent} key explicitly moves the period to some + designated position before it attempts to round the + number. Afterwards, it ``rounds from the right'', i.e.\ it rounds to + that explicitly chosen digit position. In contrast to that, + |fixed relative| ``rounds from the left'': it takes the \emph{first} + non-zero digit, temporarily places the period after this digit, and + rounds that number. The rounding style |fixed| leaves the period + where it is, and rounds everything behind that digit. The |sci| + style is similar to |fixed relative|. \end{keylist} + \begin{key}{/pgf/number format/int detect} -Configures |\pgfmathprintnumber| to detect integers automatically. If the input number is an integer, no period is displayed at all. If not, the scientific format is chosen. + Configures |\pgfmathprintnumber| to detect integers + automatically. If the input number is an integer, no period is + displayed at all. If not, the scientific format is chosen. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,int detect,precision=2} @@ -122,12 +299,15 @@ Configures |\pgfmathprintnumber| to detect integers automatically. If the input \end{key} \begin{command}{\pgfmathifisint\marg{number constant}\marg{true code}\marg{false code}} - A command which does the same check as |int detect|, but it invokes \meta{true code} if the \meta{number constant} actually is an integer and the \meta{false code} if not. - - As a side--effect, |\pgfretval| will contain the parsed number, either in integer format or as parsed floating point number. + A command which does the same check as |int detect|, but it invokes + \meta{true code} if the \meta{number constant} actually is an + integer and the \meta{false code} if not. + As a side-effect, |\pgfretval| will contain the parsed number, + either in integer format or as parsed floating point number. - The argument \meta{number constant} will be parsed with |\pgfmathfloatparsenumber|. + The argument \meta{number constant} will be parsed with + |\pgfmathfloatparsenumber|. \begin{codeexample}[] 15 \pgfmathifisint{15}{is an int: \pgfretval.}{is no int}\hspace{1em} 15.5 \pgfmathifisint{15.5}{is an int: \pgfretval.}{is no int} @@ -135,8 +315,8 @@ Configures |\pgfmathprintnumber| to detect integers automatically. If the input \end{command} \begin{key}{/pgf/number format/int trunc} -Truncates every number to integers (discards any digit after the period). - + Truncates every number to integers (discards any digit after the + period). \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,int trunc} \pgfmathprintnumber{4.568}\hspace{1em} @@ -148,7 +328,7 @@ Truncates every number to integers (discards any digit after the period). \end{key} \begin{key}{/pgf/number format/frac} -Displays numbers as fractionals. + Displays numbers as fractionals. \begin{codeexample}[width=3cm] \pgfkeys{/pgf/number format/frac} @@ -169,10 +349,12 @@ Displays numbers as fractionals. \end{codeexample} \begin{key}{/pgf/number format/frac TeX=\marg{\textbackslash macro} (initially \texttt{\textbackslash frac})} - Allows to use a different implementation for |\frac| inside of the |frac| display type. + Allows to use a different implementation for |\frac| inside of the + |frac| display type. \end{key} + \begin{key}{/pgf/number format/frac denom=\meta{int} (initially empty)} - Allows to provide a custom denominator for |frac|. + Allows to provide a custom denominator for |frac|. \begin{codeexample}[width=3cm] \pgfkeys{/pgf/number format/.cd,frac, frac denom=10} \pgfmathprintnumber{0.1}\hspace{1em} @@ -183,7 +365,9 @@ Displays numbers as fractionals. \end{codeexample} \end{key} \begin{key}{/pgf/number format/frac whole=\mchoice{true,false} (initially true)} - Configures whether complete integer parts shall be placed in front of the fractional part. In this case, the fractional part will be less then $1$. Use |frac whole=false| to avoid whole number parts. + Configures whether complete integer parts shall be placed in front + of the fractional part. In this case, the fractional part will be + less then $1$. Use |frac whole=false| to avoid whole number parts. \begin{codeexample}[width=3cm] \pgfkeys{/pgf/number format/.cd,frac, frac whole=false} \pgfmathprintnumber{20.1}\hspace{1em} @@ -194,41 +378,59 @@ Displays numbers as fractionals. \end{codeexample} \end{key} \begin{key}{/pgf/number format/frac shift=\marg{integer} (initially 4)} - In case you experience problems because of stability problems, try experimenting with a different |frac shift|. - Higher shift values $k$ yield higher sensitivity to inaccurate data or inaccurate arithmetics. + In case you experience problems because of stability problems, try + experimenting with a different |frac shift|. Higher shift values $k$ + yield higher sensitivity to inaccurate data or inaccurate + arithmetics. - Technically, the following happens. If $r < 1$ is the fractional part of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where $k$ is the shift; fractional parts of $i$ are neglected. The value $1/r$ is computed internally, its error is amplified. + Technically, the following happens. If $r < 1$ is the fractional + part of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed + where $k$ is the shift; fractional parts of $i$ are neglected. The + value $1/r$ is computed internally, its error is amplified. - If you still experience stability problems, use |\usepackage{fp}| in your preamble. The |frac| style will then automatically employ the higher absolute precision of |fp| for the computation of $1/r$. + If you still experience stability problems, use |\usepackage{fp}| in + your preamble. The |frac| style will then automatically employ the + higher absolute precision of |fp| for the computation of $1/r$. \end{key} \end{key} \begin{key}{/pgf/number format/precision=\marg{number}} -Sets the desired rounding precision for any display operation. For scientific format, this affects the mantissa. + Sets the desired rounding precision for any display operation. For + scientific format, this affects the mantissa. \end{key} \begin{key}{/pgf/number format/sci precision=\meta{number or empty} (initially empty)} - Sets the desired rounding precision only for |sci| styles. + Sets the desired rounding precision only for |sci| styles. - Use |sci precision={}| to restore the initial configuration (which uses the argument provided to |precision| for all number styles). + Use |sci precision={}| to restore the initial configuration (which + uses the argument provided to |precision| for all number styles). \end{key} \subsection{Changing display styles}% \label{sec:number:styles}% -You can change the way how numbers are displayed. For example, if you use the `\texttt{fixed}' style, the input number is rounded to the desired precision and the current fixed point display style is used to typeset the number. The same is applied to any other format: first, rounding routines are used to get the correct digits, afterwards a display style generates proper \TeX-code. + +You can change the way how numbers are displayed. For example, if you +use the `\texttt{fixed}' style, the input number is rounded to the +desired precision and the current fixed point display style is used to +typeset the number. The same is applied to any other format: first, +rounding routines are used to get the correct digits, afterwards a +display style generates proper \TeX-code. \begin{key}{/pgf/number format/set decimal separator=\marg{text}} -Assigns \marg{text} as decimal separator for any fixed point numbers (including the mantissa in sci format). + Assigns \marg{text} as decimal separator for any fixed point numbers + (including the mantissa in sci format). -Use |\pgfkeysgetvalue{/pgf/number format/set decimal separator}\value| to get the current separator into |\value|. + Use |\pgfkeysgetvalue{/pgf/number format/set decimal separator}\value| + to get the current separator into |\value|. \end{key} \begin{stylekey}{/pgf/number format/dec sep=\marg{text}} - Just another name for |set decimal separator|. + Just another name for |set decimal separator|. \end{stylekey} \begin{key}{/pgf/number format/set thousands separator=\marg{text}} -Assigns \marg{text} as thousands separator for any fixed point numbers (including the mantissa in sci format). + Assigns \marg{text} as thousands separator for any fixed point + numbers (including the mantissa in sci format). \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd, @@ -271,17 +473,48 @@ Assigns \marg{text} as thousands separator for any fixed point numbers (includin set thousands separator={{{,}}}} \pgfmathprintnumber{1234567890} \end{codeexample} -The last example employs commas and disables the default comma-spacing. + The last example employs commas and disables the default + comma-spacing. -Use |\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value| to get the current separator into |\value|. + Use |\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value| + to get the current separator into |\value|. \end{key} \begin{stylekey}{/pgf/number format/1000 sep=\marg{text}} - Just another name for |set thousands separator|. + Just another name for |set thousands separator|. \end{stylekey} +\begin{key}{/pgf/number format/1000 sep in fractionals=\marg{boolean} (initially false)} + Configures whether the fractional part should also be grouped into + groups of three digits. + + The value |true| will active the |1000 sep| for both, integer and + fractional parts. The value |false| will active |1000 sep| only for the integer part. +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed, + precision=999, + set thousands separator={\,}, + 1000 sep in fractionals, + } +\pgfmathprintnumber{1234.1234567} +\end{codeexample} +\begin{codeexample}[] +\pgfkeys{/pgf/number format/.cd, + fixed,fixed zerofill, + precision=9, + set thousands separator={\,}, + 1000 sep in fractionals, + } +\pgfmathprintnumber{1234.1234567} +\end{codeexample} +\end{key} + \begin{key}{/pgf/number format/min exponent for 1000 sep=\marg{number} (initially 0)} - Defines the smallest exponent in scientific notation which is required to draw thousand separators. The exponent is the number of digits minus one, so $\meta{number}=4$ will use thousand separators starting with $1e4 = 10000$. + Defines the smallest exponent in scientific notation which is + required to draw thousand separators. The exponent is the number of + digits minus one, so $\meta{number}=4$ will use thousand separators + starting with $1e4 = 10000$. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd, int detect, @@ -304,11 +537,14 @@ Use |\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value| to get min exponent for 1000 sep=4} \pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000} \end{codeexample} -\noindent A value of |0| disables this feature (negative values are ignored). + \noindent A value of |0| disables this feature (negative values are + ignored). \end{key} \begin{key}{/pgf/number format/use period} -A predefined style which installs periods `\texttt{.}' as decimal separators and commas `\texttt{,}' as thousands separators. This style is the default. + A predefined style which installs periods ``\texttt{.}'' as decimal + separators and commas ``\texttt{,}'' as thousands separators. This + style is the default. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} @@ -321,7 +557,8 @@ A predefined style which installs periods `\texttt{.}' as decimal separators and \end{key} \begin{key}{/pgf/number format/use comma} -A predefined style which installs commas `\texttt{,}' as decimal separators and periods `\texttt{.}' as thousands separators. + A predefined style which installs commas ``\texttt{,}'' as decimal + separators and periods ``\texttt{.}'' as thousands separators. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} @@ -334,7 +571,8 @@ A predefined style which installs commas `\texttt{,}' as decimal separators and \end{key} \begin{key}{/pgf/number format/skip 0.=\marg{boolean} (initially false)} - Configures whether numbers like $0.1$ shall be typeset as $.1$ or not. + Configures whether numbers like $0.1$ shall be typeset as $.1$ or + not. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd, fixed, @@ -352,7 +590,8 @@ A predefined style which installs commas `\texttt{,}' as decimal separators and \end{key} \begin{key}{/pgf/number format/showpos=\marg{boolean} (initially false)} - Enables or disables display of plus signs for non-negative numbers. + Enables or disables the display of plus signs for non-negative + numbers. \begin{codeexample}[] \pgfkeys{/pgf/number format/showpos} \pgfmathprintnumber{12.345} @@ -370,11 +609,11 @@ A predefined style which installs commas `\texttt{,}' as decimal separators and \end{key} \begin{stylekey}{/pgf/number format/print sign=\marg{boolean}} - A style which is simply an alias for |showpos=|\marg{boolean}. + A style which is simply an alias for |showpos=|\marg{boolean}. \end{stylekey} \begin{key}{/pgf/number format/sci 10e} -Uses $m \cdot 10^e$ for any number displayed in scientific format. + Uses $m \cdot 10^e$ for any number displayed in scientific format. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci 10e} @@ -383,11 +622,12 @@ Uses $m \cdot 10^e$ for any number displayed in scientific format. \end{key} \begin{key}{/pgf/number format/sci 10\textasciicircum e} -The same as `|sci 10e|'. + The same as `|sci 10e|'. \end{key} \begin{key}{/pgf/number format/sci e} -Uses the `$1e{+}0$' format which is generated by common scientific tools for any number displayed in scientific format. + Uses the `$1e{+}0$' format which is generated by common scientific + tools for any number displayed in scientific format. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci e} @@ -396,7 +636,7 @@ Uses the `$1e{+}0$' format which is generated by common scientific tools for any \end{key} \begin{key}{/pgf/number format/sci E} -The same with an uppercase `\texttt{E}'. + The same with an uppercase `\texttt{E}'. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci E} @@ -405,7 +645,8 @@ The same with an uppercase `\texttt{E}'. \end{key} \begin{key}{/pgf/number format/sci subscript} -Typesets the exponent as subscript for any number displayed in scientific format. This style requires very few space. + Typesets the exponent as subscript for any number displayed in + scientific format. This style requires very little space. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci subscript} @@ -414,7 +655,8 @@ Typesets the exponent as subscript for any number displayed in scientific format \end{key} \begin{key}{/pgf/number format/sci superscript} -Typesets the exponent as superscript for any number displayed in scientific format. This style requires very few space. + Typesets the exponent as superscript for any number displayed in + scientific format. This style requires very little space. \begin{codeexample}[] \pgfkeys{/pgf/number format/.cd,sci,sci superscript} @@ -423,13 +665,17 @@ Typesets the exponent as superscript for any number displayed in scientific form \end{key} \begin{key}{/pgf/number format/sci generic=\marg{keys}} -Allows to define an own number style for the scientific format. Here, \meta{keys} can be one of the following choices (omit the long key prefix): + Allows to define an own number style for the scientific + format. Here, \meta{keys} can be one of the following choices (omit + the long key prefix): \begin{key}{/pgf/number format/sci generic/mantissa sep=\marg{text} (initially empty)} - Provides the separator between a mantissa and the exponent. It might be |\cdot|, for example, + Provides the separator between a mantissa and the exponent. It might + be |\cdot|, for example, \end{key} \begin{key}{/pgf/number format/sci generic/exponent=\marg{text} (initially empty)} - Provides text to format the exponent. The actual exponent is available as argument |#1| (see below). + Provides text to format the exponent. The actual exponent is + available as argument |#1| (see below). \end{key} \begin{codeexample}[] @@ -440,33 +686,50 @@ Allows to define an own number style for the scientific format. Here, \meta{keys \pgfmathprintnumber{12.345}; \pgfmathprintnumber{0.00012345} \end{codeexample} - The \meta{keys} can depend on three parameters, namely on |#1| which is the exponent, |#2| containing the flags entity of the floating point number and |#3| is the (unprocessed and unformatted) mantissa. + The \meta{keys} can depend on three parameters, namely on |#1| which + is the exponent, |#2| containing the flags entity of the floating + point number and |#3| is the (unprocessed and unformatted) + mantissa. - Note that |sci generic| is \emph{not} suitable to modify the appearance of fixed point numbers, nor can it be used to format the mantissa (which is typeset like fixed point numbers). Use |dec sep|, |1000 sep| and |print sign| to customize the mantissa. + Note that |sci generic| is \emph{not} suitable to modify the + appearance of fixed point numbers, nor can it be used to format the + mantissa (which is typeset like fixed point numbers). Use |dec sep|, + |1000 sep| and |print sign| to customize the mantissa. \end{key} -\begin{key}{/pgf/number format/@dec sep mark=\marg{text}} - Will be placed right before the place where a decimal separator belongs to. However, \marg{text} will be inserted even if there is no decimal separator. It is intended as place-holder for auxiliary routines to find alignment positions. +\begin{key}{/pgf/number format/\protect\atmarktext dec sep mark=\marg{text}} + Will be placed right before the place where a decimal separator + belongs to. However, \marg{text} will be inserted even if there is + no decimal separator. It is intended as place-holder for auxiliary + routines to find alignment positions. - This key should never be used to change the decimal separator! Use |dec sep| instead. + This key should never be used to change the decimal separator! + Use |dec sep| instead. \end{key} -\begin{key}{/pgf/number format/@sci exponent mark=\marg{text}} - Will be placed right before exponents in scientific notation. It is intended as place-holder for auxiliary routines to find alignment positions. +\begin{key}{/pgf/number format/\protect\atmarktext sci exponent mark=\marg{text}} + Will be placed right before exponents in scientific notation. It is + intended as place-holder for auxiliary routines to find alignment + positions. - This key should never be used to change the exponent! + This key should never be used to change the exponent! \end{key} \begin{key}{/pgf/number format/assume math mode=\marg{boolean} (default true)} - Set this to |true| if you don't want any checks for math mode. The initial setting checks whether math mode is active using |\pgfutilensuremath| for each final number. + Set this to |true| if you don't want any checks for math mode. The + initial setting checks whether math mode is active using + |\pgfutilensuremath| for each final number. - Use |assume math mode=true| if you know that math mode is active. In that case, the final number is typeset as-is, no further checking is performed. + Use |assume math mode=true| if you know that math mode is active. In + that case, the final number is typeset as-is, no further checking is + performed. \end{key} \begin{stylekey}{/pgf/number format/verbatim} - A style which configures the number printer to produce verbatim text output, i.e.\ it doesn't contain \TeX\ macros. + A style which configures the number printer to produce verbatim text + output, i.\,e., it doesn't contain \TeX\ macros. \begin{codeexample}[] \pgfkeys{ /pgf/fpu, @@ -478,9 +741,14 @@ Allows to define an own number style for the scientific format. Here, \meta{keys \pgfmathparse{exp(15)} \pgfmathprintnumber{\pgfmathresult} \end{codeexample} - The style resets |1000 sep|, |dec sep|, |print sign|, |skip 0.| and sets |assume math mode|. Furthermore, it installs a |sci generic| format for verbatim output of scientific numbers. + The style resets |1000 sep|, |dec sep|, |print sign|, |skip 0.| and + sets |assume math mode|. Furthermore, it installs a |sci generic| + format for verbatim output of scientific numbers. - However, it will still respect |precision|, |fixed zerofill|, |sci zerofill| and the overall styles |fixed|, |sci|, |int detect| (and their variants). It might be useful if you intent to write output files. + However, it will still respect |precision|, |fixed zerofill|, + |sci zerofill| and the overall styles |fixed|, |sci|, |int detect| + (and their variants). It might be useful if you intend to write + output files. \end{stylekey} %-------------------------------------------------- % \subsubsection{Defining own display styles} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex index 1d28cfa4fea..37df357e706 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-math-parsing.tex @@ -13,14 +13,14 @@ The easiest way of using \pgfname's mathematical engine is to provide a mathematical expression given in familiar infix notation, for example, |1cm+4*2cm/5.5| or |2*3+3*sin(30)|. This expression can be -parsed by the mathematical engine and the result be placed in a +parsed by the mathematical engine and the result can be placed in a dimension register, a counter, or a macro. It should be noted that all calculations must not exceed $\pm16383.99999$ at \emph{any} point, because the underlying computations rely on \TeX{} dimensions. This means that many of the underlying computations are necessarily -approximate and that in addition, are not very fast. \TeX{} is, +approximate and, in addition, not very fast. \TeX{} is, after all, a typesetting language and not ideally suited to relatively advanced mathematical operations. However, it is possible to change the computations as described in @@ -53,56 +53,77 @@ engine is the following: \begin{itemize} \item - The result stored in the macro |\pgfmathresult| is a decimal - \emph{without units}. This is true regardless of whether the - \meta{expression} contains any unit specification. All numbers - with units are converted to points first. - + The result stored in the macro |\pgfmathresult| is a decimal + \emph{without units}. This is true regardless of whether the + \meta{expression} contains any unit specification. All numbers + with units are converted to points first. + You can check whether an expression contained a unit using + the following \TeX-if. + {\let\ifpgfmathunitsdeclared\relax + \begin{command}{\ifpgfmathunitsdeclared} + After a call of |\pgfmathparse| this if will be true exactly if + some unit was encountered in the expression. It is always set + globally in each call. + \end{command} + } + + A special kind of units are \TeX's ``math units'' (|mu|). It will + be treated as if |pt| had been used, but you can + check whether an expression contained a math unit using the + following: + {\let\ifpgfmathmathunitsdeclared\relax + \begin{command}{\ifpgfmathmathunitsdeclared} + This \TeX-if is similar to |\ifpgfmathunitsdeclared|, but it + is only set when the unit |mu| is encountered at least + once. In this case, |\ifpgfmathunitsdeclared| will \emph{also} + be set to true. + \end{command} + } \item - You can check whether an expression contained a unit using - the \TeX-if |\||ifpgfmathunitsdeclared|. After a call - of |\pgfmathparse| this if will be true exactly if some unit was - encountered in the expression. - + The parser will recognize \TeX{} registers and box dimensions, + so |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|, + |\mycount\mydimen| and so on can be parsed. + \item - The parser can recognize \TeX{} registers and box dimensions, - so |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|, - |\mycount\mydimen| and so on can be parsed. - + The $\varepsilon$-TeX\ extensions |\dimexpr|, |\numexpr|, |\glueexpr|, and + |\muexpr| are recognized and evaluated. The values they + result in will be used in the further evaluation, as if you had + put |\the| before them. + \item - Parenthesis can be used to change the order of the evaluation. - + Parenthesis can be used to change the order of the evaluation. + \item - Various functions are recognized, so it is possible to parse - |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$ - radians, multiplied by 60''. The argument of functions can - be any expression. - + Various functions are recognized, so it is possible to parse + |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$ + radians, multiplied by 60''. The argument of functions can + be any expression. + \item - Scientific notation in the form |1.234e+4| is recognized (but - the restriction on the range of values still applies). The exponent - symbol can be upper or lower case (i.e., |E| or |e|). - + Scientific notation in the form |1.234e+4| is recognized (but + the restriction on the range of values still applies). The exponent + symbol can be upper or lower case (i.e., |E| or |e|). + \item - An integer with a zero-prefix (excluding, of course zero itself), - is interpreted as an octal number and is automatically converted - to base 10. - + An integer with a zero-prefix (excluding, of course zero itself), + is interpreted as an octal number and is automatically converted + to base 10. + \item - An integer with prefix |0x| or |0X| is interpreted as a hexadecimal - number and is automatically converted to base 10. Alphabetic digits - can be in uppercase or lowercase. - - \item - An integer with prefix |0b| or |0B| is interpreted as a binary - number and is automatically converted to base 10. - + An integer with prefix |0x| or |0X| is interpreted as a hexadecimal + number and is automatically converted to base 10. Alphabetic digits + can be in uppercase or lowercase. + \item - An expression (or part of an expression) surrounded with double - quotes (i.e., the character |"|) will not be evaluated. - Obviously this should be used with great care. - -\end{itemize} + An integer with prefix |0b| or |0B| is interpreted as a binary + number and is automatically converted to base 10. + + \item + An expression (or part of an expression) surrounded with double + quotes (i.e., the character |"|) will not be evaluated. + Obviously this should be used with great care. + + \end{itemize} \end{command} @@ -127,9 +148,9 @@ engine is the following: At the end of the parse this command is executed, allowing some custom action to be performed on the result of the parse. When this - command is executed the macro |\pgfmathresult| will hold the result - of the parse (as ever, without units). The result of the custom - action should be to redefined |\pgfmathresult| appropriately. + command is executed, the macro |\pgfmathresult| will hold the result + of the parse (as always, without units). The result of the custom + action should be used to redefine |\pgfmathresult| appropriately. By default, this command is equivalent to |\relax|. This differs from previous versions, where, if the parsed expression contained no units, the result of the parse was scaled according to the value @@ -143,7 +164,7 @@ engine is the following: \end{command} -Instead of the |\pgfmathparse| macro you can also wrapper commands, +Instead of the |\pgfmathparse| macro you can also use wrapper commands, whose usage is very similar to their cousins in the \calcname{} package. The only difference is that the expressions can be any expression that is handled by |\pgfmathparse|. @@ -152,15 +173,57 @@ For all of the following commands, if \meta{expression} starts with using normal \TeX\ assignments or increments. This will be orders of magnitude faster than calling the parser. -\begin{command}{\pgfmathsetlength\marg{dimension register}\marg{expression}} - Sets the length of the \TeX{} \meta{dimension register}, to the value - (in points) specified by \meta{expression}. The \meta{expression} - will be parsed using |\pgfmathparse|. +The effect of the following commands is always local to the current +\TeX\ scope. + +\begin{command}{\pgfmathsetlength\marg{register}\marg{expression}} + Basically, this command sets the length of the \TeX{} + \meta{register} to the value specified by + \meta{expression}. However, there is some fine print: + + First, in case \meta{expression} starts with a |+|, a simple \TeX\ + assignment is done. In particular, \meta{register} can be a glue + register and \meta{expression} be something like |+1pt plus 1fil| + and the \meta{register} will be assigned the expected value. + + Second, when the \meta{expected} does not start with |+|, it is + first parsed using |\pgfmathparse|, resulting in a (dimensionless) + value |\pgfmathresult|. Now, if the parser encountered the unit |mu| + somewhere in the expression, it assumes that \meta{register} is a + |\muskip| register and will try to assign to \meta{register} the + value |\pgfmathresult| followed by |mu|. Otherwise, in case |mu| was + not encountered, it is assumed that \meta{register} is a dimension + register or a glue register and we assign |\pgfmathresult| followed + by |pt| to it. + + The net effect of the above is that you can write things like +\begin{codeexample}[] + \muskipdef\mymuskip=0 + \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip +\end{codeexample} +\begin{codeexample}[] + \dimendef\mydimen=0 + \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen +\end{codeexample} +\begin{codeexample}[] + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip +\end{codeexample} + + One thing that will \emph{not} work is + |\pgfmathsetlength{\myskip}{1pt plus 1fil}| since the parser does + not support fill's. You can, however, use the |+| notation in this + case: +\begin{codeexample}[] + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip +\end{codeexample} \end{command} -\begin{command}{\pgfmathaddtolength\marg{dimension register}\marg{expression}} - Adds the value (in points) of \meta{expression} to the \TeX{} - \meta{dimension register}. +\begin{command}{\pgfmathaddtolength\marg{register}\marg{expression}} + Adds the value of \meta{expression} to the \TeX{} + \meta{register}. All of the special consideration mentioned for + |\pgfmathsetlength| also apply here in the same way. \end{command} \begin{command}{\pgfmathsetcount\marg{count register}\marg{expression}} @@ -174,7 +237,7 @@ magnitude faster than calling the parser. \end{command} \begin{command}{\pgfmathsetcounter\marg{counter}\marg{expression}} - Sets the value of the \LaTeX{} \meta{counter}, to the \emph{truncated} + Sets the value of the \LaTeX{} \meta{counter} to the \emph{truncated} value specified by \meta{expression}. \end{command} @@ -190,7 +253,7 @@ magnitude faster than calling the parser. \begin{command}{\pgfmathsetlengthmacro\marg{macro}\marg{expression}} Defines \meta{macro} as the value of \meta{expression} - \LaTeX{}\emph{in points}. + \LaTeX{} \emph{in points}. \end{command} \begin{command}{\pgfmathtruncatemacro\marg{macro}\marg{expression}} @@ -242,7 +305,7 @@ magnitude faster than calling the parser. Raises \mvar{x} to the power \mvar{y}. \end{math-operator} -\begin{math-operator}{!}{postfix}{factorial} +\begin{math-operator}{\protect\exclamationmarktext}{postfix}{factorial} Calculates the factorial of \mvar{x}. \end{math-operator} @@ -272,7 +335,7 @@ magnitude faster than calling the parser. Returns |1| if \mvar{x}$<$\mvar{y}, |0| otherwise. \end{math-operator} -\begin{math-operator}{!=}{infix}{notequal} +\begin{math-operator}{\protect\exclamationmarktext=}{infix}{notequal} Returns |1| if \mvar{x}$\neq$\mvar{y}, |0| otherwise. \end{math-operator} @@ -301,7 +364,7 @@ magnitude faster than calling the parser. \end{math-operator} } -\begin{math-operator}{!}{prefix}{not} +\begin{math-operator}{\protect\exclamationmarktext}{prefix}{not} Returns |1| if \mvar{x} evaluates to zero, |0| otherwise. \end{math-operator} @@ -355,7 +418,7 @@ the array, an error will occur, and zero will be returned. \pgfmathparse{\myarray[3]} \pgfmathresult \end{codeexample} -If the array is defined to have multiple dimensions then the array +If the array is defined to have multiple dimensions, then the array access operators can be immediately repeated. \begin{codeexample}[] @@ -368,7 +431,7 @@ access operators can be immediately repeated. \end{math-operators} -\begin{math-operators}{"}{"}{group}{} +\begin{math-operators}{\char`\"}{\char`\"}{group}{} These operators are used to quote \mvar{x}. However, as every expression is expanded with |\edef| before it is parsed, macros @@ -403,18 +466,18 @@ The following functions are recognized: \foreach \f [count=\i from 0] in {abs,acos,add,and,array,asin,atan,atan2,bin,ceil,cos, cosec,cosh,cot,deg,depth,div,divide,e,equal,factorial, false, - floor,frac,greater,height,hex,Hex,int,ifthenelse, + floor,frac,gcd,greater,height,hex,Hex,int,ifthenelse,iseven,isodd,isprime, less,ln,log10,log2,max,min,mod,Mod,multiply, neg,not,notequal,notgreater,notless, oct,or,pi,pow,rad,rand,random,real,rnd,round, sec,sin,sinh,sqrt,subtract,tan,tanh,true, veclen,width} -\node [anchor=base west] at ({int(\i/11)*2.5cm},{-mod(\i,11)*1.1*\baselineskip}) {\mathlink{\f}}; +\node [anchor=base west] at ({int(\i/12)*2.5cm},{-mod(\i,12)*1.1*\baselineskip}) {\mathlink{\f}}; \end{tikzpicture} \bigskip Each function has a \pgfname{} command associated with it (which is -also shown with the function below). In general the command +also shown with the function below). In general, the command is simply the name of the function prefixed with |\pgfmath|, for example, |\pgfmathadd|, but there are some notable exceptions. @@ -512,9 +575,9 @@ example, |\pgfmathadd|, but there are some notable exceptions. \begin{math-function}{pow(\mvar{x},\mvar{y})} \mathcommand - Raises \mvar{x} to the power \mvar{y}. For greatest accuracy - \mvar{y} should be an integer. If \mvar{y} is not an integer - the actual calculation will be an approximation of $e^{yln(x)}$. + Raises \mvar{x} to the power \mvar{y}. For greatest accuracy, + \mvar{y} should be an integer. If \mvar{y} is not an integer, + the actual calculation will be an approximation of $e^{y\text{ln}(x)}$. \begin{codeexample}[] \pgfmathparse{pow(2,7)} \pgfmathresult @@ -563,7 +626,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. \catcode`\^=7 An approximation for $\ln(\textrm{\mvar{x}})$. - This uses an algorithm due to Rouben Rostamian, and coefficients + This uses an algorithm of Rouben Rostamian, and coefficients suggested by Alain Matthes. } \begin{codeexample}[] @@ -654,7 +717,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. Rounds \mvar{x} to the nearest integer. It uses ``asymmetric half-up'' rounding. So |1.5| is rounded to |2|, but |-1.5| is rounded to |-2| - (\emph{not} |1|). + (\emph{not} |-1|). \begin{codeexample}[] \pgfmathparse{round(32.5/17)} \pgfmathresult @@ -679,6 +742,9 @@ example, |\pgfmathadd|, but there are some notable exceptions. \pgfmathparse{floor(398/12)} \pgfmathresult \end{codeexample} +\begin{codeexample}[] +\pgfmathparse{floor(-398/12)} \pgfmathresult +\end{codeexample} \end{math-function} \begin{math-function}{ceil(\mvar{x})} @@ -694,6 +760,10 @@ example, |\pgfmathadd|, but there are some notable exceptions. \pgfmathparse{ceil(398/12)} \pgfmathresult \end{codeexample} +\begin{codeexample}[] +\pgfmathparse{ceil(-398/12)} \pgfmathresult +\end{codeexample} + \end{math-function} \begin{math-function}{int(\mvar{x})} @@ -730,6 +800,58 @@ example, |\pgfmathadd|, but there are some notable exceptions. \end{math-function} +\subsubsection{Integer arithmetics functions} + +\label{pgfmath-functions-integerarithmetics} + +\begin{math-function}{gcd(\mvar{x},\mvar{y})} +\mathcommand + + Computes the greatest common divider of \mvar{x} and \mvar{y}. + +\begin{codeexample}[] +\pgfmathparse{gcd(42,56)} \pgfmathresult +\end{codeexample} + +\end{math-function} + +\begin{math-function}{isodd(\mvar{x})} +\mathcommand + + Returns |1| if the integer part of \mvar{x} is odd. Otherwise, returns |0|. + +\begin{codeexample}[] +\pgfmathparse{isodd(2)} \pgfmathresult, +\pgfmathparse{isodd(3)} \pgfmathresult +\end{codeexample} + +\end{math-function} + +\begin{math-function}{iseven(\mvar{x})} +\mathcommand + + Returns |1| if the integer part of \mvar{x} is even. Otherwise, returns |0|. + +\begin{codeexample}[] +\pgfmathparse{iseven(2)} \pgfmathresult, +\pgfmathparse{iseven(3)} \pgfmathresult +\end{codeexample} + +\end{math-function} + +\begin{math-function}{isprime(\mvar{x})} +\mathcommand + + Returns |1| if the integer part of \mvar{x} is prime. Otherwise, returns |0|. + +\begin{codeexample}[] +\pgfmathparse{isprime(1)} \pgfmathresult, +\pgfmathparse{isprime(2)} \pgfmathresult, +\pgfmathparse{isprime(31)} \pgfmathresult, +\pgfmathparse{isprime(64)} \pgfmathresult +\end{codeexample} + +\end{math-function} \subsubsection{Trigonometric functions} @@ -891,8 +1013,8 @@ example, |\pgfmathadd|, but there are some notable exceptions. \end{math-function} -\begin{math-function}{atan2(\mvar{x},\mvar{y})} -\mathcommand[atantwo(\mvar{x},\mvar{y})] +\begin{math-function}{atan2(\mvar{y},\mvar{x})} +\mathcommand[atantwo(\mvar{y},\mvar{x})] Arctangent of $y\div x$ in degrees. This also takes into account the quadrants. @@ -1050,7 +1172,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. \begin{math-function}{rnd} \mathcommand - Generates a pseudo-random number between 0 and 1. + Generates a pseudo-random number between $0$ and $1$ with a uniform distribution. \begin{codeexample}[] \foreach \x in {1,...,10}{\pgfmathparse{rnd}\pgfmathresult, } @@ -1061,7 +1183,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. \begin{math-function}{rand} \mathcommand - Generates a pseudo-random number between -1 and 1. + Generates a pseudo-random number between $-1$ and $1$ with a uniform distribution. \begin{codeexample}[] \foreach \x in {1,...,10}{\pgfmathparse{rand}\pgfmathresult, } @@ -1072,11 +1194,11 @@ example, |\pgfmathadd|, but there are some notable exceptions. \begin{math-function}{random(\opt{\mvar{x},\mvar{y}})} \mathcommand This function takes zero, one or two arguments. If there are zero - arguments, a random number between 0 and 1 is generated. If there is - one argument \mvar{x}, a random integer between 1 and \mvar{x} is + arguments, a uniform random number between $0$ and $1$ is generated. If there is + one argument \mvar{x}, a random integer between $1$ and \mvar{x} is generated. Finally, if there are two arguments, a random integer between \mvar{x} and \mvar{y} is generated. If there are no - arguments the \pgfname{} command should be called as follows: + arguments, the \pgfname{} command should be called as follows: |\pgfmathrandom{}|. \begin{codeexample}[] @@ -1123,7 +1245,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. \begin{math-function}{oct(\mvar{x})} \mathcommand - Convert \mvar{x}{} (assumed to be an integer in base 10) to a + Convert \mvar{x}{} (assumed to be an integer in base 10) to an octal representation. No further calculation should be attempted with the result, as the parser can only process numbers converted to base 10. @@ -1183,8 +1305,7 @@ example, |\pgfmathadd|, but there are some notable exceptions. \mathcommand Calculates $\sqrt{\left(\textrm{\mvar{x}}^2+\textrm{\mvar{y}}^2\right)}$. - This uses a polynomial approximation, based on ideas due - to Rouben Rostamian + This uses a polynomial approximation, based on ideas of Rouben Rostamian \begin{codeexample}[] \pgfmathparse{veclen(12,5)} \pgfmathresult \end{codeexample} @@ -1249,7 +1370,7 @@ suggested by Martin Heller: \mathcommand Return the width of a \TeX{} (horizontal) box containing \mvar{x}. - The quote characters are necessary to prevent \mvar{x}{} being + The quote characters are necessary to prevent \mvar{x}{} from being parsed. It is important to remember that any expression is expanded with |\edef| before being parsed, so any macros (e.g., font commands @@ -1259,6 +1380,8 @@ suggested by Martin Heller: \begin{codeexample}[] \pgfmathparse{width("Some Lovely Text")} \pgfmathresult \end{codeexample} + + Note that results of this method are provided in points. \end{math-function} \begin{math-function}{height("\mvar{x}")} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex index 8668d69ad24..f2ac87509d9 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex @@ -20,7 +20,7 @@ This module provides commands for defining a parser that scans some given text letter-by-letter. For each letter, some code is executed -and, possible, a state-switch occurs. The parsing process ends when a +and, possibly a state-switch occurs. The parsing process ends when a final state has been reached. \begin{command}{\pgfparserparse\marg{parser name}\meta{text}} @@ -73,7 +73,7 @@ There are \the\mycount\ a's. Inside the \meta{action} you can perform almost any kind of code. This code will not be surrounded by a scope, so its effect - persist after the parsing is done. However, each time after the + persists after the parsing is done. However, each time after the \meta{action} is executed, control goes back to the parser. You should not launch a parser inside the \meta{action} code, unless you put it in a scope. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex index 5044c0bd183..7f11f1d06e0 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-oo.tex @@ -42,8 +42,8 @@ for non-time-critical things. Basically, the oo-system supports \emph{classes} (in the object-oriented sense, this has nothing to do with \LaTeX-classes), \emph{methods}, \emph{constructors}, \emph{attributes}, -\emph{objects}, and \emph{object identities}. It (currently) does not -support either inheritance, overloading, destructors, or class nesting. +\emph{objects}, \emph{object identities}, and (thanks to Sa\v o \v +Zivanovi\'c) \emph{inheritance} and \emph{overloading.} The first step is to define a class, using the macro |\pgfooclass| (all normal macros in \pgfname's object-oriented system start with @@ -58,7 +58,7 @@ Once a class has been defined, you can create objects of this class. Objects are created using |\pgfoonew|. Such an object has many characteristics of objects in a normal object-oriented programming language: Each object has a \emph{unique identity}, so when you create -another object this object is completely distinct from all other +another object, this object is completely distinct from all other objects. Each object also has a set of private attributes, which may change over time. Suppose, for instance, that we have a |point| class. Then creating a new object (called an instance) of this class @@ -101,15 +101,16 @@ addition to \pgfname). We start with the definition of the |stamp| class. This is done using the |\pgfooclass| macro: -\begin{command}{\pgfooclass\marg{class name}\marg{body}} +\begin{command}{\pgfooclass\opt{|(|\meta{list of superclasses}|)|}\marg{class name}\marg{body}} This command defines a class named \meta{class name}. The name of the class can contain spaces and most other characters, but no periods. So, valid class names are |MyClass| or |my class| or - |Class_C++_emulation??1|. + |Class_C++_emulation??1|. The \meta{list of superclasses} is + optional just like the parenthesis around it. The \meta{body} is actually just executed, so any normal \TeX-code is permissible here. However, while the \meta{body} is - being executed, the macros |\method| and |\attribute| are setup so + being executed, the macros |\method| and |\attribute| are set up so that they can be used to define methods and attributes for this class (the original meanings are restored afterward). @@ -133,6 +134,17 @@ the |\pgfooclass| macro: % We can now create objects of type "stamp" \end{codeexample} + + Concerning the list of base classes, the Method Resolution Order + (\textsc{mro}) is computed using the C3 algorithm also used in Python, v2.3 + and higher. The linearization computed by the algorithm respects + both local precedence ordering and monotonicity. Resolution of both + methods and attributes depends on the \textsc{mro}: when a method method name + is called on an object of class $C$, the system invokes method + method name from the first class in the \textsc{mro} of $C$ which defines + method method name; when an object is created, each attribute |attr| + is initialized to the value specified in the first class in the \textsc{mro} + of $C$ which declares attribute |attr|. \end{command} The \meta{body} of a class usually just consists of calls to the macros @@ -173,7 +185,7 @@ peculiar syntax: The optional \meta{object handle or attribute} can either be an \meta{object handle} or an \meta{attribute}. When an \meta{object - handle} is give, it must be a normal \TeX\ macro name that will + handle} is given, it must be a normal \TeX\ macro name that will ``point'' to the object (handles are discussed in more detail in Section~\ref{section-identities}). You can use this macro to call methods of the object as discussed in the following section. When an @@ -217,20 +229,21 @@ command: names can contain spaces and other characters, so \meta{method names} like |put_stamp_here| or |put stamp here| are both legal. - Three method names are special: First, a method having the same name - as the class is called the \emph{constructor} of the class. The must be - such a method, even if its body is empty. There are (currently) no + Three method names are special: First, a method having either the + same name as the class or having the name |init| is called the + \emph{constructor} of the class. There are (currently) no destructors; objects simply become ``undefined'' at the end of the scope in which they have been created. The other two methods are called |get id| and |get handle|, which are always automatically defined and which you cannot redefine. They are discussed in Section~\ref{section-identities}. - Overloading of methods is not possible, that is, it is illegal to - have two methods inside a single class with the same name (despite - possibly different parameter lists). However, two different classes - may contain a method with the same name, that is, classes form - namespaces for methods. + Overloading of methods by differing numbers of parameters is not + possible, that is, it is illegal to have two methods inside a single + class with the same name (despite possibly different parameter + lists). However, two different classes may contain a method with the + same name, that is, classes form namespaces for methods. Also, a + class can (re)implement a method from a superclass. The \meta{method name} must be followed by a \meta{parameter list} in parentheses, which must be present even when the \meta{parameter @@ -244,8 +257,8 @@ command: When a method is called, the \meta{body} of the method will be executed. The main difference to a normal macro - is that while the \meta{body} is executed a special macro called - |\pgfoothis| is setup in such a way that it references that object + is that while the \meta{body} is executed, a special macro called + |\pgfoothis| is set up in such a way that it references the object for which the method is executed. \end{command} @@ -255,11 +268,18 @@ method for this object, a special syntax is used that is similar to Java or C++ syntax: \begin{pgfmanualentry} - \pgfmanualentryheadline{\meta{object handle}|.|\meta{method name}|(|\meta{parameters}|)|}% + \pgfmanualentryheadline{\meta{object handle}\opt{|.|\meta{super + class}}|.|\meta{method name}|(|\meta{parameters}|)|}% \pgfmanualbody This causes the method \meta{method name} to be called for the - object referenced by the \meta{object handle}. Naturally, the method - is the one defined in the class of the object. The \meta{parameters} + object referenced by the \meta{object handle}. The method is the one + defined in the class of the object or, if it is not defined there, + the method defined in the superclasses of the object's class (if + there are several superclasses that define the same method, the + method resolution order is used to determine which one gets + called). If the optional \meta{super class} is specified, the method + implementation of that class will be used rather than the + implementation in the object's class. The \meta{parameters} are matched against the parameters of the method and, then, the method body is executed. The execution of the method body is \emph{not} done inside a scope, so the effects of a method body @@ -320,6 +340,16 @@ Java or C++ syntax: \end{pgfmanualentry} +\begin{command}{\pgfoosuper|(|\meta{class},\meta{object + handle}|).|\meta{method name}|(|\meta{arguments}|)|} + This macro gives you finer control over which method gets invoked in + case of multiple inheritance. This macro calls \meta{method name} of + the object specified by \meta{object handle}, but which + implementation of the method is called is determined as follows: it + will be the implementation in the first class (in the method + resolution order) after \meta{class} that defines \meta{method + name}. +\end{command} \subsection{Attributes} @@ -495,7 +525,7 @@ a method of this name yourself. Different object that are alive (that are still within the scope in which they were created) will always have different ids, so you can use the id to test for equality of objects. However, after an object - has been destroyed because its scope has ended the same id may be + has been destroyed because its scope has ended, the same id may be used again for newly created objects. Here is a typical application where you need to call this method: @@ -511,7 +541,7 @@ a method of this name yourself. the |get id| method and store the resulting id, rather than the handle. \end{predefinedmethod} -There is a second predefined methods, called |get handle|, which is also +There is a second predefined method, called |get handle|, which is also used to create object handles. \begin{predefinedmethod}{get handle(\marg{macro name})} @@ -535,22 +565,41 @@ used to create object handles. +\subsection{The Object Class} + +\label{section-object} + +The object-oriented module predefines a basic class |object| that can +be used as a base class in different context. + +\begin{ooclass}{object} + This class current only implements one method: + + \begin{method}{copy(\meta{handle})} + Creates a new object and initializes the values of its (declared) + attributes to the values of the original. The method takes one + argument: a control sequence which receives the handle of the + copy. + \end{method} +\end{ooclass} + + \subsection{The Signal Class} \label{section-signals} -The object-oriented module predefines, in addition to the basic mechanism -for defining and using classes and object, one class: |signal|. This -class implements a so-called signal--slot mechanism. +In addition to the basic mechanism for defining and using classes and +object, the class |signal| is predefined. It implements a so-called +signal--slot mechanism. \begin{ooclass}{signal} This class is used to implement a simple signal--slot - mechanism. The idea is the following: Form time to time special + mechanism. The idea is the following: From time to time special things happen about which a number of objects need to be informed. Different things can happen and different object will be interested in these things. A |signal| object can be used to signal that such special things of a certain kind have happened. For - example, on signal object might be used to signal the event that ``a + example, one signal object might be used to signal the event that ``a page has been shipped out.'' Another signal might be used to signal that ``a figure is about to be typeset,'' and so on. @@ -648,6 +697,6 @@ implemented: value. This is done without scopes, so some tricky |\expandafter| magic is needed. Note that, because of this process, you cannot use commands like |\pgfutil@ifnextchar| at the end of a method. -\item An object handle contains just the code to setup and restore the +\item An object handle contains just the code to set up and restore the current object number to the number of the object being called. \end{itemize} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex index 57bf5b7cd98..452690a36d0 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pages.tex @@ -10,7 +10,7 @@ \section{Page Management} -This section describes the |pgfpages| packages. Although this package +This section describes the |pgfpages| package. Although this package is not concerned with creating pictures, its implementation relies so heavily on \pgfname\ that it is documented here. Currently, |pgfpages| only works with \LaTeX, but if you are adventurous, feel free to hack @@ -39,7 +39,7 @@ future. The internals of |pgfpages| are complex since the package can do all sorts of interesting tricks. For this reason, so-called \emph{layouts} -are predefined that setup all option in appropriate ways. +are predefined that set up all option in appropriate ways. You use a layout as follows: \begin{codeexample}[code only] @@ -170,8 +170,7 @@ printing on letter paper: This section explains the predefined layouts in more detail. You select a layout using the following command: \begin{command}{\pgfpagesuselayout\marg{layout}\oarg{options}} - Installs the specified \meta{layout} with the given \meta{options} - set. The predefined layouts and their permissible options are + Installs the specified \meta{layout} with the given \meta{options}. The predefined layouts and their permissible options are explained below. If this function is called multiple times, only the last call @@ -232,7 +231,7 @@ select a layout using the following command: landscape mode). When using this layout, it is advisable to use the |\nofiles| command, but this is not done automatically. - The same \meta{options} as for the |resize to| layout an be used, + The same \meta{options} as for the |resize to| layout can be used, plus the following option: \begin{itemize} \item @@ -244,11 +243,11 @@ select a layout using the following command: \begin{pgflayout}{4 on 1} Puts four logical pages on a single physical page. - The same \meta{options} as for the |resize to| layout an be used. + The same \meta{options} as for the |resize to| layout can be used. \end{pgflayout} \begin{pgflayout}{8 on 1} - Puts eight logical pages on a single physical page. As for |2 on 1|, + Puts eight logical pages on a single physical page. As for |2 on 1| and |4 on 1|, the orientation depends on whether the logical pages are in landscape mode or in portrait mode. \end{pgflayout} @@ -265,13 +264,13 @@ select a layout using the following command: page to the physical page size. Then four black rectangles are drawn in each corner. Next, a clipping region is set up that contains all of the logical page except for little rounded - corners. Finally, the logical page is draw, clipped against the + corners. Finally, the logical page is drawn and clipped against the clipping region. Note that every logical page should fill its background for this to work. - In addition to the \meta{options} that can be given to |resize to| + In addition to the \meta{options} that can be given to |resize to|, the following options may be given. \begin{itemize} \item \declare{|corner width=|\meta{size}} specifies the size of @@ -292,7 +291,7 @@ select a layout using the following command: This layout puts two logical pages alongside each other. The second page always shows what the main page showed on the previous physical page. Thus, the second page - ``lags behind'' the main page. This can be useful when you have to + ``lags behind'' the main page. This can be useful when you have two projectors attached to your computer and can show different parts of a physical page on different projectors. @@ -302,7 +301,7 @@ select a layout using the following command: main page. This will make the physical pages twice as wide as the logical pages, but it will retain the height. \item \declare{|second left|} puts the second page left, - otherwise it behave the same as |second right|. + otherwise it behaves the same as |second right|. \item \declare{|second bottom|} puts the second page below the main page. This make the physical pages twice as high as the logical ones. @@ -335,7 +334,7 @@ command: When |\pgfpagesuselayout|\marg{layout}\oarg{options} is called, the following happens: First, the \meta{before actions} are - executed. They can be used, for example, to setup default values for + executed. They can be used, for example, to set up default values for keys. Next, |\setkeys{pgfpagesuselayoutoption}|\marg{options} is executed. Finally, the \meta{after actions} are executed. @@ -392,7 +391,7 @@ send the physical page to the output file. In reality, things are slightly more complicated. First, once a physical page has been shipped out, the logical pages are usually voided, but this need not be the case. Instead, it is possible that -certain logical page just retain their contents after the physical +certain logical pages just retain their contents after the physical page has been shipped out and these pages need not be filled once more before a physical shipout can occur. However, the contents of these logical pages can still be changed using special commands. It is also @@ -404,7 +403,7 @@ physical page and which further modifications should be done. The following two commands are used to define the layout: \begin{command}{\pgfpagesphysicalpageoptions\marg{options}} - This command sets the characteristic of the ``physical'' page. For + This command sets the characteristics of the ``physical'' page. For example, it is used to specify how many logical pages there are and how many logical pages must be accumulated before a physical page is shipped out. How each individual logical page is typeset is @@ -469,7 +468,7 @@ following two commands are used to define the layout: \meta{current} has been filled, the internal counter is incremented normally as if the logical page \meta{current} had been ``reached'' normally. If you specify a \meta{current} larger - to \meta{last}, a physical shipout will occur after the logical + than \meta{last}, a physical shipout will occur after the logical page \meta{current} has been filled. \item \declare{|physical height=|\meta{height}} @@ -577,8 +576,8 @@ following two commands are used to define the layout: \end{codeexample} \item \declare{|border shrink|=\meta{size}} - specifies an addition reduction of the size to which the page is - page is scaled down. + specifies an additional reduction of the size to which the page is + page is scaled. \item \declare{|border code|=\meta{code}}. When this option is given, the \meta{code} is executed before the @@ -591,7 +590,7 @@ following two commands are used to define the layout: You can also call |\pgfdiscardpath| and add your own path construction code (for example to paint a rectangle with rounded - corners). The coordinate system is setup in such a way that a + corners). The coordinate system is set up in such a way that a rectangle starting at the origin and having the height and width of \TeX-box 0 will result in a rectangle filling exactly the logical page currently being put on the physical page. The logical @@ -614,13 +613,13 @@ following two commands are used to define the layout: \subsection{Creating Logical Pages} -Logical pages are created whenever a \TeX\ thinks that a page is full +Logical pages are created whenever \TeX\ thinks that a page is full and performs a |\shipout| command. This will cause |pgfpages| to store the box that was supposed to be shipped out internally until enough logical pages have been collected such that a physical shipout can occur. -Normally, whenever a logical shipout occurs that current page is +Normally, whenever a logical shipout occurs, that current page is stored in logical page number \meta{current logical page}. This counter is then incremented, until it is larger than \meta{last logical shipout}. You can, however, directly change the value of diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex index 318c01cf384..220955bc514 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfcalendar.tex @@ -108,7 +108,7 @@ This section describes the package |pgfcalendar|. set to |01| for January. The \meta{day macro} gets assigned a two-digit number representing - the day of the month (again with a possible leading zero). + the day of the month (again, possibly with a leading zero). To convert a Julian day number to an ISO-date you use code like the following: @@ -130,7 +130,7 @@ This section describes the package |pgfcalendar|. \example |\pgfcalendarjuliantoweekday{2454115}{\mycount}| sets |\mycount| to - \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount. + \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount\ (it was a Sunday). \end{command} @@ -142,8 +142,8 @@ This section describes the package |pgfcalendar|. This command is used to execute code based on properties of \meta{date}. The \meta{date} must be a date in ISO-format. For this date, the \meta{tests} are checked (to be detailed later) - and if one of the tests applied, the \meta{code} is - executed. If none of the tests applies, the \meta{else code} is + and if one of the tests succeeds, the \meta{code} is + executed. If none of the tests succeeds, the \meta{else code} is executed. \example |\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}| @@ -164,7 +164,7 @@ This section describes the package |pgfcalendar|. \itemcalendaroption{Sunday} as above. \itemcalendaroption{workday} Passed by Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays. - \itemcalendaroption{weekend} Passed Saturdays and Sundays. + \itemcalendaroption{weekend} Passed by Saturdays and Sundays. \itemcalendaroption{equals}|=|\meta{reference} The \meta{reference} can be in one of two forms: Either, it is a full ISO format date like |2007-01-01| or the year may be missing as in |12-31|. In the @@ -194,7 +194,7 @@ This section describes the package |pgfcalendar|. For another example, |between=05-01 and 05-07| is true for the days of the first week of May of any year. \itemcalendaroption{day of month}|=|\meta{number} Passed by the day - of month of the \meta{date} is \meta{number}. For example, the test + of month of the \meta{date} that is \meta{number}. For example, the test |day of month=1| is passed by every first of every month. \itemcalendaroption{end of month}\opt{|=|\meta{number}} Passed by the day of month of the \meta{date} that is \meta{number} from the @@ -205,9 +205,9 @@ This section describes the package |pgfcalendar|. \end{itemize} In addition to the above checks, you can also define new checks. To - do so, you must add a new key to the key-value group |pgfcalendar| - using |\define@key|. The job of the code of this new key is to - possibly set the \TeX-if |\ifpgfcalendarmatches| to true (if it is + do so, you must add a new key to the path |/pgf/calendar/| using + the |\pgfkeys| command. The job of the + code of this new key is to possibly set the \TeX-if |\ifpgfcalendarmatches| to true (if it is already true, no action should be taken) to indicate that the \meta{date} passes the test setup by this new key. @@ -229,17 +229,17 @@ This section describes the package |pgfcalendar|. \end{itemize} For example, let us define a new key that checks whether the - \meta{date} is a Workers day (first of May). This can be done as + \meta{date} is a Workers day (May 1st). This can be done as follows: \begin{verbatim} -\define@key{pgfcalendar}{workers day}[] +\pgfkeys{/pgf/calendar/workers day/.code=% { \ifnum\pgfcalendarifdatemonth=5\relax \ifnum\pgfcalendarifdateday=1\relax \pgfcalendarmatchestrue \fi \fi -} +}} \end{verbatim} \end{command} @@ -350,7 +350,7 @@ documentation of this package for more details. \item |\pgfcalendarendjulian| Julian day number of \meta{end date}. \item |\pgfcalendarcurrentjulian| This \TeX\ count holds the - Julian day number of day currently begin rendered. + Julian day number of the day currently being rendered. \item |\pgfcalendarcurrentweekday| The weekday (a number with zero representing Monday) of the current date. \item |\pgfcalendarcurrentyear| The year of the current date. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex index 9c3ef4832a8..770f0c89dc3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgffor.tex @@ -148,7 +148,7 @@ automatically by \tikzname, but not by \pgfname: |\foreach \x in {9,...,3.5} {\x, }| yields \foreach \x in {9,...,3.5} {\x, } - There is a yet a further special case for the |...| statement, in that + There is a yet another special case for the |...| statement, in that it can indicate an alphabetic character sequence: |\foreach \x in {a,...,m} {\x, }| yields \foreach \x in {a,...,m} {\x, } @@ -185,22 +185,26 @@ automatically by \tikzname, but not by \pgfname: \medskip \textbf{Using the foreach-statement inside paths.} - \tikzname\ allows you to use a |\foreach| statement inside a path - construction. In such a case, the \meta{commands} must be path - construction commands. Here are two examples: + \tikzname\ allows you to use |foreach| and |\foreach| (both have the + same effect) inside a path construction. In such a case, the + \meta{commands} must be path construction commands. Here are two + examples: \begin{codeexample}[] \tikz \draw (0,0) - \foreach \x in {1,...,3} + foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) } ; \end{codeexample} \begin{codeexample}[] -\tikz \draw \foreach \p in {1,...,3} {(\p,1)--(\p,3) (1,\p)--(3,\p)}; +\tikz \draw foreach \p in {1,...,3} {(\p,1)--(\p,3) (1,\p)--(3,\p)}; \end{codeexample} + Note that the |node| and |pic| path commands also support the + |foreach| statement in special ways. + \medskip \textbf{Multiple variables.} You will often wish to iterate over two variables at the same @@ -238,7 +242,7 @@ automatically by \tikzname, but not by \pgfname: \begin{codeexample}[] \begin{tikzpicture} % Define some coordinates: - \path[nodes={circle,fill=examplefill,draw}] + \path[nodes={circle,fill=yellow!80!black,draw}] (0,0) node(a) {a} (2,0.55) node(b) {b} (1,1.5) node(c) {c} @@ -264,7 +268,7 @@ automatically by \tikzname, but not by \pgfname: \begin{codeexample}[] \begin{tikzpicture}[line cap=round,line width=3pt] - \filldraw [fill=examplefill] (0,0) circle (2cm); + \filldraw [fill=yellow!80!black] (0,0) circle (2cm); \foreach \angle / \label in {0/3, 30/2, 60/1, 90/12, 120/11, 150/10, 180/9, @@ -295,7 +299,7 @@ automatically by \tikzname, but not by \pgfname: The keys described below can be used in the \meta{options} argument to the |\foreach| command. They all have the path |/pgf/foreach/|, however, the path is set automatically when \meta{options} are - parsed, so it does not have to explicitly stated. + parsed, so it does not have to be explicitly stated. \begin{key}{/pgf/foreach/var=\meta{variable}} This key provides an alternative way to specify variables: @@ -304,7 +308,7 @@ automatically by \tikzname, but not by \pgfname: \end{key} \begin{key}{/pgf/foreach/evaluate=\meta{variable}| |\opt{|as |\meta{macro}| using |\meta{formula}}} - By default list items are not evaluated: |1+2|, yields |1+2|, + By default, list items are not evaluated: |1+2|, yields |1+2|, not |3|. This key allows a variable to be evaluated using the mathematical engine. The variable must have been specified either using the |var| key or in the \meta{variables} argument of the diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex index 4ce292d380d..25825dc52c7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeys.tex @@ -147,10 +147,10 @@ executed whenever the style is executed. Here is an example: \pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}} \pgfkeys{/my style=wow} \end{codeexample} -As the above example shows, style can also be parametrized, just like +As the above example shows, styles can also be paramaterized, just like the normal code keys. -As a typical use of styles, suppose we wish to setup the key |/tikz| +As a typical use of styles, suppose we wish to set up the key |/tikz| so that it will change the default path to |/tikz|. This can be achieved as follows: \begin{codeexample}[code only] @@ -191,7 +191,7 @@ a slash, then the default path is automatically prefixed. Note that the default path is not the same as a search path. In particular, the default path is just a single path. When a partial key is given, only this single default path is prefixed; |pgfkeys| does -not try to lookup the key in different parts of a search path. It is, +not try to look up the key in different parts of a search path. It is, however, possible to emulate search paths, but a much more complicated mechanism must be used. @@ -222,7 +222,7 @@ continue with the next subsection. \end{command} \begin{command}{\pgfkeyslet\marg{full key}\marg{macro}} - Performs a |\let| statement so the the \meta{full key} pionts to the + Performs a |\let| statement so the \meta{full key} points to the contents of \meta{macro}. \begin{codeexample}[] \def\helloworld{Hello, world!} @@ -283,13 +283,13 @@ taken. This action can be one of the following: \item A command is executed whose argument(s) are \meta{value}. This command is stored in a special subkey of \meta{key}. \item The \meta{value} is stored in the \meta{key} itself. -\item If the key's name (the part after the last slahs) is a known +\item If the key's name (the part after the last slash) is a known \emph{handler}, then this handler will take care of the key. \item If the key is totally unknown, one of several possible \emph{unknown key handlers} is called. \end{enumerate} -Addtionally, if the \meta{value} is missing, a default value may or +Additionally, if the \meta{value} is missing, a default value may or may not be substituted. Before we plunge into all the details, let us have a quick look at the command itself. @@ -329,7 +329,7 @@ let us have a quick look at the command itself. \end{command} \begin{command}{\pgfkeysalso\marg{key list}} - This command has execatly the same effect as |\pgfkeys|, only the + This command has exactly the same effect as |\pgfkeys|, only the default path is not modified before or after the keys are being set. This command is mainly intended to be called by the code that is being processed for a key. @@ -344,6 +344,149 @@ let us have a quick look at the command itself. \end{command} +\subsubsection{First Char Syntax Detection} +\label{sec:pgf:first:char:syntax} + +Usually, keys are of the form \meta{key}|=|\meta{value} and how such +keys are handled is discussed in the rest of this section. However, it +is also possible to setup a different syntax for certain parts of the +input to |\pgfkeys|. Since this is a rather advanced option, most +readers may wish to skip the following discussion upon first reading; +it is discussed here because this special syntax detection is the very +first thing that is done when a key is processed, before any of the +following operations are performed. + +The |\pgfkeys| command and its variants decompose their input into a +list of \meta{string}s that are separated by commas. By default, each +such \meta{string} must either have the form \meta{key}|=|\meta{value} +or of the form \meta{key} with the value-part missing. However, you +might wish to interpret some of these strings differently. For +instance, when a \meta{string} has the form |"|\meta{text}|"|, you +might wish the \meta{string} to be interpreted as if one had written +|label text={|\meta{text}|}|. Then, people could write +\begin{codeexample}[code only] +\myset{red, "main valve", thick} +\end{codeexample} +instead of the more cumbersome +\begin{codeexample}[code only] +\myset{red, label text=main valve, thick} +\end{codeexample} +An example where such a syntax reinterpretation is done is the +|quotes| library, which allows you to write things like +\begin{codeexample}[] +\tikz \graph { a ->["1" red] b ->["0"] c }; +\end{codeexample} +\noindent instead of the somewhat longer +\begin{codeexample}[] +\tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c }; +\end{codeexample} + +In order to detect whether a \meta{string} has a special syntax, you +can request that the \emph{first character} of \meta{string} is +analysed by the key parser. If this first character matches a +character that has been flagged as a special character, the +\meta{string} is not interpreted as a usual key--value pair. Instead, +\meta{string} is passed as a parameter to a special macro that should +take care of the \meta{string}. After this macro has finished, the +parsing continues with the \meta{next string} in the list. + +In order to setup a special syntax handling for \meta{strings} that +begin with a certain character, two things need to be done: +\begin{enumerate} +\item First, the whole first char syntax detection must be ``switched + on,'' since, by default, it is turned off for efficiency reasons + (the overhead is rather small, however). This is done by setting the + following key: + \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}} + (default true, initially false)} + \end{key} +\item Second, in order to handle strings starting with a certain + \meta{character} in a special way, you need to store a macro in the + following key: + \begin{key}{/handlers/first char syntax/\meta{meaning of character}} + The \meta{meaning of character} should be the text that \TeX's + command |\meaning| returns for a macro that has been |\let| to the + \meta{character}. For instance, when strings starting with |"| + should be treated in a special way, the \meta{meaning of + character} would be the string |the character "| since this is + what \TeX\ writes when you say +\begin{codeexample}[] +\let\mycharacter=" +\meaning\mycharacter +\end{codeexample} + Now, the key |/handlers/first char syntax/|\meta{meaning of + character} should be setup (using |\pgfkeyssetvalue| or using + the |.initial| handler) to store a \meta{macro name}. + + If this is the case and if \meta{string} starts with the + \meta{character} (blanks at the beginning of \meta{string} are + deleted prior to this test), then \meta{macro name} is called with + \meta{string} as its argument. + \end{key} +\end{enumerate} + +Let us now have a look at an example. We install two handlers, one for +strings starting with |"| and one for strings starting with |<|. + +\begin{codeexample}[] +\pgfkeys{ + /handlers/first char syntax=true, + /handlers/first char syntax/the character "/.initial=\myquotemacro, + /handlers/first char syntax/the character </.initial=\mypointedmacro, +} + +\def\myquotemacro#1{Quoted: #1. } +\def\mypointedmacro#1{Pointed: #1. } + +\ttfamily \pgfkeys{"foo", <bar>} +\end{codeexample} + +Naturally, in the above examples, the two handling macros did not do +something particularly exciting. In the next example, we setup a more +elaborate macro that mimics a small part the behaviour of the |quotes| +library, only for single quotes: + +\begin{codeexample}[] +\pgfkeys{ + /handlers/first char syntax=true, + /handlers/first char syntax/the character '/.initial=\mysinglequotemacro +} + +\def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}} + +\tikz \node [circle, 'foo', draw] {bar}; +\end{codeexample} + +Note that in the above example, the macro |\mysinglequotemacro| gets +passed the complete string, including the single quotes. It is the job +of the macro to get rid of them, if this is necessary. + +The first char syntax detection allows you to perform rather powerful +transformations on the syntax of keys -- provided you can ``pin down'' +the syntax on the first character. In the following example, you can +write expressions in parentheses in front of a key--value pair and the +pair will only be executed when the expression evaluates to true: + +\begin{codeexample}[] +\pgfkeys{ + /handlers/first char syntax=true, + /handlers/first char syntax/the character (/.initial=\myparamacro +} + +\def\myparamacro#1{\myparaparser#1\someendtext} +\def\myparaparser(#1)#2\someendtext{ + \pgfmathparse{#1} + \ifx\pgfmathresult\onetext + \pgfkeysalso{#2} + \fi +} +\def\onetext{1} + +\foreach \i in {1,...,4} + \tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x}; +\end{codeexample} + + \subsubsection{Default Arguments} The arguments of the |\pgfkeys| command can either be of the form @@ -356,7 +499,7 @@ value is defined, it will be used as if you had written In the following, the details of how default values are determined is described; however, you should normally use the handlers |/.default| and |/.value required| as described in -Section~\ref{section-default-handlers} and you can may wish to skip +Section~\ref{section-default-handlers} and you may wish to skip the following details. When |\pgfkeys| encounters a \meta{key} without an equal-sign, the @@ -391,7 +534,7 @@ following happens: After the transformation process described in the previous subsection, we arrive at a key of the form \meta{key}=\meta{value}, where \meta{key} is a full key. Different things can now happen, but always -the macro |\pgfkeyscurrentkey| will have been setup to expand to the +the macro |\pgfkeyscurrentkey| will have been set up to expand to the text of the \meta{key} that is currently being processed. The first things that is tested is whether the key \meta{key}|/.@cmd| @@ -426,7 +569,7 @@ handlers described in Section~\ref{section-code-handlers}. \begin{command}{\pgfkeysdef\marg{key}\marg{code}} This command temporarily defines a \TeX-macro with the argument list |#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this - macro. The net effect of all this is that you have then setup code + macro. The net effect of all this is that you have then set up code for the key \meta{key} so that when you write |\pgfkeys{|\meta{key}|=|\meta{value}|}|, then the \meta{code} is executed with all occurrences of |#1| in \meta{code} being replaced @@ -517,9 +660,9 @@ key). It decomposed into two parts: detect for the reader. \end{enumerate} -(For efficiency reasons, these two macros are only setup at this point; +(For efficiency reasons, these two macros are only set up at this point; so when code is executed for a key in the ``usual'' manner then these -macros are not setup.) +macros are not set up.) The |\pgfkeys| command now checks whether the key |/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command @@ -527,7 +670,7 @@ and this command is executed exactly in the same manner as described in Section~\ref{section-key-code}. Thus, this code gets the \meta{value} that was originally intended for \meta{key} as its argument, followed by |\pgfeov|. -It is the job of the handlers to so something useful with the +It is the job of the handlers to do something useful with the \meta{value}. For an example, let us write a handler that will output the value @@ -550,10 +693,10 @@ this key and print it. \pgfkeys{/my key/.print to log} \end{codeexample} The above code will print |Hi!| in the log, provided the macro -|\writetolog| is setup appropriately. +|\writetolog| is set up appropriately. For a more interesting handler, let us program a handler that will -setup a key so that when the key is used some code is executed. This +set up a key so that when the key is used, some code is executed. This code is given as \meta{value}. All the handler must do is to call |\pgfkeysdef| for the path of the key (which misses the handler's name) and assign the parameter value to it. @@ -655,11 +798,13 @@ There are some parameters for handled keys which prove to be useful in some (pos key handler. \end{key} + + \subsubsection{Keys That Are Unknown} \label{sec:pgf:unknown:keys} -For some keys, neither the key is defined nor its |.@cmd| subkey nor -is a handler defined for this key. In this case, it is checked whether +For some keys, neither the key, nor its |.@cmd| subkey nor +a handler is defined. In this case, it is checked whether the key \meta{current path}|/.unknown/.@cmd| exists. Thus, when you try to use the key |/tikz/strange|, then it is checked whether |/tikz/.unknown/.@cmd| exists. If this key exists (which it does), it is @@ -668,13 +813,13 @@ instance, the handler for \tikzname\ will try to interpret the key's name as a color or as an arrow specification or as a \pgfname\ option. -You can setup unknown key handlers for your own keys by simply setting +You can set up unknown key handlers for your own keys by simply setting the code of the key \meta{my path prefix}|/.unknown|. This also allows -you to setup ``search paths.'' The idea is that you would like keys to +you to set up ``search paths.'' The idea is that you would like keys to be searched not only in a single default path, but in several. Suppose, for instance, that you would like keys to be searched -for in |/a|, |/b|, and |/b/c|. We setup a key |/my search path| for +for in |/a|, |/b|, and |/b/c|. We set up a key |/my search path| for this: \begin{codeexample}[code only] \pgfkeys{/my search path/.unknown/.code= @@ -780,125 +925,6 @@ also define new ones as described in Section~\ref{section-key-handlers}. |/.is family| handler is quicker. \end{handler} -\begin{handler}{{.search also}=\marg{path list}} - A style which installs a |/.unknown| handler into \meta{key}. This - |/.unknown| handler will then search for unknown keys in every path - provided in \marg{path list}. - -\begin{codeexample}[] -% define a key: -\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} - -% set up a search path: -\pgfkeys{/main path/.search also={/secondary path}} - -% try searching for `option=value' in '/main path': -% -> this finds `/secondary path/option'! -\pgfkeys{/main path/.cd,option=value} -\end{codeexample} - - The |/.search also| handler follows the strategy - \begin{enumerate} - \item If a user provides a fully qualified key which could not be - found, for example the full string |/main path/option|, it assume - that the user new what he is doing -- and does \emph{not} continue - searching for |an option| in \marg{path list}. - \item If a user provides only the key's name, for example |option| - and |option| can't be found in the current default path (which is - |/main path| in our example above), the current default path is - set to the next element in \marg{path list} (which is - |/secondary path| here) and |\pgfkeys| will be restarted. - - This will be iterated until either a match has been found or all - elements in \marg{path list} have been tested. - - \item If all elements in \marg{path list} have been checked and the - key is still unknown, the fall-back handler |/handlers/.unknown| - will be invoked. - \end{enumerate} -\begin{codeexample}[] -% define a key: -\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} - -% set up a search path: -\pgfkeys{/main path/.search also={/secondary path}} - -% try searching for `option=value' in '/main path': -% -> this finds `/secondary path/option'! -\pgfkeys{/main path/.cd,option=value} - -% negative example: -% try searching for fully qualified key /main path/option. -% This won't be handled by .search also. -\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}% -\pgfkeys{/main path/.cd,/main path/option=value} -\end{codeexample} - - Please note that the strategy of |/.search also| is different from - the first example provided in section~\ref{sec:pgf:unknown:keys} - ``Unknown Keys'' because |/.search also| only applies only for keys - which are not fully qualified. - - - For those who are familiar with |\pgfkeys|, the actual - implementation of |/.search also| might be interesting: - \begin{enumerate} - \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to -\begin{codeexample}[code only] -\pgfkeys{/path/.unknown/.code={% - \ifpgfkeysaddeddefaultpath - % only process keys for which no full path has been - % provided: - \pgfkeyssuccessfalse - \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW - \ifpgfkeyssuccess - \else - % search with /tikz as default path: - \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}% - \fi - \else - \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}% - \pgfutilnext - \fi - } -} -\end{codeexample} - \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to -\begin{codeexample}[code only] -\pgfkeys{/path/.unknown/.code={% - \ifpgfkeysaddeddefaultpath - \pgfkeyssuccessfalse - \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW - \ifpgfkeyssuccess - \else - % step 1: search in /tikz with .try: - \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}% - \fi - \ifpgfkeyssuccess - \else - % step 2: search in /pgf (without .try!): - \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}% - \fi - \else - \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}% - \pgfutilnext - \fi - } -} -\end{codeexample} - \end{enumerate} - - To also enable searching for styles (or other handled keys), - consider changing the configuration for handled keys to - |/hander config=full or existing| when you use |/.search also|, - that is, use -\begin{codeexample}[code only] -\pgfkeys{ - /main path/.search also={/secondary path}, - /handler config=full or existing} -\end{codeexample} -\end{handler} - \subsubsection{Setting Defaults} @@ -1079,7 +1105,7 @@ key list. Thus, a style ``stands for'' a certain key value list. Styles can be parameterized just like normal code. \begin{handler}{{.style}|=|\meta{key list}} - This handler set things up so that whenever \meta{key}|=|\meta{value} is + This handler sets things up so that whenever \meta{key}|=|\meta{value} is encountered in a key list, then the \meta{key list}, with every occurrence of |#1| replaced by \meta{value}, is processed instead. As always, if no \meta{value} is given, the default @@ -1176,8 +1202,8 @@ For styles the corresponding handlers as for normal code exist: For some keys, the code that should be executed for them is rather ``specialized.'' For instance, it happens often that the code for a -key just sets a certain \TeX-if to true or false. For these case -predefine handlers make it easier to install the necessary code. +key just sets a certain \TeX-if to true or false. For these cases, +predefined handlers make it easier to install the necessary code. However, we start with some handlers that are used to manage the value that is directly stored in a key. @@ -1196,7 +1222,7 @@ that is directly stored in a key. % "/my key" now stores the value "blue" \end{codeexample} - Note that in the after the example, writing |\pgfkeys{/my key}| will not + Note that with this configuration, writing |\pgfkeys{/my key}| will not have the effect you might expect (namely that |blue| is inserted into the main text). Rather, |/my key| will be promoted to |/my key=\pgfkeysnovalue| and, thus, |\pgfkeysnovalue| will be @@ -1300,7 +1326,7 @@ The next handler deals with the problem when a handler is useful. \begin{handler}{{.is choice}} - This handler set things up so that writing \meta{key}|=|\meta{value} + This handler sets things up so that writing \meta{key}|=|\meta{value} will cause the subkey \meta{key}|/|\meta{value} to be executed. So, each of the different possible choices should be given by a subkey of \meta{key}. @@ -1327,7 +1353,7 @@ can even use things like |#1| or unbalanced \TeX-ifs inside expanded before it is used. For instance, \meta{value} might be a macro name like |\mymacro| and you do not want |\mymacro| to be used as the macro, but rather the \emph{contents} of |\mymacro|. Thus, -instead of using \meta{value} you wish to use whatever \meta{value} +instead of using \meta{value}, you wish to use whatever \meta{value} expands to. Instead of using some fancy |\expandafter| hackery, you can use the following handlers: @@ -1384,6 +1410,148 @@ Key 4:& \pgfkeys{/key4} \end{codeexample} \end{handler} + + +\subsubsection{Handlers for Forwarding} + +\begin{handler}{{.forward to}|=|\meta{another key}} + This handler causes the \meta{key} to ``forward'' its argument to + \meta{another key}. When the \meta{key} is used, its normal code + will be executed first. Then, the value is (additionally) passed to + \meta{another key}. If the \meta{key} has not yet been defined prior + to the use of |.forward to|, it will be defined then (and do nothing by + itself, expect for forwarding it to \meta{key name}). The + \meta{another key} must be a fully qualified key name. +\begin{codeexample}[] +\pgfkeys{ + /a/.code=(a:#1), + /b/.code=(b:#1), + /b/.forward to=/a, + /c/.forward to=/a +} +\pgfkeys{/b=1} \pgfkeys{/c=2} +\end{codeexample} +\end{handler} + + +\begin{handler}{{.search also}=\marg{path list}} + A style which installs a |/.unknown| handler into \meta{key}. This + |/.unknown| handler will then search for unknown keys in every path + provided in \marg{path list}. + +\begin{codeexample}[] +% define a key: +\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} + +% set up a search path: +\pgfkeys{/main path/.search also={/secondary path}} + +% try searching for `option=value' in '/main path': +% -> this finds `/secondary path/option'! +\pgfkeys{/main path/.cd,option=value} +\end{codeexample} + + The |/.search also| handler follows the strategy + \begin{enumerate} + \item If a user provides a fully qualified key which could not be + found, for example the full string |/main path/option|, it assume + that the user knew what she is doing -- and does \emph{not} continue + searching for |an option| in \marg{path list}. + \item If a user provides only the key's name, for example |option| + and |option| cannot be found in the current default path (which is + |/main path| in our example above), the current default path is + set to the next element in \marg{path list} (which is + |/secondary path| here) and |\pgfkeys| will be restarted. + + This will be iterated until either a match has been found or all + elements in \marg{path list} have been tested. + \item If all elements in \marg{path list} have been checked and the + key is still unknown, the fall-back handler |/handlers/.unknown| + will be invoked. + \end{enumerate} +\begin{codeexample}[] +% define a key: +\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}} + +% set up a search path: +\pgfkeys{/main path/.search also={/secondary path}} + +% try searching for `option=value' in '/main path': +% -> this finds `/secondary path/option'! +\pgfkeys{/main path/.cd,option=value} + +% negative example: +% try searching for fully qualified key /main path/option. +% This won't be handled by .search also. +\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}% +\pgfkeys{/main path/.cd,/main path/option=value} +\end{codeexample} + + Please note that the strategy of |/.search also| is different from + the first example provided in section~\ref{sec:pgf:unknown:keys} + ``Unknown Keys'' because |/.search also| only applies to keys + that are not fully qualified. + + For those who are familiar with |\pgfkeys|, the actual + implementation of |/.search also| might be interesting: + \begin{enumerate} + \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to +\begin{codeexample}[code only] +\pgfkeys{/path/.unknown/.code={% + \ifpgfkeysaddeddefaultpath + % only process keys for which no full path has been + % provided: + \pgfkeyssuccessfalse + \let\pgfkeys@searchalso@name =\pgfkeyscurrentkeyRAW + \ifpgfkeyssuccess + \else + % search with /tikz as default path: + \pgfqkeys{/tikz}{\pgfkeys@searchalso@name={#1}}% + \fi + \else + \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}% + \pgfutilnext + \fi + } +} +\end{codeexample} + \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to +\begin{codeexample}[code only] +\pgfkeys{/path/.unknown/.code={% + \ifpgfkeysaddeddefaultpath + \pgfkeyssuccessfalse + \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW + \ifpgfkeyssuccess + \else + % step 1: search in /tikz with .try: + \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try={#1}}% + \fi + \ifpgfkeyssuccess + \else + % step 2: search in /pgf (without .try!): + \pgfqkeys{/pgf}{\pgfkeys@searchalso@name={#1}}% + \fi + \else + \def\pgfutilnext{\pgfkeysvalueof {/handlers/.unknown/.@cmd}#1\pgfeov}% + \pgfutilnext + \fi + } +} +\end{codeexample} + \end{enumerate} + + To also enable searching for styles (or other handled keys), + consider changing the configuration for handled keys to + |/hander config=full or existing| when you use |/.search also|, + that is, use +\begin{codeexample}[code only] +\pgfkeys{ + /main path/.search also={/secondary path}, + /handler config=full or existing} +\end{codeexample} +\end{handler} + + \subsubsection{Handlers for Testing Keys} \begin{handler}{{.try}|=|\meta{value}} @@ -1416,7 +1584,7 @@ Key 4:& \pgfkeys{/key4} \end{handler} \begin{handler}{{.lastretry}|=|\meta{value}} - This handler works like |/.retry|, only it will invoke the usual handlers for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handlers will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt. + This handler works like |/.retry|, only it will invoke the usual handlers for unknowns keys if |\||ifpgfkeyssuccess| is false. Thus, this handler will only try to set a key if ``the last attempt failed''. Furthermore, this here is the last such attempt. \end{handler} @@ -1468,13 +1636,13 @@ language currently set so that users get a localized error message. \end{key} \begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}} - This key is executed whenever a key setup using |/.is if| gets called + This key is executed whenever a key set up using |/.is if| gets called with a \meta{value} other than |true| or |false|. \end{key} \begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}} This key is executed whenever a choice is used as a \meta{value} for - a key setup using the |/.is choice| handler that is not defined. + a key set up using the |/.is choice| handler that is not defined. \end{key} \begin{key}{/errors/unknown key=\marg{offending key}\marg{value}} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeysfiltered.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeysfiltered.tex index b5c7e260432..be115418442 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeysfiltered.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfkeysfiltered.tex @@ -115,7 +115,7 @@ Remaining: `\remainingoptions'. \end{command} \begin{handler}{{.install key filter}|=|\meta{optional arguments}} - This handler install a key filter. A key filter is a command key which sets the \TeX-boolean |\ifpgfkeysfiltercontinue|, that means a key with existing `|/.@cmd|' suffix. A simple example is a key filter which returns always true: + This handler installs a key filter. A key filter is a command key which sets the \TeX-boolean |\ifpgfkeysfiltercontinue|, that means a key with existing `|/.@cmd|' suffix. A simple example is a key filter which returns always true: \begin{codeexample}[code only] \pgfkeys{/foo/bar/true key filter/.code={\pgfkeysfiltercontinuetrue}} \pgfkeys{/foo/bar/true key filter/.install key filter} @@ -126,7 +126,7 @@ Remaining: `\remainingoptions'. \pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} \end{codeexample} - If a key filter requires more than one argument, you need to provide the complete argument listing in braces like |{{first}{second}}|. + If a key filter requires more than one argument, you need to provide the complete argument list in braces like |{{first}{second}}|. You can also use |\pgfkeysinstallkeyfilter|\meta{full key}\meta{optional arguments}, it has the same effect. @@ -167,7 +167,7 @@ Remaining options: `\remainingoptions'. \subsubsection{Family Support} -\pgfname supports a family concept: every option can be associated with (at most) one family. Families form loose key groups which are independent of the key hierarchy. For example, |/my tree/key1| can belong to family |/tikz|. +\pgfname{} supports a family concept: every option can be associated with (at most) one family. Families form loose key groups which are independent of the key hierarchy. For example, |/my tree/key1| can belong to family |/tikz|. It is possible to `activate' or `deactivate' single families. Furthermore, it is possible to set only keys which belong to active families using appropriate key filter handlers. @@ -265,7 +265,7 @@ The family support is fast: if there are $N$ options in a key-value-list and the \subsubsection{Other Key Filters} There are some more key filters which have nothing to do with family handling. \begin{key}{/pgf/key filters/is descendant of=\marg{path}} - Install this key filter to process only options belonging to the key tree \marg{path}. It returns true for every key which has key path \marg{path}. It also returns true for any unknown key, that means unknown keys are processed using the standard unknown handlers of \pgfname. + Install this key filter to process only options belonging to the key tree \meta{path}. It returns true for every key whose key path is equal to \meta{path}. It also returns true for any unknown key, that means unknown keys are processed using the standard unknown handlers of \pgfname. \begin{codeexample}[] \pgfkeys{ /group 1/A/.code={(A:#1)}, @@ -326,7 +326,7 @@ There are some more key filters which have nothing to do with family handling. \subsubsection{Programmer Interface} \label{section-key-filter-api}% \begin{plainenvironment}{{pgfkeysinterruptkeyfilter}}% - Temporarily disables key filtering inside of the environment. If key filtering is not active, this has no effect at all. + Temporarily disables key filtering inside the environment. If key filtering is not active, this has no effect at all. Please note that no \TeX-group is introduced. \end{plainenvironment} @@ -351,11 +351,11 @@ switch the key filter. \end{command} \begin{command}{\pgfkeysdeactivatefamily\marg{family name}}% - Equivalent to |\pgfkeys{|\meta{family name}|/.dactivate family}|. + Equivalent to |\pgfkeys{|\meta{family name}|/.deactivate family}|. \end{command} \begin{command}{\pgfkeysactivatefamilies\marg{family list}\marg{deactivate macro name}}% - Activates each family in \meta{family list} and creates a macro \meta{deactivate macro name} which de-activates each family in \meta{family list}. + Activates each family in \meta{family list} and creates a macro \meta{deactivate macro name} which deactivates each family in \meta{family list}. \begin{codeexample}[code only] \pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename} \pgfkeysfiltered{foo,bar} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex index 3739db4d83b..7030e1f96ac 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-commands.tex @@ -12,6 +12,7 @@ \makeatletter + \subsection{Beginning and Ending a Stream of System Commands} A ``user'' of the \pgfname\ system layer (like the basic layer or a @@ -33,13 +34,13 @@ command. \begin{command}{\pgfsys@beginpicture} Called at the beginning of a |{pgfpicture}|. This command should - ``setup things.'' + ``set up things.'' Most drivers will need to implement this command. \end{command} \begin{command}{\pgfsys@endpicture} - Called at the end of a pgfpicture. + Called at the end of a |{pgfpicture}|. Most drivers will need to implement this command. \end{command} @@ -101,6 +102,19 @@ force. For this escaping, the following command is used: implementation, where a \TeX-translation makes no sense. \end{command} +\begin{command}{\pgfsys@pictureboxsynced\marg{box number}} + Basically, this should do the same as doing a (scoped) low level sync + followed by inserting the box \meta{box number} directly into the + output stream. However, the default implementation uses + |\pgfsys@hboxsynced| in conjunction with |\pgfsys@beginpicture| to + ensure that, if possible, hyperlinks survive in + \textsc{pdf}s. Drivers that are sensitive to picture-in-picture + scopes should replace this implementation by +\begin{codeexample}[code only] +\pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope +\end{codeexample} +\end{command} + \subsection{Path Construction System Commands} @@ -139,7 +153,7 @@ force. For this escaping, the following command is used: \begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}} Continue the current path to $(x_3,y_3)$ - with a Bézier curve that has the two control points $(x_1,y_1)$ and $(x_2,y_2)$. + with a B\'ezier curve that has the two control points $(x_1,y_1)$ and $(x_2,y_2)$. \example Draw a good approximation of a quarter circle: \begin{codeexample}[code only] @@ -429,14 +443,13 @@ force. For this escaping, the following command is used: \begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}} Sets the dashing patter. \meta{pattern} should be a list of \TeX\ - dimensions lengths separated by commas. \meta{phase} should be a + dimensions separated by commas. \meta{phase} should be a single dimension. \example |\pgfsys@setdash{3pt,3pt}{0pt}| The list of values in \meta{pattern} is used to determine the - lengths of the ``on'' phases of the dashing and of the ``off'' - phases. For example, if \meta{pattern} is |3bp,4bp|, then the dashing + lengths of the ``on'' and ``off'' phases of the dashing. For example, if \meta{pattern} is |3bp,4bp|, then the dashing pattern is ``3bp on followed by 4bp off, followed by 3bp on, followed by 4bp off, and so on.'' A pattern of |.5pt,4pt,3pt,1.5pt| means ``.5pt on, 4pt off, 3pt on, 1.5pt off, .5pt on, \dots'' If the @@ -508,20 +521,20 @@ whenever a stroking or a filling operation is done. \begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} Sets the color used for stroking and filling operations to the given - cymk tuple (numbers between 0 and 1). + cmyk tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. \end{command} \begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} - Sets the color used for stroking operations to the given cymk tuple + Sets the color used for stroking operations to the given cmyk tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. \end{command} \begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}} - Sets the color used for filling operations to the given cymk tuple + Sets the color used for filling operations to the given cmyk tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. @@ -529,20 +542,20 @@ whenever a stroking or a filling operation is done. \begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}} Sets the color used for stroking and filling operations to the given - cymk tuple (numbers between 0 and 1). + cmy tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. \end{command} \begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}} - Sets the color used for stroking operations to the given cymk tuple + Sets the color used for stroking operations to the given cmy tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. \end{command} \begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}} - Sets the color used for filling operations to the given cymk tuple + Sets the color used for filling operations to the given cmy tuple (numbers between 0 and 1). This command is protocolled, see Section~\ref{section-protocols}. @@ -718,7 +731,7 @@ The system layer provides some commands for image inclusion. If this macro and also the height macro are empty, the image should have its ``natural'' size. - If exactly only of them is specified, the undefined value the + If only one of them is specified, the undefined value the image is scaled so that the aspect ratio is kept. If both are set, the image is scaled in both directions @@ -743,7 +756,7 @@ The system layer provides some commands for image inclusion. interpolated in \pdf. \end{itemize} - The command should now setup the macro |\pgf@image| such that calling + The command should now set up the macro |\pgf@image| such that calling this macro will result in typesetting the image. Thus, |\pgf@image| is the ``return value'' of the command. @@ -784,7 +797,7 @@ The system layer provides some commands for image inclusion. \begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}} Declares a radial shading. Like the previous macros, this command - should setup the macro |\@pgfshading|\meta{name}|!|, which upon + should set up the macro |\@pgfshading|\meta{name}|!|, which upon invocation should insert a radial shading whose size is implicit in \meta{specification}. @@ -797,22 +810,22 @@ The system layer provides some commands for image inclusion. corner}\meta{upper right corner}\marg{type 4 function}} Declares a shading using a PostScript-like function that provides a color for each point. Like the previous macros, this command - should setup the macro |\@pgfshading|\meta{name}|!| so that it will + should set up the macro |\@pgfshading|\meta{name}|!| so that it will produce a box containing the desired shading. Parameter \meta{name} is the name of the shading. Parameter \meta{type 4 function} is a Postscript-like function (type 4 function of the PDF specification) - as described in Section 3.9.4 of the PDF Specification version 1.7. + as described in Section 3.9.4 of the PDF specification version 1.7. Parameters \meta{lower left corner} and \meta{upper right corner} are \pgfname\ points that specifies the lower left and upper right - corners of the shading. + corners of the shading, respectively. When \meta{type 4 function} is evaluated, the coordinate of the current point will be on the (virtual) PostScript stack in bp units. After the function has been evaluated, the stack should consist of three numbers (not integers! -- the Apple PDF renderer is broken in this - regard, so add cvr's at the end if needed) that represent the red, + regard, so add cvrs at the end if needed) that represent the red, green, and blue components of the color. A buggy function will result is \emph{totally unpredictable chaos} during @@ -831,8 +844,13 @@ The system layer provides some commands for image inclusion. Sets the opacity of filling operations. \end{command} +\begin{command}{\pgfsys@blend@mode\marg{value}} + Sets the blend mode, see Section 7.2.4 of the \textsc{pdf} + Specification, Version 1.7. +\end{command} + \begin{command}{\pgfsys@transparencygroupfrombox\marg{box}} - This takes a TeX box and converts it into a transparency + This takes a \TeX\ box and converts it into a transparency group. This means that any transparency settings apply to the box as a whole. For instance, if a box contains two overlapping black circles and you draw the box and, thus, the two circles normally @@ -841,9 +859,29 @@ The system layer provides some commands for image inclusion. group, the overlap will get the same color as the rest. \end{command} +A transparency group can be \emph{isolated} and/or a \emph{knockout} +group (see Sections 7.3.4 and 7.3.5 of the \textsc{pdf} +Specification Version 1.7). Which of these is the case is dictated +by the current settings of the following two ifs, which must be set +before the above command is called: + +{\let\ifpgfsys@transparency@group@isolated=\relax +\begin{command}{\ifpgfsys@transparency@group@isolated} + Determines whether a transparency group should be isolated. +\end{command} +} + +{\let\ifpgfsys@transparency@group@knockout=\relax +\begin{command}{\ifpgfsys@transparency@group@knockout} + Determines whether a transparency group is a knockout group or not. +\end{command} +} + + + \begin{command}{\pgfsys@fadingfrombox\marg{name}\marg{box}} Declares the fading \meta{name}. The \meta{box} is a \TeX-box. Its - contents luminosity determines the opacity of the resulting + content's luminosity determines the opacity of the resulting fading. This means that the lighter a pixel inside the box, the more opaque the fading will be at this position. \end{command} @@ -950,11 +988,47 @@ commands do not open a graphics scope and can be opened and closed \end{command} + +\subsection{Page Size Commands} + +The following commands can be used to set the page size of a document +in a ``portable'' way. Note, however, that many packages also (try to) +set the page size. + +These commands are typically not given inside a |{pgfpicture}|, but on +the outer level of compilation. + +\begin{command}{\pgfsys@papersize\marg{width}\marg{height}} + Inserts the necessary |\special|s for the current driver into the + output stream to ``locally'' change the page size. Whether such a + ``local'' change is possible depends strongly on the driver. For + instance, |dvips| will honor the first call to this command that is + part of the shipped-out document and will ignore all other uses. In + contrast, |pdftex| will use the current value of the paper size for + each page and, additionally, setting the papersize is local to the + current \TeX\ group. +\end{command} + +\begin{command}{\pgfsys@global@papersize\marg{width}\marg{height}} + Like the previous command, only for drivers where setting the paper + size parameters is a \TeX-group-local operation, |\global| is + prefixed to the setting of the page sizes. +\end{command} + +\begin{command}{\pgfsys@thepageheight} + This macro expands to the current page's height, provided \LaTeX\ is + used, otherwise a best guess is returned (currently just |\the\vsize|). +\end{command} + +\begin{command}{\pgfsys@thepagewidth} + As above. +\end{command} + \subsection{Position Tracking Commands} The following commands are used to determine the position of text on a page. This is a rather complicated process in general since at the -moment when the text is read by \TeX\ the final position cannot be +moment when the text is read by \TeX, the final position cannot be determined, yet. For example, the text might be put in a box which is later put in the headline or perhaps in the footline or perhaps even on a different page. @@ -963,7 +1037,7 @@ For these reasons, position tracking is typically a two-stage process. In a first stage you indicate that a certain position is of interest by \emph{marking} it. This will (depending on the details of the backend driver) cause page coordinates or this position to be -written to a |.aux| file when the page is shipped. Possibly, the +written to an |.aux| file when the page is shipped. Possibly, the position might also be determined at an even later stage. Then, on a second run of \TeX, the position is read from the |.aux| file and can be used. @@ -981,7 +1055,7 @@ The value of $x$ is \pgfsys@markposition{here}important. \begin{command}{\pgfsys@getposition\marg{name}\marg{macro}} This command retrieves a position that has been marked on an earlier run of \TeX\ on the current file. The \meta{macro} must be a macro - name such as |\mymarco|. It will redefined such that it is + name such as |\mymacro|. It will be redefined such that it is \begin{itemize} \item either just |\relax| or \item a |\pgfpoint...| command. @@ -1002,7 +1076,7 @@ The value of $x$ is \pgfsys@markposition{here}important. |pgfpageorigin|. By shifting all positions by the amount returned by this call you can position things absolutely on a page. - \example Referencing a point or the page: + \example Referencing a point of the page: \begin{codeexample}[code only] The value of $x$ is \pgfsys@markposition{here}important. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex index e2ec6f4e8ef..93951723868 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-overview.tex @@ -25,7 +25,7 @@ higher layers should never use |\special| commands directly or even check whether |\pdfoutput| is defined. Instead, all drawing requests should be ``channeled'' through the system commands. -The system layer is loaded and setup by the following package: +The system layer is loaded and set up by the following package: \begin{package}{pgfsys} This file provides ``default implementations'' of all system @@ -36,8 +36,8 @@ The system layer is loaded and setup by the following package: called \emph{driver files} in the following. When |pgfsys.sty| is loaded, it will try to determine which driver - is used by loading |pgf.cfg|. This file should setup the macro - |\pgfsysdriver| appropriately. The, |pgfsys.sty| will input the + is used by loading |pgf.cfg|. This file should set up the macro + |\pgfsysdriver| appropriately. The |pgfsys.sty| will input the appropriate |pgfsys-|\meta{drivername}|.sty|. \end{package} @@ -50,7 +50,7 @@ The system layer is loaded and setup by the following package: \end{command} \begin{filedescription}{pgf.cfg} - This file should setup the command |\pgfsysdriver| correctly. If + This file should set up the command |\pgfsysdriver| correctly. If |\pgfsysdriver| is already set to some value, the driver normally should not change it. Otherwise, it should make a ``good guess'' at which driver will be appropriate. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex index 8cf776ca3dd..a59b203b28d 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-paths.tex @@ -28,7 +28,7 @@ the sense that they are not implemented in driver files, but rather directly by the \pgfname-system layer. For this reason, the commands for creating soft paths do not start with |\pgfsys@|, but rather with |\pgfsyssoftpath@|. On the other hand, as a user you will never use -these commands directly, so they are described as part of the +these commands directly, they are described as part of the low-level interface. @@ -48,7 +48,7 @@ quite a lot happens behind the scenes: \pgfusepath{stroke} \end{codeexample} \item - The |\pgfpathxxxx| command do \emph{not} directly call ``hard'' + The |\pgfpathxxxx| commands do \emph{not} directly call ``hard'' commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto| invokes a special command called |\pgfsyssoftpath@moveto| and |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|. @@ -121,7 +121,7 @@ it. current soft path is \emph{not changed} by this command. Thus, in order to start a new soft path after the old one has been invoked and is no longer needed, you need to set the current soft path to be - empty. This may seems strange, but it is often useful to immediately + empty. This may seem strange, but it is often useful to immediately use the last soft path again. \end{command} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex index e46a31e0247..dcd21793278 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-pgfsys-protocol.tex @@ -40,7 +40,7 @@ require special |\special|'s and cannot be protocolled. \begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}} Adds the \meta{literal text} to the current protocol, after it has - been ``|\edef|ed.'' This command will always protocol. + been ``|\edef|ed.'' This command will always be protocolled. \end{command} \begin{command}{\pgfsysprotocol@literal\marg{literal text}} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex index c80846dcd85..bb201599575 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-actions.tex @@ -55,8 +55,8 @@ all have the same effect: \filldraw (0,0) circle (1cm); \end{codeexample} -In the following subsection the different actions are explained that -can be performed on a path. The following commands are abbreviations for +In the following subsection the different actions that +can be performed on a path are explained. The following commands are abbreviations for certain sets of actions, but for many useful combinations there are no abbreviations: @@ -174,7 +174,7 @@ You can draw a path using the following option: Although this option is normally used on paths to indicate that the path should be drawn, it also makes sense to use the option with a |{scope}| or |{tikzpicture}| environment. However, this will - \emph{not} cause all path to drawn. Instead, this just sets the + \emph{not} cause all paths to be drawn. Instead, this just sets the \meta{color} to be used for drawing paths inside the environment. \begin{codeexample}[] @@ -187,7 +187,7 @@ You can draw a path using the following option: The following subsections list the different options that influence how a path is drawn. All of these options only have an effect if the -|draw| options is given (directly or indirectly). +|draw| option is given (directly or indirectly). \subsubsection{Graphic Parameters: Line Width, Line Cap, and Line Join} @@ -255,6 +255,8 @@ styles. \end{stylekey} +\label{section-line-cap} + \begin{key}{/tikz/line cap=\meta{type} (initially butt)} Specifies how lines ``end.'' Permissible \meta{type} are |round|, |rect|, and |butt|. They have the following effects: @@ -281,7 +283,7 @@ styles. \draw[line join=round] (0,0) -- ++(.5,1) -- ++(.5,-1); \draw[line join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1); \draw[line join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1); - \useasboundingbox (0,1.5); % make bounding box bigger + \useasboundingbox (0,1.5); % enlarge bounding box \end{tikzpicture} \end{codeexample} @@ -389,52 +391,52 @@ dashing conveniently. \end{stylekey} -\begin{stylekey}{/tikz/dashdotted} +\begin{stylekey}{/tikz/dash dot} Shorthand for setting a dashed and dotted dash pattern. \begin{codeexample}[] -\tikz \draw[dashdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} -\begin{stylekey}{/tikz/densely dashdotted} +\begin{stylekey}{/tikz/densely dash dot} Shorthand for setting a densely dashed and dotted dash pattern. \begin{codeexample}[] -\tikz \draw[densely dashdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[densely dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} -\begin{stylekey}{/tikz/loosely dashdotted} +\begin{stylekey}{/tikz/loosely dash dot} Shorthand for setting a loosely dashed and dotted dash pattern. \begin{codeexample}[] -\tikz \draw[loosely dashdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[loosely dash dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} -\begin{stylekey}{/tikz/dashdotdotted} +\begin{stylekey}{/tikz/dash dot dot} Shorthand for setting a dashed and dotted dash pattern with more dots. \begin{codeexample}[] -\tikz \draw[dashdotdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} -\begin{stylekey}{/tikz/densely dashdotdotted} +\begin{stylekey}{/tikz/densely dash dot dot} Shorthand for setting a densely dashed and dotted dash pattern with more dots. \begin{codeexample}[] -\tikz \draw[densely dashdotdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[densely dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} -\begin{stylekey}{/tikz/loosely dashdotdotted} +\begin{stylekey}{/tikz/loosely dash dot dot} Shorthand for setting a loosely dashed and dotted dash pattern with more dots. \begin{codeexample}[] -\tikz \draw[loosely dashdotdotted] (0pt,0pt) -- (50pt,0pt); +\tikz \draw[loosely dash dot dot] (0pt,0pt) -- (50pt,0pt); \end{codeexample} \end{stylekey} @@ -442,130 +444,13 @@ dashing conveniently. \subsubsection{Graphic Parameters: Draw Opacity} When a line is drawn, it will normally ``obscure'' everything behind -it as if you has used perfectly opaque ink. It is also possible to ask +it as if you had used perfectly opaque ink. It is also possible to ask \tikzname\ to use an ink that is a little bit (or a big bit) transparent using the |draw opacity| option. This is explained in Section~\ref{section-tikz-transparency} on transparency in more detail. -\subsubsection{Graphic Parameters: Arrow Tips} - -When you draw a line, you can add arrow tips at the ends. It is -only possible to add one arrow tip at the start and one at the end. If -the path consists of several segments, only the last segment gets -arrow tips. The behavior for paths that are closed is not specified -and may change in the future. - -\begin{key}{/tikz/arrows=\meta{start arrow kind}|-|\meta{end arrow kind}} - This option sets the start and end arrow tips (an empty value as in |->| - indicates that no arrow tip should be drawn at the start).% - \indexoption{arrows} - - \emph{Note: Since the arrow option is so often used, you can leave - out the text |arrows=|.} What happens is that every option that - contains a |-| is interpreted as an arrow specification. - -\begin{codeexample}[] -\begin{tikzpicture} - \draw[->] (0,0) -- (1,0); - \draw[o-stealth] (0,0.3) -- (1,0.3); -\end{tikzpicture} -\end{codeexample} - - The permissible values are all predefined arrow tips, though - you can also define new arrow tip kinds as explained in - Section~\ref{section-arrows}. This is often necessary to obtain - ``double'' arrow tips and arrow tips that have a fixed size. You - need to load the |arrows| library if you need arrow tips other than - the default ones, see Section~\ref{section-library-arrows}. - - One arrow tip kind is special: |>| (and all arrow tip kinds containing the - arrow tip kind such as |<<| or \verb!>|!). This arrow tip type is not - fixed. Rather, you can redefine it using the |>=| option, see - below. - - \example You can also combine arrow tip types as in -\begin{codeexample}[] -\begin{tikzpicture}[thick] - \draw[to reversed-to] (0,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); - \draw[[-latex reversed] (1,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); - \draw[latex-)] (2,0) .. controls +(.5,0) and +(-.5,-.5) .. +(1.5,1); - \useasboundingbox (-.1,-.1) rectangle (3.1,1.1); % make bounding box bigger -\end{tikzpicture} -\end{codeexample} -\end{key} - -\begin{key}{/tikz/>=\meta{end arrow kind}} - This option can be used to redefine the ``standard'' arrow tip |>|. The - idea is that different people have different ideas what arrow tip kind - should normally be used. I prefer the arrow tip of \TeX's |\to| command - (which is used in things like $f\colon A \to B$). Other people will - prefer \LaTeX's standard arrow tip, which looks like this: \tikz - \draw[-latex] (0,0) -- (10pt,1ex);. Since the arrow tip kind |>| is - certainly the most ``natural'' one to use, it is kept free of any - predefined meaning. Instead, you can change it by saying |>=to| to - set the ``standard'' arrow tip kind to \TeX's arrow tip, whereas |>=latex| - will set it to \LaTeX's arrow tip and |>=stealth| will use a - \textsc{pstricks}-like arrow tip. - - Apart from redefining the arrow tip kind |>| (and |<| for the start), - this option also redefines the following arrow tip kinds: |>| and |<| as - the swapped version of \meta{end arrow kind}, |<<| and |>>| as - doubled versions, |>>| and |<<| as swapped doubled versions, %>> - and \verb!|<! and \verb!>|! as arrow tips ending with a vertical bar. - -\begin{codeexample}[] -\begin{tikzpicture}[scale=2] - \begin{scope}[>=latex] - \draw[->] (0pt,6ex) -- (1cm,6ex); - \draw[>->>] (0pt,5ex) -- (1cm,5ex); - \draw[|<->|] (0pt,4ex) -- (1cm,4ex); - \end{scope} - \begin{scope}[>=diamond] - \draw[->] (0pt,2ex) -- (1cm,2ex); - \draw[>->>] (0pt,1ex) -- (1cm,1ex); - \draw[|<->|] (0pt,0ex) -- (1cm,0ex); - \end{scope} -\end{tikzpicture} -\end{codeexample} -% << -\end{key} - -\begin{key}{/tikz/shorten >=\meta{dimension} (initially 0pt)} - This option will shorten the end of lines by the given - \meta{dimension}. If you specify an arrow tip, lines are already - shortened a bit such that the arrow tip touches the specified endpoint - and does not ``protrude over'' this point. Here is an example: - -\begin{codeexample}[] -\begin{tikzpicture}[line width=20pt] - \useasboundingbox (0,-1.5) rectangle (3.5,1.5); - \draw[red] (0,0) -- (3,0); - \draw[gray,->] (0,0) -- (3,0); -\end{tikzpicture} -\end{codeexample} - - The |shorten >| option allows you to shorten the end on the line - \emph{additionally} by the given distance. This option can also be - useful if you have not specified an arrow tip at all. - -\begin{codeexample}[] -\begin{tikzpicture}[line width=20pt] - \useasboundingbox (0,-1.5) rectangle (3.5,1.5); - \draw[red] (0,0) -- (3,0); - \draw[-to,shorten >=10pt,gray] (0,0) -- (3,0); -\end{tikzpicture} -\end{codeexample} -\end{key} - - -\begin{key}{/tikz/shorten <=\meta{dimension}} - Works like |shorten >|, but for the start. -\end{key} - - - \subsubsection{Graphic Parameters: Double Lines and Bordered Lines} \begin{key}{/tikz/double=\meta{core color} (default white)} @@ -612,7 +497,7 @@ and may change in the future. \begin{key}{/tikz/double distance between line centers=\meta{dimension}} This option works like |double distance|, only the distance is not - the distance between (inner) borders of the two main lines, ut + the distance between (inner) borders of the two main lines, but between their centers. Thus, the thickness the \emph{first} time the path is drawn is the normal line width plus the given \meta{dimension}, while the line width of the @@ -653,7 +538,35 @@ and may change in the future. +\subsection{Adding Arrow Tips to a Path} +\label{section-arrow-tip-action} + +In different situations, \tikzname\ will add arrow tips to the end of +a path. For this to happen, a number of different things need to be +specified: + +\begin{enumerate} +\item You must have used the |arrows| key, explained in detail in + Section~\ref{section-tikz-arrows}, to setup which kinds of arrow + tips you would like. +\item The path may not be closed (like a circle or a rectangle) and, + if it consists of several subpath, further restrictions apply as + explained in Section~\ref{section-tikz-arrows}. +\item The |tips| key must be set to an appropriate value, see + Section~\ref{section-tikz-arrows} once more. +\end{enumerate} +For the current section on paths, it is only important that when you +add the |tips| option to a path that is not drawn, arrow tips will +still be added at the beginning and at the end of the current +path. This is true even when ``only'' arrow tips get drawn for a path +without drawing the path itself. Here is an example: +\begin{codeexample}[width=2cm] +\tikz \path[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0); +\end{codeexample} +\begin{codeexample}[width=2cm] +\tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0); +\end{codeexample} \subsection{Filling a Path} @@ -692,7 +605,7 @@ To fill a path, use the following option: area because of the thickness of the ``pen.'' \begin{codeexample}[] -\begin{tikzpicture}[fill=examplefill,line width=5pt] +\begin{tikzpicture}[fill=yellow!80!black,line width=5pt] \filldraw (0,0) -- (1,1) -- (2,1); \filldraw (4,0) circle (.5cm) (4.5,0) circle (.5cm); \filldraw[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm); @@ -722,7 +635,7 @@ is used the current \emph{pattern color} is used as its color. Patterns are not overly flexible. In particular, it is not possible to change the size or orientation of a pattern without declaring a new -pattern. For complicated case, it may be easier to use two nested +pattern. For complicated cases, it may be easier to use two nested |\foreach| statements to simulate a pattern, but patterns are rendered \emph{much} more quickly than simulated ones. @@ -788,7 +701,7 @@ should be determined: \begin{codeexample}[] \begin{tikzpicture} - \filldraw[fill=examplefill] + \filldraw[fill=yellow!80!black] % Clockwise rectangle (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle % Counter-clockwise rectangle @@ -800,7 +713,7 @@ should be determined: \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$}; \begin{scope}[yshift=-3cm] - \filldraw[fill=examplefill] + \filldraw[fill=yellow!80!black] % Clockwise rectangle (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle % Clockwise rectangle @@ -829,7 +742,7 @@ should be determined: \begin{codeexample}[] \begin{tikzpicture} - \filldraw[fill=examplefill,even odd rule] + \filldraw[fill=yellow!80!black,even odd rule] (0,0) rectangle (1,1) (0.5,0.5) circle (0.4cm); \draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$}; \end{tikzpicture} @@ -841,8 +754,7 @@ should be determined: \subsubsection{Graphic Parameters: Fill Opacity} \label{section-fill-opacity} -Analogously to the |draw opacity|, you can also set the filling -opacity. Please see Section~\ref{section-tikz-transparency} for more +Analogously to the |draw opacity|, you can also set the fill opacity. Please see Section~\ref{section-tikz-transparency} for more details. @@ -866,13 +778,10 @@ this process much easier: and, possibly, the path is stroked, provided the |draw| option has been given. - As with other keys like |fill| or |draw| this option needs to be - given on a path, setting the |path picture| outside a path has not - effect (the path picture is cleared at the beginning of each path). + As with other keys like |fill| or |draw| this option needs to be given on a path, setting the |path picture| outside a path has no effect (the path picture is cleared at the beginning of each path). The \meta{code} can be any normal \tikzname\ code like |\draw ...| - or |\node ...|. As always, when you include an external graphic you - need to put it inside a |\node|. + or |\node ...|. As always, when you include an external graphic, you need to put it inside a |\node|. Note that no special actions are taken to transform the origin in any way. This means that the coordinate |(0,0)| is still where is @@ -969,7 +878,7 @@ is drawn, scaled and shifted such that all parts of the path are filled. The default shading is a smooth transition from gray -to white and from above to bottom. However, other shadings are also +to white and from top to bottom. However, other shadings are also possible, for example a shading that will sweep a color from the center to the corners outward. To choose the shading, you can use the |shading=| option, which will also automatically invoke the |shade| @@ -991,7 +900,7 @@ needed, which are explained below. To change the color of a shading, special options are needed like |left color|, which sets the color of an axis shading from left to - right. These options implicitly also select the right shading type, + right. These options implicitly also select the correct shading type, see the following example \begin{codeexample}[] \tikz \shadedraw [left color=red,right color=blue] @@ -1066,7 +975,7 @@ right of picture. \end{codeexample} Note: If this option is used on a path inside a \TeX\ group (scope), - the effect ``lasts'' only till the end of the scope. Again, this + the effect ``lasts'' only until the end of the scope. Again, this behavior is the same as for clipping. @@ -1260,7 +1169,7 @@ with a color, then repaint the path with a pattern and then repaint it with yet another pattern. In such cases you can use the following two options: -\begin{key}{/tikz/preactions=\meta{options}} +\begin{key}{/tikz/preaction=\meta{options}} This option can be given to a |\path| command (or to derived commands like |\draw| which internally call |\path|). Similarly to options like |draw|, this option only has an effect when given to a @@ -1415,7 +1324,7 @@ options: Before a path is used, it is possible to first ``decorate'' and/or ``morph'' it. Morphing means that the path is replaced by another path -that slightly varied. Such morphings are a special case +that is slightly varied. Such morphings are a special case of the more general ``decorations'' described in detail in Section~\ref{section-tikz-decorations}. For instance, in the following example the path is drawn twice: Once normally and then in a morphed diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-arrows.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-arrows.tex new file mode 100644 index 00000000000..6e6f87da9c8 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-arrows.tex @@ -0,0 +1,2585 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Arrows} +\label{section-tikz-arrows} + + +\subsection{Overview} + +\tikzname\ allows you to add (multiple) arrow tips to the end of +lines as in \tikz [baseline] \draw [->>]%<< +(0,.5ex) -- (3ex,.5ex); or in \tikz [baseline] \draw [-{Latex[]}] +(0,.5ex) -- (3ex,.5ex);. It is possible to change which arrow tips are +used ``on-the-fly,'' you can have several arrow tips in a row, and you +can change the appearance of each of them individually using a special +syntax. The following example is a perhaps slightly ``excessive'' +demonstration of what you can do (you need to load the |arrows.meta| +library for it to work): +\begin{codeexample}[] +\tikz { + \node [circle,draw] (A) {A}; + \node [circle,draw] (B) [right=of A] {B}; + + \draw [draw = blue, thick, + arrows={ + Computer Modern Rightarrow [sep] + - Latex[blue!50,length=8pt,bend,line width=0pt] + Stealth[length=8pt,open,bend,sep]}] + (A) edge [bend left=45] (B) + (B) edge [in=-110, out=-70,looseness=8] (B); +} +\end{codeexample} + +There are a number of predefined generic arrow tip kinds whose +appearance you can modify in many ways using various options. It is +also possible to define completely new arrow tip kinds, see +Section~\ref{section-arrows}, but doing this is somewhat harder than +configuring an existing kind (it is like the difference between using +a font at different sizes or faces like italics, compared to +designing a new font yourself). + +In the present section, we go over the various ways in which you can +configure which particular arrow tips are \emph{used.} The glorious +details of how new arrow tips can be defined are explained in +Section~\ref{section-arrows}. + +At the end of the present section, Section~\ref{section-arrows-meta}, +you will find a description of the different predefined arrow tips +from the |arrows.meta| library. + +\emph{Remark:} Almost all of the features described in the following +were introduced in version 3.0 of \tikzname. For compatibility +reasons, the old arrow tips are still available. To differentiate +between the old and new arrow tips, the following rule is used: The +new, more powerful arrow tips start with an uppercase letter as in +|Latex|, compared to the old arrow tip |latex|. + +\emph{Remark:} The libraries |arrows| and |arrows.spaced| are +deprecated. Use |arrows.meta| instead/additionally, which allows you +to do all that the old libraries offered, plus much more. However, the +old libraries still work and you can even mix old and new arrow tips +(only, the old arrow tips cannot be configured in the ways described +in the rest of this section; saying |scale=2| for a |latex| arrow has +no effect for instance, while for |Latex| arrows it doubles their size +as one would expect.) + + +\subsection{Where and When Arrow Tips Are Placed} +\label{section-arrow-tips-where} + +In order to add arrow tips to the lines you draw, the following +conditions must be met: + +\begin{enumerate} +\item You have specified that arrow tips should be added to + lines, using the |arrows| key or its short form. +\item You set the |tips| key to some value that causes tips to be + drawn (to be explained later). +\item You do not use the |clip| key (directly or indirectly) with the + current path. +\item The path actually has two ``end points'' (it is not + ``closed''). +\end{enumerate} + +Let us start with an introduction to the basics of the |arrows| key: + +\begin{key}{/tikz/arrows=\meta{start arrow specification}|-|\meta{end + arrow specification}} + This option sets the arrow tip(s) to be used at the start and end of + lines. An empty value as in |->| for the start indicates that no + arrow tip should be drawn at the start.% + \indexoption{arrows} + + \emph{Note: Since the arrow option is so often used, you can leave + out the text |arrows=|.} What happens is that every (otherwise + unknown) option that contains a |-| is interpreted as an arrow specification. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[->] (0,0) -- (1,0); + \draw[>-Stealth] (0,0.3) -- (1,0.3); +\end{tikzpicture} +\end{codeexample} + + In the above example, the first start specification is empty and the + second is |>|. The end specifications are |>| for the first line and + |Stealth| for the second line. Note that it makes a difference + whether |>| is used in a start specification or in an end + specification: In an end specification it creates, as one would + expect, a pointed tip at the end of the line. In the start + specification, however, it creates a ``reversed'' version if this + arrow -- which happens to be what one would expect here. + + The above specifications are very simple and only select a single + arrow tip without any special configuration options, resulting in + the ``natural'' versions of these arrow tips. It is also possible to + ``configure'' arrow tips in many different ways, as explained in + detail in Section~\ref{section-arrow-config} below by adding options + in square brackets following the arrow tip kind: + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[-{Stealth[red]}] (0,0) -- (1,0); +\end{tikzpicture} +\end{codeexample} + + Note that in the example I had to surround the end specification by + braces. This is necessary so that \tikzname\ does not mistake the + closing square bracket of the |Stealth| arrow tip's options for the + end of the options of the |\draw| command. In general, you often + need to add braces when specifying arrow tips except for simple case + like |->| or |<<->|, which are pretty frequent, though. When in + doubt, say |arrows={|\meta{start spec}|-|\meta{end spec}|}|, that + will always work. + + It is also possible to specify multiple (different) arrow tips in a + row inside a specification, see Section~\ref{section-arrow-spec} + below for details. +\end{key} + +As was pointed out earlier, to add arrow tips to a path, the path must +have ``end points'' and not be ``closed'' -- otherwise adding arrow +tips makes little sense, after all. However, a path can actually +consist of several subpath, which may be open or not and may even +consist of only a single point (a single move-to). In this case, it is +not immediately obvious, where arrow heads should be placed. The +actual rules that \tikzname\ uses are goverened by the setting of the +key |tips|: + +\begin{key}{/pgf/tips=\meta{value} (default true, initially on draw)} + \keyalias{tikz} + + This key governs in what situations arrow tips are added to a + path. The following \meta{values} are permissible: + \begin{itemize} + \item |true| (the value used when no \meta{value} is specified) + \item |proper| + \item |on draw| (the initial value, if the key has not yet been used + at all) + \item |on proper draw| + \item |never| or |false| (same effect) + \end{itemize} + + Firstly, there are a whole bunch of situations where the setting of + these (or other) options causes no arrow tips to be shown: + \begin{itemize} + \item If no arrow tips have been specified (for instance, by having + said |arrows=-|), no arrow tips are drawn. + \item If the |clip| option is set, no arrow tips are drawn. + \item If |tips| has been set to |never| or |false|, no arrow tips are drawn. + \item If |tips| has been set to |on draw| or |on proper draw|, but + the |draw| option is not set, no arrow tips are drawn. + \item If the path is empty (as in |\path ;|), no arrow tips are drawn. + \item If at least one of the subpaths of a path is closed (|cycle| is + used somewhere or something like |circle| or |rectangle|), arrow + tips are never drawn anywhere -- even if there are open subpaths. + \end{itemize} + + Now, if we pass all of the above tests, we must have a closer look + at the path. All its subpaths must now be open and there must be at + least one subpath. We conside the last one. Arrow tips will only be + added to this last subpath. + + \begin{enumerate} + \item If this last subpath not degenerate (all coordinates on the + subpath are the same as in a single ``move-to'' |\path (0,0);| or + in a ``move-to'' followed by a ``line-to'' to the same position as + in |\path (1,2) -- (1,2)|), arrow tips are added to this last + subpath now. + \item If the last subpath is degenerate, we add arrow tips pointing + upward at the single coordinate mentioned in the path, but only + for |tips| begin set to |true| or to |on draw| -- and not for + |proper| nor for |on proper draw|. In other words, ``proper'' + suppresses arrow tips on degenerate paths. + \end{enumerate} + +\begin{codeexample}[] +% No path, no arrow tips: +\tikz [<->] \draw; +\end{codeexample} +\begin{codeexample}[] +% Degenerate path, draw arrow tips (but no path, it is degenerate...) +\tikz [<->] \draw (0,0); +\end{codeexample} +\begin{codeexample}[] +% Degenerate path, tips=proper suppresses arrows +\tikz [<->] \draw [tips=proper] (0,0); +\end{codeexample} +\begin{codeexample}[] +% Normal case: +\tikz [<->] \draw (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +% Two subpaths, only second gets tips +\tikz [<->] \draw (0,0) -- (1,0) (2,0) -- (3,0); +\end{codeexample} +\begin{codeexample}[] +% Two subpaths, second degenerate, but still gets tips +\tikz [<->] \draw (0,0) -- (1,0) (2,0); +\end{codeexample} +\begin{codeexample}[] +% Two subpaths, second degenerate, proper suppresses them +\tikz [<->] \draw [tips=on proper draw] (0,0) -- (1,0) (2,0); +\end{codeexample} +\begin{codeexample}[] +% Two subpaths, but one is closed: No tips, even though last subpath is open +\tikz [<->] \draw (0,0) circle[radius=2pt] (2,0) -- (3,0); +\end{codeexample} +\end{key} + +One common pitfall when arrow tips are added to a path should be +addressed right here at the beginning: When \tikzname\ positions an +arrow tip at the start, for all its computations it only takes into +account the first segment of the subpath to which the arrow tip is +added. This ``first segment'' is the first line-to or curve-to operation (or arc +or parabola or a similar operation) of the path; but note that +decorations like |snake| will add many small line segments to +paths. The important point +is that if this first segment is very small, namely smaller that the +arrow tip itself, strange things may result. As will be explained in +Section~\ref{section-arrow-flex}, \tikzname\ will modify the path by +shortening the first segment and shortening a segment below its length +may result in strange effects. Similarly, for tips at the end of a +subpath, only the last segment is considered. + +The bottom line is that wherever an arrow tip is added to a path, the +line segment where it is added should be ``long enough.'' + + + + +\subsection{Arrow Keys: Configuring the Appearance of a Single Arrow Tip} +\label{section-arrow-config} + +For standard arrow tip kinds, like |Stealth| or |Latex| or |Bar|, +you can easily change their size, aspect ratio, color, and other +parameters. This is similar to selecting a font face from a font +family: \emph{``This text''} is not just typeset in the font +``Computer Modern,'' but rather in ``Computer Modern, italic face, +11pt size, medium weight, black color, no underline, \dots'' +Similarly, an arrow tip is not just a ``Stealth'' arrow tip, but +rather a ``Stealth arrow tip at its natural size, flexing, but not +bending along the path, miter line caps, draw and fill colors +identical to the path draw color, \dots'' + +Just as most programs make it easy to ``configure'' which font should +be used at a certain point in a text, \tikzname\ tries to make it easy +to specify which configuration of an arrow tip should be used. You use +\emph{arrow keys}, where a certain parameter like the |length| of an +arrow is set to a given value using the standard key--value +syntax. You can provide several arrow keys following an arrow tip kind +in an arrow tip specification as in +|Stealth[length=4pt,width=2pt]|. + +While selecting a font may be easy, \emph{designing} a new font is a +highly creative and difficult process and more often than not, not all +faces of a font are available on any given system. The difficulties +involved in designing a new arrow tip are somewhat similar to designing a new +letter for a font and, thus, it may also happen that not all +configuration options are actually implemented for a given arrow +tip. Naturally, for the standard arrow tips, all configuration options +are available -- but for special-purpose arrow tips it may well happen +that an arrow tip kind simply ``ignores'' some of the configurations +given by you. + +Some of the keys explained in the following are defined in the library +|arrows.meta|, others are always available. This has to do with the +question of whether the arrow key needs to be supported directly in the +\pgfname\ core or not. In general, the following explanations assume +that |arrows.meta| has been loaded. + + +\subsubsection{Size} + +The most important configuration parameter of an arrow tip is +undoubtedly its size. The following two keys are the main keys that +are important in this context: + +\begin{key}{/pgf/arrow keys/length=\meta{dimension}| |\opt{\meta{line width factor}}% + | |\opt{\meta{outer factor}}} + \label{length-arrow-key}% + This parameter is usually the most important parameter that governs + the size of an arrow tip: The \meta{dimension} that you provide + dictates the distance from the ``very tip'' of the arrow to its + ``back end'' along the line: +\begin{codeexample}[] +\tikz{ + \draw [-{Stealth[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); +} +\end{codeexample} +\begin{codeexample}[] +\tikz{ + \draw [-{Latex[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); +} +\end{codeexample} +\begin{codeexample}[] +\tikz{ + \draw [-{Classical TikZ Rightarrow[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.6) -- node[above=1mm] {5mm} (2,.6); +} +\end{codeexample} + + \medskip + \noindent \textbf{The Line Width Factors.} + Following the \meta{dimension}, you may put a space followed by a + \meta{line width factor}, which must be a plain number (no |pt| or + |cm| following). When you provide such a number, the size of the + arrow tip is not just \meta{dimension}, but rather $\meta{dimension} + + \meta{line width factor}\cdot w$ where + $w$ is the width of the to-be-drawn path. This + makes it easy to vary the size of an arrow tip in accordance with + the line width -- usually a very good idea since thicker lines will + need thicker arrow tips. + + As an example, when you write |length=0pt 5|, the length of the + arrow will be exactly five times the current line width. As another + example, the default length of a |Latex| arrow is + |length=3pt 4.5 0.8|. Let us ignore the 0.8 for a moment; the + |4pt 4.5| then means that for the standard line width of + |0.4pt|, the length of a |Latex| arrow will be exactly 4.8pt (3pt + plus 4.5 times |0.4pt|). + + Following the line width factor, you can additionally provide an + \meta{outer factor}, again preceded by a space (the |0.8| in the + above example). This factor is + taken into consideration only when the |double| option is used, that + is, when a so-called ``inner line width''. For a double line, we can + identify three different ``line widths'', namely the inner line + width $w_i$, the line width $w_o$ of the two outer lines, and the + ``total line width'' $w_t = w_i + 2w_o$. In the below examples, we + have $w_i = 3\mathrm{pt}$, $w_o=1\mathrm{pt}$, and $w_t = + 5\mathrm{pt}$. It is not immediately clear + which of these line widths should be considered as $w$ in the above + formula $\meta{dimension} + \meta{line width factor}\cdot w$ for the + computation of the length. One can argue both for $w_t$ and also for + $w_o$. Because of this, you use the \meta{outer factor} to + decide on one of them or even + mix them: \tikzname\ sets $w = \meta{outer factor} w_o + + (1-\meta{outer factor})w_t$. Thus, when the outer factor is $0$, as + in the first of the following examples and as is the default when it + is not specified, the computed $w$ will be the total + line width $w_t = 5\mathrm{pt}$. Since + $w=5\mathrm{pt}$, we get a total length of $15pt$ in the first + example (because of the factor |3|). In contrast, in the last + example, the outer factor is 1 and, thus, $w = w_o = \mathrm{1pt}$ and the + resulting length is 3pt. Finally, for the middle case, the ``middle'' between 5pt and + 1pt is 3pt, so the length is 9pt. +\begin{codeexample}[] +\tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 0]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 .5]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 1]} ] (0,0) -- (1,0); +\end{codeexample} + + \medskip + \noindent \textbf{The Exact Length.} + For an arrow tip kind that is just an outline that is filled with a + color, the specified length should \emph{exactly} equal the distance + from the tip to the back end. However, when the arrow tip is drawn + by stroking a line, it is no longer obvious whether the |length| + should refer to the extend of the stroked lines' path or of the + resulting pixels (which will be wider because of the thickness of + the stroking pen). The rules are as follows: + \begin{enumerate} + \item If the arrow tip consists of a closed path (like |Stealth| or + |Latex|), imagine the arrow tip drawn from left to right using a + miter line cap. Then the |length| should be the horizontal + distance from the first drawn ``pixel'' to the last drawn + ``pixel''. Thus, the thickness of the stroked line and also the + miter ends should be taken into account: +\begin{codeexample}[] +\tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); +} +\end{codeexample} + \item If, in the above case, the arrow is drawn using a round line + join (see Section~\ref{section-arrow-key-caps} for details on how + to select this), the size of the arrow should still be the same as + in the first case (that is, as if a miter join were used). This + creates some ``visual consistency'' if the two modes are mixed or + if you later one change the mode. +\begin{codeexample}[] +\tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open, round]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); +} +\end{codeexample} + As the above example shows, however, a rounded arrow will still + exactly ``tip'' the point where the line should end (the point + |(2,0)| in the above case). It is only the scaling of the arrow + that is not affected. + \end{enumerate} +\end{key} + +\begin{key}{/pgf/arrow keys/width=\meta{dimension}| |\opt{\meta{line width factor}}% + | |\opt{\meta{outer factor}}} + This key works line the |length| key, only it specifies the + ``width'' of the arrow tip; so if width and length are identical, the + arrow will just touch the borders of a square. (An exception to this + rule are ``halved'' arrow tips, see + Section~\ref{section-arrow-key-harpoon}.) The meaning of the two + optional factor numbers following the \meta{dimension} is the same + as for the |length| key. +\begin{codeexample}[] +\tikz \draw [arrows = {-Latex[width=10pt, length=10pt]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [arrows = {-Latex[width=0pt 10, length=10pt]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + +\begin{key}{/pgf/arrow keys/width'=\meta{dimension}| |\opt{\meta{length + factor}| |\opt{\meta{line width factor}}}} + The key (note the prime) has a similar effect as the |width| + key. The difference is that the second, still optional paraemter + \meta{length factor} specifies the width of the key not as a + multiple of the line width, but as a multiple of the arrow length. + + The idea is that if you write, say, |width'=0pt 0.5|, the width of + the arrow will be half its length. Indeed, for standard arrow tips + like |Stealth| the default width is specified in this way so that if + you change the length of an arrow tip, you also change the width in + such a way that the aspect ratio of the arrow tip is kept. The other + way round, if you modify the factor in |width'| without changing the + length, you change the aspect ratio of the arrow tip. + + Note that later changes of the length are taken into account for the + computation. For instance, if you write +\begin{codeexample}[code only] +length = 10pt, width'=5pt 2, length=7pt +\end{codeexample} + the resulting width will be $19\mathrm{pt} = 5\mathrm{pt} + 2\cdot + 7\mathrm{pt}$. + +\begin{codeexample}[] +\tikz \draw [arrows = {-Latex[width'=0pt .5, length=10pt]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [arrows = {-Latex[width'=0pt .5, length=15pt]}] (0,0) -- (1,0); +\end{codeexample} + The third, also optional, parameter allows you to add a multiple of + the line width to the value computed in terms of the length. +\end{key} + + +\begin{key}{/pgf/arrow keys/inset=\meta{dimension}| |\opt{\meta{line width factor}}% + | |\opt{\meta{outer factor}}} + The key is relevant only for some arrow tips such as the |Stealth| + arrow tip. It specifies a distance by which something inside the + arrow tip is set inwards; for the |Stealth| arrow tip it is the + distance by which the back angle is moved inwards. + + The computation of the distance works in the same way as for + |length| and |width|: To the \meta{dimension} we add \meta{line + width factor} times that line width, where the line width is + computed based on the \meta{outer factor} as described for the + |length| key. +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[length=10pt, inset=5pt]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[length=10pt, inset=2pt]}] (0,0) -- (1,0); +\end{codeexample} + + For most arrows for which there is no ``natural inset'' like, say, + |Latex|, this key has no effect. +\end{key} + + +\begin{key}{/pgf/arrow keys/inset'=\meta{dimension}| |\opt{\meta{length factor}}| |\opt{\meta{line width factor}}} + This key works like |inset|, only like |width'| the second parameter + is a factor of the arrow length rather than of the line width. For + instance, the |Stealth| arrow sets |inset'| to |0pt 0.325| to ensure + that the inset is always at $13/40$th of the arrow length if nothing + else is specified. +\end{key} + + + +\begin{key}{/pgf/arrow keys/angle=\meta{angle}|:|\meta{dimension}% + | |\opt{\meta{line width factor}}% + | |\opt{\meta{outer factor}}} + This key sets the |length| and the |width| of an arrow tip at the + same time. The lenght will be the cosine of \meta{angle}, while the + width will be twice the sine of half the \meta{angle} (this slightly + awkward rule ensures that a |Stealth| arrow will have an opening + angle of \meta{angle} at its tip if this option is used). As for the + |length| key, if the optional factors are given, they add a certain + multiple of the line width to the \meta{dimension} before the sine + and cosines are computed. +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[inset=0pt, angle=90:10pt]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[inset=0pt, angle=30:10pt]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/arrow keys/angle'=\meta{angle}} + Sets the width of the arrow to twice the tangent of $\meta{angle}/2$ + times the arrow length. This results in an arrow tip with an opening + angle of \meta{angle} at its tip and with the specified |length| + unchanged. +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=90]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=30]}] + (0,0) -- (1,0); +\end{codeexample} +\end{key} + + +\subsubsection{Scaling} + +In the previous section we saw that there are many options for getting +``fine control'' overt the length and width of arrow tips. However, in +some cases, you do not really care whether the arrow tip is 4pt long +or 4.2pt long, you ``just want it to be a little bit larger than +usual.'' In such cases, the following keys are useful: + +\begin{key}{/pgf/arrows keys/scale=\meta{factor} (initially 1)} + After all the other options listed in the previous (and also the + following sections) have been processed, \tikzname\ applies a + \emph{scaling} to the computed length, inset, and width of the arrow + tip (and, possibly, to other size parameters defined by + special-purpose arrow tip kinds). Everything is simply scaled by the + given \meta{factor}. +\begin{codeexample}[] +\tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale=2]}] (0,0) -- (1,0); +} +\end{codeexample} + Note that scaling has \emph{no} effect on the line width (as usual) + and also not on the arrow padding (the |sep|). +\end{key} + +You can get even more fine-grained control over scaling using the +following keys (the |scale| key is just a shorthand for setting both +of the following keys simultaneously): + +\begin{key}{/pgf/arrows keys/scale length=\meta{factor} (initially 1)} + This factor works like |scale|, only it is applied only to + dimensions ``along the axis of the arrow,'' that is, to the length + and to the inset, but not to the width. +\begin{codeexample}[] +\tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale length=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale length=2]}] (0,0) -- (1,0); +} +\end{codeexample} +\end{key} + +\begin{key}{/pgf/arrows keys/scale width=\meta{factor} (initially 1)} + Like |scale length|, but for dimensions related to the width. +\begin{codeexample}[] +\tikz { + \draw [arrows = {-Stealth[]}] (0,1) -- (1,1); + \draw [arrows = {-Stealth[scale width=1.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Stealth[scale width=2]}] (0,0) -- (1,0); +} +\end{codeexample} +\end{key} + + +\subsubsection{Arc Angles} + +A few arrow tips consist mainly of arcs, whose length can be +specified. For these arrow tips, you use the following key: + +\begin{key}{/pgf/arrow keys/arc=\meta{degrees} (initially 180)} + Sets the angle of arcs in arrows to \meta{degrees}. Note that this key + is quite different from the |angle| key, which is ``just a + fancy way of setting the length and width.'' In contrast, the |arc| + key is used to set the degrees of arcs that are part of an arrow + tip: +\begin{codeexample}[] +\tikz [ultra thick] { + \draw [arrows = {-Hooks[]}] (0,1) -- (1,1); + \draw [arrows = {-Hooks[arc=90]}] (0,0.5) -- (1,0.5); + \draw [arrows = {-Hooks[arc=270]}] (0,0) -- (1,0); +} +\end{codeexample} +\end{key} + + +\subsubsection{Slanting} + +You can ``slant'' arrow tips using the following key: + +\begin{key}{/pgf/arrow keys/slant=\meta{factor} (initially 0)} + Slanting is used to create an ``italics'' effect for arrow tips: All + arrow tips get ``slanted'' a little bit relative to the axis of the + arrow: +\begin{codeexample}[] +\tikz { + \draw [arrows = {->[]}] (0,1) -- (1,1); + \draw [arrows = {->[slant=.5]}] (0,0.5) -- (1,0.5); + \draw [arrows = {->[slant=1]}] (0,0) -- (1,0); +} +\end{codeexample} + There is one thing to note about slanting: Slanting is done using a + so-called ``canvas transformation'' and has no effect on + positioning of the arrow tip. In particular, if an arrow tip gets + slanted so strongly that it starts to protrude over the arrow tip + end, this does not change the positioning of the arrow tip. + + Here is another example where slanting is used to match italic text: +\begin{codeexample}[] +\tikz [>={[slant=.3] To[] To[]}] + \graph [math nodes] { A -> B <-> C }; +\end{codeexample} +\end{key} + + + +\subsubsection{Reversing, Halving, Swapping} +\label{section-arrow-key-harpoon} + +\begin{key}{/pgf/arrow keys/reverse} + Adding this key to an arrow tip will ``reverse its direction'' so + that is points in the opposite direction (but is still at that end of the + line where the non-reversed arrow tip would have been drawn; so only + the tip is reversed). For most arrow tips, this just results in an + internal flip of a coordinate system, but some arrow tips actually + use a slightly different version of the tip for reversed arrow tips + (namely when the joining of the tip with the line would look + strange). All of this happens automatically, so you do not need to + worry about this. + + If you apply this key twice, the effect cancels, which is useful for + the definition of shorthands (which will be discussed later). +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[reversed]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[reversed, reversed]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + +\begin{key}{/pgf/arrow keys/harpoon} + The key requests that only the ``left half'' of the arrow tip should + drawn: +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {->[harpoon]}] (0,0) -- (1,0); +\end{codeexample} + Unlike the |reverse| key, which all arrows tip kinds support at + least in a basic way, designers of arrow tips really need to take + this key into account in their arrow tip code and often a lot of + special attention needs to do be paid to this key in the + implementation. For this reason, only some arrow tips will support + it. +\end{key} + +\begin{key}{/pgf/arrow keys/swap} + This key flips that arrow tip along the axis of the line. It makes + sense only for asymmetric arrow tips like the harpoons created using + the |harpoon| option. +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon,swap]}] (0,0) -- (1,0); +\end{codeexample} + Swapping is always possible, no special code is needed on behalf of + an arrow tip implementer. +\end{key} + +\begin{key}{/pgf/arrow keys/left} + A shorthand for |harpoon|. +\end{key} + +\begin{key}{/pgf/arrow keys/right} + A shorthand for |harpoon, swap|. +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[left]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [arrows = {-Stealth[right]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + + +\subsubsection{Coloring} + +Arrow tips are drawn using the same basic mechanisms as normal paths, +so arrow tips can be stroked (drawn) and/or filled. However, we +usually want the color of arrow tips to be identical to the color used +to draw the path, even if a different color is used for filling the +path. On the other hand, we may also sometimes wish to use a special +color for the arrow tips that is different from both the line and fill +colors of the main path. + +The following options allow you to configure how arrow tips are +colored: + +\begin{key}{/pgf/arrow keys/color=\meta{color or empty} (initially + \normalfont empty)} + Normally, an arrow tip gets the same color as the path to which it + is attached. More precisely, it will get the current ``draw color'', + also known as ``stroke color,'' which you can set using + |draw=|\meta{some color}. By adding the option |color=| to an arrow + tip (note that an ``empty'' color is specified in this way), you ask + that the arrow tip gets this default draw color of the path. Since + this is the default behaviour, you usually do not need to specify + anything: +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [red, arrows = {-Stealth}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [blue, arrows = {-Stealth}] (0,0) -- (1,0); +\end{codeexample} + + Now, when you provide a \meta{color} with this option, you request + that the arrow tip should get this color \emph{instead} of the color + of the main path: +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [red, arrows = {-Stealth[color=blue]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [red, arrows = {-Stealth[color=black]}] (0,0) -- (1,0); +\end{codeexample} + + Similar to the |color| option used in normal \tikzname\ options, you + may omit the |color=| part of the option. Whenever an \meta{arrow key} + is encountered that \tikzname\ does not recognize, it will test whether + the key is the name of a color and, if so, execute + |color=|\meta{arrow key}. So, the first of the above examples can be + rewritten as follows: +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [red, arrows = {-Stealth[blue]}] (0,0) -- (1,0); +\end{codeexample} + + The \meta{color} will apply both to any drawing and filling + operations used to construct the path. For instance, even though the + |Stealth| arrow tips looks like a filled quadrilateral, it is + actually constructed by drawing a quadrilateral and then filling it + in the same color as the drawing (see the |fill| option below to + see the difference). + + When |color| is set to an empty text, the drawing color is + always used to fill the arrow tips, even if a different color is + specified for filling the path: +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [draw=red, fill=red!50, arrows = {-Stealth[length=10pt]}] + (0,0) -- (1,1) -- (2,0); +\end{codeexample} + As you can see in the above example, the filled area is not quite + what you might have expected. The reason is that the path was + actually internally shortened a bit so that the end of the ``fat + line'' as inside the arrow tip and we get a ``clear'' arrow tip. + + In general, it is a good idea not to add arrow tips to paths that + are filled. +\end{key} + +\begin{key}{/pgf/arrow keys/fill=\meta{color or |none|}} + Use this key to explicitly set the color used for filling the arrow + tips. This color can be different from the color used to draw + (stroke) the arrow tip: +\begin{codeexample}[width=3cm] +\tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=white,length=15pt]}] (0,0) -- (1,0); +} +\end{codeexample} + You can also specify the special ``color'' |none|. In this case, the + arrow tip is not filled at all (not even with white): +\begin{codeexample}[width=3cm] +\tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=none,length=15pt]}] (0,0) -- (1,0); +} +\end{codeexample} + Note that such ``open'' arrow tips are a bit difficult to draw in + some case: The problem is that the line must be shortened by just + the right amount so that it ends exactly on the back end of the + arrow tip. In some cases, especially when double lines are used, + this will not be possible. + + \begin{key}{/pgf/arrow keys/open} + A shorthand for |fill=none|. + \end{key} + + When you use both the |color| and |fill| option, the |color| option + must come first since it will reset the filling to the color + specified for drawing. +\begin{codeexample}[width=3cm] +\tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[color=blue, fill=white, length=15pt]}] + (0,0) -- (1,0); +} +\end{codeexample} + + Note that by setting |fill| to the special color |pgffillcolor|, you + can cause the arrow tips to be filled using the color used to fill + the main path. (This special color is always available and always + set to the current filling color of the graphic state.): +\begin{codeexample}[width=3cm] +\tikz [ultra thick] \draw [draw=red, fill=red!50, + arrows = {-Stealth[length=15pt, fill=pgffillcolor]}] + (0,0) -- (1,1) -- (2,0); +\end{codeexample} +\end{key} + + +\subsubsection{Line Styling} +\label{section-arrow-key-caps} + +Arrow tips are created by drawing and possibly filling a path that +makes up the arrow tip. When \tikzname\ draws a path, there are +different ways in which such a path can be drawn (such as +dashing). Three particularly important parameters are the line join, +the line cap, see Section~\ref{section-line-cap} for an introduction, +and the line width (thickness) + +\tikzname\ resets the line cap and line join each time it draws an +arrow tip since you usually do not want their settings to ``spill +over'' to the way the arrow tips are drawn. You can, however, change +there values explicitly for an arrow tip: + +\begin{key}{/pgf/arrow keys/line cap=\meta{|round| or |butt|}} + Sets the line cap of all lines that are drawn in the arrow to a + round cap or a butt cap. (Unlike for normal lines, the |rect| cap is + not allowed.) Naturally, this key has no effect for arrows whose + paths are closed. + + Each arrow tip has a default value for the line cap, which can + be overruled using this option. + + Changing the cap should have no effect on the size of the + arrow. However, it will have an effect on where the exact ``tip'' of + the arrow is since this will always be exactly at the end of the + arrow: +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=butt]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=round]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=butt]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=round]}] + (0,0) -- (1,0); +\end{codeexample} +\end{key} + +\begin{key}{/pgf/arrow keys/line join=\meta{|round| or |miter|}} + Sets the line join to round or miter (|bevel| is not allowed). This + time, the key only has an effect on paths that have ``corners'' in + them. The same rules as for |line cap| apply: the size is not + affects, but the tip end is: + \begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=miter]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=round]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=miter]}] + (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=round]}] + (0,0) -- (1,0); +\end{codeexample} +\end{key} + +The following keys set both of the above: +\begin{key}{/pgf/arrow keys/round} + A shorthand for |line cap=round, line join=round|, resulting in + ``rounded'' arrow heads. + \begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[round]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,round]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + +\begin{key}{/pgf/arrow keys/sharp} + A shorthand for |line cap=butt, line join=miter|, resulting in + ``sharp'' or ``pointed'' arrow heads. + \begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[sharp]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=3cm] +\tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,sharp]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + + +You can also set the width of lines used inside arrow tips: + +\begin{key}{/pgf/arrow keys/line width=\meta{dimension}| |\opt{\meta{line width factor}}% + | |\opt{\meta{outer factor}}} + This key sets the line width inside an arrow tip for drawing + (out)lines of the arrow tip. When you set this width to |0pt|, which + makes sense only for closed tips, the arrow tip is only filled. This + can result in better rendering of some small arrow tips and in case + of bend arrow tips (because the line joins will also be bend and not + ``mitered''.) + + The meaning of the factors is as usual the same as for |length| or |width|. + +\begin{codeexample}[width=2cm] +\tikz \draw [arrows = {-Latex[line width=0.1pt, fill=white, length=10pt]}] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[width=2cm] +\tikz \draw [arrows = {-Latex[line width=1pt, fill=white, length=10pt]}] (0,0) -- (1,0); +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/arrow keys/line width'=\meta{dimension}| |\opt{\meta{length factor}}} + Works like |line width| only the factor is with respect to the |length|. +\end{key} + +\subsubsection{Bending and Flexing} + +\label{section-arrow-flex} + +Up to now, we have only added arrow tip to the end of straight lines, +which is in some sense ``easy.'' Things get far more difficult, if the +line to which we wish to end an arrow tip is curved. In the following, +we have a look at the different actions that can be taken and how they +can be configured. + +To get a feeling for the difficulties involved, consider the following +situation: We have a ``gray wall'' at the $x$-coordinate of and a +red line that ends in its middle. + +\begin{codeexample}[] +\def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5); + \pattern [pattern=bricks] (1,-.5) rectangle (2,.5); + \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); } +\begin{tikzpicture} + \wall + % The "line" + \draw [red,line width=1mm] (-1,0) -- (1,0); +\end{tikzpicture} +\end{codeexample} + +Now we wish to add a blue open arrow tip the red line like, say, +|Stealth[length=1cm,open,blue]|: + +\def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5); + \pattern [pattern=bricks] (1,-.5) rectangle (2,.5); + \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); } +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue]}] + (-1,0) -- (1,0); +\end{tikzpicture} +\end{codeexample} + +There are several noteworthy things about the blue arrow tip: +\begin{enumerate} +\item Notice that the red line no longer goes all the way to the + wall. Indeed, the red line ends more or less exactly where it meets + the blue line, leaving the arrow tip empty. Now, recall that the red + line was supposed to be the path |(-2,0)--(1,0)|; however, this path + has obviously become much shorter (by 6.25mm to be precise). This + effect is called \emph{path shortening} in \tikzname. +\item The very tip of the arrow just ``touches'' the wall, even we + zoom out a lot. This point, where the original path ended and where + the arrow tip should now lie, is called the \emph{tip end} in + \tikzname. +\item Finally, the point where the red line touches the blue line is + the point where the original path ``visually ends.'' Notice that + this is not the same as the point that lies at a distance of the + arrow's |length| from the wall -- rather it lies at a distance of + |length| minus the |inset|. Let us call this point the \emph{visual + end} of the arrow. +\end{enumerate} + +As pointed out earlier, for straight lines, shortening the path and +rotating and shifting the arrow tip so that it ends precisely at the +tip end and the visual end lies on a line from the tip end to the +start of the line is relatively easy. + +For curved lines, things are much more difficult and \tikzname\ copes +with the difficulties in different ways, depending on which options +you add to arrows. Here is now a curved red line to which we wish to +add our arrow tip (the original straight red line is shown in light red): + +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm] (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + +The first way of dealing with curved lines is dubbed the ``quick +and dirty'' way (although the option for selecting this option is +politely just called ``|quick|'' \dots): + +\begin{key}{/pgf/arrow keys/quick} + Recall that curves in \tikzname\ are actually B\'ezier curves, which + means that they start and end at certain points and we specify two + vectors, one for the start and one for the end, that provide + tangents to the curve at these points. In particular, for the end of + the curve, there is a point called the \emph{second support point} + of the curve such that a tangent to the curve at the end goes + through this point. In our above example, the second support point + is at the middle of the light red line and, indeed, a tangent to the + red line at the point touching the wall is perfectly horizontal. + + In order to add our arrow tip to the curved path, our first + objective is to ``shorten'' the path by 6.25mm. Unfortunately, this + is now much more difficult than for a straight path. When the + |quick| option is added to an arrow tip (it is also + the default if no special libraries are loaded), we cheat somewhat: + Instead of really moving along 6.25mm along the path, we simply + shift the end of the curve by 6.25mm \emph{along the tangent} (which + is easy to compute). We also have to shift the second support point + by the same amount to ensure that the line still has the same + tangent at the end. This will result in the following: + +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,quick]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + + They main problem with the above picture is that the red line is no + longer equal to the original red line (notice much sharper curvature + near its end). In our example this is not such a bad thing, but it + certainly ``not a nice thing'' that adding arrow tips to a curve + changes the overall shape of the curves. This is especially + bothersome if there are several similar curves that have different + arrow heads. In this case, the similar curves now suddenly look + different. + + Another big problem with the above approach is that it works only + well if there is only a single arrow tip. When there are multiple + ones, simply shifting them along the tangent as the |quick| option + does produces less-than-satisfactory results: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[quick,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + Note that the third arrow tip does not really lie on the curve any + more. +\end{key} + +Because of the shortcomings of the |quick| key, more powerful +mechanisms for shortening lines and rotating arrows tips have been +implemented. To use them, you need to load the following library: + +\begin{tikzlibrary}{bending} + Load this library to use the |flex|, |flex'|, or |bending| arrow + keys. When this library is loaded, |flex| becomes the default mode + that is used with all paths, unless |quick| is explicitly selected + for the arrow tip. +\end{tikzlibrary} + +\begin{key}{/pgf/arrow keys/flex=\opt{\meta{factor}} (default 1)} + When the |bending| library is loaded, this key is applied + to all arrow tips by default. It has the following effect: + \begin{enumerate} + \item Instead of simply shifting the visual end of the arrow along + the tangent of the curve's end, we really move it along the curve + by the necessary distance. This operation is more expensive than + the |quick| operation -- but not \emph{that} expensive, only + expensive enough so that it is not selected by default for all + arrow tips. Indeed, some compromises are made in the + implementation where accuracy was traded for speed, so the + distance by which the line end is shifted is not necessarily + \emph{exactly} 6.25mm; only something reasonably close. + \item The supports of the line are updated accordingly so that the + shortened line will still follow \emph{exactly} the original + line. This means that the curve deformation effect caused by the + |quick| command does not happen here. + \item Next, the arrow tip is rotated and shifted as follows: First, + we shift it so that its tip is exactly at the tip end, where the + original line ended. Then, the arrow is rotated so the \emph{the + visual end lies on the line}: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + \end{enumerate} + + As can be seen in the example, the |flex| option gives a result that + is visually pleasing and does not deform the path. + + There is, however, one possible problem with the |flex| option: The + arrow tip no longer points along the tangent of the end of the + path. This may or may not be a problem, put especially for larger + arrow tips readers will use the orientation of the arrow head to + gauge the direction of the tangent of the line. If this tangent is + important (for example, if it should be horizontal), then it may be + necessary to enforce that the arrow tip ``really points in the + direction of the tangent. + + To achieve this, the |flex| option takes an optional \meta{factor} + parameter, which defaults to |1|. This factor specifies how much the + arrow tip should be rotated: If set to |0|, the arrow points exactly + along a tangent to curve at its tip. If set to |1|, the arrow point + exactly along a line from the visual end point on the curve to the + tip. For values in the middle, we interpolate the rotation between + these two extremes; so |flex=.5| will rotate the arrow's visual end + ``halfway away from the tangent towards the actual position on the + line.'' +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=0]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=.5]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + Note how in the above examples the red line is visible inside the + open arrow tip. Open arrow tips do not go well with a flex value + other than~|1|. Here is a more realistic use of the |flex=0| key: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,flex=0]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + If there are several arrow tips on a path, the |flex| option + positions them independently, so that each of them lies optimally on + the path: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[flex,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\begin{key}{/pgf/arrow keys/flex'=\opt{\meta{factor}} (default 1)} + The |flex'| key is almost identical to the |flex| key. The only + difference is that a factor of |1| corresponds to rotating the arrow + tip so that the instead of the visual end, the ``ultimate back end'' + of the arrow tip lies on the red path. In the example instead of + having the arrow tip at a distance of |6.25mm| from the tip lie on + the path, we have the point at a distance of |1cm| from the tip lie + on the path: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex']}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + Otherwise, the factor works as for |flex| and, indeed |flex=0| and + |flex'=0| have the same effect. + + The main use of this option is not so much with an arrow tip like + |Stealth| but rather with tips like the standard |>| in the context + of a strongly curved line: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex]}] + (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + In the example, the |flex| option does not really flex the arrow + since for a tip like the Computer Modern arrow, the visual end is + the same as the arrow tip -- after all, the red line does, indeed, end + almost exactly where it used to end. + + Nevertheless, you may feel that the arrow tip looks ``wrong'' in the sense that it + should be rotated. This is exactly what the |flex'| option does + since it allows us to align the ``back end'' of the tip with the red line: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex'=.75]}] + (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} + In the example, I used |flex'=.75| so as not to overpronounce the + effect. Usually, you will have to fiddle with it sometime to get the + ``perfectly aligned arrow tip,'' but a value of |.75| is usually a + good start. +\end{key} + + + +\begin{key}{/pgf/arrow keys/bend} + \emph{Bending} an arrow tip is a radical solution to the problem of + positioning arrow tips on a curved line: The arrow tip is no longer + ``rigid'' but the drawing itself will now bend along the curve. This + has the advantage that all the problems of flexing with wrong + tangents and overflexing disappear. The downsides are longer + computation times (bending an arrow is \emph{much} more expensive + that flexing it, let alone than quick mode) and also the fact that + excessive bending can lead to ugly arrow tips. On the other hand, + for most arrow tips their bend version are visually quite pleasing + and create a sophisticated look: +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[length=20pt,bend]}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{[bend,sep]>>>}] + (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \wall + \draw [red!25,line width=1mm] (-1,0) -- (1,0); + \draw [red,line width=1mm,-{Stealth[bend,round,length=20pt]}] + (0,-.5) .. controls (1,-.5) and (0.25,0) .. (1,0); +\end{tikzpicture} +\end{codeexample} +\end{key} + + + + + + +\subsection{Arrow Tip Specifications} +\label{section-arrow-spec} + +\subsubsection{Syntax} + +When you select the arrow tips for the start and the end of a path, +you can specify a whole sequence of arrow tips, each having its own +local options. At the beginning of this section, it was pointed out +that the syntax for selecting the start and end arrow tips is the +following: + +\begin{quote} + \meta{start specification}|-|\meta{end specification} +\end{quote} + +We now have a closer look at what these specifications may look +like. The general syntax of the \meta{start specification} is as +follows: +\begin{quote} + \opt{|[|\meta{options for all tips}|]|} \meta{first arrow tip spec} + \meta{second arrow tip spec} \meta{third arrow tip spec} \dots +\end{quote} +As can be seen, an arrow tip specification may start with some options +in brackets. If this is the case, the \meta{options for all tips} +will, indeed, be applied to all arrow tips that follow. (We will see, +in a moment, that there are even more places where options may be +specified and a list of the ordering in which the options are applied +will be given later.) + +The main part of a specification is taken up by a sequence of +individual arrow tip specifications. Such a specification can be of +three kinds: + +\begin{enumerate} +\item It can be of the form \meta{arrow tip kind name}|[|\meta{options}|]|. +\item It can be of the form \meta{shorthand}|[|\meta{options}|]|. +\item It can be of the form \meta{single char shorthand}\opt{|[|\meta{options}|]|}. Note that only for this form the + brackets are optional. +\end{enumerate} + +The easiest kind is the first one: This adds an arrow tip of the kind +\meta{arrow tip kind name} to the sequence of arrow tips with the +\meta{options} applied to it at the start (for the \meta{start + specification}) or at the end (for the \meta{end + specification}). Note that for the \meta{start specification} the +first arrow tip specified in this way will be at the very start of the +curve, while for the \meta{end specification} the ordering is +reversed: The last arrow tip specified will be at the very end of the +curve. This implies that a specification like +\begin{quote} +|Stealth[] Latex[] - Latex[] Stealth[]| +\end{quote} +will give perfectly symmetric arrow tips on a line (as one would +expect). + +It is important that even if there are no \meta{options} for an arrow +tip, the square brackets still need to be written to indicate the end +of the arrow tip's name. Indeed, the opening brackets are used to +divide the arrow tip specification into names. + +Instead of a \meta{arrow tip kind name}, you may also provide the name +of a so-called \emph{shorthand}. Shorthands look like normal arrow tip +kind names and, indeed, you will often be using shorthands without +noticing that you do. The idea is that instead of, say, +|Computer Modern Rightarrow| you might wish to just write |Rightarrow| +or perhaps just |To| or even just |>|. For this, you can create a +shorthand that tells \tikzname\ that whenever this shorthand is used, +another arrow tip kind is meant. (Actually, shorthands are somewhat +more powerful, we have a detailed look at them in +Section~\ref{section-arrow-tip-macro}.) For shorthands, the same rules +apply as for normal arrow tip kinds: You \emph{need} to provide +brackets so that \tikzname\ can find the end of the name inside a +longer specification. + +The third kind of arrow tip specifications consist of just a single +letter like |>| or |)| or |*| or even |o| or |x| (but you may not use +|[|, |]|, or |-| since they will confuse the parser). These single +letter arrow specifications will invariably be shorthands that select +some ``real'' arrow tip instead. An important feature of single letter +arrow tips is that they do \emph{not} need to be followed by options +(but they may). + +Now, since we can use any letter for single letter shorthands, how can +\tikzname\ tell whether by |foo[]| we mean an arrow tip kind |foo| +without any options or whether we mean an arrow tip called |f|, +followed by two arrow tips called |o|? Or perhaps an arrow tip called +|f| followed by an arrow tip called |oo|? To solve this problem, the +following rule is used to determine which of the three possible +specifications listed above applies: First, we check whether +everything from the current position up to the next opening bracket +(or up to the end) is the name of an arrow tip or of a shorthand. In +our case, |foo| would first be tested under this rule. Only if |foo| +is neither the name of an arrow tip kind nor of a shorthand does +\tikzname\ consider the first letter of the specification, |f| in our +case. If this is not the name of a shorthand, an error is +raised. Otherwise the arrow tip corresponding to |f| is added to the +list of arrow tips and the process restarts with the rest. Thus, we +would next text whether |oo| is the name of an arrow tip or shorthand +and, if not, whether |o| is such a name. + +All of the above rules mean that you can rather easily specify arrow +tip sequences if they either mostly consist of single letter names or +of longer names. Here are some examples: + +\begin{itemize} +\item |->>>| is interpreted as three times the |>| shorthand since + |>>>| is not the name of any arrow tip kind (and neither is |>>|). +\item |->[]>>| has the same effect as the above. +\item |-[]>>>| also has the same effect.%>> +\item |->[]>[]>[]| so does this. +\item |->Stealth| yields an arrow tip |>| followed by a |Stealth| + arrow at the end. +\item |-Stealth>| is illegal since there is no arrow tip |Stealth>| + and since |S| is also not the name of any arrow tip. +\item |-Stealth[] >| is legal and does what was presumably meant in the previous item. +\item |< Stealth-| is legal and is the counterpart to |-Stealth[] >|. +\item |-Stealth[length=5pt] Stealth[length=6pt]| selects two stealth + arrow tips, but at slightly different sizes for the end of lines. +\end{itemize} + + +An interesting question concerns how flexing and bending interact with +multiple arrow tips: After all, flexing and quick mode use different +ways of shortening the path so we cannot really mix them. The +following rule is used: We check, independently for the start and the +end specifications, whether at least one arrow tip in them uses one of +the options |flex|, |flex'|, or |bend|. If so, all |quick| settings in +the other arrow tips are ignored and treated as if |flex| had been +selected for them, too. + + +\subsubsection{Specifying Paddings} + +When you provide several arrow tips in a row, all of them are added to +the start or end of the line: +\begin{codeexample}[] +\tikz \draw [<<<->>>>] (0,0) -- (2,0); +\end{codeexample} +The question is now what will be distance between them? For this, the +following arrow key is important: +\begin{key}{/pgf/arrow keys/sep=\meta{dimension}| |\opt{\meta{line + width factor}}| |\opt{\meta{outer factor}} (default 0.88pt .3 1)} + When a sequence of arrow tips is specified in an arrow tip + specification for the end of the line, the arrow tips are normally + arranged in such a way that the tip of each arrow ends exactly at + the ``back end'' of the next arrow tip (for start specifications, + the ordering is inverted, of course). Now, when the |sep| option is + set, instead of exactly touching the back end of the next arrow, the + specified \meta{dimension} is added as additional space (the + distance may also be negative, resulting in an overlap of the arrow + tips). The optional factors have the same meaning as for the + |length| key, see that key for details. + + Let us now have a look at some examples. First, we use two arrow + tips with different separations between them: +\begin{codeexample}[] +\tikz { + \draw [-{>[sep=1pt]>[sep= 2pt]>}] (0,1.0) -- (1,1.0); + \draw [-{>[sep=1pt]>[sep=-2pt]>}] (0,0.5) -- (1,0.5); + \draw [-{> >[sep] >}] (0,0.0) -- (1,0.0); +} +\end{codeexample} + + You can also specify a |sep| for the last arrow tip in the sequence + (for end specifications, otherwise for the first arrow tip). In this + case, this first arrow tip will not exactly ``touch'' the point + where the path ends, but will rather leave the specified amount of + space. This is usually quite desirable. +\begin{codeexample}[] +\tikz { + \node [draw] (A) {A}; + \node [draw] (B) [right=of A] {B}; + + \draw [-{>>[sep=2pt]}] (A) to [bend left=45] (B); + \draw [- >> ] (A) to [bend right=45] (B); +} +\end{codeexample} + Indeed, adding a |sep| to an arrow tip is \emph{very} desirable, so + you will usually write something like |>={To[sep]}| somewhere near + the start of your files. + + One arrow tip kind can be quite useful in this context: The arrow + tip kind |_|. It draws nothing and has zero length, \emph{but} + it has |sep| set as a default option. Since it is a single letter + shorthand, you can write short and clean ``code'' in this way: +\begin{codeexample}[] +\tikz \draw [->_>] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [->__>] (0,0) -- (1,0); +\end{codeexample} + However, using the |sep| option will be faster than using the |_| + arrow tip and it also allows you to specify the desired length + directly. +\end{key} + + + +\subsubsection{Specifying the Line End} + +In the previous examples of sequences of arrow tips, the line of the +path always ended at the last of the arrow tips (for end +specifications) or at the first of the arrow tips (for start +specifications). Often, this is what you may want, but not +always. Fortunately, it is quite easy to specify the desired end of +the line: The special single char shorthand |.| is reserved to +indicate that last arrow that is still part of the line; in other +words, the line will stop at the last arrow before |.| is encountered +(for end specifications) are at the first arrow following |.| (for +start specifications). +%>> +\begin{codeexample}[] +\tikz [very thick] \draw [<<<->>>] (0,0) -- (2,0); +\end{codeexample} +\begin{codeexample}[] +\tikz [very thick] \draw [<.<<->.>>] (0,0) -- (2,0); +\end{codeexample} +\begin{codeexample}[] +\tikz [very thick] \draw [<<.<-.>>>] (0,0) -- (2,0); +\end{codeexample} +\begin{codeexample}[] +\tikz [very thick] \draw [<<.<->.>>] (0,0) to [bend left] (2,0); +\end{codeexample} + +It is permissible that there are several dots in a specification, in +this case the first one ``wins'' (for end specifications, otherwise +the last one). + +Note that |.| is parsed as any other shorthand. In particular, if you +wish to add a dot after a normal arrow tip kind name, you need to add +brackets: +\begin{codeexample}[] +\tikz [very thick] \draw [-{Stealth[] . Stealth[] Stealth[]}] (0,0) -- (2,0); +\end{codeexample} +Adding options to |.| is permissible, but they have no effect. In +particular, |sep| has no effect since a dot is not an arrow. + + + + +\subsubsection{Defining Shorthands} +\label{section-arrow-tip-macro} + +It is often desirable to create ``shorthands'' for the names of arrow +tips that you are going to use very often. Indeed, in most documents +you will only need a single arrow tip kind and it would be useful that +you could refer to it just as |>| in your arrow tip specifications. As +another example, you might constantly wish to switch between a filled +and a non-filled circle as arrow tips and would like to use |*| and +|o| are shorthands for these case. Finally, you might just like to +shorten a long name like |Computer Modern Rightarrow| down to just, +say |To| or something similar. + +All of these case can be addressed by defining appropriate +shorthands. This is done using the following handler: + +\begin{handler}{{.tip}{=\meta{end specification}}} + Defined the \meta{key} as a name that can be used inside arrow tip + specifications. If the \meta{key} has a path before it, this path is + ignored (so there is only one ``namespace'' for arrow + tips). Whenever it is used, it will be replaced by the \meta{end + specification}. Note that you must \emph{always} provide + (only) an end specification; when the \meta{key} is used inside a + start specification, the ordering and the meaning of the keys inside + the \meta{end specification} are translated automatically. + +\begin{codeexample}[] +\tikz [foo /.tip = {Stealth[sep]. >>}] + \draw [-foo] (0,0) -- (2,0); +\end{codeexample} +\begin{codeexample}[] +\tikz [foo /.tip = {Stealth[sep] Latex[sep]}, + bar /.tip = {Stealth[length=10pt,open]}] + \draw [-{foo[red] . bar}] (0,0) -- (2,0); +\end{codeexample} + + In the last of the examples, we used |foo[red]| to make the arrows + red. Any options given to a shorthand upon use will be passed on to + the actual arrows tip for which the shorthand stands. Thus, we could + also have written |Stealth[sep,red]| |Latex[sep,red]| instead of + |foo[red]|. In other words, the ``replacement'' of a shorthand by + its ``meaning'' is a semantic replacement rather than a syntactic + replacement. In particular, the \meta{end specification} will be + parsed immediately when the shorthand is being defined. However, + this applies only to the options inside the specification, whose + values are evaluated immediately. In contrast, which actual arrow + tip kind is meant by a given shorthand used inside the \meta{end + specification} is resolved only up each use of the shorthand. This + means that when you write + \begin{quote} + |dup /.tip = >>| + \end{quote} + and then later write + \begin{quote} + |> /.tip = whatever| + \end{quote} + then |dup| will have the effect as if you had written + |whatever[]whatever[]|. You will find that this behaviour is + what one would expect. + + There is one problem we have not yet addressed: The asymmetry of + single letter arrow tips like |>| or |)|. When someone writes +\begin{codeexample}[] +\tikz \draw [<->] (0,0) -- (1,0); +\end{codeexample} + we rightfully expect one arrow tip pointing left at the left end and + an arrow tip pointing right at the right end. However, compare +\begin{codeexample}[] +\tikz \draw [>->] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw [Stealth-Stealth] (0,0) -- (1,0); +\end{codeexample} + In both cases, we have \emph{identical} text in the start and end + specifications, but in the first case we rightfully expect the left + arrow to be flipped. + + The solution to this problem is that it is possible to define + two names for the same arrow tip, namely one that is used inside + start specifications and one for end specifications. Now, we can + decree that the ``name of |>|'' inside start specifications is + simply |<| and the above problems disappear. + + To specify different names for a shorthand in start and end + specifications, use the following syntax: Instead of \meta{key}, you + use \meta{name in start specifications}|-|\meta{name in end + specifications}. Thus, to set the |>| key correctly, you actually + need to write +\begin{codeexample}[] +\tikz [<-> /.tip = Stealth] \draw [<->>] (0,0) -- (1,0); +\end{codeexample} +\begin{codeexample}[] +\tikz [<-> /.tip = Latex] \draw [>-<] (0,0) -- (1,0); +\end{codeexample} + + Note that the above also works even though we have not set |<| as an + arrow tip name for end specifications! The reason this works is that + the \tikzname\ (more precisely, \pgfname) actually uses the + following definition internally: + \begin{quote} + |>-< /.tip = >[reversed]| + \end{quote} + Translation: ``When |<| is used in an end specification, please + replace it by |>|, but reversed. Also, when |>| is used in a start + specification, we also mean this inverted |>|.'' + + By default, |>| is a shorthand for |To| and |To| is a shorthand for + |to| (an arrow from the old libraries) when |arrows.meta| is not + loaded library. When |arrow.meta| is loaded, |To| is redefined to + mean the same as + |Computer Modern Rightarrow|. +\end{handler} + +\begin{key}{/tikz/>=\meta{end arrow specification}} + This is a short way of saying |<->/.tip=|\meta{end arrow specification}. +\begin{codeexample}[] +\begin{tikzpicture}[scale=2,ultra thick] + \begin{scope}[>=Latex] + \draw[>->] (0pt,3ex) -- (1cm,3ex); + \draw[|<->>|] (0pt,2ex) -- (1cm,2ex); + \end{scope} + \begin{scope}[>=Stealth] + \draw[>->] (0pt,1ex) -- (1cm,1ex); + \draw[|<<.<->|] (0pt,0ex) -- (1cm,0ex); + \end{scope} +\end{tikzpicture} +\end{codeexample} + +\end{key} + + + +\subsubsection{Scoping of Arrow Keys} +\label{section-arrow-scopes} + +There are numerous places where you can specify keys for an arrow +tip. There is, however, one final place that we have not yet +mentioned: + +\begin{key}{/tikz/arrows=|[|\meta{arrow keys}|]|} + The |arrows| key, which is normally used to set the arrow tips for + the current scope, can also be used to set some arrow keys for the + current scope. When the argument to |arrows| starts with an opening + bracket and only otherwise contains one further closing bracket at + the very end, this semantic of the |arrow| key is assumed. + + The \meta{arrow keys} will be set for the rest of current + scope. This is useful for generally setting some design parameters + or for generally switching on, say, bending as in: +\begin{codeexample}[code only] +\tikz [arrows={[bend]}] ... % Bend all arrows +\end{codeexample} +\end{key} + +We can now summarize which arrow keys are applied in what order when +an arrow tip is used: +\begin{enumerate} +\item First, the so-called \emph{defaults} are applied, which are + values for the different parameters of a key. They are fixed in the + definition of the key and cannot be changed. Since they are executed + first, they are only the ultimate fallback. +\item The \meta{keys} from the use of |arrows=[|\meta{keys}|]| in all + enclosing scopes. +\item Recursively, the \meta{keys} provided with the arrow + tip inside shorthands. +\item The keys provided at the beginning of an arrow tip specification + in brackets. +\item The keys provided directly next to the arrow tip inside the + specification. +\end{enumerate} + + + + +\subsection{Reference: Arrow Tips} +\label{section-arrows-meta} + +\begin{pgflibrary}{arrows.meta} + This library defines a large number of standard ``meta'' arrow + tips. ``Meta'' means that you can configure these arrow tips in many + different ways like changing their size or their line caps and joins + and many other details. + + The only reason this library is not loaded by default is for + compatibility with older versions of \tikzname. You can, however, + safely load and use this library alongside the older libraries + |arrows| and |arrows.spaced|. +\end{pgflibrary} + + +The different arrow tip kinds defined in the |arrows.meta| library can +be classified in different groups: +\begin{itemize} +\item \emph{Barbed} arrow tips consist mainly of lines that ``point + backward'' from the tip of the arrow and which are not filled. For + them, filling has no effect. A typical example is \tikz [baseline] + \draw (0,.5ex) -- (1.5em,.5ex) [-Straight Barb];. Here is the list + of defined arrow tips: + + \begin{arrowexamples} + \arrowexample Arc Barb[] + \arrowexample Bar[] + \arrowexample Bracket[] + \arrowexample Hooks[] + \arrowexample Parenthesis[] + \arrowexample Straight Barb[] + \arrowexample Tee Barb[] + \end{arrowexamples} + + All of these arrow tips can be configured and resized in many + different ways as described in the following. Above, they are shown at + their ``natural'' sizes, which are chosen in such a way that for a + line width of 0.4pt their width matches the height + of a letter ``x'' in Computer Modern at 11pt (with some + ``overshooting'' to create visual consistency). +\item \emph{Mathematical} arrow tips are actually a subclass of the + barbed arrow tips, but we list them separately. They contain arrow + tips that look exactly like the tips of arrows used in mathematical + fonts such as the |\to|-symbol $\to$ from standard \TeX. + \begin{arrowexamples} + \arrowexample Classical TikZ Rightarrow[] + \arrowexample Computer Modern Rightarrow[] + \arrowexampledouble Implies[] + \arrowexample To[] + \end{arrowexamples} + The |To| arrow tip is a shorthand for |Computer Modern Rightarrow| + when |arrows.meta| is loaded. +\item \emph{Geometric} arrow tips consist of a filled shape like a + kite or a circle or a ``stealth-fighter-like'' shape. A typical + example is \tikz [baseline] \draw (0,.5ex) -- (1.5em,.5ex) + [-Stealth];. These arrow tips can also be used in an ``open'' + variant as in \tikz [baseline] \draw (0,.5ex) -- (1.5em,.5ex) + [-{Stealth[open]}];. + + \begin{arrowexamples} + \arrowexample Circle[] + \arrowexample Diamond[] + \arrowexample Ellipse[] + \arrowexample Kite[] + \arrowexample Latex[] + \arrowexample Latex[round] + \arrowexample Rectangle[] + \arrowexample Square[] + \arrowexample Stealth[] + \arrowexample Stealth[round] + \arrowexample Triangle[] + \arrowexample Turned Square[] + \end{arrowexamples} + + Here are the ``open'' variants: + + \begin{arrowexamples} + \arrowexample Circle[open] + \arrowexample Diamond[open] + \arrowexample Ellipse[open] + \arrowexample Kite[open] + \arrowexample Latex[open] + \arrowexample Latex[round,open] + \arrowexample Rectangle[open] + \arrowexample Square[open] + \arrowexample Stealth[open] + \arrowexample Stealth[round,open] + \arrowexample Triangle[open] + \arrowexample Turned Square[open] + \end{arrowexamples} + + Note that ``open'' arrow tips are not the same as ``filled with + white,'' which is also available (just say |fill=white|). The + difference is that the background will ``shine through'' an open + arrow, while a filled arrow always obscures the background: + +\begin{codeexample}[] +\tikz { + \shade [left color=white, right color=red!50] (0,0) rectangle (4,1); + + \draw [ultra thick,-{Triangle[open]}] (0,2/3) -- ++ (3,0); + \draw [ultra thick,-{Triangle[fill=white]}] (0,1/3) -- ++ (3,0); +} +\end{codeexample} + +\item \emph{Cap} arrow tips are used to add a ``cap'' to the end of a + line. The graphic languages underlying \tikzname\ (\textsc{pdf}, + \textsc{postscript} or \textsc{svg}) all support three basic types + of line caps on a very low level: round, rectangular, and ``butt.'' + Using cap arrow tips, you can add new caps to lines and use + different caps for the end and the start. An example is the line + \tikz [baseline] \draw [line width=1ex, {Round + Cap[reversed]}-{Triangle Cap[] . Fast Triangle[] Fast Triangle[]}] + (0,0.5ex) -- (2em,0.5ex);. + \begin{arrowcapexamples} + \arrowcapexample Butt Cap[] + \arrowcapexample Fast Round[] + \arrowcapexample Fast Triangle[] + \arrowcapexample Round Cap[] + \arrowcapexample Triangle Cap[] + \end{arrowcapexamples} +\item \emph{Special} arrow tips are used for some specific purpose and + do not fit into the above categories. + \begin{arrowexamples} + \arrowexample Rays[] + \arrowexample Rays[n=8] + \end{arrowexamples} +\end{itemize} + +\subsubsection{Barbed Arrow Tips} + +\begin{arrowtip}{Arc Barb} + { + This arrow tip attaches an arc to the end of the line whose angle + is given by the |arc| option. The + |length| and |width| parameters refer to the size of the arrow tip + for |arc| set to 180 degrees, which is why in the example for + |arc=210| the actual length is larger than the specified + |length|. The line width is taken into account + for the computation of the length and width. Use the |round| + option to add round caps to the end of the arcs. + } + {length=1.5cm,arc=210} + {length=1.5cm,width=3cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[arc=120] + \arrowexample[arc=270] + \arrowexample[length=2pt] + \arrowexample[length=2pt,width=5pt] + \arrowexample[line width=2pt] + \arrowexample[reversed] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + + +\begin{arrowtipsimple}{Bar} + A simple bar. This is a simple instance of |Tee Barb| for length zero. +\end{arrowtipsimple} + +\begin{arrowtip}{Bracket} + { + This is an instance of the |Tee Barb| arrow tip that results in + something resembling a bracket. Just like the |Parenthesis| arrow + tip, a |Bracket| is not modelled from a text square bracket, but + rather its size has been chosen so that it fits with the other + arrow tips. + } + {} + {} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[reversed] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + +\begin{arrowtip}{Hooks} + { + This arrow tip attaches two ``hooks'' to the end of the line. The + |length| and |width| parameters refer to the size of the arrow tip + if both arcs are 180 degrees; in the example the arc is 210 + degrees and, thus, the arrow is actually longer that the |length| + dictates. The line width is taken into account for the computation + of the length and width. The |arc| option is used to specify the + angle of the arcs. Use the |round| option to add round caps to the + end of the arcs. + } + {length=1cm,width=3.5cm,arc=210} + {length=1cm,width=3.5cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[arc=120] + \arrowexample[arc=270] + \arrowexample[length=2pt] + \arrowexample[length=2pt,width=5pt] + \arrowexample[line width=2pt] + \arrowexample[reversed] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + + +\begin{arrowtip}{Parenthesis} + { + This arrow tip is an instantiation of the |Arc Barb| so that it + resembles a parenthesis. However, the idea is not to recreate a + ``real'' parenthesis as it is used in text, but rather a ``bow'' + at a size that harmonizes with the other arrow tips at their + default sizes. + } + {} + {} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[reversed] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + +\begin{arrowtip}{Straight Barb} + { + This is the ``archetypal'' arrow head, consisting of just two + straight lines. The |length| and |width| parameters refer to the + horizontal and vertical distances between the points on the path + making up the arrow tip. As can be seen, the line width of the + arrow tip's path is not taken into account. + The |angle| option is particularly useful to set + the opening angle at the tip of the arrow head. The |round| option + gives a ``softer'' or ``rounder'' version of the arrow tip. + } + {length=2cm,width=3cm} + {length=2cm/-4mm,width=3cm} + + \begin{arrowexamples} + \arrowexample[] +% \arrowexampledouble[] + \arrowexampledup[] + \arrowexampledupdot[] + \arrowexample[length=5pt] + \arrowexample[length=5pt,width=5pt] + \arrowexample[line width=2pt] + \arrowexample[reversed] + \arrowexample[angle=60:2pt 3] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + + +\begin{arrowtip}{Tee Barb} + { + This arrow tip attaches a little ``T'' on both sides of the + tip. The arrow |inset| dictates the distance from the back end to + the middle of the stem of the T. When the inset is equal to the + length, the arrow tip is drawn as a single line, not as three + lines (this is important for the ``round'' version since, then, + the corners get rounded). + } + {length=1.5cm,width=3cm,inset=1cm} + {length=1.5cm,width=3cm,inset=1cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[inset=0pt] + \arrowexample[inset'=0pt 1] + \arrowexample[line width=2pt] + \arrowexample[round] + \arrowexample[round,inset'=0pt 1] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + + + +\subsubsection{Mathematical Barbed Arrow Tips} + + +\begin{arrowtip}{Classical TikZ Rightarrow} + { + This arrow tip is the ``old'' or ``classical'' arrow tip that used + to be the standard in \tikzname\ in earlier versions. It was + modelled on an old version of the tip of \texttt{\string\rightarrow} + ($\rightarrow$) of the Computer Modern fonts. However, this ``old + version'' was really old, Donald + Knuth (the designer of both \TeX\ and of the Computer Modern + fonts) replaced the arrow tip of the mathematical fonts + in~1992. + } + {length=1cm,width=2cm} + {length=1cm,width=2cm} + The main problem with this arrow tip is that it is ``too small'' + at its natural size. I recommend using the new \texttt{Computer Modern + Rightarrow} arrow tip instead, which matches the current + $\to$. This new version is also the default used as |>| and as + |To|, now. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[length=3pt] + \arrowexample[sharp] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + +\begin{arrowtip}{Computer Modern Rightarrow} + { + For a line width of 0.4pt (the default), this arrow tip looks very + much like \texttt{\string\rightarrow} ($\to$) of the Computer Modern math + fonts. However, it is not a ``perfect'' match: the line caps and + joins of the ``real'' $\to$ are rounded differently from this + arrow tip; but it takes a keen eye to notice the difference. When + the |arrow.meta| library is loaded, this arrow tip becomes the + default of |To| and, thus, is used whenever |>| is used (unless, + of course, you redefined |>|). + } + {length=1cm,width=2cm} + {length=1cm,width=2cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[length=3pt] + \arrowexample[sharp] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[harpoon,reversed] + \arrowexample[red] + \end{arrowexamples} + The following options have no effect: |open|, |fill|. + + On |double| lines, the arrow tip will not look correct. +\end{arrowtip} + + + +\begin{arrowtipsimple}{Implies} + This arrow tip makes only sense in conjunction with the |double| + option. The idea is that you attach it to a double line to get + something that looks like \TeX's \texttt{\string\implies} arrow + ($\implies$). A typical use of this arrow tip is +\begin{codeexample}[] +\tikz \graph [clockwise=3, math nodes, + edges = {double equal sign distance, -Implies}] { + "\alpha", "\beta", "\gamma"; + "\alpha" -> "\beta" -> "\gamma" -> "\alpha" +}; +\end{codeexample} + \begin{arrowexamples} + \arrowexampledouble[] + \arrowexampledouble[red] + \end{arrowexamples} +\end{arrowtipsimple} + +\begin{arrowtipsimple}{To} + This is a shorthand for |Computer Modern Rightarrow| when the + |arrow.meta| library is loaded. Otherwise, it is a shorthand for the + classical \tikzname\ rightarrow. +\end{arrowtipsimple} + + + + +\subsubsection{Geometric Arrow Tips} + + + +\begin{arrowtip}{Circle} + { + Although this tip is called ``circle,'' you can also use it to + draw ellipses if you set the length and width to different + values. Neither |round| nor |reversed| has any effect on this + arrow tip. + } + {length=2cm,width=2cm} + {length=2cm,width=2cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=3pt] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} + +\begin{arrowtipsimple}{Diamond} + This is an instance of |Kite| where the length is larger than the + width. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[] + \arrowexampledupdot[] + \arrowexample[open] + \arrowexample[length=10pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \arrowexample[fill=red!50] + \end{arrowexamples} +\end{arrowtipsimple} + +\begin{arrowtipsimple}{Ellipse} + This is a shorthand for a ``circle'' that is twice as wide as high. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=10pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \arrowexample[fill=red!50] + \end{arrowexamples} +\end{arrowtipsimple} + + +\begin{arrowtip}{Kite} + { + This arrow tip consists of four lines that form a ``kite.'' The + |inset| prescribed how far the width-axis of the kite is removed + from the back end. Note that the inset cannot be negative, use a + |Stealth| arrow tip for this. + } + {length=3cm,width=2cm,inset=1cm} + {length=3cm,width=2cm,inset=1cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=6pt,width=4pt] + \arrowexample[length=6pt,width=4pt,inset=1.5pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} + + +\begin{arrowtip}{Latex} + { + This arrow tip is the same as the arrow tip used in \LaTeX's + standard pictures (via the \texttt{\string\vec} command), if you + set the length to 4pt. The default size for this arrow tip was set + slightly larger so that it fits better with the other geometric + arrow tips. + } + {length=3cm,width=2cm} + {length=3cm,width=2cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=4pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} + +\begin{arrowtipsimple}{LaTeX} + Another spelling for the |Latex| arrow tip. +\end{arrowtipsimple} + + + +\begin{arrowtip}{Rectangle} + { + A rectangular arrow tip. By default, it is twice as long as high. + } + {length=3cm,width=2cm} + {length=3cm,width=2cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=4pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} + + +\begin{arrowtipsimple}{Square} + An instance of the |Rectangle| whose width is identical to the length. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=4pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtipsimple} + + + +\begin{arrowtip}{Stealth} + { + This arrow tip is similar to a |Kite|, only the |inset| now counts + ``inwards.'' Because of that sharp angles, for this arrow tip is + makes quite a difference, visually, if use the |round| + option. Also, using the |harpoon| option (or |left| or |right|) + will \emph{lengthen} the arrow tip because of the even sharper + corner at the tip. + } + {length=3cm,width=2cm,inset=1cm} + {length=3cm,width=2cm,inset=1cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=6pt,width=4pt] + \arrowexample[length=6pt,width=4pt,inset=1.5pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} + + +\begin{arrowtipsimple}{Triangle} + An instance of a |Kite| with zero inset. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=4pt] + \arrowexample[angle=45:1pt 3] + \arrowexample[angle=60:1pt 3] + \arrowexample[angle=90:1pt 3] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtipsimple} + +\begin{arrowtipsimple}{Turned Square} + An instance of a |Kite| with identical width and height and mid-inset. + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[open] + \arrowexample[length=4pt] + \arrowexample[round] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtipsimple} + + + +\subsubsection{Caps} + +Recall that a \emph{cap} is a way of ending a line. The graphic +languages underlying \tikzname\ (\textsc{pdf}, \textsc{postscript} or +\textsc{svg}) all support three basic types of line caps on a very low +level: round, rectangular, and ``butt.'' Using cap arrow tips, you can +add new caps to lines and use different caps for the end and the +start. + + +\begin{arrowtipsimple}{Butt Cap} + This arrow tip ends the line ``in the normal way'' with a straight + end. This arrow tip is only need to ``cover up'' the actual line + cap, if this happens to differ from the normal cap. In the following + example, the line cap is ``round'', but, nevertheless, the right end + is a ``butt'' cap: + +\begin{codeexample}[] +\tikz \draw [line width=1ex, line cap=round, -Butt Cap] (0,0) -- (1,0); +\end{codeexample} +\end{arrowtipsimple} + + +\begin{arrowcap}{Fast Round} + { + This arrow tip is not really a cap, you use it in conjunction with + (typically) the |Round Cap|. The idea is that you end your line + using the round cap and then add several \texttt{Fast + Round}s. As for |Round Cap|, the |length| parameter + dictates the length is the length of the ``main part,'' the + inset sets the length of a line that comes before this tip. + } + {length=5mm,inset=1cm} + {length=5mm,inset=-1cm} + {-15mm} + +\begin{codeexample}[] +\tikz \draw [line width=1ex, + -{Round Cap []. Fast Round[] Fast Round[]}] + (0,0) -- (1,0); +\end{codeexample} + Note that in conjunction with the |bend| option, this works even + quite well for curves: +\begin{codeexample}[] +\tikz [f/.tip = Fast Round] % shorthand + \draw [line width=1ex, -{[bend] Round Cap[] . f f f}] + (0,0) to [bend left] (1,0); +\end{codeexample} + + \begin{arrowcapexamples} + \arrowcapexample[] + \arrowcapexample[reversed] + \arrowcapexample[cap angle=60] + \arrowcapexample[cap angle=60,inset=5pt] + \arrowcapexample[length=.5ex] + \arrowcapexample[slant=.3] + \end{arrowcapexamples} +\end{arrowcap} + + +\begin{arrowcap}{Fast Triangle} + { + This arrow tip works like |Fast Round|, only for triangular caps. + } + {length=5mm,inset=1cm} + {length=5mm,inset=-1cm} + {-15mm} + +\begin{codeexample}[] +\tikz \draw [line width=1ex, + -{Triangle Cap []. Fast Triangle[] Fast Triangle[]}] + (0,0) -- (1,0); +\end{codeexample} + Again, this tip works well for curves: +\begin{codeexample}[] +\tikz [f/.tip = Fast Triangle] % shorthand + \draw [line width=1ex, -{[bend] Triangle Cap[] . f f f}] + (0,0) to [bend left] (1,0); +\end{codeexample} + + \begin{arrowcapexamples} + \arrowcapexample[] + \arrowcapexample[reversed] + \arrowcapexample[cap angle=60] + \arrowcapexample[cap angle=60,inset=5pt] + \arrowcapexample[length=.5ex] + \arrowcapexample[slant=.3] + \end{arrowcapexamples} +\end{arrowcap} + + + +\begin{arrowcap}{Round Cap} + { + This arrow tip ends the line using a half circle or, if the length + has been modified, a half-ellipse. + } + {length=5mm} + {length=5mm} + {-5mm} + \begin{arrowcapexamples} + \arrowcapexample[] + \arrowcapexample[reversed] + \arrowcapexample[length=.5ex] + \arrowcapexample[slant=.3] + \end{arrowcapexamples} +\end{arrowcap} + + + +\begin{arrowcap}{Triangle Cap} + { + This arrow tip ends the line using a triangle whose length is + given by the |length| option. + } + {length=5mm} + {length=5mm} + {-5mm} + + You can get any angle you want at the tip by specifying a length + that is an appropriate multiple of the line width. The following + options does this computation for you: + \begin{key}{/pgf/arrow keys/cap angle=\meta{angle}} + Sets |length| to an appropriate multiple of the line width so that + the angle of a |Triangle Cap| is exactly \meta{angle} at the tip. + \end{key} + + \begin{arrowcapexamples} + \arrowcapexample[] + \arrowcapexample[reversed] + \arrowcapexample[cap angle=60] + \arrowcapexample[cap angle=60,reversed] + \arrowcapexample[length=.5ex] + \arrowcapexample[slant=.3] + \end{arrowcapexamples} +\end{arrowcap} + + +\subsubsection{Special Arrow Tips} + +\begin{arrowtip}{Rays} + { + This arrow tip attaches a ``bundle of rays'' to the tip. The + number of evenly spaced rays is given by the |n| arrow key (see + below). When the number is even, the rays will lie to the left and + to the right of the direction of the arrow; when the number is + odd, the rays are rotated in such a way that one of them points + perpendicular to the direction of the arrow (this is to ensure + that no ray points in the direction of the line, which would look + strange). The |length| and |width| describe the length and width + of an ellipse into which the rays fit. + } + {length=3cm,width=3cm,n=6} + {length=3cm,width=3cm} + + \begin{arrowexamples} + \arrowexample[] + \arrowexampledup[sep] + \arrowexampledupdot[sep] + \arrowexample[width'=0pt 2] + \arrowexample[round] + \arrowexample[n=2] + \arrowexample[n=3] + \arrowexample[n=4] + \arrowexample[n=5] + \arrowexample[n=6] + \arrowexample[n=7] + \arrowexample[n=8] + \arrowexample[n=9] + \arrowexample[slant=.3] + \arrowexample[left] + \arrowexample[right] + \arrowexample[left,n=5] + \arrowexample[right,n=5] + \arrowexample[red] + \end{arrowexamples} +\end{arrowtip} +\begin{key}{/pgf/arrow keys/n=\meta{number} (initially 4)} + Sets the number of rays in a |Rays| arrow tip. +\end{key} + + +\endinput + + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex index 1847b27bc92..d23d81efb3e 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex @@ -18,7 +18,7 @@ coordinates. Coordinates are always put in round brackets. The general syntax is \declare{|(|\opt{|[|\meta{options}|]|}\meta{coordinate specification}|)|}. -The \meta{coordinate specification} specified coordinates using one of +The \meta{coordinate specification} specifies coordinates using one of many different possible \emph{coordinate systems}. Examples are the Cartesian coordinate system or polar coordinates or spherical coordinates. No matter which coordinate system is used, in the end, a @@ -185,7 +185,7 @@ by interpreting them as |pt|. So, |2+3cm| is the same dimension as polar coordinates. You provide an angle using the |angle=| option and a radius using the |radius=| option. This yields the point on the canvas that is at the given radius distance from the origin at - the given degree. A degree of zero points to the right, a degree of + the given degree. An angle of zero degrees to the right, a degree of 90 upward. \begin{key}{/tikz/cs/angle=\meta{degrees}} The angle of the coordinate. @@ -238,7 +238,7 @@ by interpreting them as |pt|. So, |2+3cm| is the same dimension as point that lies at a given angle on this ellipse, where an angle of zero is the same as the $x$-vector and an angle of 90 is the $y$-vector. Finally, multiply the resulting vector by the given - radius factor. Voilà. + radius factor. Voil\`a. \begin{key}{/tikz/cs/angle=\meta{degrees}} The angle of the coordinate interpreted in the ellipse whose axes are the $x$-vector and the @@ -359,8 +359,8 @@ you use the following coordinate system: You can use three options to specify which coordinate you mean: \begin{key}{/tikz/cs/name=\meta{node name}} - Specifies the node in which you which to specify a coordinate. The - \meta{node name} is + Specifies the node that you wish to use to specify a coordinate. + The \meta{node name} is the name that was previously used to name the node using the |name=|\meta{node name} option or the special node name syntax. \end{key} @@ -375,7 +375,8 @@ you use the following coordinate system: \draw (node cs:name=circle,anchor=north) |- (0,1); \draw (node cs:name=ellipse,anchor=north) |- (0,1); - \draw[-open triangle 90] (node cs:name=rect,anchor=north) + \draw [arrows = -{Triangle[open, angle=60:3mm]}] + (node cs:name=rect,anchor=north) |- (0,1) -| (node cs:name=shape,anchor=south); \end{tikzpicture} \end{codeexample} @@ -700,7 +701,7 @@ coordinate system. \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}. For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield - the same as \verb!(2,4)! (provided the $xy$-coordinate system has not + the same as \verb!(2,4)! (provided the $xy$-co\-or\-di\-nate system has not been modified). The most useful application of the syntax is to draw a line up to some @@ -719,6 +720,30 @@ coordinate system. \draw[->] (p2) -- (p2 -| yline); \end{tikzpicture} \end{codeexample} + + Note that in \declare{|(|\meta{c}\verb! |- !\meta{d}|)|} the + coordinates \meta{c} and \meta{d} are \emph{not} surrounded by + parentheses. If they need to be complicated expressions (like a + computation using the |$|-syntax), %$ + you must surround them with braces; parentheses will then be added + around them. + + As an example, let us specify a point that lies horizontally at the + middle of the line from $A$ to~$B$ and vertically at the middle of + the line from $C$ to~$D$: +\begin{codeexample}[] +\begin{tikzpicture} + \node (A) at (0,1) {A}; + \node (B) at (1,1.5) {B}; + \node (C) at (2,0) {C}; + \node (D) at (2.5,-2) {D}; + + \draw (A) -- (B) node [midway] {x}; + \draw (C) -- (D) node [midway] {x}; + + \node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X}; +\end{tikzpicture} +\end{codeexample} \end{coordinatesystem} @@ -728,7 +753,7 @@ coordinate system. This library enables the calculation of intersections of two arbitrary paths. However, due to the low accuracy of \TeX, the paths should not be ``too complicated''. - In particular, you should not try to intersect paths consisting + In particular, you should not try to intersect paths consisting of lots of very small segments such as plots or decorated paths. \end{tikzlibrary} @@ -787,7 +812,7 @@ The following keys can be used in \meta{options}: \end{key} \begin{key}{/tikz/intersection/total=\meta{macro}} - This key will mean than the total number of intersections found + This key means that the total number of intersections found will be stored in \meta{macro}. \end{key} @@ -908,14 +933,14 @@ notation to specify numerous points, all relative to the same There is a special situation, where relative coordinates are interpreted differently. If you use a relative coordinate as a control -point of a Bézier curve, the following rule applies: First, a relative +point of a B\'ezier curve, the following rule applies: First, a relative first control point is taken relative to the beginning of the curve. Second, a relative second control point is taken relative to the end of the curve. Third, a relative end point of a curve is taken relative to the start of the curve. This special behavior makes it easy to specify that a curve should -``leave or arrives from a certain direction'' at the start or end. In +``leave or arrive from a certain direction'' at the start or end. In the following example, the curve ``leaves'' at $30^\circ$ and ``arrives'' at $60^\circ$: @@ -928,6 +953,55 @@ the following example, the curve ``leaves'' at $30^\circ$ and \end{codeexample} +\subsubsection{Rotational Relative Coordinates} + +You may sometimes wish to specify points relative not only to the +previous point, but additionally relative to the tangent entering the +previous point. For this, the following key is useful: + +\begin{key}{/tikz/turn} + This key can be given as an option to a \meta{coordinate} as in the + following example: +\begin{codeexample}[] +\tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm); +\end{codeexample} + The effect of this key is to locally shift the coordinate system so + that the last point reached is at the origin and the coordinate + system is ``turned'' so that the $x$-axis points in the direction of + a tangent entering the last point. This means, in effect, that when + you use polar coordinates of the form \meta{relative + angle}|:|\meta{distance} together with the |turn| option, you + specify a point that lies at \meta{distance} from the last point in + the direction of the last tangent entering the last point, but with + a rotation of \meta{relative angle}. + + This key also works with curves \dots +\begin{codeexample}[] +\tikz [delta angle=30, radius=1cm] + \draw (0,0) arc [start angle=0] -- ([turn]0:1cm) + arc [start angle=30] -- ([turn]0:1cm) + arc [start angle=60] -- ([turn]30:1cm); +\end{codeexample} +\begin{codeexample}[] +\tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm); +\end{codeexample} + + \dots and with plots \dots +\begin{codeexample}[] +\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm); +\end{codeexample} + + Although the above examples use polar coordinates with |turn|, you + can also use any normal coordinate. For instance, |([turn]1,1)| will + append a line of length $\sqrt 2$ that is turns by $45^\circ$ + relative to the tangent to the last point. +\begin{codeexample}[] +\tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1) + .. controls ([turn]0:1cm) .. ([turn]-90:1cm); +\end{codeexample} +\end{key} + + \subsubsection{Relative Coordinates and Scopes} \label{section-scopes-relative} An interesting question is, how do relative coordinates behave in the @@ -984,7 +1058,7 @@ decide which you need. It is possible to do some basic calculations that involve coordinates. In essence, you can add and subtract coordinates, scale them, compute midpoints, and do projections. For instance, -|($(a) + 1/3*(1cm,0)$)| is the coordinate that is $1/3$cm to the right +|($(a) + 1/3*(1cm,0)$)| is the coordinate that is $1/3 \text{cm}$ to the right of the point |a|: \begin{codeexample}[] \begin{tikzpicture} @@ -1050,7 +1124,7 @@ following rule is used: Once it has been determined, that a everything up to the next occurrence of |*(|. Note that there is no space between the asterisk and the parenthesis. -It is permissible to put the \meta{factor} is curly braces. This can +It is permissible to put the \meta{factor} in curly braces. This can be used whenever it is unclear where the \meta{factor} would end. Here are some examples of coordinate specifications that consist of @@ -1089,7 +1163,7 @@ $(1-\meta{number})\meta{coordinate x} + \meta{number} \meta{coordinate \meta{number} is interpreted in the |xcolor| package: First, you use a factor between $0$ and $1$, not a percentage, and, second, as the \meta{number} approaches $1$, we approach the second coordinate, not -the first. It is permissible to use \meta{numbers} that are smaller +the first. It is permissible to use a \meta{number} that is smaller than $0$ or larger than $1$. The \meta{number} is evaluated using the |\pgfmathparse| command and, thus, it can involve complicated computations. @@ -1223,7 +1297,7 @@ Here is an example: \end{codeexample} The effect is the following: We project the \meta{projection - coordinate} orthogonally onto to the line from \meta{coordinate} to + coordinate} orthogonally onto the line from \meta{coordinate} to \meta{second coordinate}. This makes it easy to compute projected points: \begin{codeexample}[] diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex index a00c1df01ad..5c1276b02cb 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex @@ -166,7 +166,7 @@ typeset and they can be inaccurate. The reason is that \pgfname\ has to a \emph{lot} of rather difficult computations in the background and \TeX\ is not very good at doing math. Decorations are fastest when applied to straight line segments, but even then they are much slower -than other alternative. For instance, the |ticks| decoration can be +than other alternatives. For instance, the |ticks| decoration can be simulated by clever use of a dashing pattern and the dashing pattern will literally be thousands of times faster to typeset. However, for most decorations there are no real alternatives. @@ -225,7 +225,7 @@ command. \begin{key}{/pgf/decoration=\meta{decoration options}} \keyalias{tikz} This option is used to specify which decoration is used and how it - will look like. Note that his key will \emph{not} cause any + will look like. Note that this key will \emph{not} cause any decorations to be applied, immediately. It takes the |decorate| path command or the |decorate| option to actually decorate a path. The |decoration| option is only used to specify which decoration should @@ -244,7 +244,7 @@ command. The \meta{decoration options} are special options (which have the path prefix |/pgf/decoration/|) that determine the properties of the decoration. Which options are appropriate for a - decoration depend strongly on the decoration, you will have to look + decoration strongly depend on the decoration, you will have to look up the appropriate options in the documentation of the decoration, see Section~\ref{section-library-decorations}. @@ -319,7 +319,7 @@ command. You may sometimes wish to decorate a path over whose construction you have no control. For instance, the path of the background of a node is -created without your having a chance to issue a |decorate| path +created without having a chance to issue a |decorate| path command. In such cases you can use the following option, which allows you to decorate a path ``after the fact.'' @@ -334,7 +334,7 @@ you to decorate a path ``after the fact.'' \end{enumerate} The main use or the |decorate| option is the you can also use it with the nodes. It then causes the background path of the node to be - decorated. Note that you decorate a background path only once in + decorated. Note that you can decorate a background path only once in this manner. That is, in contrast to the |decorate| path command you cannot apply this option twice (this would just set it to |true|, once more). @@ -367,8 +367,8 @@ you to decorate a path ``after the fact.'' \end{codeexample} Here is more useful example, where a postaction is used to add the path after the main path has been drawn. +% \catcode`\|12 % !? \begin{codeexample}[] -\catcode`\|12 \begin{tikzpicture} \draw [help lines] grid (3,2); \fill [draw=red,fill=red!20, @@ -506,7 +506,7 @@ not with meta-decorations. \begin{key}{/pgf/decoration/pre length=\meta{dimension} (initially 0pt)} This key sets the distance along which the pre-decoration should be used. If you do not need/wish a pre-decoration, set this key to - |0pt| (exactly this string, not just to something that evaluated to + |0pt| (exactly this string, not just to something that evaluates to the same things such as |0cm|). \end{key} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex index b3e19fdefd6..48a2f06a467 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex @@ -21,9 +21,9 @@ The commands and syntax of \tikzname\ were influenced by several sources. The basic command names and the notion of path operations is taken from \textsc{metafont}, the option mechanism comes from \textsc{pstricks}, the notion of styles is reminiscent of -\textsc{svg}. To make it all work together, some compromises were -necessary. I also added some ideas of my own, like coordinate -transformations. +\textsc{svg}, the graph syntax is taken from \textsc{graphviz}. To make it +all work together, some compromises were necessary. I also added some +ideas of my own, like coordinate transformations. The following basic design principles underlie \tikzname: \begin{enumerate} @@ -33,6 +33,7 @@ The following basic design principles underlie \tikzname: \item Key-value syntax for graphic parameters. \item Special syntax for nodes. \item Special syntax for trees. +\item Special syntax for graphs. \item Grouping of graphic parameters. \item Coordinate transformation system. \end{enumerate} @@ -118,7 +119,7 @@ stroking. \subsection{Key-Value Syntax for Graphic Parameters} Whenever \tikzname\ draws or fills a path, a large number of graphic -parameters influenced the rendering. Examples include the colors +parameters influences the rendering. Examples include the colors used, the dashing pattern, the clipping area, the line width, and many others. In \tikzname, all these options are specified as lists of so called key-value pairs, as in |color=red|, that are @@ -137,8 +138,8 @@ in the following example: \tikz \draw (1,1) node {text} -- (2,2); \end{codeexample} Nodes are inserted at the current position of -the path, but only \emph{after} the path has been rendered. When -special options are given, as in +the path, but either \emph{after} (the default) or \emph{before} the +complete path is rendered. When special options are given, as in |\draw (1,1) node[circle,draw] {text};|, the text is not just put at the current position. Rather, it is surrounded by a circle and this circle is ``drawn.'' @@ -152,12 +153,10 @@ it is possible (though a bit challenging) to define new shapes. \subsection{Special Syntax for Specifying Trees} -In addition to the ``node syntax,'' \tikzname\ also introduces a -special syntax for drawing trees. The syntax is intergraded with the -special node syntax and only few new commands need to be remembered. -In essence, a |node| can be followed by any number of children, each -introduced by the keyword |child|. The children are nodes themselves, -each of which may have children in turn. +The ``node syntax'' can also be used to draw tress: A |node| can be +followed by any number of children, each introduced by the keyword +|child|. The children are nodes themselves, each of which may have +children in turn. \begin{codeexample}[] \begin{tikzpicture} @@ -176,7 +175,7 @@ redrawn with different options: \begin{codeexample}[] \begin{tikzpicture} - [edge from parent fork down, + [edge from parent fork down, sibling distance=15mm, level distance=15mm, every node/.style={fill=red!30,rounded corners}, edge from parent/.style={red,-o,thick,draw}] \node {root} @@ -191,6 +190,7 @@ redrawn with different options: \begin{codeexample}[] \begin{tikzpicture} [parent anchor=east,child anchor=west,grow=east, + sibling distance=15mm, level distance=15mm, every node/.style={ball color=red,circle,text=white}, edge from parent/.style={draw,dashed,thick,red}] \node {root} @@ -202,6 +202,31 @@ redrawn with different options: \end{tikzpicture} \end{codeexample} + + +\subsection{Special Syntax for Graphs} + +The |\node| command gives you fine control over where nodes should be +placed, what text they should use, and what they should look +like. However, when you draw a graph, you typically need to create +numerous fairly similar nodes that only differ with respect to the +name they show. In these cases, the |graph| syntax can be used, which +is another syntax layer build ``on top'' of the node syntax. + +\begin{codeexample}[] +\tikz \graph [grow down, branch right] { + root -> { left, right -> {child, child} } +}; +\end{codeexample} +The syntax of the |graph| command extends the so-called +\textsc{dot}-notation used in the popular \textsc{graphviz} program. + +Depending on the version of \TeX\ you use (it must allow you to call +Lua code, which is the case for Lua\TeX), you can also ask \tikzname\ +to do automatically compute good positions for the nodes of a graph +using one of several integrated \emph{graph drawing algorithms}. + + \subsection{Grouping of Graphic Parameters} Graphic parameters should often apply to several path drawing or @@ -244,11 +269,11 @@ transformations, a more low-level transformation system. (For details on the difference between coordinate transformations and canvas transformations see Section~\ref{section-design-transformations}.) -The syntax is setup in such a way that is harder to use canvas +The syntax is set up in such a way that it is harder to use canvas transformations than coordinate transformations. There are two reasons for this: First, the canvas transformation must be used with great care and often results in ``bad'' graphics with changing line width -and text in wrong sizes. Second, \pgfname\ looses track of where nodes +and text in wrong sizes. Second, \pgfname\ loses track of where nodes and shapes are positioned when canvas transformations are used. So, in almost all circumstances, you should use coordinate transformations rather than canvas transformations. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex new file mode 100644 index 00000000000..91aebaa1b0d --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex @@ -0,0 +1,3515 @@ +% Copyright 2010 by Till Tantau +% Copyright 2011 by Jannis Pohlmann +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Specifying Graphs} +\label{section-library-graphs} + + +\subsection{Overview} + +\tikzname\ offers a powerful path command for specifying how the nodes +in a graph are connected by edges and arcs: The |graph| path +command, which becomes available when you load the |graphs| library. + +\begin{tikzlibrary}{graphs} + The package must be loaded to use the |graph| path command. +\end{tikzlibrary} + +In this section, by \emph{graph} we refer to a set of nodes together +with some edges (sometimes also called arcs, in case they are +directed) such as the following: + +\begin{codeexample}[] +\tikz \graph { a -> {b, c} -> d }; +\end{codeexample} + +\begin{codeexample}[] +\tikz \graph { + subgraph I_nm [V={a, b, c}, W={1,...,4}]; + + a -> { 1, 2, 3 }; + b -> { 1, 4 }; + c -> { 2 [>green!75!black], 3, 4 [>red]} +}; +\end{codeexample} + +\begin{codeexample}[] +\tikz + \graph [nodes={draw, circle}, clockwise, radius=.5cm, empty nodes, n=5] { + subgraph I_n [name=inner] --[complete bipartite] + subgraph I_n [name=outer] + }; +\end{codeexample} + +\begin{codeexample}[] +\tikz + \graph [nodes={draw, circle}, clockwise, radius=.75cm, empty nodes, n=8] { + subgraph C_n [name=inner] <->[shorten <=1pt, shorten >=1pt] + subgraph C_n [name=outer] + }; +\end{codeexample} + +\begin{codeexample}[width=6.6cm] +\tikz [>={To[sep]}, rotate=90, xscale=-1, + mark/.style={fill=black!50}, mark/.default=] + \graph [trie, simple, + nodes={circle,draw}, + edges={nodes={ + inner sep=1pt, anchor=mid, + fill=graphicbackground}}, % yellowish background + put node text on incoming edges] + { + root[mark] -> { + a -> n -> { + g [mark], + f -> a -> n -> g [mark] + }, + f -> a -> n -> g [mark], + g[mark], + n -> { + g[mark], + f -> a -> n -> g[mark] + } + }, + { [edges=red] % highlight one path + root -> f -> a -> n + } + }; +\end{codeexample} + +The nodes of a graph are normal \tikzname\ nodes, the edges are +normal lines drawn between nodes. There is nothing in the |graph| +library that you cannot do using the normal |\node| and the |edge| +commands. Rather, its purpose is to offer a concise and powerful way of +\emph{specifying} which nodes are present +and how they are connected. The |graph| library only offers simple +methods for specifying \emph{where} the nodes should be shown, its +main strength is in specifying which nodes and edges are present in +principle. The problem of finding ``good positions on the canvas'' for +the nodes of a graph is left to \emph{graph drawing algorithms}, which +are covered in Part~\ref{part-gd} of this manual and which +are not part of the |graphs| library; indeed, these algorithms can be +used also with graphs specified using |node| and |edge| +commands. \ifluatex +As an example, consider the above drawing of a trie, which is drawn +without using the graph drawing libraries. Its layout can be +somewhat improved by loading the |layered| graph drawing library, +saying |\tikz[layered layout,...|, and then using Lua\TeX, resulting +in the following drawing of the same graph: +\medskip + +\tikz [layered layout, >={To[sep]}, rotate=90, xscale=-1, + mark/.style={fill=black!50}, mark/.default=] + \graph [trie, simple, sibling distance=8mm, + nodes={circle,draw}, + edges={nodes={ + inner sep=1pt, anchor=mid, fill=white}}, + put node text on incoming edges] + { + root[mark] -> { + a -> n -> { + g [mark], + f -> a -> n -> g [mark] + }, + f -> a -> n -> g [mark], + g[mark], + n -> { + g[mark], + f -> a -> n -> g[mark] + } + }, + { [edges=red] % highlight one path + root -> f -> a -> n + } + }; +\medskip +\fi + +The |graph| library uses a syntax that is quite different from the +normal \tikzname\ syntax for specifying nodes. The reason for this is +that for many medium-sized graphs it can become quite cumbersome to +specify all the nodes using |\node| repeatedly and then using a great +number of |edge| command; possibly with complicated |\foreach| +statements. Instead, the syntax of the |graph| library is loosely +inspired by the \textsc{dot} format, which is quite useful for +specifying medium-sized graphs, with some extensions on top. + + + +\subsection{Concepts} + +The present section aims at giving a quick overview of the main +concepts behind the |graph| command. The exact syntax is explained in +more detail in later sections. + + +\subsubsection{Concept: Node Chains} + +The basic way of specifying a graph is to write down a \emph{node + chain} as in the following example: + +\begin{codeexample}[] +\tikz [every node/.style = draw] + \graph { foo -> bar -> blub }; +\end{codeexample} + +As can be seen, the text |foo -> bar -> my node| creates three nodes, +one with the text |foo|, one with |bar| and one with the text +|blub|. These nodes are connected by arrows, which are caused by +the |->| between the node texts. Such a sequence of node texts and +arrows between them is called a \emph{chain} in the following. + +Inside a graph there can be more than one chain: + +\begin{codeexample}[] +\tikz \graph { + a -> b -> c; + d -> e -> f; + g -> f; +}; +\end{codeexample} + +Multiple chains are separated by a semicolon or a comma (both have +exactly the same effect). As the example shows, when a node text is +seen for the second time, instead of creating a new node, a connection +is created to the already existing node. + +When a node like |f| is created, both the node name and the node text +are identical by default. This is not always desirable and can be +changed by using the |as| key or by providing another text after +a slash: + +\begin{codeexample}[] +\tikz \graph { + x1/$x_1$ -> x2 [as=$x_2$, red] -> x34/{$x_3,x_4$}; + x1 -> [bend left] x34; +}; +\end{codeexample} + +When you wish to use a node name that contains special symbols like +commas or dashes, you must surround the node name by quotes. This +allows you to use quite arbitrary text as a ``node name'': +\begin{codeexample}[] +\tikz \graph { + "$x_1$" -> "$x_2$"[red] -> "$x_3,x_4$"; + "$x_1$" ->[bend left] "$x_3,x_4$"; +}; +\end{codeexample} + + +\subsubsection{Concept: Chain Groups} + +Multiple chains that are separated by a semicolon or a comma and that +are surrounded by curly braces form what will be called a \emph{chain + group} or just a \emph{group}. A group in itself has no special +effect. However, things get interesting when you write down a node or +even a whole group and connect it to another group. In this case, the +``exit points'' of the first node or group get connected to the +``entry points'' of the second node or group: + +\begin{codeexample}[] +\tikz \graph { + a -> { + b -> c, + d -> e + } -> f +}; +\end{codeexample} + +Chain groups make it easy to create tree structures: + +\begin{codeexample}[width=10cm] +\tikz + \graph [grow down, + branch right=2.5cm] { + root -> { + child 1, + child 2 -> { + grand child 1, + grand child 2 + }, + child 3 -> { + grand child 3 + } + } +}; +\end{codeexample} + +As can be seen, the placement is not particularly nice by default, use +the algorithms from the graph drawing libraries to get a better +layout. For instance, adding |tree layout| to the above code results in the +following somewhat more pleasing rendering: +\ifluatex +\medskip + +\tikz \graph [grow down, branch right=2.5cm, tree layout] { + root -> { + child 1, + child 2 -> { + grand child 1, + grand child 2 + }, + child 3 -> { + grand child 3 + } + } +}; +\else +(You need to use Lua\TeX\ to typeset this graphic.) +\fi + +\subsubsection{Concept: Edge Labels and Styles} + +When connectors like |->| or |--| are used to connect nodes or whole +chain groups, one or more edges will typically be created. These edges +can be styles easily by providing options in square brackets directly +after these connectors: + +\begin{codeexample}[] +\tikz \graph { + a ->[red] b --[thick] {c, d}; +}; +\end{codeexample} + +Using the quotes syntax, see Section~\ref{section-label-quotes}, +you can even add labels to the edges easily by putting the labels in +quotes: + +\begin{codeexample}[] +\tikz \graph { + a ->[red, "foo"] b --[thick, "bar"] {c, d}; +}; +\end{codeexample} + +For the first edge, the effect is as desired, however +between |b| and the group |{c,d}| two edges are inserted and the +options |thick| and the label option |"bar"| is applied to both of +them. While this is the correct and consistent behaviour, we typically +might wish to specify different labels for the edge going from |b| to +|c| and the edge going from |b| to |d|. To achieve this effect, we can +no longer specify the label as part of the options of |--|. Rather, we +must pass the desired label to the nodes |c| and |d|, but we must +somehow also indicate that these options actually ``belong'' to the +edge ``leading to'' to nodes. This is achieved by preceding the +options with a greater-than sign: + +\begin{codeexample}[] +\tikz \graph { + a -> b -- {c [> "foo"], d [> "bar"']}; +}; +\end{codeexample} + +Symmetrically, preceding the options by |<| causes the options and +labels to apply to the ``outgoing'' edges of the node: + +\begin{codeexample}[] +\tikz \graph { + a [< red] -> b -- {c [> blue], d [> "bar"']}; +}; +\end{codeexample} + +This syntax allows you to easily create trees with special edge +labels as in the following example of a treap: + +\begin{codeexample}[] +\tikz + \graph [edge quotes={fill=white,inner sep=1pt}, + grow down, branch right, nodes={circle,draw}] { + "" -> h [>"9"] -> { + c [>"4"] -> { + a [>"2"], + e [>"0"] + }, + j [>"7"] + } + }; +\end{codeexample} + + + +\subsubsection{Concept: Node Sets} + +When you write down some node text inside a |graph| command, a new +node is created by default unless this node has already been created +inside the same |graph| command. In particular, if a node has +already been declared outside of the current |graph| command, a new +node of the same name gets created. + +This is not always the desired behaviour. Often, you may wish to make +nodes part of a graph than have already been defined prior to the use +of the |graph| command. For this, simply surround a node name by +parentheses. This will cause a reference to be created to an already +existing node: + +\begin{codeexample}[] +\tikz { + \node (a) at (0,0) {A}; + \node (b) at (1,0) {B}; + \node (c) at (2,0) {C}; + + \graph { (a) -> (b) -> (c) }; +} +\end{codeexample} + +You can even go a step further: A whole collection of nodes can all be +flagged to belong to a \emph{node set} by adding the option +|set=|\meta{node set name}. Then, inside a |graph| command, you can +collectively refer to these nodes by surrounding the node set name in +parentheses: + +\begin{codeexample}[] +\tikz [new set=my nodes] { + \node [set=my nodes, circle, draw] at (1,1) {A}; + \node [set=my nodes, rectangle, draw] at (1.5,0) {B}; + \node [set=my nodes, diamond, draw] at (1,-1) {C}; + \node (d) [star, draw] at (3,0) {D}; + + \graph { X -> (my nodes) -> (d) }; +} +\end{codeexample} + + +\subsubsection{Concept: Graph Macros} + +Often, a graph will consist -- at least in parts -- of standard +parts. For instance, a graph might contain a cycle of certain size or +a path or a clique. To facilitate specifying such graphs, you can +define a \emph{graph macro}. Once a graph macro has been defined, you +can use the name of the graph to make a copy of the graph part of the +graph currently being specified: + +\begin{codeexample}[] +\tikz \graph { subgraph K_n [n=6, clockwise] }; +\end{codeexample} + +\begin{codeexample}[] +\tikz \graph { subgraph C_n [n=5, clockwise] -> mid }; +\end{codeexample} + +The library |graphs.standard| defines a number of such graphs, +including the complete clique $K_n$ on $n$ nodes, the complete +bipartite graph $K_{n,m}$ with shores sized $n$ and $m$, the cycle +$C_n$ on $n$ nodes, the path $P_n$ on $n$ nodes, and the independent +set $I_n$ on $n$ nodes. + + +\subsubsection{Concept: Graph Expressions and Color Classes} + +When a graph is being constructed using the |graph| command, it is +constructed recursively by uniting smaller graphs to larger +graphs. During this recursive union process the nodes +of the graph get implicitly \emph{colored} (conceptually) and you can +also explicitly assign colors to individual nodes and even change the +colors as the graph is being specified. All nodes having the same +color form what is called a \emph{color class}. + +The power of color class is that special \emph{connector operators} +allow you to add edges between nodes having certain colors. For instance, +saying |clique=red| at the beginning of a group will +cause all nodes that have been flagged as being (conceptually) ``red'' +to be connected as a clique. Similarly, saying +|complete bipartite={red}{green}| will cause edges to be added +between all red and all green nodes. More advanced connectors, like +the |butterfly| connector, allow you to add edges between color +classes in a fancy manner. + +\begin{codeexample}[] +\tikz [x=8mm, y=6mm, circle] + \graph [nodes={fill=blue!70}, empty nodes, n=8] { + subgraph I_n [name=A] --[butterfly={level=4}] + subgraph I_n [name=B] --[butterfly={level=2}] + subgraph I_n [name=C] --[butterfly] + subgraph I_n [name=D] -- + subgraph I_n [name=E] + }; +\end{codeexample} + + + +\subsection{Syntax of the Graph Path Command} + +\subsubsection{The Graph Command} + +In order to construct a graph, you should use the |graph| path +command, which can be used anywhere on a path at any place where +you could also use a command like, say, |plot| or |--|. + +\begin{command}{\graph} + Inside a |{tikzpicture}| this is an abbreviation for |\path graph|. +\end{command} + +\begin{pathoperation}{graph}{\opt{\oarg{options}}\meta{group specification}} + When this command is encountered on a path, the construction of the + current path is suspended (similarly to an |edge| command or a + |node| command). In a local scope, the \meta{options} are first + executed with the key path |/tikz/graphs| using the following + command: + \begin{command}{\tikzgraphsset\marg{options}} + Executes the \meta{options} with the path prefix |/tikz/graphs|. + \end{command} + Apart from the keys explained in the following, further permissible + keys will be listed during the course of the rest of this section. + + \begin{stylekey}{/tikz/graphs/every graph} + This style is executed at the beginning of every |graph| path + command prior to the \meta{options}. + \end{stylekey} + + Once the scope has been set up and once the \meta{options} have been + executed, a parser starts to parse the \meta{group + specification}. The exact syntax of such a group specification + in explained in detail in + Section~\ref{section-library-graphs-group-spec}. Basically, a group + specification is a list of chain specifications, separated by commas + or semicolons. + + Depending on the content of the \meta{group specification}, two + things will happen: + \begin{enumerate} + \item A number of new nodes may be created. These will be inserted + into the picture in the same order as if they had been created + using multiple |node| path commands at the place where the |graph| + path command was used. In other words, all nodes created in a + |graph| path command will be painted on top of any nodes created + earlier in the path and behind any nodes created later in the + path. Like normal nodes, the newly created nodes always lie on top + of the path that is currently being created (which is often + empty, for instance when the |\graph| command is used). + \item Edges between the nodes may be added. They are added in the + same order as if the |edge| command had been used at the position + where the |graph| command is being used. + \end{enumerate} + + Let us now have a look at some common keys that may be used inside + the \meta{options}: + \begin{key}{/tikz/graphs/nodes=\meta{options}} + This option causes the \meta{options} to be applied to each newly + created node inside the \meta{group specification}. + \begin{codeexample}[] +\tikz \graph [nodes=red] { a -> b -> c }; + \end{codeexample} + Multiple uses of this key accumulate. + \end{key} + \begin{key}{/tikz/graphs/edges=\meta{options}} + This option causes the \meta{options} to be applied to each newly + created edge inside the \meta{group specification}. + \begin{codeexample}[] +\tikz \graph [edges={red,thick}] { a -> b -> c }; + \end{codeexample} + Again, multiple uses of this key accumulate. + \end{key} + \begin{key}{/tikz/graphs/edge=\meta{options}} + This is an alias for |edges|. + \end{key} + + \begin{key}{/tikz/graphs/edge node=\meta{node specification}} + This key specifies that the \meta{node specification} should be + added to each newly created edge as an implicitly placed node. + \begin{codeexample}[] +\tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c }; + \end{codeexample} + Again, multiple uses of this key accumulate. + \begin{codeexample}[] +\tikz \graph [edge node={node [near end] {X}}, + edge node={node [near start] {Y}}] { a -> b -> c }; + \end{codeexample} + \end{key} + + \begin{key}{/tikz/graphs/edge label=\meta{text}} + This key is an abbreviation for + |edge node=node[auto]{|\meta{text}|}|. The net effect is that the + |text| is placed next to the newly created edges. + \begin{codeexample}[] +\tikz \graph [edge label=x] { a -> b -> {c,d} }; + \end{codeexample} + \end{key} + + \begin{key}{/tikz/graphs/edge label'=\meta{text}} + This key is an abbreviation for + |edge node=node[auto,swap]{|\meta{text}|}|. + \begin{codeexample}[] +\tikz \graph [edge label=out, edge label'=in] + { subgraph C_n [clockwise, n=5] }; + \end{codeexample} + \end{key} +\end{pathoperation} + + +\subsubsection{Syntax of Group Specifications} +\label{section-library-graphs-group-spec} + +A \meta{group specification} inside a |graph| path command has the +following syntax: +\begin{quote} + |{|\opt{\oarg{options}}\meta{list of chain specifications}|}| +\end{quote} +The \meta{chain specifications} must contain chain specifications, +whose syntax is detailed in the next section, separated by either +commas or semicolons; you can freely mix them. +It is permissible to use empty lines (which are mapped to |\par| +commands internally) to structure the chains visually, they are simply +ignored by the parser. + +In the following example, the group specification consists of three +chain specifications, namely of |a -> b|, then |c| alone, and finally +|d -> e -> f|: +\begin{codeexample}[] +\tikz \graph { + a -> b, + c; + + d -> e -> f +}; +\end{codeexample} +The above has the same effect as the more compact group specification +|{a->b,c,d->e->f}|. + +Commas are used to detect where chain specifications end. However, you +will often wish to use a comma also inside the options of a single +node like in the following example: + +\begin{codeexample}[] +\tikz \graph { + a [red, draw] -> b [blue, draw], + c [brown, draw, circle] +}; +\end{codeexample} + +Note that the above example works as expected: The first comma inside +the option list of |a| is \emph{not} interpreted as the end of the +chain specification ``|a [red|''. Rather, commas inside square +brackets are ``protected'' against being interpreted as separators of +group specifications. + +The \meta{options} that can be given at the beginning of a group +specification are local to the group. They are executed with the path +prefix |/tikz/graphs|. Note that for the outermost group specification +of a graph it makes no difference whether the options are passed to +the |graph| command or whether they are given at the beginning of this +group. However, for groups nested inside other groups, it does make a +difference: + +\begin{codeexample}[] +\tikz \graph { + a -> { [nodes=red] % the option is local to these nodes: + b, c + } -> + d +}; +\end{codeexample} + +\medskip +\textbf{Using foreach.} +There is special support for the |\foreach| statement inside groups: +You may use the statement inside a group +specification at any place where a \meta{chain specification} would +normally go. In this case, the |\foreach| statement is executed and +for each iteration the content of the statement's body is treated and +parsed as a new chain specification. + +\begin{codeexample}[] +\tikz \graph [math nodes, branch down=5mm] { + a -> { + \foreach \i in {1,2,3} { + a_\i -> { x_\i, y_\i } + }, + b + } +}; +\end{codeexample} + +\medskip +\textbf{Using macros.} +In some cases you may wish to use macros and \TeX\ code to compute +which nodes and edges are present in a group. You cannot use macros in +the normal way inside a graph specification since the parser does not +expand macros as it scans for the start and end of groups and node +names. Rather, only after commas, semicolons, and hyphens have already +been detected and only after all other parsing decisions have been +made will macros be expanded. At this point, when a macro expands to, +say |a,b|, this will not result in two nodes to be created since the +parsing is already done. For these reasons, a special key is needed to +make it possible to ``compute'' which nodes should be present in a +group. + +\begin{key}{/tikz/graph/parse=\meta{text}} + This key can only be used inside the \meta{options} of a \meta{group + specification}. Its effect is that the \meta{text} is inserted at + the beginning of the current group as if you had entered it there. + Naturally, it makes little sense to just write down some static + \meta{text} since you could just as well directly place it at the + beginning of the group. The real power of this command stems from + the fact that the keys mechanism allows you to say, for instance, + |parse/.expand once| to insert the text stored in some macro into + the group. +\begin{codeexample}[] +\def\mychain{ a -> b -> c; } +\tikz \graph { [parse/.expand once=\mychain] d -> e }; +\end{codeexample} + In the following, more fancy example we use a loop to create a chain + of dynamic length. +\begin{codeexample}[] +\def\mychain#1{ + \def\mytext{1} + \foreach \i in {2,...,#1} { + \xdef\mytext{\mytext -> \i} + } +} +\tikzgraphsset{my chain/.style={ + /utils/exec=\mychain{#1}, + parse/.expand once=\mytext} +} +\tikz \graph { [my chain=4] }; +\end{codeexample} + Multiple uses of this key accumulate, that is, all the \text{text}s + given in the different uses is inserted in the order it is given. +\end{key} + + +\subsubsection{Syntax of Chain Specifications} + +A \meta{chain specification} has the following syntax: It consists of +a sequence of \meta{node specifications}, where subsequent node +specifications are separated by \meta{edge specifications}. Node +specifications, which typically consist of some text, are discussed in +the next section in more detail. They normally represent a single node +that is either newly created or exists already, but they may also +specify a whole set of nodes. + +An \meta{edge specification} specifies \emph{which} of the node(s) to +the left of the edge specification should be connected to which +node(s) to the right of it and it also specifies in which direction +the connections go. In the following, we only discuss how the +direction is chosen, the powerful mechanism behind choosing which +nodes should be connect is detailed in +Section~\ref{section-library-graphs-color-classes}. + +The syntax of an edge specification is always one of the following +five possibilities: + +\begin{quote} + |->| \opt{\oarg{options}}\\ + |--| \opt{\oarg{options}}\\ + |<-| \opt{\oarg{options}}\\ + |<->| \opt{\oarg{options}}\\ + |-!-| \opt{\oarg{options}} +\end{quote} + +The first four correspond to a directed edge, an undirected edge, a +``backward'' directed edge, and a bidirected edge, respectively. The +fifth edge specification means that there should be no edge (this +specification can be used together with the |simple| option to remove +edges that have previously been added, see +Section~\ref{section-library-graphs-simple}). + +Suppose the nodes \meta{left nodes} are to the left of the \meta{edge + specification} and \meta{right nodes} are to the right and suppose +we have written |->| between them. Then the following happens: +\begin{enumerate} +\item The \meta{options} are executed (inside a local scope) with the + path |/tikz/graphs|. These options may setup the connector algorithm + (see below) and may also use keys like |edge| or |edge label| to + specify how the edge should look like. As a convenience, whenever an + unknown key is encountered for the path |/tikz/graphs|, the key is + passed to the |edge| key. This means that you can directly use + options like |thick| or |red| inside the \meta{options} and they + will apply to the edge as expected. +\item The chosen connector algorithm, see + Section~\ref{section-library-graphs-color-classes}, is used to + compute from which of the \meta{left nodes} an edge should lead to + which of the \meta{right nodes}. Suppose that $(l_1,r_1)$, \dots, + $(l_n,r_n)$ is the list of node pairs that result (so there should + be an edge between $l_1$ and $r_1$ and another edge between $l_2$ + and $r_2$ and so on). +\item For each pair $(l_i,r_i)$ an edge is created. This is done by + calling the following key (for the edge specification |->|, other + keys are executed for the other kinds of specifications): + \begin{key}{/tikz/graphs/new ->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} + This key will be called for a |->| edge specification with the + following four parameters: + \begin{enumerate} + \item \meta{left node} is the name of the ``left'' node, that is, + the name of $l_i$. + \item \meta{right node} is the name of the right node. + \item \meta{edge options} are the accumulated options from all + calls of |/tikz/graph/edges| in groups that surround the edge + specification. + \item \meta{edge nodes} is text like |node {A} node {B}| that + specifies some nodes that should be put as labels on the edge + using \tikzname's implicit positioning mechanism. + \end{enumerate} + By default, the key executes the following code: + \begin{quote} + |\path [->,every new ->]|\\ + \hbox{}\quad|(|\meta{left node}|\tikzgraphleftanchor) edge [|% + \meta{edge options}|]| \meta{edge nodes}||\\ + \hbox{}\quad|(|\meta{right node}|\tikzgraphrightanchor);| + \end{quote} + You are welcome to change the code underlying the key. + \begin{stylekey}{/tikz/every new ->} + This key gets executed by default for a |new ->|. + \end{stylekey} + \end{key} + \begin{key}{/tikz/graphs/left anchor=\meta{anchor}} + This anchor is used for the node that is to the left of an edge + specification. Setting this anchor to the empty string means that + no special anchor is used (which is the default). The + \meta{anchor} is stored in the macro |\tikzgraphleftanchor| with a + leading dot. + \begin{codeexample}[] +\tikz \graph { + {a,b,c} -> [complete bipartite] {e,f,g} +}; + \end{codeexample} + \begin{codeexample}[] +\tikz \graph [left anchor=east, right anchor=west] { + {a,b,c} -- [complete bipartite] {e,f,g} +}; + \end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/right anchor=\meta{anchor}} + Works like |left anchor|, only for |\tikzgraphrightanchor|. + \end{key} + For the other three kinds of edge specifications, the following keys + will be called: + \begin{key}{/tikz/graphs/new --=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} + This key is called for |--| with the same parameters as above. The + only difference in the definition is that in the |\path| command + the |->| gets replaced by |-|. + \begin{stylekey}{/tikz/every new --} + \end{stylekey} + \end{key} + \begin{key}{/tikz/graphs/new <->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} + Called for |<->| with the same parameters as above. The |->| is + replaced by |<-| + \begin{stylekey}{/tikz/every new <->} + \end{stylekey} + \end{key} + \begin{key}{/tikz/graphs/new <-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} + Called for |<-| with the same parameters as above.% + \footnote{You might + wonder why this key is needed: It seems more logical at first + sight to just call |new edge directed| with swapped first + parameters. However, a positioning + algorithm might wish to take the fact into account that an edge is + ``backward'' rather than ``forward'' in order to + improve the layout. Also, different arrow heads might be used.} + \begin{stylekey}{/tikz/every new <-} + \end{stylekey} + \end{key} + \begin{key}{/tikz/graphs/new -\protect\exclamationmarktext-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}} + Called for |-!-| with the same parameters as above. Does nothing + by default. + \end{key} +\end{enumerate} + +Here is an example that shows the default rendering of the different +edge specifications: + +\begin{codeexample}[] +\tikz \graph [branch down=5mm] { + a -> b; + c -- d; + e <- f; + g <-> h; + i -!- j; +}; +\end{codeexample} + + + +\subsubsection{Syntax of Node Specifications} + +\label{section-library-graphs-node-spec} + +Node specifications are the basic building blocks of a graph +specification. There are three different possible kinds of node +specifications, each of which has a different syntax: + +\begin{description} +\item[Direct Node Specification] + \ \\ + \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} \opt{\oarg{options}}\\ + (note that the quotation marks are optional and only needed when the + \meta{node name} contains special symbols) +\item[Reference Node Specification] + \ \\ + |(|\meta{node name or node set name}|)| +\item[Group Node Specification] + \ \\ + \meta{group specification} +\end{description} + +The rule for determining which of the possible kinds is meant is +as follows: If the node specification starts with an opening +parenthesis, a reference node specification is meant; if it starts +with an opening curly brace, a group specification is meant; and in +all other cases a direct node specification is meant. + +\medskip +\textbf{Direct Node Specifications.} If after reading the first symbol +of a node specification is has been detected to be \emph{direct}, +\tikzname\ will collect all text up to the next edge +specification and store it as the \meta{node name}; however, square +brackets are used to indicate options and a slash ends the \meta{node + name} and start a special \meta{text} that is used as a +rendering text instead of the original \meta{node name}. + +Due to the way the parsing works and due to the restrictions on node +names, most special characters are forbidding inside the \meta{node + name}, including commas, semicolons, hyphens, braces, dots, +parentheses, slashes, dashes, and more (but spaces, single +underscores, and the hat character \emph{are} allowed). To use special +characters in the name of a node, you can optionally surround the +\meta{node name} and/or the \meta{text} by quotation marks. In this +case, you can use all of the special symbols once more. The details +of what happens, exactly, when the \meta{node name} is surrounded by +quotation marks is explained later; surrounding the \meta{text} by +quotation marks has essentially the same effect as surrounding it by +curly braces. + +Once the node name has been determined, it is checked whether the same +node name was already used inside the current graph. If this is the +case, then we say that the already existing node is \emph{referenced}; +otherwise we say that the node is \emph{fresh}. + +\begin{codeexample}[] +\tikz \graph { + a -> b; % both are fresh + c -> a; % only c is fresh, a is referenced +}; +\end{codeexample} + +This behaviour of deciding whether a node is fresh or referenced can, +however, be modified by using the following keys: +\begin{key}{/tikz/graphs/use existing node=\opt{\meta{true or + false}} (default true)} + When this key is set to |true|, all nodes will be considered to the + referenced, no node will be fresh. This option is useful if you have + already created all the nodes of a graph prior to using the |graph| + command and you now only wish to connect the nodes. +\end{key} +\begin{key}{/tikz/graphs/fresh nodes=\opt{\meta{true or + false}} (default true)} + When this key is set to |true|, all nodes will be considered to be + fresh. This option is useful when you create for instance a tree + with many identical nodes. + + When a node name is encountered that was already used previously, + a new name is chosen is follows: An apostrophe (|'|) is appended + repeatedly until a node name is found that has not yet been + used: +\begin{codeexample}[] +\tikz \graph [branch down=5mm] { + { [fresh nodes] + a -> { + b -> {c, c}, + b -> {c, c}, + b -> {c, c}, + } + }, + b' -- b'' +}; +\end{codeexample} +\end{key} + +When a fresh node has been detected, a new node is created in the +inside a protecting scope. For this, the current +placement strategy is asked to compute a default position for the +node, see Section~\ref{section-library-graphs-placement} for +details. Then, the command +\begin{quote} + |\node (|\meta{full node name}|) [|\meta{node options}|] {|\meta{text}|};| +\end{quote} +is called. The different parameters are as follows: +\begin{itemize} +\item + The \meta{full node name} is normally the \meta{node name} that has + been determined as described before. However, there are two exceptions: + + First, if the \meta{node name} is empty (which happens when there + is no \meta{node name} before the slash), then a fresh internal node + name is created and used as + \meta{full node name}. This name is guaranteed to be different from all + node names used in this or any other graph. Thus, a direct node + starting with a slash represents an anonymous fresh node. + + Second, you can use the following key to prefix the \meta{node name} + inside the \meta{full node name}: + + \begin{key}{/tikz/graphs/name=\meta{text}} + This key prepends the \meta{text}, followed by a separating symbol + (a space by default), to all + \meta{node name}s inside a \meta{full node name}. Repeated calls + of this key accumulate, leading to ever-longer ``name paths'': +\begin{codeexample}[] +\begin{tikzpicture} + \graph { + { [name=first] 1, 2, 3} -- + { [name=second] 1, 2, 3} + }; + \draw [red] (second 1) circle [radius=3mm]; +\end{tikzpicture} +\end{codeexample} + Note that, indeed, in the above example six nodes are created even + though the first and second set of nodes have the same \meta{node + name}. The reason is that the full names of the six nodes are + all different. Also note that only the \meta{node name} is used as + the node text, not the full name. This can be changed as described + later on. + + This key can be used repeatedly, leading to ever longer node names. + \end{key} + + \begin{key}{/tikz/graphs/name separator=\meta{symbols} (initially \string\space)} + Changes the symbol that is used to separate the \meta{text} from + the \meta{node name}. The default is |\space|, resulting in a + space. +\begin{codeexample}[] +\begin{tikzpicture} + \graph [name separator=] { % no separator + { [name=first] 1, 2, 3} -- + { [name=second] 1, 2, 3} + }; + \draw [red] (second1) circle [radius=3mm]; +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture} + \graph [name separator=-] { + { [name=first] 1, 2, 3} -- + { [name=second] 1, 2, 3} + }; + \draw [red] (second-1) circle [radius=3mm]; +\end{tikzpicture} +\end{codeexample} + \end{key} +\item + The \meta{node options} are + \begin{enumerate} + \item The options that have accumulated in calls to |nodes| from + the surrounding scopes. + \item The local \meta{options}. + \end{enumerate} + The options are executed with the path prefix |/tikz/graphs|, but + any unknown key is executed with the prefix |/tikz|. This means, in + essence, that some esoteric keys are more difficult to use inside + the options and that any key with the prefix |/tikz/graphs| will + take precedence over a key with the prefix |/tikz|. +\item The \meta{text} that is passed to the |\node| command is + computed as follows: First, you can use the following key to + directly set the \meta{text}: + \begin{key}{/tikz/graphs/as=\meta{text}} + The \meta{text} is used as the text of the node. This allows you + to provide a text for the node that differs arbitrarily from the + name of the node. + \begin{codeexample}[] +\tikz \graph { a [as=$x$] -- b [as=$y_5$] -> c [red, as={a--b}] }; + \end{codeexample} + This key always takes precedence over all of the mechanisms + described below. + \end{key} + In case the |as| key is not used, a default text + is chosen as follows: First, when a direct node specification + contains a slash (or, for historical reasons, a double underscore), + the text to the right of the slash (or double underscore) is stored + in the macro |\tikzgraphnodetext|; if + there is no slash, the \meta{node name} is stored in + |\tikzgraphnodetext|, instead. Then, the current value of the + following key is used as \meta{text}: + \begin{key}{/tikz/graphs/typeset=\meta{code}} + The macro or code stored in this key is used as the + \meta{text} if the node. Inside the \meta{code}, the following + macros are available: + \begin{command}{\tikzgraphnodetext} + This macro expands to the \meta{text} to the right of the double + underscore or slash in a direct node specification or, if there + is no slash, to the \meta{node name}. + \end{command} + \begin{command}{\tikzgraphnodename} + This macro expands to the name of the current node with the + path. + \end{command} + \begin{command}{\tikzgraphnodepath} + This macro expands to the current path of the node. These + paths result from the use of the |name| key as described above. + \end{command} + \begin{command}{\tikzgraphnodefullname} + This macro contains the concatenation of the above two. + \end{command} + \end{key} + By default, the typesetter is just set to |\tikzgraphnodetext|, + which means that the default text of a node is its name. However, + it may be useful to change this: For instance, you might wish that + the text of all graph nodes is, say, surrounded by parentheses: + \begin{codeexample}[] +\tikz \graph [typeset=(\tikzgraphnodetext)] + { a -> b -> c }; + \end{codeexample} + A more advanced macro might take apart the node text and render it + differently: + \begin{codeexample}[] +\def\mytypesetter{\expandafter\myparser\tikzgraphnodetext\relax} +\def\myparser#1 #2 #3\relax{% + $#1_{#2,\dots,#3}$ +} +\tikz \graph [typeset=\mytypesetter, grow down] + { a 1 n -> b 2 m -> c 4 nm }; + \end{codeexample} + The following styles install useful predefined typesetting macros: + \begin{key}{/tikz/graphs/empty nodes} + Just sets |typeset| to nothing, which causes all nodes to have an + empty text (unless, of course, the |as| option is used): + \begin{codeexample}[] +\tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} }; + \end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/math nodes} + Sets |typeset| to |$\tikzgraphnodetext$|, which causes all nodes + names to be typeset in math mode: + \begin{codeexample}[] +\tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} }; + \end{codeexample} + \end{key} +\end{itemize} + +If a node is referenced instead of fresh, then this node becomes the +node that will be connected by the preceding or following edge +specification to other +nodes. The \meta{options} are executed even for a referenced node, but +they cannot be used to change the appearance of the node (because the +node exists already). Rather, the \meta{options} can only be used to +change the logical coloring of the node, see +Section~\ref{section-library-graphs-color-classes} for details. + +\medskip +\textbf{Quoted Node Names.} When the \meta{node name} and/or the +\meta{text} of a node is surrounded by quotation marks, you can use +all sorts of special symbols as part of the text that are +normally forbidden: +\begin{codeexample}[] +\begin{tikzpicture} + \graph [grow right=2cm] { + "Hi, World!" -> "It's \emph{important}!"[red,rotate=-45]; + "name"/actual text -> "It's \emph{important}!"; + }; + \draw (name) circle [radius=3pt]; +\end{tikzpicture} +\end{codeexample} + +In detail, for the following happens when qutation marks are +encountered at the beginning of a node name or its text: +\begin{itemize} +\item Everything following the quotation mark up to the next single + quotation mark is collected into a macro \meta{collected}. All sorts + of special characters, including commas, square brackets, dashes, + and even backslashes are allowed here. Basically, the only + restriction is that braces must be balanced. +\item A double quotation mark (|""|) does not count as the ``next + single quotation mark.'' Rather, it is replaced by a single + quotation mark. For instance, |"He said, ""Hello world."""| would be + stored inside \meta{collected} as |He said, "Hello world."| + However, this rule applies only on the outer-most level of + braces. Thus, in +\begin{codeexample}[code only] +"He {said, ""Hello world.""}" +\end{codeexample} + we would get |He {said, ""Hello world.""}| as \meta{collected}. +\item ``The next single quotation mark'' refers to the next + quotation mark on the current level of braces, so in + |"hello {"} world"|, the next quotation mark would be the one + following |world|. +\end{itemize} + +Now, once the \meta{collected} text has been gather, it is used as +follows: When used as \meta{text} (what is actually displayed), it is +just used ``as is''. When it is used as \meta{node name}, however, the +following happens: Every ``special character'' in \meta{collected} is +replaced by its Unicode name, surrounded by |@|-signs. For instance, +if \meta{collected} is |Hello, world!|, the \meta{node name} is the +somewhat longer text |Hello@COMMA@ world@EXCLAMATION MARK@|. Admittedly, +referencing such a node from outside the graph is +cumbersome, but when you use exactly the same \meta{collected} text +once more, the same \meta{node name} will result. The +following characters are considered ``special'': +\begin{quote} + \texttt{\char`\|}|$&^~_[](){}/.-,+*'`!":;<=>?@#%\{}|%$ +\end{quote} +These are exactly the Unicode character with a decimal code number +between 33 and 126 that are neither digits nor letters. + + +\medskip +\textbf{Reference Node Specifications.} A reference node specification +is a node specification that starts with an opening parenthesis. In +this case, parentheses must surround a \meta{name} as in |(foo)|, +where |foo| is the \meta{name}. The following will now happen: + +\begin{enumerate} +\item It is tested whether \meta{name} is the name of a currently + active \emph{node set}. This case will be discussed in a moment. +\item Otherwise, the \meta{name} is interpreted and treated as a + referenced node, but independently of whether the node has already + been fresh in the current graph or not. In other words, the node + must have been defined either already inside the graph (in which + case the parenthesis are more or less superfluous) or it must have + been defined outside the current picture. + + The way the referenced node is handled is the same way as for a + direct node that is a referenced node. + + If the node does not already exist, an error message is printed. +\end{enumerate} + +Let us now have a look at node sets. Inside a |{tikzpicture}| you can +locally define a \emph{node set} by using the following key: +\begin{key}{/tikz/new set=\meta{set name}} + This will setup a node set named \meta{set name} within the current + scope. Inside the scope, you can add nodes to the node set using the + |set| key. If a node set of the same name already exists in the + current scope, it will be reset and made empty for the current + scope. + + Note that this command has the path |/tikz| and is normally used + \emph{outside} the |graph| command. +\end{key} +\begin{key}{/tikz/set=\meta{set name}} + This key can be used as an option with a |node| command. The + \meta{set name} must be the name of a node set that has previously + been created inside some enclosing scope via the |new set| key. The + effect is that the current node is added to the node set. +\end{key} + +When you use a |graph| command inside a scope where some node set +called \meta{set name} is defined, then inside this |graph| command +you use |(|\meta{set name}|)| to reference \emph{all} of the nodes in +the node set. The effect is the same as if instead of the reference to +the set name you had created a group specification containing a list +of references to all the nodes that are part of the node set. + +\begin{codeexample}[] +\begin{tikzpicture}[new set=red, new set=green, shorten >=2pt] + \foreach \i in {1,2,3} { + \node [draw, red!80, set=red] (r\i) at (\i,1) {$r_\i$}; + \node [draw, green!50!black, set=green] (g\i) at (\i,2) {$g_\i$}; + } + \graph { + root [xshift=2cm] -> + (red) -> [complete bipartite, right anchor=south] + (green) + }; +\end{tikzpicture} +\end{codeexample} + +There is an interesting caveat with referencing node sets: Suppose +that at the beginning of a graph you just say |(foo);| where |foo| is +a set name. Unless you have specified special options, this will cause +the following to happen: A group is created whose members are all the +nodes of the node set |foo|. These nodes become referenced nodes, but +otherwise nothing happens since, by default, the nodes of a group are +not connected automatically. However, the referenced nodes have now +been referenced inside the graph, you can thus subsequently access +them as if they had been defined inside the graph. Here is an example +showing how you can create nodes outside a |graph| command and then +connect them inside as if they had been declared inside: + +\begin{codeexample}[] +\begin{tikzpicture}[new set=import nodes] + \begin{scope}[nodes={set=import nodes}] % make all nodes part of this set + \node [red] (a) at (0,1) {$a$}; + \node [red] (b) at (1,1) {$b$}; + \node [red] (d) at (2,1) {$d$}; + \end{scope} + + \graph { + (import nodes); % "import" the nodes + + a -> b -> c -> d -> e; % only c and e are new + }; +\end{tikzpicture} +\end{codeexample} + + +\medskip +\textbf{Group Node Specifications.} +At a place where a node specification should go, you can also instead +provide a group specification. Since nodes specifications are part of +chain specifications, which in turn are part of group specifications, +this is a recursive definition. + +\begin{codeexample}[] +\tikz \graph { a -> {b,c,d} -> {e -> {f,g}, h} }; +\end{codeexample} + +As can be seen in the above example, when two groups of nodes are +connected via an edge specification, it is not immediately obvious +which connecting edges are added. This is detailed in +Section~\ref{section-library-graphs-color-classes}. + + + +\subsubsection{Specifying Tries} + +In computer science, a \emph{trie} is a special kind of tree, where +for each node and each symbol of an alphabet, there is at most one +child of the node labeled with this symbol. + +The |trie| key is useful for drawing tries, but it can also be used in +other situations. What it does, essentially, is to prepend the node +names of all nodes \emph{before} the current node of the current chain +to the node's name. This will often make it easier or more natural to +specify graphs in which several nodes have the same label. + +\begin{key}{/tikz/graphs/trie=\opt{\meta{true or false}} (default true, initially false)} + If this key is set to |true|, after a node has been created on a + chain, the |name| key is executed with the node's \meta{node + name}. Thus, all nodes later on this chain have the ``path'' of + nodes leading to this node as their name. This means, in particular, + that + \begin{enumerate} + \item two nodes of the same name but in different parts of a chain + will be different, + \item while if another chain starts with the same nodes, no new + nodes get created. + \end{enumerate} + In total, this is exactly the behaviour you would expect of a trie: +\begin{codeexample}[] +\tikz \graph [trie] { + a -> { + a, + c -> {a, b}, + b + } +}; +\end{codeexample} + You can even ``reiterate'' over a path in conjunction with the + |simple| option. However, in this case, the default placement + strategies will not work and you will need options like + |layered layout| from the graph drawing libraries, which need + Lua\TeX. +\ifluatex +\begin{codeexample}[] +\tikz \graph [trie, simple, layered layout] { + a -> b -> a, + a -> b -> c, + a -> {d,a} +}; +\end{codeexample} + In the following example, we setup the |typeset| key so that it + shows the complete names of the nodes: +\begin{codeexample}[] +\tikz \graph [trie, simple, layered layout, + typeset=\tikzgraphnodefullname] { + a -> b -> a, + a -> b -> c, + a -> {d,a} +}; +\end{codeexample} +\fi + You can also use the |trie| key locally and later reference nodes + using their full name: +\begin{codeexample}[] +\tikz \graph { + { [trie, simple] + a -> { + b, + c -> a + } + }, + a b ->[red] a c a +}; +\end{codeexample} +\end{key} + + +\subsection{Quick Graphs} + +\label{section-library-graphs-quick} + +The graph syntax is powerful, but this power comes at a price: parsing +the graph syntax, which is done by \TeX, can take some time. Normally, +the parsing is fast enough that you will not notice it, but it can be +bothersome when you have graphs with hundreds of nodes as happens +frequently when nodes are generated algorithmically by some other +program. Fortunately, when another program generated a graph +specification, we typically do not need the full power of the graph +syntax. Rather, a small subset of the graph syntax would suffice that +allows to specify nodes and edges. For these reasons, the is a special +``quick'' version of the graph syntax. + +Note, however, that using this syntax will usually at most halve the +time needed to parse a graph. Thus, it really mostly makes sense in +conjunction with large, algorithmically generated graphs. + +\begin{key}{/tikz/graphs/quick} + When you provide this key with a graph, the syntax of graph + specifications gets restricted. You are no longer allowed to use + certain features of the graph syntax; but all features that are + still allowed are also allowed in the same way when you do not + provide the |quick| option. Thus, leaving out the |quick| option + will never hurt. + + Since the syntax is so severely restricted, it is easier to explain + which aspects of the graph syntax \emph{will} still work: + + \begin{enumerate} + \item + A quick graph consists of a sequence of either nodes, edges sequences, or + groups. These are separated by commas or semicolons. + \item + Every node is of the form + + \begin{quote} + |"|\meta{node name}|"|\opt{|/"|\meta{node text}|"[|\meta{options}|]|} + \end{quote} + + The quotation marks are mandatory. The part |/"|\meta{node + text}|"| may be missing, in which case the node name is used as + the node text. The \meta{options} may also be missing. The + \meta{node name} may not contain any ``funny'' characters (unlike + in the normal graph command). + \item + Every chain is of the form + + \begin{quote} + \meta{node spec} \meta{connector} \meta{node spec} + \meta{connector} \dots \meta{connector} \meta{node spec}|;| + \end{quote} + + Here, the \meta{node spec} are node specifications as described + above, the \meta{connector} is one of the four connectors |->|, + |<-|, |--|, and |<->| (the connector |-!-| is not allowed since + the |simple| option is also not allowed). Each connector may be + followed by options in square brackets. The semicolon may be + replaced by a comma. + \item + Every group is of the form + + \begin{quote} + |{ [|\meta{options}|]| \meta{chains and groups} |};| + \end{quote} + The \meta{options} are compulsory. The semicolon can, again, be + replaced by a comma. + \end{enumerate} + + Here is a typical way this syntax might be used: +\begin{codeexample}[] +\tikz \graph [quick] { "a" --["foo"] "b"[x=1] }; +\end{codeexample} + +\begin{codeexample}[] +\tikz \graph [quick] { + "a"/"$a$" -- "b"[x=1] --[red] "c"[x=2]; + { [nodes=blue] "a" -- "d"[y=1]; }; +}; +\end{codeexample} + + Let us now have a look at the most important things that will + \emph{not} work when the |quick| option is used: + + \begin{itemize} + \item Connecting a node and a group as in |a->{b,c}|. + \item Node names without quotation marks as in |a--b|. + \item Everything described in subsequent subsections, which includes + subgraphs (graph macros), graph sets, graph color classes, + anonymous nodes, the |fresh nodes| option, sublayouts, simple + graphs, edge annotations. + \item Placement strategies -- you either have to define all node + positions explicitly using |at=| or |x=| and |y=| or you must use + a graph drawing algorithm like |layered layout|. + \end{itemize} +\end{key} + + +\subsection{Simple Versus Multi-Graphs} + +\label{section-library-graphs-simple} + +The |graph| library allows you to construct both simple graphs and +multi-graphs. In a simple graph there can be at most one edge between +any two vertices, while in a multi-graph there can be multiple edges +(hence the name). The two keys |multi| and |simple| allow you to +switch (even locally inside on of the graph's scopes) between which +kind of graph is being constructed. By default, the |graph| command +produces a multi-graph since these are faster to construct. + +\begin{key}{/tikz/graphs/multi} + When this edge is set for a whole graph (which is the default) or + just for a group (which is useful if the whole graph is simple in + general, but a part is a multi-graph), then when you specify an edge + between two nodes several times, several such edges get created: + +\begin{codeexample}[] +\tikz \graph [multi] { % "multi" is not really necessary here + a ->[bend left, red] b; + a ->[bend right, blue] b; +}; +\end{codeexample} + In case |multi| is used for a scope inside a larger scope where the + |simple| option is specified, then inside the local |multi| scope + edges are immediately created and they are completely ignored when + it comes to deciding which kind of edges should be present in the + surrounding simple graph. From the surrounding scope's point of view + it is as if the local |multi| graph contained no edges at all. + + This means, in particular, that you can use the |multi| option with + a single edge to ``enforce'' this edge to be present in a simple + graph. +\end{key} + +\begin{key}{/tikz/graphs/simple} + In contrast a multi-graph, in a simple graph, at most one edge gets + created for every pair of vertices: +\begin{codeexample}[] +\tikz \graph [simple]{ + a ->[bend left, red] b; + a ->[bend right, blue] b; +}; +\end{codeexample} + As can be seen, the second edge ``wins'' over the first edge. The + general rule is as follows: In a simple graph, whenever an edge + between two vertices is specified multiple times, only the very last + specification and its options will actually be executed. + + The real power of the |simple| option lies in the fact that you can + first create a complicated graph and then later redirect and otherwise + modify edges easily: + +\begin{codeexample}[] +\tikz \graph [simple, grow right=2cm] { + {a,b,c,d} ->[complete bipartite] {e,f,g,h}; + + { [edges={red,thick}] a -> e -> d -> g -> a }; +}; +\end{codeexample} + + One particularly interesting kind of edge specification for a simple + graph is |-!-|. Recall that this is used to indicate that ``no + edge'' should be added between certain nodes. In a multi-graph, this + key usually has no effect (unless the key |new -!-| has been + redefined) and is pretty superfluous. In a simple graph, however, it + counts as an edge kind and you can thus use it to remove an edge + that been added previously: + +\begin{codeexample}[] +\tikz \graph [simple] { + subgraph K_n [n=8, clockwise]; + % Get rid of the following edges: + 1 -!- 2; + 3 -!- 4; + 6 -!- 8; + % And make one edge red: + 1 --[red] 3; +}; +\end{codeexample} + + Creating a graph such as the above in other fashions is pretty + awkward. + + For every unordered pair $\{u,v\}$ of vertices at most one edge will + be created in a simple graph. In particular, when you say |a -> b| + and later also |a <- b|, then only the edge |a <- b| will be + created. Similarly, when you say |a -> b| and later |b -> a|, then + only the edge |b -> a| will be created. + + The power of the |simple| command comes at a certain cost: As the + graph is being constructed, a (sparse) array is created that keeps + track for each edge of the last edge being specified. Then, at the + end of the scope containing the |simple| command, for every pair of + vertices the edge is created. This is implemented by two nested + loops iterating over all possible pairs of vertices -- which may + take quite a while in a graph of, say, 1000 vertices. + Internally, the |simple| command is implemented as an operator that + adds the edges when it is called, but + this should be unimportant in normal situations. +\end{key} + + + + +\subsection{Graph Edges: Labeling and Styling} + +When the |graph| library creates an edge between two nodes in a graph, +the appearance (called ``styling'' in \tikzname) can be specified in +different ways. Sometimes you will simply wish to say ``the edges +between these two groups of node should be red,'' but sometimes you +may wish to say ``this particular edge going into this node should be +red.'' In the following, different ways of specifying such styling +requirements are discussed. Note that adding labels to edges is, from +\tikzname's point of view, almost the same as styling edges, since +they are also specified using options. + + +\subsubsection{Options For All Edges Between Two Groups} + +When you write |... ->[options] ...| somewhere inside your graph +specification, this typically cause one or more edges to be created +between the nodes in the chain group before the |->| and the nodes in +the chain group following it. The |options| are applied to all of +them. In particular, if you use the |quotes| library and you write +some text in quotes inside the |options|, this text will be added as a +label to each edge: + +\begin{codeexample}[] +\tikz + \graph [edge quotes=near start] { + { a, b } -> [red, "x", complete bipartite] { c, d }; + }; +\end{codeexample} + +As documented in the |quotes| library in more detail, you can easily +modify the appearance of edge labels created using the quotes syntax +by adding options after the closing quotes: + +\begin{codeexample}[] +\tikz \graph { + a ->["x"] b ->["y"'] c ->["z" red] d; +}; +\end{codeexample} + +The following options make it easy to setup the styling of nodes +created in this way: + +\begin{key}{/tikz/graphs/edge quotes=\opt{\meta{options}}} + A shorthand for setting the style |every edge quotes| to \meta{options}. +\begin{codeexample}[] + \tikz \graph [edge quotes={blue,auto}] { + a ->["x"] b ->["y"'] c ->["b" red] d; +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/edge quotes center} + A shorthand for |edge quotes| to |anchor=center|. +\begin{codeexample}[] +\tikz \graph [edge quotes center] { + a ->["x"] b ->["y"] c ->["z" red] d; +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/edge quotes mid} + A shorthand for |edge quotes| to |anchor=mid|. +\begin{codeexample}[] +\tikz \graph [edge quotes mid] { + a ->["x"] b ->["y"] c ->["z" red] d; +}; +\end{codeexample} +\end{key} + + + +\subsubsection{Changing Options For Certain Edges} + + +Consider the following tree-like graph: + +\begin{codeexample}[] +\tikz \graph { a -> {b,c} }; +\end{codeexample} + +Suppose we wish to specify that the edge from |a| to |b| should be +red, while the edge from |a| to |c| should be blue. The difficulty +lies in the fact that \emph{both} edges are created by the single |->| +operator and we can only add one of these option |red| or |blue| to +the operator. + +There are several ways to solve this problem. First, we can simply +split up the specification and specify the two edges separately: + +\begin{codeexample}[] +\tikz \graph { + a -> [red] b; + a -> [blue] c; +}; +\end{codeexample} +While this works quite well, we can no longer use the nice chain group +syntax of the |graphs| library. For the rather simple graph |a->{b,c}| +this is not a big problem, but if you specify a tree with, say, 30 +nodes it is really worthwhile being able to specify the tree ``in its +natural form in the \TeX\ code'' rather than having to list all of the +edges explicitly. Also, as can be seen in the above example, the +node placement is changed, which is not always desirable. + +One can sidestep this problem using the |simple| option: This option +allows you to first specify a graph and then, later on, replace edges +by other edges and, thereby, provide new options: + +\begin{codeexample}[] +\tikz \graph [simple] { + a -> {b,c}; + a -> [red] b; + a -> [blue] c; +}; +\end{codeexample} + +The first line is the original specification of the tree, while the +following two lines replace some edges of the tree (in this case, all +of them) by edges with special options. While this method is slower +and in the above example creates even longer code, it is very useful +if you wish to, say, highlight a path in a larger tree: First specify +the tree normally and, then, ``respecify'' the path or paths with some +other edge options in force. In the following example, we use this to +highlight a whole subtree of a larger tree: + +\begin{codeexample}[] +\tikz \graph [simple] { + % The larger tree, no special options in force + a -> { + b -> {c,d}, + e -> {f,g}, + h + }, + { [edges=red] % Now highlight a part of the tree + a -> e -> {f,g} + } +}; +\end{codeexample} + + + +\subsubsection{Options For Incoming and Outgoing Edges} + +When you use the syntax |... ->[options] ...| to specify options, you +specify options for the ``connections between two sets of nodes''. In +many cases, however, it will be more natural to specify options ``for +the edges lead to or coming from a certain node'' and you will want to +specify these options ``at the node''. Returning to the example of the +graph |a->{b,c}| where we want a red edge between |a| and |b| and a +blue edge between |a| and |c|, this could also be phrased as follows: +``Make the edge leading to |b| red and make the edge leading to |c| +blue.'' + +For this situation, the |graph| library offers a number of special +keys, which are documented in the following. However, most of the time +you will not use these keys directly, but, rather, use a special +syntax explained in Section~\ref{section-syntax-outgoing-incoming}. + +\begin{key}{/tikz/graphs/target edge style=\meta{options}} + This key can (only) be used with a \emph{node} inside a graph + specification. When used, the \meta{options} will be added to every + edge that is created by a connector like |->| in which the node is a + \emph{target}. Consider the following example: +\begin{codeexample}[] +\tikz \graph { + { a, b } -> + { c [target edge style=red], d } -> + { e, f } +}; +\end{codeexample} + In the example, only when the edge from |a| to |c| is created, |c| + is the ``target'' of the edge. Thus, only this edge becomes red. + + When an edge already has options set directly, the \meta{options} + are executed after these direct options, thus, they ``overrule'' + them: +\begin{codeexample}[] +\tikz \graph { + { a, b } -> [blue, thick] + { c [target edge style=red], d } -> + { e, f } +}; +\end{codeexample} + + The \meta{options} set in this way will stay attached to the node, + so also for edges created later on that lead to the node will have + these options set: +\begin{codeexample}[] +\tikz \graph { + { a, b } -> + { c [target edge style=red], d } -> + { e, f }, + b -> c +}; +\end{codeexample} + + Multiple uses of this key accumulate. However, you may sometimes + also wish to ``clear'' these options for a key since at some later + point you no longer wish the \meta{options} to be added when some + further edges are added. This can be achieved using the following + key: + \begin{key}{/tikz/graphs/target edge clear} + Clears all \meta{options} for edges with the node as a target and + also edge labels (see below) for this node. + \end{key} +\begin{codeexample}[] +\tikz \graph { + { a, b } -> + { c [target edge style=red], d }, + b -> c[target edge clear] +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/target edge node=\meta{node specification}} + This key works like |target edge style|, only the \meta{node + specification} will not be added as options to any newly created + edges with the current node as their target, but rather it will be + added as a node specification. +\begin{codeexample}[] +\tikz \graph { + { a, b } -> + { c [target edge node=node{X}], d } -> + { e, f } +}; +\end{codeexample} + As for |target edge style| multiple uses of this key accumulate and + the key |target edge clear| will (also) clear all target edge nodes + that have been set for a node earlier on. +\end{key} + +\begin{key}{/tikz/graphs/source edge style=\meta{options}} + Works exactly like |target edge style|, only now the \meta{options} + are only added when the node is a source of a newly created edge: +\begin{codeexample}[] +\tikz \graph { + { a, b } -> + { c [source edge style=red], d } -> + { e, f } +}; +\end{codeexample} + If both for the source and also for the target of an edge + \meta{options} have been specified, the options are applied in the + following order: + \begin{enumerate} + \item First come the options from the edge itself. + \item Then come the options contributed by the source node using + this key. + \item Then come the options contributed by the target node using + |target node style|. + \end{enumerate} +\begin{codeexample}[] +\tikz \graph { + a [source edge style=red] ->[green] + b [target edge style=blue] % blue wins +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/source edge node=\meta{node specification}} + Works like |source edge style| and |target edge node|. +\end{key} + +\begin{key}{/tikz/graphs/source edge clear=\meta{node specification}} + Works like |target edge clear|. +\end{key} + + + +\subsubsection{Special Syntax for Options For Incoming and Outgoing Edges} +\label{section-syntax-outgoing-incoming} + +The keys |target node style| and its friends are powerful, but a bit +cumbersome to write down. For this reason, the |graphs| library +introduces a special syntax that is based on what I call the +``first-char syntax'' of keys. Inside the options of a node inside a +graph, the following special rules apply: +\begin{enumerate} +\item Whenever an option starts with |>|, the rest of the options are + passed to |target edge style|. For instance, when you write + |a[>red]|, then this has the same effect as if you had written +\begin{codeexample}[code only] +a[target edge style={red}] +\end{codeexample} +\item Whenever an options starts with |<|, the rest of the options are + passed to |source edge style|. +\item In both of the above case, in case the options following the |>| + or |<| sign start with a quote, the created edge label is passed to + |source edge node| or |target edge node|, respectively. + + This is exactly what you want to happen. +\end{enumerate} +Additionally, the following styles provide shorthands for ``clearing'' +the target and source options: +\begin{key}{/tikz/graphs/clear >} + A more easy-to-remember shorthand for |target edge clear|. +\end{key} +\begin{key}{/tikz/graphs/clear <} + A more easy-to-remember shorthand for |source edge clear|. +\end{key} + +These mechanisms make it especially easy to create trees in which the +edges are labeled in some special way: +\begin{codeexample}[] +\tikz + \graph [edge quotes={fill=white,inner sep=1pt}, + grow down, branch right] { + / -> h [>"9"] -> { + c [>"4" text=red,] -> { + a [>"2", >thick], + e [>"0"] + }, + j [>"7"] + } + }; +\end{codeexample} + + +\subsubsection{Placing Node Texts on Incoming Edges} + +Normally, the text of a node is shown (only) inside the node. In some +case, for instance when drawing certain kind of trees, the nodes +themselves should not get any text, but rather the edge leading to the +node should be labeled as in the following example: +\begin{codeexample}[] +\tikz \graph [empty nodes] +{ + root -> { + a [>"a"], + b [>"b"] -> { + c [>"c"], + d [>"d"] + } + } +}; +\end{codeexample} +As the example shows, it is a bit cumbersome that we have to label the +nodes and then specify the same text once more using the incoming edge +syntax. + +For these cases, it would be better if the text of the node where not +used with the node but, rather, be passed directly to the incoming or +the outgoing edge. The following styles do exactly this: + +\begin{key}{/tikz/graphs/put node text on incoming edges=\opt{\meta{options}}} + When this key is used with a node or a group, the following happens: + \begin{enumerate} + \item The command |target edge node={node[|\meta{options}|]{\tikzgraphnodetext}}| + is executed. This means that all incoming edges of the node get a + label with the text that would usually be displayed in the + node. You can use keys like |math nodes| normally. + \item The command |as={}| is executed. This means that the node + itself will display nothing. + \end{enumerate} + Here is an example that show how this command is used. +\begin{codeexample}[] +\tikz \graph [put node text on incoming edges, + math nodes, nodes={circle,draw}] + { a -> b -> {c, d} }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/put node text on outgoing + edges=\opt{\meta{options}}} + Works like the previous key, only with |target| replaced by |source|. +\end{key} + + + +\subsection{Graph Operators, Color Classes, and Graph Expressions} +\label{section-library-graphs-color-classes} + +\tikzname's |graph| command employs a powerful mechanism for +adding edges between nodes and sets of nodes. To a graph theorist, +this mechanism may be known as a \emph{graph expression}: A graph is +specified by starting with small graphs and then applying +\emph{operators} to them that form larger graphs and that connect and +recolor colored subsets of the graph's node in different ways. + + +\subsubsection{Color Classes} + +\label{section-library-graph-coloring} + +\tikzname\ keeps track of a \emph{(multi)coloring} of the graph as it +is being constructed. This does not mean that the +actual color of the nodes on the page will be different, rather, in +the following we refer to ``logical'' colors in the way graph +theoreticians do. These ``logical'' colors are only important while +the graph is being constructed and they are ``thrown away'' at the end +of the construction. The actual (``physical'') colors of the nodes are +set independently of these logical colors. + +As a graph is being constructed, each node can be part of one or more +overlapping \emph{color classes}. So, unlike what is sometimes called a +\emph{legal coloring}, the logical colorings that \tikzname\ keeps +track of may assign multiple colors to the same node and two nodes +connected by an edge may well have the same color. + +Color classes must be declared prior to use. This is done using the +following key: +\begin{key}{/tikz/graphs/color class=\meta{color class name}} + This sets up a new color class called \meta{color class name}. Nodes + and whole groups of nodes can now be colored with \meta{color class + name}. This is done using the following keys, which become + available inside the current scope: + \begin{key}{/tikz/graphs/\meta{color class name}} + This key internally uses the |operator| command to setup an + operator that will cause all nodes of the current group to get the + ``logical color'' \meta{color class name}. Nodes retain this color + in all encompassing scopes, unless it is explicitly changed (see + below) or unset (again, see below). +\begin{codeexample}[] +\tikz \graph [color class=red] { + [cycle=red] % causes all "logically" red nodes to be connected in + % a cycle + a, + b [red], + { [red] c ->[bend right] d }, + e +}; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [color class=red, color class=green, + math nodes, clockwise, n=5] { + [complete bipartite={red}{green}] + { [red] r_1, r_2 }, + { [green] g_1, g_2, g_3 } +}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/not \meta{color class name}} + Sets up an operator for the current scope so that all nodes in it + loose the color \meta{color class name}. You can also use + |!|\meta{color class name} as an alias for this key. +\begin{codeexample}[] +\tikz \graph [color class=red, color class=green, + math nodes, clockwise, n=5] { + [complete bipartite={red}{green}] + { [red] r_1, r_2 }, + { [green] g_1, g_2, g_3 }, + g_2 [recolor green by=red] +}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/recolor \meta{color class name} by=\meta{new color}} + Causes all keys having color \meta{color class name} to get + \meta{new color} instead. They loose having color \meta{color + class name}, but other colors are not affected. +\begin{codeexample}[] +\tikz \graph [color class=red, color class=green, + math nodes, clockwise, n=5] { + [complete bipartite={red}{green}] + { [red] r_1, r_2 }, + { [green] g_1, g_2, g_3 }, + g_2 [not green] +}; +\end{codeexample} + \end{key} +\end{key} + +The following color classes are available by default: +\begin{itemize} +\item + Color class |all|. Every node is part of this class by default. This + is useful to access all nodes of a (sub)graph, since you can simply + access all nodes of this color class. +\item + Color classes |source| and |target|. These classes are used to + identify nodes that lead ``into'' a group of nodes and nodes from + which paths should ``leave'' the group. Details on how these colors + are assigned are explained in + Section~\ref{section-library-graphs-join}. By saying |not source| or + |not target| with a node, you can influence how it is connected: + \begin{codeexample}[] +\tikz \graph { a -> { b, c, d } -> e }; + \end{codeexample} + \begin{codeexample}[] +\tikz \graph { a -> { b[not source], c, d[not target] } -> e }; + \end{codeexample} +\item + Color classes |source'| and |target'|. These are temporary colors + that are also explained in + Section~\ref{section-library-graphs-join}. +\end{itemize} + + + +\subsubsection{Graph Operators on Groups of Nodes} + +Recall that the |graph| command constructs graphs recursively from +nested \meta{group specifications}. Each such \meta{group + specification} describes a subset of the nodes of the final graph. A +\emph{graph operator} is an algorithm that gets the nodes of a group +as input and (typically) adds edges between these nodes in some +sensible way. For instance, the |clique| operator will simply add +edges between all nodes of the group. + +\begin{key}{/tikz/graphs/operator=\meta{code}} + This key has an effect in three places: + \begin{enumerate} + \item It can be used in the \meta{options} of a \meta{direct node specification}. + \item It can be used in the \meta{options} of a \meta{group + specification}. + \item It can be used in the \meta{options} of an \meta{edge specification}. + \end{enumerate} + The first case is a special case of the second, since it is treated + like a group specification containing a single node. The last case + is more complicated and discussed in the next section. + So, let us focus on the second case. + + Even though the \meta{options} of a group are given at the beginning + of the \meta{group specification}, the \meta{code} is only executed + when the group has been parsed completely and all its nodes have + been identified. If you use the |operator| multiple times in the + \meta{options}, the effect accumulates, that is, all code passed to + the different calls of |operator| gets executed in the order it is + encountered. + + The \meta{code} can do ``whatever it wants,'' but it will typically + add edges between certain nodes. You can configure what kind of + edges (directed, undirected, etc.) are created by using the + following keys: + \begin{key}{/tikz/graphs/default edge kind=\meta{value} (initially --)} + This key stores one of the five edge kinds |--|, |<-|, |->|, + |<->|, and |-!-|. When an operator wishes to create a new edge, it + should typically set +\begin{codeexample}[code only] +\tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...} +\end{codeexample} + While this key can be set explicitly, it may be more convenient to + use the abbreviating keys listed below. Also, this key is + automatically set to the current value of \meta{edge + specification} when a joining operator is called, see the + discussion of joining operators in + Section~\ref{section-library-graphs-join}. + \end{key} + \begin{key}{/tikz/graphs/--} + Sets the |default edge kind| to |--|. +\begin{codeexample}[] +\tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] }; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/->} + Sets the |default edge kind| to |->|. +\begin{codeexample}[] +\tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] }; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/<-} + Sets the |default edge kind| to |<-|. +\begin{codeexample}[] +\tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] }; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/<->} + Sets the |default edge kind| to |<->|. +\begin{codeexample}[] +\tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] }; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/-\protect\exclamationmarktext-} + Sets the |default edge kind| to |-!-|. + \end{key} + + When the \meta{code} of an operator is executed, the following + commands can be used to find the nodes that should be connected: + \begin{command}{\tikzgraphforeachcolorednode\marg{color name}\marg{macro}} + When this command is called inside \meta{code}, the following will + happen: \tikzname\ will iterate over all nodes inside the + just-specified group that have the color \meta{color name}. The + order in which they are iterated over is the order in which they + appear inside the group specification (if a node is encountered + several times inside the specification, only the first occurrence + counts). Then, for each node the \meta{macro} is executed with the + node's name as the only argument. + + In the following example we use an operator to connect every + node colored |all| inside the subgroup to he node |root|. + \begin{codeexample}[] +\def\myconnect#1{\tikzset{graphs/new ->={root}{#1}{}{}}} + +\begin{tikzpicture} + \node (root) at (-1,-1) {root}; + + \graph { + x, + { + [operator=\tikzgraphforeachcolorednode{all}{\myconnect}] + a, b, c + } + }; +\end{tikzpicture} + \end{codeexample} + \end{command} + + \begin{command}{\tikzgraphpreparecolor\marg{color + name}\marg{counter}\marg{prefix}} + This command is used to ``prepare'' the nodes of a certain color + for random access. The effect is the following: It is counted how + many nodes there are having color \meta{color name} in the current + group and the result is stored in \meta{counter}. Next, macros + named \meta{prefix}|1|, \meta{prefix}|2|, and so on are defined, + that store the names of the first, second, third, and so on node + having the color \meta{color name}. + + The net effect is that after you have prepared a color, you can + quickly iterate over them. This is especially useful when you + iterate over several color at the same time. + + As an example, let us create an operator then adds a zig-zag path + between two color classes: + \begin{codeexample}[] +\newcount\leftshorecount \newcount\rightshorecount +\newcount\mycount \newcount\myothercount +\def\zigzag{ + \tikzgraphpreparecolor{left shore}\leftshorecount{left shore prefix} + \tikzgraphpreparecolor{right shore}\rightshorecount{right shore prefix} + \mycount=0\relax + \loop + \advance\mycount by 1\relax% + % Add the "forward" edge + \tikzgraphsset{new ->= + {\csname left shore prefix\the\mycount\endcsname} + {\csname right shore prefix\the\mycount\endcsname}{}{}} + \myothercount=\mycount\relax% + \advance\myothercount by1\relax% + \tikzgraphsset{new <-= + {\csname left shore prefix\the\myothercount\endcsname} + {\csname right shore prefix\the\mycount\endcsname}{}{}} + \ifnum\myothercount<\leftshorecount\relax + \repeat +} +\begin{tikzpicture} + \graph [color class=left shore, color class=right shore] + { [operator=\zigzag] + { [left shore, Cartesian placement] a, b, c }, + { [right shore, Cartesian placement, nodes={xshift=1cm}] d, e, f } + }; +\end{tikzpicture} +\end{codeexample} + Naturally, in order to turn the above code into a usable operator, + some more code would be needed (like default values and taking + care of shores of different sizes). + \end{command} +\end{key} + +There are a number of predefined operators, like |clique| or |cycle|, +see the reference Section~\ref{section-library-graphs-reference} for a +complete list. + + + +\subsubsection{Graph Operators for Joining Groups} +\label{section-library-graphs-join} + +When you join two nodes |foo| and |bar| by the edge specification +|->|, it is fairly obvious, what should happen: An edge from |(foo)| +to |(bar)| should be created. However, suppose we use an edge +specification between two node sets like |{a,b,c}| and |{d,e,f}|. In +this case, it is not so clear which edges should be created. One might +argue that all possible edges from any node in the first set to any node +in the second set should be added. On the other hand, one might also +argue that only a matching between these two sets should be +created. Things get even more muddy when a longer chain of node sets +are joined. + +Instead of fixing how edges are created between two node sets, +\tikzname\ takes a somewhat more general, but also more complicated +approach, which can be broken into two parts. In the following, assume +that the following chain specification is given: +\begin{quote} + \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$} +\end{quote} +An example might be |{a,b,c} -> {d, e->f}|. + +\medskip +\textbf{The source and target vertices.} Let us start with the +question of which vertices of the first node set should be connected to +vertices in the second node set. + +There are two predefined special color classes that are used for this: +|source| and |target|. For every group specification, some vertices +are colored as |source| vertices and some vertices are |target| +vertices (a node can both be a target and a source). Initially, every +vertex is both a source and a target, but that can change as we will +see in a moment. + +The intuition behind source and target vertices is that, in some +sense, edges ``from the outside'' lead into the group via the source +vertices and lead out of the group via the target vertices. To be more +precise, the following happens: +\begin{enumerate} +\item The target vertices of the first group are connected to + the source vertices of the second group. +\item In the group resulting from the union of the nodes from + \meta{spec$_1$} and \meta{spec$_2$}, the source vertices are only + those from the first group, and the target vertices are only those + from the second group. +\end{enumerate} + +Let us go over the effect of these rules for the example +|{a,b,c} -> {d, e->f}|. First, each individual node is initially both +a |source| and a |target| vertex. Then, in |{a,b,c}| all nodes are +still both source and target vertices since just grouping vertices +does not change their colors. Now, in |e->f| something interesting +happens for the first time: the target vertices of the ``group'' |e| +(which is just the node |e|) are connected to the source vertices of +the ``group'' |f|. This means, that an edge is added from |e| to +|f|. Then, in the resulting group |e->f| the only source vertex is |e| +and the only target vertex is |f|. This implies that in the group +|{d,e->f}| the sources are |d| and |e| and the targets are |d| and~|f|. + +Now, in |{a,b,c} -> {d,e->f}| the targets of |{a,b,c}| (which are all +three of them) are connected to the sources of |{d,e->f}| (which are +just |d| and~|e|). Finally, in the whole graph only |a|, |b|, and |c| +are sources while only |d| and |f| are targets. + +\begin{codeexample}[] +\def\hilightsource#1{\fill [green, opacity=.25] (#1) circle [radius=2mm]; } +\def\hilighttarget#1{\fill [red, opacity=.25] (#1) circle [radius=2mm]; } +\tikz \graph + [operator=\tikzgraphforeachcolorednode{source}{\hilightsource}, + operator=\tikzgraphforeachcolorednode{target}{\hilighttarget}] + { {a,b,c} -> {d, e->f} }; +\end{codeexample} + +The next objective is to make more precise what it means that ``the +targets of the first graph'' and the ``sources of the second graph'' +should be connected. We know already of a general way of connecting +nodes of a graph: operators! Thus, we use an operator for this job. +For instance, the |complete bipartite| operator adds an edge from every node +having a certain color to every node have a certain other color. This +is exactly what we need here: The first color is ``the color |target| +restricted to the nodes of the first graph'' and the second color is +``the color |source| restricted to the nodes of the second graph.'' + +However, we cannot really specify that only nodes from a certain +subgraph are meant -- the |operator| machinery only operates on all +nodes of the current graph. For this reason, what really happens is +the following: When the |graph| command encounters \meta{spec$_1$} +\meta{edge specification} \meta{spec$_2$}, it first computes and +colors the nodes of the first and the second specification +independently. Then, the |target| nodes of the first graph are +recolored to |target'| and the |source| nodes of the second graph are +recolored to |source'|. Then, the two graphs are united into one +graph and a \emph{joining operator} is executed, which should add +edges between |target'| and |source'|. Once this is done, +the colors |target'| and |source'| get erased. Note that in the +resulting graph only the |source| nodes from the first graph are still +|source| nodes and likewise for the |target| nodes of the second graph. + + +\medskip +\textbf{The joining operators.} The job of a joining operator is +to add edges between nodes colored |target'| and |source'|. The +following rule is used to determine which operator should be chosen +for performing this job: +\begin{enumerate} +\item If the \meta{edge specification} explicitly sets the |operator| + key to something non-empty (and also not to |\relax|), then the + \meta{code} of this |operator| call is used. +\item Otherwise, the current value of the following key is used: + \begin{key}{/tikz/graphs/default edge operator=\meta{key}} + This key stores the name of a \meta{key} that is executed for every + \meta{edge specification} whose \meta{options} do not contain the + |operator| key. +\begin{codeexample}[] +\tikz \graph [default edge operator=matching] { + {a, b} ->[matching and star] + {c, d, e} --[complete bipartite] + {f, g, h} -- + {i, j, k} +}; +\end{codeexample} + \end{key} +\end{enumerate} + +A typical joining operator is |complete bipartite|. It takes the names of two +color classes as input and adds edges from all vertices of the first +class to all vertices of the second class. Now, the trick is that the +default value for the |complete bipartite| key is |{target'}{source'}|. Thus, +if you just write |->[complete bipartite]|, the same happens as if you had +written +\begin{quote} +|->[complete bipartite={target'}{source'}]| +\end{quote} +This is exactly what we want to happen. The same default values are +also set for other joining operators like |matching| or |butterfly|. + +Even though an operator like |complete bipartite| is typically used +together with an edge specification, it can also be used as a normal +operator together with a group specification. In this case, however, +the color classes must be named explicitly: + +\begin{codeexample}[] +\begin{tikzpicture} + \graph [color class=red, color class=green, math nodes] + { [complete bipartite={red}{green}] + { [red, Cartesian placement] r_1, r_2, r_3 }, + { [green, Cartesian placement, nodes={xshift=1cm}] g_1, g_2, g_3 } + }; +\end{tikzpicture} +\end{codeexample} + +A list of predefined joining operators can be found in the reference +Section~\ref{section-library-graphs-reference}. + +The fact that joining operators can also be used as normal operators +leads to a subtle problem: A normal operator will typically use the +current value of |default edge kind| to decide which kind of edges +should be put between the identified vertices, while a joining +operator should, naturally, use the kind of edge specified by the +\meta{edge specification}. This problem is solved as follows: Like a +normal operator, a joining operator should also use the current value +of |default edge kind| for the edges it produces. The trick is that +this will automatically be set to the current \meta{edge + specification} when the operator explicitly in the \meta{options} of +the edge specification or implicitly in the |default edge operator|. + + + + +\subsection{Graph Macros} +\label{section-library-graphs-macros} + +A \emph{graph macro} is a small graph that is inserted at some point +into the graph that is currently being constructed. There is special +support for such graph macros in \tikzname. You might wonder why this +is necessary -- can't one use \TeX's normal macro mechanism? The +answer is ``no'': one cannot insert new nodes into a graph using +normal macros because the chains, groups, and nodes are determined +prior to macro expansion. Thus, any macro encountered where some node +text should go will only be expanded when this node is being named and +typeset. + +A graph macro is declared using the following key: + +\begin{key}{/tikz/graphs/declare=\marg{graph name}\marg{specification}} + This key declares that \meta{graph name} can subsequently be used as + a replacement for a \meta{node name}. Whenever the \meta{graph name} + is used in the following, a graph group will be inserted instead + whose content is exactly \meta{specification}. In case \meta{graph + name} is used together with some \meta{options}, they are executed + prior to inserting the \meta{specification}. +\begin{codeexample}[] +\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] { + a; + claw; + b; +}; +\end{codeexample} + In the next example, we use a key to configure a subgraph: +\begin{codeexample}[] +\tikz \graph [ n/.code=\def\n{#1}, branch down=4mm, + declare={star}{root -- { \foreach \i in {1,...,\n} {\i} }}] +{ star [n=5]; }; +\end{codeexample} + Actually, the |n| key is already defined internally for a similar + purpose. + + As a last example, let us define a somewhat more complicated graph + macro. +\begin{codeexample}[] +\newcount\mycount +\tikzgraphsset{ + levels/.store in=\tikzgraphlevel, + levels=1, + declare={bintree}{% + [/utils/exec={% + \ifnum\tikzgraphlevel=1\relax% + \def\childtrees{ / }% + \else% + \mycount=\tikzgraphlevel% + \advance\mycount by-1\relax% + \edef\childtrees{ + / -> { + bintree[levels=\the\mycount], + bintree[levels=\the\mycount] + }} + \fi% + }, + parse/.expand once=\childtrees + ] + % Everything is inside the \childtrees... + } +} +\tikz \graph [grow down=5mm, branch right=5mm] { bintree [levels=5] }; +\end{codeexample} +\end{key} + +Note that when you use a graph macro several time inside the same +graph, you will typically have to use the |name| option so that +different copies of the subgraph are created: +\begin{codeexample}[] +\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] { + claw [name=left], + claw [name=right] +}; +\end{codeexample} + +You will find a list of useful graph macros in the reference section, +Section~\ref{section-library-graphs-reference-macros}. + + +\subsection{Online Placement Strategies} +\label{section-library-graphs-placement} + +The main job of the |graph| library is to make it easy to specify +which nodes are present in a graph and how they are connected. In +contrast, it is \emph{not} the primary job of the library to compute +good positions for nodes in a graph -- use for instance a |\matrix|, +specify good positions ``by hand'' or use the graph drawing +facilities. Nevertheless, some basic support for automatic node +placement is provided for simple cases. The graph library will provide +you with information about the position of nodes inside their groups +and chains. + +As a graph is being constructed, a \emph{placement strategy} is used +to determine a (reasonably good) position for the nodes as they are +created. These placement strategies get some information about what +\tikzname\ has already seen concerning the already constructed nodes, +but it gets no information concerning the upcoming nodes. Because of +this lack of information concerning the future, the strategies need to +be what is called an \emph{online strategy} in computer science. (The +opposite are \emph{offline strategies}, which get information about +the whole graph and all the sizes of the nodes in it. The graph +drawing libraries employ such offline strategies.) + +Strategies are selected using keys like |no placement| or +|Cartesian placement|. It is permissible to use different strategies inside +different parts of a graph, even though the different strategies do +not always work together in perfect harmony. + + +\subsubsection{Manual Placement} +\label{section-graphs-xy} + +\begin{key}{/tikz/graphs/no placement} + This strategy simply ``switches off'' the whole placement + mechanism, causing all nodes to be placed at the origin by + default. You need to use this strategy if you position nodes ``by + hand''. For this, you can use the |at| key, the |shift| keys: +\begin{codeexample}[] +\tikz \graph [no placement] +{ + a[at={(0:0)}] -> b[at={(1,0)}] -> c[yshift=1cm]; +}; +\end{codeexample} + Since the syntax and the many braces and parentheses are a bit + cumbersome, the following two keys might also be useful: + \begin{key}{/tikz/graphs/x=\meta{x dimension}} + When you use this key, it will have the same effect as if you had written + |at={(|\meta{x dimension}|,|\meta{y dimension}|)}|, where \meta{y + dimension} is a value set using the |y| key: +\begin{codeexample}[] +\tikz \graph [no placement] +{ + a[x=0,y=0] -> b[x=1,y=0] -> c[x=0,y=1]; +}; +\end{codeexample} + Note that you can specify an |x| or a |y| key for a whole scope + and then vary only the other key: +\begin{codeexample}[] +\tikz \graph [no placement] +{ + a -> + { [x=1] % group option + b [y=0] -> c[y=1] + }; +}; +\end{codeexample} + Note that these keys have the path |/tikz/graphs/|, so they will + be available inside |graph|s and will not clash with the usual |x| + and |y| keys of \tikzname, which are used to specify the basic + lengths of vectors. + \end{key} + \begin{key}{/tikz/graphs/y=\meta{y dimension}} + See above. + \end{key} +\end{key} + + + + +\subsubsection{Placement on a Grid} + +\begin{key}{/tikz/graphs/Cartesian placement} + This strategy is the default strategy. It works, roughly, as + follows: For each new node on a chain, advance a ``logical width'' + counter and for each new node in a group, advance a ``logical + depth'' counter. When a chain contains a whole group, then the + ``logical width'' taken up by the group is the maximum over the + logical widths taken up by the chains inside the group; and + symmetrically the logical depth of a chain is the maximum of the + depths of the groups inside it. + + This slightly confusing explanation is perhaps best exemplified. In + the below example, the two numbers indicate the two logical width + and depth of each node as computed by the |graph| library. Just + ignore the arcane code that is used to print these numbers. +\begin{codeexample}[] +\tikz + \graph [nodes={align=center, inner sep=1pt}, grow right=7mm, + typeset={\tikzgraphnodetext\\[-4pt] + \tiny\mywidth\\[-6pt]\tiny\mydepth}, + placement/compute position/.append code= + \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} + \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] +{ + a, + b, + c -> d -> { + e -> f -> g, + h -> i + } -> j, + k -> l +}; +\end{codeexample} + You will find a detailed description of how these logical units are + computed, exactly, in Section~\ref{section-library-graphs-new-online}. + + Now, even though we talk about ``widths'' and ``depths'' and even + though by default a graph ``grows'' to the right and down, this is + by no means fixed. Instead, you can use the following keys to change + how widths and heights are interpreted: + \begin{key}{/tikz/graphs/chain shift=\meta{coordinate} (initially {(1,0)})} + Under the regime of the |Cartesian placement| strategy, each node is + shifted by the current logical width times this \meta{coordinate}. +\begin{codeexample}[] +\tikz \graph [chain shift=(45:1)] { + a -> b -> c; + d -> e; + f -> g -> h; +}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/group shift=\meta{coordinate} (initially {(0,-1)})} + Like for |chain shift|, each node is shifted by the current + logical depth times this \meta{coordinate}. +\begin{codeexample}[] +\tikz \graph [chain shift=(45:7mm), group shift=(-45:7mm)] { + a -> b -> c; + d -> e; + f -> g -> h; +}; +\end{codeexample} + \end{key} +\end{key} + + +\begin{key}{/tikz/graphs/grow up=\meta{distance} (default 1)} + Sets the |chain shift| to |(|\meta{distance}|,0)|, so that chains + ``grow upward.'' The distance by which the center of each new + element is removed from the center of the previous one is + \meta{distance}. +\begin{codeexample}[] +\tikz \graph [grow up=7mm] { a -> b -> c}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/grow down=\meta{distance} (default 1)} + Like |grow up|. +\begin{codeexample}[] +\tikz \graph [grow down=7mm] { a -> b -> c}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/grow left=\meta{distance} (default 1)} + Like |grow up|. +\begin{codeexample}[] +\tikz \graph [grow left=7mm] { a -> b -> c}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/grow right=\meta{distance} (default 1)} + Like |grow up|. +\begin{codeexample}[] +\tikz \graph [grow right=7mm] { a -> b -> c}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/branch up=\meta{distance} (default 1)} + Sets the |group shift| so that groups ``branch upward.'' The + distance by which the center of each new element is removed from + the center of the previous one is \meta{distance}. +\begin{codeexample}[] +\tikz \graph [branch up=7mm] { a -> b -> {c, d, e} }; +\end{codeexample} + Note that when you draw a tree, the |branch ...| keys specify how + siblings (or adjacent branches) are arranged, while the |grow ...| + keys specify in which direction the branches ``grow''. +\end{key} +\begin{key}{/tikz/graphs/branch down=\meta{distance} (default 1)} +\begin{codeexample}[] +\tikz \graph [branch down=7mm] { a -> b -> {c, d, e}}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/branch left=\meta{distance} (default 1)} +\begin{codeexample}[] +\tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/branch right=\meta{distance} (default 1)} +\begin{codeexample}[] +\tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}}; +\end{codeexample} +\end{key} + +The following keys place nodes in a $N\times M$ grid. +\begin{key}{/tikz/graphs/grid placement} + This key works similar to |Cartesian placement|. As for that placement + strategy, a node has logical width and depth 1. However, the computed + total width and depth are mapped to a $N\times M$ grid. + The values of $N$ and $M$ depend on the size of the graph and the + value of |wrap after|. The number of columns $M$ is either set to + |wrap after| explicitly or computed automatically as + $\sqrt{\verb!|V|!}$. $N$ is the number of rows needed to lay out the + graph in a grid with $M$ columns. +\begin{codeexample}[] +% An example with 6 nodes, 3 columns and therefor 2 rows +\tikz \graph [grid placement] { subgraph I_n[n=6, wrap after=3] }; +\end{codeexample} +\begin{codeexample}[] +% An example with 9 nodes with columns and rows computed automatically +\tikz \graph [grid placement] { subgraph Grid_n [n=9] }; +\end{codeexample} +\begin{codeexample}[] +% Directions can be changed +\tikz \graph [grid placement, branch up, grow left] { subgraph Grid_n [n=9] }; +\end{codeexample} + In case a user-defined graph instead of a pre-defined + |subgraph| is to be layed out using |grid placement|, |n| has to be + specified explicitly: +\begin{codeexample}[] +\tikz \graph [grid placement] { + [n=6, wrap after=3] + a -- b -- c -- d -- e -- f +}; +\end{codeexample} +\end{key} + + + +\subsubsection{Placement Taking Node Sizes Into Account} + +Options like |grow up| or |branch right| do not take the sizes of the +to-be-positioned nodes into account -- all nodes are placed quite +``dumbly'' at grid positions. It turns out that the +|Cartesian placement| can also be used to place notes in such a way +that their height and/or width is taken into account. Note, however, +that while the following options may yield an adequate placement in +many situations, when you need advanced alignments you should use a +|matrix| or advanced offline strategies to place the nodes. + + +\begin{key}{/tikz/graphs/grow right sep=\meta{distance} (default 1em)} + This key has several effects, but let us start with the bottom line: + Nodes along a chain are placed in such a way that the left end of a + new node is \meta{distance} from the right end of the previous node: +\begin{codeexample}[] +\tikz \graph [grow right sep, left anchor=east, right anchor=west] { + start -- { + long text -- {short, very long text} -- more text, + long -- longer -- longest + } -- end +}; +\end{codeexample} + What happens internally is the following: First, the |anchor| of the + nodes is set to |west| (or |north west| or |south west|, see + below). Second, the logical width of a node is no + longer |1|, but set to the actual width of the node (which we define + as the horizontal difference between the |west| anchor and the + |east| anchor) in points. Third, the |chain shift| is set to + |(1pt,0pt)|. +\end{key} +\begin{key}{/tikz/graphs/grow left sep=\meta{distance} (default 1em)} +\begin{codeexample}[] +\tikz \graph [grow left sep] { long -- longer -- longest }; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/grow up sep=\meta{distance} (default 1em)} +\begin{codeexample}[] +\tikz \graph [grow up sep] { + a / $a=x$ -- + b / {$b=\displaystyle \int_0^1 x dx$} -- + c [draw, circle, inner sep=7mm] +}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/grow down sep=\meta{distance} (default 1em)} + As above. +\end{key} + +\begin{key}{/tikz/graphs/branch right sep=\meta{distance} (default 1em)} + This key works like |grow right sep|, only it affects groups rather + than chains. +\begin{codeexample}[] +\tikz \graph [grow down, branch right sep] { + start -- { + an even longer text -- {short, very long text} -- more text, + long -- longer -- longest, + some text -- a -- b + } -- end +}; +\end{codeexample} + When both this key and, say, |grow down sep| are set, instead of the + |west| anchor, the |north west| anchor will be selected + automatically. +\end{key} + +\begin{key}{/tikz/graphs/branch left sep=\meta{distance} (default 1em)} +\begin{codeexample}[] +\tikz \graph [grow down sep, branch left sep] { + start -- { + an even longer text -- {short, very long text} -- more text, + long -- longer, + some text -- a -- b + } -- end +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/branch up sep=\meta{distance} (default 1em)} +\begin{codeexample}[] +\tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/branch down sep=\meta{distance} (default 1em)} +\end{key} + + + +\subsubsection{Placement On a Circle} + +The following keys place nodes on circles. Note that, typically, you +do not use |circular placement| directly, but rather use one of the +two keys |clockwise| or |counterclockwise|. + +\begin{key}{/tikz/graphs/circular placement} + This key works quite similar to |Cartesian placement|. As for that + placement strategy, a node has logical width and depth |1|. However, + the computed total width and depth are mapped to polar coordinates + rather than Cartesian coordinates. + + \begin{key}{/tikz/graphs/chain polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(0:1)})} + Under the regime of the |circular placement| strategy, each node + on a chain is shifted by |(|\meta{logical + width}\meta{angle}|:|\meta{logical width}\meta{angle}|)|. +\begin{codeexample}[] +\tikz \graph [circular placement] { + a -> b -> c; + d -> e; + f -> g -> h; +}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/group polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(45:0)})} + Like for |group shift|, each node + on a chain is shifted by |(|\meta{logical + depth}\meta{angle}|:|\meta{logical depth}\meta{angle}|)|. +\begin{codeexample}[] +\tikz \graph [circular placement, group polar shift=(30:0)] { + a -> b -> c; + d -> e; + f -> g -> h; +}; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [circular placement, + chain polar shift=(30:0), + group polar shift=(0:1cm)] { + a -- b -- c; + d -- e; + f -- g -- h; +}; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/radius=\meta{dimension} (initially 1cm)} + This is an initial value that is added to the total computed + radius when the polar shift of a node has been + calculated. Essentially, this key allows you to set the + \meta{radius} of the innermost circle. +\begin{codeexample}[] +\tikz \graph [circular placement, radius=5mm] { a, b, c, d }; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [circular placement, radius=1cm] { a, b, c, d }; +\end{codeexample} + \end{key} + \begin{key}{/tikz/graphs/phase=\meta{angle} (initially 90)} + This is an initial value that is added to the total computed + angle when the polar shift of a node has been + calculated. +\begin{codeexample}[] +\tikz \graph [circular placement] { a, b, c, d }; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [circular placement, phase=0] { a, b, c, d }; +\end{codeexample} + \end{key} +\end{key} + +\label{key-graphs-clockwise}% +\begin{key}{/tikz/graphs/clockwise=\meta{number} (default \string\tikzgraphVnum)} + This key sets the |group shift| so that if there are exactly + \meta{number} many nodes in a group, they will form a complete + circle. If you do not provide a \meta{number}, the current value of + |\tikzgraphVnum| is used, which is exactly what you want when you + use predefined graph macros like |subgraph K_n|. +\begin{codeexample}[] +\tikz \graph [clockwise=4] { a, b, c, d }; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [clockwise] { subgraph K_n [n=5] }; +\end{codeexample} +\end{key} + +\label{key-graphs-counterclockwise}% +\begin{key}{/tikz/graphs/counterclockwise=\meta{number} (default \string\tikzgraphVnum)} + Works like |clockwise|, only the direction is inverted. +\end{key} + + +\subsubsection{Levels and Level Styles} + +As a graph is being parsed, the |graph| command keeps track of a +parameter called the \emph{level} of a node. Provided that the graph +is actually constructed in a tree-like manner, the level is exactly +equal to the level of the node inside this tree. + +\begin{key}{/tikz/graphs/placement/level} + This key stores a number that is increased for each element on a + chain, but gets reset at the end of a group: +\begin{codeexample}[] +\tikz \graph [ branch down=5mm, typeset= + \tikzgraphnodetext:\pgfkeysvalueof{/tikz/graphs/placement/level}] +{ + a -> { + b, + c -> { + d, + e -> {f,g}, + h + }, + j + } +}; +\end{codeexample} + Unlike the parameters |depth| and |width| described in the next + section, the key |level| is always available. +\end{key} + +In addition to keeping track of the value of the |level| key, the +|graph| command also executes the following keys whenever it creates a +node: + +\begin{stylekey}{/tikz/graph/level=\meta{level}} + This key gets executed for each newly created node with \meta{level} + set to the current level of the node. You can use this key to, say, + reconfigure the node distance or the node color. +\end{stylekey} + +\begin{stylekey}{/tikz/graph/level \meta{level}} + This key also gets executed for each newly created node with + \meta{level} set to the current level of the node. +\begin{codeexample}[] +\tikz \graph [ + branch down=5mm, + level 1/.style={nodes=red}, + level 2/.style={nodes=green!50!black}, + level 3/.style={nodes=blue}] +{ + a -> { + b, + c -> { + d, + e -> {f,g}, + h + }, + j + } +}; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [ + branch down=5mm, + level 1/.style={grow right=2cm}, + level 2/.style={grow right=1cm}, + level 3/.style={grow right=5mm}] +{ + a -> { + b, + c -> { + d, + e -> {f,g}, + h + }, + j + } +}; +\end{codeexample} +\end{stylekey} + + + +\subsubsection{Defining New Online Placement Strategies} + +\label{section-library-graphs-new-online} + +In the following the details of how to define a new placement strategy +are explained. Most readers may wish to skip this section. + +As a graph specification is being parsed, the |graph| library will keep +track of different numbers that identify the positions of the +nodes. Let us start with what happens on a chain. First, the following +counter is increased for each element of the chain: +\begin{key}{/tikz/graphs/placement/element count} + This key stores a number that tells us the position of the node on + the current chain. However, you only have access to this value + inside the code passed to the macro |compute position|, explained + later on. +\begin{codeexample}[] +\tikz \graph [ + grow right sep, typeset=\tikzgraphnodetext:\mynum, + placement/compute position/.append code= + \pgfkeysgetvalue{/tikz/graphs/placement/element count}{\mynum}] +{ + a -> b -> c, + d -> {e, f->h} -> j +}; +\end{codeexample} + As can be seen, each group resets the element counter. +\end{key} + +The second value that is computed is more complicated to explain, but +it also gives more interesting information: +\begin{key}{/tikz/graphs/placement/width} + This key stores the ``logical width'' of the nodes parsed up to now + in the current group or chain (more precisely, parsed since the last + call of |place| in an enclosing group). This is not necessarily the + ``total physical width'' of the nodes, but rather a number + representing how ``big'' the elements prior to the current element + were. This \emph{may} be their width, but it may also be their + height or even their number (which, incidentally, is the default). + You can use the |width| to perform shifts or rotations of + to-be-created nodes (to be explained later). + + The logical width is defined recursively as follows. First, the + width of a single node is computed by calling the following key: + \begin{key}{/tikz/graphs/placement/logical node width=\meta{full + node name}} + This key is called to compute a physical or logical width of the + node \meta{full node name}. You can change the code of this + key. The code should return the computed value in the macro + |\pgfmathresult|. By default, this key returns |1|. + \end{key} + The width of a chain is the sum of the widths of its elements. The + width of a group is the maximum of the widths of its elements. + + To get a feeling what the above rules imply in practice, let us + first have a look at an example where each node has logical width + and height |1| (which is the default). The arcane options at the + beginning of the code just setup things so that the computed width + and depth of each node is displayed at the bottom of each node. +\begin{codeexample}[] +\tikz + \graph [nodes={align=center, inner sep=1pt}, grow right=7mm, + typeset={\tikzgraphnodetext\\[-4pt] + \tiny\mywidth\\[-6pt]\tiny\mydepth}, + placement/compute position/.append code= + \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} + \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] +{ + a, + b, + c -> d -> { + e -> f -> g, + h -> i + } -> j, + k -> l +}; +\end{codeexample} + In the next example the ``logical'' width and depth actually match + the ``physical'' width and height. This is caused by the + |grow right sep| option, which internally sets the + |logical node width| key so that it returns the width of its + parameter in points. +\begin{codeexample}[] +\tikz + \graph [grow right sep, branch down sep, nodes={align=left, inner sep=1pt}, + typeset={\tikzgraphnodetext\\[-4pt] \tiny Width: \mywidth\\[-6pt] \tiny Depth: \mydepth}, + placement/compute position/.append code= + \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth} + \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}] +{ + a, + b, + c -> d -> { + e -> f -> g, + h -> i + } -> j, + k -> l +}; +\end{codeexample} +\end{key} + +Symmetrically to chains, as a group is being constructed, counters are +available for the number of chains encountered so far in the current +group and for the logical depth of the current group: +\begin{key}{/tikz/graphs/placement/element count} + This key stores a number that tells us the sequence number of the + chain in the current group. +\begin{codeexample}[] +\tikz \graph [ + grow right sep, branch down=5mm, typeset=\tikzgraphnodetext:\mynum, + placement/compute position/.append code= + \pgfkeysgetvalue{/tikz/graphs/placement/chain count}{\mynum}] +{ + a -> b -> {c,d,e}, + f, + g -> h +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/placement/depth} + Similarly to the |width| key, this key stores the ``logical depth'' + of the nodes parsed up to now in the current group or chain and, also + similarly, this key may or may not be related to the actual + depth/height of the current node. + As for the |width|, the exact definition is as follows: For a single + node, the depth is computed by the following key: + \begin{key}{/tikz/graphs/placement/logical node depth=\meta{full + node name}} + The code behind this key should return the ``logical height'' of + the node \meta{full node name} in the macro |\pgfmathresult|. + \end{key} + Second, the depth of a group is the sum of the depths of its + elements. Third, the depth of a chain is the maximum of the depth of + its elements. +\end{key} + +The |width|, |depth|, |element count|, and |chain count| keys get +updated automatically, but do not have an effect by themselves. This +is to the following two keys: + +\begin{key}{/tikz/graphs/placement/compute position=\meta{code}} + The \meta{code} is called by the |graph| command just prior to + creating a new node (the exact moment when this key is called is + detailed in the description of the |place| key). When the + \meta{code} is called, all of the keys described above will hold + numbers computed in the way described above. + + The job of the \meta{code} is to setup node options appropriately so + that the to-be-created node will be placed correctly. Thus, the + \meta{code} should typically set the key + |nodes={shift=|\meta{coordinate}|}| where \meta{coordinate} is the + computed position for the node. The \meta{code} could + also set other options like, say, the color of a node depending on + its depth. + + The following example appends some code to the standard code of + |compute position| so that ``deeper'' nodes of a tree are + lighter. (Naturally, the same effect could be achieved much more + easily using the |level| key.) +\begin{codeexample}[] +\newcount\mycount +\def\lightendeepernodes{ + \pgfmathsetcount{\mycount}{ + 100-20*\pgfkeysvalueof{/tikz/graphs/placement/width} + } + \edef\mydepth{\the\mycount} + \tikzset{nodes={fill=red!\mydepth,circle,text=white}} +} +\tikz + \graph [placement/compute position/.append code=\lightendeepernodes] + { + a -> { + b -> c -> d, + e -> { + f, + g + }, + h + } + }; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/placement/place} + Executing this key has two effects: First, the key + |compute position| is called to compute a good + position for future nodes (usually, these ``future nodes'' are just + a single node that is created immediately). Second, all of the above + counters like |depth| or |width| are reset (but not |level|). + + There are two places where this key is sensibly called: First, just + prior to creating a node, which happens automatically. Second, when + you change the online strategy. In this case, the computed width and + depth values from one strategy typically make no sense in the other + strategy, which is why the new strategy should proceed ``from a + fresh start.'' In this case, the implicit call of |compute position| + ensures that the new strategy gets the last place the old strategy + would have used as its starting point, while the computation of its + positions is now relative to this new starting point. + + For these reasons, when an online strategy like + |Cartesian placement| is called, this key gets called + implicitly. You will rarely need to call this key directly, except + when you define a new online strategy. +\end{key} + + + +\subsection{Reference: Predefined Elements} + +\label{section-library-graphs-reference} + + +\subsubsection{Graph Macros} +\label{section-library-graphs-reference-macros} + +\begin{tikzlibrary}{graph.standard} + This library defines a number of graph macros that are often used in + the literature. When new graphs are added to this collection, they + will follow the definitions in the Mathematica program, see + |mathworld.wolfram.com/topics/SimpleGraphs.html|. +\end{tikzlibrary} + + +\begin{graph}{subgraph I\_n} + This graph consists just of $n$ unconnected vertices. The following + key is used to specify the set of these vertices: + \begin{key}{/tikz/graphs/V=\marg{list of vertices}} + Sets a list of vertex names for use with graphs like + |subgraph I_n| and also other graphs. This list is available in + the macro |\tikzgraphV|. The number of elements of this list is + available in |\tikzgraphVnum|. + \end{key} + \begin{key}{/tikz/graphs/n=\meta{number}} + This is an abbreviation for + |V={1,...,|\meta{number}|}, name shore V={name=V}|. + \end{key} +\begin{codeexample}[] +\tikz \graph [branch right, nodes={draw, circle}] + { subgraph I_n [V={a,b,c}] }; +\end{codeexample} + This graph is not particularly exciting by itself. However, it is + often used to introduce nodes into a graph that are then connected + as in the following example: +\begin{codeexample}[] +\tikz \graph [clockwise, clique] { subgraph I_n [n=4] }; +\end{codeexample} +\end{graph} + + +\begin{graph}{subgraph I\_nm} + This graph consists of two sets of once $n$ unconnected vertices and + then $m$ unconnected vertices. The first set consists of the + vertices set by the key |V|, the other set consists of the vertices + set by the key |W|. +\begin{codeexample}[] +\tikz \graph { subgraph I_nm [V={1,2,3}, W={a,b,c}] }; +\end{codeexample} + In order to set the graph path name of the two + sets, the following keys get executed: + \begin{stylekey}{/tikz/graphs/name shore V (initially \normalfont empty)} + Set this style to, say, |name=my V set| in order to set a + name for the |V| set. + \end{stylekey} + \begin{stylekey}{/tikz/graphs/name shore W (initially \normalfont empty)} + Same as for |name shore V|. + \end{stylekey} + \begin{key}{/tikz/graphs/W=\marg{list of vertices}} + Sets the list of vertices for the |W| set. The elements and + their number are available in the macros |\tikzgraphW| and + |\tikzgraphWnum|, respectively. + \end{key} + \begin{key}{/tikz/graphs/m=\meta{number}} + This is an abbreviation for + |W={1,...,|\meta{number}|}, name shore W={name=W}|. + \end{key} + The main purpose of this subgraph is to setup the nodes in a + bipartite graph: +\begin{codeexample}[] +\tikz \graph { + subgraph I_nm [n=3, m=4]; + + V 1 -- { W 2, W 3 }; + V 2 -- { W 1, W 3 }; + V 3 -- { W 1, W 4 }; +}; +\end{codeexample} +\end{graph} + +\begin{graph}{subgraph K\_n} + This graph is the complete clique on the vertices from the |V| key. +\begin{codeexample}[] +\tikz \graph [clockwise] { subgraph K_n [n=7] }; +\end{codeexample} +\end{graph} + + +\begin{graph}{subgraph K\_nm} + This graph is the complete bipartite graph with the two shores |V| + and |W| as in |subgraph I_nm|. +\begin{codeexample}[] +\tikz \graph [branch right, grow down] + { subgraph K_nm [V={6,...,9}, W={b,...,e}] }; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [simple, branch right, grow down] +{ + subgraph K_nm [V={1,2,3}, W={a,b,c,d}, ->]; + subgraph K_nm [V={2,3}, W={b,c}, <-]; +}; +\end{codeexample} +\end{graph} + +\begin{graph}{subgraph P\_n} + This graph is the path on the vertices in |V|. +\begin{codeexample}[] +\tikz \graph [branch right] { subgraph P_n [n=3] }; +\end{codeexample} +\end{graph} + + +\begin{graph}{subgraph C\_n} + This graph is the cycle on the vertices in |V|. +\begin{codeexample}[] +\tikz \graph [clockwise] { subgraph C_n [n=7, ->] }; +\end{codeexample} +\end{graph} + + +\begin{graph}{subgraph Grid\_n} + This graph is a grid of the vertices in |V|. + \begin{key}{/tikz/graphs/wrap after=\meta{number}} + Defines the number of nodes placed in a single row of the grid. This + value implicitly defines the number of grid columns as well. + In the following example a |grid placement| is used to visualize the + edges created between the nodes of a |Grid_n| |subgraph| using + different values for |wrap after|. + \begin{codeexample}[] +\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=1] }; +\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=3] }; + \end{codeexample} + \begin{codeexample}[] +\tikz \graph [grid placement] { subgraph Grid_n [n=4,wrap after=2] }; +\tikz \graph [grid placement] { subgraph Grid_n [n=4] }; + \end{codeexample} + \end{key} +\end{graph} + + +% TODO: Implement the Grid_nm subgraph described here: +% +%\begin{graph}{subgraph Grid\_nm} +% This graph is a grid built from the cartesian product of the two node +% sets |V| and |W| which are either defined using the keys +% |/tikz/graphs/V| and |/tikz/graphs/W| or |/tikz/graphs/n| and +% |/tikz/graphs/m| or a mixture of both. +% +% The resulting |Grid_nm| subgraph has $n$ ``rows'' and $m$ ``columns'' and +% the nodes are named |V i W j| with $1\le i\le n$ and $1\le j\le n$. +% The names of the two shores |V| and |W| can be changed as described in +% the documentation of the keys |/tikz/graphs/name shore V| and +% |/tikz/graphs/name shore W|. +% \begin{codeexample}[] +%\tikz \graph [grid placement] { subgraph Grid_nm [V={1,2,3}, W={4, 5, 6}] }; +% \end{codeexample} +%\end{graph} + + + +\subsubsection{Group Operators} + +The following keys use the |operator| key to setup operators that +connect the vertices of the current group having a certain color in a +specific way. + +\begin{key}{/tikz/graphs/clique=\meta{color} (default all)} + Adds an edge between all vertices of the current group having the + (logical) color \meta{color}. Since, by default, this color is set + to |all|, which is a color that all nodes get by default, when you + do not specify anything, all nodes will be connected. +\begin{codeexample}[] +\tikz \graph [clockwise, n=5] { + a, + b, + { + [clique] + c, d, e + } +}; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [color class=red, clockwise, n=5] { + [clique=red, ->] + a, b[red], c[red], d, e[red] +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/induced independent set=\meta{color} (default all)} + This key is the ``opposite'' of a |clique|: It removes all edges in + the current group having belonging to color class \meta{color}. More + precisely, an edge of kind |-!-| is added for each pair of + vertices. This means that edge only get removed if you specify the + |simple| option. +\begin{codeexample}[] +\tikz \graph [simple] { + subgraph K_n [<->, n=7, clockwise]; % create lots of edges + + { [induced independent set] 1, 3, 4, 5, 6 } +}; +\end{codeexample} +\end{key} + + +\begin{key}{/tikz/graphs/cycle=\meta{color} (default all)} + Connects the nodes colored \meta{color} is a cyclic fashion. The + ordering is the ordering in which they appear in the whole graph + specification. +\begin{codeexample}[] +\tikz \graph [clockwise, n=6, phase=60] { + { [cycle, ->] a, b, c }, + { [cycle, <-] d, e, f } +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/induced cycle=\meta{color} (default all)} + While the |cycle| command will only add edges, this key will also + remove all other edges between the nodes of the cycle, provided we + are constructing a |simple| graph. +\begin{codeexample}[] +\tikz \graph [simple] { + subgraph K_n [n=7, clockwise]; % create lots of edges + + { [induced cycle, ->, edge=red] 2, 3, 4, 6, 7 }, +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/path=\meta{color} (default all)} + Works like |cycle|, only there is no edge from the last to the first + vertex. +\begin{codeexample}[] +\tikz \graph [clockwise, n=6] { + { [path, ->] a, b, c }, + { [path, <-] d, e, f } +}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/induced path=\meta{color} (default all)} + Works like |induced cycle|, only there is no edge from the last to the first + vertex. +\begin{codeexample}[] +\tikz \graph [simple] { + subgraph K_n [n=7, clockwise]; % create lots of edges + + { [induced path, ->, edges=red] 2, 3, 4, 6, 7 }, +}; +\end{codeexample} +\end{key} + + +\subsubsection{Joining Operators} + +The following keys are typically used as options of an \meta{edge + specification}, but can also be called in a group specification +(however, then, the colors need to be set explicitly). + +\begin{key}{/tikz/graphs/complete bipartite=\meta{from color}\meta{to + color} (default \char`\{source'\char`\}\char`\{target'\char`\})} + Adds all possible edges from every node having color \meta{from color} + to every node having color \meta{to color}: +\begin{codeexample}[] +\tikz \graph { {a, b} ->[complete bipartite] + {c, d, e} --[complete bipartite] + {g, h, i, j} --[complete bipartite] + k }; +\end{codeexample} +\begin{codeexample}[] +\tikz \graph [color class=red, color class=green, clockwise, n=6] { + [complete bipartite={red}{green}, ->] + a [red], b[red], c[red], d[green], e[green], f[green] +}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/induced complete bipartite} + Works like the |complete bipartite| operator, but in a |simple| + graph any edges between the vertices in either shore are removed + (more precisely, they get replaced by |-!-| edges). +\begin{codeexample}[] +\tikz \graph [simple] { + subgraph K_n [n=5, clockwise]; % Lots of edges + + {2, 3} ->[induced complete bipartite] {4, 5} +}; +\end{codeexample} +\end{key} +\begin{key}{/tikz/graphs/matching=\meta{from color}\meta{to + color} (default \char`\{source'\char`\}\char`\{target'\char`\})} + This joining operator forms a maximum + \emph{matching} between the nodes of the two sets of nodes having + colors \meta{from color} and \meta{to color}, respectively. The first node of + the from set is connected to the first node of to set, the second + node of the from set is connected to the second node of the to set, + and so on. If the sets have the same + size, what results is what graph theoreticians call a \emph{perfect + matching}, otherwise only a maximum, but not perfect matching + results. +\begin{codeexample}[] +\tikz \graph { + {a, b, c} ->[matching] + {d, e, f} --[matching] + {g, h} --[matching] + {i, j, k} +}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/graphs/matching and star=\meta{from color}\meta{to + color} (default \char`\{source'\char`\}\char`\{target'\char`\})} + The |matching and star| connector works like the |matching| + connector, only it behaves differently when the two to-be-connected + sets have different size. In this case, all the surplus nodes get + connected to the last node of the other set, resulting in what is known + as a \emph{star} in graph theory. This simple rule allows + for some powerful effects (since this connector is the default, + there is no need to add it here): + \begin{codeexample}[] +\tikz \graph { a -> {b, c} -> {d, e} -- f}; + \end{codeexample} + The |matching and star| connector also makes it easy to create trees and + series-parallel graphs. +\end{key} + +\begin{key}{/tikz/graphs/butterfly=\opt{\meta{options}}} + The |butterfly| connector is used to create the kind of connections + present between layers of a so-called \emph{butterfly network}. + As for other connectors, two sets of nodes are connected, which are + the nodes having color |target'| and |source'| by default. In a + \emph{level $l$} connection, the first $l$ nodes of the first set + are connected to the second $l$ nodes of the second set, while the + second $l$ nodes of the first set get connected to the first $l$ + nodes of the second set. Then, for next $2l$ nodes of both sets a + similar kind of connection is installed. Additionally, each node + gets connected to the corresponding node in the other set with the + same index (as in a |matching|): +\begin{codeexample}[] +\tikz \graph [left anchor=east, right anchor=west, + branch down=4mm, grow right=15mm] { + subgraph I_n [n=12, name=A] --[butterfly={level=3}] + subgraph I_n [n=12, name=B] --[butterfly={level=2}] + subgraph I_n [n=12, name=C] +}; +\end{codeexample} + Unlike most joining operators, the colors of the nodes in the first + and the second set are not passed as parameters to the |butterfly| + key. Rather, they can be set using the \meta{options}, which are + executed with the path prefix |/tikz/graphs/butterfly|. + \begin{key}{/tikz/graphs/butterfly/level=\meta{level} (initially 1)} + Sets the level $l$ for the connections. + \end{key} + \begin{key}{/tikz/graphs/butterfly/from=\meta{color} (initially target')} + Sets the color class of the from nodes. + \end{key} + \begin{key}{/tikz/graphs/butterfly/to=\meta{color} (initially source')} + Sets the color class of the to nodes. + \end{key} +\end{key} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex index 265880d2b6e..051ede9e9c6 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-matrices.tex @@ -15,7 +15,7 @@ When creating pictures, one often faces the problem of correctly aligning parts of the picture. For example, you might wish that the -base lines of certain nodes should be on the same line and some +|baseline|s of certain nodes should be on the same line and some further nodes should be below these nodes with, say, their centers on a vertical lines. There are different ways of solving such problems. For example, by making clever use of anchors, nearly all @@ -29,7 +29,7 @@ little picture or a node. The sizes of the cells are automatically adjusted such that they are large enough to contain all the cell contents. -Matrices are a powerful tool and they need to handled with some care. +Matrices are a powerful tool and they need to be handled with some care. For impatient readers who skip the rest of this section: you \emph{must} end \emph{every} row with |\\|. In particular, the last row \emph{must} be ended with |\\|. @@ -96,7 +96,7 @@ effect as for normal nodes: \subsection{Cell Pictures} - +\label{section-tikz-cell-pictures} A matrix consists of rows of \emph{cells}. Each row (including the last one!) is ended by the command |\\|. The character |&| is used to separate cells. Inside each cell, you must place commands for @@ -119,7 +119,7 @@ the origin of the cell picture can be found (the origin might even lie outside the bounding box, but let us ignore this problem for the moment). The cell pictures are then shifted around such that all origins lie on the same horizontal line. This may make it necessary to -shift some cell pictures upwards and other downwards, but it can be +shift some cell pictures upwards and others downwards, but it can be done and this yields the vertical alignment of the cell pictures this row. The top of the row is then given by the top of the ``highest'' cell picture in the row, the bottom of the row is given by the bottom @@ -173,13 +173,13 @@ shifted horizontally such that the origins lie on the same vertical line. Then, the left end of the column is at the left end of the bounding box that protrudes furthest to the left. The right end of the column is at the right end of the bounding box that protrudes furthest -to the left. This fixes the horizontal alignment of the cell pictures +to the right. This fixes the horizontal alignment of the cell pictures in the first column and the same happens the cell pictures in the other columns. Then, the right end of the first column touches the left end of the second column (unless |column sep| is used). The right end of the second column touches the left end of the third column, and so on. (Internally, two columns are actually used to achieve the -desired horizontal alignment, but that is only and implementation +desired horizontal alignment, but that is only an implementation detail.) \begin{codeexample}[] @@ -251,7 +251,7 @@ the column or row or between their borders. origins of all the cells in the second column is exactly the given distance. - \emph{The |between origins| option can only be used for columns + \emph{The }|between origins|\emph{ option can only be used for columns mentioned in the first row, that is, you cannot specify this option for columns introduced only in later rows.} @@ -366,8 +366,8 @@ of this option in later rows have no effect. \subsubsection{Cell Styles and Options} -For following style and option are useful for changing the appearance -of the all cell pictures: +The following styles and options are useful for changing the appearance +of all cell pictures: \begin{stylekey}{/tikz/every cell=\marg{row}\marg{column} (initially \normalfont empty)} This style is installed at the beginning of each cell picture with @@ -382,13 +382,13 @@ of the all cell pictures: \end{stylekey} \begin{key}{/tikz/cells=\meta{options}} - This key adds the \meta{options} to the style |every cell|. It mainly + This key adds the \meta{options} to the style |every cell|. It is mainly just a shorthand for the code |every cell/.append style=|\meta{options}. \end{key} \begin{key}{/tikz/nodes=\meta{options}} - This key adds the \meta{options} to the style |every node|. It mainly + This key adds the \meta{options} to the style |every node|. It is mainly just a shorthand for the code |every node/.append style=|\meta{options}. The main use of this option is the install some options for the @@ -563,7 +563,7 @@ effect when given as an argument to a matrix: \begin{key}{/tikz/anchor=\meta{anchor or node.anchor}} Normally, the argument of this option refers to anchor of the matrix - node, which is the node than includes all of the stuff of the + node, which is the node that includes all of the stuff of the matrix. However, you can also provide an argument of the form \meta{node}|.|\meta{anchor} where \meta{node} must be node defined inside the matrix and \meta{anchor} is an anchor of this node. In @@ -604,7 +604,7 @@ having to type |\pgfmatrixnextcell| each time: If a macro name is provided, this macro will be defined to be equal to |\pgfmatrixnextcell| inside matrices and |&| will not be made active. For instance, you could say |ampersand replacement=\&| and - then use \& to separate columns as in the following example: + then use |\&| to separate columns as in the following example: \begin{codeexample}[] \tikz \matrix [ampersand replacement=\&] diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex index 77726100290..02456c9c869 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-paths.tex @@ -21,7 +21,7 @@ present section. The \meta{specification} is a long stream of \emph{path operations}. Most of these path operations tell \tikzname\ how the path - is build. For example, when you write |--(0,0)|, you use a + is built. For example, when you write |--(0,0)|, you use a \emph{line-to operation} and it means ``continue the path from wherever you are to the origin.'' @@ -107,7 +107,7 @@ present section. everything in a scope. \begin{codeexample}[] \begin{tikzpicture} - [fill=examplefill, % only sets the color + [fill=yellow!80!black, % only sets the color every path/.style={draw}] % all paths are drawn \fill (0,0) rectangle +(1,1); \shade (2,0) rectangle +(1,1); @@ -186,27 +186,38 @@ expected. described next. \end{pathoperation} +There is special coordinate called |current subpath start| that is +always at the position of the last move-to operation on the current +path. -\subsection{The Line-To Operation} +\begin{codeexample}[] +\tikz [line width=2mm] + \draw (0,0) -- (1,0) -- (1,1) + -- (0,1) -- (current subpath start); +\end{codeexample} + +Note how in the above example the path is not closed (as |--cycle| +would do). Rather, the line just starts and ends at the origin without +being a closed path. +\subsection{The Line-To Operation} + \subsubsection{Straight Lines} -\begin{pathoperation}{--}{\meta{coordinate}} +\begin{pathoperation}{--}{\meta{coordinate or cycle}} The line-to operation extends the current path from the current - point in a straight line to the given coordinate. The ``current + point in a straight line to the given \meta{coordinate} (the ``or + cycle'' part is explained in a moment). The ``current point'' is the endpoint of the previous drawing operation or the point specified by a prior move-to operation. - You use two minus signs followed by a coordinate in round - brackets. You can add spaces before and after the~|--|. - When a line-to operation is used and some path segment has just been constructed, for example by another line-to operation, the two line segments become joined. This means that if they are drawn, the point where they meet is ``joined'' smoothly. To appreciate the difference, consider the following two examples: In the left example, the path - consists of two path segments that are not joined, but that happen to + consists of two path segments that are not joined, but they happen to share a point, while in the right example a smooth join is shown. \begin{codeexample}[] @@ -217,8 +228,36 @@ expected. \end{tikzpicture} \end{codeexample} + Instead of a coordinate following the two minus signs, you can also + use the text |cycle|. This causes the straight line from the current + point to go to the last point specified by a move-to operation. Note + that this need not be the beginning of the path. Furthermore, a + smooth join is created between the first segment created after the + last move-to operation and the straight line appended by the cycle + operation. + + Consider the following example. In the left example, two triangles are + created using three straight lines, but they are not joined at the + ends. In the second example cycle operations are used. + +\begin{codeexample}[] +\begin{tikzpicture}[line width=10pt] + \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0); + \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle; + \useasboundingbox (0,1.5); % make bounding box higher +\end{tikzpicture} +\end{codeexample} \end{pathoperation} +Writing |cycle| instead of a coordinate at the end of a path operation +is possible with all path operations that end with a coordinate (such +as |--| or |..| or |sin| or |grid|, but not |graph| or |plot|). +In all cases, the effect is that the coordinate of the last moveto is +used as the coordinate expected by the path operation and that a +smooth join is added. (What actually happens that the text |cycle| +used with any path operation other than |--| gets replaced by +|(current subpath start)--cycle|.) + \subsubsection{Horizontal and Vertical Lines} @@ -227,21 +266,28 @@ only horizontal and vertical. For this, you can use two path construction operations. {\catcode`\|=12 -\begin{pathoperation}[noindex]{-|}{\meta{coordinate}} +\begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}} \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}% \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}% \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}% This operation means ``first horizontal, then vertical.'' - \begin{codeexample}[] +\begin{codeexample}[] \begin{tikzpicture} \draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B}; \draw (a.north) |- (b.west); \draw[color=red] (a.east) -| (2,1.5) -| (b.north); \end{tikzpicture} \end{codeexample} + Instead of a coordinate you can also write \verb!cycle! to close the + path: +\begin{codeexample}[] +\begin{tikzpicture}[ultra thick] + \draw (0,0) -- (1,1) -| cycle; +\end{tikzpicture} +\end{codeexample} \end{pathoperation} -\begin{pathoperation}[noindex]{|-}{\meta{coordinate}} +\begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}} \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}% \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}% \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}% @@ -252,13 +298,15 @@ construction operations. \subsection{The Curve-To Operation} -The curve-to operation allows you to extend a path using a Bézier +The curve-to operation allows you to extend a path using a B\'ezier curve. -\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y}}} +\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}} This operation extends the current path from the current - point, let us call it $x$, via a curve to a the current point~$y$. - The curve is a cubic Bézier curve. For such a curve, + point, let us call it $x$, via a curve to a point~$y$ (if, instead + of a coordinate you say |cycle| at the end, $y$ will be the + coordinate of the last move-to operation). + The curve is a cubic B\'ezier curve. For such a curve, apart from $y$, you also specify two control points $c$ and $d$. The idea is that the curve starts at $x$, ``heading'' in the direction of~$c$. Mathematically spoken, the tangent of the curve at $x$ goes @@ -277,38 +325,21 @@ curve. \end{tikzpicture} \end{codeexample} - As with the line-to operation, it makes a difference whether two curves - are joined because they resulted from consecutive curve-to or line-to - operations, or whether they just happen to have the same ending: - \begin{codeexample}[] -\begin{tikzpicture}[line width=10pt] - \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0); - \draw (3,0) -- (4,1) .. controls (4,0) and (5,0) .. (5,0); - \useasboundingbox (0,1.5); % make bounding box higher +\begin{tikzpicture} + \draw[line width=10pt] (0,0) -- (2,0) .. controls (1,1) .. cycle; \end{tikzpicture} \end{codeexample} -\end{pathoperation} - - -\subsection{The Cycle Operation} - -\begin{pathoperation}{--cycle}{} - This operation adds a straight line from the current - point to the last point specified by a move-to operation. Note that - this need not be the beginning of the path. Furthermore, a smooth join - is created between the first segment created after the last move-to - operation and the straight line appended by the cycle operation. - Consider the following example. In the left example, two triangles are - created using three straight lines, but they are not joined at the - ends. In the second example cycle operations are used. + As with the line-to operation, it makes a difference whether two curves + are joined because they resulted from consecutive curve-to or line-to + operations, or whether they just happen to have a common (end) point: \begin{codeexample}[] \begin{tikzpicture}[line width=10pt] - \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0); - \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle; - \useasboundingbox (0,1.5); % make bounding box higher + \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0); + \draw [yshift=-1.5cm] + (0,0) -- (1,1) .. controls (1,0) and (2,0) .. (2,0); \end{tikzpicture} \end{codeexample} \end{pathoperation} @@ -321,10 +352,10 @@ A rectangle can obviously be created using four straight lines and a cycle operation. However, since rectangles are needed so often, a special syntax is available for them. -\begin{pathoperation}{rectangle}{\meta{corner}} +\begin{pathoperation}{rectangle}{\meta{corner or cycle}} When this operation is used, one corner will be the current point, another corner is given by \meta{corner}, which becomes the new - current point. + current point. \begin{codeexample}[] \begin{tikzpicture} @@ -332,6 +363,9 @@ special syntax is available for them. \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0); \end{tikzpicture} \end{codeexample} + + Just for consistency, you can also use |cycle| instead of a + coordinate, but it is a bit unclear what use this might have. \end{pathoperation} @@ -440,7 +474,7 @@ special path operation. It is possible to set the |radius| also in some enclosing scope, in this case the options can be left out (but see the note below on - what may follow: + what may follow): \begin{codeexample}[] \begin{tikzpicture}[radius=2pt] \draw (0,0) circle -- (1,1) circle -- ++(0,1) circle; @@ -449,7 +483,7 @@ special path operation. The following style is used with every circle: \begin{stylekey}{/tikz/every circle} - You can use this key to setup, say, a default radius for every + You can use this key to set up, say, a default radius for every circle. The key will also be used with the |ellipse| operation. \end{stylekey} @@ -553,9 +587,12 @@ path. You can add a grid to the current path using the |grid| path operation. -\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner}} +\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}} This operations adds a grid filling a rectangle whose two corners - are given by \meta{corner} and by the previous coordinate. Thus, the + are given by \meta{corner} and by the previous coordinate. (Instead + of a coordinate you can also say |cycle| to use the position of the + last move-to as the corner coordinate, but it not very natural to + do so.) corner Thus, the typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which yields a grid filling the rectangle whose corners are at $(1,1)$ and $(3,3)$. All coordinate transformations apply to the @@ -643,20 +680,26 @@ equation $f(x) = x^2$ and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex] +(2ex,0ex);. \begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend - coordinate}}\meta{coordinate}} + coordinate}}\meta{coordinate or cycle}} This operation adds a parabola through the current point and the - given \meta{coordinate}. If the |bend| is given, it specifies where + given \meta{coordinate} or, if |cycle| is used instead of coordinate + at the end, the \meta{coordinate} is set to the position of the last + move-to and the path gets closed after the parabola. If the |bend| + is given, it specifies where the bend should go; the \meta{options} can also be used to specify where the bend is. By default, the bend is at the old current point. \begin{codeexample}[] \begin{tikzpicture} - \draw (0,0) rectangle (1,1.5) - (0,0) parabola (1,1.5); - \draw[xshift=1.5cm] (0,0) rectangle (1,1.5) - (0,0) parabola[bend at end] (1,1.5); - \draw[xshift=3cm] (0,0) rectangle (1,1.5) - (0,0) parabola bend (.75,1.75) (1,1.5); + \draw (0,0) rectangle (1,1.5) + (0,0) parabola (1,1.5); + \draw[xshift=1.5cm] (0,0) rectangle (1,1.5) + (0,0) parabola[bend at end] (1,1.5); + \draw[xshift=3cm] (0,0) rectangle (1,1.5) + (0,0) parabola bend (.75,1.75) (1,1.5); + + \draw[yshift=-2cm] (1,1.5) -- + (0,0) parabola cycle; \end{tikzpicture} \end{codeexample} @@ -672,7 +715,7 @@ parabola[parabola height=-1.5ex] +(2ex,0ex);. There is one special property of the \meta{coordinate}: When a relative coordinate is given like |+(0,0)|, the position relative - to which this coordinate is ``flexible.'' More precisely, this + to this coordinate is ``flexible.'' More precisely, this position lies somewhere on a line from the old current point to the new current point. The exact position depends on the next option. @@ -733,7 +776,7 @@ The |sin| and |cos| operations are similar to the |parabola| operation. They, too, can be used to draw (parts of) a sine or cosine curve. -\begin{pathoperation}{sin}{\meta{coordinate}} +\begin{pathoperation}{sin}{\meta{coordinate or cycle}} The effect of |sin| is to draw a scaled and shifted version of a sine curve in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way that the start of the sine curve in the interval is at the @@ -746,7 +789,7 @@ curve. \end{codeexample} \end{pathoperation} -\begin{pathoperation}{cos}{\meta{coordinate}} +\begin{pathoperation}{cos}{\meta{coordinate or cycle}} This operation works similarly, only a cosine in the interval $[0,\pi/2]$ is drawn. By correctly alternating |sin| and |cos| operations, you can create a complete sine or cosine curve: @@ -770,21 +813,21 @@ given in the \textsc{svg} path data syntax. This syntax is described in detail in Section 8.3 of the \textsc{svg 1.1} specification, please consult this specification for details. -\begin{pathoperation}{svg}{\opt{\oarg{options}}|"|\meta{path data}|"|} +\begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}} This operation adds the path specified in the \meta{path data} in \textsc{svg 1.1 path data} syntax to the current path. Unlike the \textsc{svg}-specification, it \emph{is} permissible that the path - data does not start with a moveto command (|m| or |M|), in which + data does not start with a move-to command (|m| or |M|), in which case the last point of the current path is used as start point. The optional \meta{options} apply locally to this path operation, - typically you will use them to setup, say, some transformations. + typically you will use them to set up, say, some transformations. \begin{codeexample}[] \begin{tikzpicture} - \filldraw [fill=red!20] (0,1) svg[scale=2] "h 10 v 10 h -10" + \filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10} node [above left] {upper left} -- cycle; - \draw svg "M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0"; + \draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0}; \end{tikzpicture} \end{codeexample} @@ -795,8 +838,11 @@ consult this specification for details. (yes, this works, although some rather evil magic is involved) will cause 1cm to be the basic unit. - \emph{Warning:} The arc operations (|a| and |A|) are not numerically - stable. This means that they will be quite imprecise, except when + Instead of curly braces, you can also use quotation marks to + indicate the start and end of the \textsc{svg} path. + + \emph{Warning:} The arc operations (|a| and |A|) are numerically + instable. This means that they will be quite imprecise, except when the angle is a multiple of $90^\circ$ (as is, fortunately, most often the case). \end{pathoperation} @@ -823,14 +869,14 @@ of 45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special path to be used instead of the straight line. \begin{pathoperation}{to}{\opt{|[|\meta{options}|]|} - \opt{\meta{nodes}} |(|\meta{coordinate}|)|} + \opt{\meta{nodes}} \meta{coordinate or cycle}} - This path operation inserts the path current set via the |to path| + This path operation inserts the path currently set via the |to path| option at the current position. The \meta{options} can be used to - modify (perhaps implicitly) the |to path| and to setup how the path + modify (perhaps implicitly) the |to path| and to set up how the path will be rendered. - Before the |to path| is inserted, a number of macros are setup that + Before the |to path| is inserted, a number of macros are set up that can ``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and |\tikztonodes|; they are explained in the following. @@ -838,28 +884,31 @@ trigger a special path to be used instead of the straight line. \medskip \textbf{Start and Target Coordinates.}\ \ The |to| operation is always followed by a \meta{coordinate}, called - the target coordinate. The macro |\tikztotarget| is set to this - coordinate (without the parentheses). There is also a \emph{start - coordinate}, which is the coordinate preceding the |to| - operation. This coordinate can be accessed via the macro - |\tikztostart|. In the following example, for the first |to|, the - macro |\tikztostart| is |0pt,0pt| and the |\tikztotarget| is - |0,2|. For the second |to|, the macro |\tikztostart| is |10pt,10pt| - and |\tikztotarget| is |a|. + the target coordinate, or the text |cycle|, in which case the last + move-to is used as a coordinate and the path gets closed. The macro + |\tikztotarget| is set to this coordinate (without its + parentheses). There is also a \emph{start coordinate}, which is the + coordinate preceding the |to| operation. This coordinate can be + accessed via the macro |\tikztostart|. In the following example, for + the first |to|, the macro |\tikztostart| is |0pt,0pt| and the + |\tikztotarget| is |0,2|. For the second |to|, the macro + |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the + third, they are set to |a| and |current subpath start|. \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); + \node (a) at (2,2) {a}; - \draw (0,0) to (0,2); - \node (a) at (2,2) {a}; - \draw[red] (10pt,10pt) to (a); + \draw (0,0) to (0,2); + \draw[red] (10pt,10pt) to (a); + \draw[blue] (3,0) -- (3,2) -- (a) to cycle; \end{tikzpicture} \end{codeexample} \medskip - \textbf{Nodes on tos.}\ \ + \textbf{Nodes on to--paths.}\ \ It is possible to add nodes to the paths constructed by a |to| operation. To do so, you specify the nodes between the |to| keyword and the coordinate (if there are options to the |to| @@ -876,6 +925,42 @@ trigger a special path to be used instead of the straight line. \end{tikzpicture} \end{codeexample} + Instead of writing the node between the |to| keyword and the + target coordinate, you may also use the following keys to create + such nodes: + \begin{key}{/tikz/edge node=\meta{node specification}} + This key can be used inside the \meta{options} of a |to| path + command. It will add the \meta{node specification} to the list of + nodes to be placed on the connecting line, just as if you had + written the \meta{node specification} directly after the |to| + keyword: +\begin{codeexample}[] +\begin{tikzpicture} + \draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2); + + \draw (0,0) to [out=90,in=180, + edge node={node [sloped,above] {x}}] (3,2); +\end{tikzpicture} +\end{codeexample} + This key is mostly useful to create labels automatically using + other keys. + \end{key} + \begin{key}{/tikz/edge label=\meta{text}} + A shorthand for |edge node={node[auto]{|\meta{text}|}}|. +\begin{codeexample}[] +\tikz \draw (0,0) to [edge label=x] (3,2); +\end{codeexample} + \end{key} + \begin{key}{/tikz/edge label'=\meta{text}} + A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|. +\begin{codeexample}[] +\tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2); +\end{codeexample} + \end{key} + + When the |quotes| library is loaded, additional ways of specifying + nodes on to--paths become available, see Section~\ref{section-edge-quotes}. + \medskip \textbf{Styles for to-paths.}\ \ In addition to the \meta{options} given after the |to| operation, @@ -886,6 +971,14 @@ trigger a special path to be used instead of the straight line. \tikz[every to/.style={bend left}] \draw (0,0) to (3,2); \end{codeexample} + Note that, as explained below, every to path is implicitly + surrounded by curly braces. This means that options like |draw| + given in an |every to| do not actually influence the path. You can + fix this by using the |append after command| option: +\begin{codeexample}[] +\tikz[every to/.style={append after command={[draw,dashed]}}] + \draw (0,0) to (3,2); +\end{codeexample} \end{stylekey} \medskip @@ -910,16 +1003,16 @@ trigger a special path to be used instead of the straight line. Inside the \meta{path}, different macros are used to reference the from- and to-coordinates. In detail, these are: \begin{itemize} - \item \declare{|\tikztostart|} will expand to the from-coordinate + \item \declareandlabel{\tikztostart} will expand to the from-coordinate (without the parentheses). - \item \declare{|\tikztotarget|} will expand to the to-coordinate. - \item \declare{|\tikztonodes|} will expand to the nodes between + \item \declareandlabel{\tikztotarget} will expand to the to-coordinate. + \item \declareandlabel{\tikztonodes} will expand to the nodes between the |to| operation and the coordinate. Furthermore, these nodes will have the |pos| option set implicitly. \end{itemize} Let us have a look at a simple example. The standard straight line - for an to is achieved by the following \meta{path}: + for a |to| is achieved by the following \meta{path}: \begin{quote} |-- (\tikztotarget) \tikztonodes| \end{quote} @@ -932,7 +1025,7 @@ trigger a special path to be used instead of the straight line. \end{quote} the \meta{path} will expand to \begin{quote} - |(a) -- (b) node[pos] {x}| + |(a) -- (b) node[red] {x}| \end{quote} It is not possible to specify the path @@ -976,7 +1069,7 @@ trigger a special path to be used instead of the straight line. \end{codeexample} \begin{key}{/tikz/execute at begin to=\meta{code}} - The \meta{code} is executed prior to the to. This can be used to + The \meta{code} is executed prior to the |to|. This can be used to draw one or more additional paths or to do additional computations. \end{key} @@ -998,6 +1091,23 @@ There are a number of predefined |to path|s, see Section~\ref{library-to-paths} for a reference. +\subsection{The Foreach Operation} + +\begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in| + \marg{path commands}} + The |foreach| operation can be used to repeatedly insert the + \meta{path commands} into the current path. Naturally, the + \meta{path commands} should internally reference some of the + \meta{variables} so that you do not insert exactly the same path + repeatedly, but rather variations. For historical reasons, you can + also write |\foreach| instead of |foreach|. +\begin{codeexample}[] +\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) }; +\end{codeexample} + See Section~\ref{section-foreach} for more details on the + for-each-command. +\end{pathoperation} + \subsection{The Let Operation} The \emph{let operation} is the first of a number of path operations @@ -1020,7 +1130,7 @@ local, effects. |\n|\meta{number register}|={|\meta{formula}|}| \end{quote} When an assignment has this form, the \meta{formula} is evaluated - using the |\pgfmathparse| operation. The result stored in the + using the |\pgfmathparse| operation. The result is stored in the \meta{number register}. If the \meta{formula} involves a dimension anywhere (as in |2*3cm/2|), then the \meta{number register} stores the resulting dimension with a trailing |pt|. A \meta{number register} can @@ -1050,7 +1160,7 @@ local, effects. \end{quote} Point position registers store a single point, consisting of an $x$-part and a $y$-part measured in \TeX\ points (|pt|). In - particular, point registers do not stored nodes or node names. + particular, point registers do not store nodes or node names. Here is an example: \begin{codeexample}[] \begin{tikzpicture} @@ -1077,7 +1187,7 @@ local, effects. what you intended. \end{command} \begin{command}{\x\marg{point register}} - This macro expand just to the $x$-part of the point + This macro expands just to the $x$-part of the point register. If we say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then inside the |...| part the macro |\x1| expands to |1pt|. @@ -1127,7 +1237,7 @@ local, effects. \end{tikzpicture} \end{codeexample} - For a more useful application of the let operation, let use draw a + For a more useful application of the let operation, let us draw a circle that touches a given line: \begin{codeexample}[] \begin{tikzpicture} @@ -1164,8 +1274,7 @@ please see Section~\ref{section-scopes-relative}. \subsection{The Node and Edge Operations} -There are two more operations that can be found in paths: -|node| and |edge|. The first is used to add a so-called node to a +The |node| operation adds a so-called node to a path. This operation is special in the following sense: It does not change the current path in any way. In other words, this operation is not really a path operation, but has an effect that is @@ -1178,6 +1287,20 @@ Since these operations are quite complex, they are described in the separate Section~\ref{section-nodes}. +\subsection{The Graph Operation} + +The |graph| operation can be used to specify easily how a large number +of nodes are connected. This operation is documented in a separate +section, see Section~\ref{section-library-graphs}. + + +\subsection{The Pic Operation} + +The |pic| operation is used to insert a ``short picture'' (hence the +``short'' name) at the current position of the path. This operation is +somewhat similar to the |node| operation and discussed in detail in +Section~\ref{section-pics}. + \subsection{The PGF-Extra Operation} @@ -1209,9 +1332,9 @@ used deep inside clever macros, not on normal paths. This is an alternative syntax for the |\pgfextra| command. If the code following |\pgfextra| does not start with a brace, the \meta{code} is executed until |\endpgfextra| is encountered. What - actually happens is that |\pgfextra| that is not followed by a brace - completely shuts down the \tikzname\ parse and |\endpgfextra| is a - normal macro that restarts the parser. + actually happens is that when |\pgfextra| is not followed by a + brace, this completely shuts down the \tikzname\ parser and + |\endpgfextra| is a normal macro that restarts the parser. \begin{codeexample}[] \newdimen\mydim diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex new file mode 100644 index 00000000000..fcc88e1e5dc --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-pics.tex @@ -0,0 +1,531 @@ +% Copyright 2013 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\section{Pics: Small Pictures on Paths} + +\label{section-pics} + +\subsection{Overview} + +A ``pic'' is a ``short picture'' (hence the short name\dots) that can +be inserted anywhere in \tikzname\ picture where you could also insert +a node. Similarly to nodes, pics have a ``shape'' (called \emph{type} +to avoid confusion) that someone has defined. Each time a pic of a +specified type is used, the type's code is executed, resulting in some +drawings to be added to the current picture. The syntax for adding +nodes and adding pics to a picture are also very similar. The core +difference is that pics are typically more complex than nodes and may +consist of a whole bunch of nodes themselves together with complex +paths joining them. + +As a very simple example, suppose we want to define a pic type +|seagull| that just draw ``two bumps.'' The code for this definition +is quite easy: +\begin{codeexample}[code only] +\tikzset{ + seagull/.pic={ + % Code for a "seagull". Do you see it?... + \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); + } +} +\end{codeexample} + +The first line just tells \TeX\ that you set some \tikzname\ options +for the current scope (which is the whole document); you could put +|seagull/.pic=...| anywhere else where \tikzname\ options are allowed +(which is just about anywhere). We have now defined a |seagull| pic +type and can use it as follows: + +\tikzset{ + seagull/.pic={ + % Code for a "seagull". Do you see it?... + \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0); + } +} +\begin{codeexample}[] +\tikz \fill [fill=blue!20] + (1,1) + -- (2,2) pic {seagull} + -- (3,2) pic {seagull} + -- (3,1) pic [rotate=30] {seagull} + -- (2,1) pic [red] {seagull}; +\end{codeexample} + +As can be see, defining new types of pics is much easier than defining +new shapes for nodes; but see Section~\ref{section-new-pic-types} +for the fine details. + +Since defining new pics types is easier than defining new node shapes +and since using pics is as easy as using nodes, why should you use +nodes at all? There are chiefly two reasons: + +\begin{enumerate} +\item Unlike nodes, pics cannot be referenced later on. You \emph{can} + reference nodes that are inside a pic, but not ``the pic itself.'' + In particular, you cannot draw lines between pics the way you + can draw them between nodes. In general, whenever it makes sense + that some drawing could conceivably be connected to other + node-like-things, then a node is better than a pic. +\item If pics are used to emulate the full power of a node (which is + possible, in principle), they will be slower to construct and take + up more memory than a node achieving the same effect. +\end{enumerate} + +Despite these drawbacks, pics are an excellent choice for creating +highly configurable reusable pieces of drawings that can be inserted +into larger contexts. + + +\subsection{The Pic Syntax} + +\begin{command}{\pic} + Inside |{tikzpicture}| this is an abbreviation for |\path pic|. +\end{command} + +The syntax for adding a pic to a picture is very similar to the syntax +used for nodes (indeed, internally the same parser code is used). The +main difference is that instead of a node contents you provide the +picture's type between the braces: + +\begin{pathoperation}{pic}{\opt{\meta{foreach statements}}% + \opt{|[|\meta{options}|]|}\opt{|(|\meta{prefix}|)|}% + \opt{|at(|\meta{coordinate}|)|}\opt{\marg{pic type}}} + + Adds a pic to the current \tikzname\ picture of the specified + \meta{pic type}. The effect is, basically, that some code associated + with the \meta{pic type} is executed (how this works, exactly, is explained + later). This code can consist of arbitrary \tikzname\ code. As for + nodes, the current path will not be modified by this path command, + all drawings produced by the code are ``external'' to the path the + same way neither a node nor its border are part of the path on which + they are specified. + + Just like the |node| command, this path operation is somewhat + complex and we go over it step by step. + + \medskip + \textbf{Order of the parts of the specification.} + Just like for nodes, everything between ``|pic|'' and the opening + brace of the \meta{pic type} is optional and can be given in any + order. If there are \meta{foreach statements}, they must come + first, directly following ``|pic|.'' As for nodes, the ``end'' of + the pic specification is normally detected by the presence of the + opening brace. You can, however, use the |pic type| + option to specify the pic type as an option. + + \begin{key}{/tikz/pic type=\meta{pic type}} + This key sets the pic type of the current~|pic|. When this option + is used inside an option block of a |pic|, the parsing of the + |pic| ends immediately and no pic type in braces is expected. (In + other words, this option behaves exactly like the |node contents| + option and, indeed, the two are interchangeable.) +\begin{codeexample}[] +\tikz { + \path (0,0) pic [pic type = seagull] + (1,0) pic {seagull}; +} +\end{codeexample} + \end{key} + + \medskip + \textbf{The location of a pic.} + Just like nodes, pics are placed at the last position mentioned on + the path or, when |at| is used, at a specified position. ``Placing'' + a pic somewhere actually means that the coordinate system is + translated (shifted) to this last position. This means that inside + of the pic type's code any mentioning of the origin refers to the + last position used on the path or to the specified |at|. + +\begin{codeexample}[] +\tikz { % different ways of placing pics + \draw [help lines] (0,0) grid (3,2); + \pic at (1,0) {seagull}; + \path (2,1) pic {seagull}; + \pic [at={(3,2)}] {seagull}; +} +\end{codeexample} + + As for nodes, except for the described shifting, the coordinate + system of a pic is reset prior to executing the pic type's + code. This can be changed using the |transform shape| option, which + has the same effect as for nodes: The ``outer'' transformation gets + applied to the node: +\begin{codeexample}[] +\tikz [scale=2] { + \pic at (0,0) {seagull}; + \pic at (1,0) [transform shape] {seagull}; +} +\end{codeexample} + + When the \meta{options} contain transformation commands like |scale| + or |rotate|, these transformations always apply to the pic: +\begin{codeexample}[] +\tikz [rotate=30] { + \pic at (0,0) {seagull}; + \pic at (1,0) [rotate=90] {seagull}; +} +\end{codeexample} + + Just like nodes, pics can also be positioned implicitly and, + somewhat unsurprisingly, the same rules concerning positioning and + sloping apply: +\begin{codeexample}[] +\tikz \draw + (0,0) to [bend left] + pic [near start] {seagull} + pic {seagull} + pic [sloped, near end] {seagull} (4,0); +\end{codeexample} + + \medskip + \textbf{The options of a node.} + As always, any given \meta{options} apply only to the pic and have + no effect outside. As for nodes, most ``outside'' options also apply + to the pics, but not the ``action'' options like |draw| or + |fill|. These must be given in the \meta{options} of the pic. + + \medskip + \textbf{The code of a pic.} + As stated earlier, the main job of a pic is to execute some code in + a scope that is shifted according to the last point on the path or + to the |at| position specified in the pic. It was also claimed that + this code is specified by the \meta{pic type}. However, this + specification is somewhat indirect. What really happens is the + following: When a |pic| is encountered, the current path is + suspended and a new internal scope is started. The \meta{options} + are executed and also the \meta{pic type} (as explained + in a moment). After all this is done, the code stored in the following key + gets executed: + + \begin{key}{/tikz/pics/code=\meta{code}} + This key stores the \meta{code} that should be drawn in the + current pic. Normally, setting this key is done by the \meta{pic + type}, but you can also set it in the \meta{options} and leave + the \meta{pic type} empty: +\begin{codeexample}[] +\tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0) + to[bend left] (3mm,0);}] + {}; % no pic type specified +\end{codeexample} + \end{key} + + Now, how does the \meta{pic type} set |pics/code|? It turns out that + the \meta{pic type} is actually just a list of keys that are + executed with the prefix |/tikz/pics/|. In the above examples, this + ``list of keys'' just consisted of the single key ``|seagull|'' that + did not take any arguments, but, in principle, you could provide any + arbitrary text understood by |\pgfkeys| here. This means that when + we write |pic{seagull}|, \tikzname\ will execute the key + |/tikz/pics/seagull|. It turns out, see + Section~\ref{section-new-pic-types}, that this key is just a style + set to |code={\draw(-3mm,0)...;}|. Thus, |pic{seagull}| will cause + the |pics/code| key to be set to the text needed to draw the + seagull. + + Indeed, you can also use the \meta{pic type} simply to set the + |code| of the pic. This is useful for cases when you have some code + that you ``just want to execute, but do not want to define a new pic + type.'' Here is a typical example where we use pics to add some + markings to a path: +\begin{codeexample}[] +\tikz \draw (0,0) .. controls(1,0) and (2,1) .. (3,1) + foreach \t in {0, 0.1, ..., 1} { + pic [pos=\t] {code={\draw circle [radius=2pt];}} + }; +\end{codeexample} + + + In our seagull example, we always explicitly used |\draw| to draw + the seagull. This implies that when a user writes something + |pic[fill]{seagull}| in the hope of having a ``filled'' seagull, + nothing special will happen: The |\draw| inside the pic explicitly + states that the path should be drawn, not filled, and the fact that + in the surrounding scope the |fill| option is set has no effect. + The following key can be used to change this: + \begin{key}{/tikz/pic action} + This key is a style that can be used (only) inside the code of a + pic. There, it will set the ``action'' keys set inside the + \meta{options} of the pic (``actions'' are drawing, filling, + shading, and clipping or any combination thereof). + + To see how this key works, let us define the following pic: +\begin{codeexample}[code only] +\tikzset{ + my pic/.pic = { + \path [pic actions] (0,0) circle[radius=3mm]; + \draw (-3mm,-3mm) rectangle (3mm,3mm); + } +} +\end{codeexample} + In the code, whether or not the circle gets drawn/filled/shaded + depends on which options where given to the |pic| command when it + is used. In contrast, the rectangle will always (just) be drawn. +\tikzset{ + my pic/.pic = { + \path [pic actions] (0,0) circle[radius=3mm]; + \draw (-3mm,-3mm) rectangle (3mm,3mm); + } +} +\begin{codeexample}[width=6cm] +\tikz \pic {my pic}; \space +\tikz \pic [red] {my pic}; \space +\tikz \pic [draw] {my pic}; \space +\tikz \pic [draw=red] {my pic}; \space +\tikz \pic [draw, shading=ball] {my pic}; \space +\tikz \pic [fill=red!50] {my pic}; +\end{codeexample} + \end{key} + + \medskip + \textbf{Code executed behind or in front of the path.} + As for nodes, a pic can be ``behind'' the current path or ``in front + of it'' and, just as for nodes, the two options |behind path| and + |in front of path| are used to specify which is meant. In detail, if + |node| and |pic| are both used repeatedly on a path, in the + resulting picture we first see all nodes and pics with the + |behind path| option set in the order they appear on the path (nodes + and pics are interchangeable in this regard), then comes the path, + and then come all nodes and pics that are in front of the path in + the order they appeared. +\begin{codeexample}[] +\tikz \fill [fill=blue!20] + (1,1) + -- (2,2) pic [behind path] {seagull} + -- (3,2) pic {seagull} + -- (3,1) pic [rotate=30] {seagull} + -- (2,1) pic [red, behind path] {seagull}; +\end{codeexample} + In contrast to nodes, a pic need not only be completely behind + the path or in front of the path as specified by the user. Instead, + a pic type may also specify that a certain part of the drawing + should always be behind the path and it may specify that a certain + other part should always be before the path. For this, the values of + the following keys are relevant: + + \begin{key}{/tikz/pics/foreground code=\meta{code}} + This key stores \meta{code} that will always be drawn in front of + the current path, even when |behind path| is used. If + |behind path| is not used and |code| is (also) set, the code of + |code| is + drawn first, following by the foreground \meta{code}. + \end{key} + + \begin{key}{/tikz/pics/background code=\meta{code}} + Like |foreground code|, only that the \meta{code} is always put + behind the path, never in front of it. + \end{key} + + \medskip + \textbf{The foreach statement for pics.} + As for nodes, a pic specification may start with |foreach|. The + effect and semantics are the same as for nodes. +\begin{codeexample}[] +\tikz \pic foreach \x in {1,2,3} at (\x,0) {seagull}; +\end{codeexample} + + \medskip + \textbf{Styles for pics.} + The following styles influence how nodes are rendered: + \begin{stylekey}{/tikz/every pic (initially \normalfont empty)} + This style is installed at the beginning of every pic. +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style={draw}] + \draw (0,0) node {A} -- (1,1) node {B}; +\end{tikzpicture} +\end{codeexample} + \end{stylekey} + + + \medskip + \textbf{Name scopes.} + You can specify a \meta{name} for a pic using the key + |name=|\meta{name} or by giving the name in parenthesis inside the + pic's specification. The effect of this is, for once, quite + different from what happens for nodes: All that happens is that + |name prefix| is set to \meta{name} at the beginning of the pic. + + The |name prefix| key was already introduced in the description of + the |node| command: It allows you to set some text that is prefixed + to all nodes in a scope. For pics this makes particular sense: All + nodes defined by a pic's code can be referenced from outside the pic + with the prefix provided. + + To see how this works, let us add some nodes to the code of the + seagull: +\begin{codeexample}[code only] +\tikzset{ + seagull/.pic={ + % Code for a "seagull". Do you see it?... + \coordinate (-left wing) at (-3mm,0); + \coordinate (-head) at (0,0); + \coordinate (-right wing) at (3mm,0); + + \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); + } +} +\end{codeexample} +\tikzset{ + seagull/.pic={ + % Code for a "seagull". Do you see it?... + \coordinate (-left wing) at (-3mm,0); + \coordinate (-head) at (0,0); + \coordinate (-right wing) at (3mm,0); + + \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing); + } +} + + Now, we can use it as follows: +\begin{codeexample}[code only] +\tikz { + \pic (Emma) {seagull}; + \pic (Alexandra) at (0,1) {seagull}; + + \draw (Emma-left wing) -- (Alexandra-right wing); +} +\end{codeexample} + + Sometimes, you may also wish your pic to access nodes outside the + pic (typically, because they are given as parameters). In this case, + the name prefix gets in the way since the nodes outside the picture + do not have this prefix. The trick is to locally reset the name + prefix to the value it had outside the picture, which is achieved + using the following style: + + \begin{key}{/tikz/name prefix ..} + This key is available only inside the code of a pic. There, it + (locally) changes the name prefix to the value it had outside the + pic. This allows you to access nodes outside the current pic. + \end{key} + +\end{pathoperation} + + +There are two general purpose keys that pics may find useful: + +\begin{key}{/tikz/pic text=\meta{text}} + This macro stores the \meta{text} in the macro |\tikzpictext|, which + is |\let| to |\relax| by default. Setting the |pic text| to some + value is the ``preferred'' way of communicating a (single) piece of + text that should become part of a pic (typically of a node). In + particular, the |quotes| library maps quoted parameters to this key. +\end{key} + +\begin{key}{/tikz/pic text options=\meta{options}} + This macro stores the \meta{options} in the macro + |\tikzpictextoptions|, which is |\let| to the empty string by + default. The |quotes| library maps options for quoted parameters to + this key. +\end{key} + + + +\subsubsection{The Quotes Syntax} +\label{section-pic-quotes} + +When you load the |quotes| library, you can use the ``quotes syntax'' +inside the options of a pic. Recall that for nodes this syntax is used +to add a label to a node. For pics, the quotes syntax is used to set +the |pic text| key. Whether or not the pic type's code takes this key +into consideration is, however, up to the key. + +In detail, when the |quotes| library is loaded, each time a key--value +pair in a list of options passed to an |pic| starts with |"|, the +key--value pair must actually be a string of the following form: +\begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} +\end{quote} +This string is transformed into the following: +\begin{quote} + |every pic quotes/.try,pic text=|\meta{text}|, pic text options={|\meta{options}|}| +\end{quote} + +As example of a pic type that takes these values into account is the +|angle| pic type: +\begin{codeexample}[] +\tikz \draw (3,0) coordinate (A) + -- (0,1) coordinate (B) + -- (1,2) coordinate (C) + pic [draw, "$\alpha$"] {angle}; +\end{codeexample} + +As described in Section~\ref{section-label-quotes}, the apostrophe +becomes part of the \meta{options}, when present. As can be seen +above, the following style is executed: +\begin{stylekey}{/tikz/every pic quotes (initially \normalfont empty)} +\end{stylekey} + +\subsection{Defining New Pic Types} +\label{section-new-pic-types} + +As explained in the description of the |pic| command, in order to +define a new pic type you need to +\begin{enumerate} +\item define a key with the path prefix |/tikz/pics| that +\item sets the key |/tikz/pics/code| to the code of the pic. +\end{enumerate} + +It turns out that this is easy enough to achieve using styles: + +\begin{codeexample}[code only] +\tikzset{ + pics/seagull/.style ={ + % Ok, this is the key that should, when + % executed, set the code key: + code = { % + \draw (...) ... ; + } + } +} +\end{codeexample} + +Even though the above pattern is easy enough, there is a special +so-called key handler that allows us to write even simpler code, +namely: + +\begin{codeexample}[code only] +\tikzset{ + seagull/.pic = { + \draw (...) ... ; + } +} +\end{codeexample} + +\begin{handler}{{.pic}|=|\meta{some code}} + This handler can only be used with a key with the prefix |/tikz/|, + so just should normally use it only as an option to a \tikzname\ + command or to the |\tikzset| command. It takes the \meta{key}'s path + and, inside that path, it replaces |/tikz/| by |/tikz/pics/| (so, + basically, it adds the ``missing'' |pics| part of the path). Then, + it sets up things so that the resulting name to key is a style that + executes |code=some code|. +\end{handler} + +In almost all cases, the |.pic| key handler will suffice to setup +keys. However, there are cases where you really need to use the first +version using |.style| and |code=|: +\begin{itemize} +\item Whenever your pic type needs to set the foreground or the + background code. +\item In case of complicated arguments given to the keys. +\end{itemize} + +As an example, let us define a simple pic that draws a filled circle +behind the path. Furthermore, we make the circle's radius a parameter +of the pic: + +\begin{codeexample}[] +\tikzset{ + pics/my circle/.style = { + background code = { \fill circle [radius=#1]; } + } +} +\tikz [fill=blue!30] + \draw (0,0) pic {my circle=2mm} -- (1,1) pic {my circle=5mm}; +\end{codeexample} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex index 00f8d874b6c..35f83f1546f 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex @@ -7,17 +7,22 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. - \section{Plots of Functions} \label{section-tikz-plots} -\subsection{When Should One Use \tikzname\ for Generating Plots? } +A warning before we get started: \emph{If you are looking for an easy + way to create a normal plot of a function with scientific axes, + ignore this section and instead look at the |pgfplots| package or at + the |datavisualization| command from Part~\ref{part-dv}.} + +\subsection{Overview} \label{section-why-pgname-for-plots} -There exist many powerful programs that produce plots, examples are -\textsc{gnuplot} or \textsc{mathematica}. These programs can produce +\tikzname\ can be used to create plots of functions, a job that is +normally handled by powerful programs like \textsc{gnuplot} or +\textsc{mathematica}. These programs can produce two different kinds of output: First, they can output a complete plot picture in a certain format (like \pdf) that includes all low-level commands necessary for drawing the complete plot (including axes and @@ -27,41 +32,41 @@ consider it a to be ``a bit boring'' to just output tabled data and very much prefer to produce fancy pictures. Nevertheless, when coaxed, they can also provide the plain data. -\emph{Note that is often not necessary to use \tikzname\ for plots.} -Programs like \textsc{gnuplot} can produce very sophisticated plots -and it is usually much easier to simply include these plots as a -finished \textsc{pdf} or PostScript graphics. - -However, there are a number of reasons why you may wish to invest time -and energy into mastering the \pgfname\ commands for creating plots: - -\begin{itemize} -\item - Virtually all plots produced by ``external programs'' use different - fonts from the one used in your document. -\item - Even worse, formulas will look totally different, if they can be - rendered at all. -\item - Line width will usually be too large or too small. -\item - Scaling effects upon inclusion can create a mismatch between sizes - in the plot and sizes in the text. -\item - The automatic grid generated by most programs is mostly - distracting. -\item - The automatic ticks generated by most programs are cryptic - numerics. (Try adding a tick reading ``$\pi$'' at the right point.) -\item - Most programs make it very easy to create ``chart junk'' in a most - convenient fashion. All show, no content. -\item - Arrows and plot marks will almost never match the arrows used in the - rest of the document. -\end{itemize} +The advantage of creating plots directly using \tikzname\ is +\emph{consistency:} Plots created using \tikzname\ will automatically +have the same styling and fonts as those used in the rest of a +document -- something that is hard to do right when an external +program gets involved. Other problems people encounter with external +programs include: Formulas will look different, if they can be +rendered at all; line widths will usually be too thick or too thin; +scaling effects upon inclusion can create a mismatch between sizes in +the plot and sizes in the text; the automatic grid generated by most +programs is mostly distracting; the automatic ticks generated by most +programs are cryptic numerics (try adding a tick reading ``$\pi$'' at +the right point); most programs make it very easy to create ``chart +junk'' in a most convenient fashion; arrows and plot marks will almost +never match the arrows used in the rest of the document. This list is +not exhaustive, unfortunately. + +There are basically three ways of creating plots using \tikzname: -The above list is not exhaustive, unfortunately. +\begin{enumerate} +\item Use the |plot| path operation. How this works is explained in + the present section. This is the most ``basic'' of the three options + and forces you to do a lot of things ``by hand'' like adding axes or + ticks. +\item Use the |datavisualization| path command, which is documented in + Part~\ref{part-dv}. This command is much more powerful that the + |plot| path operation and produces complete plots including axes and + ticks. The downside is that you cannot use it to ``just'' to quickly + plot a simple curve (or, more precisely, it is hard to use it in + this way). +\item Use the |pgfplots| package, which is basically an alternative to + the |datavisualization| command. While the underlying philosophy of + this package is not as ``ambitious'' as that of the command + |datavisualization|, it is somewhat more mature, has a + simpler design, and wider support base. +\end{enumerate} \subsection{The Plot Path Operation} @@ -87,7 +92,7 @@ The syntax of the |plot| comes in different versions. coordinate of the curve. \end{pathoperation} -The \meta{further arguments} are used in three different ways to +The \meta{further arguments} are used in different ways to specifying the coordinates of the points to be plotted: \begin{enumerate} @@ -107,7 +112,7 @@ These different ways are explained in the following. \subsection{Plotting Points Given Inline} -In the first two cases, the points are given directly in the \TeX-file +Points can be given directly in the \TeX-file as in the following example: \begin{codeexample}[] @@ -131,12 +136,19 @@ The second way of specifying points is to put them in an external file named \meta{filename}. Currently, the only file format that \tikzname\ allows is the following: Each line of the \meta{filename} should contain one line starting with two numbers, separated by a -space. Anything following the two numbers on the line is -ignored. Also, lines starting with a |%| or a |#| are ignored as well -as empty lines. (This is exactly the format that \textsc{gnuplot} -produces when you say |set terminal table|.) If necessary, more -formats will be supported in the future, but it is usually easy to -produce a file containing data in this form. +space. A line may also be empty or, if it starts with |#| or |%| it is +considered empty. For such lines, a ``new data set'' is started, +typically resulting in a new subpath being started in the plot (see +Section~\ref{section-plot-jumps} on how to change this behaviour, if +necessary). For lines containing two numbers, they must be separated +by a space. They may be following by arbitrary text, which is ignored, +\emph{except} if it is |o| or |u|. In the first case, the point is +considered to be an \emph{outlier} and normally also results in a new +subpath being started. In the second case, the point is considered to +be \emph{undefined}, which also results in a new subpath being +started. Again, see Section~\ref{section-plot-jumps} on how to change +this, if necessary. (This is exactly the format that \textsc{gnuplot} +produces when you say |set terminal table|.) \begin{codeexample}[] \tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table}; @@ -202,7 +214,7 @@ is evaluated: \end{key} \begin{key}{/tikz/domain=\meta{start}|:|\meta{end} (initially -5:5)} - Sets the domain between which the samples are taken. + Sets the domain from which the samples are taken. \end{key} \begin{key}{/tikz/samples at=\meta{sample list}} @@ -213,7 +225,7 @@ is evaluated: syntax, so you can use |...| inside the \meta{sample list}. When this option is used, the |samples| and |domain| option are - overruled. The other ways round, setting either |samples| or + overruled. The other way round, setting either |samples| or |domain| will overrule this option. \end{key} @@ -225,6 +237,7 @@ is evaluated: \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$}; \draw[color=red] plot (\x,\x) node[right] {$f(x) =x$}; + % \x r means to convert '\x' from degrees to _r_adians: \draw[color=blue] plot (\x,{sin(\x r)}) node[right] {$f(x) = \sin x$}; \draw[color=orange] plot (\x,{0.05*exp(\x)}) node[right] {$f(x) = \frac{1}{20} \mathrm e^x$}; \end{tikzpicture} @@ -246,7 +259,7 @@ is evaluated: Often, you will want to plot points that are given via a function like $f(x) = x \sin x$. Unfortunately, \TeX\ does not really have enough -computational power to generate the points on such a function +computational power to generate the points of such a function efficiently (it is a text processing program, after all). However, if you allow it, \TeX\ can try to call external programs that can easily produce the necessary points. Currently, \tikzname\ knows how to @@ -256,17 +269,14 @@ When \tikzname\ encounters your operation |plot[id=|\meta{id}|] function{x*sin(x)}| for the first time, it will create a file called \meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is |\jobname.| by -default, that is, the name of you main |.tex| file. If no \meta{id} is +default, that is, the name of your main |.tex| file. If no \meta{id} is given, it will be empty, which is alright, but it is better when each plot has a unique \meta{id} for reasons explained in a moment. Next, \tikzname\ writes some initialization code into this file followed by |plot x*sin(x)|. The initialization code sets up things such that the |plot| operation will write the coordinates into another file called \meta{prefix}\meta{id}|.table|. Finally, this table file -is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|. However, -there is just one difference: |gnuplot| supports a ``type'' field following -the coordinates. If this type field contains `|u|' which means unbounded, \tikzname\ will -ignore the complete coordinate\footnote{Thanks to Andy Schlaikjer for this patch.}. +is read as if you had said |plot file{|\meta{prefix}\meta{id}|.table}|. For the plotting mechanism to work, two conditions must be met: \begin{enumerate} @@ -342,7 +352,7 @@ plots, use |t| as the variable for parametric plots. Here are some examples: \end{codeexample} -The plot in influenced by the following options: First, the options +The plot is influenced by the following options: First, the options |samples| and |domain| explained earlier. Second, there are some more specialized options. @@ -357,6 +367,28 @@ specialized options. \end{codeexample} \end{key} +\begin{key}{/tikz/range=\meta{start}|:|\meta{end}} + This key sets the range of the plot. If set, all points whose + $y$-coordinates lie outside this range will be considered to be + outliers and will cause jumps in the plot, by default: +\begin{codeexample}[] +\tikz \draw[scale=0.5,domain=-3.141:3.141, samples=100, smooth, range=-3:3] + plot[id=tan-example] function{tan(x)}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/yrange=\meta{start}|:|\meta{end}} + Same as |range|. +\end{key} + +\begin{key}{/tikz/xrange=\meta{start}|:|\meta{end}} + Set the $x$-range. This makes sense only for parametric plots. +\begin{codeexample}[] +\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,xrange=0:1] + plot[parametric,id=parametric-example-cut] function{t*sin(t),t*cos(t)}; +\end{codeexample} +\end{key} + \begin{key}{/tikz/id=\meta{id}} Sets the identifier of the current plot. This should be a unique identifier for each plot (though things will also work if it is not, @@ -419,7 +451,7 @@ In detail, the following options govern how marks are drawn: marks. One plot mark is special: the |ball| plot mark is available only - it \tikzname. The |ball color| determines the balls's color. Do not use + in \tikzname. The |ball color| option determines the balls's color. Do not use this option with a large number of marks since it will take very long to render in PostScript. @@ -552,7 +584,8 @@ use options to change the behavior of |plot|. \end{key} \begin{key}{/tikz/const plot} - This option causes the points on the path to be connected using piecewise constant series of lines: + This option causes the points on the path to be connected using + piecewise constant series of lines: \begin{codeexample}[] \tikz\draw plot[const plot] file{plots/pgfmanual-sine.table}; @@ -573,9 +606,22 @@ use options to change the behavior of |plot|. \end{codeexample} \end{key} +\begin{key}{/tikz/const plot mark mid} + A variant of |/tikz/const plot| which places its mark in the middle + of the horizontal lines: +\begin{codeexample}[] +\tikz\draw plot[const plot mark mid,mark=*] file{plots/pgfmanual-sine.table}; +\end{codeexample} + More precisely, it generates vertical lines in the middle between + each pair of consecutive points. If the mesh width is constant, this + leads to symmetrically placed marks (``middle''). +\end{key} + \begin{key}{/tikz/jump mark left} - This option causes the points on the path to be drawn using piecewise constant, non-connected series of lines. If there are any marks, they will be placed on left open ends: + This option causes the points on the path to be drawn using + piecewise constant, non-connected series of lines. If there are any + marks, they will be placed on left open ends: \begin{codeexample}[] \tikz\draw plot[jump mark left, mark=*] file{plots/pgfmanual-sine.table}; @@ -583,11 +629,26 @@ use options to change the behavior of |plot|. \end{key} \begin{key}{/tikz/jump mark right} - This option causes the points on the path to be drawn using piecewise constant, non-connected series of lines. If there are any marks, they will be placed on right open ends: + This option causes the points on the path to be drawn using + piecewise constant, non-connected series of lines. If there are any + marks, they will be placed on right open ends: + +\begin{codeexample}[] +\tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table}; +\end{codeexample} +\end{key} + +\begin{key}{/tikz/jump mark mid} + This option causes the points on the path to be drawn using + piecewise constant, non-connected series of lines. If there are any + marks, they will be placed in the middle of the horizontal line + segments: \begin{codeexample}[] \tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table}; \end{codeexample} + + In case of non--constant mesh widths, the same remarks as for |const plot mark mid| apply. \end{key} \begin{key}{/tikz/ycomb} @@ -632,7 +693,9 @@ use options to change the behavior of |plot|. \end{key} \begin{key}{/tikz/ybar} - This option produces fillable bar plots. It is thus very similar to |ycomb|, but it employs rectangular shapes instead of line-to operations. It thus allows to use any fill- or pattern style. + This option produces fillable bar plots. It is thus very similar to + |ycomb|, but it employs rectangular shapes instead of line-to + operations. It thus allows to use any fill- or pattern style. \begin{codeexample}[] \tikz\draw[draw=blue,fill=blue!60!black] plot[ybar] file{plots/pgfmanual-sine.table}; @@ -646,7 +709,10 @@ use options to change the behavior of |plot|. plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; \end{tikzpicture} \end{codeexample} - The use of |bar width| and |bar shift| is explained in the plot handler library documentation, section~\ref{section-plotlib-bar-handlers}. Please refer to page~\pageref{key-bar-width}. + The use of |bar width| and |bar shift| is explained in the plot + handler library documentation, + section~\ref{section-plotlib-bar-handlers}. Please refer to + page~\pageref{key-bar-width}. \end{key} \begin{key}{/tikz/xbar} @@ -659,7 +725,10 @@ use options to change the behavior of |plot|. \end{key} \begin{key}{/tikz/ybar interval} - As |/tikz/ybar|, this options produces vertical bars. However, bars are centered at coordinate \emph{intervals} instead of interval edges, and the bar's width is also determined relatively to the interval's length: + As |/tikz/ybar|, this options produces vertical bars. However, bars + are centered at coordinate \emph{intervals} instead of interval + edges, and the bar's width is also determined relatively to the + interval's length: \begin{codeexample}[] \begin{tikzpicture}[ybar interval,x=10pt] @@ -667,9 +736,14 @@ use options to change the behavior of |plot|. plot coordinates{(0,2) (2,1.2) (3,.3) (5,1.7) (8,.9) (9,.9)}; \end{tikzpicture} \end{codeexample} - Since there are $N$ intervals $[x_i,x_{i+1}]$ for given $N+1$ coordinates, you will always have one coordinate more than bars. The last $y$ value will be ignored. + Since there are $N$ intervals $[x_i,x_{i+1}]$ for given $N+1$ + coordinates, you will always have one coordinate more than bars. The + last $y$ value will be ignored. - You can configure relative shifts and relative bar width, which is explained in the plot handler library documentation, section~\ref{section-plotlib-bar-handlers}. Please refer to page~\pageref{key-bar-interval-width}. + You can configure relative shifts and relative bar widths, which is + explained in the plot handler library documentation, + section~\ref{section-plotlib-bar-handlers}. Please refer to + page~\pageref{key-bar-interval-width}. \end{key} \begin{key}{/tikz/xbar interval} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex index 063b4570a7e..07d04943cc8 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-scopes.tex @@ -31,7 +31,7 @@ apply to everything within the environment. \pgfname\ needs to know what \TeX\ driver you are intending to use. In most cases \pgfname\ is clever enough to determine the correct driver - for you; this is true in particular if you use \LaTeX. Currently, the only + for you; this is true in particular if you use \LaTeX. One situation where \pgfname\ cannot know the driver ``by itself'' is when you use plain \TeX\ or Con\TeX t together with |dvipdfm|. In this case, you have to write |\def\pgfsysdriver{pgfsys-dvipdfm.def}| @@ -47,17 +47,19 @@ apply to everything within the environment. like. If you try to load a library a second time, nothing will happen. - \example |\usetikzlibrary{arrows}| + \example |\usetikzlibrary{arrows.meta}| The above command will load a whole bunch of extra arrow tip definitions. What this command does is to load the file |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in - the \meta{list of libraries}. Thus, to write your own library file, - all you need to do is to place a file of the appropriate name - somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t - users can then use your library. + the \meta{list of libraries}. If this file does not exist, the file + |pgflibrary|\meta{library}|.code.tex| is loaded instead. If this + file also does not exist, an error message is printed. Thus, to + write your own library file, all you need to do is to place a file + of the appropriate name somewhere where \TeX\ can find it. \LaTeX, + plain \TeX, and Con\TeX t users can then use your library. \end{command} @@ -111,7 +113,7 @@ they apply. coordinates. This will usually give a good approximation of the bounding box, but will not always be accurate. First, the line thickness of diagonal lines is not taken - into account correctly. Second, controls points of a curve often lie far + into account correctly. Second, control points of a curve often lie far ``outside'' the curve and make the bounding box too large. In this case, you should use the |[use as bounding box]| option. @@ -121,9 +123,11 @@ they apply. Normally, the lower end of the picture is put on the baseline of the surrounding text. For example, when you give the code |\tikz\draw(0,0)circle(.5ex);|, \pgfname\ will find out that the - lower end of the picture is at $-.5\mathrm{ex}$ and that the upper - end is at $.5\mathrm{ex}$. Then, the lower end will be put on the - baseline, resulting in the following: \tikz\draw(0,0)circle(.5ex);. + lower end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$ + (the 0.2pt are half the line width, which is 0.4pt) and that the + upper end is at $.5\mathrm{ex}+.5\mathrm{pt}$. Then, the lower end + will be put on the baseline, resulting in the following: + \tikz\draw(0,0)circle(.5ex);. Using this option, you can specify that the picture should be raised or lowered such that the height \meta{dimension} is on the @@ -138,11 +142,11 @@ $A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$ Instead of a \meta{dimension} you can also provide a coordinate in parentheses. Then the effect is to put the baseline on the - $y$-coordinate that the give \meta{coordinate} has \emph{at the + $y$-coordinate that the given \meta{coordinate} has \emph{at the end of the picture}. This means that, at the end of the picture, the \meta{coordinate} is evaluated and then the baseline is set to the $y$-coordinate of the resulting point. This makes it easy - to reference the $y$-coordinate of, say, the base line of nodes. + to reference the $y$-coordinate of, say, the baseline of nodes. \begin{codeexample}[] Hello \tikz[baseline=(X.base)] @@ -211,7 +215,7 @@ Top align: This will have the desired effect. \end{environment} -In other \TeX\ format, you should use instead the following commands: +In other \TeX\ formats, you should use the following commands instead: \begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}} This is the plain \TeX\ version of the environment. @@ -247,6 +251,23 @@ commands. \end{command} +\subsubsection{Handling Catcodes and the Babel Package} + +Inside a \tikzname\ picture, most symbols need to have the category +code 12 (normal text) in order to ensure that the parser works +properly. This is typically not the case when packages like |babel| +are used, which change catcodes aggressively. + +To solve this problem, \tikzname\ provides a small library also called +|babel| (which can, however, also be used together with any other +package that globally changes category codes). What it does is to +reset the category codes at the beginning of every |{tikzpicture}| and +to restore them at the beginning of every node. In almost all cases, +this is exactly would you would expect and need, so I recommend to +always load this library by saying |\usetikzlibrary{babel}|. For +details on what, exactly, happens with the category codes, see +Section~\ref{section-library-babel}. + \subsubsection{Adding a Background} @@ -365,6 +386,34 @@ square bracket must follow, otherwise the brace is treated as a normal \TeX\ scope. +\subsubsection{Single Command Scopes} + +In some situations it is useful to create a scope for a single +command. For instance, when you wish to use algorithm graph drawing +in order to layout a tree, the path of the tree needs to be surrounded +by a scope whose only purpose is to take a key that selects a layout +for the scope. Similarly, in order to put something on a background +layer, a scope needs to be created. In such cases, where it will +cumbersome to create a |\begin{scope}| and |\end{scope}| pair just for +a single command, the |\scoped| command may be useful: + +\begin{command}{\scoped\opt{\oarg{options}}\meta{path command}} + This command works like |\tikz|, only you can use it inside a + |{tikzpicture}|. It will take the following \meta{path command} and + put it inside a |{scope}| with the \meta{options} set. The + \meta{path command} may either be a single command ended by a + semicolon or it may contain multiple commands, but then they must be + surrounded by curly braces. + \begin{codeexample}[] +\begin{tikzpicture} + \node [fill=white] at (1,1) {Hello world}; + \scoped [on background layer] + \draw (0,0) grid (3,2); +\end{tikzpicture} + \end{codeexample} +\end{command} + + \subsubsection{Using Scopes Inside Paths} The |\path| command, which is described in much more detail in later @@ -463,7 +512,7 @@ my style/.style={draw=red,fill=red!20} \end{codeexample} The meaning of the curious |/.style| is the following: ``The key -|my style| should not be used here but, rather, be defined. So, setup +|my style| should not be used here but, rather, be defined. So, set up things such that using the key |my style| will, in the following, have the same effect as if we had written |draw=red,fill=red!20| instead.'' diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex index 5cd58695209..e5fe70f35c7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-shapes.tex @@ -19,8 +19,8 @@ another simple shape with some text on it. Nodes are added to paths using the special path operation |node|. Nodes \emph{are not part of the path - itself}. Rather, they are added to the picture after the path has -been drawn. + itself}. Rather, they are added to the picture just before or after +the path has been drawn. In Section~\ref{section-nodes-basic} the basic syntax of the node operation is explained, followed in Section~\ref{section-nodes-multi} @@ -33,8 +33,8 @@ Section~\ref{section-nodes-transformations} the different ways transformations affect nodes are studied. Sections~\ref{section-nodes-placing-1} and~\ref{section-nodes-placing-2} are about placing nodes on or next -to straight lines and curves. In -Section~\ref{section-nodes-connecting} it is explained how a node can +to straight lines and curves. +Section~\ref{section-nodes-connecting} explains how a node can be used as a ``pseudo-coordinate.'' Section~\ref{section-nodes-edges} introduces the |edge| operation, which works similar to the |to| operation and also similar to the |node| @@ -58,7 +58,7 @@ There are no special \TeX\ commands for adding a node to a picture; rather, there is path operation called |node| for this. Nodes are created whenever \tikzname\ encounters |node| or |coordinate| at a point on a path where it would expect a normal path operation (like |-- (1,1)| or -|sin (1,1)|). It is also possible to give node specifications +|rectangle (1,1)|). It is also possible to give node specifications \emph{inside} certain path operations as explained later. The node operation is typically followed by some options, which apply @@ -66,27 +66,129 @@ only to the node. Then, you can optionally \emph{name} the node by providing a name in round braces. Lastly, for the |node| operation you must provide some label text for the node in curly braces, while for the |coordinate| operation you may not. The node is placed at the -current position of the path \emph{after the path has been - drawn}. Thus, all nodes are drawn ``on top'' of the path and -retained until the path is complete. If there are several nodes on a -path, they are drawn on top of the path in the order they are -encountered. +current position of the path either \emph{after the path has been + drawn} or (more seldomly and only if you add the |behind path| +option) \emph{just before the path is drawn.} Thus, all nodes are +drawn ``on top'' or ``behind'' the path and are retained until the +path is complete. If there are several nodes on a path, perhaps some +behind and some on top of the path, first come the nodes behind the +path in the order they were encountered, then comes that path, and +then come the remaining node, again in the order they are +encountered. \begin{codeexample}[] -\tikz \fill[fill=examplefill] - (0,0) node {first node} - -- (1,1) node {second node} - -- (0,2) node {third node}; +\tikz \fill [fill=yellow!80!black] + (0,0) node {first node} + -- (1,1) node[behind path] {second node} + -- (0,2) node {third node}; \end{codeexample} +\subsubsection{Syntax of the Node Command} + The syntax for specifying nodes is the following: -\begin{pathoperation}{node}{\opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}% - \opt{|at(|\meta{coordinate}|)|}\opt{\marg{text}}} - The effect of |at| is to place the node at the coordinate given - after |at| and not, as would normally be the case, at the last - position. The |at| syntax is not available when a node is given - inside a path operation (it would not make any sense, there). +\begin{pathoperation}{node}{\opt{\meta{foreach statements}}% + \opt{|[|\meta{options}|]|}\opt{|(|\meta{name}|)|}% + \opt{|at(|\meta{coordinate}|)|}\opt{\marg{node contents}}} + Since this path operation is one of the most involved around, let us + go over it step by step. + + \medskip + \textbf{Order of the parts of the specification.} + Everything between ``|node|'' and the opening brace of a node is + optional. If there are \meta{foreach statements}, they must come + first, directly following ``|node|.'' Other than that, the ordering + of all the other elements of a node specification (the + \meta{options}, the \meta{name}, and \meta{coordinate}) is + arbitrary, indeed, there can be multiple occurrences of any of these + elements (although only for options this makes much sense). + + \medskip + \textbf{The text of a node.} + At the end of a node, you must (normally) provide some \meta{node contents} + in curly braces; indeed, the ``end'' of the node specification is + detected by the opening curly brace. For normal nodes it is possible to use + ``fragile'' stuff inside the \meta{node contents} like the |\verb| + command (for the technically savvy: code inside the \meta{node + contents} is allowed to change catcodes; however, this rule does + not apply to ``nodes on a path'' to be discussed later). + + Instead of giving \meta{node contents} at the end of the node in + curly braces, you can also use the following key: + \begin{key}{/tikz/node contents=\meta{node contents}} + \label{option-node-contents}% + This key sets that contents of the node to the given text as if + you had given it at the end in curly braces. When the option is + used inside the options of a node, the parsing of the node stops + immediately after the end of the option block. In particular, the + option block cannot be followed by further option blocks or curly + braces (or, rather, these do not count as part of the node + specification.) Also note that the \meta{node contents} may not + contain fragile stuff since the catcodes get fixed upon reading + the options. Here is an example: +\begin{codeexample}[] +\tikz { + \path (0,0) node [red] {A} + (1,0) node [blue] {B} + (2,0) node [green, node contents=C] + (3,0) node [node contents=D] ; +} +\end{codeexample} +\end{key} + + \medskip + \textbf{Specifying the location of the node.} + Nodes are placed at the last position mentioned on the path. The + effect of adding ``|at|'' to a node + specification is that the coordinate given after |at| is used + instead. The |at| syntax is not available when a node is given + inside a path operation (it would not make any sense there). + + \begin{key}{/tikz/at=\meta{coordinate}} + This is another way of specifying the |at| coordinate. Note that, + typically, you will have to enclose the \meta{coordinate} in curly + braces so that a comma inside the \meta{coordinate} does not + confuse \TeX. + \end{key} + + Another aspect of the ``location'' of a node is whether it appears + \emph{in front of} or \emph{behind} the current path. You can change + which of these two possibilities happens on a node-by-node basis + using the following keys: + \begin{key}{/tikz/behind path} + When this key is set, either as a local option for the node or + some surrounding scope, the node will be drawn behind the current + path. For this, \tikzname\ collects all nodes defined on the + current path with this option set and then inserts all of them, in + the order they appear, just before it draws the path. Thus, + several nodes with this option set may obscure one anther, but + never the path itself. ``Just before it draws the path'' actually + means that the nodes are inserted into the page output just before + any pre-actions are applied to the path (see below for what + pre-actions are). +\begin{codeexample}[] +\tikz \fill [fill=blue!50, draw=blue, very thick] + (0,0) node [behind path, fill=red!50] {first node} + -- (1.5,0) node [behind path, fill=green!50] {second node} + -- (1.5,1) node [behind path, fill=brown!50] {third node} + -- (0,1) node [ fill=blue!30] {fourth node}; +\end{codeexample} + + Note that |behind path| only applies to the current path; not to + the current scope or picture. To put a node ``behind everything'' + you need to use layers and options like |on background layer|, see + the background library in Section~\ref{section-tikz-backgrounds}. + \end{key} + \begin{key}{/tikz/in front of path} + This is the opposite of |behind path|: It causes nodes to be drawn + on top of the path. Since this is the default behaviour, you + usually do not need this option; it is only needed when an + enclosing scope has used |behind path| and you now wish to + ``switch back'' to the normal behaviour. + \end{key} + + \medskip + \textbf{The name of a node.} The |(|\meta{name}|)| is a name for later reference and it is optional. You may also add the option |name=|\meta{name} to the \meta{option} list; it has the same effect. @@ -104,17 +206,13 @@ The syntax for specifying nodes is the following: \begin{key}{/tikz/alias=\meta{another node name}} This option allows you to provide another name for the node. Giving this option multiple times will allow you to access - the node via several aliases. Using the |late options| options, - you can also assign an alias name to a node at a later point. + the node via several aliases. Using the |node also| syntax, + you can also assign an alias name to a node at a later point, see + Section~\ref{section-node-also}. \end{key} - - \begin{key}{/tikz/at=\meta{coordinate}} - This is another way of specifying the |at| coordinate. Note that, - typically, you will have to enclose the \meta{coordinate} in curly - braces so that a comma inside the \meta{coordinate} does not - confuse \TeX. - \end{key} - + + \medskip + \textbf{The options of a node.} The \meta{options} is an optional list of options that \emph{apply only to the node} and have no effect outside. The other way round, most ``outside'' options also apply to the node, but not all. For @@ -123,12 +221,14 @@ The syntax for specifying nodes is the following: |draw| or |fill|, never applies to the node and must be given in the node (unless some special other options are used, deep sigh). + \medskip + \textbf{The shape of a node.} As mentioned before, we can add a border and even a background to a node: \begin{codeexample}[] -\tikz \fill[fill=examplefill] +\tikz \fill[fill=yellow!80!black] (0,0) node {first node} - -- (1,1) node[draw] {second node} + -- (1,1) node[draw, behind path] {second node} -- (0,2) node[fill=red!20,draw,double,rounded corners] {third node}; \end{codeexample} @@ -139,16 +239,15 @@ The syntax for specifying nodes is the following: |shapes.geometric| library for the latter shape): \begin{codeexample}[] -\tikz \fill[fill=examplefill] - (0,0) node{first node} - -- (1,1) node[ellipse,draw] {second node} - -- (0,2) node[circle,fill=red!20] {third node}; +\tikz \fill[fill=yellow!80!black] + (0,0) node {first node} + -- (1,1) node[ellipse,draw, behind path] {second node} + -- (0,2) node[circle,fill=red!20] {third node}; \end{codeexample} - In the future, there might be much more complicated shapes available - such as, say, a shape for a resistor or a shape for a \textsc{uml} - class. Unfortunately, creating new shapes is a bit tricky and makes - it necessary to use the basic layer directly. Life is hard. + There are many more shapes available such as, say, a shape for a + resistor or a large arrow, see the |shapes| library in + Section~\ref{section-libs-shapes} for details. To select the shape of a node, the following option is used: \begin{key}{/tikz/shape=\meta{shape name} (initially rectangle)} @@ -163,13 +262,44 @@ The syntax for specifying nodes is the following: check whether this option is the name of some shape. If so, that shape is selected as if you had said |shape=|\meta{shape name}. - By default, the following shapes are available: |rectangle|, % this par has to be adapted: no more shapes library available, only several sublibraries - |circle|, |coordinate|, and, when the package |pgflibraryshapes| is - loaded, also |ellipse|. Details of these shapes, like their anchors + By default, the following shapes are available: |rectangle|, + |circle|, |coordinate|. Details of these shapes, like their anchors and size options, are discussed in Section~\ref{section-the-shapes}. \end{key} - The following styles influences how nodes are rendered: + \medskip + \textbf{The foreach statement for nodes.} + At the beginning of a node specification (and only there) you can provide multiple + \meta{foreach statements}, each of which has the form |foreach| \meta{var} + |in| |{|\meta{list}|}| (note that there is no slash before + |foreach|). When they are given, instead of a single node, multiple + nodes will be created: The \meta{var} will iterate over all values + of \meta{list} and for each of them, a new node is created. These + nodes are all created using all the text following the \meta{foreach + statements}, but in each copy the \meta{var} will have the current + value of the current element in the \meta{list}. + + As an example, the following two codes have the same effect: +\begin{codeexample}[] +\tikz \draw (0,0) node foreach \x in {1,2,3} at (\x,0) {\x}; +\end{codeexample} +\begin{codeexample}[] +\tikz \draw (0,0) node at (1,0) {1} node at (2,0) {2} node at (3,0) {3}; +\end{codeexample} + When you provide several |foreach| statements, they work like + ``nested loops'': +\begin{codeexample}[] +\tikz \node foreach \x in {1,...,4} foreach \y in {1,2,3} + [draw] at (\x,\y) {\x,\y}; +\end{codeexample} + As the example shows, a \meta{list} can contain ellipses (three + dots) to indicated that a larger number of numbers is meant. Indeed, + you can use the full power of the |\foreach| command here, including + multiple parameters and options, see Section~\ref{section-foreach}. + + \medskip + \textbf{Styles for nodes.} + The following styles influence how nodes are rendered: \begin{stylekey}{/tikz/every node (initially \normalfont empty)} This style is installed at the beginning of every node. \begin{codeexample}[] @@ -190,16 +320,56 @@ The syntax for specifying nodes is the following: \end{tikzpicture} \end{codeexample} \end{stylekey} + + \medskip + \textbf{Name scopes.} + It turns out that the name of a node can further be influenced using + two keys: + \begin{key}{/tikz/name prefix=\meta{text} (initially \normalfont empty)} + The value of this key is prefixed to every node inside the + current scope. This includes both the naming of the node (via + the |name| key or via the implicit |(|\meta{name}|)| syntax) as + well as any referencing of the node. Outside the scope, + the nodes can (and need to) be referenced using ``full name'' + consisting of the prefix and the node name. + + The net effect of this is that you can set the name prefix at + the beginning of a scope to some value and then use short and + simple names for the nodes inside the scope. Later, outside the + scope, you can reference the nodes via their full name: +\begin{codeexample}[] +\tikz { + \begin{scope}[name prefix = top-] + \node (A) at (0,1) {A}; + \node (B) at (1,1) {B}; + \draw (A) -- (B); + \end{scope} + \begin{scope}[name prefix = bottom-] + \node (A) at (0,0) {A}; + \node (B) at (1,0) {B}; + \draw (A) -- (B); + \end{scope} + + \draw [red] (top-A) -- (bottom-B); +} +\end{codeexample} + As can be seen, name prefixing makes it easy to write + ``recycable'' code. + \end{key} + \begin{key}{/tikz/name suffix=\meta{text} (initially \normalfont empty)} + Works as |name prefix|, only the \meta{text} is appended to + every node name in the current scope. + \end{key} \end{pathoperation} -There is a special syntax for specifying ``light-weighed'' nodes: +There is a special syntax for specifying ``light-weight'' nodes: \begin{pathoperation}{coordinate}{\opt{|[|\meta{options}|]|}|(|\meta{name}|)|\opt{|at(|\meta{coordinate}|)|}} This has the same effect as - |node[shape=coordinate][|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, + |\node[shape=coordinate]|\verb|[|\meta{options}|](|\meta{name}|)at(|\meta{coordinate}|){}|, - where the |at| part might be missing. + where the |at| part may be omitted. \end{pathoperation} Since nodes are often the only path operation on paths, there are two @@ -246,12 +416,12 @@ demonstrates the difference: \path[yshift=1.5cm,shape=rectangle] (0,0) node(a1){} (1,0) node(a2){} (1,1) node(a3){} (0,1) node(a4){}; - \filldraw[fill=examplefill] (a1) -- (a2) -- (a3) -- (a4); + \filldraw[fill=yellow!80!black] (a1) -- (a2) -- (a3) -- (a4); \path[shape=coordinate] (0,0) coordinate(b1) (1,0) coordinate(b2) (1,1) coordinate(b3) (0,1) coordinate(b4); - \filldraw[fill=examplefill] (b1) -- (b2) -- (b3) -- (b4); + \filldraw[fill=yellow!80!black] (b1) -- (b2) -- (b3) -- (b4); \end{tikzpicture} \end{codeexample} @@ -283,7 +453,7 @@ shapes: \begin{tikzpicture} \draw (0,0) node[inner sep=0pt,draw] {tight} (0cm,2em) node[inner sep=5pt,draw] {loose} - (0cm,4em) node[fill=examplefill] {default}; + (0cm,4em) node[fill=yellow!80!black] {default}; \end{tikzpicture} \end{codeexample} \end{key} @@ -312,11 +482,11 @@ shapes: exactly on the ``outside border'' of the path (not on the path itself). When the shape is filled, but not drawn, this may not be desirable. In this case, the |outer sep| should be set to zero - point. + points. \begin{codeexample}[] \begin{tikzpicture} \draw[line width=5pt] - (0,0) node[outer sep=0pt,fill=examplefill] (f) {filled} + (0,0) node[outer sep=0pt,fill=yellow!80!black] (f) {filled} (2,0) node[inner sep=.5\pgflinewidth+2pt,draw] (d) {drawn}; \draw[->] (1,-1) -- (f); @@ -393,10 +563,8 @@ node contents, but \emph{in addition} to any other transformations. \begin{codeexample}[] \tikzstyle{every node}=[dart, shape border uses incircle, inner sep=1pt, draw] -\begin{tikzpicture} - \foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45} - \node [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a}; -\end{tikzpicture} +\tikz \node foreach \a/\b/\c in {A/0/0, B/45/0, C/0/45, D/45/45} + [shape border rotate=\b, rotate=\c] at (\b/36,-\c/36) {\a}; \end{codeexample} There are two types of rotation: restricted and unrestricted. Which @@ -424,7 +592,7 @@ node contents. \end{tikzpicture} \end{codeexample} -There are \pgfname{} keys determine how a shape border is +There are \pgfname{} keys that determine how a shape border is constructed, and to specify its rotation. It should be noted that not all shapes support these keys, so reference should be made to the documentation for individual @@ -479,13 +647,13 @@ two values will be used. \label{section-nodes-multi} Most nodes just have a single simple text label. However, nodes of a -more complicated shapes might be made up from several \emph{node +more complicated shape might be made up from several \emph{node parts}. For example, in automata theory a so-called Moore state has a state name, drawn in the upper part of the state circle, and an output text, drawn in the lower part of the state circle. These two parts are quite independent. Similarly, a \textsc{uml} class shape would have a name part, a method part, and an attributes -part. Different molecule shape might use parts for the different atoms +part. Different molecule shapes might use parts for the different atoms to be drawn at the different positions, and so on. Both \pgfname\ and \tikzname\ support such multipart nodes. On the @@ -555,29 +723,68 @@ set the color used for text using the following option: \end{key} Just like the color itself, you may also wish to set the opacity of -the text only. For this, use the option |text opacity| option, which +the text only. For this, use the |text opacity| option, which is detailed in Section~\ref{section-tikz-transparency}. \subsubsection{Text Parameters: Font} -Next, you may wish to adjust the font used for the text. Use the -following option for this: +Next, you may wish to adjust the font used for the text. Naturally, +you can just use a font command like |\small| or |\rm| at the +beginning of a node. However, the following two options make it easier +to set the font used in nodes on a general basis. Let us start with: + +\begin{key}{/tikz/node font=\meta{font commands}} + This option sets the font used for all text used in a node. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[node font=\itshape] (1,0) -- +(1,1) node[above] {italic}; +\end{tikzpicture} +\end{codeexample} + Since the \meta{font commands} are executed at a very early stage in + the construction of the node, the font selected using this command + will also dictate the values of dimensions defined in terms of |em| + or |ex|. For instance, when the |minimum height| of a node is |3em|, + the actual height will be (at least) three times the line distance + selected by the \meta{font commands}: +\begin{codeexample}[] +\tikz \node [node font=\tiny, minimum height=3em, draw] {tiny}; +\tikz \node [node font=\small, minimum height=3em, draw] {small}; +\end{codeexample} +\end{key} + +The other font command is: + \begin{key}{/tikz/font=\meta{font commands}} - Sets the font used for text labels. + Sets the font used for the text inside nodes. However, this font + will \emph{not} (yet) be installed when any of the dimensions of the + node are being computed, so dimensions like |1em| will be with + respect to the font used outside the node (usually the font that was + in force when the picture started). \begin{codeexample}[] \begin{tikzpicture} - \draw[font=\itshape] (1,0) -- +(1,1) node[above] {italic}; + \node [font=\itshape] {italic}; \end{tikzpicture} \end{codeexample} - A perhaps more useful example is the following: + +\begin{codeexample}[] +\tikz \node [font=\tiny, minimum height=3em, draw] {tiny}; +\tikz \node [font=\small, minimum height=3em, draw] {small}; +\end{codeexample} + + A useful example of how the |font| option can be used is the + following: \begin{codeexample}[] \tikz [every text node part/.style={font=\itshape}, every lower node part/.style={font=\footnotesize}] \node [circle split,draw] {state \nodepart{lower} output}; \end{codeexample} -\end{key} + As can be seen, the font can be changed for each node part. This + does \emph{not} work with the |node font| command since, as the name + suggests, this command can only be used to select the ``overall'' + font for the node and this is done very early. +\end{key} \subsubsection{Text Parameters: Alignment and Width for Multi-Line Text} @@ -615,7 +822,7 @@ lines of text. There are three different ways of achieving this: The |\\| command takes an optional extra space as an argument in square brackets. \begin{codeexample}[] -\tikz \node[fill=examplefill,align=right] +\tikz \node[fill=yellow!80!black,align=right] {This is a\\[-2pt] demonstration text for\\[1ex] alignments.}; \end{codeexample} \item You can request that \tikzname\ does an automatic line-breaking @@ -640,45 +847,45 @@ Let us now first have a look at the |text width| command. change the alignment using |align| or directly using commands line |\centering|. \begin{codeexample}[] -\tikz \draw (0,0) node[fill=examplefill,text width=3cm] +\tikz \draw (0,0) node[fill=yellow!80!black,text width=3cm] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} Setting \meta{dimension} to an empty string causes the automatic line breaking to be disabled. \end{key} -\begin{key}{/tikz/align=\meta{how}} - This key is used to setup an alignment for multi-line text inside a +\begin{key}{/tikz/align=\meta{alignment option}} + This key is used to set up an alignment for multi-line text inside a node. If |text width| is set to some width (let us call this \emph{alignment with line breaking}), the |align| key will setup the |\leftskip| and the |\rightskip| in such a way that the - text is broken and aligned according to \meta{how}. If |text width| + text is broken and aligned according to \meta{alignment option}. If |text width| is not set (that is, set to the empty string; let us call this \emph{alignment without line breaking}), then a different mechanism is used internally, namely the key |node halign header|, is set to an appropriate value. While this key, which is documented below, is not to be used by beginners, the net effect is simple: When |text width| is not set, you can use |\\| to break lines and - align them according to \meta{how} and the resulting node's width + align them according to \meta{alignment option} and the resulting node's width will be minimal to encompass the resulting lines. - In detail, you can set \meta{how} to one of the following values: + In detail, you can set \meta{alignment option} to one of the following values: \begin{description} \item[|align=|\declare{|left|}] For alignment without line breaking, the different lines are simply aligned such that their left borders are below one another. \begin{codeexample}[] -\tikz \node[fill=examplefill,align=left] +\tikz \node[fill=yellow!80!black,align=left] {This is a\\ demonstration text for\\ alignments.}; \end{codeexample} For alignment with line breaking, the same will happen only the lines will now, additionally, be broken automatically: \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=left] +\tikz \node[fill=yellow!80!black,text width=3cm,align=left] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - \item[|align=|\declare{|flush left|}] + \item[|align=|\declare{\texttt{flush left}}] For alignment without line breaking this option has exactly the same effect as |left|. However, for alignment with line breaking, there is a difference: While |left| uses the @@ -689,55 +896,79 @@ Let us now first have a look at the |text width| command. it may be useful for very narrow boxes and when you wish to avoid hyphenations. \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=flush left] +\tikz \node[fill=yellow!80!black,text width=3cm,align=flush left] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} \item[|align=|\declare{|right|}] Works like |left|, only for right alignment. \begin{codeexample}[] -\tikz \node[fill=examplefill,align=right] +\tikz \node[fill=yellow!80!black,align=right] {This is a\\ demonstration text for\\ alignments.}; \end{codeexample} \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=right] +\tikz \node[fill=yellow!80!black,text width=3cm,align=right] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - \item[|align=|\declare{|flush right|}] + \item[|align=|\declare{\texttt{flush right}}] Works like |flush left|, only for right alignment. \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=flush right] +\tikz \node[fill=yellow!80!black,text width=3cm,align=flush right] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} \item[|align=|\declare{|center|}] Works like |left| or |right|, only for centered alignment. \begin{codeexample}[] -\tikz \node[fill=examplefill,align=center] +\tikz \node[fill=yellow!80!black,align=center] {This is a\\ demonstration text for\\ alignments.}; \end{codeexample} \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=center] +\tikz \node[fill=yellow!80!black,text width=3cm,align=center] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} - \item[|align=|\declare{|flush center|}] - Works like |flush left| or |flush right|, only for center alignment. + There is one annoying problem with the |center| + alignment (but not with |flush center| and the other options): If + you specify a large line width and the node text + fits on a single line and is, in fact, much shorter than the + specified |text width|, an underfull horizontal box will + result. Unfortunately, this cannot be avoided, due to the way \TeX\ works. + For this reason, \tikzname\ switches off horizontal badness + warnings inside boxes with |align=center|. Since this will also + suppress some ``wanted'' warnings, there is also an option for + switching the warnings on once more: + + \begin{key}{/tikz/badness warnings for centered text=\meta{true or + false} (initially false)} + If set to true, normal badness warnings will be issued for + centered boxes. Note that you may get annoying warnings for + perfectly normal boxes, namely whenever the box is very large + and the contents is not long enough to fill the box + sufficiently. + \end{key} + + \item[|align=|\declare{\texttt{flush center}}] + Works like |flush left| or |flush right|, only for center + alignment. Because of all the trouble that results from the + |center| option in conjunction with narrow lines, I suggest picking + this option rather than |center| \emph{unless} you have longer + text, in which case |center| will give the typographically better + results. \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=flush center] +\tikz \node[fill=yellow!80!black,text width=3cm,align=flush center] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} \item[|align=|\declare{|justify|}] For alignment without line breaking, this has the same effect as |left|. For alignment with line breaking, this causes the text to - be ``justified.'' Use this - only with pretty broad nodes. + be ``justified.'' Use this only with rather broad nodes. {% \hbadness=10000 \begin{codeexample}[] -\tikz \node[fill=examplefill,text width=3cm,align=justify] +\tikz \node[fill=yellow!80!black,text width=3cm,align=justify] {This is a demonstration text for showing how line breaking works.}; \end{codeexample} } @@ -759,7 +990,7 @@ Let us now first have a look at the |text width| command. with the |\halign| command. This key only has an effect if |text width| - is empty, otherwise it is ignored. Furthermore, if \meta{header} is + is empty, otherwise it is ignored. Furthermore, if \meta{macro storing a header} is empty, then this key also has no effect. So, suppose |text width| is empty, but \meta{header} is not. In this case the following happens: @@ -858,7 +1089,7 @@ better to have the node to the right or above the actual coordinate. \subsubsection{Positioning Nodes Using Anchors} \pgfname\ uses a so-called anchoring mechanism to give you a very fine -control over the placement. The idea is simple: Imaging a node of +control over the placement. The idea is simple: Imagine a node of rectangular shape of a certain size. \pgfname\ defines numerous anchor positions in the shape. For example to upper right corner is called, well, not ``upper right anchor,'' but the |north east| anchor of the @@ -1090,7 +1321,7 @@ differently. automatically used, as explained later. The effect of this option is the following. First, the point - |(|\meta{number of dimension 2}|,|\meta{number or dimension 1}|)| + |(|\meta{number or dimension 2}|,|\meta{number or dimension 1}|)| is computed (note the inversed order), using the normal rules for evaluating such a coordinate, yielding some position. Then, the node is shifted by the vertical component of this point. The @@ -1106,8 +1337,8 @@ differently. The \meta{shifting part} can optionally be followed by a \meta{of-part}, which has one of the following forms: \begin{enumerate} - \item The \meta{of-part} can be declare{|of |\meta{coordinate}}, - where\meta{coordinate} is \emph{not} in parentheses and it is + \item The \meta{of-part} can be \declareandlabel{of}| |\meta{coordinate}, + where \meta{coordinate} is \emph{not} in parentheses and it is \emph{not} just a node name. An example would be |of somenode.north| or |of 2,3|. In this case, the following happens: First, the node's |at| parameter is set to the @@ -1129,9 +1360,9 @@ differently. |somenode|. The same effect could have been achieved writing |above=5mm| followed by |at=(somenode.north east)|. - If the \meta{shift-part} is missing, the shift is not zero, but + If the \meta{shifting-part} is missing, the shift is not zero, but rather the value of the |node distance| key is used, see below. - \item The \meta{of-part} can have be |of |\meta{node name}. An + \item The \meta{of-part} can be |of |\meta{node name}. An example would be |of somenode|. In this case, the following usually happens: \begin{itemize} @@ -1160,8 +1391,7 @@ differently. \begin{key}{/tikz/on grid=\meta{boolean} (initially false)} When this key is set to |true|, an \meta{of-part} of the current form behaves differently: The anchors set for the - current node as well as the anchor used for other \meta{node - name} are set the |center|. + current node as well as the anchor used for the other \meta{node name} are set to |center|. This has the following effect: When you say |above=1cm of somenode| with |on grid| set to true, the new node @@ -1256,13 +1486,6 @@ differently. \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw,circle}] \draw[help lines] (0,0) grid (2,5); - \begin{scope}[node distance=5mm] - \node (a) at (1,1) {a}; - \node [left=of a] {1}; \node [right=of a] {2}; - \node [above=of a] {3}; \node [below=of a] {4}; - \node [above left=of a] {5}; \node [above right=of a] {6}; - \node [below left=of a] {7}; \node [below right=of a] {8}; - \end{scope} \begin{scope}[node distance=5mm and 5mm] \node (b) at (1,4) {b}; \node [left=of b] {1}; \node [right=of b] {2}; @@ -1270,11 +1493,6 @@ differently. \node [above left=of b] {5}; \node [above right=of b] {6}; \node [below left=of b] {7}; \node [below right=of b] {8}; \end{scope} -\end{tikzpicture} -\end{codeexample} -\begin{codeexample}[] -\begin{tikzpicture}[every node/.style={draw,rectangle}] - \draw[help lines] (0,0) grid (2,5); \begin{scope}[node distance=5mm] \node (a) at (1,1) {a}; \node [left=of a] {1}; \node [right=of a] {2}; @@ -1282,6 +1500,11 @@ differently. \node [above left=of a] {5}; \node [above right=of a] {6}; \node [below left=of a] {7}; \node [below right=of a] {8}; \end{scope} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style={draw,rectangle}] + \draw[help lines] (0,0) grid (2,5); \begin{scope}[node distance=5mm and 5mm] \node (b) at (1,4) {b}; \node [left=of b] {1}; \node [right=of b] {2}; @@ -1289,6 +1512,13 @@ differently. \node [above left=of b] {5}; \node [above right=of b] {6}; \node [below left=of b] {7}; \node [below right=of b] {8}; \end{scope} + \begin{scope}[node distance=5mm] + \node (a) at (1,1) {a}; + \node [left=of a] {1}; \node [right=of a] {2}; + \node [above=of a] {3}; \node [below=of a] {4}; + \node [above left=of a] {5}; \node [above right=of a] {6}; + \node [below left=of a] {7}; \node [below right=of a] {8}; + \end{scope} \end{tikzpicture} \end{codeexample} \begin{codeexample}[] @@ -1315,10 +1545,10 @@ differently. \begin{key}{/tikz/below left=\opt{\meta{specification}}} Works similar to |above left|. \end{key} -\begin{key}{/tikz/above left=\opt{\meta{specification}}} +\begin{key}{/tikz/above right=\opt{\meta{specification}}} Works similar to |above left|. \end{key} -\begin{key}{/tikz/above right=\opt{\meta{specification}}} +\begin{key}{/tikz/below right=\opt{\meta{specification}}} Works similar to |above left|. \end{key} @@ -1359,7 +1589,7 @@ keys: -\subsubsection{Arranging Nodes Using a Chains and Matrices} +\subsubsection{Arranging Nodes Using Chains and Matrices} The simple |above| and |right| options may not always suffice for arranging a large number of nodes. For such situations \tikzname\ @@ -1379,11 +1609,11 @@ It is sometimes desirable that the size and position of a node is not given using anchors and size parameters, rather one would sometimes have a box be placed and be sized such that it ``is just large enough to contain this, that, and that point.'' This situation typically -arises when a picture has been drawn an, afterwards, parts of the +arises when a picture has been drawn and, afterwards, parts of the picture are supposed to be encircled or highlighted. In this situation the |fit| option from the |fit| library is useful, -see Section~\ref{section-library-fit} for a the details. The idea is +see Section~\ref{section-library-fit} for the details. The idea is that you may give the |fit| option to a node. The |fit| option expects a list of coordinates (one after the other without commas) as its parameter. The effect will be that the node's text area has exactly @@ -1435,7 +1665,7 @@ transformed. Scaling text is evil, rotating slightly less so. However, sometimes you \emph{do} wish to transform a node, for example, it certainly sometimes makes sense to rotate a node by -90 degrees. There are two ways in which you can achieve this: +90 degrees. There are two ways to achieve this: \begin{enumerate} \item @@ -1447,7 +1677,7 @@ example, it certainly sometimes makes sense to rotate a node by will get a ``huge'' X in your graphic. \end{key} \item - You can give transformation option \emph{inside} the option list of + You can give transformation options \emph{inside} the option list of the node. \emph{These} transformations always apply to the node. \begin{codeexample}[] \begin{tikzpicture}[every node/.style={draw}] @@ -1463,6 +1693,41 @@ example, it certainly sometimes makes sense to rotate a node by \end{enumerate} +Even though \tikzname\ currently does not allow you to configure +so-called \emph{nonlinear transformations,} see +Section~\ref{section-nonlinear-transformations}, there is an option +that influences how nodes are transformed when nonlinear +transformations are in force: + +\begin{key}{/tikz/transform shape nonlinear=\opt{\meta{true or false}} (initially false)} + When set to true, \tikzname\ will try to apply any current nonlinear + transformation also to nodes. Typically, for the text in nodes this + is not possible in general, in such cases a linear approximation of + the nonlinear transformation is used. For more details, see + Section~\ref{section-nonlinear-transformations}. +\makeatletter +\begin{codeexample}[] +\begin{tikzpicture} + % Install a nonlinear transformation: + \pgfsetcurvilinearbeziercurve + {\pgfpoint{0mm}{20mm}} + {\pgfpoint{10mm}{20mm}} + {\pgfpoint{10mm}{10mm}} + {\pgfpoint{20mm}{10mm}} + \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}% + + % Draw something: + \draw [help lines] (0,-30pt) grid [step=10pt] (80pt,30pt); + + \foreach \x in {0,20,...,80} + \node [fill=red!20] at (\x pt, -20pt) {\x}; + + \foreach \x in {0,20,...,80} + \node [fill=blue!20, transform shape nonlinear] at (\x pt, 20pt) {\x}; +\end{tikzpicture} +\end{codeexample} +\end{key} + \subsection{Placing Nodes on a Line or Curve Explicitly} @@ -1485,7 +1750,7 @@ ways are described in the following. coordinate. Rather, it is anchored on some point on the line from the previous coordinate to the current point. The \meta{fraction} dictates how ``far'' on the line the point should be. A - \meta{fraction} or 0 is the previous coordinate, 1 is the current + \meta{fraction} of 0 is the previous coordinate, 1 is the current one, everything else is in between. In particular, 0.5 is the middle. @@ -1499,6 +1764,16 @@ ways are described in the following. node[pos=0]{0} node[pos=0.5]{1/2} node[pos=0.9]{9/10}; \end{codeexample} + For the |arc| operation, the position is simply the corresponding + position on the arc: +\begin{codeexample}[] +\tikz { + \draw [help lines] (0,0) grid (3,2); + \draw (2,0) arc [x radius=1, y radius=2, start angle=0, end angle=180] + node foreach \t in {0,0.125,...,1} [pos=\t,auto] {\t}; +} +\end{codeexample} + The next case is the curve-to operation (the |..| operation). In this case, the ``middle'' of the curve, that is, the position |0.5| is not necessarily the point at the exact half distance on the @@ -1509,10 +1784,10 @@ ways are described in the following. connect the start and end points to the control points). The exact math is a bit complicated (depending on your point of view, of course); you may wish to consult a good book on computer graphics - and Bézier curves if you are intrigued. + and B\'ezier curves if you are intrigued. \begin{codeexample}[] - \tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3) - \foreach \p in {0,0.125,...,1} {node[pos=\p]{\p}}; +\tikz \draw (0,0) .. controls +(right:3.5cm) and +(right:3.5cm) .. (0,3) + node foreach \p in {0,0.125,...,1} [pos=\p]{\p}; \end{codeexample} Another interesting case are the horizontal/vertical line-to operations @@ -1530,11 +1805,10 @@ ways are described in the following. \end{codeexample} For all other path construction operations, \emph{the position - placement does not work}, currently. This will hopefully change in - the future (especially for the arc operation). + placement does not work}, currently. \end{key} -\begin{key}{/tikz/auto=\meta{left or right} (default \normalfont is scope's setting)} +\begin{key}{/tikz/auto=\opt{\meta{direction}} (default \normalfont is scope's setting)} This option causes an anchor positions to be calculated automatically according to the following rule. Consider a line between to points. If the \meta{direction} is |left|, then the @@ -1577,10 +1851,10 @@ ways are described in the following. \draw[help lines,use as bounding box] (0,-.5) grid (4,5); \draw (0.5,0) .. controls (9,6) and (-5,6) .. (3.5,0) - \foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1} - {node [pos=\pos,swap,fill=red!20] {\pos}} - \foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975} - {node [pos=\pos,fill=blue!20] {\pos}}; + node foreach \pos in {0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1} + [pos=\pos,swap,fill=red!20] {\pos} + node foreach \pos in {0.025,0.2,0.4,0.6,0.8,0.975} + [pos=\pos,fill=blue!20] {\pos}; \end{tikzpicture} \end{codeexample} \begin{codeexample}[] @@ -1602,6 +1876,10 @@ ways are described in the following. \end{codeexample} \end{key} +\begin{key}{/tikz/'} + This is a very short alias for |swap|. +\end{key} + \begin{key}{/tikz/sloped} This option causes the node to be rotated such that a horizontal line becomes a tangent to the curve. The rotation is normally @@ -1610,7 +1888,7 @@ ways are described in the following. |[allow upside down]|, see below. \begin{codeexample}[] \tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) - \foreach \p in {0,0.25,...,1} {node[sloped,above,pos=\p]{\p}}; + node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; \end{codeexample} \begin{codeexample}[] \begin{tikzpicture}[->] @@ -1626,7 +1904,7 @@ ways are described in the following. \begin{codeexample}[] \tikz [allow upside down] \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) - \foreach \p in {0,0.25,...,1} {node[sloped,above,pos=\p]{\p}}; + node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; \end{codeexample} \begin{codeexample}[] \begin{tikzpicture}[->,allow upside down] @@ -1642,13 +1920,13 @@ There exist styles for specifying positions a bit less ``technically'': This has the same effect as |pos=0.5|. \begin{codeexample}[] \tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5) - node[at end] {|at end|} - node[very near end] {|very near end|} - node[near end] {|near end|} - node[midway] {|midway|} - node[near start] {|near start|} - node[very near start] {|very near start|} - node[at start] {|at start|}; + node[at end] {\texttt{at end}} + node[very near end] {\texttt{very near end}} + node[near end] {\texttt{near end}} + node[midway] {\texttt{midway}} + node[near start] {\texttt{near start}} + node[very near start] {\texttt{very near start}} + node[at start] {\texttt{at start}}; \end{codeexample} \end{stylekey} @@ -1730,9 +2008,39 @@ the operation with the |pos| option set. \subsection{The Label and Pin Options} -In addition to the |node| path operation, nodes can also be added -using the |label| and the |pin| option. This is mostly useful -for simple nodes. +\subsubsection{Overview} + +In addition to the |node| path operation, the two options |label| and +|pin| can be used to ``add a node next to another node''. As an +example, suppose we want to draw a graph in which the nodes are +small circles: +\begin{codeexample}[] +\tikz [circle] { + \node [draw] (s) {}; + \node [draw] (a) [right=of s] {} edge (s); + \node [draw] (b) [right=of a] {} edge (a); + \node [draw] (t) [right=of b] {} edge (b); +} +\end{codeexample} + +Now, in the above example, suppose we wish to indicate that the first +node is the start node and the last node is the target node. We could +write |\node (s) {$s$};|, but this would enlarge the first +node. Rather, we want the ``$s$'' to be placed next to the node. For +this, we need to create \emph{another} node, but next to the existing +node. The |label| and |pin| option allow us to do exactly this without +having to use the cumbersome |node| syntax: + +\begin{codeexample}[] +\tikz [circle] { + \node [draw] (s) [label=$s$] {}; + \node [draw] (a) [right=of s] {} edge (s); + \node [draw] (b) [right=of a] {} edge (a); + \node [draw] (t) [right=of b, label=$t$] {} edge (b); +} +\end{codeexample} + +\subsubsection{The Label Option} \begin{key}{/tikz/label=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}} \label{label-option}% @@ -1780,20 +2088,34 @@ for simple nodes. \node [transform shape,rectangle,draw,label=right:label] {main node}; \end{codeexample} \end{key} - \item Then, an anchor point for the |label node|. It is determined - in such a way that the |labe node| will ``face away'' from the + \item Then, an anchor point for the |label node| is computed. It is determined + in such a way that the |label node| will ``face away'' from the border of the |main node|. The anchor that is chosen depends on the position of the border point that is chosen and its position relative to the center of the |main node| and on whether the - |transform shape| option is set. In general, the choice should be - what you would expect, but you may have to set the anchor yourself - in difficult situations. -\begin{codeexample}[] -\tikz - \node [circle,draw, + |transform shape| option is set. In detail, when the computed + border point is at $0^\circ$, the anchor |west| will be + used. Similarly, when the border point is at $90^\circ$, the + anchor |south| will be used, and so on for $180^\circ$ and + $270^\circ$. + + For angles between these ``major'' angles, like + $30^\circ$ or $110^\circ$, combined anchors, like |south west| for + $30^\circ$ or |south east| for $110^\circ$, are used. However, for + angles close to the major angles, (differing by up to $2^\circ$ + from the major angle), the anchor for the major angle is + used. Thus, a label at a border point for $2^\circ$ will have the + anchor |west|, while a label for $3^\circ$ will have the anchor + |south west|, resulting in a ``jump'' of the anchor. If this is + not desired, you will have to set the anchor yourself. +\begin{codeexample}[] +\tikz + \node [circle, draw, label=default, label=60:$60^\circ$, - label=below:$-90^\circ$] {my circle}; + label=below:$-90^\circ$, + label=3:$3^\circ$, + label=2:$2^\circ$] {my circle}; \end{codeexample} \item One \meta{angle} is special: If you set the \meta{angle} to @@ -1842,9 +2164,12 @@ for simple nodes. \end{stylekey} \end{key} + +\subsubsection{The Pin Option} + \begin{key}{/tikz/pin=\opt{|[|\meta{options}|]|}\meta{angle}|:|\meta{text}} - This is option is quite similar to the |label| option, but there is - one difference: In addition to adding a extra node to the picture, + This option is quite similar to the |label| option, but there is + one difference: In addition to adding an extra node to the picture, it also adds an edge from this node to the main node. This causes the node to look like a pin that has been added to the main node: \begin{codeexample}[] @@ -1901,6 +2226,213 @@ for simple nodes. \end{key} +\subsubsection{The Quotes Syntax} +\label{section-label-quotes} + +The |label| and |pin| option provide a syntax for +creating nodes next to existing nodes, but this syntax is often a +bit too verbose. By including the following library, you get access to +an even more concise syntax: + +\begin{tikzlibrary}{quotes} + Enables the quotes syntax for labels, pins, edge nodes, and pic + texts. +\end{tikzlibrary} + +Let us start with the basics of what this library does: Once loaded, +inside the options of a |node| command, instead of the usual +\meta{key}|=|\meta{value} pairs, you may also provide strings of the +following form (the actual syntax slightly more general, see the +detailed descriptions later on): +\begin{quote} + |"|\meta{text}|"|\opt{\meta{options}} +\end{quote} +The \meta{options} must be surrounded in curly braces when they +contain a comma, otherwise the curly braces are optional. The may be +preceded by an optional space. + +When a \meta{string} of the above form is encountered inside the +options of a |node|, then it is internally transformed to +\begin{quote} + |label={[|\meta{options}|]|\meta{text}|}| +\end{quote} + +Let us have a look at an example: +\begin{codeexample}[] +\tikz \node ["my label" red, draw] {my node}; +\end{codeexample} +The above has the same effect as the following: +\begin{codeexample}[] +\tikz \node [label={[red]my label}, draw] {my node}; +\end{codeexample} + +Here are further examples, one where no \meta{options} are added +to the |label|, one where a position is specified, and examples with +more complicated options in curly braces: + +\begin{codeexample}[] +\begin{tikzpicture} + \matrix [row sep=5mm] { + \node [draw, "label"] {A}; \\ + \node [draw, "label" left] {B}; \\ + \node [draw, "label" color=red] {C}; \\ + \node [draw, "label" {red,draw,thick}] {D}; \\ + }; +\end{tikzpicture} +\end{codeexample} + +Let us now have a more detailed look at what which commands this +library provides: + +\begin{key}{/tikz/quotes mean label} + When this option is used (which is the default when this library is + loaded), then, as described above, inside the options of a node a + special syntax check is done. + + \medskip + \noindent\textbf{The syntax.} + For each string in the list of options + it is tested whether it starts with a quotation mark (note that this + will never happen for normal keys since the normal keys of + \tikzname\ do not start with quotation marks). When this happens, + the \meta{string} should not be a key--value pair, but, rather, must + have the form: + \begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + \end{quote} + + (We will discuss the optional apostrophe in a moment. It is not + really important for the current option, but only for + edge labels, which are discussed later). + + \medskip + \noindent\textbf{Transformation to a label option.} + When a \meta{string} has the above form, it is treated (almost) as + if you had written + \begin{quote} + |label={[|\meta{options}|]|\meta{text}|}| + \end{quote} + instead. The ``almost'' refers to the following additional feature: + In reality, before the \meta{options} are executed inside the + |label| command, the direction keys |above|, |left|, |below right| + and so on are redefined so that |above| is a shorthand for + |label position=90| and similarly for the other keys. The net effect + is that in order to specify the position of the \meta{text} relative + to the main node you can just put something like |left| or + |above right| inside the \meta{options}: +\begin{codeexample}[] +\tikz + \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; +\end{codeexample} + + Alternatively, you can also use \meta{direction}|:|\meta{actual + text} as your \meta{text}. This works since the |label| command + allows you to specify a direction at the beginning when it is + separated by a colon: +\begin{codeexample}[] +\tikz + \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; +\end{codeexample} + Arguably, placing |above| or |left| behind the \meta{text} seems + more natural than having it inside the \meta{text}. + + In addition to the above, before the \meta{options} are executed, + the following style is also executed: + \begin{stylekey}{/tikz/every label quotes} +\begin{codeexample}[] +\tikz [every label quotes/.style=red] + \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; +\end{codeexample} + \end{stylekey} + + \medskip + \noindent\textbf{Handling commas and colons inside the text.} + The \meta{text} may not contain a comma, unless it is inside curly + braces. The reason is that the key handler separates the total + options of a |node| along the commas it finds. So, in order to have + text containing a comma, just add curly braces around either the + comma or just around the whole \meta{text}: +\begin{codeexample}[] +\tikz \node ["{yes, we can}", draw] {foo}; +\end{codeexample} + The same is true for a colon, only in this case you may need to + surround specifically the colon by curly braces to stop the |label| + option from interpreting everything before the colon as a direction: +\begin{codeexample}[] +\tikz \node ["yes{:} we can", draw] {foo}; +\end{codeexample} + + \medskip + \noindent\textbf{The optional apostrophe.} + Following the closing quotation marks in a \meta{string} there may + (but need + not) be a single quotation mark (an apostrophe), possibly surrounded + by whitespaces. If it is present, it is simply added to the + \meta{options} as another option (and, indeed, a single apostrophe + is a legal option in \tikzname, it is a shorthand for |swap|): + + \begin{tabular}{ll} + String & has the same effect as \\\hline + |"foo"'| & |"foo" {'}| \\ + |"foo"' red| & |"foo" {',red}| \\ + |"foo"'{red}| & |"foo" {',red}| \\ + |"foo"{',red}| & |"foo" {',red}| \\ + |"foo"{red,'}| & |"foo" {red,'}| \\ + |"foo"{'red}| & |"foo" {'red}| (illegal; there is no key |'red|)\\ + |"foo" red'| & |"foo" {red'}| (illegal; there is no key |red'|)\\ + \end{tabular} +\end{key} + +\begin{key}{/tikz/quotes mean pin} + This option has exactly the same effect as |quotes mean label|, only + instead of transforming quoted text to the |label| option, they get + transformed to the |pin| option: +\begin{codeexample}[] +\tikz [quotes mean pin] + \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; +\end{codeexample} + Instead of |every label quotes|, the following style is executed + with each such pin: + \begin{stylekey}{/tikz/every pin quotes} + \end{stylekey} +\end{key} + +If instead of |label|s or |pin|s you would like quoted strings to be +interpreted in a different manner, you can also define your own +handlers: + +\begin{key}{/tikz/node quotes mean=\meta{replacement}} + This key allows you to define your own handler for quotes + options. Inside the options of a |node|, whenever a key--value pair + with the syntax + \begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} + \end{quote} + is encountered, the following happens: The above string gets + replaced by \meta{replacement} where inside the \meta{replacement} + the parameter |#1| is \meta{text} and |#2| is \meta{options}. If the + apostrophe is present (see also the discussion of + |quotes mean label|), the \meta{options} start with |',|. + + The \meta{replacement} is then parsed normally as options (using + |\pgfkeys|). + + Here is an example, where the quotes are used to define labels that + are automatically named according to the |text|: +\begin{codeexample}[] +\tikzset{node quotes mean={label={[#2,name={#1}]#1}}} + +\tikz { + \node ["1", "2" label position=left, circle, draw] {circle}; + \draw (1) -- (2); +} +\end{codeexample} +\end{key} + +Some further options provided by the |quotes| library concern labels +next to edges rather than nodes and they are described in +Section~\ref{section-edge-quotes}. + \subsection{Connecting Nodes: Using Nodes as Coordinates} \label{section-nodes-connecting} @@ -1925,7 +2457,7 @@ Section~\ref{section-node-coordinates}. Suppose you have said same effect. However, for most other shapes, some path construction operations like - |--| try to be ``clever'' when this they are asked to draw a line + |--| try to be ``clever'' when they are asked to draw a line from such a coordinate or to such a coordinate. When you say |(x)--(1,1)|, the |--| path operation will not draw a line from the center of |x|, but \emph{from the border} of |x| in the direction going @@ -1955,9 +2487,11 @@ Section~\ref{section-node-coordinates}. Suppose you have said \label{section-nodes-edges} +\subsubsection{Basic Syntax of the Edge Operation} + The |edge| operation works like a |to| operation that is added after the main path has been drawn, much like a node is added after the main -path has been drawn. This allows you to have each |edge| to have a +path has been drawn. This allows each |edge| to have a different appearance. As the |node| operation, an |edge| temporarily suspends the construction of the current path and a new path $p$ is constructed. This new path $p$ will be drawn after the main path has @@ -1965,7 +2499,7 @@ been drawn. Note that $p$ can be totally different from the main path with respect to its options. Also note that if there are several |to| and/or |node| operations in the main path, each creates its own path(s) and they are drawn in the order that they -are encountered on the path. +are encountered on the main path. \begin{pathoperation}{edge}{\opt{|[|\meta{options}|]|} \opt{\meta{nodes}} |(|\meta{coordinate}|)|} @@ -2013,8 +2547,8 @@ are encountered on the path. \begin{codeexample}[] \begin{tikzpicture} - \foreach \name/\angle in {a/0,b/90,c/180,d/270} - \node (\name) at (\angle:1) {$\name$}; + \node foreach \name/\angle in {a/0,b/90,c/180,d/270} + (\name) at (\angle:1) {$\name$}; \path[->] (b) edge (a) edge (c) @@ -2030,8 +2564,8 @@ are encountered on the path. \begin{codeexample}[] \begin{tikzpicture} - \foreach \name/\angle in {a/0,b/90,c/180,d/270} - \node (\name) at (\angle:1.5) {$\name$}; + \node foreach \name/\angle in {a/0,b/90,c/180,d/270} + (\name) at (\angle:1.5) {$\name$}; \path[->] (b) edge node[above right] {$5$} (a) edge (c) @@ -2045,18 +2579,98 @@ are encountered on the path. Instead of |every to|, the style |every edge| is installed at the beginning of the main path. - \begin{stylekey}{/tikz/every edge (inititially draw)} % inititially --> initially? (ff) (this is the definition of the key, so please have a look) + \begin{stylekey}{/tikz/every edge (initially draw)} Executed for each |edge|. \begin{codeexample}[] \begin{tikzpicture}[every to/.style={draw,dashed}] - \path (0,0) to (3,2); + \path (0,0) edge (3,2); \end{tikzpicture} \end{codeexample} \end{stylekey} \end{pathoperation} -\subsection{Referencing Nodes Outside the Current Pictures} +\subsubsection{Nodes on Edges: Quotes Syntax} +\label{section-edge-quotes} + +The standard way of specifying nodes that are placed ``on'' an edge +(or on a to-path; all of the following is also true for to--paths) is +to put node specifications after the |edge| keyword, but before the +target coordinate. Another way is to use the |edge node| option and +its friends. Yet another way is to use the quotes syntax. + +The syntax is essentially the same as for labels added to nodes as +described in Section~\ref{section-label-quotes} and you also need to +load the |quotes| library. + +In detail, when the |quotes| library is loaded, each time a key--value +pair in a list of options passed to an |edge| or a |to| path command +starts with |"|, the key--value pair must actually be a string of the +following form: +\begin{quote} + |"|\meta{text}|"|\opt{|'|}\opt{\meta{options}} +\end{quote} +This string is transformed into the following: +\begin{quote} + |edge node=node [every edge quotes,|\meta{options}|]{|\meta{text}|}| +\end{quote} +As described in Section~\ref{section-label-quotes}, the apostrophe +becomes part of the \meta{options}, when present. + +The following style is important for the placement of the labels: +\begin{stylekey}{/tikz/every edge quotes (initially auto)} + This style is |auto| by default, which causes labels specified using + the quotes-syntax to be placed next to the edges. Unless the setting + of |auto| has been changed, they will be placed to the left. +\begin{codeexample}[] +\tikz \draw (0,0) edge ["left", ->] (2,0); +\end{codeexample} + + In order to place all labels to the right by default, change this + style to |auto=right|: +\begin{codeexample}[] +\tikz [every edge quotes/.style={auto=right}] + \draw (0,0) edge ["right", ->] (2,0); +\end{codeexample} + + To place all nodes ``on'' the edge, just make this style empty (and, + possibly, make your labels opaque): +\begin{codeexample}[] +\tikz [every edge quotes/.style={fill=white,font=\footnotesize}] + \draw (0,0) edge ["mid", ->] (2,1); +\end{codeexample} +\end{stylekey} + +You may often wish to place some edge nodes to the right of edges and +some to the left. For this, the special treatment of the apostrophe is +particularly convenient: Recall that in \tikzname\ there is an option +just called |'|, which is a shorthand for |swap|. Now, following the +closing quotation mark come the options of an edge node. Thus, if the +closing quotation mark is followed by an apostrophe, the |swap| option +will be added to the edge label, causing it is be placed on the other +side. Because of the special treatment, you can even add another +option like |near end| after the apostrophe without having to add +curly braces and commas: + +\begin{codeexample}[] +\tikz + \draw (0,0) edge ["left", "right"', + "start" near start, + "end"' near end] (4,0); +\end{codeexample} + +In order to modify the distance between the edge labels and the edge, +you should consider introducing some styles: + +\begin{codeexample}[] +\tikz [tight/.style={inner sep=1pt}, loose/.style={inner sep=.7em}] + \draw (0,0) edge ["left" tight, + "right"' loose, + "start" near start] (4,0); +\end{codeexample} + + +\subsection{Referencing Nodes Outside the Current Picture} \label{section-cross-picture-tikz} @@ -2166,7 +2780,7 @@ access the current page. It is a node of shape rectangle whose |north east| anchor is the upper right corner of the page. While this node is handled in a special way internally, you can reference it as if it were defined in some remembered picture other than the current -one. Thus, by giving the |remembered picture| and the |overlay| +one. Thus, by giving the |remember picture| and the |overlay| options to a picture, you can position nodes \emph{absolutely} on a page. @@ -2204,12 +2818,41 @@ page). \subsection{Late Code and Late Options} +\label{section-node-also} All options given to a node only locally affect this one node. While this is a blessing in most cases, you may sometimes want to cause options to have effects ``later'' on. The other way round, you may sometimes note ``only later'' that some options should be added to the -options of a node. +options of a node. For this, the following version of the |node| path +command can be used: + +\begin{pathoperation}{node also}{\opt{|[|\meta{late options}|]|}|(|\meta{name}|)|} + Note that the \meta{name} is compulsory and that \emph{no} text may + be given. Also, the ordering of options and node label must be as above. + + The effect of the above is the following effect: The node + \meta{name} must already be existing. Now, the \meta{late options} are + executed in a local scope. Most of these options will have no effect + since you \emph{cannot change the appearance of the node,} that is, + you cannot change a red node into a green node using these ``late'' + options. However, giving the |append after command| and + |prefix after command| options inside + the \meta{late options} (directly or indirectly) does have the desired + effect: The given path gets executed with the |\tikzlastnode| + set to the determined node. + + The net effect of all this is that you can provide, say, the |label| + option inside the \meta{options} to a add a label to a node that has + already been constructed. + +\begin{codeexample}[] +\begin{tikzpicture} + \node [draw,circle] (a) {Hello}; + \node also [label=above:world] (a); +\end{tikzpicture} +\end{codeexample} +\end{pathoperation} As explained in Section~\ref{section-paths}, you can use the options |append after command| and @@ -2219,41 +2862,20 @@ useful there: Expands to the last node on the path. \end{command} -A \emph{late option} for a node is an option that is given a long time -after the node has already been constructed. +Instead of the |node also| syntax, you can also the following option: \begin{key}{/tikz/late options=\meta{options}} This option can be given on a path (but not as an argument to a - |node| path command). It has the following effect: An already - \meta{existing node} is determined (in a way to be described in a moment) - and, then, the \meta{options} are executed in a local scope. Most of - these options will have no effect since you \emph{cannot change the - appearance of the node,} that is, you cannot change a red node - into a green node using late options. However, giving - the |append after command| and |prefix after command| options inside - the \meta{options} (directly or indirectly) does have the desired - effect: The given path gets executed with the |\tikzlastnode| - set to the determined node. - - The net effect of all this is that you can provide, say, the |label| - option inside the \meta{options} to a add a label to a node that has - already been constructed. Likewise, you can use the |on chain| - option to make an already \meta{existing node} part of a chain. - - The \meta{existing node} is determined as follows: If the - |name=|\meta{existing node} option is used inside the - \meta{options}, then this name is used. Otherwise, if the last - coordinate on the current path was of the form |(|\meta{existing - node}|)|, then this \meta{existing node} name is used. Otherwise, - an error results. - + |node| path command) and has the same effect as the |node also| path + command. Inside the \meta{options}, you should use the |name| option + to specify the node for which you wish to add late options: + \begin{codeexample}[] \begin{tikzpicture} - \node (a) [draw,circle] {Hello}; - \path (a) [late options={label=above:world}]; + \node [draw,circle] (a) {Hello}; + \path [late options={name=a, label=above:world}]; \end{tikzpicture} \end{codeexample} - \end{key} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex index 27ba94e4cf4..95a3bc7b7fb 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transformations.tex @@ -36,7 +36,7 @@ coordinate like $(1,2)$ before a point on the screen is chosen: inside the picture. \item The backend driver (like |dvips| or |pdftex|) adds transformation - commands such the coordinate is shifted to the correct position in + commands such that the coordinate is shifted to the correct position in \TeX's page coordinate system. \item \textsc{pdf} (or PostScript) apply the canvas transformation @@ -58,7 +58,7 @@ The $xy$-coordinate system and the coordinate transformation matrix the canvas transformation matrix, but you have to use commands of the core layer directly to do so and you ``better know what you are doing'' when you do this. The moment you start modifying the -canvas matrix, \pgfname\ immediately looses track of all +canvas matrix, \pgfname\ immediately loses track of all coordinates and shapes, anchors, and bounding box computations will no longer work. @@ -87,7 +87,7 @@ options: \begin{key}{/tikz/x=\meta{value} (initially 1cm)} If \meta{value} is a dimension, the $x$-vector of - \pgfname's $xyz$-coordinate system is setup to point + \pgfname's $xyz$-coordinate system is set up to point \meta{value} to the right, that is, to $(\meta{value},0pt)$. \begin{codeexample}[] @@ -135,7 +135,7 @@ options: \end{key} \begin{key}{/tikz/z=\meta{value} (initially \normalfont$-3.85$mm)} - Works like the |y=| option, but now a dimension is means the point + Works like the |y=| option, but now a dimension is the point $(\meta{value},\meta{value})$. \begin{codeexample}[] @@ -162,7 +162,7 @@ options: The next step is to apply the current \emph{coordinate transformation matrix} to the coordinate. For example, the coordinate transformation matrix might currently be set such that it adds a -certain constant to the $x$ value. Also, it might be setup such that +certain constant to the $x$ value. Also, it might be set up such that it, say, exchanges the $x$ and $y$ value. In general, any ``standard'' transformation like translation, rotation, slanting, or scaling or any combination thereof is possible. (Internally, \pgfname\ @@ -267,7 +267,7 @@ singular (if you do not know what singular matrices are, you are blessed). \begin{key}{/tikz/scale=\meta{factor}} Multiplies all coordinates by the given \meta{factor}. The \meta{factor} should not be excessively large in absolute terms or - very near to zero. + very close to zero. \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -279,7 +279,7 @@ singular (if you do not know what singular matrices are, you are blessed). \end{key} \begin{key}{/tikz/scale around={\ttfamily\char`\{}\meta{factor}|:|\meta{coordinate}{\ttfamily\char`\}}} - Scales the coordinate system by \meta{factor}, put with the ``origin + Scales the coordinate system by \meta{factor}, with the ``origin of scaling'' centered on \meta{coordinate} rather than the origin. \begin{codeexample}[] \begin{tikzpicture} @@ -360,6 +360,78 @@ singular (if you do not know what singular matrices are, you are blessed). \end{key} +\begin{key}{/tikz/rotate around x=\meta{angle}} + + This key sets the $x$, $y$ and $z$ vectors of the \pgfname\ + $xyz$-coordinate system so that they + are rotated by \meta{angle} around the axis corresponding + to the $x$-vector. + The rotation is applied so that when looking towards the origin + along this axis, positive angles result in an anticlockwise rotation. + +\begin{codeexample}[] +\begin{tikzpicture}[>=stealth] + \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$}; + \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$}; + \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$}; + + \draw [red, rotate around x=0] (0,0,0) -- (1,1,0) -- (1,0,0); + \draw [green, rotate around x=45] (0,0,0) -- (1,1,0) -- (1,0,0); + \draw [blue, rotate around x=90] (0,0,0) -- (1,1,0) -- (1,0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + +\begin{key}{/tikz/rotate around y=\meta{angle}} + + This key sets the $x$, $y$ and $z$ vectors of the \pgfname\ + $xyz$-coordinate system so that they + are rotated by \meta{angle} around the axis corresponding + to the $y$-vector. + The rotation is applied so that when looking towards the origin + along this axis, positive angles result in an anticlockwise rotation. + +\begin{codeexample}[] +\begin{tikzpicture}[>=stealth] + \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$}; + \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$}; + \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$}; + + \draw [red, rotate around y=0] (0,0,0) -- (1,1,0) -- (1,0,0); + \draw [green, rotate around y=-45] (0,0,0) -- (1,1,0) -- (1,0,0); + \draw [blue, rotate around y=-90] (0,0,0) -- (1,1,0) -- (1,0,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + +\begin{key}{/tikz/rotate around z=\meta{angle}} + + This key sets the $x$, $y$ and $z$ vectors of the \pgfname\ + $xyz$-coordinate system so that they + are rotated by \meta{angle} around the axis corresponding + to the $z$-vector. + The rotation is applied so that when looking towards the origin + along this axis, positive angles result in an anticlockwise rotation. + +\begin{codeexample}[] +\begin{tikzpicture}[>=stealth] + \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$}; + \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$}; + \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$}; + + \draw [red, rotate around z=0] (0,0) -- (1,1) -- (1,0); + \draw [green, rotate around z=45] (0,0) -- (1,1) -- (1,0); + \draw [blue, rotate around z=90] (0,0) -- (1,1) -- (1,0); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + \begin{key}{/tikz/cm={\ttfamily\char`\{}\meta{$a$}|,|\meta{$b$}|,|\meta{$c$}|,|\meta{$d$}|,|\meta{coordinate}{\ttfamily\char`\}}} applies the following transformation to all coordinates: Let $(x,y)$ be the coordinate to be transformed and let \meta{coordinate} @@ -406,13 +478,13 @@ circumstances you do \emph{not} want line widths to change in a picture as this creates visual inconsistency. Just as important, when -you use canvas transformations \emph{\pgfname\ looses track of +you use canvas transformations \emph{\pgfname\ loses track of positions of nodes and of picture sizes} since it does not take the effect of canvas transformations into account when it computes -coordinates of nodes (you not, however, rely on this; it may change in +coordinates of nodes (do not, however, rely on this; it may change in the future). -Finally, not that a canvas transformation always applies to a path as +Finally, note that a canvas transformation always applies to a path as a whole, it is not possible (as for coordinate transformations) to use different transformations in different parts of a path. diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex index 5f7eba71c8c..3891d152987 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-transparency.tex @@ -65,7 +65,7 @@ following options. \begin{codeexample}[] \begin{tikzpicture}[line width=1ex] \draw (0,0) -- (3,1); - \filldraw [fill=examplefill,draw opacity=0.5] (1,0) rectangle (2,1); + \filldraw [fill=yellow!80!black,draw opacity=0.5] (1,0) rectangle (2,1); \end{tikzpicture} \end{codeexample} \end{key} @@ -188,7 +188,7 @@ option |opacity| sets both at the same time. \end{key} -Note the following effect: If you setup a certain opacity for stroking +Note the following effect: If you set up a certain opacity for stroking or filling and you stroke or fill the same area twice, the effect accumulates: @@ -203,6 +203,185 @@ Often, this is exactly what you intend, but not always. You can use transparency groups, see the end of this section, to change this. + +\subsection{Blend Modes} +\label{section-blend-modes} + +A \emph{blend mode} specifies how colors mix when you paint on a +canvas. Normally, if you paint a red box on a green circle, the red +color will completely replace the green circle. However, in some +situations you might also wish the red color to somehow ``mix'' or +``blend'' with the green circle. We already saw that, using transparency, +we can draw something without completely obscuring the +background. \emph{Blending} is a similar operation, only here we mix +colors in more complicated ways. + +\emph{Note:} Blending is a rather ``advanced'' feature of +\textsc{pdf}. Most renderers, let alone printers, will have trouble +rendering blending correctly. + +\begin{key}{/tikz/blend mode=\meta{mode}} + Sets the current blend mode to \meta{mode}. Here \meta{mode} must be + one of the modes listed below. More details on these modes can also + be found in Section 7.2.4 of the \textsc{pdf} Specification, version 1.7. + + In the following example, the blend mode is only used and set inside + a transparency group (see also + Section~\ref{section-transparency-groups}). This is because most + renderers (viewing + programs) have trouble rendering blending correctly otherwise. For + instance, at the time of writing, the versions of Adobe's Reader and + Apple's Preview render the following drawing very differently, if + the transparency group is not used in the following example. + +\begin{codeexample}[] +\tikz { + \begin{scope}[transparency group] + \begin{scope}[blend mode=screen] + \fill[red!90!black] ( 90:.6) circle (1); + \fill[green!80!black] (210:.6) circle (1); + \fill[blue!90!black] (330:.6) circle (1); + \end{scope} + \end{scope} +} +\end{codeexample} + + Because of the trouble with rendering blending correctly outside + transparency groups, there is a special key that establishes a + transparency group and sets a blend mode simultaneously: + + \begin{key}{/tikz/blend group=\meta{mode}} + This key can only be used with a scope (like + |transparency group|). It will cause the current scope to become a + transparency group and, inside this group, the blend mode will be + set to \meta{mode}. + +\begin{codeexample}[] +\tikz [blend group=screen] { + \fill[red!90!black] ( 90:.6) circle (1); + \fill[green!80!black] (210:.6) circle (1); + \fill[blue!90!black] (330:.6) circle (1); +} +\end{codeexample} + \end{key} + + Here is an overview of the effects of the different available blend + modes. In the examples, we always have three circles drawn on + top of each other (as in the example code earlier): We start with a + triple of pure red, green, and blue. Below it, we have a triple of + light versions of these three colors (|red!50|, |green!50|, and + |blue!50|). Next comes the triple yellow, cyan, and magenta; again + with a triple of light versions below it. The large example consists + of three balls (produced using |ball color|) having the colors red, + green, and blue, are drawn on top of each other just like the + circles. + + \definecolor{rg}{rgb}{1,1,0} + \definecolor{gb}{rgb}{0,1,1} + \definecolor{br}{rgb}{1,0,1} + + \def\makeline#1#2#3{\leavevmode + \hbox to 4cm{#1\hss}\ \hbox to + 2cm{#2\hss}\ \begin{minipage}[t]{9cm}\raggedright#3\end{minipage}\par + \textcolor{black!25}{\hrule height1pt} + } + + \def\showmode#1#2{ + \makeline{ + \tikz [blend mode=#1,baseline=-.5ex] { + \fill[red] ( 90:.5em) circle (.75em); + \fill[green] (210:.5em) circle (.75em); + \fill[blue] (330:.5em) circle (.75em); + \scoped[yshift=-2.5em]{ + \fill[red!50] ( 90:.5em) circle (.75em); + \fill[green!50] (210:.5em) circle (.75em); + \fill[blue!50] (330:.5em) circle (.75em); + } + } + \tikz [blend mode=#1,baseline=-.5ex] { + \fill[rg] ( 90:.5em) circle (.75em); + \fill[gb] (210:.5em) circle (.75em); + \fill[br] (330:.5em) circle (.75em); + \scoped[yshift=-2.5em]{ + \fill[rg!50] ( 90:.5em) circle (.75em); + \fill[gb!50] (210:.5em) circle (.75em); + \fill[br!50] (330:.5em) circle (.75em); + } + } + \tikz [blend mode=#1,baseline=-.5ex+1.25em] { + \shade[ball color=red] ( 90:1em) circle (1.5em); + \shade[ball color=green] (210:1em) circle (1.5em); + \shade[ball color=blue] (330:1em) circle (1.5em); + }}{|#1|}{#2}} + + \medskip + \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from Table 7.2 of the + \textsc{pdf} Specification, Version 1.7}} + \showmode{normal}{When painting a pixel with a some color (called + the ``source color''), the background color + (called the ``backdrop'') is completely ignored.} + \showmode{multiply}{Multiplies the backdrop and source color + values. The result color is always at least as dark as + either of the two constituent colors. Multiplying any color with + black produces black; multiplying with white leaves the original + color unchanged. Painting successive overlapping objects with a + color other than black or white produces progressively darker + colors.} + \showmode{screen}{Multiplies the complements of the backdrop and + source color values, then complements the result. The + result color is always + at least as light as either of the two constituent + colors. Screening any color with white produces white; screening + with black leaves the original color unchanged. The effect is + similar to projecting multiple photographic slides + simultaneously onto a single screen.} + \showmode{overlay}{Multiplies or screens the colors, depending on + the backdrop color value. Source colors overlay the backdrop + while preserving its highlights and shadows. The backdrop color + is not replaced but is mixed with the source color to reflect + the lightness or darkness of the backdrop.} + \showmode{darken}{Selects the darker of the backdrop and source + colors. The backdrop is replaced with the source where the + source is darker; otherwise, it is left unchanged.} + \showmode{lighten}{Selects the lighter of the backdrop and source + colors. The backdrop is replaced with the source where the + source is lighter; otherwise, it is left unchanged.} + \showmode{color dodge}{Brightens the backdrop color to reflect the + source color. Painting with black produces no changes.} + \showmode{color burn}{Darkens the backdrop color to reflect the + source color. Painting with white produces no change.} + \showmode{hard light}{Multiplies or screens the colors, depending + on the source color value. The effect is similar to shining a + harsh spotlight on the backdrop.} + \showmode{soft light}{Darkens or lightens the colors, depending on + the source color value. The effect is similar to shining a + diffused spotlight on the backdrop.} + \showmode{difference}{Subtracts the darker of the two constituent + colors from the lighter color. Painting with white inverts the + backdrop color; painting with black produces no change.} + \showmode{exclusion}{Produces an effect similar to that of the + Difference mode but lower in contrast. Painting with white + inverts the backdrop color; painting with black produces no + change.} + \showmode{hue}{Creates a color with the hue of the source color + and the saturation and luminosity of the backdrop color.} + \showmode{saturation}{Creates a color with the saturation of the + source color and the hue and luminosity of the backdrop + color. Painting with this mode in an area of the backdrop that + is a pure gray (no saturation) produces no change.} + \showmode{color}{Creates a color with the hue and saturation of + the source color and the luminosity of the backdrop color. This + preserves the gray levels of the backdrop and is useful for + coloring monochrome images or tinting color images.} + \showmode{luminosity}{Creates a color with the luminosity of the + source color and the hue and saturation of the backdrop + color. This produces an inverse effect to that of the Color + mode.} + +\end{key} + + + \subsection{Fadings} For complicated graphics, uniform transparency settings are not always @@ -220,7 +399,7 @@ How do we specify a fading? This is a bit of an art since the underlying mechanism is quite powerful, but a bit difficult to use. Let us start with a bit of terminology. A \emph{fading} specifies for -each point of an area to transparency of the point. This transparency +each point of an area the transparency of that point. This transparency can by any number between 0 and 1. A \emph{fading picture} is a normal graphic that, in a way to be described in a moment, determines the transparency of points inside the fading. Each fading has an @@ -236,7 +415,7 @@ opaque is the point in the fading. In particular, a white point of the fading picture is completely opaque in the fading and a black point of the fading picture is completely transparent in the fading. (The background of the fading picture is always transparent in the fading -as if the background where black.) +as if the background were black.) It is rather counter-intuitive that a \emph{white} pixel of the fading picture will be \emph{opaque} in the fading and a \emph{black} pixel @@ -244,7 +423,7 @@ will be \emph{transparent}. For this reason, \tikzname\ defines a color called |transparent| that is the same as |black|. The nice thing about this definition is that the color |transparent!|\meta{percentage} in the fading picture yields a -pixel that is \meta{percentage} per cent transparent in the fading. +pixel that is \meta{percentage} percent transparent in the fading. Turning a fading picture into a normal picture is achieved using the following commands, which are \emph{only defined in the library}, @@ -261,7 +440,7 @@ namely the library |fadings|. So, to use them, you have to say set the name of the fading. You \emph{must} provide this option. \end{key} - The following shading is 2cm by 2cm and changes gets more and more + The following shading is 2cm by 2cm and gets more and more transparent from left to right, but is 50\% transparent for a large circle in the middle. {\tikzexternaldisable @@ -303,6 +482,9 @@ namely the library |fadings|. So, to use them, you have to say \end{tikzpicture} \end{codeexample} }% + + The same effect can also be achieved using knockout groups, see + Section~\ref{section-transparency-groups}. \end{environment} \begin{plainenvironment}{{tikzfadingfrompicture}\oarg{options}} @@ -314,7 +496,7 @@ namely the library |fadings|. So, to use them, you have to say \end{contextenvironment} \begin{command}{\tikzfading\oarg{options}} - This command is used to define a fading similarly to that way a + This command is used to define a fading similarly to the way a shading is defined. In the \meta{options} you should \begin{enumerate} \item use the |name=|\meta{name} option to set a name for the fading, @@ -363,7 +545,7 @@ namely the library |fadings|. So, to use them, you have to say \subsubsection{Fading a Path} -Aa fading specifies for each pixel of a certain area how transparent +A fading specifies for each pixel of a certain area how transparent this pixel will be. The following options are used to install such a fading for the current scope or path. @@ -402,11 +584,11 @@ fading for the current scope or path. \begin{key}{/tikz/fit fading=\meta{boolean} (default true, initially true)} When set to |true|, the fading is shifted and resized (in exactly - the same way as a shading) so that is covers the current + the same way as a shading) so that it covers the current path. When set to |false|, the fading is only shifted so that it is centered on the path's center, but it is not resized. This can be useful for special-purpose fadings, for instance when you use a - fading to ``punsh out'' something. % TODOsp: punsh out --> punch out?? + fading to ``punch out'' something. \end{key} \begin{key}{/tikz/fading transform=\meta{transformation options}} @@ -444,7 +626,7 @@ fading for the current scope or path. \end{tikzpicture} \end{codeexample} - The |fade inside| of the following example more transparent in the middle than on the + The |fade inside| of the following example is more transparent in the middle than on the outside. \begin{codeexample}[] @@ -563,6 +745,7 @@ conjunction, see the end of this section. \subsection{Transparency Groups} +\label{section-transparency-groups} Consider the following cross and sign. They ``look wrong'' because we can see how they were constructed, while this is not really part of @@ -606,9 +789,9 @@ Transparency groups are used to render them correctly: \end{tikzpicture} \end{codeexample} -\begin{key}{/tikz/transparency group} +\begin{key}{/tikz/transparency group=\oarg{options}} This option can be given to a |scope|. It will have the following - effect: The scope's contents is stroked/filled + effect: The scope's contents is stroked\,/\penalty0\,filled ``ignoring any outside transparency.'' This means, all previous transparency settings are ignored (you can still set transparency inside the group, but never mind). For instance, in the forbidden @@ -623,15 +806,93 @@ Transparency groups are used to render them correctly: is just red at the end, so this red color will be blended with whatever is ``behind'' the group on the page. - Note that, depending on the driver, it is possible to directly put - objects in a transparency group that lie outside the picture. This - has to do with internal bounding box computations. - Section~\ref{section-transparency} explains how to sidestep this - problem. +\begin{codeexample}[] +\begin{tikzpicture} + \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1); + \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking}; + + \begin{scope}[transparency group,opacity=.5] + \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white] + {Smoking}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + + Note that in the example, the |opacity=.5| is not active inside the + transparency group: The group is only established at beginning of + the scope and all options given to the |{scope}| environment are set + before the group is established. To change the opacity \emph{inside} + the group, you need to open another scope inside it or use the + |opacity| key with a command inside the group: + +\begin{codeexample}[] +\begin{tikzpicture} + \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1); + \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking}; + + \begin{scope}[transparency group,opacity=.5] + \node (s) at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white] + {Smoking}; + + \draw [opacity=.5, line width=2ex, blue] (1.2,0) -- (2.8,0); + \end{scope} +\end{tikzpicture} +\end{codeexample} + + The \meta{options} are a list of comma-separated options: + \begin{itemize} + \item \declare{|knockout|} When this option is given inside the + \meta{options}, the group becomes a so-called \emph{knockout} + group. This means, essentially, that inside the group everything + is painted as if the ``opacity'' of a line or area were just + another color channel. In particular, if you paint a pixel with + opacity $0$ inside a knockout group, this pixel becomes perfectly + transparent immediately. In contrast, painting a pixel with + something of opacity 0 normally has no effect. + + Not all renderers, let alone printers, will support + this. At the time of writing, Apple's Preview will not show the + following correctly (you should see the text \tikzname\ in the + middle): +\begin{codeexample}[] +\begin{tikzpicture} + \shade [left color=red,right color=blue] (-2,-1) rectangle (2,1); + \begin{scope}[transparency group=knockout] + \fill [white] (-1.9,-.9) rectangle (1.9,.9); + \node [opacity=0,font=\fontfamily{ptm}\fontsize{45}{45}\bfseries] + {Ti\emph{k}Z}; + \end{scope} +\end{tikzpicture} +\end{codeexample} + In the example, we first draw a large shading and then, inside the + transparency group ``overwrite'' most of this shading by a big + white rectangle. The interesting part is the text of the node, + which has opacity |0|. Normally, this would mean that nothing is + shown. However, in a knockout group, we ``paint'' the text with an + ``opacity zero'' color. The effect is that part of the totally + opaque white rectangle gets overwritten by a perfectly transparent + area (namely exactly the area taken up by the pixels of the + text). When this whole knockout group is then placed on top of the + shading, the shading will ``shine through'' at the knocked-out + pixels. + + \item \declare{|isolated|}|=false| A group can be isolated or + not. By default, they are isolated, since this is typically what you + want. For details on what isolated groups are, exactly, see + Section~7.3.4 of the \textsc{pdf} Specification, version 1.7. + \end{itemize} + + Note that when a transparency group is created, \tikzname\ must + correctly determine the size of the material inside the + group. Usually, this is no problem, but when you use things like + |overlay| or |transform canvas|, trouble may result. In this case, + please consult Section~\ref{section-transparency} on how to sidestep + this problem in such cases. \end{key} + %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex index ac0a00bda5f..cdf2cf45456 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex @@ -32,7 +32,7 @@ not downward as above. You can tell whether the author of a paper is a mathematician or a computer scientist by looking at the direction their trees grow. A computer scientist's trees will grow downward while a mathematician's tree will grow upward. Naturally, the -\emph{correct} way is the mathematician's way, which can be specify as +\emph{correct} way is the mathematician's way, which can be specified as follows: \begin{codeexample}[] \begin{tikzpicture} @@ -45,6 +45,12 @@ follows: \end{tikzpicture} \end{codeexample} +In \tikzname, there are two ways of specifying trees: Using either the +|graph| path operation, which is covered in +Section~\ref{section-library-graphs}, or using the |child| path +operation, which is covered in the present section. Both methods have +their advantages. + In \tikzname, trees are specified by adding \emph{children} to a node on a path using the |child| operation: @@ -86,7 +92,7 @@ node {root} child [red] foreach \name in {1,2} {node {\name}} \end{codeexample} the effect will be the same as if you had said \begin{codeexample}[code only] -node {root} child[red] {node {1}} child[ref] {node {2}} +node {root} child[red] {node {1}} child[red] {node {2}} \end{codeexample} When you write \begin{codeexample}[code only] @@ -114,7 +120,7 @@ node {root} child[left] {node[left] {1}} child[right] {node[right] {2}} -\subsection{Child Paths and the Child Nodes} +\subsection{Child Paths and Child Nodes} For each |child| of a root node, its \meta{child path} is inserted at a specific location in the picture (the placement rules are discussed @@ -133,9 +139,9 @@ the second child, no child node is specified and, thus, it is just As for any normal node, you can give the child node a name, shift it around, or use options to influence how it is rendered. \begin{codeexample}[] -\begin{tikzpicture} +\begin{tikzpicture}[sibling distance=15mm] \node[rectangle,draw] {root} - child {node[circle,draw] (left node) {left}} + child {node[circle,draw,yshift=-5mm] (left node) {left}} child {node[ellipse,draw] (right node) {right}}; \draw[dashed,->] (left node) -- (right node); \end{tikzpicture} @@ -208,7 +214,7 @@ first and/or second child of |parent|. Here is an example: \begin{codeexample}[] -\begin{tikzpicture} +\begin{tikzpicture}[sibling distance=15mm] \node (root) {root} child child { @@ -231,7 +237,8 @@ example: \begin{codeexample}[] \begin{tikzpicture} - [thick,level 2/.style={sibling distance=10mm}] + [thick,level 1/.style={sibling distance=15mm}, + level 2/.style={sibling distance=10mm}] \coordinate child[red] {child child} child[green] {child child[blue]}; @@ -284,16 +291,16 @@ Here is the set of rules: \begin{codeexample}[code only] \begin{tikzpicture} - \path - [...] % Options apply to the whole tree - node[...] {root} % Options apply to the root node only - [...] % Options apply to all children - child[...] % Options apply to this child and all its children - { - node[...] {} % Options apply to the child node only - ... - } - child[...] % Options apply to this child and all its children + \scoped + [...] % Options apply to the whole tree + \node[...] {root} % Options apply to the root node only + [...] % Options apply to all children + child[...] % Options apply to this child and all its children + { + node[...] {} % Options apply to the child node only + ... + } + child[...] % Options apply to this child and all its children ; \end{tikzpicture} \end{codeexample} @@ -358,7 +365,9 @@ evenly spaced or their centers are evenly distributed. Calculating good positions is especially difficult since a good position for the first child may depend on the size of the last child. -In \tikzname, a comparatively simple approach is taken to placing the +In basic \tikzname, when you do not make use of the graph drawing +facilities explained in Part~\ref{part-gd}, a comparatively simple +approach is taken to placing the children. In order to compute a child's position, all that is taken into account is the number of the current child in the list of children and the number of children in this list. Thus, if a node has @@ -391,7 +400,7 @@ is given by the |level distance|. {\catcode`\|=12 \begin{codeexample}[] -\begin{tikzpicture} +\begin{tikzpicture}[sibling distance=15mm, level distance=15mm] \path [help lines] node (root) {root} [grow=-10] @@ -637,7 +646,7 @@ will not be rendered. \end{codeexample} In the next example, the top and bottom nodes are aligned at the top - and the bottom. + and the bottom, respectively. \begin{codeexample}[] \begin{tikzpicture} [level distance=2cm,growth parent anchor=north, @@ -662,7 +671,7 @@ will not be rendered. The effect of executing the macro should be the following: It should transform the coordinate system in such a way that the origin becomes the place where the current child should be anchored. When - the macro is called, the current coordinate system will be setup + the macro is called, the current coordinate system will be set up such that the anchor of the parent node is in the origin. Thus, in each call, the \meta{macro name} must essentially do a shift to the child's origin. When the macro is called, the \TeX\ counter @@ -690,18 +699,34 @@ edge called the |edge from parent|. This edge is added to the \begin{pathoperation}{edge from parent}{\opt{\oarg{options}}} This path operation can only be used inside \meta{child paths} and - should be given at the end, possibly followed by node specifications - (we will come to that). If a \meta{child path} does not contain this - operation, it will be added at the end of the \meta{child path} - automatically. - - This operation has several effects. The most important is that it - inserts the current ``edge from parent path'' into the child - path. The edge from parent path can be set using the following - key: + should be given at the end, possibly followed by \meta{node + specifications} like |node {a}|. If a \meta{child path} does not + contain this operation, it will be added at the end of the + \meta{child path} automatically. + + By default, this operation does the following: + \begin{enumerate} + \item The following style is executed: + \begin{stylekey}{/tikz/edge from parent (initially draw)} + This style is inserted right before the |edge from parent path| and + before the \meta{options} are inserted. +\begin{codeexample}[] +\begin{tikzpicture} + [edge from parent/.style={draw,red,thick}] + \node {root} + child {node {left} edge from parent[dashed]} + child {node {right} + child {node {child}} + child {node {child} edge from parent[draw=none]} + }; +\end{tikzpicture} +\end{codeexample} + \end{stylekey} + \item Next, the \meta{options} are executed. + \item Next, the text stored in the following key is inserted: \begin{key}{/tikz/edge from parent path=\meta{path} (initially \normalfont code shown below)} - This options allows you to set the edge from parent path to a new + This option allows you to set the |edge from parent path| to a new path. Initially, this path is the following: \begin{codeexample}[code only] (\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor) @@ -719,7 +744,8 @@ edge called the |edge from parent|. This edge is added to the effects. For example, we could replace the straight line by a curve as follows: \begin{codeexample}[] -\begin{tikzpicture}[edge from parent path= +\begin{tikzpicture}[level distance=15mm, sibling distance=15mm, + edge from parent path= {(\tikzparentnode.south) .. controls +(0,-1) and +(0,1) .. (\tikzchildnode.north)}] \node {root} @@ -731,71 +757,14 @@ edge called the |edge from parent|. This edge is added to the \end{tikzpicture} \end{codeexample} - Further useful edge from parent paths are defined in the tree + Further useful |edge from parent path|s are defined in the tree library, see Section~\ref{section-tree-library}. - \end{key} - - As said before, the anchors in the default edge from parent path - are empty. However, you can set them using the following keys: - \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)} - Specifies the anchor where the edge from parent meets the child - node by setting the macro |\tikzchildanchor| to - |.|\meta{anchor}. - - If you specify |border| as the \meta{anchor}, then the macro - |\tikzchildanchor| is set to the empty string. The effect of - this is that the edge from the parent will meet the child on the - border at an automatically calculated position. -\begin{codeexample}[] -\begin{tikzpicture} - \node {root} - [child anchor=north] - child {node {left} edge from parent[dashed]} - child {node {right} - child {node {child}} - child {node {child} edge from parent[draw=none]} - }; -\end{tikzpicture} -\end{codeexample} - \end{key} - - \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)} - This option works the same way as the |child anchor|, only for - the parent. - \end{key} - - Besides inserting the edge from parent path, the |edge from parent| - operation has another effect: The \meta{options} are inserted - directly before the edge from parent path and the following style is - also installed prior to inserting the path: - \begin{stylekey}{/tikz/edge from parent (initially draw)} - This style is inserted right before the edge from parent path and - before the \meta{options} are inserted. -\begin{codeexample}[] -\begin{tikzpicture} - [edge from parent/.style={draw,red,thick}] - \node {root} - child {node {left} edge from parent[dashed]} - child {node {right} - child {node {child}} - child {node {child} edge from parent[draw=none]} - }; -\end{tikzpicture} -\end{codeexample} - \end{stylekey} - - Note: The \meta{options} inserted before the edge from parent path - is added \emph{apply to the whole child path}. Thus, it is not - possible to, say, draw a circle in red as part of the child path and - then have an edge to parent in blue. However, as always, the child - node is a node and can be drawn in a totally different way. + + The nodes in a \meta{node specification} following the + |edge from parent| path command get executed as if the |pos| option + had been added to all these nodes, see also Section~\ref{section-pos-option}. - Finally, the |edge from parent| operation has one more effect: It - causes all nodes \emph{following} the operation to be placed on the - edge. This is the same effect as if you had added the |pos| option - to all these nodes, see also Section~\ref{section-pos-option}. - - As an example, consider the following code: + As an example, consider the following code: \begin{codeexample}[code only] \node (root) {} child {node (child) {} edge to parent node {label}}; \end{codeexample} @@ -805,7 +774,7 @@ edge called the |edge from parent|. This edge is added to the (root) -- (child) node [pos=0.5] {label} \end{codeexample} - Here is a more complicated example: + Here is a more complicated example: \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -828,7 +797,64 @@ edge called the |edge from parent|. This edge is added to the }; \end{tikzpicture} \end{codeexample} + + As said before, the anchors in the default |edge from parent path| + are empty. However, you can set them using the following keys: + \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)} + Specifies the anchor where the edge from parent meets the child + node by setting the macro |\tikzchildanchor| to + |.|\meta{anchor}. + If you specify |border| as the \meta{anchor}, then the macro + |\tikzchildanchor| is set to the empty string. The effect of + this is that the edge from the parent will meet the child on the + border at an automatically calculated position. +\begin{codeexample}[] +\begin{tikzpicture} + \node {root} + [child anchor=north] + child {node {left} edge from parent[dashed]} + child {node {right} + child {node {child}} + child {node {child} edge from parent[draw=none]} + }; +\end{tikzpicture} +\end{codeexample} + \end{key} + + \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)} + This option works the same way as the |child anchor|, only for + the parent. + \end{key} + \end{key} + \end{enumerate} + + All of the above describes the standard functioning of the + |edge from parent| command. You may, however, sometimes need even + more fine-grained control (the graph drawing engine needs it, for + instance). In such cases the following key gives you complete + control: + \begin{key}{/tikz/edge from parent macro=\meta{macro}} + The \meta{macro} gets expanded each time the |edge from parent| + path operation is used. This \meta{macro} must take two parameters + and must expand to some text that is subsequently parsed by the + parser. The first parameter will be the set of \meta{options} that + where passed to the |edge from parent| command, the second + parameter will be the \meta{node specifications} that following + the command. + + The standard behaviour of drawing a straight line from the parent + node to the child node could be achieved by setting the + \meta{macro} to the following: +\begin{codeexample}[code only] +\def\mymacro#1#2{ + [style=edge from parent, #1] + (\tikzparentnode\tikzparentanchor) -- #2 (\tikzchildnode\tikzchildanchor) +} +\end{codeexample} + Note that |#2| is placed between |--| and the node to ensure that + nodes are put ``on top'' of the line. + \end{key} \end{pathoperation} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex index 2ca446abecc..e8717cf9718 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-Euclid.tex @@ -106,9 +106,7 @@ Let us have a look at how Euclid can turn this into \tikzname\ code. As in the previous tutorials, Euclid needs to load \tikzname, together with some libraries. These libraries are |calc|, |intersections|, -|through|, and |backgrounds|. Depending on which format\footnote{Note - that \pgfname/\tikzname{} is not supported by recent Con\TeX t versions - (like mark IV, the Lua\TeX-aware part of Con\TeX t).} he uses, +|through|, and |backgrounds|. Depending on which format he uses, Euclid would use one of the following in the preamble: \begin{codeexample}[code only] @@ -200,7 +198,7 @@ The new code for the coordinates is the following: \end{codeexample} Note that if a coordinate in such a computation has a factor (like -|.1|) you must place a |*| directly before the opening parenthesis of +|.1|), you must place a |*| directly before the opening parenthesis of the coordinate. You can nest such computations. @@ -545,7 +543,7 @@ The computation of the point $D$ in Euclid's second proposition is a bit more complicated. It can be expressed as follows: Consider the line from $X$ to $B$. Suppose we rotate this line around $X$ for 90$^\circ$ and then stretch it by a -factor of $\sin(60^\circ)/2$. This yields the desired point~$D$. We +factor of $\sin(60^\circ) \cdot 2$. This yields the desired point~$D$. We can do the stretching using the partway modifier above, for the rotation we need a new modifier: the rotation modifier. The idea is that the second coordinate in a partway computation can be prefixed by @@ -610,11 +608,11 @@ computation has the form \meta{p}|!|\meta{factor}|!|\meta{q}, resulting in the point $(1-\meta{factor})\meta{p} + \meta{factor}\meta{q}$. Alternatively, instead of \meta{factor} you can also use a \meta{dimension} between the points. In this case, you -get the point that is \meta{dimension} removed from \meta{p} on the +get the point that is \meta{dimension} away from \meta{p} on the straight line to \meta{q}. We know that the point $G$ is on the way from $B$ to $F$. The distance -is given by the radius of the circle~$H$. Here is the code form +is given by the radius of the circle~$H$. Here is the code for computing $H$: {\tikzexternaldisable \begin{codeexample}[pre={ diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-chains.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-chains.tex index 725702513fb..e6b05fd6bd7 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-chains.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-chains.tex @@ -8,9 +8,9 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Tutorial: Putting a Diagram in Chains} +\section{Tutorial: Diagrams as Simple Graphs} -In this tutorial we have a look at how chains and matrices can be used +In this tutorial we have a look at how graphs and matrices can be used to typeset a diagram. Ilka, who just got tenure for her professorship on Old and @@ -155,7 +155,7 @@ perhaps a bit cleaner and perhaps also bit ``cooler.'' \end{tikzpicture} }\medskip -Having read the previous tutorials, Ilka knows already how to setup +Having read the previous tutorials, Ilka knows already how to set up the environment for her diagram, namely using a |tikzpicture| environment. She wonders which libraries she will need. She decides that she will postpone the decision and add the necessary libraries as @@ -205,7 +205,7 @@ text. By giving this option to all nodes, they will all have the same height of 6mm. Styling the terminals is a bit more difficult because of the round -corners. Ilka has several options how she can achieve them. Once way +corners. Ilka has several options how she can achieve them. One way is to use the |rounded corners| option. It gets a dimension as parameter and causes all corners to be replaced by little arcs with the given dimension as radius. By setting the radius to 3mm, she will @@ -379,7 +379,7 @@ A third way is to use matrices, which we will do later. Now that the nodes have been placed, Ilka needs to add connections. Here, some connections are more difficult than -other. Consider for instance the ``repeat'' line around the +others. Consider for instance the ``repeat'' line around the |digit|. One way of describing this line is to say ``it starts a little to the right of |digit| than goes down and then goes to the left and finally ends at a point a little to the left of |digit|.'' @@ -405,11 +405,11 @@ Ilka can put this into code as follows: \end{tikzpicture} \end{codeexample} -Since Ilka needs this ``go up/down then horizontally and than up/down +Since Ilka needs this ``go up/down then horizontally and then up/down to a target'' several times, it seems sensible to define a special \emph{to-path} for this. Whenever the |edge| command is used, it simply adds the current value of |to path| to the path. So, Ilka can -setup a style that contains the correct path: +set up a style that contains the correct path: \begin{codeexample}[] \begin{tikzpicture}[node distance=5mm and 5mm, skip loop/.style={to path={-- ++(0,-.5) -| (\tikztotarget)}}] @@ -488,285 +488,521 @@ where she would like connections to start and end. skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}] \matrix[row sep=1mm,column sep=2mm] { % First row: - & & & & & & & & & & & \node [terminal] {+};\\ + & & & & & & & & & & & \node (plus) [terminal] {+};\\ % Second row: - \node (p1) [point] {}; & \node [nonterminal] {unsigned integer}; & - \node (p2) [point] {}; & \node [terminal] {.}; & - \node (p3) [point] {}; & \node [terminal] {digit}; & - \node (p4) [point] {}; & \node (p5) [point] {}; & - \node (p6) [point] {}; & \node [terminal] {E}; & - \node (p7) [point] {}; & & - \node (p8) [point] {}; & \node [nonterminal] {unsigned integer}; & - \node (p9) [point] {}; \\ + \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; & + \node (p2) [point] {}; & \node (dot) [terminal] {.}; & + \node (p3) [point] {}; & \node (digit) [terminal] {digit}; & + \node (p4) [point] {}; & \node (p5) [point] {}; & + \node (p6) [point] {}; & \node (e) [terminal] {E}; & + \node (p7) [point] {}; & & + \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; & + \node (p9) [point] {}; & \node (p10) [point] {};\\ % Third row: - & & & & & & & & & & & \node [terminal] {-};\\ + & & & & & & & & & & & \node (minus)[terminal] {-};\\ }; \path (p4) edge [->,skip loop=-5mm] (p3) (p2) edge [->,skip loop=5mm] (p6); \end{tikzpicture} \end{codeexample} -Now, its only a small step to add all the missing edges. +Now, it's only a small step to add all the missing edges. -\subsection{Using Chains} +\subsection{The Diagram as a Graph} Matrices allow Ilka to align the nodes nicely, but the connections are not quite perfect. The problem is that the code does not really -reflect the paths that underlie the diagram. - - -For this reason, Ilka decides to try out \emph{chains} by including -the |chain| library. Basically, a chain is just a sequence of -(usually) connected nodes. The nodes can already have been constructed -or they can be constructed as the chain is constructed (or these -processes can be mixed). - -\subsubsection{Creating a Simple Chain} - - -Ilka starts with creating a chain from scratch. For this, she starts a -chain using the |start chain| option in a scope. Then, inside the -scope, she uses the |on chain| option on nodes to add them to the -chain. -\begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm] - \node [on chain,nonterminal] {unsigned integer}; - \node [on chain,terminal] {.}; - \node [on chain,terminal] {digit}; - \node [on chain,terminal] {E}; - \node [on chain,nonterminal] {unsigned integer}; +reflect the paths that underlie the diagram. For this, it seems +natural enough to Ilka to use the |graph| library since, after all, +connecting nodes by edges is exactly what happens in a graph. +The |graph| library can both be used to connect nodes that have +already been created, but it can also be used to create nodes ``on the +fly'' and these processes can also be mixed. + + +\subsubsection{Connecting Already Positioned Nodes} + +Ilka has already a fine method for positioning her nodes (using a +|matrix|), so all that she needs is an easy way of specifying the +edges. For this, she uses the |\graph| command (which is actually just +a shorthand for |\path graph|). It allows her to write down edges +between them in a simple way (the macro |\matrixcontent| contains +exactly the matrix content from the previous example; no need to +repeat it here): +\def\matrixcontent{ + % First row: + \& \& \& \& \& \& \& \& \& \& \& \node (plus) [terminal] {+};\\ + % Second row: + \node (p1) [point] {}; \& \node (ui1) [nonterminal] {unsigned integer}; \& + \node (p2) [point] {}; \& \node (dot) [terminal] {.}; \& + \node (p3) [point] {}; \& \node (digit) [terminal] {digit}; \& + \node (p4) [point] {}; \& \node (p5) [point] {}; \& + \node (p6) [point] {}; \& \node (e) [terminal] {E}; \& + \node (p7) [point] {}; \& \& + \node (p8) [point] {}; \& \node (ui2) [nonterminal] {unsigned integer}; \& + \node (p9) [point] {}; \& \node (p10) [point] {};\\ + % Third row: + \& \& \& \& \& \& \& \& \& \& \& \node (minus)[terminal] {-};\\ +} +\begin{codeexample}[pre={\tikzset{ampersand replacement=\&,point/.style={coordinate}}}] +\begin{tikzpicture}[skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}, + hv path/.style={to path={-| (\tikztotarget)}}, + vh path/.style={to path={|- (\tikztotarget)}}] + \matrix[row sep=1mm,column sep=2mm] { \matrixcontent }; + + \graph { + (p1) -> (ui1) -- (p2) -> (dot) -- (p3) -> (digit) -- (p4) + -- (p5) -- (p6) -> (e) -- (p7) -- (p8) -> (ui2) -- (p9) -> (p10); + (p4) ->[skip loop=-5mm] (p3); + (p2) ->[skip loop=5mm] (p5); + (p6) ->[skip loop=-11mm] (p9); + (p7) ->[vh path] (plus) -> [hv path] (p8); + (p7) ->[vh path] (minus) -> [hv path] (p8); + }; \end{tikzpicture} \end{codeexample} -(Ilka will add the plus and minus nodes later.) -As can be seen, the nodes of a chain are placed in a row. This can be -changed, for instance by saying |start chain=going below| we get a -chain where each node is below the previous one. - -The next step is to \emph{join} the nodes of the chain. For this, we -add the |join| option to each node. This joins the node with the -previous node (for the first node nothing happens). -\begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm] - \node [on chain,join,nonterminal] {unsigned integer}; - \node [on chain,join,terminal] {.}; - \node [on chain,join,terminal] {digit}; - \node [on chain,join,terminal] {E}; - \node [on chain,join,nonterminal] {unsigned integer}; -\end{tikzpicture} -\end{codeexample} -In order to get a arrow tip, we redefine the |every join| style. Also, -we move the |join| and |on chain| options to the |every node| -style so that we do not have to repeat them so often. -\begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}] - \node [nonterminal] {unsigned integer}; - \node [terminal] {.}; - \node [terminal] {digit}; - \node [terminal] {E}; - \node [nonterminal] {unsigned integer}; +This is already pretty near to the desired result, just a few +``finishing touches'' are needed to style the edges more nicely. + +However, Ilka does not have the feeling that the |graph| command is +all that hot in the example. It certainly does cut down on the number +of characters she has to write, but the overall graph structure is not +that much clear -- it is still mainly a list of paths through the +graph. It would be nice to specify that, say, there the path from +|(p7)| sort of splits to |(plus)| and |(minus)| and then merges once +more at |(p8)|. Also, all these parentheses are bit hard to type. + +It turns out that edges from a node to a whole group of nodes are +quite easy to specify, as shown in the next example. Additionally, by +using the |use existing nodes| option, Ilka can also leave out all the +parentheses (again, some options have been moved outside to keep the +examples shorter): + +\begin{codeexample}[pre={\tikzset{ampersand replacement=\&,point/.style={coordinate}, + skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}}, + hv path/.style={to path={-| (\tikztotarget)}}, + vh path/.style={to path={|- (\tikztotarget)}}}}] +\begin{tikzpicture}[,>=stealth',thick,black!50,text=black, + every new ->/.style={shorten >=1pt}, + graphs/every graph/.style={edges=rounded corners}] + \matrix[column sep=4mm] { \matrixcontent }; + + \graph [use existing nodes] { + p1 -> ui1 -- p2 -> dot -- p3 -> digit -- p4 -- p5 -- p6 -> e -- p7 -- p8 -> ui2 -- p9 -> p10; + p4 ->[skip loop=-5mm] p3; + p2 ->[skip loop=5mm] p5; + p6 ->[skip loop=-11mm] p9; + p7 ->[vh path] { plus, minus } -> [hv path] p8; + }; \end{tikzpicture} \end{codeexample} -\subsubsection{Branching and Joining a Chain} +\subsubsection{Creating Nodes Using the Graph Command} -It is now time to add the plus and minus signs. They obviously -\emph{branch off} the main chain. For this reason, we start a branch -for them using the |start branch| option. +Ilka has heard that the |graph| command is also supposed to make it +easy to create nodes, not only to connect them. This is, indeed, +correct: When the |use existing node| option is not used and when a +node name is not surrounded by parentheses, then \tikzname\ will +actually create a node whose name and text is the node name: \begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}] - \node [nonterminal] {unsigned integer}; - \node [terminal] {.}; - \node [terminal] {digit}; - \node [terminal] {E}; - \begin{scope}[start branch=plus] - \node (plus) [terminal,on chain=going above right] {+}; - \end{scope} - \begin{scope}[start branch=minus] - \node (minus) [terminal,on chain=going below right] {-}; - \end{scope} - \node [nonterminal,join=with plus,join=with minus] {unsigned integer}; -\end{tikzpicture} +\tikz \graph [grow right=2cm] { unsigned integer -> d -> digit -> E }; \end{codeexample} - -Let us see, what is going on here. First, the |start branch| begins a -branch, starting with the node last created on the current chain, -which is the |E| node in our case. This is implicitly also the first -node on this branch. A branch is nothing different from a chain, which -is why the plus node is put on this branch using the |on chain| -option. However, this time we specify the placement of the node -explicitly using |going |\meta{direction}. This causes the plus sign -to be placed above and right of the |E| node. It is automatically -joined to its predecessor on the branch by the implicit |join| -option. - -When the first branch ends, only the plus node has been added and the -current chain is the original chain once more and we are back to the -|E| node. Now we start a new branch for the minus node. After this -branch, the current chain ends at |E| node once more. - -Finally, the rightmost unsigned integer is added to the (main) chain, -which is why it is joined correctly with the |E| node. The two -additional |join| options get a special |with| parameter. This allows -you to join a node with a node other than the predecessor on the -chain. The |with| should be followed by the name of a node. - -Since Ilka will need scopes more often in the following, she includes -the |scopes| library. This allows her to replace |\begin{scope}| - simply by an opening brace and |\end{scope}| by the corresponding -closing brace. Also, in the following example we reference -the nodes |plus| and |minus| using -their automatic name: The $i$th node on a chain is called -|chain-|\meta{i}. For a branch \meta{branch}, the $i$th node is called -|chain/|\meta{branch}|-|\meta{i}. The \meta{i} can be replaced by -|begin| and |end| to reference the first and (currently) last node on -the chain. - +Not quite perfect, but we are getting somewhere. First, let us change +the positioning algorithm by saying |grow right sep|, which causes new +nodes to be placed to the right of the previous nodes with a certain +fixed separation (|1em| by default). Second, we add some options to +make the node ``look nice''. Third, note the funny |d| node above: Ilka +tried writing just |.| there first, but got some error messages. The +reason is that a node cannot be called |.| in \tikzname, so she had to +choose a different name -- which is not good, since she wants a dot to +be shown! The trick is to put the dot in quotation marks, this allows +you to use ``quite arbitrary text'' as a node name: \begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm, every on chain/.style={join}, every join/.style={->}] - \node [on chain,nonterminal] {unsigned integer}; - \node [on chain,terminal] {.}; - \node [on chain,terminal] {digit}; - \node [on chain,terminal] {E}; - { [start branch=plus] - \node (plus) [terminal,on chain=going above right] {+}; - } - { [start branch=minus] - \node (minus) [terminal,on chain=going below right] {-}; - } - \node [nonterminal,on chain,join=with chain/plus-end,join=with chain/minus-end] {unsigned integer}; -\end{tikzpicture} +\tikz \graph [grow right sep] { + unsigned integer[nonterminal] -> "."[terminal] -> digit[terminal] -> E[terminal] +}; \end{codeexample} - - -The next step is to add intermediate coordinate nodes in the same -manner as Ilka did for the matrix. For them, we change the |join| -style slightly, namely for these nodes we do not want an arrow -tip. This can be achieved either by (locally) changing the -|every join| style or, which is what is done in the below example, by -giving the desired style using |join=by ...|, where |...| is the style -to be used for the join. - +Now comes the fork to the plus and minus signs. Here, Ilka can use the +grouping mechanism of the |graph| command to create a split: \begin{codeexample}[] -\begin{tikzpicture}[start chain,node distance=5mm and 2mm, - every node/.style={on chain}, - nonterminal/.append style={join=by ->}, - terminal/.append style={join=by ->}, - point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}] - \node [point] {}; \node [nonterminal] {unsigned integer}; - \node [point] {}; \node [terminal] {.}; - \node [point] {}; \node [terminal] {digit}; - \node [point] {}; \node [point] {}; - \node [point] {}; \node [terminal] {E}; - \node [point] {}; - { [node distance=5mm and 1cm] % local change in horizontal distance - { [start branch=plus] - \node (plus) [terminal,on chain=going above right] {+}; - } - { [start branch=minus] - \node (minus) [terminal,on chain=going below right] {-}; - } - \node [point,below right=of plus,join=with chain/plus-end by ->,join=with chain/minus-end by ->] {}; - } - \node [nonterminal] {unsigned integer}; - \node [point] {}; -\end{tikzpicture} +\tikz \graph [grow right sep] { + unsigned integer [nonterminal] -> + "." [terminal] -> + digit [terminal] -> + E [terminal] -> + { + "+" [terminal], + "" [coordinate], + "-" [terminal] + } -> + ui2/unsigned integer [nonterminal] +}; \end{codeexample} - - -\subsubsection{Chaining Together Already Positioned Nodes} - -The final step is to add the missing arrows. We can also use branches -for them (even though we do not have to, but it is good practice and -they exhibit the structure of the diagram in the code). - -Let us start with the repeat loop around the |digit|. This can be -thought of as a branch that starts at the point after the digit and -that ends at the point before the digit. However, we have already -constructed the point before the digit! In such cases, it is possible -to ``chain in'' an already positioned node, using the |\chainin| -command. This command must be followed by a coordinate that contains a -node name and optionally some options. The effect is that the named -node is made part of the current chain. - -\begin{codeexample}[pre={\tikzset{node distance=5mm and 2mm, - every node/.style={on chain}, - terminal/.append style={join=by ->}, - point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}}}] -\begin{tikzpicture}[start chain] % plus some styles that are not shown - \node [point] {}; - \node (before digit) [point] {}; - \node [terminal] {digit}; - \node [point] {}; - { [start branch=digit loop] - \chainin (before digit) [join=by {->,skip loop=-5mm}]; - } - \node [point] {}; +Let us see, what is happening here. We want two |unsigned integer| +nodes, but if we just were to use this text twice, then \tikzname\ +would have noticed that the same name was used already in the current +graph and, being smart (actually too smart in this case), would have +created an edge back to the already-created node. Thus, a fresh name +is needed here. However, Ilka also cannot just write +|unsigned integer2|, because she wants the original text to be shown, +after all! The trick is to use a slash inside the node name: In +order to ``render'' the node, the text following the slash +is used instead of the node name, which is the text before the +slash. Alternatively, the |as| option can be used, which also +allows you to specify how a node should be rendered. + +It turns out that Ilka does not need to invent a name like +|ui2| for a node that she will not reference again +anyway. In this case, she can just leave out the name (write nothing +before |/|), which always stands for a ``fresh, anonymous'' node name. + +Next, Ilka needs to add some coordinates in between of some nodes +where the back-loops should got and she needs to shift the nodes a +bit: +\begin{codeexample}[pre={\tikzset{ + skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}}, + hv path/.style={to path={-| (\tikztotarget)}}, + vh path/.style={to path={|- (\tikztotarget)}}}}] +\begin{tikzpicture}[>=stealth', thick, black!50, text=black, + every new ->/.style={shorten >=1pt}, + graphs/every graph/.style={edges=rounded corners}] + \graph [grow right sep, branch down=7mm] { + / [coordinate] -> + unsigned integer [nonterminal] -- + p1 [coordinate] -> + "." [terminal] -- + p2 [coordinate] -> + digit [terminal] -- + p3 [coordinate] -- + p4 [coordinate] -- + p5 [coordinate] -> + E [terminal] -- + q1 [coordinate] ->[vh path] + { [nodes={yshift=7mm}] + "+" [terminal], + q2/ [coordinate], + "-" [terminal] + } -> [hv path] + q3 [coordinate] -- + /unsigned integer [nonterminal] -- + p6 [coordinate] -> + / [coordinate]; + + p1 ->[skip loop=5mm] p4; + p3 ->[skip loop=-5mm] p2; + p5 ->[skip loop=-11mm] p6; + }; \end{tikzpicture} \end{codeexample} - -\subsubsection{Combined Use of Matrices and Chains} - -Ilka's final idea is to combine matrices and chains in the following -manner: She will use a matrix to position the nodes. However, to show -the logical ``flow structure'' inside the diagram, she will create -chains and branches that show what is going on. - -Ilka starts with the matrix we had earlier, only with slightly adapted -styles. Then she writes down the main chain and its branches: - +All that remains to be done is to somehow get rid of the strange +curves between the |E| and the unsigned integer. They are caused by +\tikzname's attempt at creating an edge that first goes vertical and +then horizontal but is actually just horizontal. Additionally, the +edge should not really be pointed; but it seems difficult to get rid +of this since the \emph{other} edges from |q1|, namely to |plus| and +|minus| should be pointed. + +It turns out that there is a nice way of solving this problem: You can +specify that a graph is |simple|. This means that there can be at most +one edge between any two nodes. Now, if you specify an edge twice, the +options of the second specification ``win.'' Thus, by adding two more +lines that ``correct'' these edges, we get the final diagram with its +complete code: \begin{codeexample}[] -\begin{tikzpicture}[point/.style={coordinate},>=stealth',thick,draw=black!50, - tip/.style={->,shorten >=1pt},every join/.style={rounded corners}, - hv path/.style={to path={-| (\tikztotarget)}}, - vh path/.style={to path={|- (\tikztotarget)}}] - \matrix[column sep=4mm] { - % First row: - & & & & & & & & & & & \node (plus) [terminal] {+};\\ - % Second row: - \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; & - \node (p2) [point] {}; & \node (dot) [terminal] {.}; & - \node (p3) [point] {}; & \node (digit) [terminal] {digit}; & - \node (p4) [point] {}; & \node (p5) [point] {}; & - \node (p6) [point] {}; & \node (e) [terminal] {E}; & - \node (p7) [point] {}; & & - \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; & - \node (p9) [point] {}; & \node (p10) [point] {};\\ - % Third row: - & & & & & & & & & & & \node (minus)[terminal] {-};\\ +\tikz [>=stealth', black!50, text=black, thick, + every new ->/.style = {shorten >=1pt}, + graphs/every graph/.style = {edges=rounded corners}, + skip loop/.style = {to path={-- ++(0,#1) -| (\tikztotarget)}}, + hv path/.style = {to path={-| (\tikztotarget)}}, + vh path/.style = {to path={|- (\tikztotarget)}}, + nonterminal/.style = { + rectangle, minimum size=6mm, very thick, draw=red!50!black!50, top color=white, + bottom color=red!50!black!20, font=\itshape, text height=1.5ex,text depth=.25ex}, + terminal/.style = { + rounded rectangle, minimum size=6mm, very thick, draw=black!50, top color=white, + bottom color=black!20, font=\ttfamily, text height=1.5ex, text depth=.25ex}, + shape = coordinate + ] + \graph [grow right sep, branch down=7mm, simple] { + / -> unsigned integer[nonterminal] -- p1 -> "." [terminal] -- p2 -> digit[terminal] -- + p3 -- p4 -- p5 -> E[terminal] -- q1 ->[vh path] + {[nodes={yshift=7mm}] + "+"[terminal], q2, "-"[terminal] + } -> [hv path] + q3 -- /unsigned integer [nonterminal] -- p6 -> /; + + p1 ->[skip loop=5mm] p4; + p3 ->[skip loop=-5mm] p2; + p5 ->[skip loop=-11mm] p6; + + q1 -- q2 -- q3; % make these edges plain }; - - { [start chain] - \chainin (p1); - \chainin (ui1) [join=by tip]; - \chainin (p2) [join]; - \chainin (dot) [join=by tip]; - \chainin (p3) [join]; - \chainin (digit) [join=by tip]; - \chainin (p4) [join]; - { [start branch=digit loop] - \chainin (p3) [join=by {skip loop=-6mm,tip}]; - } - \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}]; - \chainin (p6) [join]; - \chainin (e) [join=by tip]; - \chainin (p7) [join]; - { [start branch=plus] - \chainin (plus) [join=by {vh path,tip}]; - \chainin (p8) [join=by {hv path,tip}]; - } - { [start branch=minus] - \chainin (minus) [join=by {vh path,tip}]; - \chainin (p8) [join=by {hv path,tip}]; - } - \chainin (p8) [join]; - \chainin (ui2) [join=by tip]; - \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}]; - \chainin (p10) [join=by tip]; - } -\end{tikzpicture} \end{codeexample} + + + +% \subsection{Using Chains} + +% Matrices allow Ilka to align the nodes nicely, but the connections are +% not quite perfect. The problem is that the code does not really +% reflect the paths that underlie the diagram. + + +% For this reason, Ilka decides to try out \emph{chains} by including +% the |chain| library. Basically, a chain is just a sequence of +% (usually) connected nodes. The nodes can already have been constructed +% or they can be constructed as the chain is constructed (or these +% processes can be mixed). + +% \subsubsection{Creating a Simple Chain} + + +% Ilka starts with creating a chain from scratch. For this, she starts a +% chain using the |start chain| option in a scope. Then, inside the +% scope, she uses the |on chain| option on nodes to add them to the +% chain. +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm] +% \node [on chain,nonterminal] {unsigned integer}; +% \node [on chain,terminal] {.}; +% \node [on chain,terminal] {digit}; +% \node [on chain,terminal] {E}; +% \node [on chain,nonterminal] {unsigned integer}; +% \end{tikzpicture} +% \end{codeexample} +% (Ilka will add the plus and minus nodes later.) + +% As can be seen, the nodes of a chain are placed in a row. This can be +% changed, for instance by saying |start chain=going below| we get a +% chain where each node is below the previous one. + +% The next step is to \emph{join} the nodes of the chain. For this, we +% add the |join| option to each node. This joins the node with the +% previous node (for the first node nothing happens). +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm] +% \node [on chain,join,nonterminal] {unsigned integer}; +% \node [on chain,join,terminal] {.}; +% \node [on chain,join,terminal] {digit}; +% \node [on chain,join,terminal] {E}; +% \node [on chain,join,nonterminal] {unsigned integer}; +% \end{tikzpicture} +% \end{codeexample} +% In order to get a arrow tip, we redefine the |every join| style. Also, +% we move the |join| and |on chain| options to the |every node| +% style so that we do not have to repeat them so often. +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}] +% \node [nonterminal] {unsigned integer}; +% \node [terminal] {.}; +% \node [terminal] {digit}; +% \node [terminal] {E}; +% \node [nonterminal] {unsigned integer}; +% \end{tikzpicture} +% \end{codeexample} + + +% \subsubsection{Branching and Joining a Chain} + +% It is now time to add the plus and minus signs. They obviously +% \emph{branch off} the main chain. For this reason, we start a branch +% for them using the |start branch| option. +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}] +% \node [nonterminal] {unsigned integer}; +% \node [terminal] {.}; +% \node [terminal] {digit}; +% \node [terminal] {E}; +% \begin{scope}[start branch=plus] +% \node (plus) [terminal,on chain=going above right] {+}; +% \end{scope} +% \begin{scope}[start branch=minus] +% \node (minus) [terminal,on chain=going below right] {-}; +% \end{scope} +% \node [nonterminal,join=with plus,join=with minus] {unsigned integer}; +% \end{tikzpicture} +% \end{codeexample} + +% Let us see, what is going on here. First, the |start branch| begins a +% branch, starting with the node last created on the current chain, +% which is the |E| node in our case. This is implicitly also the first +% node on this branch. A branch is nothing different from a chain, which +% is why the plus node is put on this branch using the |on chain| +% option. However, this time we specify the placement of the node +% explicitly using |going |\meta{direction}. This causes the plus sign +% to be placed above and right of the |E| node. It is automatically +% joined to its predecessor on the branch by the implicit |join| +% option. + +% When the first branch ends, only the plus node has been added and the +% current chain is the original chain once more and we are back to the +% |E| node. Now we start a new branch for the minus node. After this +% branch, the current chain ends at |E| node once more. + +% Finally, the rightmost unsigned integer is added to the (main) chain, +% which is why it is joined correctly with the |E| node. The two +% additional |join| options get a special |with| parameter. This allows +% you to join a node with a node other than the predecessor on the +% chain. The |with| should be followed by the name of a node. + +% Since Ilka will need scopes more often in the following, she includes +% the |scopes| library. This allows her to replace |\begin{scope}| +% simply by an opening brace and |\end{scope}| by the corresponding +% closing brace. Also, in the following example we reference +% the nodes |plus| and |minus| using +% their automatic name: The $i$th node on a chain is called +% |chain-|\meta{i}. For a branch \meta{branch}, the $i$th node is called +% |chain/|\meta{branch}|-|\meta{i}. The \meta{i} can be replaced by +% |begin| and |end| to reference the first and (currently) last node on +% the chain. + +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm, every on chain/.style={join}, every join/.style={->}] +% \node [on chain,nonterminal] {unsigned integer}; +% \node [on chain,terminal] {.}; +% \node [on chain,terminal] {digit}; +% \node [on chain,terminal] {E}; +% { [start branch=plus] +% \node (plus) [terminal,on chain=going above right] {+}; +% } +% { [start branch=minus] +% \node (minus) [terminal,on chain=going below right] {-}; +% } +% \node [nonterminal,on chain,join=with chain/plus-end,join=with chain/minus-end] {unsigned integer}; +% \end{tikzpicture} +% \end{codeexample} + + +% The next step is to add intermediate coordinate nodes in the same +% manner as Ilka did for the matrix. For them, we change the |join| +% style slightly, namely for these nodes we do not want an arrow +% tip. This can be achieved either by (locally) changing the +% |every join| style or, which is what is done in the below example, by +% giving the desired style using |join=by ...|, where |...| is the style +% to be used for the join. + +% \begin{codeexample}[] +% \begin{tikzpicture}[start chain,node distance=5mm and 2mm, +% every node/.style={on chain}, +% nonterminal/.append style={join=by ->}, +% terminal/.append style={join=by ->}, +% point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}] +% \node [point] {}; \node [nonterminal] {unsigned integer}; +% \node [point] {}; \node [terminal] {.}; +% \node [point] {}; \node [terminal] {digit}; +% \node [point] {}; \node [point] {}; +% \node [point] {}; \node [terminal] {E}; +% \node [point] {}; +% { [node distance=5mm and 1cm] % local change in horizontal distance +% { [start branch=plus] +% \node (plus) [terminal,on chain=going above right] {+}; +% } +% { [start branch=minus] +% \node (minus) [terminal,on chain=going below right] {-}; +% } +% \node [point,below right=of plus,join=with chain/plus-end by ->,join=with chain/minus-end by ->] {}; +% } +% \node [nonterminal] {unsigned integer}; +% \node [point] {}; +% \end{tikzpicture} +% \end{codeexample} + + +% \subsubsection{Chaining Together Already Positioned Nodes} + +% The final step is to add the missing arrows. We can also use branches +% for them (even though we do not have to, but it is good practice and +% they exhibit the structure of the diagram in the code). + +% Let us start with the repeat loop around the |digit|. This can be +% thought of as a branch that starts at the point after the digit and +% that ends at the point before the digit. However, we have already +% constructed the point before the digit! In such cases, it is possible +% to ``chain in'' an already positioned node, using the |\chainin| +% command. This command must be followed by a coordinate that contains a +% node name and optionally some options. The effect is that the named +% node is made part of the current chain. + +% \begin{codeexample}[pre={\tikzset{node distance=5mm and 2mm, +% every node/.style={on chain}, +% terminal/.append style={join=by ->}, +% point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}}}] +% \begin{tikzpicture}[start chain] % plus some styles that are not shown +% \node [point] {}; +% \node (before digit) [point] {}; +% \node [terminal] {digit}; +% \node [point] {}; +% { [start branch=digit loop] +% \chainin (before digit) [join=by {->,skip loop=-5mm}]; +% } +% \node [point] {}; +% \end{tikzpicture} +% \end{codeexample} + + +% \subsubsection{Combined Use of Matrices and Chains} + +% Ilka's final idea is to combine matrices and chains in the following +% manner: She will use a matrix to position the nodes. However, to show +% the logical ``flow structure'' inside the diagram, she will create +% chains and branches that show what is going on. + +% Ilka starts with the matrix we had earlier, only with slightly adapted +% styles. Then she writes down the main chain and its branches: + +% \begin{codeexample}[] +% \begin{tikzpicture}[point/.style={coordinate},>=stealth',thick,draw=black!50, +% tip/.style={->,shorten >=1pt},every join/.style={rounded corners}, +% hv path/.style={to path={-| (\tikztotarget)}}, +% vh path/.style={to path={|- (\tikztotarget)}}] +% \matrix[column sep=4mm] { +% % First row: +% & & & & & & & & & & & \node (plus) [terminal] {+};\\ +% % Second row: +% \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; & +% \node (p2) [point] {}; & \node (dot) [terminal] {.}; & +% \node (p3) [point] {}; & \node (digit) [terminal] {digit}; & +% \node (p4) [point] {}; & \node (p5) [point] {}; & +% \node (p6) [point] {}; & \node (e) [terminal] {E}; & +% \node (p7) [point] {}; & & +% \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; & +% \node (p9) [point] {}; & \node (p10) [point] {};\\ +% % Third row: +% & & & & & & & & & & & \node (minus)[terminal] {-};\\ +% }; + +% { [start chain] +% \chainin (p1); +% \chainin (ui1) [join=by tip]; +% \chainin (p2) [join]; +% \chainin (dot) [join=by tip]; +% \chainin (p3) [join]; +% \chainin (digit) [join=by tip]; +% \chainin (p4) [join]; +% { [start branch=digit loop] +% \chainin (p3) [join=by {skip loop=-6mm,tip}]; +% } +% \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}]; +% \chainin (p6) [join]; +% \chainin (e) [join=by tip]; +% \chainin (p7) [join]; +% { [start branch=plus] +% \chainin (plus) [join=by {vh path,tip}]; +% \chainin (p8) [join=by {hv path,tip}]; +% } +% { [start branch=minus] +% \chainin (minus) [join=by {vh path,tip}]; +% \chainin (p8) [join=by {hv path,tip}]; +% } +% \chainin (p8) [join]; +% \chainin (ui2) [join=by tip]; +% \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}]; +% \chainin (p10) [join=by tip]; +% } +% \end{tikzpicture} +% \end{codeexample} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-map.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-map.tex index ec0ea535f38..99a173f9e39 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-map.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-map.tex @@ -43,17 +43,17 @@ Johannes wishes to create a lecture map with the following features: \end{enumerate} As always, Johannes will have to include the right libraries and -setup the environment. Since Johannes is going to use the -|mindmap| library and since he wishes to show a calendar, he will need -the |mindmap| and the |calendar| libraries. In order to put something +set up the environment. Johannes is going to use the +|mindmap| library and since he wishes to show a calendar, he will also need +the |calendar| library. In order to put something on a background layer, it seems like a good idea to also include the -|background| library. +|backgrounds| library. \subsection{Introduction to Trees} The first choice Johannes must make is whether he will organize the -concepts are a tree, with root concepts and concept branches and leaf +concepts as a tree, with root concepts and concept branches and leaf concepts, or as a general graph. The tree implicitly organizes the concepts, while a graph is more flexible. Johannes decides to compromise: Basically, the concepts will be organized as a @@ -229,7 +229,7 @@ a rainy Sunday afternoon, if you are really interested.) The |grow| key is used to configure the direction in which a tree grows. You can change growth direction ``in the middle of a tree'' simply by changing this key for a single child or a whole level. By -including the |tree| library you also get access to additional growth +including the |trees| library you also get access to additional growth strategies such as a ``circular'' growth: @@ -271,7 +271,7 @@ strategies such as a ``circular'' growth: Johannes is pleased to learn that he can access and manipulate the -nodes of tree like any normal node. In particular, he can name them +nodes of the tree like any normal node. In particular, he can name them using the |name=| option or the |(|\meta{name}|)| notation and he can use any available shape or style for the trees nodes. He can connect trees later on using the normal |\draw (some node) -- (another node);| @@ -302,7 +302,7 @@ of a tree will be real concepts, while other nodes might just be ``simple children.'' Typically, this is not the case, so you might consider saying |every node/.style=concept|. -The third step is to setup the sibling \emph{angle} (rather than a +The third step is to set up the sibling \emph{angle} (rather than a sibling distance) to specify the angle between sibling concepts. \begin{codeexample}[render instead={ @@ -449,7 +449,7 @@ of a parent concept smoothly changes to the color of a child concept. For the root concept Johannes decides to do something special: He sets the concept color to black, sets the line width to a large value, and sets the fill color to white. The effect of this is that the root -concept will encircled with a thick black line and the children are +concept will be encircled with a thick black line and the children are connected to the central concept via bars. \begin{codeexample}[render instead={ @@ -530,7 +530,7 @@ of the main concepts to small caps. Second, he decides that some concepts should be ``faded,'' namely those that are important in principle and belong on the map, but which he will not talk about in his lecture. To achieve this, Johannes defines four styles, one for -each of the four main branches. These styles (a) setup the +each of the four main branches. These styles (a) set up the correct concept color for the whole branch and (b) define the |faded| style appropriately for this branch. Third, he adds a |circular drop shadow|, defined in the |shadows| library, to the @@ -621,7 +621,7 @@ qualifications his students should acquire during this particular lecture (note that learning targets are not the same as the contents of a lecture). For each lecture he intends to put a little rectangle on the map containing these learning targets and the name of the -lecture, each time somewhere near to the topic of the lecture. Such +lecture, each time somewhere near the topic of the lecture. Such ``little rectangles'' are called ``annotations'' by the mindmap library. @@ -851,7 +851,7 @@ Johannes would have thought. At first sight, what he needs is some sort of ``color wheel'' that is blue in the lower right direction and then changes smoothly to orange in the upper right direction and then to green in the upper left direction and so on. Unfortunately, there -is no easy way of creating a true such a color wheel shading (although +is no easy way of creating such a color wheel shading (although it can be done, in principle, but only at a very high cost, see page~\pageref{shading-color-wheel} for an example). @@ -923,7 +923,7 @@ subject will be addressed. Johannes intends to share this plan with his students by adding a calendar to the lecture map. In addition to serving as a reference on which particular day a certain topic will be addressed, the -calendar is also useful so show the overall chronological order of the +calendar is also useful to show the overall chronological order of the course. In order to add a calendar to a \tikzname\ graphic, the |calendar| diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex index f9c5eb8de53..b9a97e2046e 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex @@ -14,11 +14,11 @@ In this second tutorial we explore the node mechanism of Hagen must give a talk tomorrow about his favorite formalism for distributed systems: Petri nets! Hagen used to give his talks using a -blackboard and everyone seemed to be perfectly concent with % TODOsp: concent --> consent? +blackboard and everyone seemed to be perfectly content with this. Unfortunately, his audience has been spoiled recently with fancy projector-based presentations and there seems to be a certain amount -of peer pressure that this Petri nets should also be drawn using a -graphic program. One of the professors at his institutes recommends +of peer pressure that his Petri nets should also be drawn using a +graphic program. One of the professors at his institute recommends \tikzname\ for this and Hagen decides to give it a try. @@ -102,10 +102,10 @@ capacities. The graphic should look like this, ideally: edge [post,bend left] node {2} (w2'); \end{scope} - \begin{pgfonlayer}{background} + \begin{scope}[on background layer] \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {}; \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {}; - \end{pgfonlayer} + \end{scope} \draw [shorten >=1mm,-to,thick,decorate,decoration={snake,amplitude=.4mm,segment length=2mm,pre=moveto,pre length=1mm,post length=2mm}] @@ -128,7 +128,7 @@ loaded explicitly. Hagen will need to load several libraries: The |arrows| library for the special arrow tip used in the graphic, the |decoration.pathmorphing| -library for the ``snaking line'' in the middle, the background +library for the ``snaking line'' in the middle, the |backgrounds| library for the two rectangular areas that are behind the two main parts of the picture, the |fit| library to easily compute the sizes of these rectangles, and the |positioning| library for placing nodes @@ -173,9 +173,7 @@ When using plain \TeX\ use: \subsubsection{Setting up the Environment in Con\TeX t} -When using Con\TeX\ use\footnote{Note that \pgfname/\tikzname{} is not - supported by recent Con\TeX t versions (like mark IV, the - Lua\TeX-aware part of Con\TeX t).}: +When using Con\TeX, use: \begin{codeexample}[code only] %% ConTeXt file \usemodule[tikz] @@ -201,8 +199,7 @@ However, this approach has numerous disadvantages: First, it is hard to change anything at a later stage. For example, if we decide to add more places to the Petri nets (the circles are called places in Petri net theory), all of the coordinates change and we need to recalculate -everything. Second, it is hard to read the code for the Petri net as -it just a long and complicated list of coordinates and drawing +everything. Second, it is hard to read the code for the Petri net as it is just a long and complicated list of coordinates and drawing commands -- the underlying structure of the Petri net is lost. Fortunately, \tikzname\ offers a powerful mechanism for avoiding the @@ -214,7 +211,7 @@ A node is a small part of a picture. When a node is created, you provide a position where the node should be drawn and a \emph{shape}. A node of shape |circle| will be drawn as a circle, a node of shape |rectangle| as a rectangle, and so on. A node may also -contain same text, which is why Karl used nodes to show text. Finally, +contain some text, which is why Karl used nodes to show text. Finally, a node can get a \emph{name} for later reference. In Hagen's picture we will use nodes for the places and for the @@ -239,7 +236,7 @@ Hagen notes that this does not quite look like the final picture, but it seems like a good first step. Let us have a more detailed look at the code. The whole picture -consists of a single path. Ignoring the |node| operations there is not +consists of a single path. Ignoring the |node| operations, there is not much going on in this path: It is just a sequence of coordinates with nothing ``happening'' between them. Indeed, even if something were to happen like a line-to or a curve-to, the |\path| command would not @@ -256,10 +253,10 @@ answer is the |draw| option for the |node| operation: It causes the So, the code |(0,2) node [shape=circle,draw] {}| means the following: ``In the main path, add a move-to to the coordinate |(0,2)|. Then, temporarily suspend the construction of the main path while the node -is build. This node will be a |circle| around an empty text. This +is built. This node will be a |circle| around an empty text. This circle is to be |draw|n, but not filled or otherwise used. Once this whole node is constructed, it is saved until after the -main path is finished. Then, it is drawn.'' Then following +main path is finished. Then, it is drawn.'' The following |(0,1) node [shape=circle,draw] {}| then has the following effect: ``Continue the main path with a move-to to |(0,1)|. Then construct a node at this position also. This node is also shown after the main @@ -353,7 +350,7 @@ places and another style for transitions: Before Hagen starts naming and connecting the nodes, let us first make sure that the nodes get their final appearance. They are still too small. Indeed, Hagen wonders why they have any size at all, after -all, the text is empty. The reason is than \tikzname\ automatically +all, the text is empty. The reason is that \tikzname\ automatically adds some space around the text. The amount is set using the option |inner sep|. So, to increase the size of the nodes, Hagen could write: @@ -373,7 +370,7 @@ adds some space around the text. The amount is set using the option However, this is not really the best way to achieve the desired effect. It is much better to use the |minimum size| option instead. This option allows Hagen to specify a minimum size that the -node should have. If the nodes actually needs to be bigger because of +node should have. If the node actually needs to be bigger because of a longer text, it will be larger, but if the text is empty, then the node will have |minimum size|. This option is also useful to ensure that several nodes containing different amounts of text have the same @@ -414,7 +411,7 @@ Fortunately, \pgfname\ will perform all the necessary calculations for him. However, he first has to assign names to the nodes so that he can reference them later on. -There are two ways to name a node. The first is the use the |name=| +There are two ways to name a node. The first is to use the |name=| option. The second method is to write the desired name in parentheses after the |node| operation. Hagen thinks that this second method seems strange, but he will soon change his opinion. @@ -425,7 +422,7 @@ strange, but he will soon change his opinion. transition/.style={rectangle,draw=black!50,fill=black!20,thick, inner sep=0pt,minimum size=4mm}} \begin{codeexample}[] -% ... setup styles +% ... set up styles \begin{tikzpicture} \node (waiting 1) at ( 0,2) [place] {}; \node (critical 1) at ( 0,1) [place] {}; @@ -499,7 +496,7 @@ either the distance between the centers of the nodes (when the |on grid| option is set to true) or the distance between the borders (when the |on grid| option is set to false, which is the default). -Even though the above code has the same effect the earlier code, Hagen +Even though the above code has the same effect as the earlier code, Hagen can pass it to his colleagues who will be able to just read and understand it, perhaps without even having to see the picture. @@ -710,7 +707,7 @@ transition/.style={rectangle,draw=black!50,fill=black!20,thick, There is another option for the |to| operation, that is even better suited to Hagen's problem: The |bend right| option. This option also takes an angle, but this angle only specifies the angle by which the -curve is bend to the right: +curve is bent to the right: { \tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, @@ -737,7 +734,7 @@ to the |to| operation, but there is one important difference: Like a node the edge generated by the |edge| operation is not part of the main path, but is added only later. This may not seem very important, but it has some nice consequences. For example, every edge can have -its own arrow tips and its own color and so one and, still, all the +its own arrow tips and its own color and so on and, still, all the edges can be given on the same path. This allows Hagen to write the following: @@ -869,7 +866,7 @@ nets. What he is unsure of is how he can create the snaked line between the nets. For this he can use a \emph{decoration}. -To draw the snake, Hagen only needs to set the two options +To draw the snaked line, Hagen only needs to set the two options |decoration=snake| and |decorate| on the path. This causes all lines of the path to be replaced by snakes. It is also possible to use snakes only in certain parts of a @@ -943,8 +940,9 @@ rectangle. If Hagen draws the rectangle first, then he needs to know the exact size of the Petri net -- which he does not. The solution is to use \emph{layers}. When the background library is -loaded, Hagen can put parts of his picture inside a |{pgfonlayer}| -environment. Then this part of the picture becomes part of the layer +loaded, Hagen can put parts of his picture inside a scope with the +|on background layer| option. Then this part of the picture becomes +part of the layer that is given as an argument to this environment. When the |{tikzpicture}| environment ends, the layers are put on top of each other, starting with the background layer. This causes everything @@ -955,7 +953,7 @@ Naturally, Hagen can compute the size ``by hand'' or using some clever observations concerning the $x$- and $y$-coordinates of the nodes, but it would be nicer to just have \tikzname\ compute a rectangle into which all the nodes ``fit.'' For this, the |fit| library can be -used. It defines the |fit| options, which, when give to a node, causes +used. It defines the |fit| options, which, when given to a node, causes the node to be resized and shifted such that it exactly covers all the nodes and coordinates given as parameters to the |fit| option. @@ -982,17 +980,16 @@ post/.style={->,shorten >=1pt,>=stealth',semithick}} edge [pre, bend left] (waiting) edge [post,bend right] (semaphore); - \begin{pgfonlayer}{background} + \begin{scope}[on background layer] \node [fill=black!30,fit=(waiting) (critical) (semaphore) (leave critical) (enter critical)] {}; - \end{pgfonlayer} + \end{scope} \end{tikzpicture} \end{codeexample} } - \subsection{The Complete Code} Hagen has now finally put everything together. Only then does he learn @@ -1096,10 +1093,10 @@ every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto} The code for the background and the snake is the following: \begin{codeexample}[code only] - \begin{pgfonlayer}{background} + \begin{scope}[on background layer] \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {}; \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {}; - \end{pgfonlayer} + \end{scope} \draw [shorten >=1mm,-to,thick,decorate, decoration={snake,amplitude=.4mm,segment length=2mm, diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex.orig b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex.orig deleted file mode 100644 index 99ac79cd642..00000000000 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial-nodes.tex.orig +++ /dev/null @@ -1,1108 +0,0 @@ -% Copyright 2006 by Tilo Tantau -% -% This file may be distributed and/or modified -% -% 1. under the LaTeX Project Public License and/or -% 2. under the GNU Free Documentation License. -% -% See the file doc/generic/pgf/licenses/LICENSE for more details. - -\section{Tutorial: A Petri-Net for Hagen} - -In this second tutorial we explore the node mechanism of -\tikzname\ and \pgfname. - -Hagen must give a talk tomorrow about his favorite formalism for -distributed systems: Petri nets! Hagen used to give his talks using a -blackboard and everyone seemed to be perfectly concent with % TODOsp: concent --> consent? -this. Unfortunately, his audience has been spoiled recently with fancy -projector-based presentations and there seems to be a certain amount -of peer pressure that this Petri nets should also be drawn using a -graphic program. One of the professors at his institutes recommends -\tikzname\ for this and Hagen decides to give it a try. - - -\subsection{Problem Statement} - -For his talk, Hagen wishes to create a graphic that demonstrates how a -net with place capacities can be simulated by a net without -capacities. The graphic should look like this, ideally: - -\begin{quote} -\begin{tikzpicture} - [node distance=1.3cm,>=stealth',bend angle=45,auto, - place/.style={circle,thick,draw=blue!75,fill=blue!20,minimum size=6mm}, - red place/.style={place,draw=red!75,fill=red!20}, - transition/.style={rectangle,thick,draw=black!75,fill=black!20,minimum size=4mm}, - every label/.style={red},on grid] - - \begin{scope} - % First net - \node [place,tokens=1] (w1) {}; - \node [place] (c1) [below=of w1] {}; - \node [place] (s) [below=of c1,label=above:$s\le 3$] {}; - \node [place] (c2) [below=of s] {}; - \node [place,tokens=1] (w2) [below=of c2] {}; - - \node [transition] (e1) [left=of c1] {} - edge [pre,bend left] (w1) - edge [post,bend right] (s) - edge [post] (c1); - - \node [transition] (e2) [left=of c2] {} - edge [pre,bend right] (w2) - edge [post,bend left] (s) - edge [post] (c2); - - \node [transition] (l1) [right=of c1] {} - edge [pre] (c1) - edge [pre,bend left] (s) - edge [post,bend right] node[swap] {2} (w1); - - \node [transition] (l2) [right=of c2] {} - edge [pre] (c2) - edge [pre,bend right] (s) - edge [post,bend left] node {2} (w2); - \end{scope} - - \begin{scope}[xshift=6cm] - % Second net - \node [place,tokens=1] - (w1') {}; - \node [place] (c1') [below=of w1'] {}; - \node [red place] (s1') [below=of c1',xshift=-5mm,label=left:$s$] {}; - \node [red place,tokens=3] - (s2') [below=of c1',xshift=5mm,label=right:$\bar s$] {}; - \node [place] (c2') [below=of s1',xshift=5mm] {}; - \node [place,tokens=1] - (w2') [below=of c2'] {}; - - \node [transition] (e1') [left=of c1'] {} - edge [pre,bend left] (w1') - edge [post] (s1') - edge [pre] (s2') - edge [post] (c1'); - - \node [transition] (e2') [left=of c2'] {} - edge [pre,bend right] (w2') - edge [post] (s1') - edge [pre] (s2') - edge [post] (c2'); - - \node [transition] (l1') [right=of c1'] {} - edge [pre] (c1') - edge [pre] (s1') - edge [post] (s2') - edge [post,bend right] node[swap] {2} (w1'); - - \node [transition] (l2') [right=of c2'] {} - edge [pre] (c2') - edge [pre] (s1') - edge [post] (s2') - edge [post,bend left] node {2} (w2'); - \end{scope} - - \begin{pgfonlayer}{background} - \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {}; - \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {}; - \end{pgfonlayer} - - \draw [shorten >=1mm,-to,thick,decorate,decoration={snake,amplitude=.4mm,segment - length=2mm,pre=moveto,pre length=1mm,post length=2mm}] - (r1) -- (r2) - node [above=1mm,midway,text width=3cm,align=center] - {replacement of the \textcolor{red}{capacity} by \textcolor{red}{two places}}; - -\end{tikzpicture} -\end{quote} - - -\subsection{Setting up the Environment} - -For the picture Hagen will need to load the \tikzname\ package as did -Karl in the previous tutorial. However, Hagen will also need to load -some additional \emph{library packages} that Karl did not need. These -library packages contain additional definitions like extra arrow tips -that are typically not needed in a picture and that need to be -loaded explicitly. - -Hagen will need to load several libraries: The |arrows| library for the -special arrow tip used in the graphic, the |decoration.pathmorphing| -library for the ``snaking line'' in the middle, the background -library for the two rectangular areas that are behind the two main -parts of the picture, the |fit| library to easily compute the sizes of -these rectangles, and the |positioning| library for placing nodes -relative to other nodes. - - -\subsubsection{Setting up the Environment in \LaTeX} - -When using \LaTeX\ use: - -\begin{codeexample}[code only] -\documentclass{article} % say - -\usepackage{tikz} -\usetikzlibrary{arrows,decorations.pathmorphing,backgrounds,positioning,fit,petri} - -\begin{document} -\begin{tikzpicture} - \draw (0,0) -- (1,1); -\end{tikzpicture} -\end{document} -\end{codeexample} - - -\subsubsection{Setting up the Environment in Plain \TeX} - -When using plain \TeX\ use: - -\begin{codeexample}[code only] -%% Plain TeX file -\input tikz.tex -\usetikzlibrary{arrows,decorations.pathmorphing,backgrounds,positioning,fit,petri} -\baselineskip=12pt -\hsize=6.3truein -\vsize=8.7truein -\tikzpicture - \draw (0,0) -- (1,1); -\endtikzpicture -\bye -\end{codeexample} - - -\subsubsection{Setting up the Environment in Con\TeX t} - -When using Con\TeX\ use: -\begin{codeexample}[code only] -%% ConTeXt file -\usemodule[tikz] -\usetikzlibrary[arrows,decorations.pathmorphing,backgrounds,positioning,fit,petri] - -\starttext - \starttikzpicture - \draw (0,0) -- (1,1); - \stoptikzpicture -\stoptext -\end{codeexample} - - - -\subsection{Introduction to Nodes} - -In principle, we already know how to create the graphics that Hagen -desires (except perhaps for the snaked line, we will come to that): We -start with big light gray rectangle and then add lots of circles and -small rectangle, plus some arrows. - -However, this approach has numerous disadvantages: First, it is hard -to change anything at a later stage. For example, if we decide to add -more places to the Petri nets (the circles are called places in Petri -net theory), all of the coordinates change and we need to recalculate -everything. Second, it is hard to read the code for the Petri net as -it just a long and complicated list of coordinates and drawing -commands -- the underlying structure of the Petri net is lost. - -Fortunately, \tikzname\ offers a powerful mechanism for avoiding the -above problems: nodes. We already came across nodes in the previous -tutorial, where we used them to add labels to Karl's graphic. In the -present tutorial we will see that nodes are much more powerful. - -A node is a small part of a picture. When a node is created, you -provide a position where the node should be drawn and a -\emph{shape}. A node of shape |circle| will be drawn as a circle, a -node of shape |rectangle| as a rectangle, and so on. A node may also -contain same text, which is why Karl used nodes to show text. Finally, -a node can get a \emph{name} for later reference. - -In Hagen's picture we will use nodes for the places and for the -transitions of the Petri net (the places are the circles, the -transitions are the rectangles). Let us start with the upper half of -the left Petri net. In this upper half we have three places and two -transitions. Instead of drawing three circles and two rectangles, we -use three nodes of shape |circle| and two nodes of shape -|rectangle|. - -\begin{codeexample}[] -\begin{tikzpicture} - \path ( 0,2) node [shape=circle,draw] {} - ( 0,1) node [shape=circle,draw] {} - ( 0,0) node [shape=circle,draw] {} - ( 1,1) node [shape=rectangle,draw] {} - (-1,1) node [shape=rectangle,draw] {}; -\end{tikzpicture} -\end{codeexample} - -Hagen notes that this does not quite look like the final picture, but -it seems like a good first step. - -Let us have a more detailed look at the code. The whole picture -consists of a single path. Ignoring the |node| operations there is not -much going on in this path: It is just a sequence of coordinates with -nothing ``happening'' between them. Indeed, even if something were to -happen like a line-to or a curve-to, the |\path| command would not -``do'' anything with the resulting path. So, all the magic must be in -the |node| commands. - -In the previous tutorial we learned that a |node| will add a piece of -text at the last coordinate. Thus, each of the five nodes is added at -a different position. In the above code, this text is empty -(because of the empty |{}|). So, why do we see anything at all? The -answer is the |draw| option for the |node| operation: It causes the -``shape around the text'' to be drawn. - -So, the code |(0,2) node [shape=circle,draw] {}| means the following: -``In the main path, add a move-to to the coordinate |(0,2)|. Then, -temporarily suspend the construction of the main path while the node -is build. This node will be a |circle| around an empty text. This -circle is to be |draw|n, but not filled or otherwise used. Once this -whole node is constructed, it is saved until after the -main path is finished. Then, it is drawn.'' Then following -|(0,1) node [shape=circle,draw] {}| then has the following effect: -``Continue the main path with a move-to to |(0,1)|. Then construct a -node at this position also. This node is also shown after the main -path is finished.'' And so on. - - - -\subsection{Placing Nodes Using the At Syntax} - -Hagen now understands how the |node| operation adds nodes to the path, -but it seems a bit silly to create a path using the |\path| operation, -consisting of numerous superfluous move-to operations, only to place -nodes. He is pleased to learn that there are ways to add nodes in a -more sensible manner. - -First, the |node| operation allows one to add -|at (|\meta{coordinate}|)| in order to directly specify where the node -should be placed, sidestepping the rule that nodes are placed on the -last coordinate. Hagen can then write the following: - -\begin{codeexample}[] -\begin{tikzpicture} - \path node at ( 0,2) [shape=circle,draw] {} - node at ( 0,1) [shape=circle,draw] {} - node at ( 0,0) [shape=circle,draw] {} - node at ( 1,1) [shape=rectangle,draw] {} - node at (-1,1) [shape=rectangle,draw] {}; -\end{tikzpicture} -\end{codeexample} - -Now Hagen is still left with a single empty path, but at least the -path no longer contains strange move-tos. It turns out that this can -be improved further: The |\node| command is an abbreviation for -|\path node|, which allows Hagen to write: - -\begin{codeexample}[] -\begin{tikzpicture} - \node at ( 0,2) [circle,draw] {}; - \node at ( 0,1) [circle,draw] {}; - \node at ( 0,0) [circle,draw] {}; - \node at ( 1,1) [rectangle,draw] {}; - \node at (-1,1) [rectangle,draw] {}; -\end{tikzpicture} -\end{codeexample} - -Hagen likes this syntax much better than the previous one. Note that -Hagen has also omitted the |shape=| since, like |color=|, \tikzname\ -allows you to omit the |shape=| if there is no confusion. - - - -\subsection{Using Styles} - -Feeling adventurous, Hagen tries to make the nodes look nicer. In the -final picture, the circles and rectangle should be filled with -different colors, resulting in the following code: - -\begin{codeexample}[] -\begin{tikzpicture}[thick] - \node at ( 0,2) [circle,draw=blue!50,fill=blue!20] {}; - \node at ( 0,1) [circle,draw=blue!50,fill=blue!20] {}; - \node at ( 0,0) [circle,draw=blue!50,fill=blue!20] {}; - \node at ( 1,1) [rectangle,draw=black!50,fill=black!20] {}; - \node at (-1,1) [rectangle,draw=black!50,fill=black!20] {}; -\end{tikzpicture} -\end{codeexample} - -While this looks nicer in the picture, the code starts to get a bit -ugly. Ideally, we would like our code to transport the message ``there -are three places and two transitions'' and not so much which -filling colors should be used. - -To solve this problem, Hagen uses styles. He defines a style for -places and another style for transitions: - -\begin{codeexample}[] -\begin{tikzpicture} - [place/.style={circle,draw=blue!50,fill=blue!20,thick}, - transition/.style={rectangle,draw=black!50,fill=black!20,thick}] - \node at ( 0,2) [place] {}; - \node at ( 0,1) [place] {}; - \node at ( 0,0) [place] {}; - \node at ( 1,1) [transition] {}; - \node at (-1,1) [transition] {}; -\end{tikzpicture} -\end{codeexample} - - -\subsection{Node Size} - -Before Hagen starts naming and connecting the nodes, let us first -make sure that the nodes get their final appearance. They are still -too small. Indeed, Hagen wonders why they have any size at all, after -all, the text is empty. The reason is than \tikzname\ automatically -adds some space around the text. The amount is set using the option -|inner sep|. So, to increase the size of the nodes, Hagen could write: - -\begin{codeexample}[] -\begin{tikzpicture} - [inner sep=2mm, - place/.style={circle,draw=blue!50,fill=blue!20,thick}, - transition/.style={rectangle,draw=black!50,fill=black!20,thick}] - \node at ( 0,2) [place] {}; - \node at ( 0,1) [place] {}; - \node at ( 0,0) [place] {}; - \node at ( 1,1) [transition] {}; - \node at (-1,1) [transition] {}; -\end{tikzpicture} -\end{codeexample} - -However, this is not really the best way to achieve the desired -effect. It is much better to use the |minimum size| option -instead. This option allows Hagen to specify a minimum size that the -node should have. If the nodes actually needs to be bigger because of -a longer text, it will be larger, but if the text is empty, then the -node will have |minimum size|. This option is also useful to ensure -that several nodes containing different amounts of text have the same -size. The options |minimum height| and |minimum width| allow you to -specify the minimum height and width independently. - -So, what Hagen needs to do is to provide |minimum size| for the -nodes. To be on the safe side, he also sets |inner sep=0pt|. This -ensures that the nodes will really have size |minimum size| and not, -for very small minimum sizes, the minimal size necessary to encompass -the automatically added space. - -\begin{codeexample}[] -\begin{tikzpicture} - [place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, - transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}] - \node at ( 0,2) [place] {}; - \node at ( 0,1) [place] {}; - \node at ( 0,0) [place] {}; - \node at ( 1,1) [transition] {}; - \node at (-1,1) [transition] {}; -\end{tikzpicture} -\end{codeexample} - - - - -\subsection{Naming Nodes} - -Hagen's next aim is to connect the nodes using arrows. This seems like -a tricky business since the arrows should not start in the middle of -the nodes, but somewhere on the border and Hagen would very much like -to avoid computing these positions by hand. - -Fortunately, \pgfname\ will perform all the necessary calculations for -him. However, he first has to assign names to the nodes so that he can -reference them later on. - -There are two ways to name a node. The first is the use the |name=| -option. The second method is to write the desired name in parentheses -after the |node| operation. Hagen thinks that this second method seems -strange, but he will soon change his opinion. - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -% ... setup styles -\begin{tikzpicture} - \node (waiting 1) at ( 0,2) [place] {}; - \node (critical 1) at ( 0,1) [place] {}; - \node (semaphore) at ( 0,0) [place] {}; - \node (leave critical) at ( 1,1) [transition] {}; - \node (enter critical) at (-1,1) [transition] {}; -\end{tikzpicture} -\end{codeexample} -} - -Hagen is pleased to note that the names help in understanding the -code. Names for nodes can be pretty arbitrary, but they should not -contain commas, periods, parentheses, colons, and some other special -characters. However, they can contain underscores and hyphens. - -The syntax for the |node| operation is quite liberal with respect to -the order in which node names, the |at| specifier, and the options -must come. Indeed, you can even have multiple option blocks between -the |node| and the text in curly braces, they accumulate. You can -rearrange them arbitrarily and perhaps the following might be preferable: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting 1) at ( 0,2) {}; - \node[place] (critical 1) at ( 0,1) {}; - \node[place] (semaphore) at ( 0,0) {}; - \node[transition] (leave critical) at ( 1,1) {}; - \node[transition] (enter critical) at (-1,1) {}; -\end{tikzpicture} -\end{codeexample} -} - - - -\subsection{Placing Nodes Using Relative Placement} - -Although Hagen still wishes to connect the nodes, he first wishes to -address another problem again: The placement of the nodes. Although he -likes the |at| syntax, in this particular case he would prefer placing -the nodes ``relative to each other.'' So, Hagen would like to say that -the |critical 1| node should be below the |waiting 1| node, wherever -the |waiting 1| node might be. There are different ways of achieving -this, but the nicest one in Hagen's case is the |below| option: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; -\end{tikzpicture} -\end{codeexample} -} - -With the |positioning| library loaded, when an option like |below| -is followed by |of|, then the position of the node is shifted -such a manner that it is placed at the distance |node distance| in the -specified direction of the given direction. The |node distance| is -either the distance between the centers of the nodes (when the -|on grid| option is set to true) or the distance between the borders -(when the |on grid| option is set to false, which is the default). - -Even though the above code has the same effect the earlier code, Hagen -can pass it to his colleagues who will be able to just read and -understand it, perhaps without even having to see the picture. - - - -\subsection{Adding Labels Next to Nodes} - -Before we have a look at how Hagen can connect the nodes, let us add -the capacity ``$s \le 3$'' to the bottom node. For this, two -approaches are possible: -\begin{enumerate} -\item Hagen can just add a new node above the |north| anchor of the - |semaphore| node. -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - - \node [red,above] at (semaphore.north) {$s\le 3$}; -\end{tikzpicture} -\end{codeexample} -} -This is a general approach that will ``always work.'' - -\item Hagen can use the special |label| option. This option is given - to a |node| and it causes \emph{another} node to be added next to - the node where the option is given. Here is the idea: When we - construct the |semaphore| node, we wish to indicate that we want - another node with the capacity above it. For this, we use the option - |label=above:$s\le 3$|. This option is interpreted as follows: We - want a node above the |semaphore| node and this node should read - ``$s \le 3$.'' Instead of |above| we could also use things like - |below left| before the colon or a number like |60|. -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical, - label=above:$s\le3$] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; -\end{tikzpicture} -\end{codeexample} -} - It is also possible to give multiple |label| options, this causes - multiple labels to be drawn. -\begin{codeexample}[] -\tikz - \node [circle,draw,label=60:$60^\circ$,label=below:$-90^\circ$] {my circle}; -\end{codeexample} - Hagen is not fully satisfied with the |label| option since the label - is not red. To achieve this, he has two options: First, he can - redefine the |every label| style. Second, he can add options to the - label's node. These options are given following the |label=|, so he - would write |label=[red]above:$s\le3$|. However, this does not quite - work since \TeX\ thinks that the |]| closes the whole option list of - the |semaphore| node. So, Hagen has to add braces and writes - |label={[red]above:$s\le3$}|. Since this looks a bit ugly, Hagen - decides to redefine the |every label| style. -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture}[every label/.style={red}] - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical, - label=above:$s\le3$] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; -\end{tikzpicture} -\end{codeexample} -} -\end{enumerate} - - - -\subsection{Connecting Nodes} - -It is now high time to connect the nodes. Let us start with something -simple, namely with the straight line from |enter critical| to -|critical|. We want this line to start at the right side of -|enter critical| and to end at the left side of |critical|. For -this, we can use the \emph{anchors} of the nodes. Every node defines a -whole bunch of anchors that lie on its border or inside it. For -example, the |center| anchor is at the center of the node, the |west| -anchor is on the left of the node, and so on. To access the coordinate -of a node, we use a coordinate that contains the node's name followed -by a dot, followed by the anchor's name: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - \draw [->] (critical.west) -- (enter critical.east); -\end{tikzpicture} -\end{codeexample} -} - -Next, let us tackle the curve from |waiting| to |enter critical|. This -can be specified using curves and controls: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - \draw [->] (enter critical.east) -- (critical.west); - \draw [->] (waiting.west) .. controls +(left:5mm) and +(up:5mm) - .. (enter critical.north); -\end{tikzpicture} -\end{codeexample} -} - -Hagen sees how he can now add all his edges, but the whole process -seems a but awkward and not very flexible. Again, the code seems to -obscure the structure of the graphic rather than showing it. - -So, let us start improving the code for the edges. First, Hagen can -leave out the anchors: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - \draw [->] (enter critical) -- (critical); - \draw [->] (waiting) .. controls +(left:8mm) and +(up:8mm) - .. (enter critical); -\end{tikzpicture} -\end{codeexample} -} - -Hagen is a bit surprised that this works. After all, how did -\tikzname\ know that the line from |enter critical| to |critical| -should actually start on the borders? Whenever \tikzname\ encounters a -whole node name as a ``coordinate,'' it tries to ``be smart'' about -the anchor that it should choose for this node. Depending on what -happens next, \tikzname\ will choose an anchor that lies on the border -of the node on a line to the next coordinate or control point. The -exact rules are a bit complex, but the chosen point will usually be -correct -- and when it is not, Hagen can still specify the desired -anchor by hand. - -Hagen would now like to simplify the curve operation somehow. It turns -out that this can be accomplished using a special path operation: the -|to| operation. This operation takes many options (you can even define -new ones yourself). One pair of option is useful for Hagen: The pair -|in| and |out|. These options take angles at which a curve should -leave or reach the start or target coordinates. Without these options, -a straight line is drawn: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - \draw [->] (enter critical) to (critical); - \draw [->] (waiting) to [out=180,in=90] (enter critical); -\end{tikzpicture} -\end{codeexample} -} - -There is another option for the |to| operation, that is even better -suited to Hagen's problem: The |bend right| option. This option also -takes an angle, but this angle only specifies the angle by which the -curve is bend to the right: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {}; - \draw [->] (enter critical) to (critical); - \draw [->] (waiting) to [bend right=45] (enter critical); - \draw [->] (enter critical) to [bend right=45] (semaphore); -\end{tikzpicture} -\end{codeexample} -} - -It is now time for Hagen to learn about yet another way of specifying -edges: Using the |edge| path operation. This operation is very similar -to the |to| operation, but there is one important difference: Like a -node the edge generated by the |edge| operation is not part of the -main path, but is added only later. This may not seem very important, -but is has some nice consequences. For example, every edge can have -its own arrow tips and its own color and so one and, still, all the -edges can be given on the same path. This allows Hagen to write the -following: - - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -\begin{tikzpicture} - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - \node[transition] (leave critical) [right=of critical] {}; - \node[transition] (enter critical) [left=of critical] {} - edge [->] (critical) - edge [<-,bend left=45] (waiting) - edge [->,bend right=45] (semaphore); -\end{tikzpicture} -\end{codeexample} -} - -Each |edge| caused a new path to be constructed, consisting of a |to| -between the node |enter critical| and the node following the |edge| -command. - -The finishing touch is to introduce two styles |pre| and |post| and to -use the |bend angle=45| option to set the bend angle once and for all: - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}} -\begin{codeexample}[] -% Styles place and transition as before -\begin{tikzpicture} - [bend angle=45, - pre/.style={<-,shorten <=1pt,>=stealth',semithick}, - post/.style={->,shorten >=1pt,>=stealth',semithick}] - - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - - \node[transition] (leave critical) [right=of critical] {} - edge [pre] (critical) - edge [post,bend right] (waiting) - edge [pre, bend left] (semaphore); - \node[transition] (enter critical) [left=of critical] {} - edge [post] (critical) - edge [pre, bend left] (waiting) - edge [post,bend right] (semaphore); -\end{tikzpicture} -\end{codeexample} -} - - - - -\subsection{Adding Labels Next to Lines} - -The next thing that Hagen needs to add is the ``$2$'' at the arcs. For -this Hagen can use \tikzname's automatic node placement: By adding the -option |auto|, \tikzname\ will position nodes on curves and lines in -such a way that they are not on the curve but next to it. Adding -|swap| will mirror the label with respect to the line. Here is a -general example: - -{ -\begin{codeexample}[] -\begin{tikzpicture}[auto,bend right] - \node (a) at (0:1) {$0^\circ$}; - \node (b) at (120:1) {$120^\circ$}; - \node (c) at (240:1) {$240^\circ$}; - - \draw (a) to node {1} node [swap] {1'} (b) - (b) to node {2} node [swap] {2'} (c) - (c) to node {3} node [swap] {3'} (a); -\end{tikzpicture} -\end{codeexample} -} - -What is happening here? The nodes are given somehow inside the |to| -operation! When this is done, the node is placed on the middle of the -curve or line created by the |to| operation. The |auto| option then -causes the node to be moved in such a way that it does not lie on the -curve, but next to it. In the example we provide even two nodes on -each |to| operation. - -For Hagen that |auto| option is not really necessary since the two -``2'' labels could also easily be placed ``by hand.'' However, in a -complicated plot with numerous edges automatic placement can be a -blessing. - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}, -pre/.style={<-,shorten <=1pt,>=stealth',semithick}, -post/.style={->,shorten >=1pt,>=stealth',semithick}} -\begin{codeexample}[] -% Styles as before -\begin{tikzpicture}[bend angle=45] - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - - \node[transition] (leave critical) [right=of critical] {} - edge [pre] (critical) - edge [post,bend right] node[auto,swap] {2} (waiting) - edge [pre, bend left] (semaphore); - \node[transition] (enter critical) [left=of critical] {} - edge [post] (critical) - edge [pre, bend left] (waiting) - edge [post,bend right] (semaphore); -\end{tikzpicture} -\end{codeexample} -} - - - -\subsection{Adding the Snaked Line and Multi-Line Text} - -With the node mechanism Hagen can now easily create the two Petri -nets. What he is unsure of is how he can create the snaked line -between the nets. - -For this he can use a \emph{decoration}. -To draw the snake, Hagen only needs to set the two options -|decoration=snake| and |decorate| on -the path. This causes all lines of the path to be replaced by -snakes. It is also possible to use snakes only in certain parts of a -path, but Hagen will not need this. - -\begin{codeexample}[] -\begin{tikzpicture} - \draw [->,decorate,decoration=snake] (0,0) -- (2,0); -\end{tikzpicture} -\end{codeexample} - -Well, that does not look quite right, yet. The problem is that the -snake happens to end exactly at the position where the arrow -begins. Fortunately, there is an option that helps here. Also, the -snake should be a bit smaller, which can be influenced by even more -options. - -\begin{codeexample}[] -\begin{tikzpicture} - \draw [->,decorate, - decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}] - (0,0) -- (3,0); -\end{tikzpicture} -\end{codeexample} - -Now Hagen needs to add the text above the snake. This text is a bit -challenging since it is a multi-line text. Hagen has two options for -this: First, he can specify an |align=center| and then use the |\\| -command to enforce the line breaks at the desired positions. - -\begin{codeexample}[] -\begin{tikzpicture} - \draw [->,decorate, - decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}] - (0,0) -- (3,0) - node [above,align=center,midway] - { - replacement of\\ - the \textcolor{red}{capacity}\\ - by \textcolor{red}{two places} - }; -\end{tikzpicture} -\end{codeexample} - -Instead of specifying the line breaks ``by hand,'' Hagen can also -specify a width for the text and let \TeX\ perform the line breaking -for him: - -\begin{codeexample}[] -\begin{tikzpicture} - \draw [->,decorate, - decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}] - (0,0) -- (3,0) - node [above,text width=3cm,align=center,midway] - { - replacement of the \textcolor{red}{capacity} by - \textcolor{red}{two places} - }; -\end{tikzpicture} -\end{codeexample} - - - -\subsection{Using Layers: The Background Rectangles} - -Hagen still needs to add the background rectangles. These are a bit -tricky: Hagen would like to draw the rectangles \emph{after} the Petri -nets are finished. The reason is that only then can he conveniently -refer to the coordinates that make up the corners of the -rectangle. If Hagen draws the rectangle first, then he needs to know -the exact size of the Petri net -- which he does not. - -The solution is to use \emph{layers}. When the background library is -loaded, Hagen can put parts of his picture inside a |{pgfonlayer}| -environment. Then this part of the picture becomes part of the layer -that is given as an argument to this environment. When the -|{tikzpicture}| environment ends, the layers are put on top of each -other, starting with the background layer. This causes everything -drawn on the background layer to be behind the main text. - -The next tricky question is, how big should the rectangle be? -Naturally, Hagen can compute the size ``by hand'' or using some clever -observations concerning the $x$- and $y$-coordinates of the nodes, but -it would be nicer to just have \tikzname\ compute a rectangle into -which all the nodes ``fit.'' For this, the |fit| library can be -used. It defines the |fit| options, which, when give to a node, causes -the node to be resized and shifted such that it exactly covers all the -nodes and coordinates given as parameters to the |fit| option. - -{ -\tikzset{place/.style={circle,draw=blue!50,fill=blue!20,thick, - inner sep=0pt,minimum size=6mm}, -transition/.style={rectangle,draw=black!50,fill=black!20,thick, - inner sep=0pt,minimum size=4mm}, -pre/.style={<-,shorten <=1pt,>=stealth',semithick}, -post/.style={->,shorten >=1pt,>=stealth',semithick}} -\begin{codeexample}[] -% Styles as before -\begin{tikzpicture}[bend angle=45] - \node[place] (waiting) {}; - \node[place] (critical) [below=of waiting] {}; - \node[place] (semaphore) [below=of critical] {}; - - \node[transition] (leave critical) [right=of critical] {} - edge [pre] (critical) - edge [post,bend right] node[auto,swap] {2} (waiting) - edge [pre, bend left] (semaphore); - \node[transition] (enter critical) [left=of critical] {} - edge [post] (critical) - edge [pre, bend left] (waiting) - edge [post,bend right] (semaphore); - - \begin{pgfonlayer}{background} - \node [fill=black!30,fit=(waiting) (critical) (semaphore) - (leave critical) (enter critical)] {}; - \end{pgfonlayer} -\end{tikzpicture} -\end{codeexample} -} - - - - -\subsection{The Complete Code} - -Hagen has now finally put everything together. Only then does he learn -that there is already a library for drawing Petri nets! It turns out -that this library mainly provides the same definitions as Hagen -did. For example, it defines a |place| style in a similar way as Hagen -did. Adjusting the code so that it uses the library shortens Hagen -code a bit, as shown in the following. - -First, Hagen needs less style definitions, but he still needs to -specify the colors of places and transitions. - -\begin{codeexample}[code only] -\begin{tikzpicture} - [node distance=1.3cm,on grid,>=stealth',bend angle=45,auto, - every place/.style= {minimum size=6mm,thick,draw=blue!75,fill=blue!20}, - every transition/.style={thick,draw=black!75,fill=black!20}, - red place/.style= {place,draw=red!75,fill=red!20}, - every label/.style= {red}] -\end{codeexample} - -Now comes the code for the nets: - -{ -\tikzset{% - every place/.style={minimum size=6mm,thick,draw=blue!75,fill=blue!20}, - every transition/.style={thick,draw=black!75,fill=black!20}, - red place/.style={place,draw=red!75,fill=red!20}, - every label/.style={red}, - every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto}} -\tikzexternaldisable -\begin{codeexample}[pre=\begin{tikzpicture},post=\end{tikzpicture}] - \node [place,tokens=1] (w1) {}; - \node [place] (c1) [below=of w1] {}; - \node [place] (s) [below=of c1,label=above:$s\le 3$] {}; - \node [place] (c2) [below=of s] {}; - \node [place,tokens=1] (w2) [below=of c2] {}; - - \node [transition] (e1) [left=of c1] {} - edge [pre,bend left] (w1) - edge [post,bend right] (s) - edge [post] (c1); - \node [transition] (e2) [left=of c2] {} - edge [pre,bend right] (w2) - edge [post,bend left] (s) - edge [post] (c2); - \node [transition] (l1) [right=of c1] {} - edge [pre] (c1) - edge [pre,bend left] (s) - edge [post,bend right] node[swap] {2} (w1); - \node [transition] (l2) [right=of c2] {} - edge [pre] (c2) - edge [pre,bend right] (s) - edge [post,bend left] node {2} (w2); -\end{codeexample} -} - -{ -\tikzset{ -every place/.style= {minimum size=6mm,thick,draw=blue!75,fill=blue!20}, -every transition/.style={thick,draw=black!75,fill=black!20}, -red place/.style= {place,draw=red!75,fill=red!20}, -every label/.style={red}, -every picture/.style={on grid,node distance=1.3cm,>=stealth',bend angle=45,auto}} -\tikzexternaldisable -\begin{codeexample}[pre=\begin{tikzpicture},post=\end{tikzpicture}] - \begin{scope}[xshift=6cm] - \node [place,tokens=1] (w1') {}; - \node [place] (c1') [below=of w1'] {}; - \node [red place] (s1') [below=of c1',xshift=-5mm] - [label=left:$s$] {}; - \node [red place,tokens=3] (s2') [below=of c1',xshift=5mm] - [label=right:$\bar s$] {}; - \node [place] (c2') [below=of s1',xshift=5mm] {}; - \node [place,tokens=1] (w2') [below=of c2'] {}; - - \node [transition] (e1') [left=of c1'] {} - edge [pre,bend left] (w1') - edge [post] (s1') - edge [pre] (s2') - edge [post] (c1'); - \node [transition] (e2') [left=of c2'] {} - edge [pre,bend right] (w2') - edge [post] (s1') - edge [pre] (s2') - edge [post] (c2'); - \node [transition] (l1') [right=of c1'] {} - edge [pre] (c1') - edge [pre] (s1') - edge [post] (s2') - edge [post,bend right] node[swap] {2} (w1'); - \node [transition] (l2') [right=of c2'] {} - edge [pre] (c2') - edge [pre] (s1') - edge [post] (s2') - edge [post,bend left] node {2} (w2'); - \end{scope} -\end{codeexample} -} - -The code for the background and the snake is the following: - -\begin{codeexample}[code only] - \begin{pgfonlayer}{background} - \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {}; - \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {}; - \end{pgfonlayer} - - \draw [shorten >=1mm,-to,thick,decorate, - decoration={snake,amplitude=.4mm,segment length=2mm, - pre=moveto,pre length=1mm,post length=2mm}] - (r1) -- (r2) node [above=1mm,midway,text width=3cm,align=center] - {replacement of the \textcolor{red}{capacity} by \textcolor{red}{two places}}; -\end{tikzpicture} -\end{codeexample} diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex index b2dcfbe5a05..99585ce2b48 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tutorial.tex @@ -9,9 +9,9 @@ \section{Tutorial: A Picture for Karl's Students} -This tutorial is intended for new users of \pgfname\ and \tikzname. It -does not give an exhaustive account of all the features of \tikzname\ or -\pgfname, just of those that you are likely to use right away. +This tutorial is intended for new users of \tikzname. It +does not give an exhaustive account of all the features of \tikzname, +just of those that you are likely to use right away. Karl is a math and chemistry high-school teacher. He used to create the graphics in his worksheets and exams using \LaTeX's |{picture}| @@ -66,7 +66,7 @@ cosine. What he would like to have is something that looks like this % The graphic \draw[help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \begin{scope}[axes] \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$}; @@ -236,9 +236,7 @@ His version of the example looks like this: \end{codeexample} Hans will now typeset this file in the usual way using -|texexec|\footnote{Note that \pgfname/\tikzname{} is not supported by - recent Con\TeX t versions (like mark IV, the Lua\TeX-aware part of - Con\TeX t).}. +|texexec| or |context|. @@ -288,10 +286,10 @@ $z$ and the tangent of the curve at point $z$ will go through $w$. Here is an example (the control points have been added for clarity): \begin{codeexample}[] \begin{tikzpicture} - \filldraw [gray] (0,0) circle (2pt) - (1,1) circle (2pt) - (2,1) circle (2pt) - (2,0) circle (2pt); + \filldraw [gray] (0,0) circle [radius=2pt] + (1,1) circle [radius=2pt] + (2,1) circle [radius=2pt] + (2,0) circle [radius=2pt]; \draw (0,0) .. controls (1,1) and (2,1) .. (2,0); \end{tikzpicture} \end{codeexample} @@ -320,38 +318,36 @@ way to be extremely awkward. Fortunately, there is a much simpler way. \subsection{Circle Path Construction} In order to draw a circle, the path construction operation |circle| can -be used. This operation is followed by a radius in round brackets as in +be used. This operation is followed by a radius in brackets as in the following example: (Note that the previous position is used as the \emph{center} of the circle.) \begin{codeexample}[] -\tikz \draw (0,0) circle (10pt); +\tikz \draw (0,0) circle [radius=10pt]; \end{codeexample} You can also append an ellipse to the path using the |ellipse| -operation. Instead of a single radius you can specify two of them, one -for the $x$-direction and one for the $y$-direction, separated by -|and|: +operation. Instead of a single radius you can specify two of them: \begin{codeexample}[] -\tikz \draw (0,0) ellipse (20pt and 10pt); +\tikz \draw (0,0) ellipse [x radius=20pt, y radius=10pt]; \end{codeexample} To draw an ellipse whose axes are not horizontal and vertical, but point in an arbitrary direction (a ``turned ellipse'' like \tikz -\draw[rotate=30] (0,0) ellipse (6pt and 3pt);) you can use +\draw[rotate=30] (0,0) ellipse [x radius=6pt, y radius=3pt];) you can use transformations, which are explained later. The code for the little -ellipse is |\tikz \draw[rotate=30] (0,0) ellipse (6pt and 3pt);|, by +ellipse is |\tikz \draw[rotate=30] (0,0) ellipse [x radius=6pt, y radius=3pt];|, by the way. So, returning to Karl's problem, he can write -|\draw (0,0) circle (1cm);| to draw the circle: +|\draw (0,0) circle [radius=1cm];| to draw the circle: \begin{codeexample}[] \begin{tikzpicture} \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \end{tikzpicture} \end{codeexample} @@ -380,7 +376,7 @@ rectangle. So, let us add two rectangles to the picture: \begin{tikzpicture} \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \draw (0,0) rectangle (0.5,0.5); \draw (-0.5,-0.5) rectangle (-1,-1); \end{tikzpicture} @@ -415,7 +411,7 @@ For Karl, the following code could be used: \begin{tikzpicture} \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \draw[step=.5cm] (-1.4,-1.4) grid (1.4,1.4); \end{tikzpicture} \end{codeexample} @@ -434,7 +430,7 @@ top. \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \end{tikzpicture} \end{codeexample} @@ -508,18 +504,16 @@ very thick lines, |ultra thick| yields really, really thick lines and |ultra thin| yields lines that are so thin that low-resolution printers and displays will have trouble showing them. He wonders what gives lines of ``normal'' thickness. It turns out that |thin| is the correct -choice. This seems strange to Karl, but his son explains him that -\LaTeX\ has two commands called |\thinlines| and |\thicklines| and -that |\thinlines| gives the line width of ``normal'' lines, more -precisely, of the thickness that, say, the stem of a letter like ``T'' -or ``i'' has. Nevertheless, Karl would like to know whether there is +choice, since it gives the same thickness as \TeX's |\hrule| +command. Nevertheless, Karl would like to know whether there is anything ``in the middle'' between |thin| and |thick|. There is: |semithick|. Another useful thing one can do with lines is to dash or dot them. For this, the two styles |dashed| and |dotted| can be used, yielding -\tikz \draw[dashed] (0,0) -- (10pt,0pt); and \tikz \draw[dotted] (0,0) --- (10pt,0pt);. Both options also exist in a loose and a dense +\tikz[baseline] \draw[dashed] (0,.5ex) -- ++(2em,0pt); and +\tikz[baseline] \draw[dotted] (0,.5ex) +-- ++(2em,0pt);. Both options also exist in a loose and a dense version, called |loosely dashed|, |densely dashed|, |loosely dotted|, and |densely dotted|. If he really, really needs to, Karl can also define much more complex dashing patterns with the |dash pattern| @@ -533,26 +527,23 @@ patterns are evil. Karl's students do not care about dashing patterns. Our next obstacle is to draw the arc for the angle. For this, the |arc| path construction operation is useful, which draws part of a -circle or ellipse. This |arc| operation must be followed by a triple in -rounded brackets, where the components of the triple are separated by -colons. The first two components are angles, the last one is a -radius. An example would be |(10:80:10pt)|, which means ``an arc from -10 degrees to 80 degrees on a circle of radius 10pt.'' Karl obviously +circle or ellipse. This |arc| operation is followed by options in +brackets that specify the arc. An example would be \texttt{arc[start + angle=10, end angle=80, radius=10pt]}, which means exactly what it +says. Karl obviously needs an arc from $0^\circ$ to $30^\circ$. The radius should be something relatively small, perhaps around one third of the circle's -radius. This gives: |(0:30:3mm)|. - -When one uses the arc path construction operation, the specified arc will -be added with its starting point at the current position. So, we first -have to ``get there.'' +radius. When one uses the arc path construction operation, the +specified arc will be added with its starting point at the current +position. So, we first have to ``get there.'' \begin{codeexample}[] \begin{tikzpicture} \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \draw (3mm,0mm) arc (0:30:3mm); + \draw (0,0) circle [radius=1cm]; + \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm]; \end{tikzpicture} \end{codeexample} @@ -567,8 +558,8 @@ causes this option to apply to everything within. \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \draw (3mm,0mm) arc (0:30:3mm); + \draw (0,0) circle [radius=1cm]; + \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm]; \end{tikzpicture} \end{codeexample} @@ -576,7 +567,9 @@ As for circles, you can specify ``two'' radii in order to get an elliptical arc. \begin{codeexample}[] - \tikz \draw (0,0) arc (0:315:1.75cm and 1cm); + \tikz \draw (0,0) + arc [start angle=0, end angle=315, + x radius=1.75cm, y radius=1cm]; \end{codeexample} @@ -585,7 +578,7 @@ elliptical arc. In order to save space in this manual, it would be nice to clip Karl's graphics a bit so that we can focus on the ``interesting'' parts. Clipping is pretty easy in \tikzname. You can use the |\clip| -command clip all subsequent drawing. It works like |\draw|, only it +command to clip all subsequent drawing. It works like |\draw|, only it does not draw anything, but uses the given path to clip everything subsequently. @@ -595,8 +588,8 @@ subsequently. \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \draw (3mm,0mm) arc (0:30:3mm); + \draw (0,0) circle [radius=1cm]; + \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm]; \end{tikzpicture} \end{codeexample} @@ -614,8 +607,8 @@ and |\clip| is a shorthand for |\path[clip]| and you could also say \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \draw (3mm,0mm) arc (0:30:3mm); + \draw (0,0) circle [radius=1cm]; + \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm]; \end{tikzpicture} \end{codeexample} @@ -666,13 +659,14 @@ with a very light green. For this he uses |\fill| instead of \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- (0,0); + \draw (0,0) circle [radius=1cm]; + \fill[green!20!white] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- (0,0); \end{tikzpicture} \end{codeexample} The color |green!20!white| means 20\% green and 80\% white mixed -together. Such color expression are possible since \pgfname\ uses Uwe +together. Such color expression are possible since \tikzname\ uses Uwe Kern's |xcolor| package, see the documentation of that package for details on color expressions. @@ -681,7 +675,8 @@ What would have happened, if Karl had not ``closed'' the path using so this could have been omitted. Indeed, it would even have been better to write the following, instead: \begin{codeexample}[code only] - \fill[green!20!white] (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \fill[green!20!white] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \end{codeexample} The |--cycle| causes the current path to be closed (actually the current part of the current path) by smoothly joining the first and @@ -708,9 +703,9 @@ arguments like this: \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \filldraw[fill=green!20!white, draw=green!50!black] - (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \draw (0,0) circle [radius=1cm]; + \filldraw[fill=green!20!white, draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \end{tikzpicture} \end{codeexample} @@ -719,7 +714,7 @@ arguments like this: \subsection{Shading} Karl briefly considers the possibility of making the angle ``more -fancy'' by \emph{shading} it. Instead of filling the with a uniform +fancy'' by \emph{shading} it. Instead of filling the area with a uniform color, a smooth transition between different colors is used. For this, |\shade| and |\shadedraw|, for shading and drawing at the same time, can be used: @@ -747,9 +742,10 @@ For Karl, the following might be appropriate: \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \shadedraw[left color=gray,right color=green, draw=green!50!black] - (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \end{tikzpicture} \end{codeexample} @@ -760,7 +756,7 @@ adding anything to the picture. \subsection{Specifying Coordinates} Karl now wants to add the sine and cosine lines. He knows already that -he can use the |color=| option to set the lines's colors. So, what is +he can use the |color=| option to set the lines' colors. So, what is the best way to specify the coordinates? There are different ways of specifying coordinates. The easiest way is @@ -788,9 +784,9 @@ For example, we can draw the sine line as follows: \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \filldraw[fill=green!20,draw=green!50!black] - (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \draw (0,0) circle [radius=1cm]; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[red,very thick] (30:1cm) -- +(0,-0.5); \end{tikzpicture} \end{codeexample} @@ -813,15 +809,15 @@ Next, let us draw the cosine line. One way would be to say \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw (-1.5,0) -- (1.5,0); \draw (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc - (0:30:3mm) -- cycle; + \draw (0,0) circle [radius=1cm]; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[red,very thick] (30:1cm) -- +(0,-0.5); \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0); \end{tikzpicture} \end{codeexample} -Note the there is no |--| between |(30:1cm)| and |++(0,-0.5)|. In +Note that there is no |--| between |(30:1cm)| and |++(0,-0.5)|. In detail, this path is interpreted as follows: ``First, the |(30:1cm)| tells me to move by pen to $(\cos 30^\circ,1/2)$. Next, there comes another coordinate specification, so I move my pen there without drawing @@ -861,9 +857,18 @@ economically like this (either with a single of a double |+|): \subsection{Intersecting Paths} Karl is left with the line for $\tan \alpha$, which seems difficult to -specify using transformations and polar coordinates. For this he needs -another way of specifying coordinates: Karl can specify intersections -of paths as coordinates. The line for $\tan \alpha$ starts at $(1,0)$ +specify using transformations and polar coordinates. The first -- and +easiest -- thing he can do is so simply use the coordinate +|(1,{tan(30)})| since \tikzname's math engine knows how to compute +things like |tan(30)|. Note the added braces since, otherwise, +\tikzname's parser would think that the first closing parenthesis ends +the coordinate (in general, you need to add braces around components +of coordinates when these components contain parentheses). + +Karl can, however, also use a more elaborate, but also more +``geometric'' way of computing the length of the orange line: He can +specify intersections of paths as coordinates. The line for $\tan +\alpha$ starts at $(1,0)$ and goes upward to a point that is at the intersection of a line going ``up'' and a line going from the origin through |(30:1cm)|. Such computations are made available by the |intersections| library. @@ -889,7 +894,7 @@ later reference. Karl now wants to add the little arrow tips at the end of the axes. He has noticed that in many plots, even in scientific journals, these arrow tips -seem to missing, presumably because the generating programs cannot +seem to be missing, presumably because the generating programs cannot produce them. Karl thinks arrow tips belong at the end of axes. His son agrees. His students do not care about arrow tips. @@ -902,9 +907,9 @@ It turns out that adding arrow tips is pretty easy: Karl adds the option \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); - \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc - (0:30:3mm) -- cycle; + \draw (0,0) circle [radius=1cm]; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[red,very thick] (30:1cm) -- +(0,-0.5); \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0); @@ -921,38 +926,35 @@ arrow tips at both ends of the path. There are certain restrictions to the kind of paths to which arrow tips can be added. As a rule of thumb, you can add arrow tips only to a -single open ``line.'' For example, you should not try to add tips to, -say, a rectangle or a circle. (You can try, but no guarantees as to what -will happen now or in future versions.) However, you can add arrow +single open ``line.'' For example, you cannot add tips to, +say, a rectangle or a circle. However, you can add arrow tips to curved paths and to paths that have several segments, as in the following examples: \begin{codeexample}[] \begin{tikzpicture} - \draw [<->] (0,0) arc (180:30:10pt); + \draw [<->] (0,0) arc [start angle=180, end angle=30, radius=10pt]; \draw [<->] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt); \end{tikzpicture} \end{codeexample} Karl has a more detailed look at the arrow that \tikzname\ puts at the -end. It looks like this when he zooms it: \tikz { \useasboundingbox - (0pt,-.5ex) rectangle (10pt,.5ex); \draw[->,line width=1pt] (0pt,0pt) -- - (10pt,0pt); }. The shape seems vaguely familiar and, indeed, this is -exactly the end of \TeX's standard arrow used in something like -$f\colon A \to B$. - +end. It looks like this when he zooms it: \tikz[baseline] +\draw[->,line width=1pt] (0pt,.5ex) -- ++(10pt,0pt);. The shape seems +vaguely familiar and, indeed, this is exactly the end of \TeX's +standard arrow used in something like $f\colon A \to B$. Karl likes the arrow, especially since it is not ``as thick'' as the arrows offered by many other packages. However, he expects that, sometimes, he might need to use some other kinds of arrow. -To do so, Karl can say |>=|\meta{right arrow tip kind}, where -\meta{right arrow tip kind} is a special arrow tip specification. For -example, if Karl says |>=stealth|, then he tells \tikzname\ +To do so, Karl can say |>=|\meta{kind of end arrow tip}, where +\meta{kind of end arrow tip} is a special arrow tip specification. For +example, if Karl says |>=Stealth|, then he tells \tikzname\ that he would like ``stealth-fighter-like'' arrow tips: \begin{codeexample}[] -\begin{tikzpicture}[>=stealth] - \draw [->] (0,0) arc (180:30:10pt); +\begin{tikzpicture}[>=Stealth] + \draw [->] (0,0) arc [start angle=180, end angle=30, radius=10pt]; \draw [<<-,very thick] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt); \end{tikzpicture} \end{codeexample}%>> @@ -962,12 +964,9 @@ necessary. He is not really mollified when his son tells him that Microsoft's PowerPoint uses the same name. He decides to have his students discuss this at some point. -In addition to |stealth| there are several other predefined arrow tip -kinds Karl can choose from, see -Section~\ref{section-library-arrows}. Furthermore, he can define -arrows types himself, if he needs new ones. - - +In addition to |Stealth| there are several other predefined kinds of +arrow tips Karl can choose from, see Section~\ref{section-arrows}. Furthermore, +he can define arrows types himself, if he needs new ones. \subsection{Scoping} @@ -1016,7 +1015,7 @@ can be given anywhere on the path. So, instead of |\draw (0,0) [thin] -- (1,0);| or |\draw (0,0) -- (1,0) [thin];|; all of these have the same effect. This might seem strange since in the last case, it would appear that the |thin| should take effect only -``after'' the line from $(0,0)$ to $(1,0)$ has been draw. However, +``after'' the line from $(0,0)$ to $(1,0)$ has been drawn. However, most graphic options only apply to the whole path. Indeed, if you say both |thin| and |thick| on the same path, the last option given will ``win.'' @@ -1035,11 +1034,11 @@ apply only to this path. When you specify a coordinate like |(1cm,1cm)|, where is that coordinate placed on the page? To determine the position, \tikzname, \TeX, and \textsc{pdf} or PostScript all apply certain transformations -to the given coordinate in order to determine the finally position on +to the given coordinate in order to determine the final position on the page. \tikzname\ provides numerous options that allow you to transform -coordinates in \pgfname's private coordinate system. For example, the +coordinates in \tikzname's private coordinate system. For example, the |xshift| option allows you to shift all subsequent points by a certain amount: @@ -1049,15 +1048,15 @@ amount: It is important to note that you can change transformation ``in the middle of a path,'' a feature that is not supported by \pdf\ -or PostScript. The reason is that \pgfname\ keeps track of its own +or PostScript. The reason is that \tikzname\ keeps track of its own transformation matrix. Here is a more complicated example: \begin{codeexample}[] \begin{tikzpicture}[even odd rule,rounded corners=2pt,x=10pt,y=10pt] - \filldraw[fill=examplefill] (0,0) rectangle (1,1) - [xshift=5pt,yshift=5pt] (0,0) rectangle (1,1) - [rotate=30] (-1,-1) rectangle (2,2); + \filldraw[fill=yellow!80!black] (0,0) rectangle (1,1) + [xshift=5pt,yshift=5pt] (0,0) rectangle (1,1) + [rotate=30] (-1,-1) rectangle (2,2); \end{tikzpicture} \end{codeexample} @@ -1084,11 +1083,11 @@ $-1/2$, $1/2$, and $1$. For this, it would be nice to use some kind of these positions. There are different packages for doing this. \LaTeX\ has its own internal command for this, |pstricks| comes along with the powerful |\multido| command. All of these can be used together with -\pgfname\ and \tikzname, so if you are familiar with them, feel free to -use them. \pgfname\ introduces yet another command, called |\foreach|, +\tikzname, so if you are familiar with them, feel free to +use them. \tikzname\ introduces yet another command, called |\foreach|, which I introduced since I could never remember the syntax of the other packages. |\foreach| is defined in the package |pgffor| and can be used -independently of \pgfname. \tikzname\ includes it automatically. +independently \tikzname, but \tikzname\ includes it automatically. In its basic form, the |\foreach| command is easy to use: \begin{codeexample}[] @@ -1107,11 +1106,11 @@ For Karl and the ticks on the axes, he could use the following code: \begin{tikzpicture}[scale=3] \clip (-0.1,-0.2) rectangle (1.1,1.51); \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); - \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc - (0:30:3mm) -- cycle; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \foreach \x in {-1cm,-0.5cm,1cm} \draw (\x,-1pt) -- (\x,1pt); @@ -1189,7 +1188,7 @@ path has been completely drawn/filled/shaded/clipped/whatever. \begin{codeexample}[] \begin{tikzpicture} \draw (0,0) rectangle (2,2); - \draw (0.5,0.5) node [fill=examplefill] + \draw (0.5,0.5) node [fill=yellow!80!black] {Text at \verb!node 1!} -- (1.5,1.5) node {Text at \verb!node 2!}; \end{tikzpicture} @@ -1201,7 +1200,7 @@ right of these positions. For this, every node object that you put in your picture is equipped with several \emph{anchors}. For example, the |north| anchor is in the middle at the upper end of the shape, the |south| anchor is at the bottom and the |north east| anchor is in -the upper right corner. When you given the option |anchor=north|, the +the upper right corner. When you give the option |anchor=north|, the text will be placed such that this northern anchor will lie on the current position and the text is, thus, below the current position. Karl uses this to draw the ticks as follows: @@ -1210,10 +1209,10 @@ position. Karl uses this to draw the ticks as follows: \begin{tikzpicture}[scale=3] \clip (-0.6,-0.2) rectangle (0.6,1.51); \draw[step=.5cm,help lines] (-1.4,-1.4) grid (1.4,1.4); - \filldraw[fill=green!20,draw=green!50!black] - (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \foreach \x in {-1,-0.5,1} \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\x$}; @@ -1258,10 +1257,10 @@ will be used again. So, here is the new code for the ticks: \begin{tikzpicture}[scale=3] \clip (-0.6,-0.2) rectangle (0.6,1.51); \draw[step=.5cm,help lines] (-1.4,-1.4) grid (1.4,1.4); - \filldraw[fill=green!20,draw=green!50!black] - (0,0) -- (3mm,0mm) arc (0:30:3mm) -- cycle; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1} \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\xtext$}; @@ -1280,7 +1279,7 @@ with a white color. The next thing Karl wants to do is to add the labels like $\sin \alpha$. For this, he would like to place a label ``in the middle of -line.'' To do so, instead of specifying the label +the line.'' To do so, instead of specifying the label |node {$\sin\alpha$}| directly after one of the endpoints of the line (which would place the label at that endpoint), Karl can give the label directly after @@ -1294,11 +1293,11 @@ modify this position: \begin{tikzpicture}[scale=3] \clip (-2,-0.2) rectangle (2,0.8); \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4); - \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) arc - (0:30:3mm) -- cycle; + \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm) + arc [start angle=0, end angle=30, radius=3mm] -- cycle; \draw[->] (-1.5,0) -- (1.5,0) coordinate (x axis); \draw[->] (0,-1.5) -- (0,1.5) coordinate (y axis); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \draw[very thick,red] (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis); @@ -1347,9 +1346,6 @@ desired effect. So, here is the full code: important line/.style={very thick}, information text/.style={rounded corners,fill=red!10,inner sep=1ex}] - % Local definitions - \def\costhirty{0.8660256} - % Colors \colorlet{anglecolor}{green!50!black} \colorlet{sincolor}{red} @@ -1359,7 +1355,7 @@ desired effect. So, here is the full code: % The graphic \draw[help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4); - \draw (0,0) circle (1cm); + \draw (0,0) circle [radius=1cm]; \begin{scope}[axes] \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$} coordinate(x axis); @@ -1372,7 +1368,8 @@ desired effect. So, here is the full code: \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$}; \end{scope} - \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm); + \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) + arc [start angle=0, end angle=30, radius=3mm]; \draw (15:2mm) node[anglecolor] {$\alpha$}; \draw[important line,sincolor] @@ -1403,3 +1400,58 @@ desired effect. So, here is the full code: }; \end{tikzpicture} \end{codeexample} + + + +\subsection{Pics: The Angle Revisited} + +Karl expects that the code of certain parts of the picture he created +might be so useful that he might wish to reuse them in the +future. A natural thing to do is to create \TeX\ macros that store +the code he wishes to reuse. However, \tikzname\ offers another way +that is integrated directly into its parser: pics! + +A ``pic'' is ``not quite a full picture,'' hence the short name. The +idea is that a pic is simply some code that you can add to a picture +at different places using the |pic| command whose syntax is almost +identical to the |node| command. The main difference is that instead +of specifying some text in curly braces that should be shown, you +specify the name of a predefined picture that should be shown. + +Defining new pics is easy enough, see Section~\ref{section-pics}, but +right now we just want to use one such predefined pic: the |angle| +pic. As the name suggests, it is a small drawing of an angle +consisting of a little wedge and an arc together with some text (Karl +needs to load the |angle| library and the |quotes| for the following +examples). What makes this pic useful is the fact that the size of the +wedge will be computed automatically. + +The |angle| pic draws an angle between the two lines $BA$ and $BC$, +where $A$, $B$, and $C$ are three coordinates. In our case, $B$ is the +origin, $A$ is somewhere on the $x$-axis and $C$ is somewhere on a +line at $30^\circ$. + +\begin{codeexample}[] +\begin{tikzpicture}[scale=3] + \coordinate (A) at (1,0); + \coordinate (B) at (0,0); + \coordinate (C) at (30:1cm); + + \draw (A) -- (B) -- (C) + pic [draw=green!50!black, fill=green!20, angle radius=9mm, + "$\alpha$"] {angle = A--B--C}; +\end{tikzpicture} +\end{codeexample} + +Let us see, what is happening here. First we have specified three +\emph{coordinates} using the |\coordinate| command. It allows us to +name a specific coordinate in the picture. Then comes something that +starts as a normal |\draw|, but then comes the |pic| command. This +command gets lots of options and, in curly braces, comes the most +important point: We specify that we want to add an |angle| pic and +this angle should be between the points we named |A|, |B|, and |C| (we +could use other names). Note that the text that we want to be shown in +the pic is specified in quotes inside the options of the |pic|, not +inside the curly braces. + +To learn more about pics, please see Section~\ref{section-pics}.
\ No newline at end of file diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.gnuplot b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.gnuplot new file mode 100644 index 00000000000..0b0a1ad8ff3 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.gnuplot @@ -0,0 +1,2 @@ +set table "plots/pgf-tan-example.table"; set format "%.5f" +set samples 100.0; plot [x=-3.141:3.141] [-3:3]tan(x) diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.table b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.table new file mode 100644 index 00000000000..63beeda4b7a --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/plots/pgf-tan-example.table @@ -0,0 +1,104 @@ + +#Curve 0 of 1, 100 points +#x y type +-3.14100 0.00059 i +-3.07755 0.06413 i +-3.01409 0.12820 i +-2.95064 0.19331 i +-2.88718 0.26005 i +-2.82373 0.32902 i +-2.76027 0.40094 i +-2.69682 0.47663 i +-2.63336 0.55704 i +-2.56991 0.64335 i +-2.50645 0.73701 i +-2.44300 0.83989 i +-2.37955 0.95436 i +-2.31609 1.08360 i +-2.25264 1.23197 i +-2.18918 1.40553 i +-2.12573 1.61314 i +-2.06227 1.86816 i +-1.99882 2.19188 i +-1.93536 2.62036 i +-1.87191 3.22003 o +-1.80845 4.12820 o +-1.74500 5.68222 o +-1.68155 8.99247 o +-1.61809 21.12830 o +-1.55464 -61.87594 o +-1.49118 -12.53398 o +-1.42773 -6.94188 o +-1.36427 -4.77302 o +-1.30082 -3.61357 o +-1.23736 -2.88713 i +-1.17391 -2.38590 i +-1.11045 -2.01664 i +-1.04700 -1.73126 i +-0.98355 -1.50245 i +-0.92009 -1.31351 i +-0.85664 -1.15368 i +-0.79318 -1.01569 i +-0.72973 -0.89443 i +-0.66627 -0.78621 i +-0.60282 -0.68828 i +-0.53936 -0.59856 i +-0.47591 -0.51542 i +-0.41245 -0.43755 i +-0.34900 -0.36390 i +-0.28555 -0.29357 i +-0.22209 -0.22582 i +-0.15864 -0.15998 i +-0.09518 -0.09547 i +-0.03173 -0.03174 i +0.03173 0.03174 i +0.09518 0.09547 i +0.15864 0.15998 i +0.22209 0.22582 i +0.28555 0.29357 i +0.34900 0.36390 i +0.41245 0.43755 i +0.47591 0.51542 i +0.53936 0.59856 i +0.60282 0.68828 i +0.66627 0.78621 i +0.72973 0.89443 i +0.79318 1.01569 i +0.85664 1.15368 i +0.92009 1.31351 i +0.98355 1.50245 i +1.04700 1.73126 i +1.11045 2.01664 i +1.17391 2.38590 i +1.23736 2.88713 i +1.30082 3.61357 o +1.36427 4.77302 o +1.42773 6.94188 o +1.49118 12.53398 o +1.55464 61.87594 o +1.61809 -21.12830 o +1.68155 -8.99247 o +1.74500 -5.68222 o +1.80845 -4.12820 o +1.87191 -3.22003 o +1.93536 -2.62036 i +1.99882 -2.19188 i +2.06227 -1.86816 i +2.12573 -1.61314 i +2.18918 -1.40553 i +2.25264 -1.23197 i +2.31609 -1.08360 i +2.37955 -0.95436 i +2.44300 -0.83989 i +2.50645 -0.73701 i +2.56991 -0.64335 i +2.63336 -0.55704 i +2.69682 -0.47663 i +2.76027 -0.40094 i +2.82373 -0.32902 i +2.88718 -0.26005 i +2.95064 -0.19331 i +3.01409 -0.12820 i +3.07755 -0.06413 i +3.14100 -0.00059 i + diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/texmf.cnf b/Master/texmf-dist/doc/generic/pgf/text-en/texmf.cnf deleted file mode 100644 index 4235f281312..00000000000 --- a/Master/texmf-dist/doc/generic/pgf/text-en/texmf.cnf +++ /dev/null @@ -1,83 +0,0 @@ -% Part 3: Array and other sizes for TeX (and Metafont and MetaPost). -% -% If you want to change some of these sizes only for a certain TeX -% variant, the usual dot notation works, e.g., -% main_memory.hugetex = 20000000 -% -% If a change here appears to be ignored, try redumping the format file -% with fmtutil-sys. - -% Memory. Must be less than 8,000,000 total. -% -% main_memory is relevant only to initex, extra_mem_* only to non-ini. -% Thus, have to redump the .fmt file after changing main_memory; to add -% to existing fmt files, increase extra_mem_*. (To get an idea of how -% much, try \tracingstats=2 in your TeX source file; -% web2c/tests/memtest.tex might also be interesting.) -% -% To increase space for boxes (as might be needed by, e.g., PiCTeX), -% increase extra_mem_bot. -% -% For some xy-pic samples, you may need as much as 700000 words of memory. -% For the vast majority of documents, 60000 or less will do. -% -main_memory = 9000000 % words of inimemory available; also applies to inimf&mp -extra_mem_top = 6000000 % extra high memory for chars, tokens, etc. -extra_mem_bot = 6000000 % extra low memory for boxes, glue, breakpoints, etc. - -% Words of font info for TeX (total size of all TFM files, approximately). -% Must be >= 20000 and <= 4000000 (without tex.ch changes). -%font_mem_size = 1200000 - -% Total number of fonts. Must be >= 50 and <= 2000 (without tex.ch changes). -%font_max = 2000 - -% Extra space for the hash table of control sequences (which allows 10K -% names as distributed). -hash_extra = 200000 - -% Max number of characters in all strings, including all error messages, -% help texts, font names, control sequences. These values apply to TeX and MP. -pool_size = 3850000 -% Minimum pool space after TeX/MP's own strings; must be at least -% 25000 less than pool_size, but doesn't need to be nearly that large. -%string_vacancies = 90000 -% Maximum number of strings. -%max_strings = 100000 -% min pool space left after loading .fmt -%pool_free = 47500 - -% Buffer size. TeX uses the buffer to contain input lines, but macro -% expansion works by writing material into the buffer and reparsing the -% line. As a consequence, certain constructs require the buffer to be -% very large, even though most documents can be handled with a small value. -%buf_size = 200000 - -% Hyphenation trie. The maximum possible is 4194303 (ssup_trie_size in -% the sources), but we don't need that much. The value here suffices -% for all known free hyphenation patterns to be loaded simultaneously -% (as TeX Live does). -% -%trie_size = 400000 - -%hyph_size = 8191 % prime number of hyphenation exceptions, >610, <32767. - % http://primes.utm.edu/curios/page.php/8191.html -%nest_size = 500 % simultaneous semantic levels (e.g., groups) -%max_in_open = 15 % simultaneous input files and error insertions -%param_size = 10000 % simultaneous macro parameters -%save_size = 5000 % for saving values outside current group -save_size=800000 -stack_size = 500000 % simultaneous input sources - - - - -% It's probably inadvisable to change these. At any rate, we must have: -% 45 < error_line < 255; -% 30 < half_error_line < error_line - 15; -% 60 <= max_print_line; -% These apply to Metafont and MetaPost as well. -error_line = 254 -half_error_line = 127 -max_print_line = 32000 - diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfm/pgfmanual-dvipdfm.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfm/pgfmanual-dvipdfm.cfg index cd6c2322fee..500c76d0058 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfm/pgfmanual-dvipdfm.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfm/pgfmanual-dvipdfm.cfg @@ -8,6 +8,8 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} + \usepackage[dvipdfm]{graphics} % This will tell everyone which driver we are using. diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/Makefile b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/Makefile index b0d1d980eec..aa777e23e39 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/Makefile +++ b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/Makefile @@ -12,6 +12,7 @@ pgfmanual.ind: pgfmanual.idx makeindex $(doc).idx pgfmanual.pdf: $(doc).tex $(doc).ind + mkdir -p plots (TEXINPUTS="$(TEXINPUTS)" $(latex) $(doc).tex) || true (egrep -q $(rerun) $(doc).log && TEXINPUTS="$(TEXINPUTS)" $(latex) $(doc).tex) || true dvipdfmx -p a4 $(doc) diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual-test.tex b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual-test.tex new file mode 100644 index 00000000000..c4d74a3e8da --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/en/pgfmanual-test.tex @@ -0,0 +1,25 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\documentclass[a4paper]{ltxdoc} + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\input{../pgfmanual-dvipdfmx.cfg} +\input{../../text-en/pgfmanual-en-main-preamble.tex} + +\begin{document} + +\hypertarget{foo}{Bar} +\hyperlink{foo}{to bar} + +\tikz [transparency group] \node {Smoking}; + +\end{document} diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/pgfmanual-dvipdfmx.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/pgfmanual-dvipdfmx.cfg index 7d619800b1b..2303efdbf5a 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/pgfmanual-dvipdfmx.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-dvipdfmx/pgfmanual-dvipdfmx.cfg @@ -7,6 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} \usepackage[dvipdfmx]{graphicx} % This will tell everyone which driver we are using. diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-dvips/pgfmanual-dvips.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-dvips/pgfmanual-dvips.cfg index 9051b2b3bfd..9f5e7f82c8a 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-dvips/pgfmanual-dvips.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-dvips/pgfmanual-dvips.cfg @@ -8,6 +8,7 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} \usepackage[dvips]{graphics} \usepackage{hyperref} diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/Makefile b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/Makefile new file mode 100644 index 00000000000..685f3468037 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/Makefile @@ -0,0 +1,45 @@ +rerun = "(There were undefined references|Rerun to get (cross-references|the bars) right)" +doc = pgfmanual +latex = lualatex +TEXINPUTS := ../../text-en:../../images:$(TEXINPUTS) + +all: $(doc).pdf + +dist: FORCE + $(latex) --jobname=pgfmanual '\def\pgfautoxrefs{1}\pdfminorversion=5 \pdfobjcompresslevel=2 \input{$(doc)}' + makeindex $(doc).idx + @echo "$(doc).pdf remade with auto-xref support. Check if auto-xrefs work and rerun make dist if not." + +pgfmanual.idx: + touch pgfmanual.idx + +pgfmanual.ind: pgfmanual.idx + makeindex $(doc).idx + +pgfmanual.pdf: $(doc).tex $(doc).ind + TEXINPUTS="$(TEXINPUTS)" $(latex) '$(linkcode)' $(doc).tex + (egrep -q $(rerun) $(doc).log && TEXINPUTS="$(TEXINPUTS)" $(latex) $(doc).tex) || true + @echo "Use 'make dist' to generate auto-xrefs." + +test: $(doc)-test.tex $(doc).ind + TEXINPUTS="$(TEXINPUTS)" $(latex) $(doc)-test.tex + (egrep -q $(rerun) $(doc).log && TEXINPUTS="$(TEXINPUTS)" $(latex) $(doc)-test.tex) || true + @echo "Use 'make dist' to generate auto-xrefs." + +FORCE: + +clean: + rm -f \ + plots/* \ + pgfmanual.out \ + pgfmanual.log \ + pgfmanual.idx \ + pgfmanual.ind \ + pgfmanual.ilg \ + pgfmanual.pdf \ + pgfmanual.toc \ + pgfmanual.bbl \ + pgfmanual.blg \ + pgfmanual.ps \ + pgfmanual.dvi \ + pgfmanual*.aux diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual-test.tex b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual-test.tex new file mode 100644 index 00000000000..9827f1a15a1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual-test.tex @@ -0,0 +1,33 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\documentclass[a4paper]{ltxdoc} + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\input{../pgfmanual-luatex.cfg} +\input{../../text-en/pgfmanual-en-main-preamble.tex} + +\begin{document} + +\begin{key}{/tikz/graph/testy} + foo +\end{key} + +\tikzset{/tikz/testy/.style=} +\tikzset{/tikz/graph/testy/.style=} + +\begin{codeexample}[] + +\tikz \draw [graph/testy,testy] (0,0) -- (1,1); +\end{codeexample} + + +\end{document} diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual.tex b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual.tex new file mode 100644 index 00000000000..d1c6389a5c7 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/en/pgfmanual.tex @@ -0,0 +1,16 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + +\documentclass[a4paper]{ltxdoc} + +% pgf version is defined in \pgfversion in file +% generic/pgf/utilities/pgfrcs.code.tex + +\input{../pgfmanual-luatex.cfg} +\input{../../text-en/pgfmanual-en-main.tex} diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-luatex/pgfmanual-luatex.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/pgfmanual-luatex.cfg new file mode 100644 index 00000000000..87f7a939757 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/version-for-luatex/pgfmanual-luatex.cfg @@ -0,0 +1,14 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\usepackage[hyphens]{url} +\usepackage[pdfborder={0 0 0}]{hyperref} + +% Just make sure to compile this using lualatex. diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/Makefile b/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/Makefile index 1983d547501..dabca5ae516 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/Makefile +++ b/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/Makefile @@ -5,14 +5,8 @@ TEXINPUTS := ../../text-en:../../images:$(TEXINPUTS) all: $(doc).pdf -# make dist will also enable automatic cross references in codeexamples. -# This is disabled by default as it requires higher mem limits. -# -# It employs a 'texmf.cnf' which lies in ../../text-en. dist: FORCE - export TEXMFCNF="../../text-en:$(TEXMFCNF)"; \ - export TEXINPUTS="$(TEXINPUTS)"; \ - $(latex) '\def\pgfautoxrefs{1}\pdfminorversion=5 \pdfobjcompresslevel=2 \input{$(doc)}' + $(latex) --jobname=pgfmanual '\def\pgfautoxrefs{1}\pdfminorversion=5 \pdfobjcompresslevel=2 \input{$(doc)}' makeindex $(doc).idx @echo "$(doc).pdf remade with auto-xref support. Check if auto-xrefs work and rerun make dist if not." diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/pgfmanual.figlist b/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/pgfmanual.figlist deleted file mode 100644 index 5bbdfc855da..00000000000 --- a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/en/pgfmanual.figlist +++ /dev/null @@ -1,1464 +0,0 @@ -pgfmanual-figure0 -pgfmanual-figure1 -pgfmanual-figure2 -pgfmanual-figure3 -pgfmanual-figure4 -pgfmanual-figure5 -pgfmanual-figure6 -pgfmanual-figure7 -pgfmanual-figure8 -pgfmanual-figure9 -pgfmanual-figure10 -pgfmanual-figure11 -pgfmanual-figure12 -pgfmanual-figure13 -pgfmanual-figure14 -pgfmanual-figure15 -pgfmanual-figure16 -pgfmanual-figure17 -pgfmanual-figure18 -pgfmanual-figure19 -pgfmanual-figure20 -pgfmanual-figure21 -pgfmanual-figure22 -pgfmanual-figure23 -pgfmanual-figure24 -pgfmanual-figure25 -pgfmanual-figure26 -pgfmanual-figure27 -pgfmanual-figure28 -pgfmanual-figure29 -pgfmanual-figure30 -pgfmanual-figure31 -pgfmanual-figure32 -pgfmanual-figure33 -pgfmanual-figure34 -pgfmanual-figure35 -pgfmanual-figure36 -pgfmanual-figure37 -pgfmanual-figure38 -pgfmanual-figure39 -pgfmanual-figure40 -pgfmanual-figure41 -pgfmanual-figure42 -pgfmanual-figure43 -pgfmanual-figure44 -pgfmanual-figure45 -pgfmanual-figure46 -pgfmanual-figure47 -pgfmanual-figure48 -pgfmanual-figure49 -pgfmanual-figure50 -pgfmanual-figure51 -pgfmanual-figure52 -pgfmanual-figure53 -pgfmanual-figure54 -pgfmanual-figure55 -pgfmanual-figure56 -pgfmanual-figure57 -pgfmanual-figure58 -pgfmanual-figure59 -pgfmanual-figure60 -pgfmanual-figure61 -pgfmanual-figure62 -pgfmanual-figure63 -pgfmanual-figure64 -pgfmanual-figure65 -pgfmanual-figure66 -pgfmanual-figure67 -pgfmanual-figure68 -pgfmanual-figure69 -pgfmanual-figure70 -pgfmanual-figure71 -pgfmanual-figure72 -pgfmanual-figure73 -pgfmanual-figure74 -pgfmanual-figure75 -pgfmanual-figure76 -pgfmanual-figure77 -pgfmanual-figure78 -pgfmanual-figure79 -pgfmanual-figure80 -pgfmanual-figure81 -pgfmanual-figure82 -pgfmanual-figure83 -pgfmanual-figure84 -pgfmanual-figure85 -pgfmanual-figure86 -pgfmanual-figure87 -pgfmanual-figure88 -pgfmanual-figure89 -pgfmanual-figure90 -pgfmanual-figure91 -pgfmanual-figure92 -pgfmanual-figure93 -pgfmanual-figure94 -pgfmanual-figure95 -pgfmanual-figure96 -pgfmanual-figure97 -pgfmanual-figure98 -pgfmanual-figure99 -pgfmanual-figure100 -pgfmanual-figure101 -pgfmanual-figure102 -pgfmanual-figure103 -pgfmanual-figure104 -pgfmanual-figure105 -pgfmanual-figure106 -pgfmanual-figure107 -pgfmanual-figure108 -pgfmanual-figure109 -pgfmanual-figure110 -pgfmanual-figure111 -pgfmanual-figure112 -pgfmanual-figure113 -pgfmanual-figure114 -pgfmanual-figure115 -pgfmanual-figure116 -pgfmanual-figure117 -pgfmanual-figure118 -pgfmanual-figure119 -pgfmanual-figure120 -pgfmanual-figure121 -pgfmanual-figure122 -pgfmanual-figure123 -pgfmanual-figure124 -pgfmanual-figure125 -pgfmanual-figure126 -pgfmanual-figure127 -pgfmanual-figure128 -pgfmanual-figure129 -pgfmanual-figure130 -pgfmanual-figure131 -pgfmanual-figure132 -pgfmanual-figure133 -pgfmanual-figure134 -pgfmanual-figure135 -pgfmanual-figure136 -pgfmanual-figure137 -pgfmanual-figure138 -pgfmanual-figure139 -pgfmanual-figure140 -pgfmanual-figure141 -pgfmanual-figure142 -pgfmanual-figure143 -pgfmanual-figure144 -pgfmanual-figure145 -pgfmanual-figure146 -pgfmanual-figure147 -pgfmanual-figure148 -pgfmanual-figure149 -pgfmanual-figure150 -pgfmanual-figure151 -pgfmanual-figure152 -pgfmanual-figure153 -pgfmanual-figure154 -pgfmanual-figure155 -pgfmanual-figure156 -pgfmanual-figure157 -pgfmanual-figure158 -pgfmanual-figure159 -pgfmanual-figure160 -pgfmanual-figure161 -pgfmanual-figure162 -pgfmanual-figure163 -pgfmanual-figure164 -pgfmanual-figure165 -pgfmanual-figure166 -pgfmanual-figure167 -pgfmanual-figure168 -pgfmanual-figure169 -pgfmanual-figure170 -pgfmanual-figure171 -pgfmanual-figure172 -pgfmanual-figure173 -pgfmanual-figure174 -pgfmanual-figure175 -pgfmanual-figure176 -pgfmanual-figure177 -pgfmanual-figure178 -pgfmanual-figure179 -pgfmanual-figure180 -pgfmanual-figure181 -pgfmanual-figure182 -pgfmanual-figure183 -pgfmanual-figure184 -pgfmanual-figure185 -pgfmanual-figure186 -pgfmanual-figure187 -pgfmanual-figure188 -pgfmanual-figure189 -pgfmanual-figure190 -pgfmanual-figure191 -pgfmanual-figure192 -pgfmanual-figure193 -pgfmanual-figure194 -pgfmanual-figure195 -pgfmanual-figure196 -pgfmanual-figure197 -pgfmanual-figure198 -pgfmanual-figure199 -pgfmanual-figure200 -pgfmanual-figure201 -pgfmanual-figure202 -pgfmanual-figure203 -pgfmanual-figure204 -pgfmanual-figure205 -pgfmanual-figure206 -pgfmanual-figure207 -pgfmanual-figure208 -pgfmanual-figure209 -pgfmanual-figure210 -pgfmanual-figure211 -pgfmanual-figure212 -pgfmanual-figure213 -pgfmanual-figure214 -pgfmanual-figure215 -pgfmanual-figure216 -pgfmanual-figure217 -pgfmanual-figure218 -pgfmanual-figure219 -pgfmanual-figure220 -pgfmanual-figure221 -pgfmanual-figure222 -pgfmanual-figure223 -pgfmanual-figure224 -pgfmanual-figure225 -pgfmanual-figure226 -pgfmanual-figure227 -pgfmanual-figure228 -pgfmanual-figure229 -pgfmanual-figure230 -pgfmanual-figure231 -pgfmanual-figure232 -pgfmanual-figure233 -pgfmanual-figure234 -pgfmanual-figure235 -pgfmanual-figure236 -pgfmanual-figure237 -pgfmanual-figure238 -pgfmanual-figure239 -pgfmanual-figure240 -pgfmanual-figure241 -pgfmanual-figure242 -pgfmanual-figure243 -pgfmanual-figure244 -pgfmanual-figure245 -pgfmanual-figure246 -pgfmanual-figure247 -pgfmanual-figure248 -pgfmanual-figure249 -pgfmanual-figure250 -pgfmanual-figure251 -pgfmanual-figure252 -pgfmanual-figure253 -pgfmanual-figure254 -pgfmanual-figure255 -pgfmanual-figure256 -pgfmanual-figure257 -pgfmanual-figure258 -pgfmanual-figure259 -pgfmanual-figure260 -pgfmanual-figure261 -pgfmanual-figure262 -pgfmanual-figure263 -pgfmanual-figure264 -pgfmanual-figure265 -pgfmanual-figure266 -pgfmanual-figure267 -pgfmanual-figure268 -pgfmanual-figure269 -pgfmanual-figure270 -pgfmanual-figure271 -pgfmanual-figure272 -pgfmanual-figure273 -pgfmanual-figure274 -pgfmanual-figure275 -pgfmanual-figure276 -pgfmanual-figure277 -pgfmanual-figure278 -pgfmanual-figure279 -pgfmanual-figure280 -pgfmanual-figure281 -pgfmanual-figure282 -pgfmanual-figure283 -pgfmanual-figure284 -pgfmanual-figure285 -pgfmanual-figure286 -pgfmanual-figure287 -pgfmanual-figure288 -pgfmanual-figure289 -pgfmanual-figure290 -pgfmanual-figure291 -pgfmanual-figure292 -pgfmanual-figure293 -pgfmanual-figure294 -pgfmanual-figure295 -pgfmanual-figure296 -pgfmanual-figure297 -pgfmanual-figure298 -pgfmanual-figure299 -pgfmanual-figure300 -pgfmanual-figure301 -pgfmanual-figure302 -pgfmanual-figure303 -pgfmanual-figure304 -pgfmanual-figure305 -pgfmanual-figure306 -pgfmanual-figure307 -pgfmanual-figure308 -pgfmanual-figure309 -pgfmanual-figure310 -pgfmanual-figure311 -pgfmanual-figure312 -pgfmanual-figure313 -pgfmanual-figure314 -pgfmanual-figure315 -pgfmanual-figure316 -pgfmanual-figure317 -pgfmanual-figure318 -pgfmanual-figure319 -pgfmanual-figure320 -pgfmanual-figure321 -pgfmanual-figure322 -pgfmanual-figure323 -pgfmanual-figure324 -pgfmanual-figure325 -pgfmanual-figure326 -pgfmanual-figure327 -pgfmanual-figure328 -pgfmanual-figure329 -pgfmanual-figure330 -pgfmanual-figure331 -pgfmanual-figure332 -pgfmanual-figure333 -pgfmanual-figure334 -pgfmanual-figure335 -pgfmanual-figure336 -pgfmanual-figure337 -pgfmanual-figure338 -pgfmanual-figure339 -pgfmanual-figure340 -pgfmanual-figure341 -pgfmanual-figure342 -pgfmanual-figure343 -pgfmanual-figure344 -pgfmanual-figure345 -pgfmanual-figure346 -pgfmanual-figure347 -pgfmanual-figure348 -pgfmanual-figure349 -pgfmanual-figure350 -pgfmanual-figure351 -pgfmanual-figure352 -pgfmanual-figure353 -pgfmanual-figure354 -pgfmanual-figure355 -pgfmanual-figure356 -pgfmanual-figure357 -pgfmanual-figure358 -pgfmanual-figure359 -pgfmanual-figure360 -pgfmanual-figure361 -pgfmanual-figure362 -pgfmanual-figure363 -pgfmanual-figure364 -pgfmanual-figure365 -pgfmanual-figure366 -pgfmanual-figure367 -pgfmanual-figure368 -pgfmanual-figure369 -pgfmanual-figure370 -pgfmanual-figure371 -pgfmanual-figure372 -pgfmanual-figure373 -pgfmanual-figure374 -pgfmanual-figure375 -pgfmanual-figure376 -pgfmanual-figure377 -pgfmanual-figure378 -pgfmanual-figure379 -pgfmanual-figure380 -pgfmanual-figure381 -pgfmanual-figure382 -pgfmanual-figure383 -pgfmanual-figure384 -pgfmanual-figure385 -pgfmanual-figure386 -pgfmanual-figure387 -pgfmanual-figure388 -pgfmanual-figure389 -pgfmanual-figure390 -pgfmanual-figure391 -pgfmanual-figure392 -pgfmanual-figure393 -pgfmanual-figure394 -pgfmanual-figure395 -pgfmanual-figure396 -pgfmanual-figure397 -pgfmanual-figure398 -pgfmanual-figure399 -pgfmanual-figure400 -pgfmanual-figure401 -pgfmanual-figure402 -pgfmanual-figure403 -pgfmanual-figure404 -pgfmanual-figure405 -pgfmanual-figure406 -pgfmanual-figure407 -pgfmanual-figure408 -pgfmanual-figure409 -pgfmanual-figure410 -pgfmanual-figure411 -pgfmanual-figure412 -pgfmanual-figure413 -pgfmanual-figure414 -pgfmanual-figure415 -pgfmanual-figure416 -pgfmanual-figure417 -pgfmanual-figure418 -pgfmanual-figure419 -pgfmanual-figure420 -pgfmanual-figure421 -pgfmanual-figure422 -pgfmanual-figure423 -pgfmanual-figure424 -pgfmanual-figure425 -pgfmanual-figure426 -pgfmanual-figure427 -pgfmanual-figure428 -pgfmanual-figure429 -pgfmanual-figure430 -pgfmanual-figure431 -pgfmanual-figure432 -pgfmanual-figure433 -pgfmanual-figure434 -pgfmanual-figure435 -pgfmanual-figure436 -pgfmanual-figure437 -pgfmanual-figure438 -pgfmanual-figure439 -pgfmanual-figure440 -pgfmanual-figure441 -pgfmanual-figure442 -pgfmanual-figure443 -pgfmanual-figure444 -pgfmanual-figure445 -pgfmanual-figure446 -pgfmanual-figure447 -pgfmanual-figure448 -pgfmanual-figure449 -pgfmanual-figure450 -pgfmanual-figure451 -pgfmanual-figure452 -pgfmanual-figure453 -pgfmanual-figure454 -pgfmanual-figure455 -pgfmanual-figure456 -pgfmanual-figure457 -pgfmanual-figure458 -pgfmanual-figure459 -pgfmanual-figure460 -pgfmanual-figure461 -pgfmanual-figure462 -pgfmanual-figure463 -pgfmanual-figure464 -pgfmanual-figure465 -pgfmanual-figure466 -pgfmanual-figure467 -pgfmanual-figure468 -pgfmanual-figure469 -pgfmanual-figure470 -pgfmanual-figure471 -pgfmanual-figure472 -pgfmanual-figure473 -pgfmanual-figure474 -pgfmanual-figure475 -pgfmanual-figure476 -pgfmanual-figure477 -pgfmanual-figure478 -pgfmanual-figure479 -pgfmanual-figure480 -pgfmanual-figure481 -pgfmanual-figure482 -pgfmanual-figure483 -pgfmanual-figure484 -pgfmanual-figure485 -pgfmanual-figure486 -pgfmanual-figure487 -pgfmanual-figure488 -pgfmanual-figure489 -pgfmanual-figure490 -pgfmanual-figure491 -pgfmanual-figure492 -pgfmanual-figure493 -pgfmanual-figure494 -pgfmanual-figure495 -pgfmanual-figure496 -pgfmanual-figure497 -pgfmanual-figure498 -pgfmanual-figure499 -pgfmanual-figure500 -pgfmanual-figure501 -pgfmanual-figure502 -pgfmanual-figure503 -pgfmanual-figure504 -pgfmanual-figure505 -pgfmanual-figure506 -pgfmanual-figure507 -pgfmanual-figure508 -pgfmanual-figure509 -pgfmanual-figure510 -pgfmanual-figure511 -pgfmanual-figure512 -pgfmanual-figure513 -pgfmanual-figure514 -pgfmanual-figure515 -pgfmanual-figure516 -pgfmanual-figure517 -pgfmanual-figure518 -pgfmanual-figure519 -pgfmanual-figure520 -pgfmanual-figure521 -pgfmanual-figure522 -pgfmanual-figure523 -pgfmanual-figure524 -pgfmanual-figure525 -pgfmanual-figure526 -pgfmanual-figure527 -pgfmanual-figure528 -pgfmanual-figure529 -pgfmanual-figure530 -pgfmanual-figure531 -pgfmanual-figure532 -pgfmanual-figure533 -pgfmanual-figure534 -pgfmanual-figure535 -pgfmanual-figure536 -pgfmanual-figure537 -pgfmanual-figure538 -pgfmanual-figure539 -pgfmanual-figure540 -pgfmanual-figure541 -pgfmanual-figure542 -pgfmanual-figure543 -pgfmanual-figure544 -pgfmanual-figure545 -pgfmanual-figure546 -pgfmanual-figure547 -pgfmanual-figure548 -pgfmanual-figure549 -pgfmanual-figure550 -pgfmanual-figure551 -pgfmanual-figure552 -pgfmanual-figure553 -pgfmanual-figure554 -pgfmanual-figure555 -pgfmanual-figure556 -pgfmanual-figure557 -pgfmanual-figure558 -pgfmanual-figure559 -pgfmanual-figure560 -pgfmanual-figure561 -pgfmanual-figure562 -pgfmanual-figure563 -pgfmanual-figure564 -pgfmanual-figure565 -pgfmanual-figure566 -pgfmanual-figure567 -pgfmanual-figure568 -pgfmanual-figure569 -pgfmanual-figure570 -pgfmanual-figure571 -pgfmanual-figure572 -pgfmanual-figure573 -pgfmanual-figure574 -pgfmanual-figure575 -pgfmanual-figure576 -pgfmanual-figure577 -pgfmanual-figure578 -pgfmanual-figure579 -pgfmanual-figure580 -pgfmanual-figure581 -pgfmanual-figure582 -pgfmanual-figure583 -pgfmanual-figure584 -pgfmanual-figure585 -pgfmanual-figure586 -pgfmanual-figure587 -pgfmanual-figure588 -pgfmanual-figure589 -pgfmanual-figure590 -pgfmanual-figure591 -pgfmanual-figure592 -pgfmanual-figure593 -pgfmanual-figure594 -pgfmanual-figure595 -pgfmanual-figure596 -pgfmanual-figure597 -pgfmanual-figure598 -pgfmanual-figure599 -pgfmanual-figure600 -pgfmanual-figure601 -pgfmanual-figure602 -pgfmanual-figure603 -pgfmanual-figure604 -pgfmanual-figure605 -pgfmanual-figure606 -pgfmanual-figure607 -pgfmanual-figure608 -pgfmanual-figure609 -pgfmanual-figure610 -pgfmanual-figure611 -pgfmanual-figure612 -pgfmanual-figure613 -pgfmanual-figure614 -pgfmanual-figure615 -pgfmanual-figure616 -pgfmanual-figure617 -pgfmanual-figure618 -pgfmanual-figure619 -pgfmanual-figure620 -pgfmanual-figure621 -pgfmanual-figure622 -pgfmanual-figure623 -pgfmanual-figure624 -pgfmanual-figure625 -pgfmanual-figure626 -pgfmanual-figure627 -pgfmanual-figure628 -pgfmanual-figure629 -pgfmanual-figure630 -pgfmanual-figure631 -pgfmanual-figure632 -pgfmanual-figure633 -pgfmanual-figure634 -pgfmanual-figure635 -pgfmanual-figure636 -pgfmanual-figure637 -pgfmanual-figure638 -pgfmanual-figure639 -pgfmanual-figure640 -pgfmanual-figure641 -pgfmanual-figure642 -pgfmanual-figure643 -pgfmanual-figure644 -pgfmanual-figure645 -pgfmanual-figure646 -pgfmanual-figure647 -pgfmanual-figure648 -pgfmanual-figure649 -pgfmanual-figure650 -pgfmanual-figure651 -pgfmanual-figure652 -pgfmanual-figure653 -pgfmanual-figure654 -pgfmanual-figure655 -pgfmanual-figure656 -pgfmanual-figure657 -pgfmanual-figure658 -pgfmanual-figure659 -pgfmanual-figure660 -pgfmanual-figure661 -pgfmanual-figure662 -pgfmanual-figure663 -pgfmanual-figure664 -pgfmanual-figure665 -pgfmanual-figure666 -pgfmanual-figure667 -pgfmanual-figure668 -pgfmanual-figure669 -pgfmanual-figure670 -pgfmanual-figure671 -pgfmanual-figure672 -pgfmanual-figure673 -pgfmanual-figure674 -pgfmanual-figure675 -pgfmanual-figure676 -pgfmanual-figure677 -pgfmanual-figure678 -pgfmanual-figure679 -pgfmanual-figure680 -pgfmanual-figure681 -pgfmanual-figure682 -pgfmanual-figure683 -pgfmanual-figure684 -pgfmanual-figure685 -pgfmanual-figure686 -pgfmanual-figure687 -pgfmanual-figure688 -pgfmanual-figure689 -pgfmanual-figure690 -pgfmanual-figure691 -pgfmanual-figure692 -pgfmanual-figure693 -pgfmanual-figure694 -pgfmanual-figure695 -pgfmanual-figure696 -pgfmanual-figure697 -pgfmanual-figure698 -pgfmanual-figure699 -pgfmanual-figure700 -pgfmanual-figure701 -pgfmanual-figure702 -pgfmanual-figure703 -pgfmanual-figure704 -pgfmanual-figure705 -pgfmanual-figure706 -pgfmanual-figure707 -pgfmanual-figure708 -pgfmanual-figure709 -pgfmanual-figure710 -pgfmanual-figure711 -pgfmanual-figure712 -pgfmanual-figure713 -pgfmanual-figure714 -pgfmanual-figure715 -pgfmanual-figure716 -pgfmanual-figure717 -pgfmanual-figure718 -pgfmanual-figure719 -pgfmanual-figure720 -pgfmanual-figure721 -pgfmanual-figure722 -pgfmanual-figure723 -pgfmanual-figure724 -pgfmanual-figure725 -pgfmanual-figure726 -pgfmanual-figure727 -pgfmanual-figure728 -pgfmanual-figure729 -pgfmanual-figure730 -pgfmanual-figure731 -pgfmanual-figure732 -pgfmanual-figure733 -pgfmanual-figure734 -pgfmanual-figure735 -pgfmanual-figure736 -pgfmanual-figure737 -pgfmanual-figure738 -pgfmanual-figure739 -pgfmanual-figure740 -pgfmanual-figure741 -pgfmanual-figure742 -pgfmanual-figure743 -pgfmanual-figure744 -pgfmanual-figure745 -pgfmanual-figure746 -pgfmanual-figure747 -pgfmanual-figure748 -pgfmanual-figure749 -pgfmanual-figure750 -pgfmanual-figure751 -pgfmanual-figure752 -pgfmanual-figure753 -pgfmanual-figure754 -pgfmanual-figure755 -pgfmanual-figure756 -pgfmanual-figure757 -pgfmanual-figure758 -pgfmanual-figure759 -pgfmanual-figure760 -pgfmanual-figure761 -pgfmanual-figure762 -pgfmanual-figure763 -pgfmanual-figure764 -pgfmanual-figure765 -pgfmanual-figure766 -pgfmanual-figure767 -pgfmanual-figure768 -pgfmanual-figure769 -pgfmanual-figure770 -pgfmanual-figure771 -pgfmanual-figure772 -pgfmanual-figure773 -pgfmanual-figure774 -pgfmanual-figure775 -pgfmanual-figure776 -pgfmanual-figure777 -pgfmanual-figure778 -pgfmanual-figure779 -pgfmanual-figure780 -pgfmanual-figure781 -pgfmanual-figure782 -pgfmanual-figure783 -pgfmanual-figure784 -pgfmanual-figure785 -pgfmanual-figure786 -pgfmanual-figure787 -pgfmanual-figure788 -pgfmanual-figure789 -pgfmanual-figure790 -pgfmanual-figure791 -pgfmanual-figure792 -pgfmanual-figure793 -pgfmanual-figure794 -pgfmanual-figure795 -pgfmanual-figure796 -pgfmanual-figure797 -pgfmanual-figure798 -pgfmanual-figure799 -pgfmanual-figure800 -pgfmanual-figure801 -pgfmanual-figure802 -pgfmanual-figure803 -pgfmanual-figure804 -pgfmanual-figure805 -pgfmanual-figure806 -pgfmanual-figure807 -pgfmanual-figure808 -pgfmanual-figure809 -pgfmanual-figure810 -pgfmanual-figure811 -pgfmanual-figure812 -pgfmanual-figure813 -pgfmanual-figure814 -pgfmanual-figure815 -pgfmanual-figure816 -pgfmanual-figure817 -pgfmanual-figure818 -pgfmanual-figure819 -pgfmanual-figure820 -pgfmanual-figure821 -pgfmanual-figure822 -pgfmanual-figure823 -pgfmanual-figure824 -pgfmanual-figure825 -pgfmanual-figure826 -pgfmanual-figure827 -pgfmanual-figure828 -pgfmanual-figure829 -pgfmanual-figure830 -pgfmanual-figure831 -pgfmanual-figure832 -pgfmanual-figure833 -pgfmanual-figure834 -pgfmanual-figure835 -pgfmanual-figure836 -pgfmanual-figure837 -pgfmanual-figure838 -pgfmanual-figure839 -pgfmanual-figure840 -pgfmanual-figure841 -pgfmanual-figure842 -pgfmanual-figure843 -pgfmanual-figure844 -pgfmanual-figure845 -pgfmanual-figure846 -pgfmanual-figure847 -pgfmanual-figure848 -pgfmanual-figure849 -pgfmanual-figure850 -pgfmanual-figure851 -pgfmanual-figure852 -pgfmanual-figure853 -pgfmanual-figure854 -pgfmanual-figure855 -pgfmanual-figure856 -pgfmanual-figure857 -pgfmanual-figure858 -pgfmanual-figure859 -pgfmanual-figure860 -pgfmanual-figure861 -pgfmanual-figure862 -pgfmanual-figure863 -pgfmanual-figure864 -pgfmanual-figure865 -pgfmanual-figure866 -pgfmanual-figure867 -pgfmanual-figure868 -pgfmanual-figure869 -pgfmanual-figure870 -pgfmanual-figure871 -pgfmanual-figure872 -pgfmanual-figure873 -pgfmanual-figure874 -pgfmanual-figure875 -pgfmanual-figure876 -pgfmanual-figure877 -pgfmanual-figure878 -pgfmanual-figure879 -pgfmanual-figure880 -pgfmanual-figure881 -pgfmanual-figure882 -pgfmanual-figure883 -pgfmanual-figure884 -pgfmanual-figure885 -pgfmanual-figure886 -pgfmanual-figure887 -pgfmanual-figure888 -pgfmanual-figure889 -pgfmanual-figure890 -pgfmanual-figure891 -pgfmanual-figure892 -pgfmanual-figure893 -pgfmanual-figure894 -pgfmanual-figure895 -pgfmanual-figure896 -pgfmanual-figure897 -pgfmanual-figure898 -pgfmanual-figure899 -pgfmanual-figure900 -pgfmanual-figure901 -pgfmanual-figure902 -pgfmanual-figure903 -pgfmanual-figure904 -pgfmanual-figure905 -pgfmanual-figure906 -pgfmanual-figure907 -pgfmanual-figure908 -pgfmanual-figure909 -pgfmanual-figure910 -pgfmanual-figure911 -pgfmanual-figure912 -pgfmanual-figure913 -pgfmanual-figure914 -pgfmanual-figure915 -pgfmanual-figure916 -pgfmanual-figure917 -pgfmanual-figure918 -pgfmanual-figure919 -pgfmanual-figure920 -pgfmanual-figure921 -pgfmanual-figure922 -pgfmanual-figure923 -pgfmanual-figure924 -pgfmanual-figure925 -pgfmanual-figure926 -pgfmanual-figure927 -pgfmanual-figure928 -pgfmanual-figure929 -pgfmanual-figure930 -pgfmanual-figure931 -pgfmanual-figure932 -pgfmanual-figure933 -pgfmanual-figure934 -pgfmanual-figure935 -pgfmanual-figure936 -pgfmanual-figure937 -pgfmanual-figure938 -pgfmanual-figure939 -pgfmanual-figure940 -pgfmanual-figure941 -pgfmanual-figure942 -pgfmanual-figure943 -pgfmanual-figure944 -pgfmanual-figure945 -pgfmanual-figure946 -pgfmanual-figure947 -pgfmanual-figure948 -pgfmanual-figure949 -pgfmanual-figure950 -pgfmanual-figure951 -pgfmanual-figure952 -pgfmanual-figure953 -pgfmanual-figure954 -pgfmanual-figure955 -pgfmanual-figure956 -pgfmanual-figure957 -pgfmanual-figure958 -pgfmanual-figure959 -pgfmanual-figure960 -pgfmanual-figure961 -pgfmanual-figure962 -pgfmanual-figure963 -pgfmanual-figure964 -pgfmanual-figure965 -pgfmanual-figure966 -pgfmanual-figure967 -pgfmanual-figure968 -pgfmanual-figure969 -pgfmanual-figure970 -pgfmanual-figure971 -pgfmanual-figure972 -pgfmanual-figure973 -pgfmanual-figure974 -pgfmanual-figure975 -pgfmanual-figure976 -pgfmanual-figure977 -pgfmanual-figure978 -pgfmanual-figure979 -pgfmanual-figure980 -pgfmanual-figure981 -pgfmanual-figure982 -pgfmanual-figure983 -pgfmanual-figure984 -pgfmanual-figure985 -pgfmanual-figure986 -pgfmanual-figure987 -pgfmanual-figure988 -pgfmanual-figure989 -pgfmanual-figure990 -pgfmanual-figure991 -pgfmanual-figure992 -pgfmanual-figure993 -pgfmanual-figure994 -pgfmanual-figure995 -pgfmanual-figure996 -pgfmanual-figure997 -pgfmanual-figure998 -pgfmanual-figure999 -pgfmanual-figure1000 -pgfmanual-figure1001 -pgfmanual-figure1002 -pgfmanual-figure1003 -pgfmanual-figure1004 -pgfmanual-figure1005 -pgfmanual-figure1006 -pgfmanual-figure1007 -pgfmanual-figure1008 -pgfmanual-figure1009 -pgfmanual-figure1010 -pgfmanual-figure1011 -pgfmanual-figure1012 -pgfmanual-figure1013 -pgfmanual-figure1014 -pgfmanual-figure1015 -pgfmanual-figure1016 -pgfmanual-figure1017 -pgfmanual-figure1018 -pgfmanual-figure1019 -pgfmanual-figure1020 -pgfmanual-figure1021 -pgfmanual-figure1022 -pgfmanual-figure1023 -pgfmanual-figure1024 -pgfmanual-figure1025 -pgfmanual-figure1026 -pgfmanual-figure1027 -pgfmanual-figure1028 -pgfmanual-figure1029 -pgfmanual-figure1030 -pgfmanual-figure1031 -pgfmanual-figure1032 -pgfmanual-figure1033 -pgfmanual-figure1034 -pgfmanual-figure1035 -pgfmanual-figure1036 -pgfmanual-figure1037 -pgfmanual-figure1038 -pgfmanual-figure1039 -pgfmanual-figure1040 -pgfmanual-figure1041 -pgfmanual-figure1042 -pgfmanual-figure1043 -pgfmanual-figure1044 -pgfmanual-figure1045 -pgfmanual-figure1046 -pgfmanual-figure1047 -pgfmanual-figure1048 -pgfmanual-figure1049 -pgfmanual-figure1050 -pgfmanual-figure1051 -pgfmanual-figure1052 -pgfmanual-figure1053 -pgfmanual-figure1054 -pgfmanual-figure1055 -pgfmanual-figure1056 -pgfmanual-figure1057 -pgfmanual-figure1058 -pgfmanual-figure1059 -pgfmanual-figure1060 -pgfmanual-figure1061 -pgfmanual-figure1062 -pgfmanual-figure1063 -pgfmanual-figure1064 -pgfmanual-figure1065 -pgfmanual-figure1066 -pgfmanual-figure1067 -pgfmanual-figure1068 -pgfmanual-figure1069 -pgfmanual-figure1070 -pgfmanual-figure1071 -pgfmanual-figure1072 -pgfmanual-figure1073 -pgfmanual-figure1074 -pgfmanual-figure1075 -pgfmanual-figure1076 -pgfmanual-figure1077 -pgfmanual-figure1078 -pgfmanual-figure1079 -pgfmanual-figure1080 -pgfmanual-figure1081 -pgfmanual-figure1082 -pgfmanual-figure1083 -pgfmanual-figure1084 -pgfmanual-figure1085 -pgfmanual-figure1086 -pgfmanual-figure1087 -pgfmanual-figure1088 -pgfmanual-figure1089 -pgfmanual-figure1090 -pgfmanual-figure1091 -pgfmanual-figure1092 -pgfmanual-figure1093 -pgfmanual-figure1094 -pgfmanual-figure1095 -pgfmanual-figure1096 -pgfmanual-figure1097 -pgfmanual-figure1098 -pgfmanual-figure1099 -pgfmanual-figure1100 -pgfmanual-figure1101 -pgfmanual-figure1102 -pgfmanual-figure1103 -pgfmanual-figure1104 -pgfmanual-figure1105 -pgfmanual-figure1106 -pgfmanual-figure1107 -pgfmanual-figure1108 -pgfmanual-figure1109 -pgfmanual-figure1110 -pgfmanual-figure1111 -pgfmanual-figure1112 -pgfmanual-figure1113 -pgfmanual-figure1114 -pgfmanual-figure1115 -pgfmanual-figure1116 -pgfmanual-figure1117 -pgfmanual-figure1118 -pgfmanual-figure1119 -pgfmanual-figure1120 -pgfmanual-figure1121 -pgfmanual-figure1122 -pgfmanual-figure1123 -pgfmanual-figure1124 -pgfmanual-figure1125 -pgfmanual-figure1126 -pgfmanual-figure1127 -pgfmanual-figure1128 -pgfmanual-figure1129 -pgfmanual-figure1130 -pgfmanual-figure1131 -pgfmanual-figure1132 -pgfmanual-figure1133 -pgfmanual-figure1134 -pgfmanual-figure1135 -pgfmanual-figure1136 -pgfmanual-figure1137 -pgfmanual-figure1138 -pgfmanual-figure1139 -pgfmanual-figure1140 -pgfmanual-figure1141 -pgfmanual-figure1142 -pgfmanual-figure1143 -pgfmanual-figure1144 -pgfmanual-figure1145 -pgfmanual-figure1146 -pgfmanual-figure1147 -pgfmanual-figure1148 -pgfmanual-figure1149 -pgfmanual-figure1150 -pgfmanual-figure1151 -pgfmanual-figure1152 -pgfmanual-figure1153 -pgfmanual-figure1154 -pgfmanual-figure1155 -pgfmanual-figure1156 -pgfmanual-figure1157 -pgfmanual-figure1158 -pgfmanual-figure1159 -pgfmanual-figure1160 -pgfmanual-figure1161 -pgfmanual-figure1162 -pgfmanual-figure1163 -pgfmanual-figure1164 -pgfmanual-figure1165 -pgfmanual-figure1166 -pgfmanual-figure1167 -pgfmanual-figure1168 -pgfmanual-figure1169 -pgfmanual-figure1170 -pgfmanual-figure1171 -pgfmanual-figure1172 -pgfmanual-figure1173 -pgfmanual-figure1174 -pgfmanual-figure1175 -pgfmanual-figure1176 -pgfmanual-figure1177 -pgfmanual-figure1178 -pgfmanual-figure1179 -pgfmanual-figure1180 -pgfmanual-figure1181 -pgfmanual-figure1182 -pgfmanual-figure1183 -pgfmanual-figure1184 -pgfmanual-figure1185 -pgfmanual-figure1186 -pgfmanual-figure1187 -pgfmanual-figure1188 -pgfmanual-figure1189 -pgfmanual-figure1190 -pgfmanual-figure1191 -pgfmanual-figure1192 -pgfmanual-figure1193 -pgfmanual-figure1194 -pgfmanual-figure1195 -pgfmanual-figure1196 -pgfmanual-figure1197 -pgfmanual-figure1198 -pgfmanual-figure1199 -pgfmanual-figure1200 -pgfmanual-figure1201 -pgfmanual-figure1202 -pgfmanual-figure1203 -pgfmanual-figure1204 -pgfmanual-figure1205 -pgfmanual-figure1206 -pgfmanual-figure1207 -pgfmanual-figure1208 -pgfmanual-figure1209 -pgfmanual-figure1210 -pgfmanual-figure1211 -pgfmanual-figure1212 -pgfmanual-figure1213 -pgfmanual-figure1214 -pgfmanual-figure1215 -pgfmanual-figure1216 -pgfmanual-figure1217 -pgfmanual-figure1218 -pgfmanual-figure1219 -pgfmanual-figure1220 -pgfmanual-figure1221 -pgfmanual-figure1222 -pgfmanual-figure1223 -pgfmanual-figure1224 -pgfmanual-figure1225 -pgfmanual-figure1226 -pgfmanual-figure1227 -pgfmanual-figure1228 -pgfmanual-figure1229 -pgfmanual-figure1230 -pgfmanual-figure1231 -pgfmanual-figure1232 -pgfmanual-figure1233 -pgfmanual-figure1234 -pgfmanual-figure1235 -pgfmanual-figure1236 -pgfmanual-figure1237 -pgfmanual-figure1238 -pgfmanual-figure1239 -pgfmanual-figure1240 -pgfmanual-figure1241 -pgfmanual-figure1242 -pgfmanual-figure1243 -pgfmanual-figure1244 -pgfmanual-figure1245 -pgfmanual-figure1246 -pgfmanual-figure1247 -pgfmanual-figure1248 -pgfmanual-figure1249 -pgfmanual-figure1250 -pgfmanual-figure1251 -pgfmanual-figure1252 -pgfmanual-figure1253 -pgfmanual-figure1254 -pgfmanual-figure1255 -pgfmanual-figure1256 -pgfmanual-figure1257 -pgfmanual-figure1258 -pgfmanual-figure1259 -pgfmanual-figure1260 -pgfmanual-figure1261 -pgfmanual-figure1262 -pgfmanual-figure1263 -pgfmanual-figure1264 -pgfmanual-figure1265 -pgfmanual-figure1266 -pgfmanual-figure1267 -pgfmanual-figure1268 -pgfmanual-figure1269 -pgfmanual-figure1270 -pgfmanual-figure1271 -pgfmanual-figure1272 -pgfmanual-figure1273 -pgfmanual-figure1274 -pgfmanual-figure1275 -pgfmanual-figure1276 -pgfmanual-figure1277 -pgfmanual-figure1278 -pgfmanual-figure1279 -pgfmanual-figure1280 -pgfmanual-figure1281 -pgfmanual-figure1282 -pgfmanual-figure1283 -pgfmanual-figure1284 -pgfmanual-figure1285 -pgfmanual-figure1286 -pgfmanual-figure1287 -pgfmanual-figure1288 -pgfmanual-figure1289 -pgfmanual-figure1290 -pgfmanual-figure1291 -pgfmanual-figure1292 -pgfmanual-figure1293 -pgfmanual-figure1294 -pgfmanual-figure1295 -pgfmanual-figure1296 -pgfmanual-figure1297 -pgfmanual-figure1298 -pgfmanual-figure1299 -pgfmanual-figure1300 -pgfmanual-figure1301 -pgfmanual-figure1302 -pgfmanual-figure1303 -pgfmanual-figure1304 -pgfmanual-figure1305 -pgfmanual-figure1306 -pgfmanual-figure1307 -pgfmanual-figure1308 -pgfmanual-figure1309 -pgfmanual-figure1310 -pgfmanual-figure1311 -pgfmanual-figure1312 -pgfmanual-figure1313 -pgfmanual-figure1314 -pgfmanual-figure1315 -pgfmanual-figure1316 -pgfmanual-figure1317 -pgfmanual-figure1318 -pgfmanual-figure1319 -pgfmanual-figure1320 -pgfmanual-figure1321 -pgfmanual-figure1322 -pgfmanual-figure1323 -pgfmanual-figure1324 -pgfmanual-figure1325 -pgfmanual-figure1326 -pgfmanual-figure1327 -pgfmanual-figure1328 -pgfmanual-figure1329 -pgfmanual-figure1330 -pgfmanual-figure1331 -pgfmanual-figure1332 -pgfmanual-figure1333 -pgfmanual-figure1334 -pgfmanual-figure1335 -pgfmanual-figure1336 -pgfmanual-figure1337 -pgfmanual-figure1338 -pgfmanual-figure1339 -pgfmanual-figure1340 -pgfmanual-figure1341 -pgfmanual-figure1342 -pgfmanual-figure1343 -pgfmanual-figure1344 -pgfmanual-figure1345 -pgfmanual-figure1346 -pgfmanual-figure1347 -pgfmanual-figure1348 -pgfmanual-figure1349 -pgfmanual-figure1350 -pgfmanual-figure1351 -pgfmanual-figure1352 -pgfmanual-figure1353 -pgfmanual-figure1354 -pgfmanual-figure1355 -pgfmanual-figure1356 -pgfmanual-figure1357 -pgfmanual-figure1358 -pgfmanual-figure1359 -pgfmanual-figure1360 -pgfmanual-figure1361 -pgfmanual-figure1362 -pgfmanual-figure1363 -pgfmanual-figure1364 -pgfmanual-figure1365 -pgfmanual-figure1366 -pgfmanual-figure1367 -pgfmanual-figure1368 -pgfmanual-figure1369 -pgfmanual-figure1370 -pgfmanual-figure1371 -pgfmanual-figure1372 -pgfmanual-figure1373 -pgfmanual-figure1374 -pgfmanual-figure1375 -pgfmanual-figure1376 -pgfmanual-figure1377 -pgfmanual-figure1378 -pgfmanual-figure1379 -pgfmanual-figure1380 -pgfmanual-figure1381 -pgfmanual-figure1382 -pgfmanual-figure1383 -pgfmanual-figure1384 -pgfmanual-figure1385 -pgfmanual-figure1386 -pgfmanual-figure1387 -pgfmanual-figure1388 -pgfmanual-figure1389 -pgfmanual-figure1390 -pgfmanual-figure1391 -pgfmanual-figure1392 -pgfmanual-figure1393 -pgfmanual-figure1394 -pgfmanual-figure1395 -pgfmanual-figure1396 -pgfmanual-figure1397 -pgfmanual-figure1398 -pgfmanual-figure1399 -pgfmanual-figure1400 -pgfmanual-figure1401 -pgfmanual-figure1402 -pgfmanual-figure1403 -pgfmanual-figure1404 -pgfmanual-figure1405 -pgfmanual-figure1406 -pgfmanual-figure1407 -pgfmanual-figure1408 -pgfmanual-figure1409 -pgfmanual-figure1410 -pgfmanual-figure1411 -pgfmanual-figure1412 -pgfmanual-figure1413 -pgfmanual-figure1414 -pgfmanual-figure1415 -pgfmanual-figure1416 -pgfmanual-figure1417 -pgfmanual-figure1418 -pgfmanual-figure1419 -pgfmanual-figure1420 -pgfmanual-figure1421 -pgfmanual-figure1422 -pgfmanual-figure1423 -pgfmanual-figure1424 -pgfmanual-figure1425 -pgfmanual-figure1426 -pgfmanual-figure1427 -pgfmanual-figure1428 -pgfmanual-figure1429 -pgfmanual-figure1430 -pgfmanual-figure1431 -pgfmanual-figure1432 -pgfmanual-figure1433 -pgfmanual-figure1434 -pgfmanual-figure1435 -pgfmanual-figure1436 -pgfmanual-figure1437 -pgfmanual-figure1438 -pgfmanual-figure1439 -pgfmanual-figure1440 -pgfmanual-figure1441 -pgfmanual-figure1442 -pgfmanual-figure1443 -pgfmanual-figure1444 -pgfmanual-figure1445 -pgfmanual-figure1446 -pgfmanual-figure1447 -pgfmanual-figure1448 -pgfmanual-figure1449 -pgfmanual-figure1450 -pgfmanual-figure1451 -pgfmanual-figure1452 -pgfmanual-figure1453 -pgfmanual-figure1454 -pgfmanual-figure1455 -pgfmanual-figure1456 -pgfmanual-figure1457 -pgfmanual-figure1458 -pgfmanual-figure1459 -pgfmanual-figure1460 -pgfmanual-figure1461 -pgfmanual-figure1462 -pgfmanual-figure1463 diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/pgfmanual-pdftex.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/pgfmanual-pdftex.cfg index 25c46a965a9..0beedab340c 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/pgfmanual-pdftex.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-pdftex/pgfmanual-pdftex.cfg @@ -8,6 +8,7 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} \usepackage[pdfborder={0 0 0}]{hyperref} % Just make sure to compile this using pdfelatex. diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-vtex/pgfmanual-vtex.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-vtex/pgfmanual-vtex.cfg index 6b959370d1a..166b2c1111f 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-vtex/pgfmanual-vtex.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-vtex/pgfmanual-vtex.cfg @@ -7,6 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} \usepackage[vtex]{graphics} \usepackage{hyperref} diff --git a/Master/texmf-dist/doc/generic/pgf/version-for-xetex/pgfmanual-xetex.cfg b/Master/texmf-dist/doc/generic/pgf/version-for-xetex/pgfmanual-xetex.cfg index 0466c698f54..d61e6c3365e 100644 --- a/Master/texmf-dist/doc/generic/pgf/version-for-xetex/pgfmanual-xetex.cfg +++ b/Master/texmf-dist/doc/generic/pgf/version-for-xetex/pgfmanual-xetex.cfg @@ -7,6 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. +\usepackage[hyphens]{url} \usepackage[xetex]{graphics} % This will tell everyone which driver we are using. |