From 673717f7c662dd135f63b61c1da1ecd59bcdbe90 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 5 Dec 2022 03:03:23 +0000 Subject: CTAN sync 202212050303 --- support/digestif/INSTALL.md | 80 + support/digestif/LICENSE | 152 + support/digestif/README.md | 161 + support/digestif/bin/digestif | 2 + support/digestif/bin/digestif.texlua | 25 + support/digestif/data/amsrefs.sty.tags | 612 + support/digestif/data/amssymb.sty.tags | 677 + support/digestif/data/biblatex.sty.tags | 7982 +++++++ support/digestif/data/cleveref.sty.tags | 103 + support/digestif/data/csquotes.sty.tags | 1113 + support/digestif/data/etoolbox.sty.tags | 1285 ++ support/digestif/data/hyperref.sty.tags | 45 + support/digestif/data/latex-prog.tags | 6 + support/digestif/data/latex.tags | 2489 +++ support/digestif/data/natbib.sty.tags | 34 + support/digestif/data/pgf.sty.tags | 1 + support/digestif/data/pgf.tags | 20068 ++++++++++++++++++ support/digestif/data/plain.tags | 2753 +++ support/digestif/data/primitives.tags | 2058 ++ support/digestif/data/t-pgf.xml.tags | 6 + support/digestif/data/t-tikz.xml.tags | 31 + support/digestif/data/teximpatient.tags | 3848 ++++ support/digestif/data/texinfo.tags | 2496 +++ support/digestif/data/tikz.sty.tags | 27 + support/digestif/data/tikz.tags | 22187 ++++++++++++++++++++ support/digestif/data/unicode-math.sty.tags | 10021 +++++++++ support/digestif/data/xparse.sty.tags | 86 + support/digestif/digestif/Cache.lua | 129 + support/digestif/digestif/Manuscript.lua | 1523 ++ support/digestif/digestif/ManuscriptBibTeX.lua | 38 + support/digestif/digestif/ManuscriptConTeXt.lua | 604 + support/digestif/digestif/ManuscriptDoctex.lua | 19 + support/digestif/digestif/ManuscriptLaTeX.lua | 360 + support/digestif/digestif/ManuscriptLatexProg.lua | 12 + support/digestif/digestif/ManuscriptPlainTeX.lua | 56 + support/digestif/digestif/ManuscriptTexinfo.lua | 25 + support/digestif/digestif/Parser.lua | 227 + support/digestif/digestif/Schema.lua | 189 + support/digestif/digestif/bibtex.lua | 271 + support/digestif/digestif/config.lua | 156 + support/digestif/digestif/data.lua | 384 + support/digestif/digestif/langserver.lua | 567 + support/digestif/digestif/util.lua | 789 + 43 files changed, 83697 insertions(+) create mode 100644 support/digestif/INSTALL.md create mode 100644 support/digestif/LICENSE create mode 100644 support/digestif/README.md create mode 100755 support/digestif/bin/digestif create mode 100755 support/digestif/bin/digestif.texlua create mode 100644 support/digestif/data/amsrefs.sty.tags create mode 100644 support/digestif/data/amssymb.sty.tags create mode 100644 support/digestif/data/biblatex.sty.tags create mode 100644 support/digestif/data/cleveref.sty.tags create mode 100644 support/digestif/data/csquotes.sty.tags create mode 100644 support/digestif/data/etoolbox.sty.tags create mode 100644 support/digestif/data/hyperref.sty.tags create mode 100644 support/digestif/data/latex-prog.tags create mode 100644 support/digestif/data/latex.tags create mode 100644 support/digestif/data/natbib.sty.tags create mode 100644 support/digestif/data/pgf.sty.tags create mode 100644 support/digestif/data/pgf.tags create mode 100644 support/digestif/data/plain.tags create mode 100644 support/digestif/data/primitives.tags create mode 100644 support/digestif/data/t-pgf.xml.tags create mode 100644 support/digestif/data/t-tikz.xml.tags create mode 100644 support/digestif/data/teximpatient.tags create mode 100644 support/digestif/data/texinfo.tags create mode 100644 support/digestif/data/tikz.sty.tags create mode 100644 support/digestif/data/tikz.tags create mode 100644 support/digestif/data/unicode-math.sty.tags create mode 100644 support/digestif/data/xparse.sty.tags create mode 100644 support/digestif/digestif/Cache.lua create mode 100644 support/digestif/digestif/Manuscript.lua create mode 100644 support/digestif/digestif/ManuscriptBibTeX.lua create mode 100644 support/digestif/digestif/ManuscriptConTeXt.lua create mode 100644 support/digestif/digestif/ManuscriptDoctex.lua create mode 100644 support/digestif/digestif/ManuscriptLaTeX.lua create mode 100644 support/digestif/digestif/ManuscriptLatexProg.lua create mode 100644 support/digestif/digestif/ManuscriptPlainTeX.lua create mode 100644 support/digestif/digestif/ManuscriptTexinfo.lua create mode 100644 support/digestif/digestif/Parser.lua create mode 100644 support/digestif/digestif/Schema.lua create mode 100644 support/digestif/digestif/bibtex.lua create mode 100644 support/digestif/digestif/config.lua create mode 100644 support/digestif/digestif/data.lua create mode 100644 support/digestif/digestif/langserver.lua create mode 100644 support/digestif/digestif/util.lua (limited to 'support') diff --git a/support/digestif/INSTALL.md b/support/digestif/INSTALL.md new file mode 100644 index 0000000000..f99f4b286a --- /dev/null +++ b/support/digestif/INSTALL.md @@ -0,0 +1,80 @@ +Installation guide +================== + +This installation guide focuses on packaging for redistribution. For +the final user, it is recommended to install via LuaRocks or using the +self-installing script; see the [README](README.md) for details. + +Digestif has the following dependencies: + +* Lua version 5.3 or 5.4 +* LPeg (https://luarocks.org/modules/gvvaughan/lpeg) +* LuaFileSystem (https://luarocks.org/modules/hisham/luafilesystem) +* cjson (optional, https://luarocks.org/modules/openresty/lua-cjson) +* LuaZip (optional, https://luarocks.org/modules/mpeterv/luazip) + +If the cjson library is missing, Digestif uses its own LPeg-based JSON +serializer, which is slower but adequate. LuaZip is required only +when placing the data files in a zip archive. + +All shell commands and file name references assume that the directory +containing this file is the current directory. + +Standard packaging +------------------ + +For a regular installation of Digestif into, say, `PREFIX=/usr`, copy +the files as follows: + + install -Dt $PREFIX/bin bin/digestif + install -Dt $PREFIX/share/lua/$LUA_VERSION digestif + install -Dt $PREFIX/share/digestif data/*.tags + +Before doing so, however, consider the following: + +1. In order for the tags files to be found, add the following at the + top of the `bin/digestif` script: + + require "digestif.config".data_dirs = {"$PREFIX/share/digestif"} + +2. Make sure the `package.path` Lua variable includes the directory + into which the `digestif` directory is installed. + +3. It is recommended that the `package.path` and `package.cpath` Lua + variables do not include the default relative entries such as + `./?.lua`. This is especially important if any of the optional + dependencies are not installed. + +4. If LuaZip is available, the tags files may also be placed in a zip + file: + + zip -j data.zip data/*.tags + install -Dt $PREFIX/share/digestif data.zip + + In this case, add the following line at the top of `bin/digestif`: + + require "digestif.config".data_dirs = {"$PREFIX/share/digestif/data.zip"} + +Packaging for a TeX distribution +-------------------------------- + +For an installation depending only on the `texlua` interpreter from +LuaTeX (which already includes all other dependencies except cjson), +create a zip file containing `digestif/*.lua` and `data/*.tags` (no +subdirectories), place it anywhere kpathsearch will find it and use +the `bin/digestif.texlua` executable script. For instance: + + zip -j digestif.zip digestif/*.lua tags/*.tags + install -Dt $TEXMF/scripts digestif.zip + install bin/digestif.texlua $PREFIX/bin/digestif + +Unbundled installation +---------------------- + +To install Digestif on a directory of its own, say +`PREFIX=/opt/digestif`, copy the `bin`, `data` and `digestif` folders +and add a symlink of the executable script somewhere in the `PATH`. +For instance: + + install -Dt $PREFIX bin data digestif + ln -s $PREFIX/bin/digestif /opt/bin/digestif diff --git a/support/digestif/LICENSE b/support/digestif/LICENSE new file mode 100644 index 0000000000..b1f2360edc --- /dev/null +++ b/support/digestif/LICENSE @@ -0,0 +1,152 @@ +With the exception of the files individually listed below, the +following applies: + +Copyright 2018-2022 Augusto Stoffel + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . + +--- + +amsrefs.sty.tags: + + Copyright 2001-2004, 2007, 2008, 2010-2013 American Mathematical Society + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c+ + + Adapted from the amsrefs package documentation, which can be found + at https://ctan.org/pkg/amsrefs. + +amssymb.sty.tags: + + Copyright 2006-2019 Will Robertson + Copyright 2010-2017 Philipp Stephani + Copyright 2011-2017 Joseph Wright + Copyright 2012-2015 Khaled Hosny + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c+ + + Adapted from the file unicode-math-table.tex, part of the + unicode-math package, which can be found at + https://ctan.org/pkg/unicode-math. + +biblatex.sty.tags: + + Copyright 2006-2012 Philipp Lehman + Copyright 2012-2022 Philipp Lehman, Joseph Wright, Audrey Boruvka, + Philip Kime + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c + + Adapted from the biblatex package documentation, which can be found + at https://github.com/plk/biblatex. + +csquotes.sty.tags: + + Copyright 2003-2011 Philipp Lehman + Copyright 2015-2019, 2021, 2022 Joseph Wright + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c+ + + Adapted from the csquotes package documentation, which can be found + at https://ctan.org/pkg/csquotes. + +etoolbox.sty.tags: + + Copyright 2007-2011 Philipp Lehman + Copyright 2015-2020 Joseph Wright + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c+ + + Adapted form the etoolbox package documentation, which can be found + at https://ctan.org/pkg/etoolbox. + +latex.tags: + + Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, + 2016, 2017, 2018, 2019, 2020, 2021, 2022 Karl Berry + Copyright 1988, 1994, 2007 Stephen Gilmore + Copyright 1994, 1995, 1996 Torsten Martinsen + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: GFDL + + Adapted from the LaTeX2e Unofficial Reference Manual, which can be + found at https://latexref.xyz/. + +pgf.tags: + + Copyright 2007-2013 Till Tantau + Copyright 2022 Augusto Stoffel, Jens Schneider + SPDX-License-Identifier: GFDL-1.2-or-later or LPPL-1.3c+ + + Adapted from the PGF manual, version 3.1.9a, which can be found at + https://github.com/pgf-tikz/pgf/. + +plain.tags: + + Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: GFDL-1.3-only + + Adapted from the book TeX for the Impatient, which can be found at + https://www.gnu.org/software/teximpatient. + +primitives.tags: + + Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: GFDL-1.3-only + + Adapted from the book TeX for the Impatient, which can be found at + https://www.gnu.org/software/teximpatient. + +teximpatient.tags: + + Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: GFDL-1.3-only + + Adapted from the book TeX for the Impatient, which can be found at + https://www.gnu.org/software/teximpatient. + +texinfo.tags: + + Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + Copyright 2019 Augusto Stoffel + SPDX-License-Identifier: GFDL-1.3-only + + Adapted from the GNU Texinfo manual, which can be found at + https://www.gnu.org/software/texinfo/manual/texinfo/. + +tikz.tags: + + Copyright 2007-2013 Till Tantau + Copyright 2022 Augusto Stoffel, Jens Schneider + SPDX-License-Identifier: GFDL-1.2-or-later or LPPL-1.3c+ + + Adapted from the PGF manual, version 3.1.9a, which can be found at + https://github.com/pgf-tikz/pgf/. + +unicode-math.sty.tags: + + Copyright 2006-2019 Will Robertson + Copyright 2010-2017 Philipp Stephani + Copyright 2011-2017 Joseph Wright + Copyright 2012-2015 Khaled Hosny + Copyright 2022 Augusto Stoffel + SPDX-License-Identifier: LPPL-1.3c+ + + Adapted from the file unicode-math-table.tex, part of + the unicode-math package, which can be found at + https://github.com/wspr/unicode-math/ + diff --git a/support/digestif/README.md b/support/digestif/README.md new file mode 100644 index 0000000000..c489d4fa6c --- /dev/null +++ b/support/digestif/README.md @@ -0,0 +1,161 @@ +Digestif +======== + +

+LuaRocks +Build Status +

+ +Digestif is a code analyzer, and a [language server][lsp], for LaTeX, +ConTeXt et caterva. It provides context-sensitive completion, +documentation, code navigation, and related functionality to any text +editor that speaks the LSP protocol. + +![Mandatory GIF][gif] + +Features +-------- + +- Completion for commands, environments, key-value options (for + instance, TikZ options), cross-references and citations. + +- Popup help messages, including command signature and documentation. + For the best results, make sure you have the [LaTeX reference + manual][latexref] installed as an [info node][info-issues]. + +- Find definition and references to labels and citations. + +- Document outline. + +- Multi-file documents are supported via TeXShop-style magic comments. + Just add a comment like this near the top of each child document: + + ``` + % !TeX root = somefile.tex + ``` + +- Digestif is fuzzy! For citations, it tries an exact match against + the BibTeX identifier and a fuzzy match against author and title. + In the GIF above, the user types `groalhom`, which matches + **Gro**thendieck's “Sur quelques points d'**al**gébre + **hom**ologique”; selecting this inserts the BibTeX identifier + `Tohoku`. Similarly, for cross-references, Digestif tries an exact + match against the label and a fuzzy match against the text around + the label. + +- Support for LaTeX, ConTeXt, plain TeX, DocTeX (`.dtx` files) and + Texinfo. + +- Bibliography support via BibTeX, BibLaTeX and amsrefs. + +- Lua API, independent of the language server protocol, for use in + editors capable of loading Lua modules. See [API on the wiki][api] + for details. + +Installation +------------ + +Digestif has minimal dependencies and can run on LuaTeX or on a +standalone Lua interpreter. Correspondingly, there are two ways to +install it. + +### LuaTeX with the self-installing script ![easy] + +The only dependencies for this are git and a recent TeX installation. + +1. Download the [digestif][self-install-sh] wrapper script (or, on + Windows, [digestif.cmd][self-install-cmd]). +2. Place it in your `$PATH` (say, `~/.local/bin`). +3. Make it executable (`chmod +x ~/.local/bin/digestif`). + +In the first run, the script will automatically download the +package, by default to `~/.digestif`. To update or uninstall, +simply delete that folder. + +### Standalone Lua via LuaRocks + +Run `luarocks install digestif`. This should be done either as root +or with the `--local` option, in which case the executable script will +land in `~/.luarocks/bin/digestif`; make sure this is in your `$PATH` +or adapt your text editor configuration accordingly. + +Editor setup +------------ + +Next, you need to enable Digestif as a language server in your +favorite text editor. + +### Emacs with the [Eglot] package + +Digestif works out-of-the-box with Eglot. Just install the package +(`M-x package-install RET eglot RET`), open some TeX document and +enable Eglot (`M-x eglot`). Voilà! Some hints: + +- If you want automatic snippet insertion upon choosing a completion + candidate, make sure to activate `yas-minor-mode` *before* + starting up Eglot. + +- Try the [consult-eglot] package to access the index of a multifile + project (this is exposed via the the `workspace/symbols` LSP + method.) + +### Emacs with the [lsp-mode] package + +To ensure that Digestif is used, add the following to your init file: + + ``` emacs-lisp + (setq lsp-tex-server 'digestif) + ``` + +### Vim with the [Coc] plugin + +See instructions [here](https://github.com/neoclide/coc.nvim/wiki/Language-servers#latex). + +### Other editors + +It shouldn't be hard to set up other editors to use Digestif. Please +open an issue if you want to include additional instructions here. + +Supported TeX packages +---------------------- + +Digestif tries to learn about the commands provided by a package by +looking at its source code, but this has limitations, since the +typical TeX literate documentation is ostensibly not machine readable. + +For full support, a detailed “tags” file should be created for each +package. Among other things, this file lists all defined macros +together with their signatures and docstrings. To generate a stub +tags file from a `.sty`, `.cls` or `.dtx` file, use the command + +``` +digestif --generate FILES +``` + +After filling in the missing details, the resulting tags file can be +added to this repository (pull requests are welcome!). The format of +the tags files should be more or less self explanatory. See the data +folder for examples. + +License +------- + +Digestif is available under the [GNU General Public License][GPL], +version 3 or later. For some files in the [data](./data) directory, a +different license applies. See [LICENSE](./LICENSE) for details. + +[gif]: https://raw.githubusercontent.com/astoff/digestif/images/screenshot.gif +[info-issues]: https://github.com/astoff/digestif/wiki/Common-installation-issues#info-nodes +[installation-issues]: https://github.com/astoff/digestif/wiki/Common-installation-issues +[coc]: https://github.com/neoclide/coc.nvim +[eglot]: https://github.com/joaotavora/eglot +[latexref]: https://latexref.xyz/ +[lsp-mode]: https://github.com/emacs-lsp/lsp-mode +[lsp]: https://microsoft.github.io/language-server-protocol/ +[api]: https://github.com/astoff/digestif/wiki/API +[self-install-sh]: https://raw.githubusercontent.com/astoff/digestif/master/scripts/digestif +[self-install-cmd]: https://raw.githubusercontent.com/astoff/digestif/master/scripts/digestif.cmd +[easy]: https://raw.githubusercontent.com/astoff/digestif/images/easy.png +[GPL]: https://www.gnu.org/licenses/gpl-3.0.txt +[consult-eglot]: https://github.com/mohkale/consult-eglot/ +[Company mode]: https://company-mode.github.io/ diff --git a/support/digestif/bin/digestif b/support/digestif/bin/digestif new file mode 100755 index 0000000000..818d5b355a --- /dev/null +++ b/support/digestif/bin/digestif @@ -0,0 +1,2 @@ +#!/usr/bin/env lua +require "digestif.langserver".main(arg) diff --git a/support/digestif/bin/digestif.texlua b/support/digestif/bin/digestif.texlua new file mode 100755 index 0000000000..caf518071b --- /dev/null +++ b/support/digestif/bin/digestif.texlua @@ -0,0 +1,25 @@ +#!/usr/bin/env texlua +-- Use an invalid directory name in order not to allow kpse to search +-- in the current directory. +os.setenv("TEXMFDOTDIR", package.config:find("^\\") and "NUL" or "/dev/null") +kpse.set_program_name("luatex") +local zip = require "zip" +local archive = kpse.find_file("digestif.zip") + or error("Can't find 'digestif.zip' archive") +local function digestif_searcher(modname) + local submod = modname:match("^digestif%.(.+)") + if not submod then return end + local zipfile = zip.open(archive) + local luafile = zipfile and zipfile:open(submod .. ".lua") + if not luafile then + return "\n\t[digestif] no file '"..submod..".lua' in '"..archive.."'" + end + local chunk = luafile:read("*a") + luafile:close(); zipfile:close() + return load(chunk, "="..archive.."#"..submod..".lua") +end +-- Search inside digestif.zip when requiring digestif.* modules. +table.insert(package.searchers, 2, digestif_searcher) +-- Search inside digestif.zip when loading the *.tags data files. +table.insert(require "digestif.config".data_dirs, archive) +require "digestif.langserver".main(arg) diff --git a/support/digestif/data/amsrefs.sty.tags b/support/digestif/data/amsrefs.sty.tags new file mode 100644 index 0000000000..21bcad5c01 --- /dev/null +++ b/support/digestif/data/amsrefs.sty.tags @@ -0,0 +1,612 @@ +-- Copyright 2001-2004, 2007, 2008, 2010-2013 American Mathematical Society +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c+ +-- +-- Adapted from the amsrefs package documentation, which can be found +-- at https://ctan.org/pkg/amsrefs. +ctan_package = "amsrefs" +package = { + options = { + alphabetic = { + details = [[ +This generates alphabetic labels similar to the `alpha` BibTeX +style, consisting of the first letter(s) of each author name plus the +year of publication. +]] + }, + shortalphabetic = { + details = [[ +This generates a shorter alphabetic label using only the first letter +of each author name. +]] + }, + ["author-year"] = { + details = [[ +This switches to the popular author-year citation format, similar to +that described in The Chicago Manual of Style. +]] + }, + y2k = { + details = [[ +When using the `alphabetic` option, normally only the last two digits +of the year are used in the label. The `y2k` option instructs amsrefs +to use the full year. +]] + }, + ["non-compressed-cites"] = { + details = [[ +Turn off range compression; citations will still be sorted. Range +compression is also automatically turned off if amsrefs detects that +the hyperref package has been loaded. (In order for this to work +correctly, the hyperref package must be loaded after the amsrefs +package.) +]] + }, + ["non-sorted-cites"] = { + details = [[ +Turn off range sorting. This also turns off range compression as a +side-effect. +]] + }, + abbrev = { + details = [[ +This is equivalent to requesting all four of the options `initials`, +`short-journals`,`short-months` and `short-publishers`. +]] + }, + initials = { + details = [[ +Replace the given names of all authors, editors, and translators with +their initials. +]] + }, + ["short-journals"] = { + details = [[ +Print short form instead of full form for journal names. This works +only with abbreviations defined with the `\DefineJournal` command. +]] + }, + ["short-months"] = { + details = [[ +Print short version of month names (e.g., Jan. instead of January). +This works only when you write all dates in ISO 8601 format. +]] + }, + ["short-publishers"] = { + details = [[ +Print short form instead of full form for publisher names. This works +only with abbreviations defined with the `\DefinePublisher` command. +]] + }, + backrefs = { + details = [[ +This option causes “back-references” to be printed at the end of each +bibliography entry to show what page it was cited on. This option +will work only if the hyperref package is installed. +]] + }, + ["bibtex-style"] = { + details = [[ +By default, amsrefs formats references using the AMS house style. The +`bibtex-style` option instructs it to use a format that is very +similar to the one implemented by the standard BibTeX styles (plain, +alpha, abbrv, and unsrt). +]] + }, + ["citation-order"] = { + details = [[ +This option applies only when using amsrefs in conjunction with +BibTeX. Consequently, changing this option will have no effect until +after the next bibtex run. + +The `citation-order` option corresponds to the standard BibTeX style +unsrt, where items are printed in the reference list in the order in +which they are cited in the document. +]] + }, + lite = { + details = [[ +Suppress the loading of the following packages, which amsrefs +will normally automatically load: + + - mathscinet: Define a number of special characters and accents that + are sometimes encountered when downloading data from MathSciNet. + + - txtcmds: Provide shorthand commands for a number of characters + that are usually specified via ligatures (e.g., -- for an en-dash + or ?` for ?. Using these ligatures can cause problems if you're + using fonts other than the Computer Modern Roman family or if you + want to make it easy to convert your document to, say, HTML. + LaTeX does provide macros for these characters, but their names + tend to be rather unwieldy (e.g., `\textendash` and + `\textquestiondown`, so txtcmds provides shorter names (`\ndash` + and `\qd` in this case). +]] + }, + ["msc-links"] = { + details = [[ +Redefine the `\MR` command to create hypertext links to the +MathSciNet database. This option will work only if the hyperref +package is installed. +]] + }, + nobysame = { + details = [[ +If two or more consecutive bibliography items have the same authors, +amsrefs will normally replace the author names in the second and +succeeding entries by a horizontal rule. This option disables this +feature, causing the full author names to always be printed. +]] + } + } +} +commands= { + bibselect = { + summary = "Read \\bib entries from an ltb file.", + action = "input", + filename = "?.ltb", + arguments = { + { + meta = "*", + summary = "If present, print all bibliography items, including not cited.", + optional = true, + type = "literal" + }, + { + meta = "files", + summary = "A list of files with ltb extension." + } + } + }, + bib = { + action = "amsrefs_bib", + summary = "Create a bibliogprahy item.", + arguments = { + { + meta = "label" + }, + { + meta = "type", + keys = { + article = { + details = [[ +A relatively short but self-contained item that is typically published +as part of a larger collection, such as a journal, a conference +proceedings, an edited collection published as a book, or even as part +of a World Wide Web document. +]] + }, + book = { + details = [[ +A written work by one or more authors where the authors share credit +for the work as a whole. For compatibility with BibTeX, the following +entry types are available as aliases for book: collection, +proceedings, manual, and unpublished. +]] + }, + misc = { + details = [[ +Anything that doesn’t fit into one of the other types. +]] + }, + report = { + details = [[ +A technical report, white paper, or the like. Similar to an article +but usually published and distributed by an organization such as a +university or corporation whose primary business is usually not +publishing. Also known as a techreport. +]] + }, + thesis = { + details = [[ +Like report but produced by the author for an educational institution +to satisfy the requirements for a degree. Not (normally) produced by +a commercial publisher for sale. +]] + }, + webpage = { + details = [[ +An online resource. It is limited to the following fields: accessdate, +author, date, note, subtitle, title, url. +]] + } + } + }, + { + meta = "fields", + keys = { + accessdate = { + details = [[ +Used to specify the date on which a webpage was viewed, as opposed to +the date on which the resource was last modified, which would be put +in the date field. +]] + }, + address = { + details = [[ +Usually the address of the publisher or other issuing organization, +but inside the conference compound field it refers to the address of +the conference. +]] + }, + booktitle = { + details = [[ +Used in the article type to specify the title of the book in which the +article appeared. If anything other than a simple book title is +required, the book compound field should be used instead. +]] + }, + date = { + details = [[ +Usually the date of publication, except inside the conference field, +where it is the date of the conference. + +This replaces BibTeX's year and month fields. Its value should be +written in ISO 8601 format, e.g., 1967-02-24. The day and/or month +can be omitted, so all of the following are valid representations of +February 24, 1967: +``` +date={1967-02-24} +date={1967-02} +date={1967} +``` +Using this format allows amsrefs maximum flexibility in formatting +dates, for example, by allowing month names to be printed in full or +abbreviated as necessary. + +For Winter, Spring, Summer, Fall, either use month numbers of 13, 14, +15, 16 (respectively) or just put in the text before the year: +``` +date={Summer 1987}, +``` +For compatibility, year is provided as an alias for date, but its use +is discouraged. +]] + }, + edition = { + details = [[ +For books or reports. If the value of this field is a simple number, +bib will convert it to cardinal form and add “ed.” (or alternative +text if specified by the bibliography style). Otherwise it will be +printed as is. +]] + }, + eprint = { + details = [[ +Electronic preprint information such as for . See + for recommended form. +]] + }, + hyphenation = { + details = [[ +This corresponds to the Babel package notion of language. The +hyphenation language used for a given bib entry is determined from +various clues, which are checked in the following order: + +- The Babel language specified by the hyphenation field. + +- The Babel language specified by the \emph{first word} of the + language field (after lowercasing). + +- The current Babel language that was in effect before the \cn{bib} + command started. + +- The current hyphenation patterns of the document, if there are no + Babel language modules loaded. + +The hyphenation field applies to an entire entry. To change the Babel +language for a single field, see the discussion of the language +attribute. +]] + }, + journal = {}, + label = { + details = [[ +When the alphabetic or shortalphabetic options are used, amsrefs will +usually try to generate the label on its own. If necessary, you can +override the automatically generated label by specifying a label +field. +]] + }, + language = { + details = [[ +Language of the work. The language name should be the printed form, +not a Babel-style language name, since in principle this field could +contain more complicated remarks such as “Russian, with French +abstract”. +]] + }, + note = { + details = [[ +Any additional information that does not fit into one of the other +fields. +]] + }, + number = { + details = [[ +The issue number of the journal for an article or the technical report +number for a report. +]] + }, + organization = { + details = [[ +The school, university, corporation, or other nonpublisher +organization that issued the document. +]] + }, + pages = {}, + part = {}, + publisher = {}, + series = {}, + setup = { + details = [[ +This is a special field that can be used to give arbitrary commands to +be executed at the beginning of the current bib entry, after all the +fields have been read. The idea is that one can alter the formatting +of an individual entry through this field to handle special cases. +]] + }, + status = { + details = [[ +Typically used for notes such as “to appear” or “in preparation” +or “unpublished” with journal articles. +]] + }, + subtitle = { + details = [[ +Typically used with a multipart journal article to give a subtitle for +each part, but it can also be used for books. +]] + }, + type = { + details = [[ +The type of a thesis, e.g., “Master's Thesis” or “Ph.D. Thesis”. +]] + }, + xref = { + }, + author = { + details = [[ +The authors of the item. If there are other contributors that should +be acknowledged, they should be listed in contribution fields. +]] + }, + editor = { + details = [[ +The editors of the item. If there are other contributors that should +be acknowledged, they should be listed in contribution fields. +]] + }, + translator = { + details = [[ +The translators of the item. If there are other contributors that +should be acknowledged, they should be listed in contribution fields. +]] + }, + isbn, issn = { + details = [[ +An International Standard Book or Serial Number. (These are not +printed by the standard styles, but are reserved for future use.) +]] + }, + review = { + details = [[ +A review number or similar pointer to, for example, Mathematical +Reviews or Zentralblatt. You must supply any special markup for the +number; i.e., you should write + + review={\MR{2015463}} + +instead of + + review={2015463} +]] + }, + book = { + details = [[ +This is used for conference articles to make it easier to +differentiate between an article and the book or proceedings that it +appeared in. The book field can contain any of the following +subfields: title, part, subtitle, edition, editor, translator, +contribution, series, volume, publisher, organization, address, date, +note. + +It is often used in conjunction with the conference field. +]] + }, + conference = { + details = [[ +The conference field can contain a title, address, and date. + + \bib{Burkholder1986a}{article}{ + author={Burkholder, Donald L.}, + title={Martingales and Fourier analysis in Banach spaces}, + conference={ + title={C.I.M.E. Lectures}, + address={Varenna, Italy}, + date={1985} + }, + book={ + series={Lecture Notes in Math.}, + volume={1206}, + publisher={Springer-Verlag}, + address={Berlin and New York}, + date={1986}, + }, + pages={61--108}, + review={\MR{0864712}} + } +]] + }, + contribution = { + details = [[ +This field can be repeated as many times as necessary to list any +contributors other than authors, editors, or translators. + + contribution={ + type={illustrations}, + author={Gorey, Edward} + } + +which in the default style produces + + with illustrations by Edward Gorey + +Since contributions are potentially complicated, so is the +contribution field: + +- Sometimes it is necessary to add additional material to the type in + order to produce intelligible text: + + contribution={ + type={an appendix}, + author={Doe, John} + } + +- amsrefs tries very hard to format multiple contributions, each of + which may have multiple authors, in an appropriate way. However, + there might be cases where the default rules aren't flexible enough, + in which case you can instead use the contribution field as a simple + field and format it exactly the way you want: + + contribution={some arbitrary text about contributions} + +This feature should only be used as a last resort, though. +]] + }, + partial = { + details = [[ +This is used with the article type for multipart articles. Like the +contribution field, it is repeatable. It can contain any of the +following fields: part, subtitle, contribution, journal, volume, date, +number, pages. + + \bib{Zho-fan1972}{article}{ + author={Zho-fan, Z.}, + title={Monomials}, + partial={ + part={I}, + journal={Tot. Math.}, + volume={19}, + date={1972}, + pages={335--350} + }, + partial={ + part={II}, + journal={Tot. Math.}, + volume={20}, + date={1973}, + pages={19--37} + } + } +]] + }, + reprint = { + details = [[ +This can be used inside an article to indicate another place (usually +a book) where the article can also be found. It can contain any field +that the book type can. + + \bib{Sokal96}{article}{ + title={Trangressing the boundaries}, + subtitle={Toward a transformative hermeneutics of quantum + gravity}, + author={Sokal, Alan}, + journal={Social Text}, + volume={46/47}, + date={1996}, + pages={217--252}, + reprint={ + title={Fashionable Nonsense}, + subtitle={Postmodern Intellectuals' Abuse of Science}, + author={Sokal, Alan}, + author={Bricmont, Jean}, + publisher={Picador USA}, + address={New York}, + date={1998} + } + } +]] + }, + translation = { + details = [[ +This is the only compound field that can be used with any bibliography +type. It can contain any field that its parent type can contain. +]] + } + } + } + } + }, + citelist = { + details = [[ +This is used to group a number of individual `\cite` commands into a +single citation. Among other things, this makes it possible to add an +optional argument to any of the `\cite` commands unambiguously: + + \citelist{\cite{xx} \cite{yy}*{Theorem 4.9} \cite{zz}} + +Note that there is no punctuation or other text between the `\cite +commands. Any necessary commas or other punctuation will be supplied +automatically. Any attempts to supply it by hand will backfire. +]] + }, + cites = { + action = "cite", + arguments = {{meta = "labels"}}, + details = [[ +This is a variant of citelist, provided for convenience: + + \cites{aa,bb,cc} + +is equivalent to + + \citelist{\cite{aa}\cite{bb}\cite{cc}} + +Note that cites does not take an optional arguments. +]] + }, + nocite = { + action = "cite", + arguments = {{meta = "labels"}}, + details = [[ +This continues to work the same way that it does in standard LaTeX +when used with BibTeX, but see the manual for limitations when it is +used with bibselect and ltb files. +]] + }, + ocite = { + action = "cite", + arguments = {{meta = "label"}}, + summary = "Cite as an object.", + action = "cite" + }, + ycite = { + action = "cite", + arguments = {{meta = "label"}}, + summary = "Cite year.", + action = "cite", + }, + DefineName = { + arguments = { + {meta = "label"}, + {meta = "text"} + } + }, + DefinePublisher = { + arguments = { + {meta = "label"}, + {meta = "text"} + } + }, + DefineJournal = { + arguments = { + {meta = "label"}, + {meta = "text"} + } + } +} +environments = { + bibdiv = {}, + biblist = {} +} diff --git a/support/digestif/data/amssymb.sty.tags b/support/digestif/data/amssymb.sty.tags new file mode 100644 index 0000000000..c7b19b5a3c --- /dev/null +++ b/support/digestif/data/amssymb.sty.tags @@ -0,0 +1,677 @@ +-- Copyright 2006-2019 Will Robertson +-- Copyright 2010-2017 Philipp Stephani +-- Copyright 2011-2017 Joseph Wright +-- Copyright 2012-2015 Khaled Hosny +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c+ +-- +-- Adapted from the file unicode-math-table.tex, part of the +-- unicode-math package, which can be found at +-- https://ctan.org/pkg/unicode-math. +ctan_package = "amsfonts" +commands = { + Bbbk = { + summary = "mathematical double-struck small k", + symbol = "𝕜" + }, + Bumpeq = { + summary = "bumpy equals", + symbol = "≎" + }, + Cap = { + summary = "/cap /doublecap b: double intersection", + symbol = "⋒" + }, + Cup = { + summary = "/cup /doublecup b: double union", + symbol = "⋓" + }, + Doteq = { + summary = "/doteqdot /doteq r: equals, even dots", + symbol = "≑" + }, + Finv = { + summary = "turned capital f", + symbol = "Ⅎ" + }, + Game = { + summary = "turned sans-serif capital g", + symbol = "⅁" + }, + Lleftarrow = { + summary = "left triple arrow", + symbol = "⇚" + }, + Lsh = { + summary = "/lsh a:", + symbol = "↰" + }, + Rrightarrow = { + summary = "right triple arrow", + symbol = "⇛" + }, + Rsh = { + summary = "/rsh a:", + symbol = "↱" + }, + Subset = { + summary = "double subset", + symbol = "⋐" + }, + Supset = { + summary = "double superset", + symbol = "⋑" + }, + Vdash = { + summary = "double vertical, dash", + symbol = "⊩" + }, + Vvdash = { + summary = "triple vertical, dash", + symbol = "⊪" + }, + approxeq = { + summary = "approximate, equals", + symbol = "≊" + }, + backprime = { + summary = "reverse prime, not superscripted", + symbol = "‵" + }, + backsim = { + summary = "reverse similar", + symbol = "∽" + }, + backsimeq = { + summary = "reverse similar, equals", + symbol = "⋍" + }, + barwedge = { + summary = "bar, wedge (large wedge)", + symbol = "⊼" + }, + because = { + summary = "because", + symbol = "∵" + }, + beth = { + summary = "beth, hebrew", + symbol = "ℶ" + }, + between = { + summary = "between", + symbol = "≬" + }, + bigstar = { + summary = "star, filled", + symbol = "★" + }, + blacktriangle = { + summary = "up triangle, filled", + symbol = "▴" + }, + blacktriangledown = { + summary = "down triangle, filled", + symbol = "▾" + }, + blacktriangleleft = { + summary = "(large) left triangle, filled", + symbol = "◀" + }, + blacktriangleright = { + summary = "(large) right triangle, filled", + symbol = "▶" + }, + boxdot = { + summary = "/dotsquare /boxdot b: small dot in box", + symbol = "⊡" + }, + boxminus = { + summary = "minus sign in box", + symbol = "⊟" + }, + boxplus = { + summary = "plus sign in box", + symbol = "⊞" + }, + boxtimes = { + summary = "multiply sign in box", + symbol = "⊠" + }, + bumpeq = { + summary = "bumpy equals, equals", + symbol = "≏" + }, + circeq = { + summary = "circle, equals", + symbol = "≗" + }, + circledast = { + summary = "asterisk in circle", + symbol = "⊛" + }, + circledcirc = { + summary = "small circle in circle", + symbol = "⊚" + }, + circleddash = { + summary = "hyphen in circle", + symbol = "⊝" + }, + complement = { + summary = "complement sign", + symbol = "∁" + }, + curlyeqprec = { + summary = "curly equals, precedes", + symbol = "⋞" + }, + curlyeqsucc = { + summary = "curly equals, succeeds", + symbol = "⋟" + }, + curlyvee = { + summary = "curly logical or", + symbol = "⋎" + }, + curlywedge = { + summary = "curly logical and", + symbol = "⋏" + }, + curvearrowleft = { + summary = "left curved arrow", + symbol = "↶" + }, + curvearrowright = { + summary = "right curved arrow", + symbol = "↷" + }, + daleth = { + summary = "daleth, hebrew", + symbol = "ℸ" + }, + divideontimes = { + summary = "division on times", + symbol = "⋇" + }, + dotplus = { + summary = "plus sign, dot above", + symbol = "∔" + }, + doublebarwedge = { + summary = "logical and with double overbar", + symbol = "⩞" + }, + downdownarrows = { + summary = "two down arrows", + symbol = "⇊" + }, + downharpoonleft = { + summary = "down harpoon-left", + symbol = "⇃" + }, + downharpoonright = { + summary = "down harpoon-right", + symbol = "⇂" + }, + eqcirc = { + summary = "circle on equals sign", + symbol = "≖" + }, + eqsim = { + summary = "equals, similar", + symbol = "≂" + }, + eqslantgtr = { + summary = "slanted equal to or greater-than", + symbol = "⪖" + }, + eqslantless = { + summary = "slanted equal to or less-than", + symbol = "⪕" + }, + fallingdotseq = { + summary = "equals, falling dots", + symbol = "≒" + }, + geqq = { + summary = "greater, double equals", + symbol = "≧" + }, + geqslant = { + summary = "greater-than or slanted equal to", + symbol = "⩾" + }, + ggg = { + summary = "/ggg /gg /gggtr r: triple greater-than", + symbol = "⋙" + }, + gimel = { + summary = "gimel, hebrew", + symbol = "ℷ" + }, + gnapprox = { + summary = "greater-than and not approximate", + symbol = "⪊" + }, + gneq = { + summary = "greater-than and single-line not equal to", + symbol = "⪈" + }, + gneqq = { + summary = "greater, not double equals", + symbol = "≩" + }, + gnsim = { + summary = "greater, not similar", + symbol = "⋧" + }, + gtrapprox = { + summary = "greater-than or approximate", + symbol = "⪆" + }, + gtrdot = { + summary = "greater than, with dot", + symbol = "⋗" + }, + gtreqless = { + summary = "greater, equals, less", + symbol = "⋛" + }, + gtreqqless = { + summary = "greater-than above double-line equal above less-than", + symbol = "⪌" + }, + gtrless = { + summary = "greater, less", + symbol = "≷" + }, + gtrsim = { + summary = "greater, similar", + symbol = "≳" + }, + hslash = { + summary = "/hslash - variant planck's over 2pi", + symbol = "ℏ" + }, + intercal = { + summary = "intercal", + symbol = "⊺" + }, + leftarrowtail = { + summary = "left arrow-tailed", + symbol = "↢" + }, + leftleftarrows = { + summary = "two left arrows", + symbol = "⇇" + }, + leftrightarrows = { + summary = "left arrow over right arrow", + symbol = "⇆" + }, + leftrightharpoons = { + summary = "left harpoon over right", + symbol = "⇋" + }, + leftrightsquigarrow = { + summary = "left and right arr-wavy", + symbol = "↭" + }, + leftthreetimes = { + summary = "left semidirect product", + symbol = "⋋" + }, + leqq = { + summary = "less, double equals", + symbol = "≦" + }, + leqslant = { + summary = "less-than or slanted equal to", + symbol = "⩽" + }, + lessapprox = { + summary = "less-than or approximate", + symbol = "⪅" + }, + lessdot = { + summary = "less than, with dot", + symbol = "⋖" + }, + lesseqgtr = { + summary = "less, equals, greater", + symbol = "⋚" + }, + lesseqqgtr = { + summary = "less-than above double-line equal above greater-than", + symbol = "⪋" + }, + lessgtr = { + summary = "less, greater", + symbol = "≶" + }, + lesssim = { + summary = "less, similar", + symbol = "≲" + }, + lll = { + summary = "/ll /lll /llless r: triple less-than", + symbol = "⋘" + }, + lnapprox = { + summary = "less-than and not approximate", + symbol = "⪉" + }, + lneq = { + summary = "less-than and single-line not equal to", + symbol = "⪇" + }, + lneqq = { + summary = "less, not double equals", + symbol = "≨" + }, + lnsim = { + summary = "less, not similar", + symbol = "⋦" + }, + looparrowleft = { + summary = "left arrow-looped", + symbol = "↫" + }, + looparrowright = { + summary = "right arrow-looped", + symbol = "↬" + }, + ltimes = { + summary = "times sign, left closed", + symbol = "⋉" + }, + measuredangle = { + summary = "angle-measured", + symbol = "∡" + }, + multimap = { + summary = "/multimap a:", + symbol = "⊸" + }, + nLeftarrow = { + summary = "not implied by", + symbol = "⇍" + }, + nLeftrightarrow = { + summary = "not left and right double arrows", + symbol = "⇎" + }, + nRightarrow = { + summary = "not implies", + symbol = "⇏" + }, + nVDash = { + summary = "not double vert, double dash", + symbol = "⊯" + }, + nVdash = { + summary = "not double vertical, dash", + symbol = "⊮" + }, + ncong = { + summary = "not congruent with", + symbol = "≇" + }, + nexists = { + summary = "negated exists", + symbol = "∄" + }, + ngeq = { + summary = "not greater-than-or-equal", + symbol = "≱" + }, + ngtr = { + summary = "not greater-than", + symbol = "≯" + }, + nleftarrow = { + summary = "not left arrow", + symbol = "↚" + }, + nleftrightarrow = { + summary = "not left and right arrow", + symbol = "↮" + }, + nleq = { + summary = "not less-than-or-equal", + symbol = "≰" + }, + nless = { + summary = "not less-than", + symbol = "≮" + }, + nmid = { + summary = "negated mid", + symbol = "∤" + }, + nparallel = { + summary = "not parallel", + symbol = "∦" + }, + nprec = { + summary = "not precedes", + symbol = "⊀" + }, + nrightarrow = { + summary = "not right arrow", + symbol = "↛" + }, + nsim = { + summary = "not similar", + symbol = "≁" + }, + nsubseteq = { + summary = "not subset, equals", + symbol = "⊈" + }, + nsucc = { + summary = "not succeeds", + symbol = "⊁" + }, + nsupseteq = { + summary = "not superset, equals", + symbol = "⊉" + }, + ntrianglelefteq = { + summary = "not left triangle, equals", + symbol = "⋬" + }, + ntrianglerighteq = { + summary = "not right triangle, equals", + symbol = "⋭" + }, + nvDash = { + summary = "not vertical, double dash", + symbol = "⊭" + }, + nvdash = { + summary = "not vertical, dash", + symbol = "⊬" + }, + pitchfork = { + summary = "pitchfork", + symbol = "⋔" + }, + precapprox = { + summary = "precedes above almost equal to", + symbol = "⪷" + }, + preccurlyeq = { + summary = "precedes, curly equals", + symbol = "≼" + }, + precnapprox = { + summary = "precedes above not almost equal to", + symbol = "⪹" + }, + precneqq = { + summary = "precedes above not equal to", + symbol = "⪵" + }, + precnsim = { + summary = "precedes, not similar", + symbol = "⋨" + }, + precsim = { + summary = "precedes, similar", + symbol = "≾" + }, + rightarrowtail = { + summary = "right arrow-tailed", + symbol = "↣" + }, + rightleftarrows = { + summary = "right arrow over left arrow", + symbol = "⇄" + }, + rightrightarrows = { + summary = "two right arrows", + symbol = "⇉" + }, + rightsquigarrow = { + summary = "rightwards squiggle arrow", + symbol = "⇝" + }, + rightthreetimes = { + summary = "right semidirect product", + symbol = "⋌" + }, + risingdotseq = { + summary = "equals, rising dots", + symbol = "≓" + }, + rtimes = { + summary = "times sign, right closed", + symbol = "⋊" + }, + smallsetminus = { + summary = "small set minus (cf. reverse solidus)", + symbol = "∖" + }, + sphericalangle = { + summary = "angle-spherical", + symbol = "∢" + }, + subseteqq = { + summary = "subset of above equals sign", + symbol = "⫅" + }, + subsetneq = { + summary = "subset, not equals", + symbol = "⊊" + }, + subsetneqq = { + summary = "subset of above not equal to", + symbol = "⫋" + }, + succapprox = { + summary = "succeeds above almost equal to", + symbol = "⪸" + }, + succcurlyeq = { + summary = "succeeds, curly equals", + symbol = "≽" + }, + succnapprox = { + summary = "succeeds above not almost equal to", + symbol = "⪺" + }, + succneqq = { + summary = "succeeds above not equal to", + symbol = "⪶" + }, + succnsim = { + summary = "succeeds, not similar", + symbol = "⋩" + }, + succsim = { + summary = "succeeds, similar", + symbol = "≿" + }, + supseteqq = { + summary = "superset of above equals sign", + symbol = "⫆" + }, + supsetneq = { + summary = "superset, not equals", + symbol = "⊋" + }, + supsetneqq = { + summary = "superset of above not equal to", + symbol = "⫌" + }, + therefore = { + summary = "therefore", + symbol = "∴" + }, + triangledown = { + summary = "down triangle, open", + symbol = "▿" + }, + trianglelefteq = { + summary = "left triangle, equals", + symbol = "⊴" + }, + triangleq = { + summary = "triangle, equals", + symbol = "≜" + }, + trianglerighteq = { + summary = "right triangle, equals", + symbol = "⊵" + }, + twoheadleftarrow = { + summary = "left two-headed arrow", + symbol = "↞" + }, + twoheadrightarrow = { + summary = "right two-headed arrow", + symbol = "↠" + }, + upharpoonleft = { + summary = "up harpoon-left", + symbol = "↿" + }, + upharpoonright = { + summary = "/upharpoonright /restriction a: up harpoon-right", + symbol = "↾" + }, + upuparrows = { + summary = "two up arrows", + symbol = "⇈" + }, + vDash = { + summary = "vertical, double dash", + symbol = "⊨" + }, + varkappa = { + summary = "rounded small kappa, greek", + symbol = "ϰ" + }, + varnothing = { + summary = "circle, slash", + symbol = "∅" + }, + vartriangle = { + summary = "/triangle - up triangle, open", + symbol = "▵" + }, + vartriangleleft = { + summary = "left triangle, open, variant", + symbol = "⊲" + }, + vartriangleright = { + summary = "right triangle, open, variant", + symbol = "⊳" + }, + veebar = { + summary = "logical or, bar below (large vee); exclusive disjunction", + symbol = "⊻" + } +} diff --git a/support/digestif/data/biblatex.sty.tags b/support/digestif/data/biblatex.sty.tags new file mode 100644 index 0000000000..a99a80fe65 --- /dev/null +++ b/support/digestif/data/biblatex.sty.tags @@ -0,0 +1,7982 @@ +-- Copyright 2006-2012 Philipp Lehman +-- Copyright 2012-2022 Philipp Lehman, Joseph Wright, Audrey Boruvka, +-- Philip Kime +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c +-- +-- Adapted from the biblatex package documentation, which can be found +-- at https://github.com/plk/biblatex. +ctan_package = "biblatex" +dependencies = { + "blx-case-expl3.sty", + "blx-case-latex2e.sty", + "etexcmds.sty", + "etoolbox.sty", + "expl3.sty", + "iftex.sty", + "ifthen.sty", + "infwarerr.sty", + "keyval.sty", + "kvoptions-patch.sty", + "kvoptions.sty", + "kvsetkeys.sty", + "logreq.sty", + "ltxcmds.sty", + "pdftexcmds.sty", + "url.sty", + "xparse.sty" +} +commands = { + AtBeginBibliography = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtBeginBibliography{code} +``` + +Appends the `code` to an internal hook executed at the beginning of the +bibliography. The `code` is executed at the beginning of the list of +references, immediately after the `begin code` of `\defbibenvironment`. +This command may only be used in the preamble. +]] + }, + AtBeginBiblist = { + arguments = {{meta = "biblistname"}, {meta = "code"}}, + details = [[ +```latex +\AtBeginBiblist{biblistname}{code} +``` + +Appends the `code` to an internal hook executed at the beginning of the +bibliography list `biblistname`. The `code` is executed at the beginning +of the bibliography list, immediately after the `begin code` of +`\defbibenvironment`. This command may only be used in the preamble. +]] + }, + AtEveryCitekey = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtEveryCitekey{code} +``` + +Appends the `code` to an internal hook executed once for every entry key +passed to a citation command. The `code` is executed immediately before +the `loopcode` of the command (see ??). The bibliographic data of the +respective entry is available at this point. This command may only be +used in the preamble. +]] + }, + AtEveryEntrykey = { + arguments = {{meta = "code"}, {meta = "success"}, {meta = "failure"}}, + details = [[ +```latex +\AtEveryEntrykey{code}{success}{failure} +``` + +Appends `code` to an internal hook executed every time an entrykey is +processed for a citation command or `\nocite`. The `code` is passed one +argument (`#1`), which contains the entrykey. If the code can be +appended to the hook `success` is executed, otherwise `failure` is +executed. Unlike `\AtEveryCitekey` the entry data of the current +entrykey is not available when `code` is processed, indeed it is not +even known whether or not there is any entry data at all. +]] + }, + AtEveryLositem = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtEveryLositem{code} +``` + +Appends the `code` to an internal hook executed at the beginning of +every item in the list of shorthands. The `code` is executed immediately +after the `item code` of `\defbibenvironment`. The bibliographic data of +the respective entry is available at this point. This command may only +be used in the preamble. + +This is just an alias for: + + \AtEveryBiblistitem{shorthand}{code} +]] + }, + AtNextBibliography = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtNextBibliography{code} +``` + +Similar to `\AtBeginBibliography` but only affecting the next +`\printbibliography`. The internal hook is cleared after being executed +once. This command may be used in the document body. +]] + }, + AtNextCite = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtNextCite{code} +``` + +Similar to `\AtEveryCite` but only affecting the next citation command. +The internal hook is cleared after being executed once. This command may +be used in the document body. +]] + }, + AtNextCitekey = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AtNextCitekey{code} +``` + +Similar to `\AtEveryCitekey` but only affecting the next entry key. The +internal hook is cleared after being executed once. This command may be +used in the document body. +]] + }, + AtUsedriver = { + arguments = {{literal = "*", optional = true}, {meta = "code"}}, + details = [[ +```latex +\AtUsedriver*{code} +``` + +Appends the `code` to an internal hook executed when initializing +`\usedriver`. The starred variant of the command clears the +initialisation hook, so the defaults can be overwritten. This command +may only be used in the preamble. The default setting is: + + \AtUsedriver{% + \delimcontext{bib}% + \let\finentry\blx@finentry@usedrv + \let\newblock\relax + \let\abx@macro@bibindex\@empty + \let\abx@macro@pageref\@empty} +]] + }, + AtVolcite = { + arguments = {{literal = "*", optional = true}, {meta = "code"}}, + details = [[ +```latex +\AtVolcite{code} +\AtVolcite*{code} +``` + +Appends the `code` to an internal hook executed when initializing +`\volcite`. The starred variant of the command clears the initialisation +hook, so the defaults can be overwritten. This command may only be used +in the preamble. The default setting is: + + \AtVolcite{% + \DeclareFieldAlias{postnote}{volcitenote}} +]] + }, + Autocite = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\autocite[prenote][postnote]{key} +\Autocite[prenote][postnote]{key} +``` + +In contrast to other citation commands, the `\autocite` command does not +only scan ahead for punctuation marks following its last argument to +avoid double punctuation marks, it actually moves them around if +required. For example, with `autocite=footnote`, a trailing punctuation +mark will be moved such that the footnote mark is printed after the +punctuation. `\Autocite` is similar to `\autocite` but capitalizes the +name prefix of the first name in the citation if the `useprefix` option +is enabled, provided that there is a name prefix and the citation style +prints any name at all. + +```latex +\Autocite*[prenote][postnote]{key} +``` + +The starred variants of `\autocite` do not behave differently from the +regular ones. The asterisk is simply passed on to the backend command. +For example, if `\autocite` is configured to use `\parencite`, then +`\autocite*` will execute `\parencite*`. +]] + }, + Autocites = { + action = "cite", + details = [[ +```latex +\Autocites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +This is the multicite version of `\autocite`. It also detects and moves +punctuation if required. Note that there is no starred variant. +`\Autocites` is similar to `\autocites` but capitalizes the name prefix +of the first name in the citation if the `useprefix` option is enabled, +provided that there is a name prefix and the citation style prints any +name at all. +]] + }, + Avolcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Avolcite[prenote]{volume}[pages]{key} +``` + +Similar to `\volcite` but based on `\autocite`. +]] + }, + Avolcites = { + action = "cite", + details = [[ +```latex +\Avolcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\avolcite` and `\Avolcite`, respectively. +]] + }, + Cite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\cite[prenote][postnote]{key} +\Cite[prenote][postnote]{key} +``` + +These are the bare citation commands. They print the citation without +any additions such as parentheses. The numeric and alphabetic styles +still wrap the label in square brackets since the reference may be +ambiguous otherwise. `\Cite` is similar to `\cite` but capitalizes the +name prefix of the first name in the citation if the `useprefix` option +is enabled, provided that there is a name prefix and the citation style +prints any name at all. +]] + }, + Citeauthor = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\citeauthor[prenote][postnote]{key} +\citeauthor*[prenote][postnote]{key} +\Citeauthor[prenote][postnote]{key} +\Citeauthor*[prenote][postnote]{key} +``` + +These commands print the authors. Strictly speaking, it prints the +`labelname` list, which may be the `author`, the `editor`, or the +`translator`. `\Citeauthor` is similar to `\citeauthor` but capitalizes +the name prefix of the first name in the citation if the `useprefix` +option is enabled, provided that there is a name prefix. The starred +variants effectively force maxcitenames to 1 for just this command on so +only print the first name in the labelname list (potentially followed by +the «et al» string if there are more names). This allows more natural +textual flow when refering to a paper in the singular when otherwise +`\citeauthor` would generate a (naturally plural) list of names. +]] + }, + Cites = { + action = "cite", + details = [[ +```latex +\cites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +\Cites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +The multicite version of `\cite` and `\Cite`, respectively. +]] + }, + DeclareBabelToExplLanguageMapping = { + arguments = {{meta = "babel language"}, {meta = "expl language"}}, + details = [[ +```latex +\DeclareBabelToExplLanguageMapping{babel language}{expl language} +``` + +This command is only available if the `expl3` case changing code is +used. + +Use `expl language` as `language` argument for the `l3text` case +changing functions when `babel language` is active. This command is only +required if `babel language` should correspond to a language for which +`l3text` has special rules set up. The default invocations of this +command are + + \DeclareBabelToExplLanguageMapping{dutch}{nl} + \DeclareBabelToExplLanguageMapping{greek}{el} + \DeclareBabelToExplLanguageMapping{turkish}{tr} +]] + }, + DeclareBibliographyCategory = { + arguments = {{meta = "category"}}, + details = [[ +```latex +\DeclareBibliographyCategory{category} +``` + +Declares a new `category`, to be used in conjunction with +`\addtocategory` and the `category` and `notcategory` filters of +`\printbibliography`. This command is used in the document preamble. +]] + }, + DeclareBibliographyDriver = { + arguments = {{meta = "entrytype"}, {meta = "code"}}, + details = [[ +```latex +\DeclareBibliographyDriver{entrytype}{code} +``` + +Defines a bibliography driver. A <driver> is a macro which handles a +specific entry type (when printing bibliography lists) or a specific +named bibliography list (when printing bibliography lists). The +`entrytype` corresponds to the entry type used in `bib` files, specified +in lowercase letters (see ??). The `entrytype` argument may also be an +asterisk. In this case, the driver serves as a fallback which is used if +no specific driver for the entry type has been defined. The `code` is +arbitrary code which typesets all bibliography entries of the respective +`entrytype`. This command is mandatory. Every bibliography style should +provide a driver for each entry type. +]] + }, + DeclareBibliographyExtras = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\DeclareBibliographyExtras{code} +``` + +This command is only available in `lbx` files. It is used to adapt +language specific features such as the date format and ordinals. The +`code`, which may be arbitrary LaTeX code, will usually consist of +redefinitions of the formatting commands from ??. +]] + }, + DeclareBibliographyOption = { + arguments = { + {delimiters = {"[", "]"}, meta = "datatype", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "value", optional = true}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareBibliographyOption[datatype]{key}[value]{code} +``` +]] + }, + DeclareBibliographyStrings = { + arguments = {{meta = "definitions"}}, + details = [[ +```latex +\DeclareBibliographyStrings{definitions} +``` + +This command is only available in `lbx` files. It is used to define +localisation strings. The `definitions` consist of `key=value`pairs +which assign an expression to an identifier. A complete list of all keys +supported by default is given is ??. Note that the syntax of the value +is different in `lbx` files. The value assigned to a key consists of two +expressions, each of which is wrapped in an additional pair of brackets. +This is best shown by example: + + \DeclareBibliographyStrings{% + bibliography = {{Bibliography}{Bibliography}}, + shorthands = {{List of Abbreviations}{Abbreviations}}, + editor = {{editor}{ed.}}, + editors = {{editors}{eds.}}, + } + +The first value is the long, written out expression, the second one is +an abbreviated or short form. Both strings must always be given even +though they may be identical if an expression is always (or never) +abbreviated. Depending on the setting of the `abbreviate` package option +(see ??), `biblatex`selects one expression when loading the `lbx` file. +There is also a special key named `inherit` which copies the strings +from a different language. This is intended for languages which only +differ in a few expressions, such as German and Austrian or American and +British English. For example, here are the complete definitions for +Austrian: + + \DeclareBibliographyStrings{% + inherit = {german}, + january = {{J\"anner}{J\"an.}}, + } + +The above examples are slightly simplified. Real localisation files +should use the punctuation and formatting commands discussed in ?? +instead of literal punctuation. Here is an excerpt from a real +localisation file: + + bibliography = {{Bibliography}{Bibliography}}, + shorthands = {{List of Abbreviations}{Abbreviations}}, + editor = {{editor}{ed\adddot}}, + editors = {{editors}{eds\adddot}}, + byeditor = {{edited by}{ed\adddotspace by}}, + mathesis = {{Master's thesis}{MA\addabbrvspace thesis}}, + +Note the handling of abbreviation dots, the spacing in abbreviated +expressions, and the capitalization in the example above. All +expressions should be capitalized as they usually are when used in the +middle of a sentence. The `biblatex`package will automatically +capitalize the first word when required at the beginning of a sentence, +see `\DeclareCapitalPunctuation` in ?? for details. Expressions intended +for use in headings are special. They should be capitalized in a way +that is suitable for titling and should not be abbreviated (but they may +have a short form). +]] + }, + DeclareBiblistFilter = { + arguments = {{meta = "name"}, {meta = "specification"}}, + details = [[ +```latex +\DeclareBiblistFilter{name}{specification} +``` + +Defines a bibliography list filter with `name`. The `specification` +consists of one or more `\filter` or `\filteror` macros, all of which +must be satisfied for the entry to pass the filter: +]] + }, + DeclareBibstringSet = { + arguments = {{meta = "setname"}, {meta = "key, ... "}}, + details = [[ +```latex +\DeclareBibstringSet{setname}{key, ... } +``` + +This commands assigns all `key`s to the bibliography string set +`setname`. +]] + }, + DeclareCapitalPunctuation = { + arguments = {{meta = "characters"}}, + details = [[ +```latex +\DeclareCapitalPunctuation{characters} +``` + +When `biblatex`inserts localisation strings, i.e. key terms such as +<edition> or <volume>, it automatically capitalizes them after +terminal punctuation marks. This command defines the punctuation marks +which will cause localisation strings to be capitalized if one of them +precedes a string. Note that `characters` is an undelimited list of +characters. Valid `characters` are period, comma, semicolon, colon, +exclamation and question mark. The package default is: + + \DeclareCapitalPunctuation{.!?} + +Using `\DeclareCapitalPunctuation` with an empty argument is equivalent +to disabling automatic capitalization. Since this feature is language +specific, this command must be used in the argument to +`\DefineBibliographyExtras` (when used in the preamble) or +`\DeclareBibliographyExtras` (when used in a localisation module). See +?? for details. By default, strings are capitalized after periods, +exclamation marks, and question marks. All strings are generally +capitalized at the beginning of a paragraph (in fact whenever TeX is in +vertical mode). +]] + }, + DeclareCaseLangs = { + arguments = {{literal = "*", optional = true}, {meta = "languages"}}, + details = [[ +```latex +\DeclareCaseLangs{languages} +\DeclareCaseLangs*{languages} +``` + +Defines the list of languages which are considered by the +`\MakeSentenceCase*` command as it converts a string to sentence case. +The `languages` argument is a comma-separated list of +`babel`/`polyglossia` language identifiers. The regular version of this +command replaces the current setting, the starred version appends its +argument to the current list. The default setting is: + + \DeclareCaseLangs{% + american,british,canadian,english,australian,newzealand,USenglish,UKenglish} + +See the `babel`/`polyglossia` manuals and ?? for a list of languages +identifiers. +]] + }, + DeclareCitePunctuationPosition = { + arguments = {{meta = "command"}, {meta = "position"}}, + details = [[ +```latex +\DeclareCitePunctuationPosition{command}{position} +``` + +Set up the cite command `command` to move punctuation marks after the +citation like `\autocite`. The `position` argument can take the values +`r`, `l`, `f`, `c`, `o` and `d`. If an unknown `position` identifier is +used, it defaults to `o`. + +r +The punctuation mark is not moved and remains to the right of the +citation. + +l +The punctuation mark is moved to the left of the citation and thus +appears before it. + +f +Like `r` in footnotes and like `l` otherwise. + +c +Pass the punctuation on to the internal implementation of the citation +commands. It will then be executed within the `wrapper` command if +given. + +o +Retain the default setup of `c` for citation defined commands without +`wrapper` command and `l` for citation commands defined with a `wrapper` +command. + +d +Drop the explicit punctuation mark. It will only be available as the +field `postpunct`. + +This command can not be used for `\autocite`, to configure `\autocite` +use the optional `position` argument for `\DeclareAutoCiteCommand`. +]] + }, + DeclareDataInheritance = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "source, ... "}, + {meta = "target, ... "}, + {meta = "rules"} + }, + details = [[ +```latex +\DeclareDataInheritance[options]{source, ... }{target, ... }{rules} +``` + +Declares inheritance rules. The `source` and `target` arguments specify +the parent and the child entry type. Either argument may be a single +entry type, a comma-separated list of types, or an asterisk. The +asterisk matches all entry types. The `rules` are an undelimited list of +`\inherit` and/or `\noinherit` directives. Spaces, tabs, and line +endings may be used freely to visually arrange the `rules`. Blank lines +are not permissible. This command may only be used in the preamble. The +options are: + +`ignore=` +As the `ignore` option on `\DefaultInheritance` explained above. When +set here, it takes precedence over any global options set with +`\DefaultInheritance`. For example, this would ignore `singletitle` and +`uniquetitle` tracking for a `book` inheriting from a `mvbook`. + + \DeclareDataInheritance[ignore={singletitle,uniquetitle}]{mvbook}{book}{<<...>>} +]] + }, + DeclareDatafieldSet = { + arguments = {{meta = "name"}, {meta = "specification"}}, + details = [[ +```latex +\DeclareDatafieldSet{name}{specification} +``` + +Declare a set of datasource fields with name `name`. + +`name=` +The name of the set. + +The `specification` is one or more `\member` items: +]] + }, + DeclareDatamodelConstant = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "name"}, + {meta = "constantdef"} + }, + details = [[ +```latex +\DeclareDatamodelConstant[options]{name}{constantdef} +``` + +Declares the `name` as a datamodel constant with definition +`constantdef`. Such constants are typically used internally by `biber`. + +`type={string, list}` +A constant can be a simple string (default if the `type` option is +omitted) or a comma-separated list of strings. +]] + }, + DeclareDatamodelConstraints = { + arguments = { + {delimiters = {"[", "]"}, meta = "entrytypes", optional = true}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareDatamodelConstraints[entrytypes]{specification} +``` + +If a comma-separated list of `entrytypes` is given, the constraints +apply only to those entrytypes. The `specification` is an undelimited +list of `\constraint` directives which specify a constraint. Spaces, +tabs, and line endings may be used freely to visually arrange the +`specification`. Blank lines are not permissible. +]] + }, + DeclareDatamodelFields = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "fields"} + }, + details = [[ +```latex +\DeclareDatamodelFields[options]{fields} +``` + +Declares the comma-separated list of `fields` to be valid fields in the +data model with associated comma-separated `options`. The `type` and +`datatype` options are mandatory. All valid `options` are: + +`type=` +Set the type of the field as described in ??, typically <field> or +<list>. + +`format=` +Any special format of the field. Normally unspecified but can take the +value <xsv> which tells `biber`that this field has a separated values +format. The exact separator can be controlled with the `biber`option +`xsvsep` and defaults to the expected comma surrounded by optional +whitespace. + +`datatype=` +Set the datatype of the field as described in ??. For example, <name> +or <literal>. + +`nullok` +The field is allowed to be defined but empty. + +`skipout` +The field is not output to the `.bbl` and is therefore not present +during `biblatex`style processing. As usual in TeX csv lists, make sure +each element is immediately followed by a comma or the closing +brace---no extraneous whitespace. + +`label` +The field can be used as a label in a bibliography or bibliography list. +Specifying this causes `biblatex`to create several helper macros for the +field so that there are some internal lengths and headings etc. defined. +]] + }, + DeclareDelimAlias = { + arguments = { + {literal = "*", optional = true}, + { + delimiters = {"[", "]"}, + meta = "alias context, ... ", + optional = true + }, + {meta = "alias"}, + {delimiters = {"[", "]"}, meta = "delim context", optional = true}, + {meta = "delim"} + }, + deprecated = true, + details = [[ +```latex +\DeclareDelimAlias*[alias context, ... ]{alias}[delim context]{delim} +``` + +The starred version of `\DeclareDelimAlias` is deprecated in favour of +using unstarred `\DeclareDelimAlias` with optional arguments. + +It assigns the delimiter alias for specific contexts only. The first +optional argument `alias context` holds a list of contexts for which the +assignment is going to be performed. If it is empty or missing the +global/empty context is assumed. The second optional argument +`delim context` specifies the context of the target delimiter. This +argument may not be a list, it can only hold one context. If it is +missing the `alias context` is assumed (if `alias context` is a list, +the assignment is performed separately for each list item), if it is +empty the global context is used. +]] + }, + DeclareDelimFormat = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "context, ... ", optional = true}, + {meta = "name"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareDelimFormat[context, ... ]{name}{code} +\DeclareDelimFormat*[context, ... ]{name}{code} +``` + +Declares the delimiter macro `name` with the replacement text `code`. If +the optional comma-separated list of `contexts` is given, declare `name` +only for those contexts. `name` defined without any `contexts` behaves +just like the global delimiter definitions which `\newcommand` +gives---just a plain macro with a replacement which can be used as +`\name`. However, you can also call delimiter macros defined in this way +by using `\printdelim`, which is context-aware. The starred version +clears all `context` specific declarations for all `names` first. +]] + }, + DeclareDriverSourcemap = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "datatype=driver", + optional = true + }, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareDriverSourcemap[datatype=driver]{specification} +``` + +This command sets the driver default source mappings for the specified +`driver`. Such mappings are conceptually separate from user mappings +defined with `\DeclareSourcemap` and style mapping defined with +`\DeclareStyleSourcemap`. They consist of mappings which are part of the +driver setup. Users should not normally need to change these. Driver +default mapping are applied after user mappings (`\DeclareSourcemap`) +and style mappings (`\DeclareStyleSourcemap`). These defaults are +described in Appendix ??. The `specification` is identical to that for +`\DeclareSourcemap` but without the `\maps` elements: the +`specification` is just a list of `\map` elements since each +`\DeclareDriverSourcemap` only applies to one datatype driver. See the +default definitions in Appendix ?? for examples. +]] + }, + DeclareEntryOption = { + arguments = { + {delimiters = {"[", "]"}, meta = "datatype", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "value", optional = true}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareEntryOption[datatype]{key}[value]{code} +``` + +Similar to `\DeclareBibliographyOption` but defines options which are +settable on a per-entry basis in the `options` field from ??. The `code` +is executed whenever `biblatex`prepares the data of the entry for use by +a citation command or a bibliography driver. +]] + }, + DeclareExtradate = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareExtradate{specification} +``` + +Defines how `biber`tracks information used to construct the `extradate` +field. This field (see ??) is printed to disambiguate works by the same +author which occur in the same date scope. By default, the date scope is +the year and so two works by the same author within the same year will +have different `extradate` values which are used to disambiguate the +works in the bibliography in the usual manner seen in many authoryear +type styles. The `specification` is one or more `\scope` specifications +which can contain one or more `\field` specifications. Within a +`\scope`, the existence of each `\field` will be checked and if found, +the first `\field` is used and the rest are ignored. This allows a +fallback in case certain fields are not available in all entries. All +`\scope`s are used to track information and `\scope`s should be +specified in decreasing order of generality (e.g. year then month then +day etc) The default definition is: + + \DeclareExtradate{% + \scope{ + \field{labelyear} + \field{year} + } + } + +This means that the `labelyear` field only (or `year` if this does not +exist) will be used to track works by the same author. With the +following datasource entries: + + {} + @BOOK{extra1, + AUTHOR = {John Doe}, + DATE = {2001-01} + } + + @BOOK{extra2, + AUTHOR = {John Doe}, + DATE = {2001-02} + } + +The default definition would result in: + + {} + Doe 2001a + Doe 2001b + +Here, `extradate` only considers the `(`(label)year) information and +since this is identical, disambiguation is required. However, consider +the following definition: + + \DeclareExtradate{% + \scope{ + \field{labelyear} + \field{year} + } + \scope{ + \field{labelmonth} + } + } + +The result would be: + + {} + Doe 2001 + Doe 2001 + +If only years were printed, this would be ambiguous because `extradate` +now considers `labelmonth` and since this differs, no disambiguation is +necessary. Care should therefore be taken to synchronise the printed +information with the `extradate` disambiguation settings. Notice that +the second definition is <month-in-year> disambiguation and quite +different from: + + \DeclareExtradate{% + \scope{ + \field{labelmonth} + } + } + +which is just plain <month> disambiguation which is very unlikely to +be what you ever want to do since this disambiguation only based on +month and ignores the year entirely. `extradate` calculation should +almost always be based on all information down to the resolution you +require. For example, if you wish to disambiguate right down to the hour +level (perhaps useful in large bibliographies of rapidly changing online +material), you would specify something like this: + + \DeclareExtradate{% + \scope{ + \field{labelyear} + \field{year} + } + \scope{ + \field{labelmonth} + } + \scope{ + \field{labelday} + } + \scope{ + \field{labelhour} + } + } + +Entries without the specified granularity of information will +disambiguate at the lowest granularity they contain, so, for example, +with: + + \DeclareExtradate{% + \scope{ + \field{labelyear} + \field{year} + } + \scope{ + \field{labelmonth} + } + } + + {} + @BOOK{extra1, + AUTHOR = {John Doe}, + DATE = {2001} + } + + @BOOK{extra2, + AUTHOR = {John Doe}, + DATE = {2001} + } + +The result would still be: + + {} + Doe 2001a + Doe 2001b + +This command may only be used in the preamble. +]] + }, + DeclareFieldFormat = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "entrytype, ... ", + optional = true + }, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareFieldFormat[entrytype, ... ]{format}{code} +\DeclareFieldFormat*{format}{code} +``` + +Defines the field format `format`. This formatting directive is +arbitrary `code` to be executed by `\printfield`. The value of the field +will be passed to the `code` as its first and only argument. The name of +the field currently being processed is available to the `code` as +`\currentfield`. If an `entrytype` is specified, the format is specific +to that type. The `entrytype` argument may be a comma-separated list of +values. The starred variant of this command is similar to the regular +version, except that all type-specific formats are cleared. +]] + }, + DeclareFieldInputHandler = { + arguments = {{meta = "field"}, {meta = "code"}}, + details = [[ +```latex +\DeclareFieldInputHandler{field}{code} +``` + +This command can be used to define a data input handler for `field` when +it is read from the `.bbl`. The `code` is passed one argument (`#1`), +which contains the input field value, it should then redefine the +command `\NewValue`, which holds the desired output field value. For +example, to ignore the `volumes` field when it appears, you could do + + \DeclareFieldInputHandler{volumes}{\def\NewValue{}} + +Generally, you would want to use `\DeclareSourcemap` (see ??) to remove +and modify fields but this alternative method may be useful in some +circumstances when the emphasis is on appearance rather than data since +the `code` can be arbitraty TeX . + +In general, `\DeclareFieldInputHandler` should not be used to apply +formatting to a field, since that should happen with +`\DeclareFieldFormat`, so the following is just a toy example that shows +how `\DeclareFieldInputHandler` works. + + \DeclareFieldInputHandler{volumes}{\def\NewValue{\textbf{#1}}} +]] + }, + DeclareIndexFieldAlias = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeclareIndexFieldAlias[entry type]{alias}[format entry type]{format} +``` + +Declares `alias` to be an alias for the field format `format`. If an +`entrytype` is specified, the alias is specific to that type. The +`format entry type` is the entry type of the backend format. This is +only required when declaring an alias for a type-specific formatting +directive. +]] + }, + DeclareIndexFieldFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareIndexFieldFormat*{format}{code} +``` + +Defines the field format `format`. This formatting directive is +arbitrary `code` to be executed by `\indexfield`. The value of the field +will be passed to the `code` as its first and only argument. The name of +the field currently being processed is available to the `code` as +`\currentfield`. If an `entrytype` is specified, the format is specific +to that type. The `entrytype` argument may be a comma-separated list of +values. This command is similar to `\DeclareFieldFormat` except that the +data handled by the `code` is not intended to be printed but written to +the index. Note that `\indexfield` will execute the `code` as is, i.e. +the `code` must include `\index` or a similar command. The starred +variant of this command is similar to the regular version, except that +all type-specific formats are cleared. +]] + }, + DeclareIndexListFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareIndexListFormat*{format}{code} +``` + +Defines the literal list format `format`. This formatting directive is +arbitrary `code` to be executed for every item in a list processed by +`\indexlist`. The current item will be passed to the `code` as its only +argument. The name of the literal list currently being processed is +available to the `code` as `\currentlist`. If an `entrytype` is +specified, the format is specific to that type. The `entrytype` argument +may be a comma-separated list of values. This command is similar to +`\DeclareListFormat` except that the data handled by the `code` is not +intended to be printed but written to the index. Note that `\indexlist` +will execute the `code` as is, i.e. the `code` must include `\index` or +a similar command. The starred variant of this command is similar to the +regular version, except that all type-specific formats are cleared. +]] + }, + DeclareIndexNameAlias = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeclareIndexNameAlias[entry type]{alias}[format entry type]{format} +``` + +Declares `alias` to be an alias for the name list format `format`. If an +`entrytype` is specified, the alias is specific to that type. The +`format entry type` is the entry type of the backend format. This is +only required when declaring an alias for a type-specific formatting +directive. +]] + }, + DeclareIndexNameFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareIndexNameFormat*{format}{code} +``` + +Defines the name list format `format`. This formatting directive is +arbitrary `code` to be executed for every name in a list processed by +`\indexnames`. The name of the name list currently being processed is +available to the `code` as `\currentname`. If an `entrytype` is +specified, the format is specific to that type. The `entrytype` argument +may be a comma-separated list of values. The parts of the name will be +passed to the `code` as separate arguments. This command is very similar +to `\DeclareNameFormat` except that the data handled by the `code` is +not intended to be printed but written to the index. Note that +`\indexnames` will execute the `code` as is, i.e. the `code` must +include `\index` or a similar command. The starred variant of this +command is similar to the regular version, except that all type-specific +formats are cleared. +]] + }, + DeclareLabelalphaNameTemplate = { + arguments = { + {delimiters = {"[", "]"}, meta = "name", optional = true}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareLabelalphaNameTemplate[name]{specification} +``` + +Defines the `labelalphaname` template `name`. The `name` is optional and +defaults to ``. + +Such templates specify how to extract a label string from a name list +when a `\field` specification in `\DeclareLabelalphaTemplate` contains a +name list. +]] + }, + DeclareLabelalphaTemplate = { + arguments = { + {delimiters = {"[", "]"}, meta = "", optional = true}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareLabelalphaTemplate[]{specification} +``` + +Defines the alphabetic label template for the given entrytypes. If no +entrytypes are specified in the first argument, then the global label +template is defined. The `specification` is an undelimited list of +`\labelelement` directives which specify the elements used to build the +label. Spaces, tabs, and line endings may be used freely to visually +arrange the `specification`. Blank lines are not permissible. This +command may only be used in the preamble. +]] + }, + DeclareLabelname = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "entrytype, ... ", + optional = true + }, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareLabelname[entrytype, ... ]{specification} +``` + +Defines the fields to consider when generating the `labelname` field +(see ??). The `specification` is an ordered list of `\field` commands. +The fields are checked in the order listed and the first field which is +available will be used as `labelname`. This is the default definition: + + \DeclareLabelname{% + \field{shortauthor} + \field{author} + \field{shorteditor} + \field{editor} + \field{translator} + } + +The `labelname` field may be customized globally or on a per-type basis. +If the optional `entrytype` argument is given, the specification applies +to the respective entry type. If not, it is applied globally. The +`entrytype` argument may be a comma-separated list of values. This +command may only be used in the preamble. +]] + }, + DeclareLanguageMappingSuffix = { + arguments = {{meta = "suffix"}}, + details = [[ +```latex +\DeclareLanguageMappingSuffix{suffix} +``` + +This command defines a language file suffix which will be added when +looking for `.lbx` language string definition files. This is intended +for styles which provide their own `.lbx` files so that they will be +used automatically. For example, the APA style defines: + + \DeclareLanguageMappingSuffix{-apa} + +When the document language is <german>, `biblatex`will look for the +file `german-apa.lbx` which defines some APA specific strings and in +turn loads `german.lbx`. If `\DeclareLanguageMapping` is defined for a +language, this overrides `\DeclareLanguageMappingSuffix`. + +The suffix will be applied to other language files loaded recursively by +the loading of a language file. For example, given the suffix defined +above, when loading <ngerman>, `biblatex`will look for the file +`ngerman-apa.lbx` and if this recursively loads <german>, then +biblatex will look for `german-apa.lbx`. Infinite recursion is of course +avoided. +]] + }, + DeclareListAlias = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeclareListAlias[entry type]{alias}[format entry type]{format} +``` + +Declares `alias` to be an alias for the literal list format `format`. If +an `entrytype` is specified, the alias is specific to that type. The +`format entry type` is the entry type of the backend format. This is +only required when declaring an alias for a type-specific formatting +directive. +]] + }, + DeclareListFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareListFormat*{format}{code} +``` + +Defines the literal list format `format`. This formatting directive is +arbitrary `code` to be executed for every item in a list processed by +`\printlist`. The current item will be passed to the `code` as its first +and only argument. The name of the literal list currently being +processed is available to the `code` as `\currentlist`. If an +`entrytype` is specified, the format is specific to that type. The +`entrytype` argument may be a comma-separated list of values. Note that +the formatting directive also handles the punctuation to be inserted +between the individual items in the list. You need to check whether you +are in the middle of or at the end of the list, i.e. whether `listcount` +is smaller than or equal to `liststop`. The starred variant of this +command is similar to the regular version, except that all type-specific +formats are cleared. +]] + }, + DeclareListWrapperAlias = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeclareListWrapperAlias[entry type]{alias}[format entry type]{format} +``` + +Declares `alias` to be an alias for the outer list format `format`. If +an `entrytype` is specified, the alias is specific to that type. The +`format entry type` is the entry type of the backend format. This is +only required when declaring an alias for a type-specific formatting +directive. +]] + }, + DeclareListWrapperFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareListWrapperFormat*{format}{code} +``` + +Defines the list wrapper format `format`. This formatting directive is +arbitrary `code` to be executed once for the entire list processed by +`\printlist`. The name of the literal list currently being processed is +available to the `code` as `\currentlist`. If an `entrytype` is +specified, the format is specific to that type. The `entrytype` argument +may be a comma-separated list of values. The starred variant of this +command is similar to the regular version, except that all type-specific +formats are cleared. +]] + }, + DeclareMultiCiteCommand = { + arguments = { + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "cite"}, + {meta = "delimiter"} + }, + details = [[ +```latex +\DeclareMultiCiteCommand{command}[wrapper]{cite}{delimiter} +``` + +This command defines <multicite> commands (??). The `command` is the +multicite command to be defined, for example `\cites`. It is +automatically made robust. Multicite commands are built on top of +backend commands defined with `\DeclareCiteCommand` and the `cite` +argument specifies the name of the backend command to be used. Note that +the wrapper of the backend command (i.e. the `wrapper` argument passed +to `\DeclareCiteCommand`) is ignored. Use the optional `wrapper` +argument to specify an alternative wrapper. The `delimiter` is the +string to be printed as a separator between the individual citations in +the list. This will typically be `\multicitedelim`. The following +examples are real definitions taken from `biblatex.def`: + + \DeclareMultiCiteCommand{\cites}% + {\cite}{\multicitedelim} + \DeclareMultiCiteCommand{\parencites}[\mkbibparens]% + {\parencite}{\multicitedelim} + \DeclareMultiCiteCommand{\footcites}[\mkbibfootnote]% + {\footcite}{\multicitedelim} +]] + }, + DeclareNameFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareNameFormat*{format}{code} +``` + +Defines the name list format `format`. This formatting directive is +arbitrary `code` to be executed for every name in a list processed by +`\printnames`. If an `entrytype` is specified, the format is specific to +that type. The `entrytype` argument may be a comma-separated list of +values. The individual parts of a name will be available in +automatically created macros (see below). The default data mode defines +four name part which correspond to the standard BibTeX name parts +arguments: + +family +The family name(s), know as <last> in BibTeX . If a name consists of +a single part only (for example, <Aristotle>), this part will be +treated as the family name. + +given +The given name(s). Note that given names are referred to as the +<first> names in the BibTeX file format documentation. + +prefix +Any name prefices, for example von, van, of, da, de, del, della, etc. +Note that name prefices are referred to as the <von> part of the name +in the BibTeX file format documentation. + +suffix +Any name suffices, for example Jr, Sr. Note that name suffices are +referred to as the <Jr> part of the name in the BibTeX file format +documentation. + +The value of the datamodel <nameparts> constant (see ??) creates two +macros for each name part in the datamodel for the name. So, for +example, in the default data model, name formats will have defined the +following macros: + + \namepartprefix + \namepartprefixi + \namepartfamily + \namepartfamilyi + \namepartsuffix + \namepartsuffixi + \namepartgiven + \namepartgiveni + +If a certain part of a name is not available, the corresponding macro +will be empty, hence you may use, for example, the `etoolbox` tests like +`\ifdefvoid` to check for the individual parts of a name. The name of +the name list currently being processed is available to the `code` as +`\currentname`. Note that the formatting directive also handles the +punctuation to be inserted between separate names and between the +individual parts of a name. You need to check whether you are in the +middle of or at the end of the list, i.e. whether `listcount` is smaller +than or equal to `liststop`. See also ??. The starred variant of this +command is similar to the regular version, except that all type-specific +formats are cleared. +]] + }, + DeclareNameInputHandler = { + arguments = {{meta = "name"}, {meta = "code"}}, + details = [[ +```latex +\DeclareNameInputHandler{name}{code} +``` + +As `\DeclareFieldInputHandler` but for names. Within the `code`, the +macro `\NewValue` contains the value of the name, `\NewCount` contains +the number of individual names in the name and `\NewOption` contains any +per-name options passed in the `.bbl`. Note that `\NewValue` as well as +the single argument to `code` contain the internal representation of the +name list. +]] + }, + DeclareNameWrapperFormat = { + arguments = { + {literal = "*", optional = true}, + {meta = "format"}, + {meta = "code"} + }, + details = [[ +```latex +\DeclareNameWrapperFormat*{format}{code} +``` + +Defines the list wrapper format `format`. This formatting directive is +arbitrary `code` to be executed once for the entire name list processed +by `\printnames`. The name of the literal list currently being processed +is available to the `code` as `\currentname`. If an `entrytype` is +specified, the format is specific to that type. The `entrytype` argument +may be a comma-separated list of values. The starred variant of this +command is similar to the regular version, except that all type-specific +formats are cleared. +]] + }, + DeclareNoinit = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareNoinit{specification} +``` + +Defines regular expressions to strip from names before generating +initials. The `specification` is an undelimited list of `\noinit` +directives which specify the regular expressions to remove from the +name. Spaces, tabs and line endings may be used freely to visually +arrange the `specification`. Blank lines are not permissible. This +command may only be used in the preamble. +]] + }, + DeclareNolabel = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareNolabel{specification} +``` + +Defines regular expressions to strip from any field before generating a +label part for the field. The `specification` is an undelimited list of +`\nolabel` directives which specify the regular expressions to remove +from fields. Spaces, tabs and line endings may be used freely to +visually arrange the `specification`. Blank lines are not permissible. +This command may only be used in the preamble. +]] + }, + DeclareNolabelwidthcount = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareNolabelwidthcount{specification} +``` + +Defines regular expressions to ignore from any field when counting +characters in fixed-width substrings. The `specification` is an +undelimited list of `\nolabelwidthcount` directives which specify the +regular expressions to ignore when counting characters for fixed-width +substrings. Spaces, tabs and line endings may be used freely to visually +arrange the `specification`. Blank lines are not permissible. This +command may only be used in the preamble. +]] + }, + DeclareNonamestring = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareNonamestring{specification} +``` + +Defines regular expressions to strip from name fields when generating +`fullhash` and `uniquename`. The `specification` is an undelimited list +of `\nonamestring` directives which specify the regular expressions to +remove from particular name fields. Spaces, tabs and line endings may be +used freely to visually arrange the `specification`. Blank lines are not +permissible. This command may only be used in the preamble. +]] + }, + DeclareNosort = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareNosort{specification} +``` + +Defines regular expressions to strip from particular fields or types of +fields when sorting. The `specification` is an undelimited list of +`\nosort` directives which specify the regular expressions to remove +from particular fields or type of field. Spaces, tabs and line endings +may be used freely to visually arrange the `specification`. Blank lines +are not permissible. This command may only be used in the preamble. +]] + }, + DeclareNumChars = { + arguments = {{literal = "*", optional = true}, {meta = "characters"}}, + details = [[ +```latex +\DeclareNumChars{characters} +\DeclareNumChars*{characters} +``` + +This command configures the `\ifnumeral`, `\ifnumerals`, and `\ifpages` +tests from ??. The setup will also affect `\iffieldnum`, `\iffieldnums`, +`\iffieldpages` as well as `\mkpageprefix` and `\mkpagetotal`. The +`characters` argument is an undelimited list of characters which are to +be considered as being part of a number. The regular version of this +command replaces the current setting, the starred version appends its +argument to the current list. The default setting is: + + \DeclareNumChars{.} + +This means that a (section or other) number like <3.4.5> will be +considered as a number. Note that Arabic and Roman numerals are detected +by default, there is no need to declare them explicitly. +]] + }, + DeclarePageCommands = { + arguments = {{literal = "*", optional = true}, {meta = "commands"}}, + details = [[ +```latex +\DeclarePageCommands*{commands} +``` + +This command is similar to `\DeclareRangeCommands`, except that it only +affects the `\ifpages` and `\iffieldpages` tests but not `\ifnumerals` +and `\iffieldnums`. The default setting is: + + \DeclarePageCommands{\pno\ppno} +]] + }, + DeclarePrefChars = { + arguments = {{literal = "*", optional = true}, {meta = "characters"}}, + details = [[ +```latex +\DeclarePrefChars{characters} +\DeclarePrefChars*{characters} +``` + +This command declares characters that are to be treated specially when +testing to see if `\bibnamedelimc` is to be inserted between a name +prefix and a family name. If a character is in the list of `characters`, +`\bibnamedelimc` is not inserted. It is used to allow abbreviated name +prefices like <d'Argent> where no space should be inserted after the +apostrophe. The starred version appends its argument to the list of +prefix characters, the unstarred version replaces the current setting. +The default setting is: + + \DeclarePrefChars{'-} + +For engines that fully support Unicode these defaults are extended with + + [escapeinside={(*@}{@*)}] + \DeclarePrefChars*{(*@’@*)} +]] + }, + DeclarePresort = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "entrytype, ... ", + optional = true + }, + {meta = "string"} + }, + details = [[ +```latex +\DeclarePresort[entrytype, ... ]{string} +``` + +Specifies a string to be used to automatically populate the `presort` +field of entries without a `presort` field. The `presort` may be defined +globally or on a per-type basis. If the optional `entrytype` argument is +given, the `string` applies to the respective entry type. If not, it +serves as the global default value. Specifying an `entrytype` in +conjunction with a blank `string` will clear the type-specific setting. +The `entrytype` argument may be a comma-separated list of values. This +command may only be used in the preamble. +]] + }, + DeclarePrintbibliographyDefaults = { + arguments = {{meta = "key=value, ... "}}, + details = [[ +```latex +\DeclarePrintbibliographyDefaults{key=value, ... } +``` + +This command can be used to globally set defaults for some options to +`\printbibliography`, the `\bibby...` bibliography commands and +`\printbibheading`. The supported keys are + +- `env` + +- `heading` + +- `title` + +- `prenote` + +- `postnote` + +- `filter` +]] + }, + DeclareQuotePunctuation = { + arguments = {{meta = "characters"}}, + details = [[ +```latex +\DeclareQuotePunctuation{characters} +``` + +This command controls <American-style> punctuation. The `\mkbibquote` +wrapper from ?? can interact with the punctuation facilities discussed +in ??. Punctuation marks after `\mkbibquote` will be moved inside the +quotes if they have been registered with `\DeclareQuotePunctuation`. +Note that `characters` is an undelimited list of characters. Valid +`characters` are period, comma, semicolon, colon, exclamation and +question mark. Here is an example: + + \DeclareQuotePunctuation{.,} + +Executing `\DeclareQuotePunctuation{}` is equivalent to disabling this +feature. This is the package default. Since this feature is language +specific, this command must be used in the argument to +`\DefineBibliographyExtras` (when used in the preamble) or +`\DeclareBibliographyExtras` (when used in a localisation module). See +?? for details. See also ??. +]] + }, + DeclareRangeChars = { + arguments = {{literal = "*", optional = true}, {meta = "characters"}}, + details = [[ +```latex +\DeclareRangeChars*{characters} +``` + +This command configures the `\ifnumerals` and `\ifpages` tests from ??. +The setup will also affect `\iffieldnums` and `\iffieldpages` as well as +`\mkpageprefix` and `\mkpagetotal`. The `characters` argument is an +undelimited list of characters which are to be considered as range +indicators. The regular version of this command replaces the current +setting, the starred version appends its argument to the current list. +The default setting is: + + \DeclareRangeChars{~,;-+/} + +For engines that fully support Unicode these defaults are extended with + + [escapeinside={(*@}{@*)}] + \DeclareRangeChars*{(*@–—@*)} + +This means that strings like <3--5>, <35+>, <8/9> and so on +will be considered as a range by `\ifnumerals` and `\ifpages`. Non-range +characters in such strings are recognized as numbers. So strings like +<3a--5a> and <35b+> are not deemed to be ranges by default. See +also ?? for further details. +]] + }, + DeclareRangeCommands = { + arguments = {{literal = "*", optional = true}, {meta = "commands"}}, + details = [[ +```latex +\DeclareRangeCommands*{commands} +``` + +This command is similar to `\DeclareRangeChars`, except that the +`commands` argument is an undelimited list of commands which are to be +considered as range indicators. The regular version of this command +replaces the current setting, the starred version appends its argument +to the current list. The default list is rather long and should cover +all common cases; here is a shorter example: + + \DeclareRangeCommands{\&\bibrangedash\textendash\textemdash\psq\psqq} + +See also ?? for further details. +]] + }, + DeclareRedundantLanguages = { + arguments = {{meta = "language, language, ..."}, {meta = "langid, langid, ..."}}, + details = [[ +```latex +\DeclareRedundantLanguages{language, language, ...}{langid, langid, ...} +``` + +This command provides the language mappings required by the `clearlang` +option from ??. The `language` is the string given in the `language` +field (without the optional `lang` prefix); `langid` is +`babel`/`polyglossia`'s language identifier, as given in the optional +argument of `\usepackage` when loading `babel` or the argument of +`\setdefaultlanguage` or `\setotherlanguages` when using `polyglossia`. +This command may be used in `lbx` files or in the document preamble. +Here are some examples: + + \DeclareRedundantLanguages{french}{french} + \DeclareRedundantLanguages{german}{german,ngerman,austrian,naustrian, + nswissgerman,swissgerman} + \DeclareRedundantLanguages{english,american}{english,american,british, + canadian,australian,newzealand,USenglish,UKenglish} + +Note that this feature needs to be enabled globally with the `clearlang` +option from ??. If it is disabled, all mappings will be ignored. If the +`langid` parameter is blank, `biblatex`will clear the mappings for the +corresponding `language`, i.e. the feature will be disabled for this +`language` only. +]] + }, + DeclareRefcontext = { + arguments = {{meta = "name"}, {meta = "key=value, ... "}}, + details = [[ +```latex +\DeclareRefcontext{name}{key=value, ... } +``` + +Declares a named reference context with name `name`. The `key=value` +options define the context attributes. All context attributes are +optional and default to the global settings if absent. The valid options +are: + +`sorting=` +Specify a sorting template defined previously with +`\DeclareSortingTemplate`. This template is used to determine which data +to retrieve and/or print for an entry in the commands inside the +context. + +`sortingnamekeytemplatename=` +Specify a sorting name key template defined previously with +`\DeclareSortingNamekeyTemplate`. This template is used to construct +sorting keys for names inside the context. The template name can also be +specified (in increasing order of preference) per-entry, per-name list +and per-name. See ?? for information on setting per-option, per-namelist +and per-name options. + +`uniquenametemplatename=` +Specify a uniquename template defined previously with +`\DeclareUniquenameTemplate` (see ??). This template is used to +calculate uniqueness information for names inside the context. The +template name can also be specified (in increasing order of preference) +per-entry, per-name list and per-name. See ?? for information on setting +per-option, per-namelist and per-name options. + +`labelalphanametemplatename=` +Specify a template defined previously with +`\DeclareLabelalphaNameTemplate` (see ??). This template is used to +construct name parts of alphabetic labels for names inside the context. +The template name can also be specified (in increasing order of +preference) per-entry, per-name list and per-name. See ?? for +information on setting per-option, per-namelist and per-name options. + +`nametemplates=` +A convenience meta-option which sets `sortingnamekeytemplate`, +`uniquenametemplate` and `labelalphanametemplate` to the same template +name. This option can also be specified (in increasing order of +preference) per-entry, per-name list and per-name. See ?? for +information on setting per-option, per-namelist and per-name options. + +`labelprefix=` +This option applies to numerical citation/bibliography styles only and +requires that the `defernumbers` option from ?? be enabled globally. +Setting this option will implicitly enable `resetnumbers` for the any +`\printbibliography` in the scope of the context (unless overridden by a +user-specified value for `resetnumbers`). The option assigns the +`string` as a prefix to all entries in the reference context. For +example, if the `string` is `A`, the numerical labels printed will be +`[A1]`, `[A2]`, `[A3]`, etc. This is useful for subdivided numerical +bibliographies where each subbibliography uses a different prefix. The +`string` is available to styles in the `labelprefix` field of all +affected entries. Note that the `string` is fully expanded, which means +that you can use context-dependent macros like `\thechapter`, but not +unexpandable commands such as `\dag`. If you need to pass unexpandable +code to `string`, protect it from expansion with `\detokenize`. See ?? +for details. +]] + }, + DeclareSortExclusion = { + arguments = {{meta = "entrytype, ... "}, {meta = "field, ... "}}, + details = [[ +```latex +\DeclareSortExclusion{entrytype, ... }{field, ... } +``` + +Specifies fields to be excluded from sorting on a per-type basis. The +`entrytype` argument and the `field` argument may be a comma-separated +list of values. A blank `field` argument will clear all exclusions for +this `entrytype`. A value of <\*> for `entrytype` will exclude +`field,…` for every entrytype. This is equivalent to simply deleting the +field from the sorting specification and is only normally used in +combination with `\DeclareSortInclusion` when one wishes to exclude a +field for all but explicitly included entrytypes. See example in +`\DeclareSortInclusion` below. This command may only be used in the +preamble. +]] + }, + DeclareSortingNamekeyTemplate = { + arguments = { + {delimiters = {"[", "]"}, meta = "name", optional = true}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareSortingNamekeyTemplate[name]{specification} +``` + +Defines how the sorting keys for names are constructed. This can change +the sorting order of names arbitrarily because you can choose how to put +together the name parts when constructing the string to compare when +sorting. The sorting key construction template so defined is called +`name` which defaults to «global» if this optional parameter is absent. +When constructing the sorting key for a name, a sorting key for each +name part is constructed and the key for each name is formed into an +ordered key list with a special internal separator. The point of this +option is to accommodate languages or situations where sorting of names +needs to be customised (for example, Icelandic names are sometimes +sorted by given names rather than by family names). This macro may be +used multiple times to define templates with different names which can +then be referred to later. Sorting name key templates can be specified +at the following scopes, in order of increasing precedence: + +- The default template defined without the optional name argument + +- Given as the `sortingnamekeytemplate` option to a reference context + (see ??) + +- Given as a per-entry option `sortnamekeytemplate` in a bibliography + data source entry + +- Given as a per-namelist option `sortnamekeytemplate` + +- Given as a per-name option `sortnamekeytemplate` + +By default there is only a global template which has the following +`specification`: + + \DeclareSortingNamekeyTemplate{ + \keypart{ + \namepart[use=true]{<>} + \namepart{<>} + } + \keypart{ + \namepart{<>} + } + \keypart{ + \namepart{<>} + } + \keypart{ + \namepart[use=false]{<>} + } + } + +This means that the key is constructed by concatenating, in order, the +name prefix (only if the `useprefix` option is true) with the family +name(s), the given names(s), the name suffix and then the name prefix +(only if the `useprefix` option is false). +]] + }, + DeclareSortingTemplate = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "name"}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareSortingTemplate[options]{name}{specification} +``` + +Defines the sorting template `name`. The `name` is the identifier passed +to the `sorting` option (??) when selecting the sorting template. The +`\DeclareSortingTemplate` command supports the following optional +arguments: + +`locale={locale}` +The locale for the sorting template which then overrides the global +sorting locale in the `sortlocale` option discussed in ??. + +The `specification` is an undelimited list of `\sort` directives which +specify the elements to be considered in the sorting process. Spaces, +tabs, and line endings may be used freely to visually arrange the +`specification`. Blank lines are not permissible. This command may only +be used in the preamble. +]] + }, + DeclareSourcemap = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareSourcemap{specification} +``` + +Defines source data modification (mapping) rules which can be used to +perform any combination of the following tasks: + +- Map data source entrytypes to different entrytypes + +- Map datasource fields to different fields + +- Add new fields to an entry + +- Remove fields from an entry + +- Modify the contents of a field using standard Perl regular + expression match and replace[1] + +- Restrict any of the above operations to entries coming from + particular datasources which you defined in `\addresource` macros + +- Restrict any of the above operations to entries only of a certain + entrytype + +- Restrict any of the above operations to entries in a particular + reference section + +The `specification` is an undelimited list of `\maps` directives which +specify containers for mappings rules applying to a particular data +source type (??). Spaces, tabs, and line endings may be used freely to +visually arrange the `specification`. Blank lines are not permissible. +This command may only be used in the preamble and can be used multiple +times, the maps being run in order of definition. + +[1] See for example , + and +. There are many more resources +available about regular expessions in Perl. +]] + }, + DeclareStyleSourcemap = { + arguments = {{meta = "specification"}}, + details = [[ +```latex +\DeclareStyleSourcemap{specification} +``` + +This command sets the source mappings used by a style. Such mappings are +conceptually separate from user mappings defined with +`\DeclareSourcemap` and are applied directly after user maps. The syntax +is identical to `\DeclareSourcemap`. This command is provided for style +authors so that any maps defined for the style do not interfere with +user maps or the default driver maps defined with +`\DeclareDriverSourcemap`. This command is for use in style files and +can be used multiple times, the maps being run in order of definition. +]] + }, + DeclareUniquenameTemplate = { + arguments = { + {delimiters = {"[", "]"}, meta = "name", optional = true}, + {meta = "specification"} + }, + details = [[ +```latex +\DeclareUniquenameTemplate[name]{specification} +``` + +Defines the `uniquename` template `name`. The `name` is optional and +defaults to ``. + +The `specification` is an ordered list of `\namepart` commands which +define the nameparts to use in determining the uniquename information. +]] + }, + DefaultInheritance = { + arguments = { + {delimiters = {"[", "]"}, meta = "exceptions", optional = true}, + {meta = "options"} + }, + details = [[ +```latex +\DefaultInheritance[exceptions]{options} +``` + +Configures the default inheritance behavior. This command may only be +used in the preamble. The default behavior may be customized be setting +the following `options`: + +`all` +Whether or not to inherit all fields from the parent by default. + +`all=true` means that the child entry inherits all fields from the +parent, unless a more specific inheritance rule has been set up with +`\DeclareDataInheritance`. If an inheritance rule is defined for a +field, data inheritance is controlled by that rule. `all=false` means +that no data is inherited from the parent by default and each field to +be inherited requires an explicit inheritance rule set up with +`\DeclareDataInheritance`. The package default is `all=true`. + +`override` +Whether or not to overwrite target fields with source fields if both are +defined. This applies both to automatic inheritance and to explicit +inheritance rules. The package default is `override=false`, i.e. +existing fields of the child entry are not overwritten. + +`ignore=` +This option takes a comma-separated list of one of more of +<singletitle>, <uniquetitle>, <uniquebaretitle> and/or +<uniquework>. The purpose of this option is to ignore tracking +information for these three options when the field which would trigger +the tracking (??) is inherited. An example---Suppose that you have +several `book` entries which all crossref a `mvbook` from which they get +their `author` field. You might reasonably want the `\ifsingletitle` +test to return <true> for this author as their only <work> is the +`mvbook`. Similar comments would apply to situations involving the +`\ifuniquetitle`, `\ifuniquebaretitle` and `\ifuniquework` tests. The +`ignore` option lists which of these should have their tracking +information ignored when the fields which would trigger them are +inherited. The idea is that the presence of an inherited field does not +contribute towards the determination of whether some combination of +name/title is unique in the bibliographic data. For example, this +modified default setting would ignore `singletitle` and `uniquetitle` +tracking: + + \DefaultInheritance{ignore={singletitle,uniquetitle}, all=true, override=false} + +Of course, the ignoring of tracking does nothing if the fields inherited +do not play a role in tracking. Only the fields listed in ?? are +relevant to this option. + +The optional `exceptions` are an undelimited list of `\except` +directives. Spaces, tabs, and line endings may be used freely to +visually arrange the `exceptions`. Blank lines are not permissible. +]] + }, + DefineBibliographyStrings = { + arguments = {{meta = "language"}, {meta = "definitions"}}, + details = [[ +```latex +\DefineBibliographyStrings{language}{definitions} +``` + +This command is used to define localisation strings. The `language` must +be a language name known to the `babel`/`polyglossia` packages, i.e. one +of the identifiers listed in ?? on page ??. The `definitions` are +`key=value`pairs which assign an expression to an identifier: + + \DefineBibliographyStrings{american}{% + bibliography = {Bibliography}, + shorthands = {Abbreviations}, + editor = {editor}, + editors = {editors}, + } + +A complete list of all keys supported by default is given is ??. Note +that all expressions should be capitalized as they usually are when used +in the middle of a sentence. The `biblatex`package will automatically +capitalize the first word when required at the beginning of a sentence. +Expressions intended for use in headings should be capitalized in a way +that is suitable for titling. In contrast to +`\DeclareBibliographyStrings`, `\DefineBibliographyStrings` overrides +both the full and the abbreviated version of the string. See ?? for +further details. +]] + }, + DeprecateField = { + arguments = {{meta = "field"}, {meta = "message"}}, + details = [[ +```latex +\DeprecateField{field}{message} +\DeprecateList{list}{message} +\DeprecateName{name}{message} +``` + +When an attempt is made to print `field`, `list`, `name`, a deprecation +warning is issued with the additional `message`. This aids style authors +who are changing field names in their style. Note that the deprecated +item must no longer be defined in the datamodel for this to work; +`field`, `list` or `name` cannot be listed anywhere as an argument to +`\DeclareDatamodelFields`. +]] + }, + DeprecateIndexFieldFormatWithReplacement = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeprecateIndexFieldFormatWithReplacement[entry type]{alias}[format entry type]{format} +``` + +Similar to `\DeprecateFieldFormatWithReplacement` but for index field +formats. +]] + }, + DeprecateIndexNameFormatWithReplacement = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeprecateIndexNameFormatWithReplacement[entry type]{alias}[format entry type]{format} +``` + +Similar to `\DeprecateFieldFormatWithReplacement` but for index name +formats. +]] + }, + DeprecateList = { + arguments = {{meta = "list"}, {meta = "message"}}, + details = "$ref:biblatex.sty#/commands/DeprecateField/details" + }, + DeprecateListFormatWithReplacement = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeprecateListFormatWithReplacement[entry type]{alias}[format entry type]{format} +``` + +Similar to `\DeprecateFieldFormatWithReplacement` but for list formats. +]] + }, + DeprecateListWithReplacement = { + arguments = {{meta = "list"}, {meta = "replacement"}}, + details = [[ +```latex +\DeprecateListWithReplacement{list}{replacement} +\DeprecateNameWithReplacement{name}{replacement} +``` + +Similar to `\DeprecateField`, `\DeprecateList` and `\DeprecateName`. The +commands do not only issue a deprecation warning, they try to define a +replacement for the deprecated field that is printed in its stead. The +`\replacement` must be of the same type as the deprecated `field`, +`list` or `name`. If the formatting of `replacement` should be applied +when printing the deprecated field, that needs to be requested with +`\DeclareFieldAlias` (see ??). Note that the deprecated item must no +longer be defined in the datamodel for this work; `field`, `list` or +`name` cannot be listed anywhere as an argument to +`\DeclareDatamodelFields`. +]] + }, + DeprecateListWrapperFormatWithReplacement = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "alias"}, + { + delimiters = {"[", "]"}, + meta = "format entry type", + optional = true + }, + {meta = "format"} + }, + details = [[ +```latex +\DeprecateListWrapperFormatWithReplacement[entry type]{alias}[format entry type]{format} +``` + +Similar to `\DeprecateFieldFormatWithReplacement` but for outer list +formats. +]] + }, + DeprecateName = { + arguments = {{meta = "name"}, {meta = "message"}}, + details = "$ref:biblatex.sty#/commands/DeprecateField/details" + }, + DeprecateNameWithReplacement = { + arguments = {{meta = "name"}, {meta = "replacement"}}, + details = "$ref:biblatex.sty#/commands/DeprecateListWithReplacement/details" + }, + ExecuteBibliographyOptions = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "entrytype, ... ", + optional = true + }, + {meta = "key=value, ... "} + }, + details = [[ +```latex +\ExecuteBibliographyOptions[entrytype, ... ]{key=value, ... } +``` + +This command may also be used in the configuration file to modify the +default setting of a package option. Certain options are also settable +on a per-type basis. In this case, the optional `entrytype` argument +specifies the entry type. The `entrytype` argument may be a +comma-separated list of values. +]] + }, + Fvolcites = { + action = "cite", + details = [[ +```latex +\Fvolcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\fvolcite` and `\Fvolcite`, respectively. +]] + }, + InheritBibliographyExtras = { + arguments = {{meta = "language"}}, + details = [[ +```latex +\InheritBibliographyExtras{language} +``` + +This command is only available in `lbx` files. It copies the +bibliography extras for `language` to the current language, as specified +by the name of the `lbx` file. +]] + }, + MakeCapital = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\MakeCapital{text} +``` + +Similar to `\MakeUppercase` but only converts the first printable +character in `text` to uppercase. Note that the restrictions that apply +to `\MakeUppercase` also apply to this command. Namely, all commands in +`text` must either be robust or prefixed with `\protect` since the +`text` is expanded during capitalization. Apart from US-ASCII characters +and the standard accent commands, this command also handles the active +characters of the `inputenc` package as well as the shorthands of the +`babel` package. If the `text` starts with a control sequence, nothing +is capitalized. This command is robust. +]] + }, + MakeSentenceCase = { + arguments = {{literal = "*", optional = true}, {meta = "text"}}, + details = [[ +```latex +\MakeSentenceCase*{text} +``` + +Converts its `text` argument to sentence case, i.e. the first word is +capitalized and the remainder of the string is converted to lowercase. +This command is robust. The starred variant differs from the regular +version in that it considers the language of the entry, as specified in +the `langid` field. If the `langid` field is defined and holds a +language declared with `\DeclareCaseLangs` (see below)[1], then the +sentence case conversion is performed. If the `langid` field is +undefined, then the language list declared with `\DeclareCaseLangs` is +checked for the presence of the main document language derived from the +`language` option. If found, sentence case conversion is performed, if +not, the `text` is not altered in any way. It is recommended to use +`\MakeSentenceCase*` rather than the regular variant in formatting +directives. + +Depending on the option `casechanger` `\MakeCaseChange` and +`\MakeCaseChange*` are either implemented using the `expl3` module +`l3text` or original LaTeX2ɛ code. + +Both variants support the traditional BibTeX convention for `bib` files +that anything wrapped in a pair of curly braces is not modified when +changing the case. For example: + + \MakeSentenceCase{an Introduction to LaTeX} + \MakeSentenceCase{an Introduction to {LaTeX}} + +would yield: + + {} + An introduction to latex + An introduction to LaTeX + +In `bib` files designed with traditional BibTeX in mind, it has been +fairly common to only wrap single letters in braces to prevent +case-changing: + + {} + title = {An Introduction to {L}a{T}e{X}} + +The problem with this convention is that the braces will suppress the +kerning on both sides of the enclosed letter. It is preferable to wrap +the entire word in braces as shown in the first example. Macros in +titles must also be protected with braces + + {} + title = {The {\TeX book}}, + +The behaviour of `\MakeSentenceCase` differs slightly between the +`latex2e` and `expl3` implementation. Generally speaking, the `expl3` +code is closer to the BibTeX behaviour of `change.case$`. It is also +better equipped to deal with non-US-ASCII input and macros than the +`latex2e` implementation. `\MakeSentenceCase` behaves as follows. + +- The first letter of its argument is capitalised with + `\MakeUppercase`. This is different from BibTeX 's `change.case$`, + which does not touch the first letter of its argument. + + Note that with the `latex2e` code a pair of braces that starts with + a control sequence will be treated as a single character for + capitalisation purposes. This means that the entire argument of a + command protected with a single pair of braces is capitalised. + +- With the `latex2e` code expandable commands are expanded before the + case change, which means that the case change applies to the + replacement text. Unexpandable commands are not touched. + + BibTeX does not interpret macros and therefore passes commands + through unchanged (this does not necessarily apply to the + *arguments* of those commands). The `expl3` implementation also does + not expand commands and only applies case change to the arguments. + +- Text wrapped in one or more pairs of braces is protected from case + change *unless* it starts with a control sequence. This is the same + behaviour as with BibTeX . Note that the braces could either be + explicit groups or argument delimiters. + +- Text in a single pair of braces that starts with a control sequence + is not protected and will be subject to case changes. Note that this + need not apply to braces that are argument delimiters, in fact the + `latex2e` implementation of `\MakeSentenceCase` may in some cases + produce an error or otherwise undesirable output if the argument of + a command starts with a control sequence. BibTeX 's case change + function does not differentiate between argument delimiters and + brace groups and always subjects text at brace level 1 to case + change if it starts with a control sequence. + +For most intents and purposes the following rules should give a sensible +result. + +- Protect all words whose case should not be changed by wrapping them + in one pair of braces. + +- If words are already in the braced argument of a command such as + `\mkbibquote` or `\emph`, they are automatically protected. + + - To *undo* this protection wrap the command in braces again. + + - It is not possible to selectively re-apply protection if it has + been undone with an additional pair of braces. If a more + fine-grained control is needed, work-arounds like splitting the + argument could be tried. + +- While it is possible to protect words from case change at the + beginning of a field with a pair of braces, it is not possible to + undo the case protection that a command automatically implies by + wrapping it in braces in that position. In that case work-arounds + are necessary. + +  + + {} + title = {The Story of {HMS} \emph{Erebus} + in {\emph{Really}} Strong Wind}, + +would be converted to sentence case by `\MakeSentenceCase` as + +> The story of HMS *Erebus* in *really* strong wind + +If the `expl3` implementation of the case changing functions is +selected, the BibTeX case protection behaviour can be exchanged for a +slightly simpler version. When `bibtexcaseprotection` set to `false`, +braces no longer automatically imply case protection. Instead words can +be protected from case change with `\NoCaseChange`. The examples from +above would then read + + {} + title = {An Introduction to \NoCaseChange{LaTeX}}, + title = {The Story of \NoCaseChange{HMS \emph{Erebus}} + in \emph{Really} Strong Wind}, + +Generally, this option should allow for a saner case protection input, +because curly braces are no longer overloaded with different levels of +meaning, but it is a big departure from the standard case protection +input that has been with the LaTeX world for a long time. + +Due to its complex implementation `\MakeSentenceCase` can not accept +arbitrary input, it only safely operates on raw text or field data. In +the standard styles the `title` and other `title`-like field formats do +not work together with `\MakeSentenceCase` because of their argument +structure, so the standard styles offer a dedicated `titlecase` field +format to apply this command. To enable sentence casing in standard +styles for languages that support it you would use: + + \DeclareFieldFormat{titlecase}{<<\MakeSentenceCase*{#1}>>} + +Sentence casing can then be disabled by resetting that field format to + + \DeclareFieldFormat{titlecase}{<<#1>>} + +Custom styles may follow a different approach, but style authors are +encouraged to apply the same general ideas to their styles. + +[1] By default, converting to sentence case is enabled for the following +language identifiers: `american`, `british`, `canadian`, `english`, +`australian`, `newzealand` as well as the aliases `USenglish` and +`UKenglish`. Use `\DeclareCaseLangs` to extend or change this list. +]] + }, + NewBibliographyString = { + arguments = {{meta = "key"}}, + details = [[ +```latex +\NewBibliographyString{key} +``` + +This command declares new localisation strings, i.e. it initializes a +new `key` to be used in the `definitions` of +`\DefineBibliographyStrings`. The `key` argument may also be a +comma-separated list of key names. The keys listed in ?? are defined by +default. +]] + }, + Notecite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Notecite[prenote][postnote]{key} +``` + +These commands print the `prenote` and `postnote` arguments but no +citation. This may be useful for authors who incorporate implicit +citations in their writing, only giving information not mentioned before +in the running text, but who still want to take advantage of the +automatic `postnote` formatting and citation tracking. This is a +generic, style-independent citation command. Special citation styles may +provide smarter facilities for the same purpose. The capitalized version +forces capitalization (note that this is only applicable if the note +starts with a command which is sensitive to `biblatex`'s punctuation +tracker). +]] + }, + NumsCheckSetup = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\NumsCheckSetup{code} +``` + +Like `\NumCheckSetup` but only applies to `\ifnumerals` and `\ifpages` +from ?? and their derivative tests. +]] + }, + OnManualCitation = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\OnManualCitation{code} +``` + +Specifies arbitrary `code` required for a partial reset of the citation +style. This hook will be executed every time the `\mancite` command from +?? is used. It is particularly useful in citation styles which replace +repeated citations by abbreviations like <ibidem> or <op. cit.> +which may get ambiguous if automatically generated and manual citations +are mixed. The `\mancite` command also resets the internal <ibidem> +and <idem> trackers of this package. The reset will affect the +`\ifciteibid` and `\ifciteidem` tests discussed in ??. +]] + }, + Parencite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Parencite[prenote][postnote]{key} +``` + +These commands use a format similar to `\cite` but enclose the entire +citation in parentheses. The numeric and alphabetic styles use square +brackets instead. `\Parencite` is similar to `\parencite` but +capitalizes the name prefix of the first name in the citation if the +`useprefix` option is enabled, provided that there is a name prefix and +the citation style prints any name at all. +]] + }, + Parencites = { + action = "cite", + details = [[ +```latex +\Parencites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +The multicite version of `\parencite` and `\Parencite`, respectively. +]] + }, + Pnotecite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Pnotecite[prenote][postnote]{key} +``` + +Similar to `\notecite` but the notes are printed in parentheses. +]] + }, + Pvolcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Pvolcite[prenote]{volume}[pages]{key} +``` + +Similar to `\volcite` but based on `\parencite`. +]] + }, + Pvolcites = { + action = "cite", + details = [[ +```latex +\Pvolcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\pvolcite` and `\Pvolcite`, respectively. +]] + }, + RequireBibliographyStyle = { + arguments = {{meta = "style"}}, + details = [[ +```latex +\RequireBibliographyStyle{style} +``` + +This command is optional and intended for specialized bibliography +styles built on top of a more generic style. It loads the bibliography +style `style.bbx`. +]] + }, + RequireCitationStyle = { + arguments = {{meta = "style"}}, + details = [[ +```latex +\RequireCitationStyle{style} +``` + +This command is optional and intended for specialized citation styles +built on top of a more generic style. It loads the citation style +`style.cbx`. +]] + }, + ResetDatamodelConstraints = { + details = [[ +```latex +\ResetDatamodelConstraints +``` + +Clear all data model fields Constraints information. +]] + }, + ResetDatamodelFields = { + details = [[ +```latex +\ResetDatamodelFields +``` + +Clear all data model field information. +]] + }, + Rn = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\Rn{integer} +``` + +Similar to `\RN` but prints a lowercase Roman numeral. The formatting +applied to the numeral may be modified by redefining the macro +`\Rnfont`. +]] + }, + Smartcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Smartcite[prenote][postnote]{key} +``` + +Like `\parencite` in a footnote and like `\footcite` in the body. +]] + }, + Smartcites = { + action = "cite", + details = [[ +```latex +\Smartcites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +The multicite version of `\smartcite` and `\Smartcite`, respectively. +]] + }, + Svolcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Svolcite[prenote]{volume}[pages]{key} +``` + +Similar to `\volcite` but based on `\smartcite`. +]] + }, + Svolcites = { + action = "cite", + details = [[ +```latex +\Svolcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\svolcite` and `\Svolcite`, respectively. +]] + }, + Textcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\textcite[prenote][postnote]{key} +\Textcite[prenote][postnote]{key} +``` + +These citation commands are provided by all styles that come with this +package. They are intended for use in the flow of text, replacing the +subject of a sentence. They print the authors or editors followed by a +citation label which is enclosed in parentheses. Depending on the +citation style, the label may be a number, the year of publication, an +abridged version of the title, or something else. The numeric and +alphabetic styles use square brackets instead of parentheses. In the +verbose styles, the label is provided in a footnote. Trailing +punctuation is moved between the author or editor names and the footnote +mark. `\Textcite` is similar to `\textcite` but capitalizes the name +prefix of the first name in the citation if the `useprefix` option is +enabled, provided that there is a name prefix. +]] + }, + Textcites = { + action = "cite", + details = [[ +```latex +\Textcites(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +The multicite version of `\textcite` and `\Textcite`, respectively. +]] + }, + Tvolcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Tvolcite[prenote]{volume}[pages]{key} +``` + +Similar to `\volcite` but based on `\textcite`. +]] + }, + Tvolcites = { + action = "cite", + details = [[ +```latex +\Tvolcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\tvolcite` and `\Tvolcite`, respectively. +]] + }, + UndeclareBibstringSets = { + details = [[ +```latex +\UndeclareBibstringSets +``` + +Remove all existing bibliography string sets with +`\UndeclareBibstringSet`. +]] + }, + UndeclareDelimcontextAlias = { + arguments = {{meta = "alias"}}, + details = [[ +```latex +\UndeclareDelimcontextAlias{alias} +``` + +Removes the delimiter context alias declared for `alias`. +]] + }, + UndefineBibliographyExtras = { + arguments = {{meta = "language"}, {meta = "code"}}, + details = [[ +```latex +\UndefineBibliographyExtras{language}{code} +``` + +This command is used to restore the original definition of any commands +modified with `\DefineBibliographyExtras`. If a redefined command is +included in ??, there is no need to restore its previous definition +since these commands are adapted by all language modules anyway. +]] + }, + UneclareBibstringSetFormat = { + arguments = {{meta = "setname"}}, + details = [[ +```latex +\UneclareBibstringSetFormat{setname} +``` + +Remove any bibliography string set format defined for `setname`. +]] + }, + UseBibitemHook = { + details = [[ +```latex +\UseBibitemHook +``` + +Executes the internal hook corresponding to `\AtEveryBibitem`. +]] + }, + UseEveryCiteHook = { + details = [[ +```latex +\UseEveryCiteHook +``` + +Executes the internal hook corresponding to `\AtEveryCite`. +]] + }, + UseEveryMultiCiteHook = { + details = [[ +```latex +\UseEveryMultiCiteHook +``` + +Executes the internal hook corresponding to `\AtMultiEveryCite`. +]] + }, + UseNextCitekeyHook = { + details = [[ +```latex +\UseNextCitekeyHook +``` + +Executes and clears the internal hook corresponding to `\AtNextCitekey`. +]] + }, + UseVolciteHook = { + details = [[ +```latex +\UseVolciteHook +``` + +Executes the internal hook corresponding to `\AtVolcite`. +]] + }, + Volcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\Volcite[prenote]{volume}[pages]{key} +``` + +These commands are similar to `\cite` and `\Cite` but intended for +references to multi-volume works which are cited by volume and page +number. Instead of the `postnote`, they take a mandatory `volume` and an +optional `pages` argument. Since they merely compose the postnote and +pass it to the `\cite` command provided by the citation style as a +`postnote` argument, these commands are style independent. The volume +and pages/text portion are formatted with the macro `\mkvolcitenote` +when they are passed on to the citation command. Additionally they are +made available in the special fields `volcitevolume` and `volcitevolume` +(??) The format of the volume portion is controlled by the field +formatting directive `volcitevolume`, the format of the pages/text +portion is controlled by the field formatting directive `volcitepages` +(??). The delimiter printed between the volume portion and the +pages/text portion may be modified by redefining the macro +`\volcitedelim` (??). +]] + }, + Volcites = { + action = "cite", + details = [[ +```latex +\Volcites(multiprenote)(multipostnote)[prenote]{volume}[pages]{key}|\\...|[prenote]{volume}[pages]{key} +``` + +The multicite version of `\volcite` and `\Volcite`, respectively. +]] + }, + abbrvpenalty = { + details = [[ +```latex +\abbrvpenalty +``` + +This counter, which is used by the localisation modules, holds the +penalty used in short or abbreviated localisation strings. For example, +a linebreak in expressions such as «et al.» or «ed. by» is unfortunate, +but should still be possible to prevent overfull boxes. This counter is +initialized to `\hyphenpenalty` at load-time. The idea is making TeX +treat the whole expression as if it were a single, hyphenatable word as +far as line-breaking is concerned. If you dislike such linebreaks, use a +higher value. If you do not mind them at all, set this counter to zero. +If you want to suppress them unconditionally, set it to <infinite> +(10 000 or higher).[1] + +[1] The default values assigned to `abbrvpenalty`, `lownamepenalty`, and +`highnamepenalty` are deliberately very low to prevent overfull boxes. +This implies that you will hardly notice any effect on line-breaking if +the text is set justified. If you set these counters to 10 000 to +suppress the respective breakpoints, you will notice their effect but +you may also be confronted with overfull boxes. Keep in mind that +line-breaking in the bibliography is often more difficult than in the +body text and that you can not resort to rephrasing a sentence. In some +cases it may be preferable to set the entire bibliography `\raggedright` +to prevent suboptimal linebreaks. In this case, even the fairly low +default penalties will make a visible difference. + +```latex +\abbrvpenalty +``` + +The penalty used by `\addabbrvspace`, `\addabthinspace`, and +`\adddotspace`, see ?? for details. This counter is initialized to +`\hyphenpenalty` at load-time. +]] + }, + addabthinspace = { + details = [[ +```latex +\addabthinspace +``` + +Similar to `\addabbrvspace` but using a thin space. +]] + }, + addbibresource = { + action = "input", + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "resource"} + }, + details = [[ +```latex +\addbibresource[options]{resource} +``` + +Adds a `resource`, such as a `.bib` file, to the default resource list. +This command is only available in the preamble. It replaces the +`\bibliography` legacy command. Note that files must be specified with +their full name, including the extension. With `biber`, the resource +name can be a BSD-style glob pattern. This only makes sense when +resources refer to files with an absolute or relative path and does not +work when looking for data resources in `biber`s input/output +directories or with resources located by `kpsewhich` etc. When running +on Windows, `biber`will switch to a Windows compatible globbing mode +where backslashes are also useable as path separators and case does not +matter. If the resources contain duplicate entries (that is, duplicate +`entrykey`s), it is backend dependent what then happens. For example, by +default `biber`will ignore further occurrence of `entrykey`s unless its +`–noskipduplicates` options is used. Invoke `\addbibresource` multiple +times to add more resources, for example: + + \addbibresource{bibfile1.bib} + \addbibresource{bibfile2.bib} + \addbibresource[glob]{bibfiles/bibfile*.bib} + \addbibresource[glob]{bibfile-num?.bib} + \addbibresource[glob]{bibfile{1,2,3}.bib} + \addbibresource[location=remote]{https://raw.githubusercontent.com/plk/biblatex/master/bibtex/bib/biblatex/biblatex-examples.bib} + \addbibresource[location=remote,label=lan]{ftp://192.168.1.57/~user/file.bib} + +Since the `resource` string is read in a verbatim-like mode, it may +contain arbitrary characters. The only restriction is that any curly +braces must be balanced. The following `options` are available: + +`bibencoding=` +This option can be used to override the global `bibencoding` option for +a particular `resource`. + +`label=` +Assigns a label to a resource. The `identifier` may be used in place of +the full resource name in the optional argument of `refsection` (see +??). The label is a *unique* identifier for the `resource`, so each +label should only be used once. + +`location=` +The location of the resource. The `location` may be either `local` for +local resources or `remote` for URLs. Remote resources require `biber`. +The protocols HTTP/HTTPS and FTP are supported. The remote URL must be a +fully qualified path to a `bib` file or a URL which returns a `bib` +file. + +`type=` +The type of resource. Currently, the only supported type is `file`. + +`datatype=` +The data type (format) of the resource. The following formats are +currently supported: + +bibtex +BibTeX format. + +biblatexml +Experimental XML format for `biblatex`. See ??. + +`glob` +Whether `biber`should glob (expand according to pattern) the datasource +name. There is a global setting for this in `biber`(false by default and +settable to true using the `–glob-datasources` option). This option +allows overriding the `biber`default on a per-resource basis. +]], + filename = "?" + }, + adddot = { + details = [[ +```latex +\adddot +``` + +Adds a period unless it is preceded by any punctuation mark. The purpose +of this command is inserting the dot after an abbreviation. Any dot +inserted this way is recognized as such by the other punctuation +commands. This command may also be used to turn a previously inserted +literal period into an abbreviation dot. +]] + }, + addhighpenspace = { + details = [[ +```latex +\addhighpenspace +``` + +Adds a space penalized by the value of the `highnamepenalty` counter, +see ?? for details. +]] + }, + addhpthinspace = { + details = [[ +```latex +\addhpthinspace +``` + +Similar to `\addhighpenspace` but adds a breakable thin space. +]] + }, + addnbspace = { + details = [[ +```latex +\addnbspace +``` + +Adds a non-breakable interword space. +]] + }, + addnbthinspace = { + details = [[ +```latex +\addnbthinspace +``` + +Adds a non-breakable thin space. This is similar to `\,` and +`\thinspace`. +]] + }, + addperiod = { + details = [[ +```latex +\addperiod +``` + +Adds a period unless it is preceded by an abbreviation dot or any other +punctuation mark. This command may also be used to turn a previously +inserted abbreviation dot into a period, for example at the end of a +sentence. +]] + }, + addquestion = { + details = [[ +```latex +\addquestion +``` + +Adds a question mark unless it is preceded by any punctuation mark +except for an abbreviation dot. +]] + }, + addsectionbib = { + action = "input", + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "resource"} + }, + details = [[ +```latex +\addsectionbib[options]{resource} +``` + +This command differs from `\addbibresource` in that the resource +`options` are registered but the `resource` not added to any resource +list. This is only required for resources which 1) are given exclusively +in the optional argument of `refsection` (??) and 2) require options +different from the default settings. In this case, `\addsectionbib` is +employed to qualify the `resource` prior to using it by setting the +appropriate `options` in the preamble. The `label` option may be useful +to assign a short name to the resource. +]], + filename = "?" + }, + addsemicolon = { + details = [[ +```latex +\addsemicolon +``` + +Adds a semicolon unless it is preceded by a comma, another semicolon, a +colon, or a period. +]] + }, + addslash = { + details = [[ +```latex +\addslash +``` + +Adds a breakable slash. This command differs from the `\slash` command +in the LaTeX kernel in that a linebreak after the slash is not penalized +at all. +]] + }, + andothersdelim = { + details = [[ +```latex +\andothersdelim +``` + +The delimiter printed before the localisation string <`andothers`> +if a name list like `author` or `editor` is truncated. The default is an +interword space. + +```latex +\andothersdelim +``` + +The delimiter to be printed before the localisation string +<`andothers`> if a name list like `author` or `editor` is +truncated. This command should be incorporated in all formatting +directives for name lists. The default is an interword space. +]] + }, + antecedent = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "quantifier=quantspec", + optional = true + }, + {meta = "fields"} + }, + details = [[ +```latex +\antecedent[quantifier=quantspec]{fields} +``` + +For constraints of `type` <conditional>, specifies a quantified set +of `\constraintfield`s which must be satisfied before the `\consequent` +of the constraint is checked. `quantspec` should have one of the +following values: + +`quantifier={all, one, none}` +Specifies how many of the `\constrainfield`'s inside the `\antecedent` +have to be present to satisfy the antecedent of the conditional +constraint. +]] + }, + assignrefcontextcats = { + arguments = { + {literal = "*", optional = true}, + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + }, + {meta = "category1, category2, ..."} + }, + details = [[ +```latex +\assignrefcontextkeyws[key=value, ... ]{keyword1,keyword2, ...} +\assignrefcontextkeyws*[key=value, ... ]{keyword1,keyword2, ...} +\assignrefcontextcats[key=value, ... ]{category1, category2, ...} +\assignrefcontextcats*[key=value, ... ]{category1, category2, ...} +\assignrefcontextentries[key=value, ... ]{entrykey1, entrykey2, ...} +\assignrefcontextentries*[key=value, ... ]{entrykey1, entrykey2, ...} +\assignrefcontextentries[key=value, ... ]{*} +\assignrefcontextentries*[key=value, ... ]{*} +``` + + +]] + }, + assignrefcontextentries = { + arguments = { + {literal = "*", optional = true}, + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + }, + {meta = "entrykey1, entrykey2, ..."} + }, + details = "$ref:biblatex.sty#/commands/assignrefcontextcats/details" + }, + assignrefcontextkeyws = { + arguments = { + {literal = "*", optional = true}, + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + }, + {meta = "keyword1,keyword2, ..."} + }, + details = "$ref:biblatex.sty#/commands/assignrefcontextcats/details" + }, + authortypedelim = { + details = [[ +```latex +\authortypedelim +``` + +The delimiter printed between the author and the `authortype`. The +default is a comma followed by a space. +]] + }, + autocite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\autocite[prenote][postnote]{key} +\Autocite[prenote][postnote]{key} +``` + +In contrast to other citation commands, the `\autocite` command does not +only scan ahead for punctuation marks following its last argument to +avoid double punctuation marks, it actually moves them around if +required. For example, with `autocite=footnote`, a trailing punctuation +mark will be moved such that the footnote mark is printed after the +punctuation. `\Autocite` is similar to `\autocite` but capitalizes the +name prefix of the first name in the citation if the `useprefix` option +is enabled, provided that there is a name prefix and the citation style +prints any name at all. +]] + }, + begrelateddelim = { + details = [[ +```latex +\begrelateddelim +``` + +The generic separator before the block of related entries. The default +definition is `\newunitpunct`. +]] + }, + bibbycategory = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + } + }, + details = [[ +```latex +\bibbycategory[key=value, ... ] +``` + +This command loops over all bibliography categories. This is equivalent +to giving one `\printbibliography` command for every category but has +the additional benefit of automatically skipping empty categories. The +categories are processed in the order in which they were declared. See +?? for usage examples. The options are a subset of those supported by +`\printbibliography`. Valid options are `env`, `prenote`, `postnote`, +`section`. Note that `heading` is not available with this command. The +name of the current category is automatically used as the heading name. +This is equivalent to passing `heading=category` to `\printbibliography` +and implies that there must be a matching heading definition for every +category. The current bibliography context sorting template is used for +all categories (see ??). +]] + }, + bibbysection = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + } + }, + details = [[ +```latex +\bibbysection[key=value, ... ] +``` + +This command automatically loops over all reference sections. This is +equivalent to giving one `\printbibliography` command for every section +but has the additional benefit of automatically skipping sections +without references. Note that `\bibbysection` starts looking for +references in section `1`. It will ignore references given outside of +`refsection` environments since they are assigned to section 0. See ?? +for usage examples. The options are a subset of those supported by +`\printbibliography`. Valid options are `env`, `heading`, `prenote`, +`postnote`. The current bibliography context sorting template is used +for all sections (see ??). +]] + }, + bibcpsstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibcpsstring[wrapper]{key} +``` + +Similar to `\bibsstring` but the term is always capitalized. +]] + }, + bibcpstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibcpstring[wrapper]{key} +``` + +Similar to `\bibstring` but the term is always capitalized. +]] + }, + bibdateeraprefix = { + details = [[ +```latex +\bibdateeraprefix +``` + +The language specific marker which is printed as a prefix to beginning +BCE/BC dates in a date range when the option `dateera` is set to +<astronomical>. Defaults to `\textminus`, if defined and +`\textendash` otherwise. +]] + }, + bibdatesep = { + details = [[ +```latex +\bibdatesep +``` + +The language specific separator used between date components in terse +date formats. Defaults to `\hyphen`. +]] + }, + bibdatetimesep = { + details = [[ +```latex +\bibdatetimesep +``` + +The language specific separator printed between date and time components +when printing time components along with date components (see the +`dateusetime` option in ??). Defaults to a space for +non-ISO8601-2 output formats, and 'T' for ISO8601-2 output format. +]] + }, + bibeidpunct = { + details = [[ +```latex +\bibeidpunct +``` + +The separator printed before the `eid` field (similar to +`\bibpagespunct`). The default is a comma plus an interword space. +]] + }, + bibellipsis = { + details = [[ +```latex +\bibellipsis +``` + +An ellipsis symbol with brackets: <\[...\]>. +]] + }, + bibfootnotewrapper = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\bibfootnotewrapper{text} +``` + +An inner wrapper which encloses the `text` argument of `\mkbibfootnote` +and `\mkbibfootnotetext`. For example, `\mkbibfootnote` eventually boils +down to this: + + \footnote{<<\bibfootnotewrapper{>>text<<}>>} + +The wrapper ensures capitalization at the beginning of the note and adds +a period at the end. The default definition is: + + \newcommand{\bibfootnotewrapper}[1]{<<\bibsentence>> #1<<\addperiod>>} + +If you don't want capitalization at the beginning or a period at the end +of the note, do not modify `\mkbibfootnote` but redefine +`\bibfootnotewrapper` instead. +]] + }, + bibhang = { + details = [[ +```latex +\bibhang +``` + +The hanging indentation of the bibliography, if applicable. This length +is initialized to `\parindent` at load-time. If `\parindent` is zero +length for some reason, `\bibhang` will default to `1em`. +]] + }, + bibhyperref = { + arguments = { + {delimiters = {"[", "]"}, meta = "entrykey", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\bibhyperref[entrykey]{text} +``` + +Transforms `text` into an internal link pointing to `entrykey` in the +bibliography. If `entrykey` is omitted, this command uses the key of the +entry currently being processed. This command is employed to transform +citations into clickable links pointing to the corresponding entry in +the bibliography. The link target is marked automatically by `biblatex`. +If there are multiple bibliographies in a document, the target will be +the first occurence of `entrykey` in one of the bibliographies. If there +are `refsection` environments, the links are local to the environment. +See also the formatting directive `bibhyperref` in ??. +]] + }, + bibhypertarget = { + arguments = {{meta = "name"}, {meta = "text"}}, + details = [[ +```latex +\bibhypertarget{name}{text} +``` + +A wrapper for `hyperref`'s `\hypertarget` command. The `name` is the +name of the anchor, the `text` is arbitrary printable text or code which +serves as an anchor. If there are any `refsection` environments in the +document, the `name` is local to the current environment. If the +`hyperref` package option is disabled or the `hyperref` package has not +been loaded, this command will simply pass on its `text` argument. See +also the formatting directive `bibhypertarget` in ??. +]] + }, + bibindexinithyphendelim = { + details = [[ +```latex +\bibindexinithyphendelim +``` + +Replaces `\bibinithyphendelim` in the index. +]] + }, + bibindexinitperiod = { + details = [[ +```latex +\bibindexinitperiod +``` + +Replaces `\bibinitperiod` in the index. +]] + }, + bibindexnamedelimb = { + details = [[ +```latex +\bibindexnamedelimb +``` + +Replaces `\bibnamedelimb` in the index. +]] + }, + bibindexnamedelimd = { + details = [[ +```latex +\bibindexnamedelimd +``` + +Replaces `\bibnamedelimd` in the index. +]] + }, + bibinithyphendelim = { + details = [[ +```latex +\bibinithyphendelim +``` + +The punctuation inserted automatically by the backend between the +initials of hyphenated name parts, replacing `\bibinitperiod` and +`\bibinitdelim`. The default definition is a period followed by an +unbreakable hyphen. Please refer to ?? for further details. +]] + }, + bibinitperiod = { + details = [[ +```latex +\bibinitperiod +``` + +The punctuation inserted automatically by the backend after all initials +unless `\bibinithyphendelim` applies. The default definition is a period +(`\adddot`). Please refer to ?? for further details. +]] + }, + bibinitsep = { + details = [[ +```latex +\bibinitsep +``` + +Vertical space to be inserted between two entries in the bibliography +whenever an entry starts with a letter which is different from the +initial letter of the previous entry. The default value is zero. Setting +this length to a positive value greater than `bibitemsep` will group the +bibliography alphabetically. Note that `bibitemsep`, `bibnamesep`, and +`bibinitsep` obey the rules for `\addvspace`, that is, when vertical +space introduced by any of these commands immediately follows on from +space introduced by another of them, the resulting total space is equal +to the largest of them. +]] + }, + bibitemsep = { + details = [[ +```latex +\bibitemsep +``` + +The vertical space between the individual entries in the bibliography. +This length is initialized to `\itemsep` at load-time. Note that +`bibitemsep`, `bibnamesep`, and `bibinitsep` obey the rules for +`\addvspace`, that is, when vertical space introduced by any of these +commands immediately follows on from space introduced by another of +them, the resulting total space is equal to the largest of them. + +```latex +\bibitemsep +``` + +The vertical space between the individual entries in the bibliography. +Bibliography styles using `list` environments should set `itemsep` to +`bibitemsep` in the definition of the respective environment. This +length is initialized to `\itemsep` at load-time. +]] + }, + biblcsstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\biblcsstring[wrapper]{key} +``` + +Similar to `\bibsstring` but the whole term is lowercased. +]] + }, + biblcstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\biblcstring[wrapper]{key} +``` + +Similar to `\bibstring` but the whole term is lowercased. +]] + }, + bibnamedash = { + details = [[ +```latex +\bibnamedash +``` + +The dash to be used as a replacement for recurrent authors or editors in +the bibliography. The default is an <em> or an <en> dash, +depending on the indentation of the list of references. +]] + }, + bibnamedelimb = { + details = [[ +```latex +\bibnamedelimb +``` + +This delimiter controls the spacing between the elements which make up a +name part. It is inserted automatically by the backend between all name +elements where `\bibnamedelima` does not apply. The default definition +is `\addlowpenspace`, i.e. a space penalized by the value of the +`lownamepenalty` counter (??). Please refer to ?? for further details. +]] + }, + bibnamedelimd = { + details = [[ +```latex +\bibnamedelimd +``` + +This delimiter controls the spacing between name parts. The default name +formats use it between all name parts where `\bibnamedelimc` does not +apply. The default definition is `\addlowpenspace`, i.e. a space +penalized by the value of the `lownamepenalty` counter (??). Please +refer to ?? for further details. +]] + }, + bibncplstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibncplstring[wrapper]{key} +``` + +Similar to `\biblstring` but the term is never capitalized. +]] + }, + bibopenparen = { + details = [[ +```latex +\bibopenparen\bibcloseparen +``` + +Alternative syntax for `\mkbibparens`. This will also work across +groups. Note that `\bibopenparen` and `\bibcloseparen` must always be +balanced. +]] + }, + bibpagespunct = { + details = [[ +```latex +\bibpagespunct +``` + +The separator printed before the `pages` field. The default is a comma +plus an interword space. + +```latex +\bibpagespunct +``` + +The separator to be printed before the `pages` field. Use this separator +instead of `\newunitpunct` at this location. The default is a comma plus +an interword space. +]] + }, + bibrangedash = { + details = [[ +```latex +\bibrangedash +``` + +The language specific dash to be used for ranges of numbers. Defaults to +`\textendash`. +]] + }, + bibsentence = { + details = [[ +```latex +\bibsentence +``` + +This command marks the beginning of a sentence. A localisation string +immediately after this command will be capitalized and the punctuation +tracker is reset, i.e. this command hides all preceding punctuation +marks from the punctuation tracker and enforces capitalization. +]] + }, + bibsetup = { + details = [[ +```latex +\bibsetup +``` + +Arbitrary code to be executed at the beginning of the bibliography, +intended for commands which affect the layout of the bibliography. +]] + }, + bibsstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibsstring[wrapper]{key} +``` + +Similar to `\bibstring` but always prints the short string, ignoring the +`abbreviate` option. +]] + }, + bibstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibstring[wrapper]{key} +``` + +Prints the localisation string `key`, where `key` is an identifier in +lowercase letters (see ??). The string will be capitalized as required, +see ?? for details. Depending on the `abbreviate` package option from +??, `\bibstring` prints the short or the long version of the string. If +localisation strings are nested, i.e. if `\bibstring` is used in another +string, it will behave like `\bibxstring`. If the `wrapper` argument is +given, the string is passed to the `wrapper` for formatting. This is +intended for font commands such as `\emph`. +]] + }, + bibtimesep = { + details = [[ +```latex +\bibtimesep +``` + +The language specific marker which separates time components. Defaults +to a colon. + +```latex +\bibtimesep +``` + +The language specific marker which separates time components. Default to +a colon. +]] + }, + bibtimezonesep = { + details = [[ +```latex +\bibtimezonesep +``` + +The language specific marker which separates an optional time zone +component from a time. Empty by default. +]] + }, + bibuclstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibuclstring[wrapper]{key} +``` + +Similar to `\biblstring` but the whole term is uppercased. +]] + }, + biburlbigbreakpenalty = { + details = [[ +```latex +\biburlbigbreakpenalty +``` + +The `biblatex` version of `url`'s `UrlBigBreakPenalty`. The default +value is `100`. +]] + }, + biburlbigskip = { + details = [[ +```latex +\biburlbigskip +``` + +The `biblatex` version of `Urlmuskip`. This length holds the additional +(stretchable) space inserted around breakable characters in the `\url` +command from the `url` package. The default value is `0mu plus 3mu`. +]] + }, + biburlbreakpenalty = { + details = [[ +```latex +\biburlbreakpenalty +``` + +The `biblatex` version of `url`'s `UrlBreakPenalty`. The default value +is `200`. +]] + }, + biburlucpenalty = { + details = [[ +```latex +\biburlucpenalty +``` + +Similar to `biburlnumpenalty`, except that it will add a breakpoint +after all uppercase letters. +]] + }, + biburlucskip = { + details = [[ +```latex +\biburlucskip +``` + +Similar to `biburlnumskip`, except that it will add space after all +uppercase letters. +]] + }, + bibxlstring = { + arguments = { + {delimiters = {"[", "]"}, meta = "wrapper", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\bibxlstring[wrapper]{key} +``` + +Similar to `\bibxstring` but always uses the long string, ignoring the +`abbreviate` option. +]] + }, + cite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = "$ref:biblatex.sty#/commands/Cite/details" + }, + citeauthor = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = "$ref:biblatex.sty#/commands/Citeauthor/details" + }, + citecount = { + action = "cite", + details = [[ +```latex +\citecount +``` + +The `\citecount` element has a special meaning. It requests a sort based +on the number of times an item was cited. The standard `count` sorting +template uses this to provide a sort in descending order of number of +citations. Note that the option `citecounter` must also be enabled for +this to work. In addition, an additional `biber`run is required in order +to calculate the data for this option correctly and so the typical +invocation sequence for this option is +*latex*$\rightarrow$*biber*$\rightarrow$*latex*$\rightarrow$*latex*$\rightarrow$*biber*$\rightarrow$*latex*. + +```latex +\citecount +``` + +This counter, which is only available in the `loopcode` of a citation +command defined with `\DeclareCiteCommand`, holds the number of the +entry key currently being processed by the `loopcode`. +]] + }, + citecounter = { + action = "cite", + details = [[ +```latex +\citecounter +``` + +This counter indicates how many times the entry currently being +processed is cited in the current reference section. Note that this +feature needs to be enabled explicitly with the package option +`citecounter`. If the option is set to `context`, citations in the body +text and in footnotes are counted separately. In this case, +`citecounter` will hold the value of the context it is used in. +]] + }, + citedate = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\citedate*[prenote][postnote]{key} +``` + +This command prints the full date (`date` or `year`). The starred +variant includes the `extradate` information, if any. +]] + }, + citefield = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "format", optional = true}, + {meta = "field"} + }, + details = [[ +```latex +\citefield[prenote][postnote]{key}[format]{field} +``` + +The `format` is a formatting directive defined with +`\DeclareFieldFormat`. Formatting directives are discussed in ??. If +this optional argument is omitted, this command falls back to the format +`citefield`. The last argument is the name of a `field`, in the sense +explained in ??. +]] + }, + citename = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "format", optional = true}, + {meta = "name list"} + }, + details = [[ +```latex +\citename[prenote][postnote]{key}[format]{name list} +``` + +The `format` is a formatting directive defined with +`\DeclareNameFormat`. Formatting directives are discussed in ??. If this +optional argument is omitted, this command falls back to the format +`citename`. The last argument is the name of a `name list`, in the sense +explained in ??. +]] + }, + citereset = { + details = [[ +```latex +\citereset +``` + +This command resets the citation style. This may be useful if the style +replaces repeated citations with abbreviations like *ibidem*, *idem*, +*op. cit.*, etc. and you want to force a full citation at the beginning +of a new chapter, section, or some other location. The command executes +a style specific initialization hook defined with the +`\InitializeCitationStyle` command from ??. It also resets the internal +citation trackers of this package. The reset will affect the +`\ifciteseen`, `\ifentryseen`, `\ifciteibid`, and `\ifciteidem` tests +discussed in ??. When used inside a `refsection` environment, the reset +of the citation tracker is local to the current `refsection` +environment. Also see the `citereset` package option in ??. +]] + }, + cites = { + action = "cites", + details = "$ref:biblatex.sty#/commands/Cites/details" + }, + citesetup = { + details = [[ +```latex +\citesetup +``` + +Arbitrary code to be executed at the beginning of each citation command. +]] + }, + citetitle = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\citetitle*[prenote][postnote]{key} +``` + +This command prints the title. It will use the abridged title in the +`shorttitle` field, if available. Otherwise it falls back to the full +title found in the `title` field. The starred variant always prints the +full title. +]] + }, + citeyear = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\citeyear*[prenote][postnote]{key} +``` + +This command prints the year (`year` field or year component of `date`). +The starred variant includes the `extradate` information, if any. +]] + }, + clearfield = { + arguments = {{meta = "field"}}, + details = [[ +```latex +\clearfield{field} +``` + +Clears the `field` within a local scope. A field cleared this way is +treated as undefined by subsequent data commands. +]] + }, + clearname = { + arguments = {{meta = "name list"}}, + details = [[ +```latex +\clearname{name list} +``` + +Clears the `name list` within a local scope. A list cleared this way is +treated as undefined by subsequent data commands. +]] + }, + command = { + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "keys"} + }, + details = [[ +```latex +\command[prenote][postnote]{keys} +``` + +If the `autopunct` package option from ?? is enabled, they will scan +ahead for any `punctuation` immediately following their last argument. +This is useful to avoid spurious punctuation marks after citations. This +feature is configured with `\DeclareAutoPunctuation`, see ?? for +details. +]] + }, + compcitedelim = { + details = [[ +```latex +\compcitedelim +``` + +Similar to `\multicitedelim`, but used by certain citation styles when +<compressing> multiple citations. The default definition is a comma +plus an interword space. + +```latex +\compcitedelim +``` + +Similar to `\multicitedelim`, but intended for citation styles that +<compress> multiple citations, i.e. print the author only once if +subsequent citations share the same author etc. The default definition +is a comma plus an interword space. +]] + }, + constraintfield = { + arguments = {{meta = "field"}}, + details = [[ +```latex +\constraintfield{field} +``` + +For constraints of `type` <data>, the constraint applies to this +`field`. For constraints of `type` <mandatory>, the entry must +contain this `field`. + +The data model declaration macros may be used multiple times as they +append to the previous definitions. In order to replace, change or +remove existing definitions (such as the default model which is loaded +with `biblatex`), you should reset (clear) the current definition and +then set what you want using the following macros. Typically, these +macros will be the first things in any `biblatex-dm.cfg` file: +]] + }, + constraintfieldsor = { + arguments = {{meta = "fields"}}, + details = [[ +```latex +\constraintfieldsor{fields} +``` + +For constraints of `type` <mandatory>, specifies that an entry must +contain a boolean OR of the `\constraintfield`s. +]] + }, + csfield = { + arguments = {{meta = "field"}}, + details = [[ +```latex +\csfield{field} +``` + +Similar to `\thefield`, but prevents expansion. +]] + }, + currentfield = { + details = [[ +```latex +\currentfield +``` + +The name of the field currently being processed by `\printfield`. This +information is only available locally in field formatting directives. +]] + }, + currentname = { + details = [[ +```latex +\currentname +``` + +The name of the name list currently being processed by `\printnames`. +This information is only available locally in name formatting +directives. +]] + }, + datecircadelim = { + details = [[ +```latex +\datecircadelim +``` + +When formatting dates with the global option `datecirca` enabled, the +delimiter printed after any localised <circa> term. Defaults to +interword space. +]] + }, + datecircaprint = { + details = [[ +```latex +\datecircaprint +``` + +Prints date circa information when the global option `datecirca` is +enabled and the `\ifdatecirca` test is true. By default, prints the +<circa> localised term (??) and the `datecircadelim` delimiter. +]] + }, + datecircaprintiso = { + details = [[ +```latex +\datecircaprintiso +``` + +Prints ISO8601-2 format date circa information when the global option +`datecirca` is enabled and the `\ifdatecirca` test is true. Prints +`\textasciitilde`. +]] + }, + dateeradelim = { + details = [[ +```latex +\dateeradelim +``` + +When formatting dates with the global option `dateera` set, the +delimiter printed before the localisation era term. Defaults to +interword space. +]] + }, + dateeraprint = { + arguments = {{meta = "yearfield"}}, + details = [[ +```latex +\dateeraprint{yearfield} +``` + +Prints date era information when the global option `dateera` is set to +<secular> or <christian>. By default, prints the `dateeradelim` +delimiter and the appropriate localised era term (??). If the +`dateeraauto` option is set, then the passed `yearfield` (which is the +name of a year field such as <year>, <origyear>, <endeventyear> +etc.) is tested to see if its value is earlier than the `dateeraauto` +threshold and if so, then the BCE/CE localisation will be output too. +The default setting for `dateeraauto` is 0 and so only BCE/BC +localisation strings are candidates for output. Detects whether the +start or end year era information is to be printed by looking at the +`yearfield` name passed to it. +]] + }, + dateeraprintpre = { + details = [[ +```latex +\dateeraprintpre +``` + +Prints date era information when the global option `dateera` is set to +<astronomical>. By default, prints `bibdataeraprefix`. Detects +whether the start or end year era information is to be printed by +looking at the `yearfield` name passed to it. +]] + }, + dateuncertainprint = { + details = [[ +```latex +\dateuncertainprint +``` + +Prints date uncertainty information when the global option +`dateuncertain` is enabled and the `\ifdateuncertain` test is true. By +default, prints the language specific `\bibdateuncertain` string (??). +]] + }, + defbibcheck = { + arguments = {{meta = "name"}, {meta = "code"}}, + details = [[ +```latex +\defbibcheck{name}{code} +``` + +Defines the custom bibliography filter `name`, to be used via the +`check` option of `\printbibliography`. `\defbibcheck` is similar in +concept to `\defbibfilter` but much more low-level. Rather than a +high-level expression, the `code` is LaTeX code, much like the code used +in driver definitions, which may perform arbitrary tests to decide +whether or not a given entry is to be printed. The bibliographic data of +the respective entry is available when the `code` is executed. Issuing +the command `\skipentry` in the `code` will cause the current entry to +be skipped. For example, the following filter will only output entries +with an `abstract` field: + + \defbibcheck{<>}{% + \iffieldundef{abstract}{<<\skipentry>>}{}} + ... + \printbibliography[<>] + +The following check will exclude all entries published before the year +2000: + + \defbibcheck{recent}{% + \iffieldint{year} + {\ifnumless{\thefield{year}}{2000} + {\skipentry} + {}} + {\skipentry}} + +See the author guide, in particular ??, for further details. +]] + }, + defbibentryset = { + arguments = {{meta = "key"}, {meta = "key1,key2,key3, ... "}}, + details = [[ +```latex +\defbibentryset{key}{key1,key2,key3, ... } +``` + +The `key` is the entry key of the set, which is used like any other +entry key when referring to the set. The `key` must be unique and it +must not conflict with any other entry key. The second argument is a +comma-separated list of the entry keys which make up the set. +`\defbibentryset` implies the equivalent of a `\nocite` command, i.e. +all sets which are declared are also added to the bibliography. When +declaring the same set more than once, only the first invocation of +`\defbibentryset` will define the set. Subsequent definitions of the +same `key` are ignored and work like `\nocite``key`. Dynamic entry sets +defined in the document body are local to the enclosing `refsection` +environment, if any. Otherwise, they are assigned to reference +section 0. Those defined in the preamble are assigned to reference +section 0. See ?? for further details. +]] + }, + defbibenvironment = { + arguments = { + {meta = "name"}, + {meta = "begin code"}, + {meta = "end code"}, + {meta = "item code"} + }, + details = [[ +```latex +\defbibenvironment{name}{begin code}{end code}{item code} +``` + +This command defines bibliography environments. The `name` is an +identifier passed to the `env` option of `\printbibliography` and +`\printbiblist` when selecting the environment. The `begin code` is +LaTeX code to be executed at the beginning of the environment; the +`end code` is executed at the end of the environment; the `item code` is +code to be executed at the beginning of each entry in the bibliography +or a bibliography list. Here is an example of a definition based on the +standard LaTeX `list` environment: + + \defbibenvironment{bibliography} + {\list{} + {\setlength{\leftmargin}{\bibhang}% + \setlength{\itemindent}{-\leftmargin}% + \setlength{\itemsep}{\bibitemsep}% + \setlength{\parsep}{\bibparsep}}} + {\endlist} + {\item} + +As seen in the above example, usage of `\defbibenvironment` is roughly +similar to `\newenvironment` except that there is an additional +mandatory argument for the `item code`. +]] + }, + defbibfilter = { + arguments = {{meta = "name"}, {meta = "expression"}}, + details = [[ +```latex +\defbibfilter{name}{expression} +``` + +Defines the custom bibliography filter `name`, to be used via the +`filter` option of `\printbibliography`. The `expression` is a complex +test based on the logical operators `and`, `or`, `not`, the group +separator `(...)`, and the following atomic tests: +]] + }, + defbibnote = { + arguments = {{meta = "name"}, {meta = "text"}}, + details = [[ +```latex +\defbibnote{name}{text} +``` + +Defines the bibliography note `name`, to be used via the `prenote` and +`postnote` options of `\printbibliography` and `\printbiblist`. The +`text` may be any arbitrary piece of text, possibly spanning several +paragraphs and containing font declarations. Also see ??. +]] + }, + delimcontext = { + arguments = {{meta = "context"}}, + details = [[ +```latex +\delimcontext{context} +``` + +Set the delimiter context to `context`. This setting is not global so +that delimiter contexts can be nested using the usual LaTeX group +method. +]] + }, + docsvfield = { + arguments = {{meta = "field"}}, + details = [[ +```latex +\docsvfield{field} +``` + +Similar to the `\docsvlist` command from the `etoolbox` package, except +that it takes a field name as its argument. The value of this field is +parsed as a comma-separated list. If the `field` is undefined, this +command expands to an empty string. +]] + }, + enddatecircaprint = { + details = [[ +```latex +\enddatecircaprint +``` + +Prints date circa information when the global option `datecirca` is +enabled and the `\ifenddatecirca` test is true. By default, prints the +<circa> localised term (??) and the `datecircadelim` delimiter. +]] + }, + enddatecircaprintiso = { + details = [[ +```latex +\enddatecircaprintiso +``` + +Prints ISO8601-2 format date circa information when the global option +`datecirca` is enabled and the `\ifenddatecirca` test is true. Prints +`\textasciitilde`. +]] + }, + enddateuncertainprint = { + details = [[ +```latex +\enddateuncertainprint +``` + +Prints date uncertainty information when the global option +`dateuncertain` is enabled and the `\ifenddateuncertain` test is true. +By default, prints the language specific `\bibdateuncertain` string +(??). +]] + }, + entrydata = { + arguments = {{literal = "*", optional = true}, {meta = "key"}, {meta = "code"}}, + details = [[ +```latex +\entrydata{key}{code} +\entrydata*{key}{code} +``` + +Data commands like `\printfield` normally use the data of the entry +currently being processed. You may use `\entrydata` to switch contexts +locally. The `key` is the entry key of the entry to use locally. The +`code` is arbitrary code to be executed in this context. This code will +be executed in a group. See ?? for an example. Note that this command +will automatically switch languages if the `autolang` package option is +enabled. The starred version `\entrydata*` will clone all fields of the +enclosing entry, using field, counter, and other resource names prefixed +with the string <`saved`>. This is useful when comparing two data +sets. For example, inside the `code` argument, the `author` field holds +the author of entry `key` and the author of the enclosing entry is +available as `savedauthor`. The `author` counter holds the number of +names in the `author` field of `key`; the `savedauthor` counter refers +to the author count of the enclosing entry. +]] + }, + entrysetpunct = { + details = [[ +```latex +\entrysetpunct +``` + +The punctuation printed between bibliography subentries of an entry set. +The default definition is a semicolon and a space. +]] + }, + extpostnotedelim = { + details = [[ +```latex +\extpostnotedelim +``` + +The delimiter printed between the citation and the parenthetical +`postnote` argument of a citation command when the postnote occurs +outside of the citation parentheses. In the standard styles, this occurs +when the citation uses the shorthand field of the entry. The default is +an interword space. +]] + }, + field = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "field"} + }, + details = [[ +```latex +\field[options]{field} +``` + +If `field` is non-empty, use it as the current label `\labelelement`, +subject to the options below. Useful values for `field` are typically +the name list type fields, date fields, and title fields. You may also +use the 'citekey' or 'entrykey' pseudo-fields to specify the +citation/entry key as part of the label. Name list fields are treated +specially and when a name list field is specified, the template defined +with `\DeclareLabelalphaNameTemplate` is used to extract parts from the +name which then returns the string that the `\field` option uses. + +`final` +This option marks a `\field` directive as the final one in the +`specification`. If the `field` is non-empty, then this field is used +for the label and the remainder of the `specification` will be ignored. +The short form `final` is equivalent to `final=true`. + +`lowercase` +Forces the label part derived from the field to lowercase. By default, +the case is taken from the field source and not modified. + +`strwidth` +The number of characters of the `field` to use. This setting may be +overridden by an individual name part when extracting characters from a +name. See `\DeclareLabelalphaNameTemplate` below. + +`strside={left, right}` +The side of the string from which to take the `strwidth` number of +characters. This setting may be overridden by an individual name part +when extracting characters from a name. See +`\DeclareLabelalphaNameTemplate` below. + +`padside={left, right}` +Side to pad the label part when using the `padchar` option. Only for use +with fixed-width label strings (`strwidth`). + +`padchar=` +If present, pads the label part on the `padside` side with the specified +character to the length of `strwidth`. Only for use with fixed-width +label strings (`strwidth`). + +`uppercase` +Forces the label part derived from the field to uppercase. By default, +the case is taken from the field source and not modified. + +`varwidth` +Use a variable width, left-side substring of characters from the string +returned for `field`. The length of the string is determined by the +minimum length needed to disambiguate the substring from all other +`field` elements in the same position in the label. For name list +fields, this means that each name substring is disambiguated from all +other name substrings which occur in the same position in the name list +(see examples below). This option overrides `strwidth` if both are used. +The short form `varwidth` is equivalent to `varwidth=true`. For name +list fields, the `\namepart`s with the `pre` option set are prepended to +the string returned from this disambiguation. + +`varwidthnorm` +As `varwidth` but will force the disambiguated substrings for the +`field` to be the same length as the longest disambiguated substring. +This can be used to regularise the format of the labels if desired. This +option overrides `strwidth` if both are used. The short form +`varwidthnorm` is equivalent to `varwidthnorm=true`. + +`varwidthlist` +Alternative method of automatic label disambiguation where the field as +a whole is disambiguated from all other fields in the same label +position. For non-name list fields, this is equivalent to `varwidth`. +For name list fields, names in a name list are not disambiguated from +other names in the same position in their name lists but instead the +entire name list is disambiguated as a whole from other name lists (see +examples below). This option overrides `strwidth` if both are used. The +short form `varwidthlist` is equivalent to `varwidthlist=true`. For name +list fields, the `\namepart`s with the `pre` option set are prepended to +the string returned from this disambiguation. + +`strwidthmax` +When using `varwidth`, this option sets a limit (in number of +characters) on the length of variable width substrings. This option can +be used to regularise the label. + +`strfixedcount` +When using `varwidthnorm`, there must be at least `strfixedcount` +disambiguated substrings with the same, maximal length to trigger the +forcing of all disambiguated substrings to this same maximal length. + +`ifnames=` +Only use this `\field` specification if it is a name list field with a +number of names matching the `ifnames` range value. This allows a +`\labelelement` to be conditionalised on name length (see below). The +range can specified as in the following examples: + + ifnames=3 -> Only apply to name lists containing exactly 3 names + ifnames={2-4} -> Only apply to name lists containing minimum 2 and maximum 4 names + ifnames={-3} -> Only apply to name lists containing at most 3 names + ifnames={2-} -> Only apply to name lists containing at least 2 names + +`names=` +By default, for name list fields, the names used range from the first +name to the `maxalphanames`/`minalphanames` truncation. This option can +be used to override this with an explicit range of names to consider. +The plus <+> sign is a special end of range marker denoting the +truncation point of max/minalphanames. The range separator can be any +number of characters with the Unicode Dash property. For example: + + names=3 -> Use first 3 names in the name list + names={2-3} -> Use second and thirds names only + names={-3} -> Same as 1-3 + names={2-} -> Use all names starting with the second name (ignoring max/minalphanames truncation) + names={2-+} -> Use all names starting with the second name (respecting max/minalphanames truncation) + +`namessep=` +An arbitrary string separator to put between names in a namelist. + +`noalphaothers` +By default, `\labelalphaothers` is appended to label parts derived from +name lists if there are more names in the list than are shown in the +label part. This option can be used to disable the default behaviour. + +```latex +\field[key=value, ... ]{field} +``` + +The `\field` element adds a `field` to the sorting specification. If the +`field` is undefined, the element is skipped. The `\field` command +supports the following optional arguments: + +`padside={left, right}` +Pads a field on the `left` or `right` side using `padchar` so that its +width is `padwidth`. If no padding option is set, no padding is done at +all. If any padding option is specified, then padding is performed and +the missing options are assigned built-in default values. If padding and +substring matching are both specified, the substring match is performed +first. + +`padwidth` +The target width in characters. + +`padchar=` +The character to be used when padding the field. + +`strside={left, right}` +Performs a substring match on the `left` or `right` side of the field. +The number of characters to match is specified by the corresponding +`strwidth` option. If no substring option is set, no substring matching +is performed at all. If any substring option is specified, then +substring matching is performed and the missing options are assigned +built-in default values. If padding and substring matching are both +specified, the substring match is performed first. + +`strwidth` +The number of characters to match. +]] + }, + fieldhascomputableequivalent = { + arguments = {{meta = "field"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\fieldhascomputableequivalent{field}{true}{false} +``` + +Similar to `\hascomputableequivalent`, but uses the value of a `field` +rather than a literal string in the test. If the `field` is undefined, +it executes `false`. +]] + }, + filteror = { + arguments = {{meta = "type"}, {meta = "filters"}}, + details = [[ +```latex +\filteror{type}{filters} +``` + +A wrapper around one or more `\filter` commands specifying that they +form a disjunctive set, i.e. any one of the `filters` must be satisfied. +]] + }, + finalandsemicolon = { + details = [[ +```latex +\finalandsemicolon +``` + +Prints the semicolon to be inserted before the final <and> in a list +of lists, if applicable in the respective language. Here is an example: + + Goossens, Mittelbach, and Samarin; Bertram and Wenworth<<;>> and Knuth + +`\finalandsemicolon` is the semicolon before the word <and>. See also +`\textcitedelim` in ??. + +```latex +\finalandsemicolon +``` + +Prints the semicolon to be inserted before the final <and> in an +enumeration, if applicable in the respective language. +]] + }, + finallistdelim = { + details = [[ +```latex +\finallistdelim +``` + +The delimiter printed instead of `\multilistdelim` before the final item +in a literal list. The default is the localised term <and>, separated +by interword spaces. See `\finalnamedelim` for further explanation. + +```latex +\finallistdelim +``` + +Use this command instead of `\multilistdelim` before the final item in a +literal list. The default is the localised term <and>, separated by +interword spaces. +]] + }, + finalnamedelim = { + details = [[ +```latex +\finalnamedelim +``` + +The delimiter printed instead of `\multinamedelim` before the final name +in a name list. The default is the localised term <and>, separated by +interword spaces. Here is an example: + + Michel Goossens<<,>> Frank Mittelbach <> Alexander Samarin + Edward Jones <> Joe Williams + +The comma in the first example is the `\multinamedelim` whereas the +string <and> in both examples is the `\finalnamedelim`. See also +`\finalandcomma` in ??. + +```latex +\finalnamedelim +``` + +Use this command instead of `\multinamedelim` before the final name in a +name list. The default is the localised term <and>, separated by +interword spaces. +]] + }, + finentry = { + details = [[ +```latex +\finentry +``` + +Inserts `\finentrypunct`. This command should be used at the very end of +every bibliography entry. +]] + }, + footcitetext = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\footcitetext[prenote][postnote]{key} +``` + +These command use a format similar to `\cite` but put the entire +citation in a footnote and add a period at the end. In the footnote, +they automatically capitalize the name prefix of the first name if the +`useprefix` option is enabled, provided that there is a name prefix and +the citation style prints any name at all. `\footcitetext` differs from +`\footcite` in that it uses `\footnotetext` instead of `\footnote`. +]] + }, + footcitetexts = { + action = "cite", + details = [[ +```latex +\footcitetexts(multiprenote)(multipostnote)[prenote][postnote]{key}|...|[prenote][postnote]{key} +``` + +The multicite version of `\footcite` and `\footcitetext`, respectively. +]] + }, + footfullcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\footfullcite[prenote][postnote]{key} +``` + +Similar to `\fullcite` but puts the entire citation in a footnote and +adds a period at the end. +]] + }, + forceY = { + details = [[ +```latex +\forceY +``` + +Similar to `\forceE` but enforces <y>. +]] + }, + forcezerosy = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\forcezerosy{integer} +``` + +This command adds zeros to a year (or any number supposed to be +4-digits). It is intended for date formatting and ordinals. The argument +is expanded with `\protected@edef` before it is processed. +]] + }, + ftvolcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {meta = "volume"}, + {delimiters = {"[", "]"}, meta = "pages", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\ftvolcite[prenote]{volume}[pages]{key} +``` + +Similar to `\volcite` but based on `\footcite` and `\footcitetext`, +respectively. +]] + }, + getfieldannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + } + }, + details = [[ +```latex +\getfieldannotation[field][annotationname] +``` + +Retrieves any literal annotation for the field `field`. If +`annotationname` is not given, then the annotation named <default> is +assumed (this is the name given to annotations defined without an +explicit name). If `field` is not given, the current data field as +indicated by `\currentfield`, `\currentlist` or `\currentname` (see ??) +is assumed. Of course, this is only possible if these commands are +defined, that is, inside formatting directives. +]] + }, + getpartannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + }, + {delimiters = {"[", "]"}, meta = "item", optional = true}, + {meta = "part"} + }, + details = [[ +```latex +\getpartannotation[field][annotationname][item]{part} +``` + +Retrieves any literal annotation for the part `part`. If +`annotationname` is not given, then the annotation named <default> is +assumed (this is the name given to annotations defined without an +explicit name). The two optional arguments `field` and `item` can be +inferred as in `\getitemannotation`. The parameter `part` can never be +inferred and is therefore a mandatory argument. + +Date fields are special and handled in a context where `\currentfield` +is not accessible. Thus there is a fourth command to access literal +annotations for dates. +]] + }, + hasfieldannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + }, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\hasfieldannotation[field][annotationname]{true}{false} +``` + +Executes `true` if the data field `field` has a literal annotation +`annotationname` defined and false otherwise. If `annotationname` is not +given, then the annotation named <default> is assumed (this is the +name given to annotations defined without an explicit name). If `field` +is not given, the current data field as indicated by `\currentfield`, +`\currentlist` or `\currentname` (see ??) is assumed. Of course, this is +only possible if these commands are defined, that is, inside formatting +directives. +]] + }, + haspartannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + }, + {delimiters = {"[", "]"}, meta = "item", optional = true}, + {meta = "part"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\haspartannotation[field][annotationname][item]{part}{true}{false} +``` + +Executes `true` if the part named `part` in the item `item` in the data +field `field` has a literal annotation `annotationname` defined and +false otherwise. If `annotationname` is not given, then the annotation +named <default> is assumed (this is the name given to annotations +defined without an explicit name). The two optional arguments `field` +and `item` can be inferred as in `\ifitemannotation`. The parameter +`part` can never be inferred and is therefore a mandatory argument. + +Date fields are special and handled in a context where `\currentfield` +is not accessible. Thus there is a fourth command to test the existence +of annotations for dates. +]] + }, + hyphenate = { + details = [[ +```latex +\hyphenate +``` + +A conditional hyphen. In contrast to the standard `\-` command, this one +allows hyphenation in the rest of the word. It is similar to the `"-` +shorthand provided by some language modules of the `babel`/`polyglossia` +packages. +]] + }, + ifbibindex = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifbibindex{true}{false} +``` + +Expands to `true` or `false` depending on the `indexing` option from ??. +]] + }, + ifbibxstring = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifbibxstring{string}{true}{false} +``` + +Similar to `\ifbibstring`, but the `string` is expanded. +]] + }, + ifboolexpr = { + arguments = {{meta = "expression"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifboolexpr{expression}{true}{false} +``` + +`etoolbox` command which allows for complex tests with boolean operators +and grouping: + + {} + \ifboolexpr{ ( + test {\ifnameundef{editor}} + and + not test {\iflistundef{location}} + ) + or test {\iffieldundef{year}} + } + {...} + {...} +]] + }, + ifcapital = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifcapital{true}{false} +``` + +Executes `true` if `biblatex`'s punctuation tracker would capitalize a +localisation string at the current location, and `false` otherwise. This +command is robust. It may be useful for conditional capitalization of +certain parts of a name in a formatting directive. +]] + }, + ifciteibid = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifciteibid{true}{false} +``` + +Expands to `true` if the entry currently being processed is the same as +the last one, and to `false` otherwise. This command is intended for use +in citation styles. If there are any `refsection` environments in the +document, the tracking is local to these environments. Note that the +<ibidem> tracker needs to be enabled explicitly with the package +option `ibidtracker`. The behavior of this test depends on the mode the +tracker is operating in, see ?? for details. If the tracker is disabled, +the test always yields `false`. Also see the `\citetrackertrue` and +`\citetrackerfalse` switches in ??. +]] + }, + ifcurrentlist = { + arguments = {{meta = "literal list"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifcurrentlist{literal list}{true}{false} +``` + +Executes `true` if the current list is `literal list`, and `false` +otherwise. This command is robust. It is intended for use in list +formatting directives and always executes `false` when used in any other +context. +]] + }, + ifdatehastime = { + arguments = {{meta = "datetype"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdatehastime{datetype}{true}{false} +``` + +Expands to `true` if the `datetype`date is defined, has a time component +and `dateusetime` is true, and to false otherwise. +]] + }, + ifdaterangesequal = { + arguments = { + {meta = "datetype1"}, + {meta = "datetype2"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdaterangesequal{datetype1}{datetype2}{true}{false} +``` + +Expands to `true` if the two date ranges---that is the start and the end +date---`datetype1` and `datetype2` are the same. +]] + }, + ifdateunknown = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdateunknown{true}{false} +``` + +As `\ifdateunknown` but for use in `\mkbibdate*` formatting +commands (??) inside which the appropriate `\ifdateunknown` +command is aliased to this command. +]] + }, + ifdateyearsequal = { + arguments = { + {meta = "datetype1"}, + {meta = "datetype2"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdateyearsequal{datetype1}{datetype2}{true}{false} +``` + +Expands to `true` if the two dates `datetype1` and `datetype2` have the +same year and era. Since the sign of the date is saved in the era field, +years should be compared using this command to avoid confusion when the +two years have opposite signs +]] + }, + ifenddateuncertain = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifenddateuncertain{true}{false} +``` + +As `\ifenddateuncertain` but for use in `\mkbibdate*` +formatting commands (??) inside which the appropriate +`\ifenddateuncertain` command is aliased to this command. +]] + }, + ifentrycategory = { + arguments = { + {meta = "entrykey"}, + {meta = "category"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifentryseen{entrykey}{true}{false} +\ifentryinbib{entrykey}{true}{false} +\ifentrycategory{entrykey}{category}{true}{false} +\ifentrykeyword{entrykey}{keyword}{true}{false} +``` + + + +```latex +\ifentrycategory{entrykey}{category}{true}{false} +``` + +A variant of `\ifcategory` which takes an entry key as its first +argument. This is useful for testing an entry other than the one +currently processed. A user-facing version of this command is available +for use in documents see ?? +]] + }, + ifentryinbib = { + arguments = {{meta = "entrykey"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifentryseen{entrykey}{true}{false} +\ifentryinbib{entrykey}{true}{false} +\ifentrycategory{entrykey}{category}{true}{false} +\ifentrykeyword{entrykey}{keyword}{true}{false} +``` + + +]] + }, + ifentrykeyword = { + arguments = { + {meta = "entrykey"}, + {meta = "keyword"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifentryseen{entrykey}{true}{false} +\ifentryinbib{entrykey}{true}{false} +\ifentrycategory{entrykey}{category}{true}{false} +\ifentrykeyword{entrykey}{keyword}{true}{false} +``` + + + +```latex +\ifentrykeyword{entrykey}{keyword}{true}{false} +``` + +A variant of `\ifkeyword` which takes an entry key as its first +argument. This is useful for testing an entry other than the one +currently processed. A user-facing version of this command is available +for use in documents see ??. +]] + }, + ifentryseen = { + arguments = {{meta = "entrykey"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifentryseen{entrykey}{true}{false} +\ifentryinbib{entrykey}{true}{false} +\ifentrycategory{entrykey}{category}{true}{false} +\ifentrykeyword{entrykey}{keyword}{true}{false} +``` + + + +```latex +\ifentryseen{entrykey}{true}{false} +``` + +A variant of `\ifciteseen` which takes an entry key as its first +argument. Since the `entrykey` is expanded prior to performing the test, +it is possible to test for entry keys in a field such as `xref`: + + \ifentryseen{<<\thefield{xref}>>}{true}{false} + +Apart from the additional argument, `\ifentryseen` behaves like +`\ifciteseen`. A user-facing version of this command is available for +use in documents see ??. +]] + }, + ifentrytype = { + arguments = {{meta = "type"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifentrytype{type}{true}{false} +``` + +Executes `true` if the entry type of the entry currently being processed +is `type`, and `false` otherwise. +]] + }, + iffieldannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + }, + {meta = "annotation"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iffieldannotation[field][annotationname]{annotation}{true}{false} +``` + +Executes `true` if the data field `field` has an annotation `annotation` +for the annotation called `annotationname` and false otherwise. If +`annotationname` is not given, then the annotation named <default> is +assumed (this is the name given to annotations defined without an +explicit name). If `field` is not given, the current data field as +indicated by `\currentfield`, `\currentlist` or `\currentname` (see ??) +is assumed. Of course, this is only possible if these commands are +defined, that is, inside formatting directives. +]] + }, + iffieldequalcs = { + arguments = { + {meta = "field"}, + {meta = "csname"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iffieldequalcs{field}{csname}{true}{false} +``` + +Similar to `\iffieldequals` but takes the control sequence name `csname` +(without a leading backslash) as an argument, rather than a macro name. +]] + }, + iffieldformatundef = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "name"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iffieldformatundef[entry type]{name}{true}{false} +\iflistformatundef[entry type]{name}{true}{false} +\ifnameformatundef[entry type]{name}{true}{false} +\iflistwrapperformatundef[entry type]{name}{true}{false} +\ifnamewrapperformatundef[entry type]{name}{true}{false} +``` + +Expands to `true` if the formatting directive `format` is undefined, and +to `false` otherwise. +]] + }, + iffieldnum = { + arguments = {{meta = "field"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iffieldnum{field}{true}{false} +``` + +Similar to `\ifnumeral`, but uses the value of a `field` rather than a +literal string in the test. If the `field` is undefined, it executes +`false`. +]] + }, + iffieldpages = { + arguments = {{meta = "field"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iffieldpages{field}{true}{false} +``` + +Similar to `\ifpages`, but uses the value of a `field` rather than a +literal string in the test. If the `field` is undefined, it executes +`false`. +]] + }, + iffieldplusstringbibstring = { + arguments = { + {meta = "field"}, + {meta = "string"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iffieldplusstringbibstring{field}{string}{true}{false} +``` + +Similar to `\iffieldbibstring`, but appends `string` to the value of +`field` and checks if the resulting string is a known localisation key. +Expands to `false` if `field` is undefined. +]] + }, + iffieldsequal = { + arguments = { + {meta = "field 1"}, + {meta = "field 2"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iffieldsequal{field 1}{field 2}{true}{false} +``` + +Expands to `true` if the values of `field 1` and `field 2` are equal, +and to `false` otherwise. +]] + }, + iffieldxref = { + arguments = {{meta = "field"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iffieldxref{field}{true}{false} +``` + +If the `crossref`/`xref` field of an entry is defined, this command +checks if the `field` is related to the cross-referenced parent entry. +It executes `true` if the `field` of the child entry is equal to the +corresponding `field` of the parent entry, and `false` otherwise. If the +`crossref`/`xref` field is undefined, it always executes `false`. This +command is robust. See the description of the `crossref` and `xref` +fields in ?? as well as ?? for further information concerning +cross-referencing. +]] + }, + iffirstcitekey = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iffirstcitekey{true}{false} +``` + +Executes `true` if the entry currently being processed is the first one +in the citation list, and `false` otherwise. This command relies on the +`citecount`, `citetotal`, `multicitecount` and `multicitetotal` counters +(??) and thus is intended for use only in the `loopcode` of a citation +command defined with `\DeclareCiteCommand`. +]] + }, + iffirstonpage = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iffirstonpage{true}{false} +``` + +The behavior of this command is responsive to the package option +`pagetracker`. If the option is set to `page`, it expands to `true` if +the current item is the first one on the page, and to `false` otherwise. +If the option is set to `spread`, it expands to `true` if the current +item is the first one on the double-page spread, and to `false` +otherwise. If the page tracker is disabled, this test always yields +`false`. Depending on the context, the <item> may be a citation or an +entry in the bibliography or a bibliography list. Note that this test +distinguishes between body text and footnotes. For example, if used in +the first footnote on a page, it will expand to `true` even if there is +a citation in the body text prior to the footnote. Also see the +`\pagetrackertrue` and `\pagetrackerfalse` switches in ??. +]] + }, + ifinteger = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifinteger{string}{true}{false} +``` + +Executes `true` if the `string` is a positive integer, and `false` +otherwise. This command is robust. +]] + }, + ifiscomputable = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifiscomputable{string}{true}{false} +``` + +Returns `true` if `\ifinteger` or `\hascomputableequivalent` retrurns +`true` on `string` and `false` otherwise. +]] + }, + ifkomabibtotoc = { + arguments = {{meta = "true"}, {meta = "false"}}, + deprecated = true, + details = [[ +```latex +\ifkomabibtotoc{true}{false} +``` + +Expands to `true` if the class would add the bibliography to the table +of contents, and to `false` otherwise. This test is deprecated. +]] + }, + iflabelalphanametemplatename = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [=[ +```latex +\iflabelalphanametemplatename{string}{true}{false} +``` + +Expands to `true` if the `string` is equal to the current in scope +alphabetic label name template name (see [\[aut:ctm:srt\]][1]), and to +`false` otherwise. + + [1]: #aut:ctm:srt +]=] + }, + iflabeldateisdate = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iflabeldateisdate{true}{false} +``` + +Expands to `true` if labeldate is defined and was obtained from date, +and to `false` otherwise. +]] + }, + iflistequals = { + arguments = { + {meta = "literal list"}, + {meta = "macro"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\iflistequals{literal list}{macro}{true}{false} +``` + +Expands to `true` if the value of the `literal list` is equal to the +definition of `macro`, and to `false` otherwise. +]] + }, + iflistformatundef = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "name"}, + {meta = "true"}, + {meta = "false"} + }, + details = "$ref:biblatex.sty#/commands/iffieldformatundef/details" + }, + iflistundef = { + arguments = {{meta = "literal list"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iflistundef{literal list}{true}{false} +``` + +Expands to `true` if the `literal list` is undefined, and to `false` +otherwise. +]] + }, + iflistwrapperformatundef = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "name"}, + {meta = "true"}, + {meta = "false"} + }, + details = "$ref:biblatex.sty#/commands/iffieldformatundef/details" + }, + ifmemoirbibintoc = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifmemoirbibintoc{true}{false} +``` + +Expands to `true` or `false`, depending on `memoir`'s `\bibintoc` and +`\nobibintoc` switches. This is a LaTeX frontend to `memoir`'s +`\ifnobibintoc` test. Note that the logic of the test is reversed. +]] + }, + ifmorenames = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifmorenames{true}{false} +``` + +Expands to `true` if the current name list has been or will be +truncated, and to `false` otherwise. This command is intended for use in +formatting directives for name lists. It will always expand to `false` +when used elsewhere. This command performs the equivalent of an +`\ifandothers` test for the current list. If this test is negative, it +also checks if the `listtotal` counter is larger than `liststop`. This +command may be used in a formatting directive to decide if a note such +as «and others» or «et al.» is to be printed at the end of the list. +Note that you still need to check whether you are in the middle or at +the end of the list, i.e. whether `listcount` is smaller than or equal +to `liststop`, see ?? for details. +]] + }, + ifnameequalcs = { + arguments = { + {meta = "name list"}, + {meta = "csname"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifnameequalcs{name list}{csname}{true}{false} +``` + +Similar to `\ifnameequals` but takes the control sequence name `csname` +(without a leading backslash) as an argument, rather than a macro name. +]] + }, + ifnameformatundef = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "name"}, + {meta = "true"}, + {meta = "false"} + }, + details = "$ref:biblatex.sty#/commands/iffieldformatundef/details" + }, + ifnamesequal = { + arguments = { + {meta = "name list 1"}, + {meta = "name list 2"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifnamesequal{name list 1}{name list 2}{true}{false} +``` + +Expands to `true` if the values of `name list 1` and `name list 2` are +equal, and to `false` otherwise. +]] + }, + ifnamewrapperformatundef = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "name"}, + {meta = "true"}, + {meta = "false"} + }, + details = "$ref:biblatex.sty#/commands/iffieldformatundef/details" + }, + ifnamexref = { + arguments = {{meta = "name list"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifnamexref{name list}{true}{false} +``` + +Similar to `\iffieldxref` but checks if a `name list` is related to the +cross-referenced parent entry. See the description of the `crossref` and +`xref` fields in ?? as well as ?? for further information concerning +cross-referencing. +]] + }, + ifnatbibmode = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifnatbibmode{true}{false} +``` + +Expands to `true` or `false` depending on the `natbib` option from ??. +]] + }, + ifnocite = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifnocite{true}{false} +``` + +Expands to `true` if the entry was *only* included in the `.bbl` via +`\nocite`. That is, returns `false` if an entry was both `\nocite`'d and +`\cite`'d. +]] + }, + ifnumeral = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifnumeral{string}{true}{false} +``` + +Executes `true` if the `string` is an Arabic or Roman numeral, and +`false` otherwise. This command is robust. See also `\DeclareNumChars` +and `\NumCheckSetup` in ??. +]] + }, + ifopcit = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifopcit{true}{false} +``` + +This command is similar to `\ifciteibid` except that it expands to +`true` if the entry currently being processed is the same as the last +one *by this author or editor*. Note that the <opcit> tracker needs +to be enabled explicitly with the package option `opcittracker`. The +behavior of this test depends on the mode the tracker is operating in, +see ?? for details. If the tracker is disabled, the test always yields +`false`. Also see the `\citetrackertrue` and `\citetrackerfalse` +switches in ??. +]] + }, + ifpages = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifpages{string}{true}{false} +``` + +Similar to `\ifnumerals`, but also considers `\DeclarePageCommands` and +`\PagesCheckSetup` from ??. +]] + }, + ifpartannotation = { + arguments = { + {delimiters = {"[", "]"}, meta = "field", optional = true}, + { + delimiters = {"[", "]"}, + meta = "annotationname", + optional = true + }, + {delimiters = {"[", "]"}, meta = "item", optional = true}, + {meta = "part"}, + {meta = "annotation"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifpartannotation[field][annotationname][item]{part}{annotation}{true}{false} +``` + +Executes `true` if the part named `part` in item `item` in the data +field `field` has an annotation `annotation` and false otherwise. If +`annotationname` is not given, then the annotation named <default> is +assumed (this is the name given to annotations defined without an +explicit name). The two optional arguments `field` and `item` can be +inferred as in `\ifitemannotation`. The parameter `part` can never be +inferred and is therefore a mandatory argument. + +Date fields are special and handled in a context where `\currentfield` +is not accessible. Thus there is a fourth command to test annotations +for dates. +]] + }, + ifpunct = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifpunct{true}{false} +``` + +Executes `true` if preceded by any punctuation mark except for an +abbreviation dot, and `false` otherwise. +]] + }, + ifpunctmark = { + arguments = {{meta = "character"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifpunctmark{character}{true}{false} +``` + +Executes `true` if preceded by the punctuation mark `character`, and +`false` otherwise. The `character` may be a comma, a semicolon, a colon, +a period, an exclamation mark, a question mark, or an asterisk. Note +that a period denotes an end-of-sentence period. Use the asterisk to +test for the dot after an abbreviation. If this command is used in a +formatting directive for name lists, i.e. in the argument to +`\DeclareNameFormat`, the `character` may also be an apostrophe. +]] + }, + ifsortingnamekeytemplatename = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [=[ +```latex +\ifsortingnamekeytemplatename{string}{true}{false} +``` + +Expands to `true` if the `string` is equal to the current in scope +sorting name key template name (see [\[aut:ctm:srt\]][1]), and to +`false` otherwise. + + [1]: #aut:ctm:srt +]=] + }, + ifuniquebaretitle = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifuniquebaretitle{true}{false} +``` + +Expands to `true` if `labelname` is empty and there is only one work +with the title `labeltitle` and to `false` otherwise. If `labeltitle` is +not set for an entry, this will always expand to `false`. Note that this +feature needs to be enabled explicitly with the package option +`uniquebaretitle`. +]] + }, + ifuniqueprimaryauthor = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifuniqueprimaryauthor{true}{false} +``` + +Expands to `true` if the primary (first) author name of `labelname` is +unique in the bibliography list and to `false` otherwise. This +effectively answers the question <is there more than one author with +the same base name>. The base name parts are defined by +`\DeclareUniquenameTemplate` see ??. This is required by some styles +(e.g. APA) which mandates primary author disambiguation only and only if +there are (different) primary authors with the same family name. If +`labelname` is not set for an entry, this will always expand to `false`. +Note that this feature needs to be enabled explicitly with the package +option `uniqueprimaryauthor`. +]] + }, + ifuseeditor = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifuseeditor{true}{false} +``` + +This is just a particular case of the `\ifuse` macro below but is +mentioned here as `editor` is part of the default data model. Expands to +`true` if the `useeditor` option is enabled (either globally or for the +current entry), and `false` otherwise. See ?? for details on this +option. +]] + }, + ifuseprefix = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifuseprefix{true}{false} +``` + +Expands to `true` if the `useprefix` option is enabled (either globally +or for the current entry), and `false` otherwise. See ?? for details on +this option. +]] + }, + ifvolcite = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifvolcite{true}{false} +``` + +Expands to `true` when located in `\volcite` or a related citation +command (??), and to `false` otherwise. +]] + }, + ifxrefsource = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifxrefsource{true}{false} +``` + +Expands to `true` if the entry was inclued in the `.bbl` due to being +referenced more than `minxrefs` times and false otherwise. See ??. Also +expands to false if the entry was directly cited. +]] + }, + indexlist = { + arguments = { + {delimiters = {"[", "]"}, meta = "format", optional = true}, + {delimiters = {"[", "]"}, meta = "start--stop", optional = true}, + {meta = "literal list"} + }, + details = [[ +```latex +\indexlist[format][start--stop]{literal list} +``` + +This command is similar to `\printlist` except that the items in the +list are not printed but added to the index using the formatting +directive `format`, as defined with `\DeclareIndexListFormat`. If a +type-specific `format` has been declared, the type-specific formatting +directive takes precedence over the generic one. If the `literal list` +is undefined, this command does nothing. If the `format` is omitted, +`\indexlist` tries using the name of the list as a format name. In this +case, any type-specific formatting directive will also take precedence +over the generic one. If all of these formats are undefined, it falls +back to `default` as a last resort. +]] + }, + instcount = { + details = [[ +```latex +\instcount +``` + +This counter is incremented by `biblatex`for every citation as well as +for every entry in the bibliography and bibliography lists. The value of +this counter uniquely identifies a single instance of a reference in the +document. +]] + }, + labelalphawidth = { + details = [[ +```latex +\labelalphawidth +``` + +This length register indicates the width of the widest `labelalpha`. +Alphabetic bibliography styles should incorporate this length in the +definition of the bibliography environment. +]] + }, + letbibmacro = { + arguments = { + {literal = "*", optional = true}, + {meta = "alias"}, + {meta = "name"} + }, + details = [[ +```latex +\letbibmacro*{alias}{name} +``` + +This command defines the macro `alias` to be an alias of the macro +`name`. The definition is perfomed by `\csletcs`. An error is issued if +`name` is undefined. The regular variant of this command sanitizes +`name` while the starred variant does not. +]] + }, + listcount = { + details = [[ +```latex +\listcount +``` + +This counter holds the number of the list item currently being +processed. It is intended for use in list formatting directives and does +not hold a meaningful value when used anywhere else. +]] + }, + liststop = { + details = [[ +```latex +\liststop +``` + +This counter holds the `stop` argument passed to `\printnames` or +`\printlist`. It is intended for use in list formatting directives and +does not hold a meaningful value when used anywhere else. +]] + }, + literal = { + arguments = {{meta = "string"}}, + details = [[ +```latex +\literal{string} +``` + +A literal string to insert into the name sorting key. +]] + }, + lownamepenalty = { + details = [[ +```latex +\lownamepenalty +``` + +Similar to `highnamepenalty`. Please refer to ?? for explanation. The +counter is initialized to half the `\hyphenpenalty` at load-time. Use a +higher value if you dislike the respective linebreaks. If you do not +mind them at all, set this counter to zero. + +```latex +\lownamepenalty +``` + +The penalty used by `\addlowpenspace` and `\addlpthinspace`, see ?? for +details. The counter is initialized to half the `\hyphenpenalty` at +load-time. +]] + }, + mainlang = { + deprecated = true, + details = [[ +```latex +\mainlang +``` + +Switches from the current language to the main document language. This +command is deprecated. Use the text-macro `\textmainlang` instead. With +`babel` this command will need to be wrapped into *two* groups to have +purely local effect. +]] + }, + mancite = { + details = [[ +```latex +\mancite +``` + +Use this command to mark manually inserted citations if you mix +automatically generated and manual citations. This is particularly +useful if the citation style replaces repeated citations by an +abbreviation like *ibidem* which may get ambiguous or misleading +otherwise. Always use `\mancite` in the same context as the manual +citation, e.g. if the citation is given in a footnote, include +`\mancite` in the footnote. The `\mancite` command executes a style +specific reset hook defined with the `\OnManualCitation` command from +??. It also resets the internal <ibidem> and <idem> trackers of +this package. The reset will affect the `\ifciteibid` and `\ifciteidem` +tests discussed in ??. +]] + }, + map = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "restrictions,steps"} + }, + details = [[ +```latex +\map[options]{restrictions,steps} +``` + +A container for an ordered set of map `\step`s, optionally restricted to +particular entrytypes or data sources. This is a grouping element to +allow a set of mapping steps to apply only to specific entrytypes or +data sources. Mapping steps must always be contained within a `\map` +element. The `options` are: + +`overwrite` +As the same option on the parent `\maps` element. This option allows an +override on a per-map group basis. If this option is not specified, the +default is the parent `\maps` element option value. The short form +`overwrite` is equivalent to `overwrite=true`. + +`foreach=` +Loop over all `\step`s in this `\map`, setting the special variable +`$MAPLOOP` to each of the comma-separated values contained in `loopval`. +`loopval` can either be the name of a datafield set defined with +`\DeclareDatafieldSet` (see ??), a datasource field which is fetched and +parsed as a comma-separated values list or an explicit comma-separated +values list. `loopval` is determined in this order. This allows the user +to repeat a group of `\step`s for each value `loopval`. Using regexp +maps, it is possible to create a CSV field for use with this +functionality. The special variable `$MAPUNIQ` may also be used in the +`\step`s to generate a random unique string. This can be useful when +creating keys for new entries. An example: + + [style=latex] + \DeclareSourcemap{ + \maps[datatype=bibtex]{ + \map[overwrite, foreach={author,editor, translator}]{ + \step[fieldsource=\regexp{$MAPLOOP}, match={Smith}, replace={Jones}] + } + } + } + +`refsection` +Only apply the contained `\step` commands to entries in the reference +section with number `refsection`. +]] + }, + maxextradate = { + details = [[ +```latex +\maxextradate +``` + +This counter holds the highest number found in any `extradate` field. +]] + }, + maxextratitle = { + details = [[ +```latex +\maxextratitle +``` + +This counter holds the highest number found in any `extratitle` field. +]] + }, + maxitems = { + details = [[ +```latex +\maxitems +``` + +This counter holds the setting of the `maxitems` package option. +]] + }, + maxnames = { + details = [[ +```latex +\maxnames +``` + +This counter holds the setting of the `maxnames` package option. +]] + }, + midsentence = { + arguments = {{literal = "*", optional = true}}, + details = [[ +```latex +\midsentence* +``` + +The starred variant of `\midsentence` differs from the regular one in +that a preceding abbreviation dot is not hidden from the punctuation +tracker, i.e. any code after `\midsentence*` will see a preceding +abbreviation dot. All other punctuation marks are hidden from the +punctuation tracker and capitalization is suppressed. +]] + }, + mkbibacro = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibacro{text} +``` + +Generic command which typesets an acronym using the small caps variant +of the current font, if available, and as-is otherwise. The acronym +should be given in uppercase letters. +]] + }, + mkbibbold = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibbold{text} +``` + +Similar in concept to `\mkbibemph` but prints bold text. This is a +simple wrapper around the standard `\textbf` command which incorporates +`\setpunctfont`. If the `punctfont` package option is disabled, this +command behaves like `\textbf`. +]] + }, + mkbibcompletename = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibcompletename{text} +``` + +The initial value of all default formatting hooks +`\mkbibcompletename`. +]] + }, + ["mkbibcompletename"] = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibcompletename{text} +``` + +Formatting hook for the complete name in format order <formatorder>. +The default styles use the name format orders <family>, +<family-given> and <given-family>, therefore the following macros +are automatically defined: + + \mkbibcompletenamefamily + \mkbibcompletenamefamilygiven + \mkbibcompletenamegivenfamily + +These formatting hooks should enclose the complete name in the +bibliography macro `\name:`. Initially all hooks expand to +`\mkbibcompletename`. +]] + }, + mkbibcompletenamefamilygiven = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibcompletenamefamilygiven{text} +``` + +This command, which takes one argument, is used to format the complete +name in `family-given` format order. +]] + }, + mkbibdatelong = { + details = [[ +```latex +\mkbibdatelong +``` + +Takes the names of three field as arguments which correspond to three +date components (in the order year/month/day) and uses their values to +print the date in the language specific long date format. +]] + }, + mkbibemph = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibemph{text} +``` + +A generic command which prints its argument as emphasized text. This is +a simple wrapper around the standard `\emph` command. Apart from that, +it uses `\setpunctfont` from ?? to adapt the font of the next +punctuation mark following the text set in italics. If the `punctfont` +package option is disabled, this command behaves like `\emph`. +]] + }, + mkbibendnote = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibendnote{text} +``` + +Similar in concept to `\mkbibfootnote` except that it prints its +argument as an endnote. `\mkbibendnote` removes spurious whitespace +preceding the endnote mark and prevents nested notes. It supports the +`\endnote` command provided by the `endnotes` package as well as the +`\pagenote` command provided by the `pagenote` package and the `memoir` +class. If both commands are available, `\endnote` takes precedence. If +no endnote support is available, `\mkbibendnote` issues an error and +falls back to `\footnote`. By default, `\mkbibendnote` requests +capitalization at the beginning of the note and automatically adds a +period at the end. You may change this behavior by redefining the +`\bibendnotewrapper` macro introduced below. +]] + }, + mkbibfootnote = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibfootnote{text} +``` + +A generic command which prints its argument as a footnote. This is a +wrapper around the standard LaTeX `\footnote` command which removes +spurious whitespace preceding the footnote mark and prevents nested +footnotes. By default, `\mkbibfootnote` requests capitalization at the +beginning of the note and automatically adds a period at the end. You +may change this behavior by redefining the `\bibfootnotewrapper` macro +introduced below. +]] + }, + mkbibmascord = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\mkbibmascord{integer} +``` + +Similar to `\mkbibordinal`, but prints a masculine ordinal, if +applicable in the respective language. +]] + }, + ["mkbibname"] = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibname{text} +``` + +This command, which takes one argument, is used to format the name part +<namepart> of name list fields. The default datamodel defines the +name parts <family>, <given>, <prefix> and <suffix> and +therefore the following macros are automatically defined: + + \mkbibnamefamily + \mkbibnamegiven + \mkbibnameprefix + \mkbibnamesuffix + +For backwards compatibility with the legacy BibTeX name parts, the +following are also defined, will generate warnings and will set the +correct macro: + + \mkbibnamelast + \mkbibnamefirst + \mkbibnameaffix +]] + }, + mkbibneutord = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\mkbibneutord{integer} +``` + +Similar to `\mkbibordinal`, but prints a neuter ordinal, if applicable +in the respective language. +]] + }, + mkbibordseries = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\mkbibordseries{integer} +``` + +Similar to `\mkbibordinal`, but intended for use with the term +<series>. +]] + }, + mkbibparens = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibparens{text} +``` + +A generic command which wraps its argument in parentheses. This command +is nestable. When nested, it will alternate between parentheses and +brackets, depending on the nesting level. +]] + }, + mkbibsuperscript = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\mkbibsuperscript{text} +``` + +A generic command which prints its argument as superscripted text. This +is a simple wrapper around the standard LaTeX `\textsuperscript` command +which removes spurious whitespace and allows hyphenation of the +preceding word. +]] + }, + mkbibtimezone = { + details = [[ +```latex +\mkbibtimezone +``` + +Modifies a timezone string passed in as the only argument. By default +this changes <Z> to the value of `\bibtimezone`. +]] + }, + mkbibyeardivision = { + arguments = {{meta = "string"}}, + deprecated = true, + details = [[ +```latex +\mkbibyeardivision{string} +``` + +This command takes a year division localisation string and prints the +version of the string corresponding to the setting of the `dateabbrev` +package option. Even though the output of this command is language +specific, its definition is not, hence it is normally not redefined in +localisation modules. +]] + }, + mkcomprange = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "postpro", optional = true}, + {delimiters = {"[", "]"}, meta = "itempostpro", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\mkcomprange*[postpro][itempostpro]{text} +``` + +This command, which is intended for use in field formatting directives, +will parse its `text` argument for page ranges and compress them. For +example, «125--129» may be formatted as «125--9». You may configure the +behavior of `\mkcomprange` by adjusting the LaTeX counters +`mincomprange`, `maxcomprange`, and `mincompwidth`, as illustrated in +??. The default settings are `10`, `100000`, and `1`, respectively. This +means that the command tries to compress as much as possible by default. +Use `\setcounter` to adjust the parameters. The scanner recognises +`\bibrangedash` and hyphens as range dashes. It will normalize the dash +by replacing any number of consecutive hyphens with `\bibrangedash`. +Lists of ranges delimited with `\bibrangessep` are also supported. The +scanner will normalise any comma or semicolons surrounded by optional +space by replacing them with `\bibrangessep`. If you want to hide a +character from the list/range scanner for some reason, wrap the +character or the entire string in curly braces. The optional `postpro` +argument specifies a macro to be used for post-processing the `text`. +This is important if you want to combine `\mkcomprange` with other +formatting macros which also need to parse their `text` argument, such +as `\mkpageprefix`. Simply nesting these commands will not work as +expected. Use the `postpro` argument to set up the processing chain as +follows: + + \DeclareFieldFormat{postnote}{\mkcomprange[<<{>>\mkpageprefix[pagination]<<}>>]{#1}} + +Note that `\mkcomprange` is executed first, using `\mkpageprefix` as +post-processor. Also note that the `postpro` argument is wrapped in an +additional pair of braces. This is only required in this particular case +to prevent LaTeX 's optional argument scanner from getting confused by +the nested brackets. The starred version of this command differs from +the regular one in the way the `postpro` argument is applied to a list +of values. For example: + + \mkcomprange[\mkpageprefix]{5, 123-129, 423-439} + \mkcomprange*[\mkpageprefix]{5, 123-129, 423-439} + +will output: + + pp. 5, 123-9, 423-39 + p. 5, pp. 123-9, pp. 423-39 + +The second optional argument `itempostpro` is used to post-process each +individual number item in the formatted list. It can be used to convert +numbers from cardinals to ordinals. If only one optional argument is +present, it is treated as `postpro`. +]] + }, + mkdayzeros = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\mkdayzeros{integer} +``` + +This command strips leading zeros from a day or enforces them, depending +on the `datezeros` package option (??). It is intended for use in the +definition of date formatting macros. If zeros are enforced, this +command calls `\forcezerosmdt` and thus expands its argument with +`\protected@edef`. +]] + }, + mkfirstpage = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "postpro", optional = true}, + {delimiters = {"[", "]"}, meta = "itempostpro", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\mkfirstpage*[postpro][itempostpro]{text} +``` + +This command, which is intended for use in field formatting directives, +will parse its `text` argument for page ranges and print the start page +of the range only. The scanner recognizes `\bibrangedash` and hyphens as +range dashes. Lists of ranges delimited with `\bibrangessep` are also +supported. If you want to hide a character from the list/range scanner +for some reason, wrap the character or the entire string in curly +braces. The optional `postpro` argument specifies a macro to be used for +post-processing the `text`. See `\mkcomprange` on how to use this +argument. The starred version of this command differs from the regular +one in the way the `postpro` argument is applied to a list of values. +The second optional argument `itempostpro` is used to post-process each +individual number item in the formatted list. It can be used to convert +numbers from cardinals to ordinals. If only one optional argument is +present, it is treated as `postpro`. For example: + + \mkfirstpage[\mkpageprefix]{5, 123-129, 423-439} + \mkfirstpage*[\mkpageprefix]{5, 123-129, 423-439} + +will output: + + pp. 5, 123, 423 + p. 5, p. 123, p. 423 +]] + }, + mknormrange = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "postpro", optional = true}, + {delimiters = {"[", "]"}, meta = "itempostpro", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\mknormrange*[postpro][itempostpro]{text} +``` + +This command, which is intended for use in field formatting directives, +will parse its `text` argument for page ranges and will normalise them. +The command is similar to `\mkcomprange` except that the page ranges +will not be compressed. The scanner recognises `\bibrangedash` and +hyphens as range dashes. It will normalize the dash by replacing any +number of consecutive hyphens with `\bibrangedash`. Lists of ranges +delimited with `\bibrangessep` are also supported. The scanner will +normalise any comma or semicolons surrounded by optional space by +replacing them with `\bibrangessep`. If you want to hide a character +from the list/range scanner for some reason, wrap the character or the +entire string in curly braces. The optional `postpro` argument specifies +a macro to be used for post-processing the `text`. See `\mkcomprange` on +how to use this argument. The starred version of this command differs +from the regular one in the way the `postpro` argument is applied to a +list of values. The second optional argument `itempostpro` is used to +post-process each individual number item in the formatted list. It can +be used to convert numbers from cardinals to ordinals. If only one +optional argument is present, it is treated as `postpro`. +]] + }, + mkpagetotal = { + arguments = { + {delimiters = {"[", "]"}, meta = "pagination", optional = true}, + {delimiters = {"[", "]"}, meta = "postpro", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\mkpagetotal[pagination][postpro]{text} +``` + +This command is similar to `\mkpageprefix` except that it is intended +for the `pagetotal` field of bibliography entries, i.e. it will print +«123 pages» rather than «page 123». The optional `pagination` argument +defaults to `bookpagination`. The spacing inserted between the +pagination suffix and the `text` may be modified by redefining the macro +`\ppspace`. The optional `postpro` argument specifies a macro to be used +for post-processing the `text`. If only one optional argument is given, +it is taken as `pagination`. Here is a typical example: + + \DeclareFieldFormat{pagetotal}{<<\mkpagetotal[bookpagination]{#1}>>} + +The optional argument `bookpagination` is omissible in this case. The +pagination strings are taken from `total` and +`totals`. + +@>X@p0.25@p0.25@p0.25@ & +(r)1-1 & & & +(r)2-2(r)3-3 11--15 & 11--5 & 11--15 & 11--15 +111--115 & 111--5 & 111--5 & 111--115 +1111--1115 & 1111--5 & 1111--5 & 1111--5 +& & & +(r)2-2(r)3-3 1111--1115 & 1111--5 & 1111--5 & 1111--5 +1111--1155 & 1111--55 & 1111--55 & 1111--1155 +1111--1555 & 1111--555 & 1111--1555 & 1111--1555 +& & & +(r)2-2(r)3-3 1111--1115 & 1111--5 & 1111--15 & 1111--115 +1111--1155 & 1111--55 & 1111--55 & 1111--155 +1111--1555 & 1111--555 & 1111--555 & 1111--555 +]] + }, + mkvolcitenote = { + arguments = {{meta = "volume"}, {meta = "pages"}}, + details = [[ +```latex +\mkvolcitenote{volume}{pages} +``` + +This macro formats the `volume` and `pages` arguments of `\volcite` and +related commands (??) when they are passed on to the underlying citation +command. +]] + }, + mkyearzeros = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\mkyearzeros{integer} +``` + +This command strips leading zeros from a year or enforces them, +depending on the `datezeros` package option (??). It is intended for use +in the definition of date formatting macros. If zeros are enforced, this +command calls `\forcezerosy` and thus expands its argument with +`\protected@edef`. +]] + }, + multicitecount = { + details = [[ +```latex +\multicitecount +``` + +This counter is similar to `citecount` but only available in multicite +commands. It holds the number of the citation currently being processed. +Note that this citation may consist of more than one entry key. This +information is provided by the `citetotal` and `citecount` counters. +]] + }, + multicitedelim = { + details = [[ +```latex +\multicitedelim +``` + +The delimiter printed between citations if multiple entry keys are +passed to a single citation command. The default is a semicolon plus an +interword space. + +```latex +\multicitedelim +``` + +The delimiter printed between citations if multiple entry keys are +passed to a single citation command. This command should be incorporated +in the definition of all citation commands, for example in the `sepcode` +argument passed to `\DeclareCiteCommand`. See ?? for details. The +default is a semicolon plus an interword space. +]] + }, + multicitesubentrydelim = { + details = [[ +```latex +\multicitesubentrydelim +``` + +The delimiter printed between subentry citations of the same set. This +delimiter is only used in citation styles that reduce citations of the +same set to a more compact form (`subentry` of `numeric-comp`). The +default is a comma. +]] + }, + multipostnotedelim = { + details = [[ +```latex +\multipostnotedelim +``` + +The delimiter to be printed before the `multipostnote` argument of a +citation command. +]] + }, + multiprenotedelim = { + details = [[ +```latex +\multiprenotedelim +``` + +The delimiter printed after the `multiprenote` argument of a citation +command. See ?? for details. The default is `\prenotedelim`. +]] + }, + namelabeldelim = { + details = [[ +```latex +\namelabeldelim +``` + +The delimiter printed between the name/title and the label by alphabetic +and numeric citation styles. The default definition is an interword +space. + +```latex +\namelabeldelim +``` + +The delimiter printed between the name/title and the label. This command +should be incorporated in the definition of all citation commands of +alphabetic and numeric citation styles. The default definition is an +interword space. +]] + }, + nametitledelim = { + details = [[ +```latex +\nametitledelim +``` + +The delimiter printed between the author/editor and the title by +author-title and some verbose citation styles and in the bibliography. +In author-year bibliography styles this delimiter is placed after the +author/editor and year and before the title. The default definition +inside bibliographies is the now deprecated `\labelnamepunct` and is a +comma plus an interword space otherwise. + +```latex +\nametitledelim +``` + +The delimiter to be printed between the author/editor and the title. +This command should be incorporated in the definition of all citation +commands of author-title and some verbose citation styles and in the +bibliography drivers---in author-year bibliographies `\nametitledelim` +may be printed between the author/editor-year block and the title. The +default definition inside bibliographies is the now deprecated +`\labelnamepunct` (for backwrds compatibility reasons) and is a comma +plus an interword space otherwise. +]] + }, + nbhyphen = { + details = [[ +```latex +\nbhyphen +``` + +An explicit, non-breakable hyphen intended for compound words. In +contrast to a literal <`-`>, this command does not permit line +breaks at the hyphen but still allows hyphenation in the rest of the +word. It is similar to the `"~` shorthand provided by some language +modules of the `babel`/`polyglossia` packages. +]] + }, + newbibmacro = { + arguments = { + {literal = "*", optional = true}, + {meta = "name"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + {delimiters = {"[", "]"}, meta = "optional", optional = true}, + {meta = "definition"} + }, + details = [[ +```latex +\newbibmacro{name}[arguments][optional]{definition} +\newbibmacro*{name}[arguments][optional]{definition} +``` + +Defines a macro to be executed via `\usebibmacro` later. The syntax of +this command is very similar to `\newcommand` except that `name` may +contain characters such as numbers and punctuation marks and does not +start with a backslash. The optional argument `arguments` is an integer +specifying the number of arguments taken by the macro. If `optional` is +given, it specifies a default value for the first argument of the macro, +which automatically becomes an optional argument. In contrast to +`\newcommand`, `\newbibmacro` issues a warning message if the macro is +already defined, and automatically falls back to `\renewbibmacro`. As +with `\newcommand`, the regular variant of this command uses the `\long` +prefix in the definition while the starred one does not. If a macro has +been declared to be long, it may take arguments containing `\par` +tokens. `\newbibmacro` and `\renewbibmacro` are provided for +convenience. Style authors are free to use `\newcommand` or `\def` +instead. However, note that most shared definitions found in +`biblatex.def` are defined with `\newbibmacro`, hence they must be used +and modified accordingly. +]] + }, + newblock = { + details = [[ +```latex +\newblock +``` + +Records the end of a block. This command does not print anything, it +merely marks the end of the block. The block delimiter `\newblockpunct` +will be inserted by a subsequent `\printtext`, `\printfield`, +`\printlist`, `\printnames`, or `\bibstring` command. You may use +`\newblock` at suitable places without having to worry about spurious +blocks. A new block will only be started by the next `\printfield` (or +similar) command if this command prints anything. See ?? for further +details. +]] + }, + newrefcontext = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + }, + {meta = "name"} + }, + details = [[ +```latex +\newrefcontext[key=value, ... ]{name} +``` + +This command is similar to the `refcontext` environment except that it +is a stand-alone command rather than an environment. It automatically +ends any previous reference context section begun with `\newrefcontext` +(if any) and immediately starts a new one. Note that the context section +started by the last `\newrefcontext` command in the document will extend +to the very end of the document. Use `\endrefcontext` if you want to +terminate it earlier. +]] + }, + newunitpunct = { + details = [[ +```latex +\newunitpunct +``` + +The separator inserted between <units> in the sense explained in ??. +This will usually be a period or a comma plus an interword space. The +default definition is a period and a space. +]] + }, + nocite = { + action = "cite", + arguments = {{meta = "key"}}, + details = [[ +```latex +\nocite{key} +\nocite{*} +``` + +This command is similar to the standard LaTeX `\nocite` command. It adds +the `key` to the bibliography without printing a citation. If the `key` +is an asterisk, all entries available in the in-scope bibliography +datasource(s) are added to the bibliography. Like all other citation +commands, `\nocite` commands in the document body are local to the +enclosing `refsection` environment, if any. In contrast to standard +LaTeX , `\nocite` may also be used in the document preamble. In this +case, the references are assigned to reference section 0. For the +purposes of ordering citations by appearance `\nocite` will behave like +all other cite commands, with the added rule that a `\nocite` issued in +the preamble is treated as coming before all explicit citations in +reference section 0 from the document body. +]] + }, + noinherit = { + arguments = {{meta = "source"}}, + details = [[ +```latex +\noinherit{source} +``` + +Unconditionally prevents inheritance of the `source` field. +]] + }, + nopunct = { + details = [[ +```latex +\nopunct +``` + +Adds an internal marker which will cause the next punctuation command to +print nothing. +]] + }, + parencite = { + action = "cite", + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = [[ +```latex +\parencite*[prenote][postnote]{key} +``` + +This command is provided by all author-year and author-title styles. It +is similar to the regular `\parencite` command but merely prints the +year or the title, respectively. +]] + }, + parenlevel = { + details = [[ +```latex +\parenlevel +``` + +The current nesting level of parentheses and/or brackets. This +information is only available if the `parentracker` from ?? is enabled. +]] + }, + parentext = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\parentext{text} +``` + +This command wraps the `text` in context sensitive parentheses. +]] + }, + pertype = { + arguments = {{meta = "entrytype"}}, + details = [[ +```latex +\pertype{entrytype} +``` + +Restricts all `\step`s in this `\map` element to entries of the named +`entrytype`. Multiple `\pertype` restrictions are allowed within a +`\map` element. +]] + }, + pnfmt = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\pnfmt{text} +``` + +This command formats its argument `text` in the same format as +`postnote`. The command can be used to format a page range while adding +additional text in the postnote argument of a cite command. + + \autocite[\pnfmt{378-381, 383} and more]{sigfridsson} +]] + }, + postnotedelim = { + details = [[ +```latex +\postnotedelim +``` + +The delimiter printed before the `postnote` argument of a citation +command. See ?? for details. The default is a comma plus an interword +space. +]] + }, + ppno = { + details = [[ +```latex +\ppno +``` + +Similar to `\pno` but forces a range prefix. See ?? for further details +and usage instructions. Note that this command is only available locally +in citations and the bibliography. +]] + }, + prenotedelim = { + details = [[ +```latex +\prenotedelim +``` + +The delimiter to be printed after the `prenote` argument of a citation +command. The default is an interword space. +]] + }, + printbibliography = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + } + }, + details = [[ +```latex +\printbibliography[key=value, ... ] +``` + +This command prints the bibliography. It takes one optional argument, +which is a list of options given in `key=value`notation. The following +options are available: +]] + }, + printbiblist = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key=value, ... ", + optional = true + }, + {meta = "biblistname"} + }, + details = [[ +```latex +\printbiblist[key=value, ... ]{biblistname} +``` + +This command prints a bibliography list. It takes an optional argument, +which is a list of options given in `key=value`notation. Valid options +are all options supported by `\printbibliography` (??) except +`resetnumbers` and `omitnumbers`. Additionaly, the two options `driver` +and `biblistfilter` are available. If there are any `refsection` +environments in the document, the bibliography list will be local to +these environments; see ?? for details. By default, this command uses +the heading `biblist`. See ?? for details. + +The `biblistname` is a mandatory argument which names the bibliography +list. This name is used to identify: + +- The default bibliography driver used to print the list entries + +- A default bibliography list filter declared with + `\DeclareBiblistFilter` (see ??) used to filter the entries returned + from `biber` + +- A default check declared with `\defbibcheck` (see ??) used to + post-process the list entries + +- The default bib environment to use + +- The default sorting template to use + +The two additional options can be used to change some of the defaults +set by the mandatory argument. + +`driver=` +Change the bibliography driver used to print the list entries. + +`biblistfilter=` +Change the bibliography list filter used to filter the entries. +`biblistfilter` must be a valid bibliography list filter defined with +`\DeclareBiblistFilter` (see ??). + +In terms of sorting the list, the default is to sort using the sorting +template named after the bibliography list (if it exists) and only then +to fall back to the current context sorting template if this is not +defined (see ??). + +The most common bibliography list is a list of shorthand abbreviations +for certain entries and so this has a convenience alias +`\printshorthands[…]` for backwards compatibility which is defined as: + + \printbiblist[...]{shorthand} + +`biblatex`provides automatic support for data source fields in the +default data model marked as <Label fields> (See ??). Such fields +automatically have defined for them: + +- A default bib environment (See ??) + +- A bibliography list filter (See ??) + +- Some supporting formats and lengths (See ?? and ??) + +Therefore only a minimal setup is required to print bibliography lists +with such fields. For example, to print a list of journal title +abbreviations, you can minimally put this in your preamble: + + \DeclareBibliographyDriver{shortjournal}{% + \printfield{journaltitle}} + +Then you can put this in your document where you want to print the list: + + \printbiblist[title={Journal Shorthands}]{shortjournal} + +Since `shortjournal` is defined in the default data model as a <Label +field>, this example: + +- Uses the automatically created <shortjournal> bib environment + +- Uses the automatically created <shortjournal> bibliography list + filter to return only entries with a `shortjournal` field in the + `.bbl` + +- Uses the defined <shortjournal> bibliography driver to print the + entries + +- Uses the default <biblist> heading but overrides the title with + <Journal Shorthands> + +- Uses the current bibliography context sorting template if no + template exists with the name `shortjournal` + +Often, you will want to sort on the label field of the list and since a +sorting template is automatically picked up if it is named after the +list, in this case you could simply do: + + \DeclareSortingTemplate{shortjournal}{ + \sort{ + \field{shortjournal} + } + } + +Naturally all defaults can be overridden by options to `\printbiblist` +and definitions of the environments, filters etc. and in this way +arbitrary types of bibliography lists can be printed containing a +variety of information from the bibliography data. +]] + }, + printdate = { + details = [[ +```latex +\printdate +``` + +This command prints the date of the entry, as specified in the fields +`date` or `month`/`year`. The date format is controlled by the package +option `date` from ??. Additional formatting (fonts etc.) may be applied +by adjusting the field format `date` (??). Note that this command +interfaces with the punctuation tracker. There is no need to wrap it in +a `\printtext` command. +]] + }, + printlabeldate = { + details = [[ +```latex +\printlabeldate +``` + +Similar to `\printdate` but prints the date field determined by +`\DeclareLabeldate`. The date format is controlled by the package option +`labeldate` from ??. Additional formatting may be applied by adjusting +the field format `labeldate` (??). +]] + }, + printlist = { + arguments = { + {delimiters = {"[", "]"}, meta = "format", optional = true}, + {delimiters = {"[", "]"}, meta = "start--stop", optional = true}, + {meta = "literal list"} + }, + details = [[ +```latex +\printlist[format][start--stop]{literal list} +``` + +This command loops over all items in a `literal list`, starting at item +number `start` and stopping at item number `stop`, including `start` and +`stop` (all lists are numbered starting at 1). Each item is printed +using the formatting directive `format`, as defined with +`\DeclareListFormat`. If a type-specific `format` has been declared, the +type-specific formatting directive takes precedence over the generic +one. If the `literal list` is undefined, nothing is printed. If the +`format` is omitted, `\printlist` tries using the name of the list as a +format name. In this case, any type-specific formatting directive will +also take precedence over the generic one. If all of these formats are +undefined, it falls back to `default` as a last resort. The `start` +argument defaults to 1; `stop` defaults to the total number of items in +the list. If the total number is greater than `maxitems`, `stop` +defaults to `minitems` (see ??). See `\printnames` for further details. +Note that `\printlist` provides the name of the literal list currently +being processed in `\currentlist` for use in list formatting directives. +]] + }, + printtext = { + arguments = { + {delimiters = {"[", "]"}, meta = "format", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\printtext[format]{text} +``` + +This command prints `text`, which may be printable text or arbitrary +code generating printable text. It clears the punctuation buffer before +inserting `text` and informs `biblatex`that printable text has been +inserted. This ensures that all preceding and following `\newblock` and +`\newunit` commands have the desired effect. `\printfield` and +`\printnames` as well as `\bibstring` and its companion commands (see +??) do that automatically. Using this command is required if a +bibliography styles inserts literal text (including the commands from +??) to ensure that block and unit punctuation works as advertised in ??. +The optional `format` argument specifies a field formatting directive to +be used to format `text`. This may also be useful when several fields +are to be printed as one chunk, for example, by enclosing the entire +chunk in parentheses or quotation marks. If a type-specific `format` has +been declared, the type-specific formatting directive takes precedence +over the generic one. If the `format` is omitted, the `text` is printed +as is. See also ?? for some practical hints. +]] + }, + printunit = { + arguments = {{literal = "*", optional = true}, {meta = "punctuation"}}, + details = [[ +```latex +\printunit*{punctuation} +``` + +The `\printunit` command is similar to `\setunit` except that +`punctuation` persists in the buffer. This ensures that `punctuation` is +inserted before the next non-empty field printed by the `\printtext`, +`\printfield`, `\printlist`, `\printnames`, or `\bibstring` +commands---regardless of any intermediate calls to `\newunit` or +`\setunit`. +]] + }, + providebibmacro = { + arguments = { + {literal = "*", optional = true}, + {meta = "name"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + {delimiters = {"[", "]"}, meta = "optional", optional = true}, + {meta = "definition"} + }, + details = [[ +```latex +\providebibmacro*{name}[arguments][optional]{definition} +``` + +Similar to `\newbibmacro` but only defines `name` if it is undefined. +This command is similar in concept to `\providecommand`. +]] + }, + psq = { + details = [[ +```latex +\psq +``` + +In the `postnote` argument to a citation command, this command indicates +a range of two pages where only the starting page is given. See ?? for +further details and usage instructions. The suffix printed is the +localisation string `sequens`, see ??. The spacing inserted between the +suffix and the page number may be modified by redefining the macro +`\sqspace`. The default is an unbreakable interword space. Note that +this command is only available locally in citations and the +bibliography. +]] + }, + refsection = { + details = [[ +```latex +\refsection +``` + +This counter indicates the current `refsection` environment. When +queried in a bibliography heading, the counter returns the value of the +`refsection` option passed to `\printbibliography`. +]] + }, + regexp = { + arguments = {{meta = "PCRE"}}, + details = [[ +```latex +\regexp{PCRE} +``` + +This command can be used with any command accepting a regular expression +key to protect a regular expression from being interpreted by TeX so +that it is passed through to `biber`correctly. Regular expressions often +contain sequences of characters that are also valid TeX commands but +which should not be interpreted as such. The argument is a normal PCRE +(Perl Compatible Regular Expression). +Perl escape sequences like `\t` for a tab, `\n` for a newline, `\A` for +the start of a string or `\d` for a digit can be used, without +TeX trying to execute them as commands, as can be special characters +like `^`, `_` or `{..}` and `#`. Only the % must be protected: to match +a single % in the bib, use \\% in the regular expression, a \\% is +matched by \\\\%. +]] + }, + relateddelim = { + details = [[ +```latex +\relateddelim +``` + +The generic separator between the data of multiple related entries. The +default definition is an optional dot plus linebreak. Here is an example +where volumes A-E are related entries of the 5 volume main work: + + Donald E. Knuth. Computers & Typesetting. 5 vols. Reading, Mass.: Addison-Wesley, 1984-1986. + Vol. A: The TEXbook. 1984. + Vol. B: TEX: The Program. 1986. + Vol. C: The METAFONTbook. By. 1986. + Vol. D: METAFONT: The Program. 1986. + Vol. E: Computer Modern Typefaces. 1986. +]] + }, + relatedpunct = { + details = [[ +```latex +\relatedpunct +``` + +The separator between the `relatedtype` bibliography localisation string +and the data from the first related entry. +]] + }, + renewbibmacro = { + arguments = { + {literal = "*", optional = true}, + {meta = "name"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + {delimiters = {"[", "]"}, meta = "optional", optional = true}, + {meta = "definition"} + }, + details = [[ +```latex +\renewbibmacro*{name}[arguments][optional]{definition} +``` + +Similar to `\newbibmacro` but redefines `name`. In contrast to +`\renewcommand`, `\renewbibmacro` issues a warning message if the macro +is undefined, and automatically falls back to `\newbibmacro`. +]] + }, + resetpunctfont = { + details = [[ +```latex +\resetpunctfont +``` + +This command resets the unit punctuation font defined with +`\setpunctfont` before it takes effect. If the `punctfont` package +option is disabled, this command does nothing. +]] + }, + restorebibmacro = { + arguments = {{meta = "name"}}, + details = [[ +```latex +\restorebibmacro{name} +``` + +These commands save and restore the macro `name`, where `name` is the +identifier of a macro defined with `\newbibmacro`. Both commands work +within a local scope. They are mainly provided for use in localisation +files. +]] + }, + restorecommand = { + arguments = {{meta = "command"}}, + details = [[ +```latex +\restorecommand{command} +``` + +These commands save and restore any `command`, which must be a command +name starting with a backslash. Both commands work within a local scope. +They are mainly provided for use in localisation files. +]] + }, + restorefieldformat = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "format"} + }, + details = [[ +```latex +\restorefieldformat[entry type]{format} +``` + +These commands save and restore the formatting directive `format`, as +defined with `\DeclareFieldFormat`. Both commands work within a local +scope. They are mainly provided for use in localisation files. +]] + }, + restorelist = { + arguments = {{meta = "literal list"}, {meta = "macro"}}, + details = [[ +```latex +\restorelist{literal list}{macro} +``` + +Restores a `literal list` from a `macro` defined with `\savelist` +before. The list is restored within a local scope. +]] + }, + restorelistformat = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "format"} + }, + details = [[ +```latex +\restorelistformat[entry type]{format} +``` + +These commands save and restore the formatting directive `format`, as +defined with `\DeclareListFormat`. Both commands work within a local +scope. They are mainly provided for use in localisation files. +]] + }, + restorelistwrapperformat = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "format"} + }, + details = [[ +```latex +\restorelistwrapperformat[entry type]{format} +``` + +These commands save and restore the formatting directive `format`, as +defined with `\DeclareListWrapperFormat`. Both commands work within a +local scope. They are mainly provided for use in localisation files. +]] + }, + restorenameformat = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "format"} + }, + details = [[ +```latex +\restorenameformat[entry type]{format} +``` + +These commands save and restore the formatting directive `format`, as +defined with `\DeclareNameFormat`. Both commands work within a local +scope. They are mainly provided for use in localisation files. +]] + }, + restorenamewrapperformat = { + arguments = { + {delimiters = {"[", "]"}, meta = "entry type", optional = true}, + {meta = "format"} + }, + details = [[ +```latex +\restorenamewrapperformat[entry type]{format} +``` + +These commands save and restore the formatting directive `format`, as +defined with `\DeclareNameWrapperFormat`. Both commands work within a +local scope. They are mainly provided for use in localisation files. +]] + }, + savefield = { + arguments = { + {literal = "*", optional = true}, + {meta = "field"}, + {meta = "macro"} + }, + details = [[ +```latex +\savefield*{field}{macro} +``` + +Copies an unformatted `field` to a `macro`. The regular variant of this +command defines the `macro` globally, the starred one works locally. +]] + }, + savefieldcs = { + arguments = { + {literal = "*", optional = true}, + {meta = "field"}, + {meta = "csname"} + }, + details = [[ +```latex +\savefieldcs*{field}{csname} +``` + +Similar to `\savefield`, but takes the control sequence name `csname` +(without a leading backslash) as an argument, rather than a macro name. +]] + }, + savelist = { + arguments = { + {literal = "*", optional = true}, + {meta = "literal list"}, + {meta = "macro"} + }, + details = [[ +```latex +\savelist*{literal list}{macro} +``` + +Copies an unformatted `literal list` to a `macro`. The regular variant +of this command defines the `macro` globally, the starred one works +locally. +]] + }, + savelistcs = { + arguments = { + {literal = "*", optional = true}, + {meta = "literal list"}, + {meta = "csname"} + }, + details = [[ +```latex +\savelistcs*{literal list}{csname} +``` + +Similar to `\savelist`, but takes the control sequence name `csname` +(without a leading backslash) as an argument, rather than a macro name. +]] + }, + savename = { + arguments = { + {literal = "*", optional = true}, + {meta = "name list"}, + {meta = "macro"} + }, + details = [[ +```latex +\savename*{name list}{macro} +``` + +Copies an unformatted `name list` to a `macro`. The regular variant of +this command defines the `macro` globally, the starred one works +locally. +]] + }, + savenamecs = { + arguments = { + {literal = "*", optional = true}, + {meta = "name list"}, + {meta = "csname"} + }, + details = [[ +```latex +\savenamecs*{name list}{csname} +``` + +Similar to `\savename`, but takes the control sequence name `csname` +(without a leading backslash) as an argument, rather than a macro name. +]] + }, + setunit = { + arguments = {{literal = "*", optional = true}, {meta = "punctuation"}}, + details = [[ +```latex +\setunit*{punctuation} +``` + +The `\setunit` command is similar to `\newunit` except that it uses +`punctuation` instead of `\newunitpunct`. The starred variant differs +from the regular version in that it checks if the last `\printtext`, +`\printfield`, `\printlist`, `\printnames`, or `\bibstring` command did +actually print anything. If not, it does nothing. +]] + }, + smartand = { + details = [[ +```latex +\smartand +``` + +This counter controls the behavior of the internal <smart and> +command. When set to 1, it prints <y> or <e>, depending on the +context. When set to 2, it always prints <y>. When set to 3, it +always prints <e>. When set to 0, the <smart and> feature is +disabled. This counter is initialized to 1 at load-time and may be +changed in the preamble. Note that setting this counter to a positive +value implies that the Spanish localisation module ignores +`\finalnamedelim` and `\finallistdelim`. +]] + }, + sortalphaothers = { + details = [[ +```latex +\sortalphaothers +``` + +Similar to `\labelalphaothers` but used in the sorting process. Setting +it to a different value is advisable if the latter contains formatting +commands, for example: + + \renewcommand*{\labelalphaothers}{\textbf{+}} + \renewcommand*{\sortalphaothers}{+} + +If `\sortalphaothers` is not redefined, it defaults to +`\labelalphaothers`. + +```latex +\sortalphaothers +``` + +Similar to `\labelalphaothers` but used in the sorting process. Setting +it to a different value is advisable if the latter contains formatting +commands. If `\sortalphaothers` is not redefined, it defaults to +`\labelalphaothers`. +]] + }, + stdpunctuation = { + details = [[ +```latex +\stdpunctuation +``` + +Undoes the settings applied by `\uspunctuation`, restoring standard +punctuation. As standard punctuation is the default setting, you only +need this command to override a previously executed `\uspunctuation` +command. See ?? for details. +]] + }, + step = { + arguments = {{delimiters = {"[", "]"}, meta = "options", optional = true}}, + details = [[ +```latex +\step[options] +``` + +A mapping step. Each step is applied sequentially to every relevant +entry where <relevant> means those entries which correspond to the +data source type, entrytype and data source name restrictions mentioned +above. Each step is applied to the entry as it appears after the +application of all previous steps. The mapping performed by the step is +determined by the following `option`s: + +`typesource=` + +`typetarget=` + +`fieldsource=` + +`notfield=` + +`fieldtarget=` + +`match=` + +`matchi=` + +`notmatch=` + +`notmatchi=` + +`matches=` + +`matchesi=` + +`replace=` + +`fieldset=` + +`fieldvalue=` + +`entryclone=` + +`entrynew=` + +`entrynewtype=` + +`entrytarget=` + +`cited` + +`nocited` + +`citedornocited` + +`allnocited` + +`starnocited` + +`entrynocite` + +`entrynull` + +`append` + +`appendstrict` + +`final` + +`null` + +`origfield` + +`origfieldval` + +`origentrytype` +For all boolean `\step` options, the short form `option` is equivalent +to `option=true`. The following rules for a mapping step apply: + +Note that the options `cited`, `nocited`, `citedornocited`, `allnocited` +and `starnocited` are unique in that they can make the results of a +sourcemap differ depending on the refsection. This is because a +datasource to which source mapping applies may be used in several +refsections and source mappings are applied when fetching the data from +the datasources for a refsection. Citation commands are local to a +refsection and therefore may differ for the same entry from refsection +to refsection. For example, the same entry may be `\cite`d in one +refsection but `\nocite`d in another, resulting in different source map +results and therefore data between the refsections. This can be avoided +if desired, by limiting source maps to specific refsections only (see +`refsection` option to the `\map` command above). + +- If `entrynew` is set, a new entry is created with the entry key + `entrynewkey` and the entry type given in the option `entrynewtype`. + This entry is only in-scope during the processing of the current + entry and can be referenced by `entrytarget`. In `entrynewkey`, you + may use standard Perl regular expression backreferences to captures + from a previous `match` step. + +- When a `fieldset` step has `entrytarget` set to the entrykey of an + entry created by `entrynew`, the target for the field set will be + the `entrytarget` entry rather than the entry being currently + processed. This allows users to create new entries and set fields in + them. + +- If `entrynocite` is used in a `entrynew` or `entryclone` step, the + new/clone entry will be included in the `.bbl` as if the entry/clone + had been `\nocite`ed in the document. + +- If `entrynull` is set, processing of the `\map` immediately + terminates and the current entry is not created. It is as if it did + not exist in the datasource. Obviously, you should select the + entries which you want to apply this to using prior mapping steps. + +- If `entryclone` is set, a clone of the entry is created with an + entry key `clonekey`. Obviously this may cause labelling problems in + author/year styles etc. and should be used with care. The cloned + entry is in-scope during the processing of the current entry and can + be modified by passing its key as the value to `entrytarget`. In + `clonekey`, you may use standard Perl regular expression + backreferences to captures from a previous `match` step. + +- If `cited` is used then only apply the step if the entry key of an + entry was specifically cited via `\cite`. + +- If `nocited` is used then only apply the step if the entry key of an + entry was specifically nocited via `\nocite` or was included via + `\nocite{*}`. + +- If `citedornocited` is used then only apply the step if the entry + key of an entry was specifically cited via `\cite` or specifically + nocited via `\nocite`. + +- If `allnocited` is used then only apply the step if the entry key of + an entry was included via `\nocite{*}`. + +- If `starnocited` is used then only apply the step if the entry key + of an entry was included solely because of `\nocite{*}`. This + implies that the entry was neither explicitly `\cite`ed nor + explicitly `\nocite`ed. + +- Change the `typesource` `entrytype` to the `typetarget` `entrytype`, + if defined. If `final` is `true` then if the `entrytype` of the + entry is not `typesource`, processing of the parent `\map` + immediately terminates. + +- Change the `fieldsource` `entryfield` to `fieldtarget`, if defined. + If `final` is `true` then if there is no `fieldsource` `entryfield` + in the entry, processing of the parent `\map` immediately + terminates. + +- If `notfield` is true only if the `entryfield` does not exist. + Usually used with `final` so that if an entry does contain + `entryfield`, the map terminates. + +- If `match` is defined but `replace` is not, only apply the step if + the `fieldsource` `entryfield` matches the `match` regular + expression (logic is reversed if you use `notmatch` and + case-insensitive if you use the versions ending in <i>)[1]. You + may use capture parenthesis as usual and refer to these (\$1...\$9) + in later `fieldvalue` specifications. This allows you to pull out + parts of some fields and put these parts in other fields. + +- Perform a regular expression match and replace on the value of the + `fieldsource` `entryfield` if `match` and `replace` are defined. + +- If `matches` is defined, it should be a comma-separated list of + literal strings which are replaced by corresponding locations in a + comma-separated list provided in `replace`. The lists must have the + same number of elements or the step will be skipped. `matchesi` is + the same but case-insensitive. + +- If `fieldset` is defined, then its value is `entryfield` which will + be set to a value specified by further options. If `overwrite` is + false for this step and the field to set already exists then the map + step is ignored. If `final` is also true for this step, then + processing of the parent map stops at this point. If `append` is + true, then the value to set is appended to the current value of + `entryfield`. `appendstrict` only appends to `entryfield` if + `entryfield` is not empty. The value to set is specified by a + mandatory one and only one of the following options: + + -  `fieldvalue` --- The `fieldset` `entryfield` is set to the + `fieldvalue` `string` + + -  `null` --- The `fieldset` `entryfield` is ignored, as if it did + not exist in the datasource + + -  `origentrytype` --- The `fieldset` `entryfield` is set to the + most recently mentioned `typesource` `entrytype` name + + -  `origfield` --- The `fieldset` `entryfield` is set to the most + recently mentioned `fieldsource` `entryfield` name + + -  `origfieldval` --- The `fieldset` `entryfield` is set to the + most recently mentioned `fieldsource` value + +[1] Regular expressions are full Perl 5.16 regular expressions. This +means you may need to deal with special characters, see examples. +]] + }, + stripzeros = { + arguments = {{meta = "integer"}}, + details = [[ +```latex +\stripzeros{integer} +``` + +This command strips leading zeros from a number. It is intended for date +formatting and ordinals. + +For every field marked as a <Label field> in the data model, a +formatting directive is created as per `shorthandwidth` above. Since +`shorthand` is so marked in the default data model, this functionality +is a superset of that described for `shorthandwidth`. + +Similar to `shorthandwidth`, but referring to the `labelnumber` field +and the length register `\labelnumberwidth`. Numeric styles should +adjust this directive such that it corresponds to the format used in the +bibliography. + +Similar to `shorthandwidth`, but referring to the `labelalpha` field and +the length register `\labelalphawidth`. Alphabetic styles should adjust +this directive such that it corresponds to the format used in the +bibliography. + +A special formatting directive for use with `\printfield` and +`\printtext`. This directive wraps its argument in a `\bibhyperref` +command, see ?? for details. + +A special formatting directive for use with `\printfield` and +`\printtext`. It wraps its argument in a `\bibhyperlink` command, see ?? +for details. The `name` argument passed to `\bibhyperlink` is the value +of the `entrykey` field. + +A special formatting directive for use with `\printfield` and +`\printtext`. It wraps its argument in a `\bibhypertarget` command, see +?? for details. The `name` argument passed to `\bibhypertarget` is the +value of the `entrykey` field. + +A special formatting directive which controls the format of the +page/text portion in the argument of citation commands like `\volcite`. + +A special formatting directive which controls the format of the volume +portion in the argument of citation commands like `\volcite`. + +A special formatting directive which controls the format of `\printdate` +(??). Note that the date format (long/short etc.) is controlled by the +package option `date` from ??. This formatting directive only controls +additional formatting such as fonts etc. + +As `date` but controls the format of `\printlabeldate`. + +As `date` but controls the format of `\printdate`. + +A special formatting directive which controls the format of `\printtime` +(??). Note that the time format (24h/12h etc.) is controlled by the +package option `time` from ??. This formatting directive only controls +additional formatting such as fonts etc. + +As `time` but controls the format of `\printlabeltime`. + +As `time` but controls the format of `\printtime`. +]] + }, + strname = { + arguments = {{meta = "name list"}}, + details = [[ +```latex +\strname{name list} +``` + +Similar to `\thename`, except that the name internal representation is +automatically sanitized such that its value may safely be used in the +formation of a control sequence name. +]] + }, + subtitlepunct = { + details = [[ +```latex +\subtitlepunct +``` + +The separator printed between the fields `title` and `subtitle`, +`booktitle` and `booksubtitle`, as well as `maintitle` and +`mainsubtitle`. With the default styles, this separator replaces +`\newunitpunct` at this location. The default definition is +`\newunitpunct`, i.e. it is not handled differently from regular unit +punctuation. + +```latex +\subtitlepunct +``` + +The separator to be printed between the fields `title` and `subtitle`, +`booktitle` and `booksubtitle`, as well as `maintitle` and +`mainsubtitle`. Use this separator instead of `\newunitpunct` at this +location. The default is `\newunitpunct`, i.e. it is not handled +differently from regular unit punctuation but permits convenient +reconfiguration. +]] + }, + supercitedelim = { + details = [[ +```latex +\supercitedelim +``` + +Similar to `\multicitedelim`, but used by the `\supercite` command only. +The default is a comma. + +```latex +\supercitedelim +``` + +Similar to `\multinamedelim`, but intended for the `\supercite` command +only. The default is a comma. +]] + }, + supercitesubentrydelim = { + details = [[ +```latex +\supercitesubentrydelim +``` + +Analogue of `\multicitesubentrydelim` for `\supercite`. The default is +`\supercitedelim`. +]] + }, + texouterlang = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\texouterlang{text} +``` + +Locally switches from the current language to the surrounding language +(which was not selected by `biblatex`) to typeset `text`. This can be +used the `wrapper` argument in the localisation string commands above. +]] + }, + textcite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"} + }, + details = "$ref:biblatex.sty#/commands/Textcite/details" + }, + textnohyphenation = { + arguments = {{meta = "text"}}, + details = [[ +```latex +\textnohyphenation{text} +``` + +Similar to `\nohyphenation` but restricted to the `text` argument. +]] + }, + thefield = { + arguments = {{meta = "field"}}, + details = [[ +```latex +\thefield{field} +``` + +Expands to the unformatted `field`. If the `field` is undefined, this +command expands to an empty string. +]] + }, + thefirstlistitem = { + arguments = {{meta = "literal list"}}, + details = [[ +```latex +\thefirstlistitem{literal list} +``` + +Expands to the unformatted first item in `literal list`. If the +`literal list` is undefined, this command expands to an empty string. +]] + }, + thelist = { + arguments = {{meta = "literal list"}}, + details = [[ +```latex +\thelist{literal list} +``` + +Expands to the unformatted `literal list`. If the list is undefined, +this command expands to an empty string. Note that this command will +dump the `literal list` in the internal format used by this package. +This format is not suitable for printing. +]] + }, + translatortypedelim = { + details = [[ +```latex +\translatortypedelim +``` + +The delimiter printed between the translator and the `translator` +string. The default is a comma followed by a space. +]] + }, + translit = { + arguments = { + {delimiters = {"[", "]"}, meta = "langids", optional = true}, + {meta = "field or fieldset"}, + {meta = "from"}, + {meta = "to"} + }, + details = [=[ +```latex +\translit[langids]{field or fieldset}{from}{to} +``` + +Specifies that the data field `field` or all fields in a fieldset +`fieldset` declared with `\DeclareDatafieldSet` (see ??) should be +transliterated from script `from` to script `to` for sorting purposes. +The field/set argument should be <\*> to apply transliteration to +all fields. The valid `from` and `to` values are given in table +[\[tab:translit\]][1]. The optional `langids` parameter is a +comma-separated list of `langid` fields and the transliteration will +apply only to bibliography entries containing one of the `langid`s in +the list. Note that `biblatex`does not aim to support general +transliteration, only those which are useful for sorting purposes. +Please open a GitHub ticket for `biblatex` if you think you need +additional transliterations. + +An example of transliterating titles so that they sort correctly in +Sanskrit. This example assumes that entries that should have their title +fields transliterated have a `langid` field set to <sanskrit>. + + \DeclareDatafieldSet{settitles}{ + \member[field=title] + \member[field=booktitle] + \member[field=eventtitle] + \member[field=issuetitle] + \member[field=journaltitle] + \member[field=maintitle] + \member[field=origtitle] + } + + \DeclareSortTranslit{ + \translit[sanskrit]{settitles}{iast}{devanagari} + } + + [1]: #tab:translit +]=] + }, + uniquename = { + details = [[ +```latex +\uniquename +``` + +This counter refers to the `labelname` list. It is set on a per-name +basis. Its value is `0` if the base parts of the name (by default just +the <family> part of the name) are unique, `1` if adding the other +non-base parts of the name (as specified in the uniquename template +defined by `\DeclareUniquenameTemplate`) as initials will make it +unique, and `2` if adding the full form of the non-base parts of the +name are required to disambiguate the name. This information is required +by author-year and author-title citation schemes which add additional +parts of the name when citing different authors with the same family +name. For example, (given the default `\DeclareUniquenameTemplate` +definition) if there is one <John Doe> and one <Edward Doe> in the +list of references, this counter will be set to `1`. If there is one +<John Doe> and one <Jane Doe>, the value of the counter will be +`2`. If the option is set to `init`/`allinit`/`mininit`, the counter +will be limited to `1`. This is useful for citations styles which use +initials to disambiguate names but never print the full name in +citations. If adding the initials is not sufficient to disambiguate the +name, `uniquename` will also be set to `0` for that name. This feature +needs to be enabled explicitly with the package option `uniquename`. +Note that the `uniquename` counter is local to `\printnames` and that it +is only set for the `labelname` list and for the name list that +`labelname` has been derived from (typically `author` or `editor`). Its +value is zero in any other context, i.e., it must be evaluated in the +name formatting directives handling name lists. See ?? for further +details and practical examples. This counter can be overridden on a +per-namepart basis by consulting the `\namepartun` macros +during name formatting, see ??. +]] + }, + unspace = { + details = [[ +```latex +\unspace +``` + +Removes preceding whitespace, i.e. removes all skips and penalties from +the end of the current horizontal list. This command is implicitly +executed by all of the following commands. +]] + }, + usebibmacro = { + arguments = {{literal = "*", optional = true}, {meta = "name"}}, + details = [[ +```latex +\usebibmacro*{name} +``` + +This command executes the macro `name`, as defined with `\newbibmacro`. +If the macro takes any arguments, they are simply appended after `name`. +The regular variant of this command sanitizes `name` while the starred +variant does not. +]] + }, + usefirstlistitem = { + arguments = {{meta = "command"}, {meta = "literal list"}}, + details = [[ +```latex +\usefirstlistitem{command}{literal list} +``` + +Executes `command` using the unformatted first item of `literal list` as +its argument. +]] + } +} +environments = { + refsection = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "resource, ... ", + optional = true + } + }, + details = [[ +```latex +\begin{refsection}[resource, ... ] ... \end{refsection} +``` + +The optional argument is a comma-separated list of resources specific to +the reference section. If the argument is omitted, the reference section +will use the default resource list, as specified with `\addbibresource` +in the preamble. If the argument is provided, it replaces the default +resource list. Global resources specified with `\addglobalbib` are +always considered. `refsection` environments may not be nested, but you +may use `refsegment` environments within a `refsection` to subdivide it +into segments. Use the `section` option of `\printbibliography` to +select a section when printing the bibliography, and the corresponding +option of `\printbiblist` when printing bibliography lists. Bibliography +sections are numbered starting at `1`. The number of the current section +is also written to the transcript file. All citations given outside a +`refsection` environment are assigned to section 0. If +`\printbibliography` is used within a `refsection`, it will +automatically select the current section. The `section` option is not +required in this case. This also applies to `\printbiblist`. Beginning a +new reference section automatically ends the active reference context +(see ??). +]] + }, + refsegment = { + details = [[ +```latex +\begin{refsegment} ... \end{refsegment} +``` + +The difference between a `refsection` and a `refsegment` environment is +that the former creates labels which are local to the environment +whereas the latter provides a target for the `segment` filter of +`\printbibliography` without affecting the labels. They will be unique +across the entire document. `refsegment` environments may not be nested, +but you may use them in conjunction with `refsection` to subdivide a +reference section into segments. In this case, the segments are local to +the enclosing `refsection` environment. Use the `segment` option of +`\printbibliography` to select a segment when printing the bibliography. +Within a section, the reference segments are numbered starting at `1` +and the number of the current segment will be written to the transcript +file. All citations given outside a `refsegment` environment are +assigned to segment 0. In contrast to the `refsection` environment, the +current segment is not selected automatically if `\printbibliography` is +used within a `refsegment` environment. +]] + } +} diff --git a/support/digestif/data/cleveref.sty.tags b/support/digestif/data/cleveref.sty.tags new file mode 100644 index 0000000000..9e62e98e05 --- /dev/null +++ b/support/digestif/data/cleveref.sty.tags @@ -0,0 +1,103 @@ +ctan_package = "cleveref" +commands = { + Cpageref = "$ref:cleveref.sty#/commands/cpageref", + Cpagerefrange = "$ref:cleveref.sty#/commands/cpagerefrange", + Cref = "$ref:cleveref.sty#/commands/cref", + Crefformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + Crefmultiformat = {arguments = "$ref:cleveref.sty#/commands/crefmultiformat/arguments"}, + Crefname = { + arguments = {{meta = "type"}, {meta = "singular"}, {meta = "plural"}} + }, + Crefrange = "$ref:cleveref.sty#/commands/crefrange", + Crefrangeformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + Crefrangemultiformat = {arguments = "$ref:cleveref.sty#/commands/crefmultiformat/arguments"}, + cpageref = { + action = "ref", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create a hyperlink." + }, + {list = true, meta = "key"} + }, + summary = "Refer to a page number." + }, + cpagerefrange = { + action = "ref", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create hyperlinks." + }, + {meta = "key1"}, + {meta = "key2"} + }, + summary = "Refer to a range of page numbers." + }, + cref = { + action = "ref", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create a hyperlink." + }, + {list = true, meta = "key"} + }, + summary = "Refer to a section, figure or similar." + }, + crefalias = {arguments = {{meta = "counter"}, {meta = "type"}}}, + crefdefaultlabelformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + crefformat = {arguments = {{meta = "type"}, {meta = "format"}}}, + creflabelformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + crefmultiformat = { + arguments = { + {meta = "type"}, + {meta = "first"}, + {meta = "second"}, + {meta = "middle"}, + {meta = "last"} + } + }, + crefname = { + arguments = {{meta = "type"}, {meta = "singluar"}, {meta = "plural"}} + }, + crefrange = { + action = "ref", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create hyperlinks." + }, + {meta = "key1"}, + {meta = "key2"} + }, + summary = "Refer to a range of sections, figures or similar." + }, + crefrangeformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + crefrangelabelformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + crefrangemultiformat = {arguments = "$ref:cleveref.sty#/commands/crefmultiformat/arguments"}, + labelcpageref = "$ref:cleveref.sty#/commands/cpageref", + labelcref = "$ref:cleveref.sty#/commands/cref", + labelcrefformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + labelcrefmultiformat = {arguments = "$ref:cleveref.sty#/commands/crefmultiformat/arguments"}, + labelcrefrangeformat = {arguments = "$ref:cleveref.sty#/commands/crefformat/arguments"}, + labelcrefrangemultiformat = {arguments = "$ref:cleveref.sty#/commands/crefmultiformat/arguments"}, + lcnamecref = {arguments = {{meta = "#1"}}}, + lcnamecrefs = {arguments = {{meta = "#1"}}}, + nameCref = "$ref:cleveref.sty#/commands/namecref", + nameCrefs = "$ref:cleveref.sty#/commands/namecref", + namecref = { + action = "ref", + arguments = {{meta = "key"}}, + summary = "Print the name of reference (section, figure, etc.)." + }, + namecrefs = "$ref:cleveref.sty#/commands/namecref" +} diff --git a/support/digestif/data/csquotes.sty.tags b/support/digestif/data/csquotes.sty.tags new file mode 100644 index 0000000000..d3dac638f3 --- /dev/null +++ b/support/digestif/data/csquotes.sty.tags @@ -0,0 +1,1113 @@ +-- Copyright 2003-2011 Philipp Lehman +-- Copyright 2015-2019, 2021, 2022 Joseph Wright +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c+ +-- +-- Adapted from the csquotes package documentation, which can be found +-- at https://ctan.org/pkg/csquotes. +ctan_package = "csquotes" +dependencies = {"etoolbox.sty", "keyval.sty"} +commands = { + ["@enablequotes"] = { + details = [[ +```latex +\@enablequotes +``` + +This command enables all characters allocated as active quotes. It also +restores their definitions if they were disabled or accidentally +overwritten. With single-byte encodings, this command (re)defines all +allocated characters and makes them active. With UTF-8 encoding, it +redefines the internal macro used by the `inputenc` package to typeset +the respective UTF-8 sequence (`\u8:``character`). UTF-8 characters in +the range 0--127 are handled as with single-byte encodings. When using a +TeX engine with native UTF-8 support, such as XeTeX , all characters are +handled as with single-byte encodings. +]] + }, + ["@verbatimquotes"] = { + details = [[ +```latex +\@verbatimquotes +``` + +For verbatim environments and similar applications, use this command +rather than `\@disablequotes`. It redefines the active quotes in a way +that is better suited for verbatim typesetting. With single-byte +encodings, it will do one of the following things. (1) If a character is +in the range 0--127, it is redefined such that it expands to itself with +category code 12. (2) If a character is in the range 128--255, there are +two possibilities. (a) If it had already been active when it was +allocated, its former definition is restored. (b) If it had not been +active before, it is redefined such that it expands to itself with its +former category code. + +Characters in the range 0--127 are added to the `\dospecials` list. +Characters in the range 128--255 remain active, permitting the +`inputenc` package to typeset them verbatim (due to case 2a, which +implies that you must load `inputenc` before allocating active quotes). +Case 2b is usually undesirable in verbatim environments. If `inputenc` +is loaded, however, this should not happen. With UTF-8 encoding, this +command restores the former definition of the internal macro used by the +`inputenc` package to typeset the respective UTF-8 sequence. UTF-8 +characters in the range 0--127 are handled as with single-byte +encodings. When using a TeX engine with native UTF-8 support, such as +XeTeX , all characters are handled as with single-byte encodings. + +Due to case 1, `\@verbatimquotes` itself is independent of any +`\dospecials` processing. You may typeset all active quotes verbatim by +using this command exclusively. The advantage of this approach is that +it does not require any category code changes, hence this command may +also be used to modify an argument after it has been read. Also note +that the standard LaTeX verbatim environments as well as all +environments provided by or defined via the packages `verbatim`, +`fancyvrb`, `moreverb`, and `alltt` are catered for automatically. This +also applies to the `\verb` command and the `shortvrb` package. +]] + }, + BlockquoteDisable = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\BlockquoteDisable{code} +``` + +The `code` may be arbitrary LaTeX code which redefines vulnerable +commands locally such that they work differently during the trial pass. +The `code` itself should obviously not include any global assignments. +This solution should be considered as a last ressort but may be the +quickest way to fix a vulnerable package. Note that there is no need to +escape parameter characters by doubling them in the `code` argument. +Simply use this command like `\AtBeginDocument` and similar hooks. +]] + }, + DeclareAutoPunct = { + arguments = {{meta = "characters"}}, + details = [[ +```latex +\DeclareAutoPunct{characters} +``` + +This command defines the punctuation marks to be considered by the +quotation commands as they scan ahead for punctuation. Note that +`characters` is an undelimited list of characters. Valid `characters` +are period, comma, semicolon, colon, exclamation and question mark. The +default setting is: + + {} + \DeclareAutoPunct{.,;:!?} + +This definition is restored automatically whenever the `autopunct` +package option is set to `true`. Executing `\DeclareAutoPunctuation{}` +is equivalent to setting `autopunct=false`, i.e. it disables this +feature. +]] + }, + DeclarePlainStyle = { + arguments = {{meta = "opening outer mark"}, {meta = "closing outer mark"}}, + details = [[ +```latex +\DeclarePlainStyle{opening outer mark}{closing outer mark}\\ +``` + +opening inner markclosing inner mark + +This command may be used in the configuration file or in the document +preamble. By default, outer quotations get straight double quotes and +inner quotations straight single quotes. See ?? for additional hints +concerning PDF strings. +]] + }, + DeclareQuoteAlias = { + arguments = { + {delimiters = {"[", "]"}, meta = "variant", optional = true}, + {meta = "style"}, + {meta = "alias"} + }, + details = [[ +```latex +\DeclareQuoteAlias[variant]{style}{alias} +\DeclareQuoteAlias{first-level alias}{second-level alias} +``` + +This command may be used in the configuration file or in the document +preamble. The alias may point to a backend style or to another alias. +Most language aliases refer to a backend style, but some point to an +intermediate alias instead. If the alias is defined for the sake of the +`babel` or the `polyglossia` package, its name must be identical to the +language name used by `babel`/`polyglossia`, i.e. the expansion of +`\languagename`. See ?? for an illustration of how quote styles, +aliases, and package options interact. A list of all aliases defined by +default is given in ??. +]] + }, + DeclareQuoteGlyph = { + arguments = {{meta = "encoding"}, {meta = "position"}}, + details = [[ +```latex +\DeclareQuoteGlyph{encoding}{position} +``` + + +]] + }, + DeclareQuoteOption = { + arguments = {{meta = "style"}}, + details = [[ +```latex +\DeclareQuoteOption{style} +``` + +When using the new option, the name of the quote style will serve as the +key. The value may be any style variant defined for the respective +style. The package option will select a variant by defining an alias +pointing to the desired backend style. This command is available in the +configuration file only. See ?? for an illustration of how quote styles, +aliases, and package options interact. +]] + }, + DeclareQuoteStyle = { + arguments = { + {delimiters = {"[", "]"}, meta = "variant", optional = true}, + {meta = "style"}, + {delimiters = {"[", "]"}, meta = "outer init", optional = true}, + {delimiters = {"[", "]"}, meta = "inner init", optional = true} + }, + details = [[ +```latex +\DeclareQuoteStyle[variant]{style}[outer init][inner init]\\ +``` + +opening outer mark\[middle outer mark\]closing outer mark\[kern\] +opening inner mark\[middle inner mark\]closing inner mark + +This command may be used in the configuration file or in the document +preamble. The term <outer> refers to the first quotation level, +<inner> means quotations within another quotation. A <middle mark> +is a quotation mark inserted at the beginning of every paragraph within +a quotation spanning multiple paragraphs. In most cases, the arguments +defining the quotation marks will simply contain one of the commands +listed in ??. If both an outer and an inner quotation begin or end +simultaneously, the kerning specified by the value `kern` will be +inserted between the adjoining quotation marks. While this value can be +given in any unit known to TeX , it is advisable to use the relative, +font-dependent unit <em> instead of absolute units such as points, +inches, or millimeters. Note that `kern` is used as a fallback value +only. If the font provides kerning data for the respective pair of +quotation marks the font's kerning takes precedence. `outer init` and +`inner init` are all-purpose hooks initializing the quote style. +Selecting a quote style will make these hooks available to all quotation +commands without expanding them. The execution of `outer init` will take +place immediately before the opening outer quote is inserted, but inside +the group formed by the quotation. `inner init` is executed before the +opening inner quote is inserted. It is advisable to avoid any global +assignments in this context to prevent interference with other styles. +Whenever `inner init` is used `outer init` has to be given as well, even +if the argument is empty. Refer to ?? for a list of all predefined quote +styles and their variants. These are the backend styles only, see also +?? for a list of language aliases. See ?? for some examples as well as +an illustration of how quote styles, aliases, and package options +interact. +]] + }, + EnableQuotes = { + details = [[ +```latex +\EnableQuotes +``` + +Enables all active quotes by redefining the allocated characters and +making them active. It also restores them when disabled, set to +verbatim, or overwritten. +]] + }, + ExecuteQuoteOptions = { + arguments = {{meta = "key=value,\\,... "}}, + details = [[ +```latex +\ExecuteQuoteOptions{key=value,\,... } +``` + +This command permits presetting package options in the configuration +file. It may also be used in the document preamble. +]] + }, + MakeAutoQuote = { + arguments = { + {literal = "*", optional = true}, + {meta = "character 1"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeAutoQuote*{character 1}{character 2} +``` + +All active quotes defined with `\MakeAutoQuote` work like `\enquote`. +Those defined with `\MakeOuterQuote` and `\MakeInnerQuote` cover only a +part of this functionality. The former correspond to the outer level of +`\enquote` whereas the latter correspond to the starred version. +`\MakeAutoQuote*` is similar to `\MakeInnerQuote`, i.e. it corresponds +to `\enquote*`. +]] + }, + MakeBlockQuote = { + arguments = { + {meta = "character 1"}, + {meta = "delimiter"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeBlockQuote{character 1}{delimiter}{character 2} +``` + +The arguments are checked for validity, see ?? for details. All active +quotes defined with `\MakeBlockQuote` behave essentially the same as +`\blockquote`, but the handling of the citation is slightly different. +`character 1` will serve as the opening mark in the source file, +`character 2` as the closing one. The character indicated by the middle +argument `delimiter` will serve as a delimiter separating the quoted +text from the citation which is given last as the active quotes are +used: + + \MakeBlockQuote{<}{|}{>} + ... + + +If the delimiter is omitted, the entire text between the opening and the +closing mark will be treated as quotation text. +]] + }, + MakeForeignBlockQuote = { + arguments = { + {meta = "lang"}, + {meta = "character 1"}, + {meta = "delimiter"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeForeignBlockQuote{lang}{character 1}{delimiter}{character 2} +``` + +The active quotes defined with this command are similar in concept and +function to `\foreignblockquote`. The behavior of the delimiter +character is similar to `\MakeBlockQuote`. +]] + }, + MakeForeignQuote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {meta = "character 1"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeForeignQuote{lang}{character 1}{character 2} +\MakeForeignQuote*{lang}{character 1}{character 2} +``` + +The active quotes defined with the above commands are similar in concept +and function to `\foreignquote` and `\foreignquote*`, respectively. +]] + }, + MakeHybridBlockQuote = { + arguments = { + {meta = "lang"}, + {meta = "character 1"}, + {meta = "delimiter"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeHybridBlockQuote{lang}{character 1}{delimiter}{character 2} +``` + +The active quotes defined with this command are similar in concept and +function to `\hybridblockquote`. The behavior of the delimiter character +is similar to `\MakeBlockQuote`. +]] + }, + MakeHyphenQuote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {meta = "character 1"}, + {meta = "character 2"} + }, + details = [[ +```latex +\MakeHyphenQuote*{lang}{character 1}{character 2} +``` + +The active quotes defined with the above commands are similar in concept +and function to `\hyphenquote` and `\hyphenquote*`, respectively. +]] + }, + MakeInnerQuote = { + arguments = {{meta = "character"}}, + details = [[ +```latex +\MakeOuterQuote{character} +\MakeInnerQuote{character} +``` + +`\MakeAutoQuote` defines active quotes which toggle between outer and +inner quotations automatically. The two mandatory arguments serve as +opening and closing mark and must be distinct: +]] + }, + MakeOuterQuote = { + arguments = {{meta = "character"}}, + details = "$ref:csquotes.sty#/commands/MakeInnerQuote/details" + }, + SetBlockEnvironment = { + arguments = {{meta = "environment"}}, + details = [[ +```latex +\SetBlockThreshold{integer} +\SetBlockEnvironment{environment} +\SetCiteCommand{command} +``` + +`\SetBlockThreshold` defines the number of lines or words the block +quotation facilities use as a threshold when determining whether a +quotation should be typeset in inline or in display mode. The default is +three. `\SetBlockEnvironment` specifies the environment used for block +and display quotations. It takes the name of an existing environment as +its argument. The default is the `quote` environment provided by most +document classes. The argument to `\SetCiteCommand` specifies a +replacement for `\cite` which will be used by all integrated quotation +facilities to handle citations. It must be a single command which takes +one or two optional arguments followed by a mandatory one, the citation +key. The default is `\cite`. The citation commands of the `natbib`, +`jurabib`, and `biblatex` packages, which take two optional arguments, +are supported. +]] + }, + SetBlockThreshold = { + arguments = {{meta = "integer"}}, + details = "$ref:csquotes.sty#/commands/SetBlockEnvironment/details" + }, + SetCiteCommand = { + arguments = {{meta = "command"}}, + details = "$ref:csquotes.sty#/commands/SetBlockEnvironment/details" + }, + VerbatimQuotes = { + details = [[ +```latex +\VerbatimQuotes +``` + +Switches to verbatim active quotes. All active quotes will be printed +verbatim until their default behavior is restored with `\EnableQuotes`. +]] + }, + blockcquote = { + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\blockcquote[prenote][postnote]{key}[punct]{text} +``` + +The difference between `\blockcquote` and `\blockquote` is that there +are three citation arguments instead of one. The handling of these +citation arguments is similar to `\textcquote`; see ?? for details. Also +see ?? on how to customize block quotations. +]] + }, + blockquote = { + arguments = { + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\blockquote[cite][punct]{text} +``` + +This command determines the length of the `text`. If the length exceeds +a certain threshold, the `text` will be typeset in display mode, i.e. as +a block quotation. If not, `\blockquote` will behave like `\textquote`. +Depending on the `thresholdtype` option, the threshold may be based on +the number of lines required to typeset the `text` or on the number of +words in the `text`. If the `parthreshold` option has been enabled, any +explicit paragraph or line break in the `text` will trigger the +threshold, i.e. it will be typeset in display mode regardless of its +length. The default threshold setup is three lines with `parthreshold` +enabled. The default environment used for display quotations is the +`quote` environment. See ?? on how to change these parameters. Note that +`csquotes` will force inline quotations in footnotes, parboxes, +minipages, and floats by default. Use the `csdisplay` option from ?? to +change this behavior. The optional arguments `cite` and `punct` specify +the citation and any terminal punctuation of the `text`. `tpunct` +denotes trailing punctuation after the command. If the `autopunct` +option is enabled, the quotation commands will scan ahead for +punctuation marks immediately following their last argument and can move +them around if required. See ?? on how to change the way these arguments +are handled and ?? for reasons why you may want to specify the +punctuation as a separate argument. +]] + }, + closeautoquote = { + details = [[ +```latex +\openautoquote Opens a nestable quotation. +\closeautoquote Closes a nestable quotation. +``` + + +]] + }, + closeinnerquote = { + details = [[ +```latex +\openinnerquote Opens an inner quotation. +\closeinnerquote Closes an inner quotation. +``` + + +]] + }, + enquote = { + arguments = {{literal = "*", optional = true}, {meta = "text"}}, + details = [[ +```latex +\enquote{text} +\enquote*{text} +``` + +Like all quotation facilities, this command is context sensitive. +Depending on the nesting level, it will toggle between outer and inner +quotation marks with plain and nested quotations. The starred version of +this command skips directly to the inner level. If multilingual support +is enabled, the style of all quotation marks will be adapted to the +current language. +]] + }, + foreignblockcquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\foreignblockcquote{lang}[prenote][postnote]{key}[punct]{text} +``` + +This command combines `\blockcquote` with `\foreignlanguage`. Long +quotations will be wrapped in an `otherlanguage*` environment. The +handling of the citation arguments is similar to `\textcquote`. +]] + }, + foreignblockquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\foreignblockquote{lang}[cite][punct]{text} +``` + +This command behaves like `\foreignquote` if the quotation is short. If +it exceeds the threshold, it will be wrapped in an `otherlanguage*` +environment which is in turn wrapped in a block quotation environment. +The arguments are handled as with `\blockquote`. +]] + }, + foreignquote = { + arguments = {{literal = "*", optional = true}, {meta = "lang"}, {meta = "text"}}, + details = [[ +```latex +\foreignquote{lang}{text} +\foreignquote*{lang}{text} +``` + +This command combines `\enquote` with `\foreignlanguage`. It switches +hyphenation patterns and enables the extra definitions provided by +`babel`/`polyglossia` for `lang`, which must be a language name known to +the respective package. The quotation marks will match the language of +the quoted piece of text. +]] + }, + foreigntextcquote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\foreigntextcquote{lang}[prenote][postnote]{key}[punct]{text} +\foreigntextcquote*{lang}[prenote][postnote]{key}[punct]{text} +``` + +This command combines `\textcquote` with `\foreignlanguage`. The +handling of the arguments is similar to `\textcquote`. +]] + }, + foreigntextquote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\foreigntextquote{lang}[cite][punct]{text} +\foreigntextquote*{lang}[cite][punct]{text} +``` + +This command combines `\textquote` with `\foreignlanguage`. Apart from +the language, the arguments are handled as with `\textquote`. +]] + }, + hybridblockcquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\hybridblockcquote{lang}[prenote][postnote]{key}[punct]{text} +``` + +This command behaves like `\hyphenblockcquote` if the quotation is +short, and like `\foreignblockquote` if it is long. The handling of the +citation arguments is similar to `\textcquote`. +]] + }, + hybridblockquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\hybridblockquote{lang}[cite][punct]{text} +``` + +This command behaves like `\hyphenquote` if the quotation is short. If +it exceeds the threshold, the command behaves like `\foreignblockquote`. +In other words, it combines features of `\foreignblockquote` and +`\hyphenblockquote`. The arguments are handled as with `\blockquote`. +]] + }, + hyphenquote = { + arguments = {{literal = "*", optional = true}, {meta = "lang"}, {meta = "text"}}, + details = [[ +```latex +\hyphenquote*{lang}{text} +``` + +This command combines `\enquote` with the `hyphenrules` environment, +that is, it merely switches hyphenation patterns. The quotation marks +will match the language of the text surrounding the quotation. +]] + }, + hyphentextcquote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\hyphentextcquote*{lang}[prenote][postnote]{key}[punct]{text} +``` + +This command combines `\textcquote` with the `hyphenrules` environment. +The handling of the arguments is similar to `\textcquote`. +]] + }, + hyphentextquote = { + arguments = { + {literal = "*", optional = true}, + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\hyphentextquote*{lang}[cite][punct]{text} +``` + +This command combines `\textquote` with the `hyphenrules` environment. +Apart from the language, the arguments are handled as with `\textquote`. +]] + }, + ifblockquote = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifblockquote{true}{false} +``` + +Expands to `true` in all block and display quotations, and to `false` +otherwise. +]] + }, + ifpunctmark = { + arguments = {{meta = "character"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifpunctmark{character}{true}{false} +``` + +Expands to `true` if preceeded by the punctuation mark `character`, and +to `false` otherwise. The `character` may be a period, a comma, a +semicolon, a colon, an exclamation mark, or a question mark. Note that +this test is only available in the definition of the hooks from ??. +]] + }, + ifterm = { + arguments = {{meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifterm{true}{false} +``` + +Expands to `true` if preceeded by a terminal punctuation mark (period, +exclamation mark, or question mark), and to `false` otherwise. Note that +this test is only available in the definition of the hooks from ??. +]] + }, + iftextpunct = { + arguments = {{meta = "text"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\iftextpunct{text}{true}{false} +``` + +Executes `true` if the `text` ends with any punctuation mark, and to +`false` otherwise. This command is robust. +]] + }, + initiquote = { + details = [[ +```latex +\initoquote Executes the outer initialization hook. +\initiquote Executes the inner initialization hook. +``` + + +]] + }, + initoquote = {details = "$ref:csquotes.sty#/commands/initiquote/details"}, + mkbegdispquote = { + arguments = {{meta = "punct"}, {meta = "cite"}}, + details = [[ +```latex +\mkbegdispquote{punct}{cite} +\mkenddispquote{punct}{cite} +``` + +The `\mkbegdispquote` and `\mkenddispquote` hooks are used by +`displayquote` and related environments from ??. These hooks take two +arguments: + +#1 +The `punct` argument passed to the `\begin` line of the environment. If +there is no `punct` argument, this parameter is empty. + +#2 +The `cite` argument passed to the environment, wrapped in `\mkcitation`. +If there is no `cite` argument, this parameter is empty. With integrated +quotation environments, this parameter is the citation code, wrapped in +`\mkccitation`. + +By default, `\mkenddispquote` adds the `punct` argument as well as the +`cite` argument or the citation code at the very end of the quotation. +`\mkbegdispquote` does not insert anything be default. This is +equivalent to the following definition: + + \newcommand{<<\mkbegdispquote>>}[2]{} + \newcommand{<<\mkenddispquote>>}[2]{#1#2} + +See ?? for practical examples. +]] + }, + mkcitation = { + arguments = {{meta = "cite"}}, + details = [[ +```latex +\mkcitation{cite} +``` + +All facilities which take a `cite` argument will pass it to the +`\mkcitation` hook, which may be redefined to format the citation. +`\mkcitation` will only be executed if there is a citation. The default +behavior is to separate the citation from the preceding text by an +interword space and enclose it in parentheses. This is equivalent to the +following definition: + + [showspaces=true] + \newcommand*{<<\mkcitation>>}[1]{ (#1)} +]] + }, + mkenddispquote = { + arguments = {{meta = "punct"}, {meta = "cite"}}, + details = "$ref:csquotes.sty#/commands/mkbegdispquote/details" + }, + mktextquote = { + arguments = { + {meta = "open"}, + {meta = "text"}, + {meta = "close"}, + {meta = "punct"}, + {meta = "tpunct"}, + {meta = "cite"} + }, + details = [[ +```latex +\mktextquote{open}{text}{close}{punct}{tpunct}{cite} +``` + +The `\mktextquote` hook controls the layout of all text quotations. This +hook is used by `\textquote` and related commands from ??. `\blockquote` +and related commands from ?? use this hook for short quotations. It +takes six arguments which may be arranged according to the desired +output: + +#1 +The opening quotation mark. + +#2 +The `text` argument of the command. + +#3 +The closing quotation mark. + +#4 +The optional `punct` argument of the command. If there is no `punct` +argument, this parameter is empty. + +#5 +Trailing `tpunct` punctuation immediately after the command. If there is +no such punctuation or if the `autopunct` feature is disabled, this +parameter is empty. + +#6 +The optional `cite` argument of the command, wrapped in `\mkcitation`. +If there is no `cite` argument, this parameter is empty. With integrated +quotation commands, this parameter is the citation code, wrapped in +`\mkccitation`. + +By default, `\mktextquote` encloses the `punct` argument in the +quotation marks along with the `text` and inserts the `cite` argument or +the citation code before any trailing `tpunct` punctuation. This is +equivalent to the following definition: + + \newcommand{<<\mktextquote>>}[6]{#1#2#4#3#6#5} + +The way in which `\mktextquote` hooks into the formatting process is +best seen when looking at an example. The commands + + \textquote[<>]{<>} + \textcquote[<<55>>]{<>}[<<.>>]{<>} + \blockcquote[<<87>>]{<>}{<>}<<.>> + +would execute `\mktextquote` with the following arguments: + + \mktextquote{open}{<>}{close}{}{}{\mkcitation{<>}} + \mktextquote{open}{<>}{close}{<<.>>}{}{\mkccitation{\cite[<<55>>]{<>}}} + \mktextquote{open}{<>}{close}{}{<<.>>}{\mkccitation{\cite[<<87>>]{<>}}} + +where `\cite` is the command selected with `\SetCiteCommand` and +`open`/`close` are internal macros which print the opening and closing +quotation marks. Note that these internal macros are fully-fledged +markup elements with grouping and nesting control. They must be placed +in the correct order, otherwise `csquotes` will report errors about +unbalanced groups or invalidly nested quotations. Since the `text` +should obviously be enclosed in the quotation marks, the parameter order +`#1#2#3` is effectively fixed. The parameters `#4`, `#5`, `#6` may be +placed freely. +]] + }, + openautoquote = {details = "$ref:csquotes.sty#/commands/closeautoquote/details"}, + openinnerquote = {details = "$ref:csquotes.sty#/commands/closeinnerquote/details"}, + setquotestyle = { + arguments = { + {delimiters = {"[", "]"}, meta = "variant", optional = true}, + {meta = "style"} + }, + details = [[ +```latex +\setquotestyle[variant]{style} +\setquotestyle{alias} +\setquotestyle* +``` + +The regular form of this command selects a quote style and disables +multilingual support. Its mandatory argument may be a quote style or an +alias. If it is a quote style, the optional argument indicates the style +variant. The starred version, which takes no arguments, enables +multilingual support. Please refer to ?? for a list of available styles, +style variants, and language aliases. +]] + }, + textciquote = { + details = [[ +```latex +\textciquote Prints the closing inner quotation mark. +\textmiquote Prints the middle inner quotation mark. +``` + + +]] + }, + textcoquote = { + details = [[ +```latex +\textooquote Prints the opening outer quotation mark of the currently active quote style. +\textcoquote Prints the closing outer quotation mark. +\textmoquote Prints the middle outer quotation mark. +``` + + +]] + }, + textcquote = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\textcquote[prenote][postnote]{key}[punct]{text} +\textcquote*[prenote][postnote]{key}[punct]{text} +``` + +The `text` may be any arbitrary piece of text to be enclosed in +quotation marks. The optional arguments `cite` and `punct` specify the +citation and any terminal punctuation of `text`. `tpunct` denotes +trailing punctuation after the command. If the `autopunct` option is +enabled, the quotation commands will scan ahead for punctuation marks +immediately following their last argument and can move them around if +required. See ?? on how to change the way these arguments are handled +and ?? for reasons why you may want to specify the punctuation as a +separate argument. The starred version of this command skips directly to +the inner quotation level. The remaining arguments are handed over to +`\cite`. Note that `\cite` normally supports one optional argument only. +`prenote` is only available in conjunction with the `natbib`, `jurabib`, +and `biblatex` packages. How these arguments are handled depends on the +citation command. With `natbib` and `biblatex`, `prenote` is in fact a +notice such as <see>. With jurabib, this argument has a different +function by default. The argument `postnote`, which is always available, +indicates the citation postnote. This is usually a page number. `key` is +the citation key. See ?? on how to customize the citation. +]] + }, + textelp = { + arguments = {{literal = "*", optional = true}, {meta = "text"}}, + details = [[ +```latex +\textelp{} +\textelp{text} +\textelp*{text} +``` + +When used with an empty `text` argument, this command prints an ellipsis +symbol to indicate the omission of material from the quoted material. +When used with a non-empty argument, the ellipsis symbol is followed by +the `text` enclosed in square brackets to indicate that the `text` has +been added after the omitted material. The starred version reverts the +order, i.e. it prints the `text` followed by an ellipsis symbol to +indicate that the `text` has been added before the omitted material. In +sum, there are three ways to use this command: + + [escapechar={\%},escapebegin={\rmfamily}] + \textelp{} %= \textelp{} % + \textelp{text} %= \textelp{text} % + \textelp*{text} %= \textelp*{text} % + +The insertion of text or individual letters may be indicated with the +following command: +]] + }, + textins = { + arguments = {{literal = "*", optional = true}, {meta = "text"}}, + details = [[ +```latex +\textins*{text} +``` + +By default, `\textins` will enclose the `text` added to the quoted +material in square brackets. The starred version is intended for minor +changes, such as the capitalization of a word, which are required to +adapt the quoted material to the new context in which it is quoted. + + [escapechar={\%},escapebegin={\rmfamily}] + \textins{text} %= \textins{text} % + \textins*{T}ext %= \textins*{T}ext % + +The deletion of individual letters may be indicated with the following +command: +]] + }, + textmiquote = {details = "$ref:csquotes.sty#/commands/textciquote/details"}, + textmoquote = {details = "$ref:csquotes.sty#/commands/textcoquote/details"}, + textooquote = {details = "$ref:csquotes.sty#/commands/textcoquote/details"}, + textquote = { + arguments = { + {literal = "*", optional = true}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true}, + {meta = "text"} + }, + details = [[ +```latex +\textquote[cite][punct]{text} +\textquote*[cite][punct]{text} +``` + +The `text` may be any arbitrary piece of text to be enclosed in +quotation marks. The optional arguments `cite` and `punct` specify the +citation and any terminal punctuation of `text`. `tpunct` denotes +trailing punctuation after the command. If the `autopunct` option is +enabled, the quotation commands will scan ahead for punctuation marks +immediately following their last argument and can move them around if +required. See ?? on how to change the way these arguments are handled +and ?? for reasons why you may want to specify the punctuation as a +separate argument. The starred version of this command skips directly to +the inner quotation level. Here are some usage examples: + + \textquote{...} + \textquote[][.]{...} + \textquote[Doe 1990, 67]{...} + \textquote[{\cite[67]{doe90}}]{...} + +Note the use of the optional arguments in the examples above. As seen in +the second example, `cite` is required whenever `punct` is used, even if +it is empty. Also keep in mind that an optional argument containing +square brackets must be wrapped in an additional pair of curly braces as +shown in the last example. When working with automated citations, you +might also want to learn about the integrated quotation facilities +presented in ??. +]] + }, + unspace = { + details = [[ +```latex +\unspace +``` + +Removes preceding whitespace, i.e. removes all skips and penalties from +the end of the current horizontal list. +]] + } +} +environments = { + displaycquote = { + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true} + }, + details = [[ +```latex +\begin{displaycquote}[prenote][postnote]{key}[punct] ... \end{displaycquote} +``` + +The difference between `displaycquote` and its more basic counterpart is +that there are three citation arguments instead of one. The placement of +the citation is similar to `displayquote`. The handling of the citation +arguments is similar to `\textcquote`, see ?? for details. See ?? on how +to customize this environment. Also see ?? on how to change the way the +optional arguments are handled and ?? for reasons why you may want to +specify the punctuation as a separate argument. There are two +environments which combine `displaycquote` with the language switches of +the `babel` or the `polyglossia` package: +]] + }, + displayquote = { + arguments = { + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true} + }, + details = [[ +```latex +\begin{displayquote}[cite][punct] ... \end{displayquote} +``` + +The optional arguments `cite` and `punct` specify the citation and any +terminal punctuation of the quotation. See ?? on how to customize this +environment. Also see ?? on how to change the way the optional arguments +are handled and ?? for reasons why you may want to specify the +punctuation as a separate argument. Trailing white space at the end of +the environment is removed automatically. There are two additional +environments which combine `displayquote` with the language switches of +the `babel` or the `polyglossia` package: +]] + }, + hyphendisplaycquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {meta = "key"}, + {delimiters = {"[", "]"}, meta = "punct", optional = true} + }, + details = [[ +```latex +\begin{hyphendisplaycquote}{lang}[prenote][postnote]{key}[punct] ... \end{hyphendisplaycquote} +``` + +This environment combines `displaycquote` with `hyphenrules`. Apart from +the language, the arguments are handled as with `displaycquote`. +]] + }, + hyphendisplayquote = { + arguments = { + {meta = "lang"}, + {delimiters = {"[", "]"}, meta = "cite", optional = true}, + {delimiters = {"[", "]"}, meta = "punct", optional = true} + }, + details = [[ +```latex +\begin{hyphendisplayquote}{lang}[cite][punct] ... \end{hyphendisplayquote} +``` + +This environment combines `displayquote` with `hyphenrules`. Apart from +the language, the arguments are handled as with `displayquote`. +]] + } +} diff --git a/support/digestif/data/etoolbox.sty.tags b/support/digestif/data/etoolbox.sty.tags new file mode 100644 index 0000000000..7e9f06556f --- /dev/null +++ b/support/digestif/data/etoolbox.sty.tags @@ -0,0 +1,1285 @@ +-- Copyright 2007-2011 Philipp Lehman +-- Copyright 2015-2020 Joseph Wright +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c+ +-- +-- Adapted form the etoolbox package documentation, which can be found +-- at https://ctan.org/pkg/etoolbox. +ctan_package = "etoolbox" +dependencies = {"etex.sty"} +commands = { + AfterEndPreamble = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AfterEndPreamble{code} +``` + +This hook differs from `\AtBeginDocument` in that the `code` is executed +at the very end of `\begin{document}`, after any `\AtBeginDocument` +code. Note that commands whose scope has been restricted to the preamble +with `\@onlypreamble` are no longer available when this hook is +executed. +]] + }, + AfterPreamble = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\AfterPreamble{code} +``` + +This hook is a variant of `\AtBeginDocument` which may be used in both +the preamble and the document body. When used in the preamble, it +behaves exactely like `\AtBeginDocument`. When used in the document +body, it immediately executes its `code` argument. `\AtBeginDocument` +would issue an error in this case. This hook is useful to defer code +which needs to write to the main `aux` file. +]] + }, + AtBeginEnvironment = { + arguments = {{meta = "environment"}, {meta = "code"}}, + details = [[ +```latex +\AtBeginEnvironment{environment}{code} +``` + +Appends arbitrary `code` to a hook executed by the `\begin` command at +the beginning of a given `environment`, immediately before +`\environment`, inside the group opened by `\begin`. +]] + }, + BeforeBeginEnvironment = { + arguments = {{meta = "environment"}, {meta = "code"}}, + details = [[ +```latex +\BeforeBeginEnvironment{environment}{code} +``` + +Appends arbitrary `code` to a hook executed at a very early point by the +`\begin` command, before the group holding the environment is opened. +]] + }, + DeclareListParser = { + arguments = {{meta = "command"}, {meta = "separator"}}, + details = [[ +```latex +\DeclareListParser{command}{separator} +``` + +This command defines a list parser similar to the `\docsvlist` command +below, which is defined like this: + + \DeclareListParser{\docsvlist}{,} + +Note that the list parsers are sensitive to the category code of the +`separator`. +]] + }, + appto = { + details = [[ +```latex +\appto{code} +``` + +This command appends arbitrary `code` to a `hook`. If the `code` +contains any parameter characters, they need not be doubled. This +command is robust. +]] + }, + booltrue = { + arguments = {{meta = "name"}}, + details = [[ +```latex +\booltrue{name} +``` + +Sets the boolean flag `name` to `true`. This command is robust and may +be prefixed with `\global`. It will issue an error if the flag is +undefined. +]] + }, + csappto = { + arguments = {{meta = "csname"}, {meta = "code"}}, + details = [[ +```latex +\csappto{csname}{code} +``` + +Similar to `\appto` except that it takes a control sequence name as its +first argument. +]] + }, + csdef = { + arguments = {{meta = "csname"}}, + details = [[ +```latex +\csdef{csname}{replacement text} +``` + +Similar to the TeX primitive `\def` except that it takes a control +sequence name as its first argument. This command is robust and +corresponds to `\@namedef`. +]] + }, + csdimdef = { + arguments = {{meta = "csname"}, {meta = "dimen expression"}}, + details = [[ +```latex +\csdimdef{csname}{dimen expression} +``` + +Similar to `\dimdef` except that it takes a control sequence name as its +first argument. +]] + }, + cseappto = { + arguments = {{meta = "csname"}, {meta = "code"}}, + details = [[ +```latex +\cseappto{csname}{code} +``` + +Similar to `\eappto` except that it takes a control sequence name as its +first argument. +]] + }, + csedef = { + arguments = {{meta = "csname"}}, + details = [[ +```latex +\csedef{csname}{replacement text} +``` + +Similar to the TeX primitive `\edef` except that it takes a control +sequence name as its first argument. This command is robust. +]] + }, + csepreto = { + arguments = {{meta = "csname"}, {meta = "code"}}, + details = [[ +```latex +\csepreto{csname}{code} +``` + +Similar to `\epreto` except that it takes a control sequence name as its +first argument. +]] + }, + csgluedef = { + arguments = {{meta = "csname"}, {meta = "glue expression"}}, + details = [[ +```latex +\csgluedef{csname}{glue expression} +``` + +Similar to `\gluedef` except that it takes a control sequence name as +its first argument. +]] + }, + cslet = { + arguments = {{meta = "csname"}, {meta = "command"}}, + details = [[ +```latex +\cslet{csname}{command} +``` + +Similar to the TeX primitive `\let` except that the first argument is a +control sequence name. If `command` is undefined, `csname` will be +undefined as well after the assignment. This command is robust and may +be prefixed with `\global`. +]] + }, + csletcs = { + arguments = {{meta = "csname"}, {meta = "csname"}}, + details = [[ +```latex +\csletcs{csname}{csname} +``` + +Similar to the TeX primitive `\let` except that both arguments are +control sequence names. If the second `csname` is undefined, the first +`csname` will be undefined as well after the assignment. This command is +robust and may be prefixed with `\global`. +]] + }, + csmeaning = { + arguments = {{meta = "csname"}}, + details = [[ +```latex +\csmeaning{csname} +``` + +Similar to the TeX primitive `\meaning` but takes a control sequence +name as its argument. If the control sequence is undefined, this command +will not implicitly assign a meaning of `\relax` to it. +]] + }, + csmudef = { + arguments = {{meta = "csname"}, {meta = "muglue expression"}}, + details = [[ +```latex +\csmudef{csname}{muglue expression} +``` + +Similar to `\mudef` except that it takes a control sequence name as its +first argument. +]] + }, + csnumdef = { + arguments = {{meta = "csname"}, {meta = "integer expression"}}, + details = [[ +```latex +\csnumdef{csname}{integer expression} +``` + +Similar to `\numdef` except that it takes a control sequence name as its +first argument. +]] + }, + cspreto = { + arguments = {{meta = "csname"}, {meta = "code"}}, + details = [[ +```latex +\cspreto{csname}{code} +``` + +Similar to `\preto` except that it takes a control sequence name as its +first argument. +]] + }, + csundef = { + arguments = {{meta = "csname"}}, + details = [[ +```latex +\csundef{csname} +``` + +Similar to `\undef` except that it takes a control sequence name as its +argument. This command is robust and may be prefixed with `\global`. +]] + }, + defcounter = { + arguments = {{meta = "counter"}, {meta = "integer expression"}}, + details = [[ +```latex +\defcounter{counter}{integer expression} +``` + +Assigns a value to a LaTeX `counter` previously initialized with +`\newcounter`. This command is similar in concept and syntax to +`\setcounter` except for two major differences. 1) The second argument +may be an `integer expression` which will be processed with `\numexpr`. +The `integer expression` may be any arbitrary code which is valid in +this context. The value assigned to the `counter` will be the result of +that calculation. 2) In contrast to `\setcounter`, the assignment is +local by default but `\defcounter` may be prefixed with `\global`. The +functional equivalent of `\setcounter` would be `\global``\defcounter`. +]] + }, + dimdef = { + details = [[ +```latex +\dimdef{dimen expression} +``` + +Similar to `\edef` except that the `dimen expression` is processed with +`\dimexpr`. The `dimen expression` may be any arbitrary code which is +valid in this context. The replacement text assigned to the `command` +will be the result of that calculation. If the `command` is undefined, +it will be initialized to `0pt` before the `dimen expression` is +processed. +]] + }, + docsvlist = { + arguments = {{meta = "item, item, ..."}}, + details = [[ +```latex +\docsvlist{item, item, ...} +``` + +This command loops over a comma-separated list of items and executes the +auxiliary command `\do` for every item in the list, passing the item as +an argument. In contrast to the `\@for` loop in the LaTeX kernel, +`\docsvlist` is expandable. With a suitable definition of `\do`, lists +may be processed in an `\edef` or a comparable context. You may use +`\listbreak` at the end of the replacement text of `\do` to stop +processing and discard the remaining items in the list. Whitespace after +list separators is ignored. If an item contains a comma or starts with a +space, it must be wrapped in curly braces. The braces will be removed as +the list is processed. Here is a usage example which prints a +comma-separated list as an `itemize` environment: + + \begin{itemize} + \renewcommand*{\do}[1]{\item #1} + \docsvlist{item1, item2, {item3a, item3b}, item4} + \end{itemize} + +Here is another example: + + \renewcommand*{\do}[1]{* #1\MessageBreak} + \PackageInfo{mypackage}{% + Example list:\MessageBreak + \docsvlist{item1, item2, {item3a, item3b}, item4}} + +In this example, the list is written to the log file as part of an +informational message. The list processing takes place during the +`\write` operation. +]] + }, + dolistloop = { + arguments = {{meta = "listmacro"}}, + details = [[ +```latex +\dolistloop{listmacro} +``` + +This command loops over all items in a `listmacro` and executes the +auxiliary command `\do` for every item in the list, passing the item as +an argument. The list loop itself is expandable. You may use +`\listbreak` at the end of the replacement text of `\do` to stop +processing and discard the remaining items in the list. Here is a usage +example which prints an internal list called `\mylist` as an `itemize` +environment: + + \begin{itemize} + \renewcommand*{\do}[1]{\item #1} + \dolistloop{\mylist} + \end{itemize} +]] + }, + eappto = { + details = [[ +```latex +\eappto{code} +``` + +This command appends arbitrary `code` to a `hook`. The `code` is +expanded at definition-time. Only the new `code` is expanded, the +current replacement text of the `hook` is not. This command is robust. +]] + }, + epreto = { + details = [[ +```latex +\epreto{code} +``` + +Similar to `\eappto` except that the `code` is prepended. +]] + }, + expandonce = { + details = [[ +```latex +\expandonce +``` + +This command expands a `command` once and prevents further expansion of +the replacement text. This command is expandable. +]] + }, + forlistloop = { + arguments = {{meta = "handler"}, {meta = "listmacro"}}, + details = [[ +```latex +\forlistloop{handler}{listmacro} +``` + +This command is similar to `\dolistloop` except that `\do` is replaced +by a `handler` specified at invocation time. The `handler` may also be a +sequence of commands, provided that the command given last takes the +item as trailing argument. For example, the following code will prefix +all items in the internal list `\mylist` with `\item`, count the items +as the list is processed, and append the item count at the end: + + \newcounter{itemcount} + \begin{itemize} + \forlistloop{\stepcounter{itemcount}\item}{\mylist} + \item Total: \number\value{itemcount} items + \end{itemize} +]] + }, + gluedef = { + details = [[ +```latex +\gluedef{glue expression} +``` + +Similar to `\edef` except that the `glue expression` is processed with +`\glueexpr`. The `glue expression` may be any arbitrary code which is +valid in this context. The replacement text assigned to the `command` +will be the result of that calculation. If the `command` is undefined, +it will be initialized to `0pt plus 0pt minus 0pt` before the +`glue expression` is processed. +]] + }, + ifblank = { + arguments = {{meta = "string"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifblank{string}{true}{false} +``` + +Expands to `true` if the `string` is blank (empty or spaces), and to +`false` otherwise. The `string` is not expanded in the test. +]] + }, + ifboolexpr = { + arguments = {{meta = "expression"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifboolexpr{expression}{true}{false} +``` + +Evaluates the `expression` and executes `true` if it is true, and +`false` otherwise. The `expression` is evaluated sequentially from left +to right. The following elements, discussed in more detail below, are +available in the `expression`: the test operators `togl`, `bool`, +`test`; the logical operators `not`, `and`, `or`; and the subexpression +delimiter `(...)`. Spaces, tabs, and line endings may be used freely to +arrange the `expression` visually. Blank lines are not permissible in +the `expression`. This command is robust. +]] + }, + ifcsdimen = { + arguments = {{meta = "csname"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifcsdimen{csname}{true}{false} +``` + +Similar to `\ifdefdimen` except that it takes a control sequence name as +its first argument. +]] + }, + ifcslength = { + arguments = {{meta = "csname"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifcslength{csname}{true}{false} +``` + +Similar to `\ifdeflength` except that it takes a control sequence name +as its first argument. +]] + }, + ifdef = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdef{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined, and to `false` +otherwise. Note that control sequences will be considered as defined +even if their meaning is `\relax`. This command is a LaTeX wrapper for +the e-TeX primitive `\ifdefined`. +]] + }, + ifdefcounter = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefcounter{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is a TeX `\count` register +allocated with `\newcount`, and to `false` otherwise. +]] + }, + ifdefempty = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefempty{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined and is a +parameterless macro whose replacement text is empty, and to `false` +otherwise. In contrast to `\ifx`, this test ignores the prefixes of the +`command`. +]] + }, + ifdefequal = { + arguments = { + {meta = "control sequence"}, + {meta = "control sequence"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdefequal{control sequence}{control sequence}{true}{false} +``` + +Compares two control sequences and expands to `true` if they are equal +in the sense of `\ifx`, and to `false` otherwise. In contrast to `\ifx`, +this test will also yield `false` if both control sequences are +undefined or have a meaning of `\relax`. +]] + }, + ifdefltxprotect = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefltxprotect{control sequence}{true}{false} +``` + +Executes `true` if the `control sequence` is defined and is a LaTeX +protection shell, and `false` otherwise. This command is robust. It will +detect commands which have been defined with `\DeclareRobustCommand` or +by way of a similar technique. +]] + }, + ifdefmacro = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefmacro{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined and is a macro, +and to `false` otherwise. +]] + }, + ifdefparam = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefparam{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined and is a macro +with one or more parameters, and to `false` otherwise. +]] + }, + ifdefprefix = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefprefix{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined and is a macro +prefixed with `\long` and/or `\protected`, and to `false` otherwise. +Note that `\outer` macros may not be tested. +]] + }, + ifdefprotected = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefprotected{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is defined and is a macro +prefixed with `\protected`, and to `false` otherwise. +]] + }, + ifdefstrequal = { + arguments = { + {meta = "command"}, + {meta = "command"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdefstrequal{command}{command}{true}{false} +``` + +Performs a category code agnostic string comparison of the replacement +text of two commands. This command is similar to `\ifdefstring` except +that both arguments to be compared are macros. This command is robust. +]] + }, + ifdefstring = { + arguments = { + {meta = "command"}, + {meta = "string"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdefstring{command}{string}{true}{false} +``` + +Compares the replacement text of a `command` to a `string` and executes +`true` if they are equal, and `false` otherwise. Neither the `command` +nor the `string` is expanded in the test and the comparison is category +code agnostic. Control sequence tokens in the `string` argument will be +detokenized and treated as strings. This command is robust. Note that it +will only consider the replacement text of the `command`. For example, +this test + + \long\edef\mymacro#1#2{\string&} + \ifdefstring{\mymacro}{&}{true}{false} + +would yield `true`. The prefix and the parameters of `\mymacro` as well +as the category codes in the replacement text are ignored. +]] + }, + ifdefvoid = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifdefvoid{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is undefined, or is a +control sequence whose meaning is `\relax`, or is a parameterless macro +whose replacement text is empty, and to `false` otherwise. +]] + }, + ifdimequal = { + arguments = { + {meta = "dimen expression"}, + {meta = "dimen expression"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdimequal{dimen expression}{dimen expression}{true}{false} +``` + +Alternative syntax for `\ifdimcomp{...}{=}{...}{...}{...}`. +]] + }, + ifdimless = { + arguments = { + {meta = "dimen expression"}, + {meta = "dimen expression"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifdimless{dimen expression}{dimen expression}{true}{false} +``` + +Alternative syntax for `\ifdimcomp{...}{<}{...}{...}{...}`. +]] + }, + ifinlist = { + arguments = { + {meta = "item"}, + {meta = "listmacro"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifinlist{item}{listmacro}{true}{false} +``` + +This command executes `true` if the `item` is included in a `listmacro`, +and `false` otherwise. Note that this test uses pattern matching based +on TeX 's argument scanner to check if the search string is included in +the list. This means that it is usually faster than looping over all +items in the list, but it also implies that the items must not include +curly braces which would effectively hide them from the scanner. In +other words, this macro is most useful when dealing with lists of plain +strings rather than printable data. When dealing with printable text, it +is safer to use `\dolistloop` to check if an item is in the list as +follows: + + \renewcommand*{\do}[1]{% + \ifstrequal{#1}{<>} + {item found!\listbreak} + {}} + \dolistloop{\mylist} +]] + }, + ifinlistcs = { + arguments = { + {meta = "item"}, + {meta = "listcsname"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifinlistcs{item}{listcsname}{true}{false} +``` + +Similar to `\ifinlist` except that it takes a control sequence name as +its second argument. +]] + }, + ifltxcounter = { + arguments = {{meta = "name"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifltxcounter{name}{true}{false} +``` + +Expands to `true` if `name` is a LaTeX counter allocated with +`\newcounter`, and to `false` otherwise. +]] + }, + ifnumcomp = { + arguments = { + {meta = "integer expression"}, + {meta = "relation"}, + {meta = "integer expression"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifnumcomp{integer expression}{relation}{integer expression}{true}{false} +``` + +Compares two integer expressions according to `relation` and expands to +`true` or `false` depending on the result. The `relation` may be `<`, +`>`, or `=`. Both integer expressions will be processed with `\numexpr`. +An `integer expression` may be any arbitrary code which is valid in this +context. All arithmetic expressions may contain spaces. Here are some +examples: + + \ifnumcomp{<<3>>}{<<>>>}{<<6>>}{true}{<>} + \ifnumcomp{<<(7 + 5) / 2>>}{<<=>>}{<<6>>}{<>}{false} + \ifnumcomp{<<(7+5) / 4>>}{<<>>>}{<<3*(12-10)>>}{true}{<>} + \newcounter{countA} + \setcounter{countA}{<<6>>} + \newcounter{countB} + \setcounter{countB}{<<5>>} + \ifnumcomp{<<\value{countA} * \value{countB}/2}>>{<<=>>}{<<15>>}{<>}{false} + \ifnumcomp{<<6/2>>}{<<=>>}{<<5/2>>}{<>}{false} + +Technically, this command is a LaTeX wrapper for the TeX primitive +`\ifnum`, incorporating `\numexpr`. Note that `\numexpr` will round the +result of all integer expressions, i.e. both expressions will be +processed and rounded prior to being compared. In the last line of the +above examples, the result of the second expression is 2.5, which is +rounded to 3, hence `\ifnumcomp` will expand to `true`. +]] + }, + ifnumgreater = { + arguments = { + {meta = "integer expression"}, + {meta = "integer expression"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifnumgreater{integer expression}{integer expression}{true}{false} +``` + +Alternative syntax for `\ifnumcomp{...}{>}{...}{...}{...}`. +]] + }, + ifnumodd = { + arguments = {{meta = "integer expression"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifnumodd{integer expression}{true}{false} +``` + +Evaluates an integer expression and expands to `true` if the result is +an odd number, and to `false` otherwise. Technically, this command is a +LaTeX wrapper for the TeX primitive `\ifodd`, incorporating `\numexpr`. +]] + }, + ifpatchable = { + arguments = { + {literal = "*", optional = true}, + {meta = "command"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifpatchable*{command}{true}{false} +``` + +Similar to `\ifpatchable` except that the starred variant does not +require a search pattern. Use this version to check if a command may be +patched with `\apptocmd` and `\pretocmd`. +]] + }, + ifstrequal = { + arguments = { + {meta = "string"}, + {meta = "string"}, + {meta = "true"}, + {meta = "false"} + }, + details = [[ +```latex +\ifstrequal{string}{string}{true}{false} +``` + +Compares two strings and executes `true` if they are equal, and `false` +otherwise. The strings are not expanded in the test and the comparison +is category code agnostic. Control sequence tokens in any of the +`string` arguments will be detokenized and treated as strings. This +command is robust. +]] + }, + ifundef = { + arguments = {{meta = "control sequence"}, {meta = "true"}, {meta = "false"}}, + details = [[ +```latex +\ifundef{control sequence}{true}{false} +``` + +Expands to `true` if the `control sequence` is undefined, and to `false` +otherwise. Apart from reversing the logic of the test, this command also +differs from `\ifdef` in that commands will be considered as undefined +if their meaning is `\relax`. +]] + }, + listadd = { + arguments = {{meta = "listmacro"}, {meta = "item"}}, + details = [[ +```latex +\listadd{listmacro}{item} +``` + +This command appends an `item` to a `listmacro`. A blank `item` is not +added to the list. +]] + }, + listcsadd = { + arguments = {{meta = "listcsname"}, {meta = "item"}}, + details = [[ +```latex +\listcsadd{listcsname}{item} +``` + +Similar to `\listadd` except that it takes a control sequence name as +its first argument. +]] + }, + listcseadd = { + arguments = {{meta = "listcsname"}, {meta = "item"}}, + details = [[ +```latex +\listcseadd{listcsname}{item} +``` + +Similar to `\listeadd` except that it takes a control sequence name as +its first argument. +]] + }, + listcsremove = { + arguments = {{meta = "listcsname"}, {meta = "item"}}, + details = [[ +```latex +\listcsremove{listcsname}{item} +``` + +Similar to `\listremove` except that it takes a control sequence name as +its first argument. +]] + }, + listeadd = { + arguments = {{meta = "listmacro"}, {meta = "item"}}, + details = [[ +```latex +\listeadd{listmacro}{item} +``` + +Similar to `\listadd` except that the `item` is expanded at +definition-time. Only the new `item` is expanded, the `listmacro` is +not. If the expanded `item` is blank, it is not added to the list. +]] + }, + listremove = { + arguments = {{meta = "listmacro"}, {meta = "item"}}, + details = [[ +```latex +\listremove{listmacro}{item} +``` + +This command removes an `item` from a `listmacro`. A blank `item` is +ignored. +]] + }, + mudef = { + details = [[ +```latex +\mudef{muglue expression} +``` + +Similar to `\edef` except that the `muglue expression` is processed with +`\muexpr`. The `muglue expression` may be any arbitrary code which is +valid in this context. The replacement text assigned to the `command` +will be the result of that calculation. If the `command` is undefined, +it will be initialized to `0mu` before the `muglue expression` is +processed. +]] + }, + newbool = { + arguments = {{meta = "name"}}, + details = [[ +```latex +\newbool{name} +``` + +Defines a new boolean flag called `name`. If the flag has already been +defined, this command issues an error. The initial state of newly +defined flags is `false`. This command is robust. +]] + }, + newrobustcmd = { + arguments = { + {literal = "*", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + { + delimiters = {"[", "]"}, + meta = "optarg default", + optional = true + }, + {meta = "replacement text"} + }, + details = [[ +```latex +\newrobustcmd{command}[arguments][optarg default]{replacement text} +\newrobustcmd*{command}[arguments][optarg default]{replacement text} +``` + +The syntax and behavior of this command is similar to `\newcommand` +except that the newly defined `command` will be robust. The behavior of +this command differs from the `\DeclareRobustCommand` command from the +LaTeX kernel in that it issues an error rather than just an +informational message if the `command` is already defined. Since it uses +e-TeX 's low-level protection mechanism rather than the corresponding +higher-level LaTeX facilities, it does not require an additional macro +to implement the <robustness>. +]] + }, + newtoggle = { + arguments = {{meta = "name"}}, + details = [[ +```latex +\newtoggle{name} +``` + +Defines a new boolean flag called `name`. If the flag has already been +defined, this command issues an error. The initial state of newly +defined flags is `false`. This command is robust. +]] + }, + notbool = { + arguments = {{meta = "name"}, {meta = "not true"}, {meta = "not false"}}, + details = [[ +```latex +\notbool{name}{not true}{not false} +``` + +Similar to `\ifbool` but negates the test. +]] + }, + nottoggle = { + arguments = {{meta = "name"}, {meta = "not true"}, {meta = "not false"}}, + details = [[ +```latex +\nottoggle{name}{not true}{not false} +``` + +Similar to `\iftoggle` but negates the test. +]] + }, + numdef = { + details = [[ +```latex +\numdef{integer expression} +``` + +Similar to `\edef` except that the `integer expression` is processed +with `\numexpr`. The `integer expression` may be any arbitrary code +which is valid in this context. The replacement text assigned to the +`command` will be the result of that calculation. If the `command` is +undefined, it will be initialized to `0` before the `integer expression` +is processed. +]] + }, + patchcmd = { + arguments = { + {delimiters = {"[", "]"}, meta = "prefix", optional = true}, + {meta = "command"}, + {meta = "search"}, + {meta = "replace"}, + {meta = "success"}, + {meta = "failure"} + }, + details = [[ +```latex +\patchcmd[prefix]{command}{search}{replace}{success}{failure} +``` + +This command extracts the replacement text of a `command`, replaces +`search` with `replace`, and reassembles the `command`. The pattern +match is category code agnostic and matches the first occurence of the +`search` pattern in the replacement text of the `command` to be patched. +Note that the patching process involves detokenizing the replacement +text of the `command` and retokenizing it under the current category +code regime after patching. The category code of the @ sign is +temporarily set to 11. If the replacement text of the `command` includes +any tokens with non-standard category codes, the respective category +codes must be adjusted prior to patching. If the code to be replaced or +inserted refers to the parameters of the `command` to be patched, the +parameter characters need not be doubled. If an optional `prefix` is +specified, it replaces the prefixes of the `command`. An empty `prefix` +argument strips all prefixes from the `command`. The assignment is +local. This command implicitly performs the equivalent of an +`\ifpatchable` test prior to patching. If this test succeeds, the +command applies the patch and executes `success`. If the test fails, it +executes `failure` without modifying the original `command`. This +command is robust. +]] + }, + preto = { + details = [[ +```latex +\preto{code} +``` + +Similar to `\appto` except that the `code` is prepended. +]] + }, + pretocmd = { + arguments = { + {meta = "command"}, + {meta = "code"}, + {meta = "success"}, + {meta = "failure"} + }, + details = [=[ +```latex +\pretocmd{command}{code}{success}{failure} +``` + +This command is similar to `\apptocmd` except that the `code` is +inserted at the beginning of the replacement text of the `command`. If +the `command` is a parameterless macro, it behaves like `\preto` from +section [\[aut:hok:app\]][1]. In contrast to `\preto`, `\pretocmd` may +also be used to patch commands with parameters. In this case, it will +detokenize the replacement text of the `command`, apply the patch, and +retokenize it under the current category code regime. The category code +of the @ sign is temporarily set to 11. The `code` may refer to the +parameters of the `command`. The assignment is local. If patching +succeeds, this command executes `success`. If patching fails, it +executes `failure` without modifying the original `command`. This +command is robust. + + [1]: #aut:hok:app +]=] + }, + ["protected@cseappto"] = { + details = [[ +```latex +\protected@cseappto{code} +``` + +Similar to `\protected@eappto` except that it takes a control sequence +name as its first argument. +]] + }, + ["protected@csedef"] = { + arguments = {{meta = "csname"}}, + details = [[ +```latex +\protected@csedef{csname}{replacement text} +``` + +Similar to `\csedef` except that LaTeX 's protection mechanism is +temporarily enabled. To put it in other words: this command is similar +to the LaTeX kernel command `\protected@edef` except that it takes a +control sequence name as its first argument. This command is robust. +]] + }, + ["protected@csepreto"] = { + details = [[ +```latex +\protected@csepreto{code} +``` + +Similar to `\protected@epreto` except that it takes a control sequence +name as its first argument. +]] + }, + ["protected@eappto"] = { + details = [[ +```latex +\protected@eappto{code} +``` + +Similar to `\eappto` except that LaTeX 's protection mechanism is +temporarily enabled. +]] + }, + ["protected@epreto"] = { + details = [[ +```latex +\protected@epreto{code} +``` + +Similar to `\epreto` except that LaTeX 's protection mechanism is +temporarily enabled. +]] + }, + protecting = { + arguments = {{meta = "code"}}, + details = [[ +```latex +\protecting{code} +``` + +This command applies LaTeX 's protection mechanism, which normally +requires prefixing each fragile command with `\protect`, to an entire +chunk of arbitrary `code`. Its behavior depends on the current state of +`\protect`. Note that the braces around the `code` are mandatory even if +it is a single token. +]] + }, + providerobustcmd = { + arguments = { + {literal = "*", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + { + delimiters = {"[", "]"}, + meta = "optarg default", + optional = true + }, + {meta = "replacement text"} + }, + details = [[ +```latex +\providerobustcmd*{command}[arguments][optarg default]{replacement text} +``` + +The syntax and behavior of this command is similar to `\providecommand` +except that the newly defined `command` will be robust. Note that this +command will provide a robust definition of the `command` only if it is +undefined. It will not make an already defined `command` robust. +]] + }, + renewrobustcmd = { + arguments = { + {literal = "*", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "arguments", optional = true}, + { + delimiters = {"[", "]"}, + meta = "optarg default", + optional = true + }, + {meta = "replacement text"} + }, + details = [[ +```latex +\renewrobustcmd*{command}[arguments][optarg default]{replacement text} +``` + +The syntax and behavior of this command is similar to `\renewcommand` +except that the redefined `command` will be robust. +]] + }, + rmntonum = { + arguments = {{meta = "numeral"}}, + details = [[ +```latex +\rmntonum{numeral} +``` + +The TeX primitive `\romannumeral` converts an integer to a Roman numeral +but TeX or LaTeX provide no command which goes the opposite way. +`\rmntonum` fills this gap. It takes a Roman numeral as its argument and +converts it to the corresponding integer. Since it is expandable, it may +also be used in counter assignments or arithmetic tests: + + <<\rmntonum>>{<>} + \setcounter{counter}{<<\rmntonum>>{<>}} + \ifnumless{<<\rmntonum>>{<>}}{2000}{true}{false} + +The `numeral` argument must be a literal string. It will be detokenized +prior to parsing. The parsing of the numeral is case-insensitive and +whitespace in the argument is ignored. If there is an invalid token in +the argument, `\rmntonum` will expand to `-1`; an empty argument will +yield an empty string. Note that `\rmntonum` will not check the numeral +for formal validity. For example, both `V` and `VX` would yield `5`, +`IC` would yield `99`, etc. +]] + }, + robustify = { + arguments = {{meta = "command"}}, + details = [[ +```latex +\robustify{command} +``` + +Redefines a `command` defined with `\newcommand` such that it is robust, +without altering its parameters, its prefixes, or its replacement text. +If the `command` has been defined with `\DeclareRobustCommand`, this +will be detected automatically and LaTeX 's high-level protection +mechanism will be replaced by the corresponding low-level e-TeX feature. +]] + }, + setbool = { + arguments = {{meta = "name"}, {meta = "value"}}, + details = [[ +```latex +\setbool{name}{value} +``` + +Sets the boolean flag `name` to `value` which may be either `true` or +`false`. This command is robust and may be prefixed with `\global`. It +will issue an error if the flag is undefined. +]] + }, + settoggle = { + arguments = {{meta = "name"}, {meta = "value"}}, + details = [[ +```latex +\settoggle{name}{value} +``` + +Sets the boolean flag `name` to `value` which may be either `true` or +`false`. This command is robust and may be prefixed with `\global`. It +will issue an error if the flag is undefined. +]] + }, + toggletrue = { + arguments = {{meta = "name"}}, + details = [[ +```latex +\toggletrue{name} +``` + +Sets the boolean flag `name` to `true`. This command is robust and may +be prefixed with `\global`. It will issue an error if the flag is +undefined. +]] + }, + undef = { + details = [[ +```latex +\undef +``` + +Clears a `command` such that e-TeX 's `\ifdefined` and `\ifcsname` tests +will consider it as undefined. This command is robust and may be +prefixed with `\global`. +]] + }, + whileboolexpr = { + arguments = {{meta = "expression"}, {meta = "code"}}, + details = [[ +```latex +\whileboolexpr{expression}{code} +``` + +Evaluates the `expression` like `\ifboolexpr` and repeatedly executes +the `code` while the expression is true. The `code` may be any valid TeX +or LaTeX code. This command is robust. +]] + } +} diff --git a/support/digestif/data/hyperref.sty.tags b/support/digestif/data/hyperref.sty.tags new file mode 100644 index 0000000000..937767676a --- /dev/null +++ b/support/digestif/data/hyperref.sty.tags @@ -0,0 +1,45 @@ +ctan_package = "hyperref" +commands = { + autopageref = "$ref:hyperref.sty#/commands/pageref", + autoref = "$ref:hyperref.sty#/commands/ref", + href = { + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "URL"}, + {meta = "text"} + }, + summary = "Create a hyperlink." + }, + nolinkurl = { + arguments = {{meta = "URL"}}, + summary = "Typeset an URL like `\\url`, but without a hyperlink." + }, + pageref = { + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create a hyperlink." + }, + {list = true, meta = "key"} + }, + documentation = "info:latex2e#\\pageref", + summary = "Refer to a page number." + }, + ref = { + action = "ref", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "Do not create a hyperlink." + }, + {list = true, meta = "key"} + }, + documentation = "info:latex2e#\\ref", + summary = "Refer to a section, figure or similar." + }, + url = {arguments = {{meta = "URL"}}, summary = "Typeset an URL."} +} diff --git a/support/digestif/data/latex-prog.tags b/support/digestif/data/latex-prog.tags new file mode 100644 index 0000000000..8b4e173078 --- /dev/null +++ b/support/digestif/data/latex-prog.tags @@ -0,0 +1,6 @@ +package = { + dependencies = { + "latex" + }, + name = "LaTeX style files" +} diff --git a/support/digestif/data/latex.tags b/support/digestif/data/latex.tags new file mode 100644 index 0000000000..7d8a3bbd53 --- /dev/null +++ b/support/digestif/data/latex.tags @@ -0,0 +1,2489 @@ +-- Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, +-- 2016, 2017, 2018, 2019, 2020, 2021, 2022 Karl Berry +-- Copyright 1988, 1994, 2007 Stephen Gilmore +-- Copyright 1994, 1995, 1996 Torsten Martinsen +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: GFDL +-- +-- Adapted from the LaTeX2e Unofficial Reference Manual, which can be +-- found at https://latexref.xyz/. +ctan_package = "latex" +dependencies = {"primitives"} +documentation = { + { + summary = "A (Not So) Short Introduction to LaTeX 2ε", + uri = "texmf:doc/latex/lshort-english/lshort.pdf" + }, + { + summary = "LaTeX 2ε for authors", + uri = "texmf:doc/latex/base/usrguide.pdf" + }, + { + summary = "LaTeX 2ε for class and package writers", + uri = "texmf:doc/latex/base/clsguide.pdf" + } +} +commands = { + [" "] = { + documentation = "info:latex2e#LaTeX command syntax", + summary = "An explicit space." + }, + ["!"] = {documentation = "info:latex2e#Spacing in math mode"}, + ["\""] = {documentation = "info:latex2e#Accents"}, + ["#"] = {documentation = "info:latex2e#Reserved characters"}, + ["$"] = {documentation = "info:latex2e#Reserved characters"}, + ["%"] = {documentation = "info:latex2e#Reserved characters"}, + ["&"] = {documentation = "info:latex2e#Reserved characters"}, + ["'"] = {documentation = "info:latex2e#tabbing"}, + ["("] = {summary = "Begin inline mathematics."}, + [")"] = {summary = "End inline mathematics."}, + ["*"] = { + documentation = "info:latex2e#\\*", + summary = "Discretionary multiplication." + }, + ["+"] = {documentation = "info:latex2e#tabbing"}, + [","] = {documentation = "info:latex2e#Spacing in math mode"}, + ["-"] = { + documentation = "info:latex2e#\\- (hyphenation)", + summary = "Insert explicit hyphenation." + }, + ["."] = {documentation = "info:latex2e#Accents"}, + ["/"] = {documentation = "info:latex2e#\\/", summary = "Italic correction."}, + [":"] = {documentation = "info:latex2e#Spacing in math mode"}, + [";"] = {documentation = "info:latex2e#Spacing in math mode"}, + ["<"] = {documentation = "info:latex2e#tabbing"}, + ["="] = {documentation = "info:latex2e#tabbing"}, + [">"] = {documentation = "info:latex2e#tabbing"}, + ["@"] = { + documentation = "info:latex2e#\\@", + summary = "Distinguish sentence-ending periods from abbreviations." + }, + ["@@beginparpenalty"] = {}, + ["@@endparpenalty"] = {}, + ["@@itempenalty"] = {}, + ["@beginparpenalty"] = {documentation = "info:latex2e#list"}, + ["@endparpenalty"] = {documentation = "info:latex2e#list"}, + ["@fnsymbol"] = {documentation = "info:latex2e#\\footnote"}, + ["@ifstar"] = { + documentation = "info:latex2e#\\@ifstar", + summary = "Define your own commands with *-variants." + }, + ["@itempenalty"] = {documentation = "info:latex2e#list"}, + ["@startsection"] = { + arguments = { + {meta = "name"}, + {meta = "level"}, + {meta = "indent"}, + {meta = "beforeskip"}, + {meta = "afterskip"}, + {meta = "style"} + }, + documentation = "info:latex2e#\\@startsection", + summary = "Layout of sectional units." + }, + AA = {documentation = "info:latex2e#Additional Latin letters"}, + AE = {documentation = "info:latex2e#Additional Latin letters"}, + Alph = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + AtBeginDocument = { + arguments = {{meta = "code"}}, + documentation = "info:latex2e#\\AtBeginDocument", + summary = "Hook for commands at the start of the document." + }, + AtBeginDvi = { + arguments = {{meta = "specials"}}, + documentation = "info:latex2e#Class and package commands" + }, + AtEndDocument = { + arguments = {{meta = "code"}}, + documentation = "info:latex2e#\\AtEndDocument", + summary = "Hook for commands at the end of the document." + }, + AtEndOfClass = { + arguments = {{meta = "code"}}, + documentation = "info:latex2e#Class and package commands" + }, + AtEndOfPackage = { + arguments = {{meta = "code"}}, + documentation = "info:latex2e#Class and package commands" + }, + Big = {arguments = {{meta = "delimiter"}}}, + Bigg = {arguments = {{meta = "delimiter"}}}, + Biggl = {arguments = {{meta = "delimiter1"}}}, + Biggm = {arguments = {{meta = "delimiter"}}}, + Biggr = {arguments = {{meta = "delimiter2"}}}, + Bigl = {arguments = {{meta = "delimiter1"}}}, + Bigm = {arguments = {{meta = "delimiter"}}}, + Box = {documentation = "info:latex2e#Math symbols"}, + CheckCommand = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "cmd"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "definition"} + }, + documentation = "info:latex2e#Class and package commands" + }, + ClassError = { + arguments = { + {meta = "class name"}, + {meta = "error text"}, + {meta = "help text"} + }, + documentation = "info:latex2e#Class and package commands" + }, + ClassInfo = { + arguments = {{meta = "class name"}, {meta = "info text"}}, + documentation = "info:latex2e#Class and package commands" + }, + ClassInfoNoLine = { + arguments = {{meta = "class name"}, {meta = "info text"}}, + documentation = "info:latex2e#Class and package commands" + }, + ClassWarning = { + arguments = {{meta = "class name"}, {meta = "warning text"}}, + documentation = "info:latex2e#Class and package commands" + }, + ClassWarningNoLine = { + arguments = {{meta = "class name"}, {meta = "warning text"}}, + documentation = "info:latex2e#Class and package commands" + }, + CurrentOption = {documentation = "info:latex2e#Class and package commands"}, + DH = {documentation = "info:latex2e#Additional Latin letters"}, + DJ = {documentation = "info:latex2e#Additional Latin letters"}, + DeclareFontEncoding = { + arguments = { + {meta = "encoding"}, + {meta = "text-settings"}, + {meta = "math-settings"} + }, + documentation = "info:latex2e#\\DeclareFontEncoding", + summary = "Define an encoding." + }, + DeclareGraphicsExtensions = { + arguments = {{meta = "comma-separated list of file extensions"}}, + documentation = "info:latex2e#\\DeclareGraphicsExtensions", + summary = "File types, such as JPG or EPS." + }, + DeclareGraphicsRule = { + arguments = { + {meta = "extension"}, + {meta = "type"}, + {meta = "size-file extension"}, + {meta = "command"} + }, + documentation = "info:latex2e#\\DeclareGraphicsRule", + summary = "How to handle file types." + }, + DeclareOption = { + action = "DeclareOption", + arguments = {{meta = "option"}, {meta = "code"}}, + documentation = "info:latex2e#Class and package commands" + }, + DeclareRobustCommand = { + action = "newcommand", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "definition"} + }, + documentation = "info:latex2e#Class and package commands" + }, + DeclareTextAccent = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "encoding"}, {meta = "slot"}}, + documentation = "info:latex2e#\\DeclareTextAccentDefault", + summary = "Define an accent in the encoding." + }, + DeclareTextAccentDefault = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "encoding"}}, + documentation = "info:latex2e#\\DeclareTextAccentDefault", + summary = "Fallback for using an accent in the encoding." + }, + DeclareTextCommand = { + action = "newcommand", + arguments = { + {meta = "command"}, + {meta = "encoding"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "code"} + }, + documentation = "info:latex2e#\\DeclareTextCommandDefault & \\ProvideTextCommandDefault", + summary = "New encoding-specific command." + }, + DeclareTextCommandDefault = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "code"}}, + documentation = "info:latex2e#\\DeclareTextCommandDefault & \\ProvideTextCommandDefault", + summary = "Fallback for encoding-specific commands." + }, + DeclareTextComposite = { + action = "newcommand", + arguments = { + {meta = "command"}, + {meta = "encoding"}, + {meta = "simple object"}, + {meta = "slot"} + }, + documentation = "info:latex2e#\\DeclareTextComposite", + summary = "Directly access an accented glyph, in the encoding." + }, + DeclareTextCompositeCommand = { + action = "newcommand", + arguments = { + {meta = "command"}, + {meta = "encoding"}, + {meta = "arg"}, + {meta = "code"} + }, + documentation = "info:latex2e#\\DeclareTextCompositeCommand", + summary = "Run code in slot, in the encoding." + }, + DeclareTextSymbol = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "encoding"}, {meta = "slot"}}, + documentation = "info:latex2e#\\DeclareTextSymbolDefault", + summary = "Define a symbol in the encoding." + }, + DeclareTextSymbolDefault = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "encoding"}}, + documentation = "info:latex2e#\\DeclareTextSymbolDefault", + summary = "Fallback for a symbol in the encoding." + }, + Delta = {documentation = "info:latex2e#Math symbols", symbol = "Δ"}, + Diamond = {documentation = "info:latex2e#Math symbols"}, + Downarrow = {documentation = "info:latex2e#Math symbols", symbol = "⇓"}, + ExecuteOptions = { + arguments = {{list = true, meta = "options"}}, + documentation = "info:latex2e#Class and package commands" + }, + Gamma = {documentation = "info:latex2e#Math symbols", symbol = "Γ"}, + Gls = {arguments = {{meta = "label"}}}, + Glspl = {arguments = {{meta = "label"}}}, + H = {documentation = "info:latex2e#Accents"}, + Huge = {documentation = "info:latex2e#Font sizes"}, + IJ = {documentation = "info:latex2e#Additional Latin letters"}, + IfFileExists = { + arguments = { + {meta = "file name"}, + {meta = "true code"}, + {meta = "false code"} + }, + documentation = "info:latex2e#Class and package commands" + }, + Im = {documentation = "info:latex2e#Math symbols", symbol = "ℑ"}, + InputIfFileExists = { + arguments = { + {meta = "file name"}, + {meta = "true code"}, + {meta = "false code"} + }, + documentation = "info:latex2e#Class and package commands" + }, + Join = {documentation = "info:latex2e#Math symbols", symbol = "⨝"}, + L = {documentation = "info:latex2e#Additional Latin letters"}, + LARGE = {documentation = "info:latex2e#Font sizes"}, + LaTeX = {documentation = "info:latex2e#Text symbols"}, + LaTeXe = {documentation = "info:latex2e#Text symbols"}, + Lambda = {documentation = "info:latex2e#Math symbols", symbol = "Λ"}, + Large = {documentation = "info:latex2e#Font sizes"}, + LastDeclaredEncoding = { + documentation = "info:latex2e#\\LastDeclaredEncoding", + summary = "Save most recently declared encoding." + }, + Leftarrow = {documentation = "info:latex2e#Math symbols", symbol = "⇐"}, + Leftrightarrow = {documentation = "info:latex2e#Math symbols", symbol = "⇔"}, + LoadClass = { + action = "input", + arguments = { + { + delimiters = {"[", "]"}, + list = true, + meta = "options", + optional = true + }, + {meta = "class name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands", + filename = "?.cls" + }, + LoadClassWithOptions = { + action = "input", + arguments = { + {meta = "class name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands", + filename = "?.cls" + }, + MakeLowercase = {arguments = {{meta = "text"}}}, + MakeUppercase = {arguments = {{meta = "text"}}}, + NEWLINE = {documentation = "info:latex2e#\\(SPACE)"}, + NG = {documentation = "info:latex2e#Additional Latin letters"}, + NeedsTeXFormat = { + arguments = { + {meta = "format"}, + {delimiters = {"[", "]"}, meta = "format date", optional = true} + }, + documentation = "info:latex2e#Class and package commands" + }, + O = {documentation = "info:latex2e#Additional Latin letters"}, + OE = {documentation = "info:latex2e#Additional Latin letters"}, + Omega = {documentation = "info:latex2e#Math symbols", symbol = "Ω"}, + OptionNotUsed = {documentation = "info:latex2e#Class and package commands"}, + P = {documentation = "info:latex2e#Text symbols"}, + PackageError = { + arguments = { + {meta = "package name"}, + {meta = "error text"}, + {meta = "help text"} + }, + documentation = "info:latex2e#Class and package commands" + }, + PackageInfo = { + arguments = {{meta = "package name"}, {meta = "info text"}}, + documentation = "info:latex2e#Class and package commands" + }, + PackageInfoNoLine = { + arguments = {{meta = "package name"}, {meta = "info text"}}, + documentation = "info:latex2e#Class and package commands" + }, + PackageWarning = { + arguments = {{meta = "package name"}, {meta = "warning text"}}, + documentation = "info:latex2e#Class and package commands" + }, + PackageWarningNoLine = { + arguments = {{meta = "package name"}, {meta = "warning text"}}, + documentation = "info:latex2e#Class and package commands" + }, + PassOptionsToClass = { + arguments = {{list = true, meta = "options"}, {meta = "class name"}}, + documentation = "info:latex2e#Class and package commands" + }, + PassOptionsToPackage = { + arguments = {{list = true, meta = "options"}, {meta = "package name"}}, + documentation = "info:latex2e#Class and package commands" + }, + Phi = {documentation = "info:latex2e#Math symbols", symbol = "Φ"}, + Pi = {documentation = "info:latex2e#Math symbols", symbol = "Π"}, + Pr = {documentation = "info:latex2e#Math functions"}, + ProcessOptions = { + arguments = {{literal = "*", meta = "star", optional = true}}, + documentation = "info:latex2e#Class and package commands" + }, + ProvideTextCommand = { + action = "newcommand", + arguments = { + {meta = "command"}, + {meta = "encoding"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "code"} + }, + documentation = "info:latex2e#\\DeclareTextCommandDefault & \\ProvideTextCommandDefault", + summary = "New encoding-specific command." + }, + ProvideTextCommandDefault = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "code"}}, + documentation = "info:latex2e#\\DeclareTextCommandDefault & \\ProvideTextCommandDefault", + summary = "Fallback for encoding-specific commands." + }, + ProvidesClass = { + arguments = { + {meta = "class name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands" + }, + ProvidesFile = { + arguments = { + {meta = "file name"}, + { + delimiters = {"[", "]"}, + meta = "additional information", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands" + }, + ProvidesPackage = { + arguments = { + {meta = "package name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands" + }, + Psi = {documentation = "info:latex2e#Math symbols", symbol = "Ψ"}, + Re = {documentation = "info:latex2e#Math symbols", symbol = "ℜ"}, + RequirePackage = { + action = "input", + arguments = { + { + delimiters = {"[", "]"}, + list = true, + meta = "options", + optional = true + }, + {list = true, meta = "package name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands", + filename = "?.sty" + }, + RequirePackageWithOptions = { + action = "input", + arguments = { + {list = true, meta = "package name"}, + { + delimiters = {"[", "]"}, + meta = "release date", + optional = true + } + }, + documentation = "info:latex2e#Class and package commands", + filename = "?.sty" + }, + Rightarrow = {documentation = "info:latex2e#Math symbols", symbol = "⇒"}, + Roman = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + S = {documentation = "info:latex2e#Text symbols"}, + SS = {documentation = "info:latex2e#Additional Latin letters"}, + Sigma = {documentation = "info:latex2e#Math symbols", symbol = "Σ"}, + TH = {documentation = "info:latex2e#Additional Latin letters"}, + TeX = {documentation = "info:latex2e#Text symbols"}, + Uparrow = {documentation = "info:latex2e#Math symbols", symbol = "⇑"}, + Updownarrow = {documentation = "info:latex2e#Math symbols", symbol = "⇕"}, + Upsilon = {documentation = "info:latex2e#Math symbols", symbol = "Υ"}, + UseTextAccent = { + arguments = {{meta = "encoding"}, {meta = "command"}, {meta = "text"}}, + documentation = "info:latex2e#\\UseTextAccent & \\UseTextSymbol", + summary = "Temporarily switch to another encoding." + }, + UseTextSymbol = { + arguments = {{meta = "encoding"}, {meta = "command"}}, + documentation = "info:latex2e#\\UseTextAccent & \\UseTextSymbol", + summary = "Temporarily switch to another encoding." + }, + Vert = {documentation = "info:latex2e#Math symbols", symbol = "‖"}, + Xi = {documentation = "info:latex2e#Math symbols", symbol = "Ξ"}, + ["\\"] = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {delimiters = {"[", "]"}, meta = "morespace", optional = true} + }, + documentation = "info:latex2e#eqnarray", + summary = "Start a new line." + }, + ["^"] = {documentation = "info:latex2e#Accents"}, + _ = {documentation = "info:latex2e#Reserved characters"}, + ["`"] = {documentation = "info:latex2e#tabbing"}, + a = {documentation = "info:latex2e#tabbing"}, + aa = {documentation = "info:latex2e#Additional Latin letters"}, + accent = { + documentation = "info:latex2e#\\accent", + summary = "Low level command to produce an accented character." + }, + acute = {documentation = "info:latex2e#Math accents", symbol = "◌́"}, + addcontentsline = { + arguments = {{meta = "ext"}, {meta = "unit"}, {meta = "text"}}, + documentation = "info:latex2e#\\addcontentsline", + summary = "Add an entry to table of contents, etc." + }, + address = { + arguments = {{meta = "sender's address"}}, + documentation = "info:latex2e#\\address", + summary = "Sender's return address." + }, + addtocontents = { + arguments = {{meta = "ext"}, {meta = "text"}}, + documentation = "info:latex2e#\\addtocontents", + summary = "Add text directly to table of contents file, etc." + }, + addtocounter = { + arguments = {{meta = "counter"}, {meta = "value"}}, + documentation = "info:latex2e#\\addtocounter", + summary = "Add a quantity to a counter." + }, + addtolength = { + arguments = {{meta = "len"}, {meta = "amount"}}, + documentation = "info:latex2e#\\addtolength", + summary = "Add a quantity to a length." + }, + addvspace = { + arguments = {{meta = "vert-length"}}, + documentation = "info:latex2e#\\addvspace", + summary = "Add arbitrary vertical space if needed." + }, + ae = {documentation = "info:latex2e#Additional Latin letters"}, + aleph = {documentation = "info:latex2e#Math symbols", symbol = "ℵ"}, + alph = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + alpha = {documentation = "info:latex2e#Math symbols", symbol = "α"}, + alsoname = {documentation = "info:latex2e#\\index"}, + amalg = {documentation = "info:latex2e#Math symbols", symbol = "⨿"}, + ["and"] = {documentation = "info:latex2e#\\maketitle"}, + angle = {documentation = "info:latex2e#Math symbols", symbol = "∠"}, + appendix = { + documentation = "info:latex2e#\\appendix", + summary = "Start appendices." + }, + approx = {documentation = "info:latex2e#Math symbols", symbol = "≈"}, + arabic = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + arccos = {documentation = "info:latex2e#Math functions"}, + arcsin = {documentation = "info:latex2e#Math functions"}, + arctan = {documentation = "info:latex2e#Math functions"}, + arg = {documentation = "info:latex2e#Math functions"}, + arraycolsep = {documentation = "info:latex2e#array"}, + arrayrulewidth = {documentation = "info:latex2e#tabular"}, + arraystretch = {documentation = "info:latex2e#tabular"}, + ast = {documentation = "info:latex2e#Math symbols", symbol = "∗"}, + asymp = {documentation = "info:latex2e#Math symbols", symbol = "≍"}, + author = { + arguments = {{meta = "names"}}, + documentation = "info:latex2e#\\maketitle" + }, + b = {documentation = "info:latex2e#Accents"}, + backmatter = { + documentation = "info:latex2e#\\frontmatter & \\mainmatter & \\backmatter", + summary = "Start backmatter of a book." + }, + backslash = {documentation = "info:latex2e#Math symbols", symbol = "\\"}, + bar = {documentation = "info:latex2e#Math accents", symbol = "◌̄"}, + baselineskip = {documentation = "info:latex2e#Low-level font commands"}, + baselinestretch = {documentation = "info:latex2e#Low-level font commands"}, + begin = { + action = "begin", + arguments = {{meta = "environment name"}}, + documentation = "info:latex2e#Environments", + snippet = "begin{${1:environment}}$0\n\\end{$1}" + }, + beta = {documentation = "info:latex2e#Math symbols", symbol = "β"}, + bf = {documentation = "info:latex2e#Font styles"}, + bfseries = {documentation = "info:latex2e#Font styles"}, + bibitem = { + action = "bibitem", + arguments = { + {delimiters = {"[", "]"}, meta = "label", optional = true}, + {meta = "cite_key"} + }, + documentation = "info:latex2e#\\bibitem", + summary = "Specify a bibliography item." + }, + bibliography = { + action = "input", + arguments = {{list = true, meta = "bibfiles"}}, + documentation = "info:latex2e#Using BibTeX", + filename = "?.bib" + }, + bibliographystyle = { + arguments = {{meta = "bibstyle"}}, + documentation = "info:latex2e#Using BibTeX" + }, + big = {arguments = {{meta = "delimiter"}}}, + bigbreak = {summary = "Inter-paragraph space and page breaks."}, + bigcap = {documentation = "info:latex2e#Math symbols", symbol = "⋂"}, + bigcirc = {documentation = "info:latex2e#Math symbols"}, + bigcup = {documentation = "info:latex2e#Math symbols", symbol = "⋃"}, + bigg = { + arguments = {{meta = "delimiter"}}, + summary = "Manually sized delimiter." + }, + biggl = { + arguments = {{meta = "delimiter1"}}, + summary = "Manually sized delimiter." + }, + biggm = { + arguments = {{meta = "delimiter"}}, + summary = "Manually sized delimiter." + }, + biggr = { + arguments = {{meta = "delimiter2"}}, + summary = "Manually sized delimiter." + }, + bigl = { + arguments = {{meta = "delimiter1"}}, + summary = "Manually sized delimiter." + }, + bigm = { + arguments = {{meta = "delimiter"}}, + summary = "Manually sized delimiter." + }, + bigodot = {documentation = "info:latex2e#Math symbols", symbol = "⨀"}, + bigoplus = {documentation = "info:latex2e#Math symbols", symbol = "⨁"}, + bigotimes = {documentation = "info:latex2e#Math symbols", symbol = "⨂"}, + bigr = { + arguments = {{meta = "delimiter2"}}, + summary = "Manually sized delimiter." + }, + bigskip = { + documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip", + summary = "Inter-paragraph vertical spaces." + }, + bigskipamount = {documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip"}, + bigsqcup = {documentation = "info:latex2e#Math symbols", symbol = "⨆"}, + bigtriangledown = {documentation = "info:latex2e#Math symbols", symbol = "▽"}, + bigtriangleup = {documentation = "info:latex2e#Math symbols", symbol = "△"}, + biguplus = {documentation = "info:latex2e#Math symbols", symbol = "⨄"}, + bigvee = {documentation = "info:latex2e#Math symbols", symbol = "⋁"}, + bigwedge = {documentation = "info:latex2e#Math symbols", symbol = "⋀"}, + bmod = {documentation = "info:latex2e#Math functions"}, + boldmath = { + documentation = "info:latex2e#\\boldmath & \\unboldmath", + summary = "Symbols in boldface." + }, + bot = {documentation = "info:latex2e#Math symbols", symbol = "⊥"}, + bottomfraction = {documentation = "info:latex2e#Floats"}, + bowtie = {documentation = "info:latex2e#Math symbols", symbol = "⋈"}, + breve = {documentation = "info:latex2e#Math accents", symbol = "◌̆"}, + bullet = {documentation = "info:latex2e#Math symbols"}, + c = {documentation = "info:latex2e#Accents"}, + cal = {documentation = "info:latex2e#Font styles"}, + cap = {documentation = "info:latex2e#Math symbols", symbol = "∩"}, + capitalacute = {documentation = "info:latex2e#Accents"}, + capitalbreve = {documentation = "info:latex2e#Accents"}, + capitalcaron = {documentation = "info:latex2e#Accents"}, + capitalcedilla = {documentation = "info:latex2e#Accents"}, + capitalcircumflex = {documentation = "info:latex2e#Accents"}, + capitaldieresis = {documentation = "info:latex2e#Accents"}, + capitaldotaccent = {documentation = "info:latex2e#Accents"}, + capitalgrave = {documentation = "info:latex2e#Accents"}, + capitalhungarumlaut = {documentation = "info:latex2e#Accents"}, + capitalmacron = {documentation = "info:latex2e#Accents"}, + capitalnewtie = {documentation = "info:latex2e#Accents"}, + capitalogonek = {documentation = "info:latex2e#Accents"}, + capitalring = {documentation = "info:latex2e#Accents"}, + capitaltie = {documentation = "info:latex2e#Accents"}, + capitaltilde = {documentation = "info:latex2e#Accents"}, + caption = { + action = "caption", + arguments = {{meta = "text"}}, + documentation = "info:latex2e#table", + summary = "Create a caption for a floating figure or table." + }, + cc = { + arguments = {{meta = "name"}}, + documentation = "info:latex2e#\\cc", + summary = "Carbon copy list." + }, + cdot = {documentation = "info:latex2e#Math symbols", symbol = "⋅"}, + cdots = {documentation = "info:latex2e#Dots"}, + centering = { + documentation = "info:latex2e#\\centering", + summary = "Declaration form of the center environment." + }, + chapter = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\chapter", + section_level = 0, + summary = "Start a chapter." + }, + check = {documentation = "info:latex2e#Math accents", symbol = "◌̌"}, + chi = {documentation = "info:latex2e#Math symbols", symbol = "χ"}, + circ = {documentation = "info:latex2e#Math symbols"}, + circle = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "diameter"} + }, + documentation = "info:latex2e#\\circle", + summary = "Draw a circle." + }, + cite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "subcite", optional = true}, + {list = true, meta = "keys"} + }, + documentation = "info:latex2e#\\cite", + summary = "Refer to a bibliography item." + }, + cleardoublepage = { + documentation = "info:latex2e#\\clearpage & \\cleardoublepage", + summary = "Start a new page; eject floats." + }, + clearpage = { + documentation = "info:latex2e#\\clearpage & \\cleardoublepage", + summary = "Start a new page; eject floats." + }, + cline = { + arguments = {{meta = "i-j"}}, + documentation = "info:latex2e#\\cline", + summary = "Draw a horizontal line spanning some columns." + }, + closein = {documentation = "info:latex2e#\\openin & \\openout"}, + closeout = {documentation = "info:latex2e#\\openin & \\openout"}, + closing = { + arguments = {{meta = "closing text"}}, + documentation = "info:latex2e#\\closing", + summary = "Saying goodbye." + }, + clubsuit = {documentation = "info:latex2e#Math symbols", symbol = "♣"}, + colon = {documentation = "info:latex2e#Colon character & \\colon"}, + color = { + arguments = { + {delimiters = {"[", "]"}, meta = "color model", optional = true}, + {meta = "specification"} + } + }, + colorbox = { + arguments = { + {delimiters = {"[", "]"}, meta = "model name", optional = true}, + {meta = "box background color"}, + {meta = "text"} + } + }, + columnsep = {documentation = "info:latex2e#Page layout parameters"}, + columnseprule = {documentation = "info:latex2e#Page layout parameters"}, + columnwidth = {documentation = "info:latex2e#Page layout parameters"}, + complement = {documentation = "info:latex2e#Math symbols", symbol = "∁"}, + cong = {documentation = "info:latex2e#Math symbols", symbol = "≅"}, + contentsline = {documentation = "info:latex2e#\\addcontentsline"}, + coprod = {documentation = "info:latex2e#Math symbols", symbol = "∐"}, + copyright = {documentation = "info:latex2e#Text symbols"}, + cos = {documentation = "info:latex2e#Math functions"}, + cosh = {documentation = "info:latex2e#Math functions"}, + cot = {documentation = "info:latex2e#Math functions"}, + coth = {documentation = "info:latex2e#Math functions"}, + csc = {documentation = "info:latex2e#Math functions"}, + cup = {documentation = "info:latex2e#Math symbols", symbol = "∪"}, + d = {documentation = "info:latex2e#Accents"}, + dag = {documentation = "info:latex2e#Text symbols"}, + dagger = {documentation = "info:latex2e#Math symbols", symbol = "†"}, + dashbox = { + arguments = { + {meta = "dash-len"}, + {delimiters = {"(", ")"}, meta = "rect-width,rect-height"}, + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\dashbox", + summary = "Draw a dashed box." + }, + dashv = {documentation = "info:latex2e#Math symbols", symbol = "⊣"}, + date = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\maketitle" + }, + day = { + documentation = "info:latex2e#\\day & \\month & \\year", + summary = "Numeric date values." + }, + dblfloatpagefraction = {documentation = "info:latex2e#\\twocolumn"}, + dblfloatsep = {documentation = "info:latex2e#\\twocolumn"}, + dbltextfloatsep = {documentation = "info:latex2e#\\twocolumn"}, + dbltopfraction = {documentation = "info:latex2e#\\twocolumn"}, + dbltopnumber = {documentation = "info:latex2e#\\twocolumn"}, + ddag = {documentation = "info:latex2e#Text symbols"}, + ddagger = {documentation = "info:latex2e#Math symbols", symbol = "‡"}, + ddot = {documentation = "info:latex2e#Math accents", symbol = "◌̈"}, + ddots = {documentation = "info:latex2e#Dots", symbol = "⋱"}, + definecolor = { + arguments = {{meta = "name"}, {meta = "model"}, {meta = "specification"}} + }, + deg = {documentation = "info:latex2e#Math functions"}, + delta = {documentation = "info:latex2e#Math symbols", symbol = "δ"}, + det = {documentation = "info:latex2e#Math functions"}, + dh = {documentation = "info:latex2e#Additional Latin letters"}, + diamond = {documentation = "info:latex2e#Math symbols"}, + diamondsuit = {documentation = "info:latex2e#Math symbols", symbol = "♢"}, + dim = {documentation = "info:latex2e#Math functions"}, + discretionary = { + arguments = {{meta = "pre-break"}, {meta = "post-break"}, {meta = "no-break"}}, + summary = "Explicit control of the hyphen character." + }, + displaystyle = {documentation = "info:latex2e#Math formulas"}, + div = {documentation = "info:latex2e#Math symbols", symbol = "÷"}, + dj = {documentation = "info:latex2e#Additional Latin letters"}, + documentclass = { + action = "input", + arguments = { + {delimiters = {"[", "]"}, meta = "options", optional = true}, + {meta = "class"} + }, + documentation = "info:latex2e#Document classes", + filename = "?.cls" + }, + dot = {documentation = "info:latex2e#Math accents", symbol = "◌̇"}, + doteq = {documentation = "info:latex2e#Math symbols", symbol = "≐"}, + dotfill = { + documentation = "info:latex2e#\\hrulefill & \\dotfill", + summary = "Stretchable horizontal dots." + }, + dots = {documentation = "info:latex2e#Text symbols"}, + doublerulesep = {documentation = "info:latex2e#tabular"}, + downarrow = {documentation = "info:latex2e#Math symbols", symbol = "↓"}, + ell = {documentation = "info:latex2e#Math symbols", symbol = "ℓ"}, + emph = {documentation = "info:latex2e#Font styles"}, + emptyset = {documentation = "info:latex2e#Math symbols"}, + encl = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\encl", + summary = "List of enclosed material." + }, + ["end"] = { + action = "end", + arguments = {{meta = "environment name"}}, + documentation = "info:latex2e#Environments" + }, + endinput = { + documentation = "info:latex2e#\\endinput", + summary = "Stop including material from a file." + }, + enlargethispage = { + documentation = "info:latex2e#\\enlargethispage", + summary = "Enlarge the current page a bit." + }, + enspace = { + documentation = "info:latex2e#\\enspace & \\quad & \\qquad", + summary = "Traditional horizontal spaces. " + }, + ensuremath = { + arguments = {{meta = "formula"}}, + summary = "Ensure that math mode is active." + }, + enumi = {documentation = "info:latex2e#enumerate"}, + enumii = {documentation = "info:latex2e#enumerate"}, + enumiii = {documentation = "info:latex2e#enumerate"}, + enumiv = {documentation = "info:latex2e#enumerate"}, + epsilon = {documentation = "info:latex2e#Math symbols", symbol = "ϵ"}, + equiv = {documentation = "info:latex2e#Math symbols", symbol = "≡"}, + eta = {documentation = "info:latex2e#Math symbols", symbol = "η"}, + evensidemargin = {documentation = "info:latex2e#Page layout parameters"}, + exists = {documentation = "info:latex2e#Math symbols", symbol = "∃"}, + exp = {documentation = "info:latex2e#Math functions"}, + extracolsep = {documentation = "info:latex2e#tabular"}, + fbox = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\fbox & \\framebox", + summary = "Put a frame around a box." + }, + fboxrule = {documentation = "info:latex2e#\\fbox & \\framebox"}, + fboxsep = {documentation = "info:latex2e#\\fbox & \\framebox"}, + fcolorbox = { + arguments = { + {delimiters = {"[", "]"}, meta = "model name", optional = true}, + {meta = "frame color"}, + {meta = "box background color"}, + {meta = "text"} + } + }, + fill = {documentation = "info:latex2e#\\hfill"}, + flat = {documentation = "info:latex2e#Math symbols", symbol = "♭"}, + floatpagefraction = {documentation = "info:latex2e#Floats"}, + floatsep = {documentation = "info:latex2e#Floats"}, + flushbottom = { + documentation = "info:latex2e#\\flushbottom", + summary = "Make all text pages the same height." + }, + fnsymbol = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + fontencoding = { + arguments = {{meta = "encoding"}}, + documentation = "info:latex2e#Low-level font commands" + }, + fontfamily = { + arguments = {{meta = "family"}}, + documentation = "info:latex2e#Low-level font commands" + }, + fontseries = { + arguments = {{meta = "series"}}, + documentation = "info:latex2e#Low-level font commands" + }, + fontshape = { + arguments = {{meta = "shape"}}, + documentation = "info:latex2e#Low-level font commands" + }, + fontsize = { + arguments = {{meta = "size"}, {meta = "skip"}}, + documentation = "info:latex2e#Low-level font commands" + }, + footnote = { + arguments = { + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\footnote", + summary = "Insert a footnote." + }, + footnotemark = { + arguments = {{delimiters = {"[", "]"}, meta = "number", optional = true}}, + documentation = "info:latex2e#\\footnotemark", + summary = "Insert footnote mark only." + }, + footnoterule = {documentation = "info:latex2e#\\footnote"}, + footnotesep = {documentation = "info:latex2e#\\footnote"}, + footnotesize = {documentation = "info:latex2e#Font sizes"}, + footnotetext = { + arguments = { + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\footnotetext", + summary = "Insert footnote text only." + }, + footskip = {documentation = "info:latex2e#Page layout parameters"}, + forall = {documentation = "info:latex2e#Math symbols", symbol = "∀"}, + frac = { + arguments = {{meta = "numerator"}, {meta = "denominator"}}, + documentation = "info:latex2e#\\frac", + summary = "Fraction." + }, + frame = { + arguments = {{meta = "contents"}}, + documentation = "info:latex2e#\\frame", + summary = "Draw a frame around an object." + }, + framebox = { + arguments = { + {delimiters = {"(", ")"}, meta = "rec-width,rec-height"}, + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\fbox & \\framebox", + summary = "Draw a box with a frame around it." + }, + frenchspacing = { + documentation = "info:latex2e#\\frenchspacing", + summary = "Equal interword and inter-sentence space." + }, + frontmatter = { + documentation = "info:latex2e#\\frontmatter & \\mainmatter & \\backmatter", + summary = "Start frontmatter of a book." + }, + frown = {documentation = "info:latex2e#Math symbols", symbol = "⌢"}, + fussy = { + documentation = "info:latex2e#\\fussy & \\sloppy", + summary = "Be more particular with line breaking." + }, + gamma = {documentation = "info:latex2e#Math symbols", symbol = "γ"}, + gcd = {documentation = "info:latex2e#Math functions"}, + ge = {documentation = "info:latex2e#Math symbols"}, + geq = {documentation = "info:latex2e#Math symbols", symbol = "≥"}, + gets = {documentation = "info:latex2e#Math symbols"}, + gg = {documentation = "info:latex2e#Math symbols", symbol = "≫"}, + gls = { + arguments = {{meta = "label"}}, + documentation = "info:latex2e#\\gls", + summary = "Give a page reference for a glossary entry." + }, + glspl = {arguments = {{meta = "label"}}}, + graphicspath = { + arguments = {{meta = "list of dir names inside curly brackets"}}, + documentation = "info:latex2e#\\graphicspath", + summary = "Directories to search." + }, + graphpaper = { + arguments = { + {delimiters = {"[", "]"}, meta = "spacing", optional = true}, + {delimiters = {"(", ")"}, meta = "x_init,y_init"}, + {delimiters = {"(", ")"}, meta = "x_dimen,y_dimen"} + }, + documentation = "info:latex2e#\\graphpaper", + summary = "Draw graph paper." + }, + grave = {documentation = "info:latex2e#Math accents", symbol = "◌̀"}, + guillemotleft = {documentation = "info:latex2e#Text symbols"}, + guillemotright = {documentation = "info:latex2e#Text symbols"}, + guilsinglleft = {documentation = "info:latex2e#Text symbols"}, + guilsinglright = {documentation = "info:latex2e#Text symbols"}, + hat = {documentation = "info:latex2e#Math accents", symbol = "◌̂"}, + hbar = {documentation = "info:latex2e#Math symbols"}, + headheight = {documentation = "info:latex2e#Page layout parameters"}, + headsep = {documentation = "info:latex2e#Page layout parameters"}, + heartsuit = {documentation = "info:latex2e#Math symbols", symbol = "♡"}, + hfill = { + documentation = "info:latex2e#\\hfill", + summary = "Stretchable horizontal space. " + }, + hline = { + documentation = "info:latex2e#\\hline", + summary = "Draw a horizontal line spanning all columns." + }, + hom = {documentation = "info:latex2e#Math functions"}, + hookleftarrow = {documentation = "info:latex2e#Math symbols", symbol = "↩"}, + hookrightarrow = {documentation = "info:latex2e#Math symbols", symbol = "↪"}, + hphantom = { + arguments = {{meta = "subformula"}}, + summary = "Make empty box with the same size as the argument." + }, + hrulefill = { + documentation = "info:latex2e#\\hrulefill & \\dotfill", + summary = "Stretchable horizontal rule." + }, + hsize = {documentation = "info:latex2e#Page layout parameters"}, + hspace = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "length"} + }, + documentation = "info:latex2e#\\hspace", + summary = "Any horizontal space. " + }, + hss = { + documentation = "info:latex2e#\\hss", + summary = "Infinitely stretchable/shrinkable horizontal space." + }, + huge = {documentation = "info:latex2e#Font sizes"}, + hyphenation = { + arguments = {{meta = "words"}}, + documentation = "info:latex2e#\\hyphenation", + summary = "Tell LaTeX how to hyphenate a word." + }, + i = {documentation = "info:latex2e#Accents"}, + iff = {documentation = "info:latex2e#Math symbols"}, + ignorespaces = { + documentation = "info:latex2e#\\ignorespaces & \\ignorespacesafterend", + summary = "Discard extra spaces." + }, + ignorespacesafterend = { + documentation = "info:latex2e#\\ignorespaces & \\ignorespacesafterend", + summary = "Discard extra spaces." + }, + ij = {documentation = "info:latex2e#Additional Latin letters"}, + imath = {documentation = "info:latex2e#Math symbols", symbol = "𝚤"}, + immediate = {}, + ["in"] = {documentation = "info:latex2e#Math symbols", symbol = "∈"}, + include = { + action = "input", + arguments = {{meta = "filename"}}, + documentation = "info:latex2e#\\include & \\includeonly", + filename = "?.tex", + summary = "Include a file." + }, + includegraphics = { + arguments = { + {literal = "*", meta = "star", optional = true}, + { + delimiters = {"[", "]"}, + meta = "key-value list", + optional = true + }, + {meta = "filename"} + }, + documentation = "info:latex2e#\\includegraphics", + summary = "Using a graphic in your document." + }, + includeonly = { + arguments = {{list = true, meta = "files"}}, + documentation = "info:latex2e#\\include & \\includeonly", + summary = "Conditionally include files." + }, + indent = { + documentation = "info:latex2e#\\indent & \\noindent", + summary = "Go into horizontal mode, with an indent." + }, + index = { + arguments = {{meta = "index-entry-string"}}, + documentation = "info:latex2e#\\index", + summary = "Declare an index entry." + }, + indexentry = {documentation = "info:latex2e#\\index"}, + indexspace = {documentation = "info:latex2e#makeindex"}, + inf = {documentation = "info:latex2e#Math functions"}, + infty = {documentation = "info:latex2e#Math symbols", symbol = "∞"}, + input = { + action = "input", + arguments = {{meta = "filename"}}, + documentation = "info:latex2e#\\input", + filename = "?", + summary = "Unconditionally include a file." + }, + int = {documentation = "info:latex2e#Math symbols", symbol = "∫"}, + intextsep = {documentation = "info:latex2e#Floats"}, + iota = {documentation = "info:latex2e#Math symbols", symbol = "ι"}, + it = {documentation = "info:latex2e#Font styles"}, + item = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "optional-label", + optional = true + } + }, + documentation = "info:latex2e#itemize", + summary = "An entry in a list." + }, + itemindent = {documentation = "info:latex2e#list"}, + itemsep = {documentation = "info:latex2e#list"}, + itshape = {documentation = "info:latex2e#Font styles"}, + j = {documentation = "info:latex2e#Accents"}, + jmath = {documentation = "info:latex2e#Math symbols", symbol = "𝚥"}, + k = {documentation = "info:latex2e#Accents"}, + kappa = {documentation = "info:latex2e#Math symbols", symbol = "κ"}, + ker = {documentation = "info:latex2e#Math functions"}, + kill = {documentation = "info:latex2e#tabbing"}, + l = {documentation = "info:latex2e#Additional Latin letters"}, + label = { + action = "label", + arguments = {{meta = "key"}}, + documentation = "info:latex2e#\\label", + summary = "Assign a symbolic name to a piece of text." + }, + labelenumi = {documentation = "info:latex2e#enumerate"}, + labelenumii = {documentation = "info:latex2e#enumerate"}, + labelenumiii = {documentation = "info:latex2e#enumerate"}, + labelenumiv = {documentation = "info:latex2e#enumerate"}, + labelitemi = {documentation = "info:latex2e#itemize"}, + labelitemii = {documentation = "info:latex2e#itemize"}, + labelitemiii = {documentation = "info:latex2e#itemize"}, + labelitemiv = {documentation = "info:latex2e#itemize"}, + labelsep = {documentation = "info:latex2e#list"}, + labelwidth = {documentation = "info:latex2e#list"}, + lambda = {documentation = "info:latex2e#Math symbols", symbol = "λ"}, + land = {documentation = "info:latex2e#Math symbols"}, + langle = {documentation = "info:latex2e#Math symbols", symbol = "⟨"}, + large = {documentation = "info:latex2e#Font sizes"}, + lbrace = {documentation = "info:latex2e#Math symbols", symbol = "{"}, + lbrack = {documentation = "info:latex2e#Math symbols", symbol = "["}, + lceil = {documentation = "info:latex2e#Math symbols", symbol = "⌈"}, + ldots = {documentation = "info:latex2e#Text symbols"}, + le = {documentation = "info:latex2e#Math symbols"}, + leadsto = {documentation = "info:latex2e#Math symbols"}, + left = { + arguments = {{meta = "delimiter"}}, + documentation = "info:latex2e#\\left & \\right", + summary = "Automatically sized delimiters." + }, + leftarrow = {documentation = "info:latex2e#Math symbols", symbol = "←"}, + lefteqn = {documentation = "info:latex2e#eqnarray"}, + leftharpoondown = {documentation = "info:latex2e#Math symbols", symbol = "↽"}, + leftharpoonup = {documentation = "info:latex2e#Math symbols", symbol = "↼"}, + leftmargin = {documentation = "info:latex2e#list"}, + leftmargini = {documentation = "info:latex2e#itemize"}, + leftmarginii = {documentation = "info:latex2e#itemize"}, + leftmarginiii = {documentation = "info:latex2e#itemize"}, + leftmarginiv = {documentation = "info:latex2e#itemize"}, + leftmarginv = {documentation = "info:latex2e#itemize"}, + leftmarginvi = {documentation = "info:latex2e#itemize"}, + leftrightarrow = {documentation = "info:latex2e#Math symbols", symbol = "↔"}, + leq = {documentation = "info:latex2e#Math symbols", symbol = "≤"}, + lfloor = {documentation = "info:latex2e#Math symbols", symbol = "⌊"}, + lg = {documentation = "info:latex2e#Math functions"}, + lhd = {documentation = "info:latex2e#Math symbols"}, + lim = {documentation = "info:latex2e#Math functions"}, + liminf = {documentation = "info:latex2e#Math functions"}, + limsup = {documentation = "info:latex2e#Math functions"}, + line = { + arguments = { + {delimiters = {"(", ")"}, meta = "x_run,y_rise"}, + {meta = "travel"} + }, + documentation = "info:latex2e#\\line", + summary = "Draw a straight line." + }, + linebreak = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "zero-to-four", + optional = true + } + }, + documentation = "info:latex2e#\\linebreak & \\nolinebreak", + summary = "Force a line break." + }, + linespread = { + arguments = {{meta = "factor"}}, + documentation = "info:latex2e#Low-level font commands" + }, + linethickness = { + arguments = {{meta = "dim"}}, + documentation = "info:latex2e#\\linethickness", + summary = "Set thickness of horizontal and vertical lines." + }, + linewidth = {documentation = "info:latex2e#Page layout parameters"}, + listoffigures = {documentation = "info:latex2e#Table of contents etc"}, + listoftables = {documentation = "info:latex2e#Table of contents etc"}, + listparindent = {documentation = "info:latex2e#list"}, + ll = {documentation = "info:latex2e#Math symbols", symbol = "≪"}, + ln = {documentation = "info:latex2e#Math functions"}, + lnot = {documentation = "info:latex2e#Math symbols"}, + location = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\location", + summary = "Sender's organizational location." + }, + log = {documentation = "info:latex2e#Math functions"}, + longleftarrow = {documentation = "info:latex2e#Math symbols", symbol = "⟵"}, + longleftrightarrow = {documentation = "info:latex2e#Math symbols", symbol = "⟷"}, + longmapsto = {documentation = "info:latex2e#Math symbols", symbol = "⟼"}, + longnewglossaryentry = {arguments = {{meta = "label"}}}, + longrightarrow = {documentation = "info:latex2e#Math symbols", symbol = "⟶"}, + lor = {documentation = "info:latex2e#Math symbols"}, + lq = {documentation = "info:latex2e#Text symbols"}, + mainmatter = { + documentation = "info:latex2e#\\frontmatter & \\mainmatter & \\backmatter", + summary = "Start main part of a book." + }, + makeatletter = {summary = "Change the status of the at-sign character."}, + makeatother = {summary = "Change the status of the at-sign character."}, + makebox = { + arguments = { + {delimiters = {"(", ")"}, meta = "rec-width,rec-height"}, + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\makebox (picture)", + summary = "Horizontal boxes." + }, + makeglossary = {documentation = "info:latex2e#Glossaries"}, + makeindex = {documentation = "info:latex2e#Indexes"}, + makelabel = {documentation = "info:latex2e#list"}, + makelabels = { + documentation = "info:latex2e#\\makelabels", + summary = "Make address labels." + }, + maketitle = { + documentation = "info:latex2e#\\maketitle", + summary = "Generate a title page." + }, + mapsto = {documentation = "info:latex2e#Math symbols", symbol = "↦"}, + marginpar = { + arguments = { + {delimiters = {"[", "]"}, meta = "left", optional = true}, + {meta = "right"} + }, + documentation = "info:latex2e#Marginal notes" + }, + marginparpush = {documentation = "info:latex2e#Marginal notes"}, + marginparsep = {documentation = "info:latex2e#Marginal notes"}, + marginparwidth = {documentation = "info:latex2e#Marginal notes"}, + marginsep = {documentation = "info:latex2e#Page layout parameters"}, + markboth = { + arguments = {{meta = "left-head"}, {meta = "right-head"}}, + documentation = "info:latex2e#\\pagestyle" + }, + markright = { + arguments = {{meta = "right"}}, + documentation = "info:latex2e#\\pagestyle" + }, + mathbb = {arguments = {{meta = "uppercase-letter"}}}, + mathbf = {documentation = "info:latex2e#Font styles"}, + mathcal = { + arguments = {{meta = "uppercase-letters"}}, + documentation = "info:latex2e#Font styles" + }, + mathdollar = {documentation = "info:latex2e#Math symbols", symbol = "$"}, + mathit = {}, + mathnormal = {documentation = "info:latex2e#Font styles"}, + mathparagraph = {documentation = "info:latex2e#Math symbols", symbol = "¶"}, + mathring = {documentation = "info:latex2e#Math accents"}, + mathrm = {documentation = "info:latex2e#Font styles"}, + mathsection = {documentation = "info:latex2e#Math symbols", symbol = "§"}, + mathsf = {documentation = "info:latex2e#Font styles"}, + mathsterling = {documentation = "info:latex2e#Math symbols", symbol = "£"}, + mathtt = {documentation = "info:latex2e#Font styles"}, + mathunderscore = {documentation = "info:latex2e#Math symbols"}, + mathversion = {documentation = "info:latex2e#Font styles"}, + max = {documentation = "info:latex2e#Math functions"}, + mbox = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\mbox & \\makebox", + summary = "Horizontal boxes." + }, + mdseries = {documentation = "info:latex2e#Font styles"}, + medbreak = {summary = "Inter-paragraph space and page breaks."}, + medskip = { + documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip", + summary = "Inter-paragraph vertical spaces." + }, + medskipamount = {documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip"}, + medspace = {documentation = "info:latex2e#Spacing in math mode"}, + message = { + arguments = {{meta = "string"}}, + documentation = "info:latex2e#\\message", + summary = "Write part of a line to log file and terminal." + }, + mho = {documentation = "info:latex2e#Math symbols", symbol = "℧"}, + mid = {documentation = "info:latex2e#Math symbols", symbol = "∣"}, + min = {documentation = "info:latex2e#Math functions"}, + models = {documentation = "info:latex2e#Math symbols", symbol = "⊧"}, + month = { + documentation = "info:latex2e#\\day & \\month & \\year", + summary = "Numeric date values." + }, + mp = {documentation = "info:latex2e#Math symbols", symbol = "∓"}, + mu = {documentation = "info:latex2e#Math symbols", symbol = "μ"}, + multicolumn = { + arguments = {{meta = "numcols"}, {meta = "cols"}, {meta = "text"}}, + documentation = "info:latex2e#\\multicolumn", + summary = "Make an item spanning several columns." + }, + multiput = { + arguments = { + {delimiters = {"(", ")"}, meta = "x,y"}, + {delimiters = {"(", ")"}, meta = "delta_x,delta_y"}, + {meta = "num-copies"}, + {meta = "obj"} + }, + documentation = "info:latex2e#\\multiput", + summary = "Draw multiple instances of an object." + }, + nabla = {documentation = "info:latex2e#Math symbols", symbol = "∇"}, + name = { + arguments = {{meta = "name"}}, + documentation = "info:latex2e#\\name", + summary = "Sender's name, for the return address." + }, + natural = {documentation = "info:latex2e#Math symbols", symbol = "♮"}, + ne = {documentation = "info:latex2e#Math symbols", symbol = "≠"}, + nearrow = {documentation = "info:latex2e#Math symbols", symbol = "↗"}, + neg = {documentation = "info:latex2e#Math symbols", symbol = "¬"}, + negthinspace = { + documentation = "info:latex2e#\\thinspace & \\negthinspace", + summary = "Negative one-sixth of an em." + }, + neq = {documentation = "info:latex2e#Math symbols"}, + newcommand = { + action = "newcommand", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "code"} + }, + documentation = "info:latex2e#\\newcommand & \\renewcommand", + summary = "Define a new command." + }, + newcounter = { + arguments = { + {meta = "countername"}, + { + delimiters = {"[", "]"}, + meta = "supercounter", + optional = true + } + }, + documentation = "info:latex2e#\\newcounter", + summary = "Define a new counter." + }, + newenvironment = { + action = "newenvironment", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "environment"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "begdef"}, + {meta = "enddef"} + }, + documentation = "info:latex2e#\\newenvironment & \\renewenvironment", + summary = "Define a new environment." + }, + newfont = { + action = "newcommand", + arguments = {{meta = "command"}, {meta = "font description"}}, + documentation = "info:latex2e#\\newfont", + summary = "Define a new font name." + }, + newglossaryentry = { + arguments = {{meta = "label"}, {meta = "settings"}}, + documentation = "info:latex2e#\\newglossaryentry", + summary = "Declare the content of a glossary entry." + }, + newlength = { + arguments = {{meta = "arg"}}, + documentation = "info:latex2e#\\newlength", + summary = "Define a new length." + }, + newline = { + documentation = "info:latex2e#\\newline", + summary = "Break the line" + }, + newpage = { + documentation = "info:latex2e#\\newpage", + summary = "Start a new page." + }, + newsavebox = { + arguments = {{meta = "command"}}, + documentation = "info:latex2e#\\newsavebox", + summary = "Define a new box." + }, + newtheorem = { + action = "newenvironment", + arguments = { + {meta = "name"}, + { + delimiters = {"[", "]"}, + meta = "numbered_like", + optional = true + }, + {meta = "title"} + }, + documentation = "info:latex2e#\\newtheorem", + summary = "Define a new theorem-like environment." + }, + newtie = {documentation = "info:latex2e#Accents"}, + ng = {documentation = "info:latex2e#Additional Latin letters"}, + ni = {documentation = "info:latex2e#Math symbols", symbol = "∋"}, + nocite = { + documentation = "info:latex2e#\\nocite", + summary = "Include an item in the bibliography." + }, + nocorr = {documentation = "info:latex2e#Font styles"}, + nocorrlist = {documentation = "info:latex2e#Font styles"}, + nofiles = { + documentation = "info:latex2e#\\nofiles", + summary = "Prevent writing to auxiliary files." + }, + noindent = { + documentation = "info:latex2e#\\indent & \\noindent", + summary = "Go into horizontal mode, without an indent." + }, + nolinebreak = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "zero-to-four", + optional = true + } + }, + documentation = "info:latex2e#\\linebreak & \\nolinebreak", + summary = "Avoid a line break." + }, + nonfrenchspacing = {documentation = "info:latex2e#\\frenchspacing"}, + nonumber = {documentation = "info:latex2e#eqnarray"}, + nopagebreak = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "zero-to-four", + optional = true + } + }, + documentation = "info:latex2e#\\pagebreak & \\nopagebreak", + summary = "Avoid a page break." + }, + normalfont = {documentation = "info:latex2e#Font styles"}, + normalmarginpar = {documentation = "info:latex2e#Marginal notes"}, + normalsfcodes = { + documentation = "info:latex2e#\\normalsfcodes", + summary = "Restore space factor settings to the default." + }, + normalsize = {documentation = "info:latex2e#Font sizes"}, + ["not"] = {documentation = "info:latex2e#Math symbols"}, + notin = {documentation = "info:latex2e#Math symbols", symbol = "∉"}, + nu = {documentation = "info:latex2e#Math symbols", symbol = "ν"}, + nwarrow = {documentation = "info:latex2e#Math symbols", symbol = "↖"}, + o = {documentation = "info:latex2e#Additional Latin letters"}, + obeycr = { + documentation = "info:latex2e#\\obeycr & \\restorecr", + summary = "Make each input line start a new output line." + }, + oddsidemargin = {documentation = "info:latex2e#Page layout parameters"}, + odot = {documentation = "info:latex2e#Math symbols", symbol = "⊙"}, + oe = {documentation = "info:latex2e#Additional Latin letters"}, + oint = {documentation = "info:latex2e#Math symbols", symbol = "∮"}, + oldstylenums = {documentation = "info:latex2e#Font styles"}, + omega = {documentation = "info:latex2e#Math symbols", symbol = "ω"}, + ominus = {documentation = "info:latex2e#Math symbols", symbol = "⊖"}, + onecolumn = { + documentation = "info:latex2e#\\onecolumn", + summary = "Use one-column layout." + }, + openin = { + documentation = "info:latex2e#\\openin & \\openout", + summary = "Open a file." + }, + opening = { + arguments = {{meta = "salutation"}}, + documentation = "info:latex2e#\\opening", + summary = "Saying hello." + }, + openout = { + documentation = "info:latex2e#\\openin & \\openout", + summary = "Open a file." + }, + oplus = {documentation = "info:latex2e#Math symbols", symbol = "⊕"}, + oslash = {documentation = "info:latex2e#Math symbols", symbol = "⊘"}, + otimes = {documentation = "info:latex2e#Math symbols", symbol = "⊗"}, + oval = { + arguments = { + {delimiters = {"(", ")"}, meta = "width,height"}, + {delimiters = {"[", "]"}, meta = "portion", optional = true} + }, + documentation = "info:latex2e#\\oval", + summary = "Draw an oval." + }, + overbrace = { + arguments = {{meta = "math"}}, + documentation = "info:latex2e#Over- and Underlining", + symbol = "⏞" + }, + overline = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#Over- and Underlining" + }, + owns = {documentation = "info:latex2e#Math symbols"}, + pagebreak = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "zero-to-four", + optional = true + } + }, + documentation = "info:latex2e#\\pagebreak & \\nopagebreak", + summary = "Force a page break." + }, + pagecolor = { + arguments = { + {delimiters = {"[", "]"}, meta = "color model", optional = true}, + {meta = "color specification"} + } + }, + pagenumbering = { + arguments = {{meta = "number-style"}}, + documentation = "info:latex2e#\\pagenumbering", + summary = "Set the style used for page numbers." + }, + pageref = { + arguments = {{meta = "key"}}, + documentation = "info:latex2e#\\pageref", + summary = "Refer to a page number." + }, + pagestyle = { + arguments = {{meta = "style"}}, + documentation = "info:latex2e#\\pagestyle", + summary = "Change the headings/footings style." + }, + paperheight = {documentation = "info:latex2e#Page layout parameters"}, + paperwidth = {documentation = "info:latex2e#Page layout parameters"}, + par = { + documentation = "info:latex2e#\\par", + summary = "End the current paragraph." + }, + paragraph = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\subsubsection & \\paragraph & \\subparagraph", + section_level = 5, + summary = "Start a paragraph. " + }, + parallel = {documentation = "info:latex2e#Math symbols", symbol = "∥"}, + parbox = { + arguments = { + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {delimiters = {"[", "]"}, meta = "height", optional = true}, + {delimiters = {"[", "]"}, meta = "inner-pos", optional = true}, + {meta = "width"}, + {meta = "contents"} + }, + documentation = "info:latex2e#\\parbox", + summary = "Box with text in paragraph mode." + }, + parindent = { + documentation = "info:latex2e#\\parindent & \\parskip", + summary = "Space added before paragraphs." + }, + parsep = {documentation = "info:latex2e#list"}, + parskip = { + documentation = "info:latex2e#itemize", + summary = "Space added before paragraphs." + }, + part = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\part", + section_level = -1, + summary = "Start a part." + }, + partial = {documentation = "info:latex2e#Math symbols", symbol = "∂"}, + partopsep = {documentation = "info:latex2e#list"}, + pdfpageheight = {documentation = "info:latex2e#Document class options"}, + pdfpagewidth = {documentation = "info:latex2e#Document class options"}, + perp = {documentation = "info:latex2e#Math symbols", symbol = "⟂"}, + phantom = { + arguments = {{meta = "subformula"}}, + summary = "Make empty box with the same size as the argument." + }, + phi = {documentation = "info:latex2e#Math symbols", symbol = "ϕ"}, + pi = {documentation = "info:latex2e#Math symbols", symbol = "π"}, + pm = {documentation = "info:latex2e#Math symbols", symbol = "±"}, + pmod = {documentation = "info:latex2e#Math functions"}, + poptabs = {documentation = "info:latex2e#tabbing"}, + pounds = {documentation = "info:latex2e#Text symbols"}, + prec = {documentation = "info:latex2e#Math symbols", symbol = "≺"}, + preceq = {documentation = "info:latex2e#Math symbols", symbol = "⪯"}, + prime = {documentation = "info:latex2e#Math symbols", symbol = "′"}, + printglossaries = {documentation = "info:latex2e#Glossaries"}, + printindex = { + documentation = "info:latex2e#\\printindex", + summary = "Put the index here." + }, + prod = {documentation = "info:latex2e#Math symbols", symbol = "∏"}, + propto = {documentation = "info:latex2e#Math symbols", symbol = "∝"}, + protect = { + documentation = "info:latex2e#\\protect", + summary = "Using tricky commands." + }, + providecommand = { + action = "newcommand", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "code"} + }, + documentation = "info:latex2e#\\providecommand", + summary = "Define a new command, if name not used." + }, + ps = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\ps", + summary = "Adding a postscript." + }, + psi = {documentation = "info:latex2e#Math symbols", symbol = "ψ"}, + pushtabs = {documentation = "info:latex2e#tabbing"}, + put = { + arguments = { + {delimiters = {"(", ")"}, meta = "xcoord,ycoord"}, + {meta = "content"} + }, + documentation = "info:latex2e#\\put", + summary = "Place an object at a specified place." + }, + qbezier = { + arguments = { + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"(", ")"}, meta = "x1,y1"}, + {delimiters = {"(", ")"}, meta = "x2,y2"}, + {delimiters = {"(", ")"}, meta = "x3,y3"} + }, + documentation = "info:latex2e#\\qbezier", + summary = "Draw a quadratic Bezier curve." + }, + qquad = { + documentation = "info:latex2e#\\enspace & \\quad & \\qquad", + summary = "Traditional horizontal spaces." + }, + quad = { + documentation = "info:latex2e#\\enspace & \\quad & \\qquad", + summary = "Traditional horizontal spaces." + }, + quotedblbase = {documentation = "info:latex2e#Text symbols"}, + quotesinglbase = {documentation = "info:latex2e#Text symbols"}, + r = {documentation = "info:latex2e#Accents"}, + raggedbottom = { + documentation = "info:latex2e#\\raggedbottom", + summary = "Allow text pages of differing height." + }, + raggedleft = { + documentation = "info:latex2e#\\raggedleft", + summary = "Declaration form of the flushright environment." + }, + raggedright = { + documentation = "info:latex2e#\\raggedright", + summary = "Declaration form of the flushleft environment." + }, + raisebox = { + arguments = { + {meta = "distance"}, + {delimiters = {"[", "]"}, meta = "height", optional = true}, + {delimiters = {"[", "]"}, meta = "depth", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\raisebox", + summary = "Raise or lower text." + }, + rangle = {documentation = "info:latex2e#Math symbols", symbol = "⟩"}, + rbrace = {documentation = "info:latex2e#Math symbols", symbol = "}"}, + rbrack = {documentation = "info:latex2e#Math symbols", symbol = "]"}, + rceil = {documentation = "info:latex2e#Math symbols", symbol = "⌉"}, + read = { + documentation = "info:latex2e#\\read", + summary = "Read text from a file." + }, + ref = { + action = "ref", + arguments = {{meta = "key"}}, + documentation = "info:latex2e#\\ref", + summary = "Refer to a section, figure or similar." + }, + reflectbox = { + arguments = {{meta = "material"}}, + documentation = "info:latex2e#\\scalebox" + }, + refstepcounter = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\refstepcounter", + summary = "Add to a counter." + }, + renewcommand = { + action = "newcommand", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "code"} + }, + summary = "Redefine an existing new command." + }, + renewenvironment = { + action = "newenvironment", + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "environment"}, + {delimiters = {"[", "]"}, meta = "number", optional = true}, + {delimiters = {"[", "]"}, meta = "default", optional = true}, + {meta = "begdef"}, + {meta = "enddef"} + }, + documentation = "info:latex2e#\\newenvironment & \\renewenvironment", + summary = "Redefine an existing environment." + }, + resizebox = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "horizontal length"}, + {meta = "vertical length"}, + {meta = "material"} + }, + documentation = "info:latex2e#\\resizebox", + summary = "Scaling boxes, including graphics, to a set size." + }, + restorecr = { + documentation = "info:latex2e#\\obeycr & \\restorecr", + summary = "Make each input line start a new output line." + }, + restriction = {documentation = "info:latex2e#Math symbols"}, + revemptyset = {documentation = "info:latex2e#Math symbols", symbol = "⦰"}, + reversemarginpar = {documentation = "info:latex2e#Marginal notes"}, + rfloor = {documentation = "info:latex2e#Math symbols", symbol = "⌋"}, + rhd = {documentation = "info:latex2e#Math symbols"}, + rho = {documentation = "info:latex2e#Math symbols", symbol = "ρ"}, + right = { + arguments = {{meta = "delimiter"}}, + documentation = "info:latex2e#\\left & \\right", + summary = "Automatically sized delimiters." + }, + rightarrow = {documentation = "info:latex2e#Math symbols", symbol = "→"}, + rightharpoondown = {documentation = "info:latex2e#Math symbols", symbol = "⇁"}, + rightharpoonup = {documentation = "info:latex2e#Math symbols", symbol = "⇀"}, + rightleftharpoons = {documentation = "info:latex2e#Math symbols", symbol = "⇌"}, + rightmargin = {documentation = "info:latex2e#list"}, + rm = {documentation = "info:latex2e#Font styles"}, + rmfamily = {documentation = "info:latex2e#Font styles"}, + roman = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\alph \\Alph \\arabic \\roman \\Roman \\fnsymbol", + summary = "Print value of a counter." + }, + rotatebox = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "key-value list", + optional = true + }, + {meta = "angle"}, + {meta = "material"} + }, + documentation = "info:latex2e#\\rotatebox", + summary = "Rotating boxes, including graphics." + }, + rq = {documentation = "info:latex2e#Text symbols"}, + rule = { + arguments = { + {delimiters = {"[", "]"}, meta = "raise", optional = true}, + {meta = "width"}, + {meta = "thickness"} + }, + documentation = "info:latex2e#\\rule", + summary = "Inserting lines and rectangles." + }, + savebox = { + arguments = { + {meta = "command"}, + {delimiters = {"[", "]"}, meta = "width", optional = true}, + {delimiters = {"[", "]"}, meta = "pos", optional = true}, + {meta = "text"} + }, + documentation = "info:latex2e#\\sbox & \\savebox", + summary = "Like \\makebox but save the text for later." + }, + sbox = { + arguments = {{meta = "command"}, {meta = "text"}}, + documentation = "info:latex2e#\\sbox & \\savebox", + summary = "Like \\makebox but save the text for later." + }, + sc = {documentation = "info:latex2e#Font styles"}, + scalebox = { + arguments = { + {meta = "horizontal factor"}, + { + delimiters = {"[", "]"}, + meta = "vertical factor", + optional = true + }, + {meta = "material"} + }, + documentation = "info:latex2e#\\scalebox", + summary = "Scaling boxes, including graphics." + }, + scriptsize = {documentation = "info:latex2e#Font sizes"}, + scshape = {documentation = "info:latex2e#Font styles"}, + searrow = {documentation = "info:latex2e#Math symbols", symbol = "↘"}, + sec = {documentation = "info:latex2e#Math functions"}, + section = { + action = "section", + arguments = { + { + literal = "*", + meta = "star", + optional = true, + summary = "If present, make an unnumbered heading." + }, + { + delimiters = {"[", "]"}, + meta = "short title", + optional = true, + summary = "Short title for table of contents and running headers." + }, + {meta = "title", summary = "The section heading."} + }, + documentation = "info:latex2e#\\section", + section_level = 1, + summary = "Start a section." + }, + seename = {documentation = "info:latex2e#\\index"}, + selectfont = {documentation = "info:latex2e#Low-level font commands"}, + setcounter = { + arguments = {{meta = "counter"}, {meta = "value"}}, + documentation = "info:latex2e#\\setcounter", + summary = "Set the value of a counter." + }, + setlength = { + arguments = {{meta = "len"}, {meta = "amount"}}, + documentation = "info:latex2e#\\setlength", + summary = "Set the value of a length." + }, + setminus = {documentation = "info:latex2e#Math symbols", symbol = "⧵"}, + settodepth = { + arguments = {{meta = "len"}, {meta = "text"}}, + documentation = "info:latex2e#\\settodepth", + summary = "Set a length to the depth of something." + }, + settoheight = { + arguments = {{meta = "len"}, {meta = "text"}}, + documentation = "info:latex2e#\\settoheight", + summary = "Set a length to the height of something." + }, + settowidth = { + arguments = {{meta = "len"}, {meta = "text"}}, + documentation = "info:latex2e#\\settowidth", + summary = "Set a length to the width of something." + }, + sf = {documentation = "info:latex2e#Font styles"}, + sffamily = {documentation = "info:latex2e#Font styles"}, + sharp = {documentation = "info:latex2e#Math symbols", symbol = "♯"}, + shortstack = { + arguments = { + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {meta = "lines"} + }, + documentation = "info:latex2e#\\shortstack", + summary = "Make a stack of objects." + }, + sigma = {documentation = "info:latex2e#Math symbols", symbol = "σ"}, + signature = { + arguments = {{meta = "sender name"}}, + documentation = "info:latex2e#\\signature", + summary = "Sender's signature." + }, + sim = {documentation = "info:latex2e#Math symbols", symbol = "∼"}, + simeq = {documentation = "info:latex2e#Math symbols", symbol = "≃"}, + sin = {documentation = "info:latex2e#Math functions"}, + sinh = {documentation = "info:latex2e#Math functions"}, + sl = {documentation = "info:latex2e#Font styles"}, + sloppy = { + documentation = "info:latex2e#\\fussy & \\sloppy", + summary = "Be less particular with line breaking." + }, + slshape = {documentation = "info:latex2e#Font styles"}, + small = {documentation = "info:latex2e#Font sizes"}, + smallbreak = {summary = "Inter-paragraph space and page breaks."}, + smallint = {documentation = "info:latex2e#Math symbols"}, + smallskip = { + documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip", + summary = "Inter-paragraph vertical spaces." + }, + smallskipamount = {documentation = "info:latex2e#\\bigskip & \\medskip & \\smallskip"}, + smash = { + arguments = {{meta = "subformula"}}, + summary = "Eliminate height or depth of a subformula." + }, + smile = {documentation = "info:latex2e#Math symbols", symbol = "⌣"}, + spacefactor = { + documentation = "info:latex2e#\\spacefactor", + summary = "Stretchability of following space" + }, + spadesuit = {documentation = "info:latex2e#Math symbols", symbol = "♠"}, + sqcap = {documentation = "info:latex2e#Math symbols", symbol = "⊓"}, + sqcup = {documentation = "info:latex2e#Math symbols", symbol = "⊔"}, + sqrt = { + arguments = { + {delimiters = {"[", "]"}, meta = "root-number", optional = true}, + {meta = "arg"} + }, + documentation = "info:latex2e#\\sqrt", + summary = "Radicals.", + symbol = "√" + }, + sqsubset = {documentation = "info:latex2e#Math symbols", symbol = "⊏"}, + sqsubseteq = {documentation = "info:latex2e#Math symbols", symbol = "⊑"}, + sqsupset = {documentation = "info:latex2e#Math symbols", symbol = "⊐"}, + sqsupseteq = {documentation = "info:latex2e#Math symbols", symbol = "⊒"}, + ss = {documentation = "info:latex2e#Additional Latin letters"}, + stackrel = { + arguments = {{meta = "text"}, {meta = "relation"}}, + documentation = "info:latex2e#\\stackrel", + summary = "Text over a relation." + }, + star = {documentation = "info:latex2e#Math symbols", symbol = "⋆"}, + stepcounter = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\stepcounter", + summary = "Add to a counter, resetting subsidiary counters." + }, + stop = {documentation = "info:latex2e#Recovering from errors"}, + strut = { + documentation = "info:latex2e#\\strut", + summary = "Ensure height of a line." + }, + subparagraph = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\subsubsection & \\paragraph & \\subparagraph", + section_level = 6, + summary = "Start a subparagraph." + }, + subsection = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\subsection", + section_level = 2, + summary = "Start a subsection." + }, + subset = {documentation = "info:latex2e#Math symbols", symbol = "⊂"}, + subseteq = {documentation = "info:latex2e#Math symbols", symbol = "⊆"}, + subsubsection = { + action = "section", + arguments = "$ref:latex#/commands/section/arguments", + documentation = "info:latex2e#\\subsubsection & \\paragraph & \\subparagraph", + section_level = 4, + summary = "Start a subsubsection." + }, + succ = {documentation = "info:latex2e#Math symbols", symbol = "≻"}, + succeq = {documentation = "info:latex2e#Math symbols", symbol = "⪰"}, + sum = {documentation = "info:latex2e#Math symbols", symbol = "∑"}, + sup = {documentation = "info:latex2e#Math functions"}, + suppressfloats = {documentation = "info:latex2e#Floats"}, + supset = {documentation = "info:latex2e#Math symbols", symbol = "⊃"}, + supseteq = {documentation = "info:latex2e#Math symbols", symbol = "⊇"}, + surd = {documentation = "info:latex2e#Math symbols", symbol = "√"}, + swarrow = {documentation = "info:latex2e#Math symbols", symbol = "↙"}, + symbol = {documentation = "info:latex2e#Symbols by font position"}, + t = {documentation = "info:latex2e#Accents"}, + tabbingsep = {documentation = "info:latex2e#tabbing"}, + tabcolsep = {documentation = "info:latex2e#tabular"}, + tableofcontents = {documentation = "info:latex2e#Table of contents etc"}, + tan = {documentation = "info:latex2e#Math functions"}, + tanh = {documentation = "info:latex2e#Math functions"}, + tau = {documentation = "info:latex2e#Math symbols", symbol = "τ"}, + telephone = { + arguments = {{meta = "number"}}, + documentation = "info:latex2e#\\telephone", + summary = "Sender's phone number." + }, + textascendercompwordmark = {documentation = "info:latex2e#Text symbols"}, + textasciicircum = {documentation = "info:latex2e#Text symbols"}, + textasciitilde = {documentation = "info:latex2e#Text symbols"}, + textasteriskcentered = {documentation = "info:latex2e#Text symbols"}, + textbackslash = {documentation = "info:latex2e#Text symbols"}, + textbar = {documentation = "info:latex2e#Text symbols"}, + textbardbl = {documentation = "info:latex2e#Text symbols"}, + textbf = {documentation = "info:latex2e#Font styles"}, + textbigcircle = {documentation = "info:latex2e#Text symbols"}, + textbraceleft = {documentation = "info:latex2e#Text symbols"}, + textbraceright = {documentation = "info:latex2e#Text symbols"}, + textbullet = {documentation = "info:latex2e#Text symbols"}, + textcapitalcompwordmark = {documentation = "info:latex2e#Text symbols"}, + textcircled = { + arguments = {{meta = "letter"}}, + documentation = "info:latex2e#Text symbols" + }, + textcolor = { + arguments = { + {delimiters = {"[", "]"}, meta = "color model", optional = true}, + {meta = "color specification"}, + {meta = "text"} + } + }, + textcompwordmark = {documentation = "info:latex2e#Text symbols"}, + textcopyright = {documentation = "info:latex2e#Text symbols"}, + textdagger = {documentation = "info:latex2e#Text symbols"}, + textdaggerdbl = {documentation = "info:latex2e#Text symbols"}, + textdollar = {documentation = "info:latex2e#Text symbols"}, + textellipsis = {documentation = "info:latex2e#Text symbols"}, + textemdash = {documentation = "info:latex2e#Text symbols"}, + textendash = {documentation = "info:latex2e#Text symbols"}, + texteuro = {documentation = "info:latex2e#Text symbols"}, + textexclamdown = {documentation = "info:latex2e#Text symbols"}, + textfloatsep = {documentation = "info:latex2e#Floats"}, + textfraction = {documentation = "info:latex2e#Floats"}, + textgreater = {documentation = "info:latex2e#Text symbols"}, + textheight = {documentation = "info:latex2e#Page layout parameters"}, + textit = {documentation = "info:latex2e#Font styles"}, + textleftarrow = {documentation = "info:latex2e#Text symbols"}, + textless = {documentation = "info:latex2e#Text symbols"}, + textmd = {documentation = "info:latex2e#Font styles"}, + textnormal = {documentation = "info:latex2e#Font styles"}, + textordfeminine = {documentation = "info:latex2e#Text symbols"}, + textordmasculine = {documentation = "info:latex2e#Text symbols"}, + textparagraph = {documentation = "info:latex2e#Text symbols"}, + textperiodcentered = {documentation = "info:latex2e#Text symbols"}, + textquestiondown = {documentation = "info:latex2e#Text symbols"}, + textquotedblleft = {documentation = "info:latex2e#Text symbols"}, + textquotedblright = {documentation = "info:latex2e#Text symbols"}, + textquoteleft = {documentation = "info:latex2e#Text symbols"}, + textquoteright = {documentation = "info:latex2e#Text symbols"}, + textquotesingle = {documentation = "info:latex2e#Text symbols"}, + textquotestraightbase = {documentation = "info:latex2e#Text symbols"}, + textquotestraightdblbase = {documentation = "info:latex2e#Text symbols"}, + textregistered = {documentation = "info:latex2e#Text symbols"}, + textrightarrow = {documentation = "info:latex2e#Text symbols"}, + textrm = {documentation = "info:latex2e#Font styles"}, + textsc = {documentation = "info:latex2e#Font styles"}, + textsection = {documentation = "info:latex2e#Text symbols"}, + textsf = {documentation = "info:latex2e#Font styles"}, + textsl = {documentation = "info:latex2e#Font styles"}, + textsterling = {documentation = "info:latex2e#Text symbols"}, + textthreequartersemdash = {documentation = "info:latex2e#Text symbols"}, + texttrademark = {documentation = "info:latex2e#Text symbols"}, + texttt = {documentation = "info:latex2e#Font styles"}, + texttwelveudash = {documentation = "info:latex2e#Text symbols"}, + textunderscore = {documentation = "info:latex2e#Text symbols"}, + textup = {documentation = "info:latex2e#Font styles"}, + textvisiblespace = {documentation = "info:latex2e#Text symbols"}, + textwidth = {documentation = "info:latex2e#Page layout parameters"}, + th = {documentation = "info:latex2e#Additional Latin letters"}, + thanks = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\maketitle" + }, + theta = {documentation = "info:latex2e#Math symbols", symbol = "θ"}, + thicklines = { + documentation = "info:latex2e#\\thicklines", + summary = "A heavier line thickness." + }, + thickspace = {documentation = "info:latex2e#Spacing in math mode"}, + thinlines = { + documentation = "info:latex2e#\\thinlines", + summary = "The default line thickness." + }, + thinspace = { + documentation = "info:latex2e#\\thinspace & \\negthinspace", + summary = "One-sixth of an em." + }, + thispagestyle = { + arguments = {{meta = "style"}}, + documentation = "info:latex2e#\\thispagestyle", + summary = "Change the headings/footings style for this page." + }, + tilde = {documentation = "info:latex2e#Math accents", symbol = "◌̃"}, + times = {documentation = "info:latex2e#Math symbols", symbol = "×"}, + tiny = {documentation = "info:latex2e#Font sizes"}, + title = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#\\maketitle" + }, + to = {documentation = "info:latex2e#Math symbols"}, + today = { + documentation = "info:latex2e#\\today", + summary = "Inserting today's date." + }, + top = {documentation = "info:latex2e#Math symbols", symbol = "⊤"}, + topfraction = {documentation = "info:latex2e#Floats"}, + topmargin = {documentation = "info:latex2e#Page layout parameters"}, + topsep = {documentation = "info:latex2e#list"}, + topskip = {documentation = "info:latex2e#Page layout parameters"}, + triangle = {documentation = "info:latex2e#Math symbols"}, + triangleleft = {documentation = "info:latex2e#Math symbols", symbol = "◁"}, + triangleright = {documentation = "info:latex2e#Math symbols", symbol = "▷"}, + tt = {documentation = "info:latex2e#Font styles"}, + ttfamily = {documentation = "info:latex2e#Font styles"}, + twocolumn = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "prelim one column text", + optional = true + } + }, + documentation = "info:latex2e#\\twocolumn", + summary = "Use two-column layout." + }, + typein = { + arguments = {{delimiters = {"[", "]"}, meta = "command", optional = true}}, + documentation = "info:latex2e#\\typein", + summary = "Read text from the terminal." + }, + typeout = { + arguments = {{meta = "msg"}}, + documentation = "info:latex2e#\\typeout", + summary = "Write text to the terminal." + }, + u = {documentation = "info:latex2e#Accents"}, + unboldmath = { + documentation = "info:latex2e#\\boldmath & \\unboldmath", + summary = "Symbols in boldface." + }, + underbar = {documentation = "info:latex2e#Accents"}, + underbrace = { + arguments = {{meta = "math"}}, + documentation = "info:latex2e#Over- and Underlining", + symbol = "⏟" + }, + underline = { + arguments = {{meta = "text"}}, + documentation = "info:latex2e#Over- and Underlining" + }, + unitlength = {documentation = "info:latex2e#picture"}, + unlhd = {documentation = "info:latex2e#Math symbols"}, + unrhd = {documentation = "info:latex2e#Math symbols"}, + uparrow = {documentation = "info:latex2e#Math symbols", symbol = "↑"}, + updownarrow = {documentation = "info:latex2e#Math symbols", symbol = "↕"}, + upharpoonright = {documentation = "info:latex2e#Math symbols", symbol = "↾"}, + uplus = {documentation = "info:latex2e#Math symbols", symbol = "⊎"}, + upshape = {documentation = "info:latex2e#Font styles"}, + upsilon = {documentation = "info:latex2e#Math symbols", symbol = "υ"}, + usebox = { + arguments = {{meta = "command"}}, + documentation = "info:latex2e#\\usebox", + summary = "Print saved text." + }, + usecounter = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\usecounter", + summary = "Use a specified counter in a list environment." + }, + usefont = { + arguments = { + {meta = "enc"}, + {meta = "family"}, + {meta = "series"}, + {meta = "shape"} + }, + documentation = "info:latex2e#Low-level font commands" + }, + usepackage = { + action = "input", + arguments = { + { + delimiters = {"[", "]"}, + list = true, + meta = "options", + optional = true + }, + {list = true, meta = "package"} + }, + documentation = "info:latex2e#Additional packages", + filename = "?.sty" + }, + v = {documentation = "info:latex2e#Accents"}, + value = { + arguments = {{meta = "counter"}}, + documentation = "info:latex2e#\\value", + summary = "Use the value of a counter in an expression. " + }, + vanothing = {documentation = "info:latex2e#Math symbols"}, + varepsilon = {documentation = "info:latex2e#Math symbols", symbol = "ε"}, + varphi = {documentation = "info:latex2e#Math symbols", symbol = "φ"}, + varpi = {documentation = "info:latex2e#Math symbols", symbol = "ϖ"}, + varrho = {documentation = "info:latex2e#Math symbols", symbol = "ϱ"}, + varsigma = {documentation = "info:latex2e#Math symbols", symbol = "ς"}, + vartheta = {documentation = "info:latex2e#Math symbols", symbol = "ϑ"}, + vdash = {documentation = "info:latex2e#Math symbols", symbol = "⊢"}, + vdots = {documentation = "info:latex2e#Dots", symbol = "⋮"}, + vec = {documentation = "info:latex2e#Math accents", symbol = "◌⃗"}, + vector = { + arguments = { + {delimiters = {"(", ")"}, meta = "x_run,y_rise"}, + {meta = "travel"} + }, + documentation = "info:latex2e#\\vector", + summary = "Draw a line with an arrow." + }, + vee = {documentation = "info:latex2e#Math symbols", symbol = "∨"}, + verb = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "char"}, + {meta = "literal-text"}, + {meta = "char"} + }, + documentation = "info:latex2e#\\verb", + summary = "The macro form of the verbatim environment." + }, + vert = {documentation = "info:latex2e#Math symbols", symbol = "|"}, + vfill = { + documentation = "info:latex2e#\\vfill", + summary = "Stretchable vertical space." + }, + vline = { + documentation = "info:latex2e#\\vline", + summary = "Draw a vertical line." + }, + vphantom = { + arguments = {{meta = "subformula"}}, + summary = "Make empty box with the same size as the argument." + }, + vspace = { + arguments = { + {literal = "*", meta = "star", optional = true}, + {meta = "length"} + }, + documentation = "info:latex2e#\\vspace", + summary = "Vertical space." + }, + wedge = {documentation = "info:latex2e#Math symbols", symbol = "∧"}, + widehat = {documentation = "info:latex2e#Math accents", symbol = "◌̂"}, + widetilde = {documentation = "info:latex2e#Math accents", symbol = "◌̃"}, + wlog = { + arguments = {{meta = "string"}}, + documentation = "info:latex2e#\\wlog", + summary = "Write to the log file." + }, + wp = {documentation = "info:latex2e#Math symbols", symbol = "℘"}, + wr = {documentation = "info:latex2e#Math symbols", symbol = "≀"}, + write = { + documentation = "info:latex2e#\\write18", + summary = "Write text to a file or terminal." + }, + xi = {documentation = "info:latex2e#Math symbols", symbol = "ξ"}, + year = {documentation = "info:latex2e#\\day & \\month & \\year"}, + zeta = {documentation = "info:latex2e#Math symbols", symbol = "ζ"}, + ["{"] = {documentation = "info:latex2e#Reserved characters"}, + ["|"] = {documentation = "info:latex2e#Math symbols"}, + ["}"] = {documentation = "info:latex2e#Reserved characters"}, + ["~"] = {documentation = "info:latex2e#Accents"} +} +environments = { + abstract = { + documentation = "info:latex2e#abstract", + summary = "Produce an abstract." + }, + array = { + arguments = { + {delimiters = {"[", "]"}, meta = "pos", optional = true}, + {meta = "cols"} + }, + documentation = "info:latex2e#array", + summary = "Math arrays." + }, + center = { + documentation = "info:latex2e#center", + summary = "Centered lines." + }, + description = { + action = "list", + documentation = "info:latex2e#description", + summary = "Labelled lists." + }, + displaymath = { + documentation = "info:latex2e#Math formulas", + summary = "Formulas that appear on their own line." + }, + document = { + documentation = "info:latex2e#document", + summary = "Enclose the whole document." + }, + enumerate = { + action = "list", + documentation = "info:latex2e#enumerate", + summary = "Numbered lists." + }, + eqnarray = { + documentation = "info:latex2e#eqnarray", + summary = "Sequences of aligned equations." + }, + equation = { + documentation = "info:latex2e#Math formulas", + summary = "Displayed equation." + }, + figure = { + arguments = {{delimiters = {"[", "]"}, meta = "placement", optional = true}}, + documentation = "info:latex2e#figure", + snippet = "begin{figure}${1:[placement]}\n\t$0\n\\caption{${2:caption text}}\n\\end{figure}", + summary = "Floating figures." + }, + ["figure*"] = { + arguments = {{delimiters = {"[", "]"}, meta = "placement", optional = true}}, + documentation = "info:latex2e#figure", + snippet = "begin{figure*}${1:[placement]}\n\t$0\n\\caption{${2:caption text}}\n\\end{figure*}", + summary = "Floating figure spanning both text columns." + }, + filecontents = { + arguments = {{meta = "filename"}}, + documentation = "info:latex2e#filecontents", + summary = "Writing multiple files from the source." + }, + ["filecontents*"] = { + arguments = {{meta = "filename"}}, + documentation = "info:latex2e#filecontents" + }, + flushleft = { + documentation = "info:latex2e#flushleft", + summary = "Flushed left lines." + }, + flushright = { + documentation = "info:latex2e#flushright", + summary = "Flushed right lines." + }, + itemize = { + action = "list", + documentation = "info:latex2e#itemize", + summary = "Bulleted lists." + }, + letter = { + arguments = {{meta = "recipient address"}}, + documentation = "info:latex2e#letter", + summary = "Letters." + }, + list = { + action = "list", + arguments = {{meta = "labeling"}, {meta = "spacing"}}, + documentation = "info:latex2e#list", + summary = "Generic list environment." + }, + lrbox = { + arguments = {{meta = "command"}}, + summary = "Environment version of \\sbox." + }, + math = { + documentation = "info:latex2e#Math formulas", + summary = "In-line math." + }, + minipage = { + arguments = { + {delimiters = {"[", "]"}, meta = "position", optional = true}, + {delimiters = {"[", "]"}, meta = "height", optional = true}, + {delimiters = {"[", "]"}, meta = "inner-pos", optional = true}, + {meta = "width"} + }, + documentation = "info:latex2e#minipage", + summary = "Miniature page." + }, + picture = { + arguments = { + {delimiters = {"(", ")"}, meta = "width,height"}, + {delimiters = {"(", ")"}, meta = "xoffset,yoffset"} + }, + documentation = "info:latex2e#picture", + summary = "Picture with text, arrows, lines and circles." + }, + quotation = { + documentation = "info:latex2e#quotation & quote", + summary = "Include a quotation." + }, + quote = { + documentation = "info:latex2e#quotation & quote", + summary = "Include a quotation." + }, + sloppypar = {summary = "Environment version of \\sloppy command."}, + tabbing = { + documentation = "info:latex2e#tabbing", + summary = "Align text arbitrarily." + }, + table = { + arguments = {{delimiters = {"[", "]"}, meta = "placement", optional = true}}, + documentation = "info:latex2e#table", + summary = "Floating tables." + }, + tabular = { + arguments = { + {delimiters = {"[", "]"}, meta = "pos", optional = true}, + {meta = "cols"} + }, + documentation = "info:latex2e#tabular", + summary = "Align text in columns." + }, + ["tabular*"] = { + arguments = { + {meta = "width"}, + {delimiters = {"[", "]"}, meta = "pos", optional = true}, + {meta = "cols"} + } + }, + thebibliography = { + arguments = {{meta = "widest-label"}}, + documentation = "info:latex2e#thebibliography", + summary = "Bibliography or reference list." + }, + theorem = { + documentation = "info:latex2e#\\newtheorem", + summary = "Theorems, lemmas, etc." + }, + titlepage = { + documentation = "info:latex2e#titlepage", + summary = "For hand crafted title pages." + }, + trivlist = {summary = "A restricted form of list."}, + verbatim = { + documentation = "info:latex2e#verbatim", + summary = "Simulating typed input." + }, + verse = { + documentation = "info:latex2e#verse", + summary = "For poetry and other things." + } +} diff --git a/support/digestif/data/natbib.sty.tags b/support/digestif/data/natbib.sty.tags new file mode 100644 index 0000000000..fc62570636 --- /dev/null +++ b/support/digestif/data/natbib.sty.tags @@ -0,0 +1,34 @@ +ctan_package = "natbib" +commands = { + Citealp = "$ref:natbib.sty#/commands/cite", + Citealt = "$ref:natbib.sty#/commands/cite", + Citeauthor = "$ref:natbib.sty#/commands/cite", + Citep = "$ref:natbib.sty#/commands/cite", + Citet = "$ref:natbib.sty#/commands/cite", + cite = { + action = "cite", + arguments = { + {delimiters = {"[", "]"}, meta = "prenote", optional = true}, + {delimiters = {"[", "]"}, meta = "postnote", optional = true}, + {list = true, meta = "keys"} + }, + summary = "Refer to a bibliography item." + }, + citealp = "$ref:natbib.sty#/commands/cite", + citealt = "$ref:natbib.sty#/commands/cite", + citeauthor = "$ref:natbib.sty#/commands/cite", + citeauthoryear = "$ref:natbib.sty#/commands/cite", + citefullauthor = "$ref:natbib.sty#/commands/cite", + citename = "$ref:natbib.sty#/commands/cite", + citenum = "$ref:natbib.sty#/commands/cite", + citep = "$ref:natbib.sty#/commands/cite", + citepalias = "$ref:natbib.sty#/commands/cite", + citestarts = "$ref:natbib.sty#/commands/cite", + citestyle = {arguments = {{meta = "style"}}}, + citet = "$ref:natbib.sty#/commands/cite", + citetalias = "$ref:natbib.sty#/commands/cite", + citetext = {arguments = {{meta = "text"}}}, + citeyear = "$ref:natbib.sty#/commands/cite", + citeyearpar = "$ref:natbib.sty#/commands/cite", + shortcites = "$ref:natbib.sty#/commands/cite" +} diff --git a/support/digestif/data/pgf.sty.tags b/support/digestif/data/pgf.sty.tags new file mode 100644 index 0000000000..defd5dd50c --- /dev/null +++ b/support/digestif/data/pgf.sty.tags @@ -0,0 +1 @@ +dependencies = {"pgf"} diff --git a/support/digestif/data/pgf.tags b/support/digestif/data/pgf.tags new file mode 100644 index 0000000000..24bdeeec27 --- /dev/null +++ b/support/digestif/data/pgf.tags @@ -0,0 +1,20068 @@ +-- Copyright 2007-2013 Till Tantau +-- Copyright 2022 Augusto Stoffel, Jens Schneider +-- SPDX-License-Identifier: GFDL-1.2-or-later or LPPL-1.3c+ +-- +-- Adapted from the PGF manual, version 3.1.9a, which can be found at +-- https://github.com/pgf-tikz/pgf/. +ctan_package = "pgf" +documentation = {{summary = "PGF Manual", uri = "texmf:doc/generic/pgf/pgfmanual.pdf"}} +commands = { + beginpgfgraphicnamed = { + arguments = {{meta = "file name prefix"}}, + details = [[ +This command indicates that everything up to the next call of +`\endpgfgraphicnamed` is part of a graphic that should be placed in a +file named ⟨file name prefix⟩`.`⟨suffix⟩, where the ⟨suffix⟩ depends on +your backend driver. Typically, ⟨suffix⟩ will be `dvi` or `pdf`. + +Here is a typical example of how this command is used: + + % In file main.tex: + ... + As we see in Figure~\ref{fig1}, the world is flat. + \begin{figure} + \beginpgfgraphicnamed{graphic-of-flat-world} + \begin{tikzpicture} + \fill (0,0) circle (1cm); + \end{tikzpicture} + \endpgfgraphicnamed + \caption{The flat world.} + \label{fig1} + \end{figure} + +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. + +This command can have three different effects: + +1. The easiest situation arises if there does not yet exist a graphic + file called ⟨file name prefix⟩`.`⟨suffix⟩, where the ⟨suffix⟩ is one + of the suffixes understood by your current backend driver (so `pdf` + or `jpg` if you use `pdftex`, `eps` if you use `dvips`, and so on). + In this case, both this command and the `\endpgfgraphicnamed` + command simply have no effect. + +2. A more complex situation arises when a graphic file named ⟨file name + prefix⟩`.`⟨suffix⟩ *does* exist. In this case, this graphic file is + included using the `\includegraphics` command [1]. Furthermore, the + text between `\beginpgfgraphicnamed` and `\endpgfgraphicnamed` is + ignored. + + When the text is "ignored", what actually happens is that all text + up to the next occurrence of `\endpgfgraphicnamed` is thrown away + without any macro expansion. This means, in particular, that (a) you + cannot put `\endpgfgraphicnamed` inside a macro and (b) the macros + used in the graphics need not be defined at all when the graphic + file is included. + +3. The most complex behavior arises when current the `\jobname` equals + the ⟨file name prefix⟩ and, furthermore, the *real job name* has + been declared. The behavior for this case is explained later. + +Note that the `\beginpgfgraphicnamed` does not really have any effect +until you have generated the graphic files named. Till then, this +command is simply ignored. Also, if you delete the graphics file later +on, the graphics are typeset normally once more. + +[1] Actually, the command key `/pgf/images/include external` is invoked +which calls an appropriate `\includegraphics` command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/beginpgfgraphicnamed" + }, + endpgfgraphicnamed = { + details = [[ +This command just marks the end of the graphic that should be +externalized. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/endpgfgraphicnamed" + }, + ifpgfmathmathunitsdeclared = { + details = [[ +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 *also* be set to true. The `scalar` +function has no effect on this TeX-if. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfmathmathunitsdeclared" + }, + ifpgfmathunitsdeclared = { + details = [[ +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. + +Note that *any* "mentioning" of a unit inside an expression will set +this TeX-if to true. In particular, even an expressionlike `2pt/1pt`, +which arguably should be considered "scalar" or "unit-free" will still +have this TeX-if set to true. However, see the `scalar` function for a +way to change this. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfmathunitsdeclared" + }, + ifpgfrememberpicturepositiononpage = { + details = [[ +Determines whether the position of pictures on the page should be +recorded. The value of this TeX-if at the end of a `{pgfpicture}` +environment is important, not the value at the beginning. + +If this option is set to true of a picture, PGF 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 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 ?? and ?? for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfrememberpicturepositiononpage" + }, + ifpgfshadingmodelcmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `cmyk` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelcmyk" + }, + ifpgfshadingmodelgray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `gray` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelgray" + }, + ifpgfshadingmodelrgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +test if the `xcolor` color model is `rgb` *at the time the shading is +created*. This can be used to ensure that the data output in the ⟨type 4 +function⟩ correctly matches the active color model. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfshadingmodelrgb" + }, + ["ifpgfsys@eorule"] = { + details = [[ +Determines whether the even odd rule is used for filling and clipping or +not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@eorule" + }, + ["ifpgfsys@transparency@group@isolated"] = { + details = [[ +Determines whether a transparency group should be isolated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@transparency@group@isolated" + }, + ["ifpgfsys@transparency@group@knockout"] = { + details = [[ +Determines whether a transparency group is a knockout group or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifpgfsys@transparency@group@knockout" + }, + ["pgf@process"] = { + arguments = {{meta = "code"}}, + details = [[ +Executes the ⟨code⟩ in a scope and then makes `\pgf@x` and `\pgf@y` +global. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@process" + }, + ["pgf@protocolsizes"] = { + arguments = {{meta = "x-dimension"}, {meta = "y-dimension"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@protocolsizes" + }, + ["pgf@relevantforpicturesizefalse"] = { + details = [[ +Suppresses updating of the picture's bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@relevantforpicturesizefalse" + }, + ["pgf@relevantforpicturesizetrue"] = { + details = [[ +Causes updating of the picture's bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@relevantforpicturesizetrue" + }, + ["pgf@sys@bp"] = { + arguments = {{meta = "dimension"}}, + details = [[ +Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the ⟨dimension⟩ +is into the current protocol stream (buffered). + +`\pgf@sys@bp{\pgf@x}` or `\pgf@sys@bp{1cm}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgf@sys@bp" + }, + pgfactualjobname = { + details = [[ +Once `\tikzexternalize` has been called, `\pgfactualjobname` contains +the name of the currently generated output file (which may be `main` or +`main-figure0` or `main-figure1` in our example above). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfactualjobname" + }, + pgfaliasid = { + arguments = {{meta = "alias"}, {meta = "name"}}, + details = [[ +Creates an alias of a name inside the current TeX scope. After calling +this command, you can use ⟨alias⟩ anywhere where you would normally use +⟨name⟩. Note that the binding between ⟨alias⟩ and ⟨name⟩ is not kept +when `\pgfuseid` is used on the ⟨name⟩ (or the ⟨alias⟩). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfaliasid" + }, + pgfaliasimage = { + arguments = {{meta = "new image name"}, {meta = "existing image name"}}, + details = [[ +The `{existing image name}` is "cloned" and the `{new image 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`. + +`\pgfaliasimage{image.!30!white}{image.!25!white}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfaliasimage" + }, + pgfalternateextension = { + details = [[ +You should redefine this command to install a different alternate +extension. + +`\def\pgfalternateextension{!25!white}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfalternateextension" + }, + pgfanimateattribute = { + arguments = { + {meta = "attribute"}, + {keys = "$ref:pgf#/keys/pgf", meta = "options"} + }, + details = [[ +Adds an animation of the ⟨attribute⟩ of a future *object* to the current +graphic. Attributes are things like the "fill opacity" or the +transformation matrix or the line width. + +The ⟨options⟩ are keys that configure how the attribute changes over +time. Using the `entry` key multiple times, you specify which value the +chosen attribute should have at different points in time. Unless special +keys are used, "outside" the specified timeline the animation has no +effect: + + \tikz { + \pgfanimateattribute{opacity}{ + whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + +Other keys, like `repeats`, allow you to specify how the animation +behaves "as a whole". These keys are documented later in this section. + +**The Attributes** + +In detail, the `\pgfanimateattribute` command opens a TeX-scope, looks +up the *type* values of the specified ⟨attribute⟩ have (if you wish to +animate the `opacity` of an object, the type is "scalar" meaning that +entries must be scalar numbers; when you animate the `fill` attribute, +the type is "color" and values must be colors, and so on), and then +executes the ⟨options⟩ with the path prefix `/pgf/animation`. Finally, +an appropriate system layer command `\pgfsysanimate...` is called to +create the actual animation and the scope is closed. + +The following ⟨attributes⟩ are permissible: + + ------------------------------------------- ----------- + *Attribute* *Type* + `draw`, `fill` color + `line width` dimension + `motion` scalar + `opacity`, `fill opacity`, `draw opacity` scalar + `path` path + `rotate` scalar + `scale` scaling + `softpath` softpath + `translate` point + `view` viewbox + `visible` boolean + `stage` boolean + `xskew`, `yskew` scalar + ------------------------------------------- ----------- + +These attributes are detailed in Sections ?? to ??, but here is a quick +overview: + +- `draw` and `fill` refer to the color used to draw (stroke) and fill + paths in an object, respectively. Typical values for this attribute + are `red` or `black!10`. + +- `line width` is, of course, the line width used in an object. + Typical values are `0.4pt` or `1mm`. Note that you (currently) + cannot use keys like `thin` or `thick` here, but this may change in + the future. + +- `motion` is a slightly special attribute: It allows you to specify a + path along which the object should be moved (using the `along` key). + The values given to the `entry` key for this attribute refer to a + *fraction of the distance along the path*. See the `along` key for + details. + +- `opacity` and the variants `fill opacity` and `draw opacity` animate + the opacity of an object. Allowed values range between 0 and 1. + +- `path` allows you to animate a path (it will morph). The "values" + are now paths themselves. See Section ?? for details. + +- `rotate` refers to a rotation of the object. Values for the `entry` + key are the rotation angles like `0` or `90`. + +- `scale` refers to the scaling of the object. Values are either + single scalars values (like `1` or `1.5`) or two numbers separated + by a comma (like `1,1.5` or `0.5,2`), referring to the $x$-scaling + and $y$-scaling. + +- `softpath` is a special case of the `path` attribute, see Section ?? + once more. + +- `translate` shifts the object by a certain vector. Values are points + like `\pgfpoint{1cm}{2cm}`. + +- `view` allows you to animate the view box of a view, see Section ?? + for details. + +- `visible` refers to the visibility of an object. Allowed values are + `true` and `false`. + +- `stage` is identical to `visible`, but when the object is not + animated, it will be hidden by default. + +- `xskew` and `yskew` skew the object. Attributes are angles like `0` + or `45` or even `90`. + +**The Target Object** + +As stated earlier, the ⟨options⟩ are used to specify the object whose +attribute for which an animation should be added to the picture. Indeed, +you *must* specify the object explicitly using the `whom` key and you +must do so *before* the object is created. Note that, in contrast, in +SVG you can specify an animation more or less anywhere and then use +hyper-references to link the animation to the to-be-animated object; +PGF insists that you specify the animation before the object. This is a +bit of a bother in some situations, but it is the only way to ensure +that PGF has a fighting chance to attach some additional code to the +object (which is necessary for almost all animations of the +transformation matrix). + +As explained in the introduction of this chapter, an "animation" is just +a bit of special text in the output document asking a viewer application +to animate the object at some later time. The `\pgfanimateattribute` +command inserts this special text immediately, even though it refers to +an object created only later on. Normally, this is not a problem, but +the special text should be on the same page as the to-be-animated +object. To ensure this, it suffices to call `\pgfanimateattribute` no +earlier than the beginning of the `pgfpicture` containing the object. + +**Naming the Animation** + +You can assign a name to an animation for later (or early) reference. In +particular, it is possible to begin *another* animation relative to the +beginning or end of this animation and for referencing this animation +must be assigned a name. See the `of` and `of next` keys for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfanimateattribute" + }, + pgfanimateattributecode = { + arguments = {{meta = "attribute"}, {meta = "code"}}, + details = [[ +The command works like `\pgfanimateattribute`, only instead of ⟨options⟩ +you specify some ⟨code⟩ whose job is to setup the options. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfanimateattributecode" + }, + pgfapproximatenonlineartransformation = { + details = [[ +This command will do two things: + +1. It clears the nonlinear transformations for the rest of the current + TeX scope, so only linear transformations apply. + +2. 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. + +  + + \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} + +This command is used by `\pgftext` and `\pgfnode` to transform text when +a nonlinear transformation is in force. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfapproximatenonlineartransformation" + }, + pgfapproximatenonlineartranslation = { + details = [[ +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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfapproximatenonlineartranslation" + }, + pgfarrowsaddtolateoptions = { + arguments = {{meta = "code"}}, + details = [[ +This command works like `\pgfarrowsaddtooptions`, only the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtolateoptions" + }, + pgfarrowsaddtolengthscalelist = { + arguments = {{meta = "dimension register"}}, + details = [[ +Each time an arrow tip is used, the given ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtolengthscalelist" + }, + pgfarrowsaddtooptions = { + arguments = {{meta = "code"}}, + details = [[ +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: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}} + +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: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy + +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: + + \pgfkeys{/pgf/arrow keys/depth/.code= + \pgfmathsetlength{\somedimen}{#1} + \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtooptions" + }, + pgfarrowsaddtowidthscalelist = { + arguments = {{meta = "dimension register"}}, + details = [[ +Works like `\pgfarrowsaddtolengthscalelist`, only for width parameters. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsaddtowidthscalelist" + }, + pgfarrowshullpoint = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Adds a point to the convex hull of the arrow tip. As for the previous +commands, no math parsing is done; instead PGF says `\pgf@x=`⟨x +dimension⟩ and then `\pgf@y=`⟨y dimension⟩. Thus, both "dimensions" can +contain code for advancing and thus modifying `\pgf@x` and `\pgf@y`. + +In our example we would write + + \pgfarrowshullpoint{1cm}{0pt} + \pgfarrowshullpoint{-3cm}{2cm} + \pgfarrowshullpoint{-3cm}{-2cm} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowshullpoint" + }, + pgfarrowslengthdependent = { + arguments = {{meta = "dimension"}, {meta = "length factor"}, {meta = "dummy"}}, + details = [[ +This command takes 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`. + +You can setup length dependent keys using code like the following: + + \pgfkeys{/pgf/arrow keys/depth'/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowslengthdependent" + }, + pgfarrowslinewidthdependent = { + arguments = { + {meta = "dimension"}, + {meta = "line width factor"}, + {meta = "outer factor"} + }, + details = [[ +This command takes three parameters and does the "line width dependent +computation" described on page ?? for the `length` key. The result is +returned in `\pgf@x`. + +The idea is that you can setup line-width dependent keys like `length` +or `width` using code like the following: + + \pgfkeys{/pgf/arrow keys/depth/.code={% + \pgfarrowsthreeparameters{#1}% + \expandafter\pgfarrowsaddtolateoptions\expandafter{% + \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute... + \pgfarrowdepth\pgf@x% ... and store. + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowslinewidthdependent" + }, + pgfarrowssave = { + arguments = {{meta = "macro"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssave" + }, + pgfarrowssavethe = { + arguments = {{meta = "register"}}, + details = [[ +Works like `\pgfarrowssave`, only the parameter must be a register and +`\the`⟨register⟩ will be saved. Typically, you will write something like + + \pgfarrowssavethe{\pgfarrowlength} + \pgfarrowssavethe{\pgfarrowwidth} + +To ensure that inside the drawing code the the dimension registers +`\pgfarrowlength` and `\pgfarrowwidth` are setup with the values they +had during the setup. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssavethe" + }, + pgfarrowssetbackend = { + arguments = {{meta = "dimension"}}, + details = [[ +Works like the command for the tip end, only it sets the back end. In +our example we would call + + \pgfarrowssettipend{-3cm} + +Defaults to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetbackend" + }, + pgfarrowssetlineend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the line end, so in the example we have +`\pgfarrowssettipend{-1cm}`. Default to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetlineend" + }, + pgfarrowssettipend = { + arguments = {{meta = "dimension"}}, + details = [[ +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 +⟨dimension⟩. For example, for our earlier example of the large arrow +tip, where the tip end was at 1cm, we would call + + \pgfarrowssettipend{1cm} + +Note that for efficiency reasons, the ⟨dimension⟩ is not passed through +`\pgfmathsetlength`; rather what happens is that `\pgf@x=`⟨dimension⟩ +gets executed. In particular, you can pack further computations into the +⟨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: + + \pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth} + +If the command is not called at all inside the setup code, the tip end +is set to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssettipend" + }, + pgfarrowssetvisualbackend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the visual back end, `\pgfarrowssetvisualbackend{-2cm}` in our +example. Default to the value of the normal back end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetvisualbackend" + }, + pgfarrowssetvisualtipend = { + arguments = {{meta = "dimension"}}, + details = [[ +Sets the visual tip end. Default to the value of the normal tip end and, +thus, we need not set it in our example. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowssetvisualtipend" + }, + pgfarrowsthreeparameters = { + arguments = {{meta = "line-width dependent size specification"}}, + details = [[ +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 ⟨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} + }% + + \pgfarrowsthreeparameters{2pt 1} + \showvalueofmacro\pgfarrowstheparameters +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsthreeparameters" + }, + pgfarrowsupperhullpoint = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +This command works like the previous command, only it normally adds +*two* points to the convex hull: First, the point +$(⟨x dimension⟩,⟨y dimension⟩)$ and, secondly, the point +$(⟨x dimension⟩,-⟨y dimension⟩)$. However, the second point is only +added if the arrow is not a harpoon. + +Thus, in our example we could simplify the convex hull to + + \pgfarrowshullpoint{1cm}{0pt} + \pgfarrowsupperhullpoint{-3cm}{2cm} + +If the ⟨y dimension⟩ is zero or less, only one point, namely +$(⟨x dimension⟩,⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfarrowsupperhullpoint" + }, + pgfcalendar = { + arguments = { + {meta = "prefix"}, + {meta = "start date"}, + {meta = "end date"}, + {meta = "rendering code"} + }, + details = [[ +This command can be used to typeset a calendar. It is a very general +command, the actual work has to be done by giving clever implementations +of ⟨rendering code⟩. Note that this macro need *not* be called inside a +`{pgfpicture}` environment (even though it typically will be) and you +can use it to typeset calendars in normal TeX or using packages other +than PGF. + +**Basic typesetting process.** A calendar is typeset as follows: The +⟨start date⟩ and ⟨end date⟩ specify a range of dates. For each date in +this range the ⟨rendering code⟩ is executed with certain macros setup to +yield information about the *current date* (the current date in the +enumeration of dates of the range). Typically, the ⟨rendering code⟩ +places nodes inside a picture, but it can do other things as well. Note +that it is also the job of the ⟨rendering code⟩ to position the calendar +correctly. + +The different calls of the ⟨rending code⟩ are not surrounded by +TeX groups (though you can do so yourself, of course). This means that +settings can accumulate between different calls, which is often +desirable and useful. + +**Information about the current date.** Inside the ⟨rendering code⟩, +different macros can be access: + +- `\pgfcalendarprefix` The ⟨prefix⟩ parameter. This prefix is + recommended for nodes inside the calendar, but you have to use it + yourself explicitly. + +- `\pgfcalendarbeginiso` The ⟨start date⟩ of range being typeset in + ISO format (like 2006-01-10). + +- `\pgfcalendarbeginjulian` Julian day number of ⟨start date⟩. + +- `\pgfcalendarendiso` The ⟨end date⟩ of range being typeset in ISO + format. + +- `\pgfcalendarendjulian` Julian day number of ⟨end date⟩. + +- `\pgfcalendarcurrentjulian` This TeX count holds the Julian day + number of the day currently being rendered. + +- `\pgfcalendarcurrentweekday` The weekday (a number with zero + representing Monday) of the current date. + +- `\pgfcalendarcurrentyear` The year of the current date. + +- `\pgfcalendarcurrentmonth` The month of the current date (always two + digits with a leading zero, if necessary). + +- `\pgfcalendarcurrentday` The day of month of the current date + (always two digits). + +**The `\ifdate` command.** Inside the `\pgfcalendar` the macro `\ifdate` +is available locally: + +**Examples.** In a first example, let us create a very simple calendar: +It just lists the dates in a certain range. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ } + +Let us now make this a little more interesting: Let us add a line break +after each Sunday. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10} + { + \pgfcalendarcurrentday\ + \ifdate{Sunday}{\par}{} + } + +We now want to have all Mondays to be aligned on a column. For this, +different approaches work. Here is one based positioning each day +horizontally using a skip. + + \pgfcalendar{cal}{2007-01-20}{2007-02-10} + {% + \leavevmode% + \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}% + \ifdate{Sunday}{\par}{}% + } + +Let us now typeset two complete months. + + \pgfcalendar{cal}{2007-01-01}{2007-02-28}{% + \ifdate{day of month=1}{ + \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par + }{}% + \leavevmode% + {% + \ifdate{weekend}{\color{black!50}}{\color{black}}% + \hbox to0pt{% + \hskip\pgfcalendarcurrentweekday cm% + \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss% + }% + }% + \ifdate{Sunday}{\par}{}% + } + +For our final example, we use a `{tikzpicture}`. + + \begin{tikzpicture} + \pgfcalendar{cal}{2007-01-20}{2007-02-10}{% + \ifdate{workday} + {\tikzset{filling/.style={fill=blue!20}}} + {\tikzset{filling/.style={fill=red!20}}} + \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0) + [anchor=base,circle,filling] {\pgfcalendarcurrentday}; + \ifdate{Sunday}{\pgftransformyshift{-3em}}{}% + } + \draw (cal-2007-01-21) -- (cal-2007-02-03); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendar" + }, + pgfcalendardatetojulian = { + arguments = {{meta = "date"}, {meta = "counter"}}, + details = [[ +This macro converts a date in a format to be described in a moment to +the Julian day number in the Gregorian calendar. The ⟨date⟩ should +expand to a string of the following form: + +1. It should start with a number representing the year. Use `\year` for + the current year, that is, the year the file is being typeset. + +2. The year must be followed by a hyphen. + +3. Next should come a number representing the month. Use `\month` for + the current month. You can, but need not, use leading zeros. For + example, `02` represents February, just like `2`. + +4. The month must also be followed by a hyphen. + +5. Next you must either provide a day of month (again, a number and, + again, `\day` yields the current day of month) or the keyword + `last`. This keyword refers to the last day of the month, which is + automatically computed (and which is a bit tricky to compute, + especially for February). + +6. Optionally, you can next provide a plus sign followed by positive or + negative number. This number of days will be added to the computed + date. + +Here are some examples: + +- `2006-01-01` refers to the first day of 2006. + +- `2006-02-last` refers to February 28, 2006. + +- `\year-\month-\day` refers to today. + +- `2006-01-01+2` refers to January 3, 2006. + +- `\year-\month-\day+1` refers to tomorrow. + +- `\year-\month-\day+-1` refers to yesterday. + +The conversion method is taken from the English Wikipedia entry on +Julian days. + +`\pgfcalendardatetojulian{2007-01-14}{\mycount}` sets `\mycount` to . +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendardatetojulian" + }, + pgfcalendareastersunday = { + arguments = {{meta = "year"}, {meta = "counter"}}, + details = [[ +This command computes the date of Easter Sunday as a Julian date and +stores it in ⟨counter⟩. + +`\pgfcalendareastersunday{2019}{\mycount}` sets `\mycount` to , which +corresponds to ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendareastersunday" + }, + pgfcalendarifdate = { + arguments = { + {meta = "date"}, + {meta = "tests"}, + {meta = "code"}, + {meta = "else code"} + }, + details = [[ +\[pgfcalendarifdate\] This command is used to execute code based on +properties of ⟨date⟩. The ⟨date⟩ must be a date in ISO-format. For this +date, the ⟨tests⟩ are checked (to be detailed later) and if one of the +tests succeeds, the ⟨code⟩ is executed. If none of the tests succeeds, +the ⟨else code⟩ is executed. + +`\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}` +yields ``. + +The ⟨tests⟩ is a comma-separated list of key--value pairs. The following +are defined by default: + +This test is passed by all dates. This test is passed by all dates that +are Mondays. as above. as above. as above. as above. as above. as above. +Passed by Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays. Passed +by Saturdays and Sundays. `=`⟨reference⟩ The ⟨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 first case, the test is +passed if ⟨date⟩ is the same as ⟨reference⟩. In the second case, the +test is passed if the month and day part of ⟨date⟩ is the same as +⟨reference⟩. + +For example, the test `equals=2007-01-10` will only be passed by this +particular date. The test `equals=05-01` will be passed by every first +of May on any year. `=`⟨reference⟩ This test works similarly to the +`equals` test, only it is checked whether ⟨date⟩ is equal to ⟨reference⟩ +or to any later date. Again, the ⟨reference⟩ can be a full date like +`2007-01-01` or a short version like `07-01`. For example, +`at least=07-01` is true for every day in the second half of any year. +`=`⟨reference⟩ as above. `=`⟨start reference⟩` and `⟨end reference⟩ This +test checks whether the current date lies between the two given +reference dates. Both full and short version may be given. + +For example `between=2007-01-01 and 2007-02-28` is true for the days in +January and February of 2007. + +For another example, `between=05-01 and 05-07` is true for the days of +the first week of May of any year. `=`⟨number⟩ Passed by the day of +month of the ⟨date⟩ that is ⟨number⟩. For example, the test +`day of month=1` is passed by every first of every month. `=`⟨number⟩ +Passed by the day of month of the ⟨date⟩ that is ⟨number⟩ from the end +of the month. For example, the test `end of month=1` is passed by the +last day of every month, the test `end of month=2` is passed by the +second last day of every month. If ⟨number⟩ is omitted, it is assumed to +be `1`. `=`⟨number⟩ This test checks whether the given date is Easter +Sunday. The optional number can be used for offsets from Easter Sunday, +e.g. `Easter=-3` for Maundy Thursday, `Easter=-2` for Good Friday, +`Easter=1` for Easter Monday. Since the dates of other Christian +holidays are determined by the date of Easter, these can be accessed as +well, e.g. `Easter=39` for Feast of the Ascension, `Easter=49` for +Pentecost, and `Easter=50` for Whit Monday. + +In addition to the above checks, you can also define new checks. To 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 ⟨date⟩ passes the test +setup by this new key. + +In order to perform the test, the key code needs to know the date that +should be checked. The date is available through a macro, but a whole +bunch of additional information about this date is also available +through the following macros: + +- `\pgfcalendarifdatejulian` is the Julian day number of the ⟨date⟩ to + be checked. + +- `\pgfcalendarifdateweekday` is the weekday of the ⟨date⟩ to be + checked. + +- `\pgfcalendarifdateyear` is the year of the ⟨date⟩ to be checked. + +- `\pgfcalendarifdatemonth` is the month of the ⟨date⟩ to be checked. + +- `\pgfcalendarifdateday` is the day of month of the ⟨date⟩ to be + checked. + +For example, let us define a new key that checks whether the ⟨date⟩ is a +Workers day (May 1st). This can be done as follows: + + \pgfkeys{/pgf/calendar/workers day/.code=% + { + \ifnum\pgfcalendarifdatemonth=5\relax + \ifnum\pgfcalendarifdateday=1\relax + \pgfcalendarmatchestrue + \fi + \fi + }} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarifdate" + }, + pgfcalendarjuliantodate = { + arguments = { + {meta = "Julian day"}, + {meta = "year macro"}, + {meta = "month macro"}, + {meta = "day macro"} + }, + details = [[ +This command converts a Julian day number to an ISO-date. The ⟨Julian +day⟩ must be a number or TeX counter, the ⟨year macro⟩, ⟨month macro⟩ +and ⟨day macro⟩ must be TeX macro names. They will be set to numbers +representing the year, month, and day of the given Julian day in the +Gregorian calendar. + +The ⟨year macro⟩ will be assigned the year without leading zeros. Note +that this macro will produce year 0 (as opposed to other calendars, +where year 0 does not exist). However, if you really need calendars for +before the year 1, it is expected that you know what you are doing +anyway. + +The ⟨month macro⟩ gets assigned a two-digit number representing the +month (with a leading zero, if necessary). Thus, the macro is set to +`01` for January. + +The ⟨day macro⟩ gets assigned a two-digit number representing 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: + + \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday} + \edef\isodate{\myyear-\mymonth-\myday} + +The above code sets `\isodate` to ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarjuliantodate" + }, + pgfcalendarjuliantoweekday = { + arguments = {{meta = "Julian day"}, {meta = "week day counter"}}, + details = [[ +This command converts a Julian day to a week day by computing the day +modulo 7. The ⟨week day counter⟩ must be a TeX counter. It will be set +to 0 for a Monday, to 1 for a Tuesday, and so on. + +`\pgfcalendarjuliantoweekday{2454115}{\mycount}` sets `\mycount` to  (it +was a Sunday). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarjuliantoweekday" + }, + pgfcalendarmonthname = { + arguments = {{meta = "month number"}}, + details = [[ +This command expands to a textual representation of the month, which is +given by the ⟨month number⟩. + +`\pgfcalendarmonthname{12}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarmonthname" + }, + pgfcalendarmonthshortname = { + arguments = {{meta = "month number"}}, + details = [[ +As above, only an abbreviated version is produced. + +`\pgfcalendarmonthshortname{12}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarmonthshortname" + }, + pgfcalendarshorthand = { + arguments = {{meta = "kind"}, {meta = "representation"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarshorthand" + }, + pgfcalendarsuggestedname = { + details = [[ +This macro expands to a suggested name for nodes representing days in a +calendar. If the ⟨prefix⟩ is empty, it expands to the empty string, +otherwise it expands to the ⟨prefix⟩ of the calendar, followed by a +hyphen, followed by the ISO format version of the date. Thus, when the +date `2007-01-01` is typeset in a calendar for the prefix `mycal`, the +macro expands to `mycal-2007-01-01`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarsuggestedname" + }, + pgfcalendarweekdayname = { + arguments = {{meta = "week day number"}}, + details = [[ +This command expands to a textual representation of the day of week, +given by the ⟨week day number⟩. Thus, `\pgfcalendarweekdayname{0}` +expands to `Monday` if the current language is English and to `Montag` +if the current language is German, and so on. See Section ?? for more +details on translations. + +`\pgfcalendarweekdayname{2}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarweekdayname" + }, + pgfcalendarweekdayshortname = { + arguments = {{meta = "week day number"}}, + details = [[ +This command works similarly to the previous command, only an +abbreviated version of the week day is produced. + +`\pgfcalendarweekdayshortname{2}` yields ``. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcalendarweekdayshortname" + }, + pgfclearid = { + details = [[ +Clears the current id (and type) for the local scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfclearid" + }, + pgfcoordinate = { + arguments = {{meta = "name"}, {meta = "coordinate"}}, + details = [[ +This command creates a node of shape `coordinate` at the given +⟨coordinate⟩. Exactly the same effect can be achieved using first a +shift of the coordinate system to ⟨coordinate⟩, followed by creating a +node of shape `coordinate` named ⟨name⟩. However, this command is easier +and more natural to use and, more importantly, it is much faster. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcoordinate" + }, + pgfcurvilineardistancetotime = { + arguments = {{meta = "distance"}}, + details = [[ +This command does a "distance-to-time-conversion": It tries to compute a +time $t$, returned in `\pgf@x`, that corresponds to travelling +⟨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: + +- The conversion will be best near the start of the curve. + +- The more "degenerate" the curve, the worse the results. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfcurvilineardistancetotime" + }, + pgfdata = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "inline data"} + }, + details = [[ +This command is used to feed data to the visualization pipeline. This +command can only be used when a data visualization object has been +properly setup, see Section ??. + +**Basic options.** The `\pgfdata` command may be followed by ⟨options⟩, +which are executed with the path `/pgf/data/`. Depending on these +options, the ⟨options⟩ may either be followed by ⟨inline data⟩ or, +alternatively, no ⟨inline data⟩ is present and the data is read from an +external source. + +The first important option is ⟨source⟩, which governs which of these two +alternatives applies: + +The second important key is `format`, which is used to specify the data +format: + +In case all your data is in a certain format, you may wish to generally +set the above key somewhere at the beginning of your file. +Alternatively, you can use the following style to setup the `format` key +and possibly further keys concerning the data format: + +**Gathering of the data.** Once the data format and the source have been +decided upon, the data is "gathered". During this phase the data is not +actually parsed in detail, but just gathered so that it can later be +parsed during the visualization. There are two different ways in which +the data is gathered: + +- In case you have specified an external source, the data + visualization object is told (by means of invoking the `add data` + method) that it should (later) read data from the file specified by + the `source` key using the format specified by the `format` key. The + file is not read at this point, but only later during the actual + visualization. + +- Otherwise, namely when data is given inline, depending on which + format is used, some catcodes get changed. This is necessary since + TeX's special characters are often not-so-special in a certain + format. + + Independently of the format, the end-of-line character (carriage + return) is made an active character. + + Finally, the ⟨inline data⟩ is then read as a normal argument and the + data visualization object is told that later on it should parse this + data using the given format parser. Note that in this case the data + visualization object must store the whole data internally. + +In both cases the "data visualization object" is the object stored in +the `/pgf/data visualization/obj` key. + +**Parsing of the data.** During the actual data visualization, all code +that has been added to the data visualization object by means of the +`add data` method is executed several times. It is the job of this code +to call the `\pgfdatapoint` method for all data points present in the +data. + +When the `\pgfdata` method calls `add data`, the code that is passed to +the data visualization object is just a call to internal macros of +`\pgfdata`, which are able to parse the data stored in an external file +or in the inlined data. Independently of where the data is stored, these +macros always do the following: + +1. The catcodes are setup according to what the data format requires. + +2. Format-specific startup code gets called, which can initialize + internal variables of the parsing process. (The catcode changes are + not part of the startup code since in order to read inline data + `\pgfdata` must be able to setup to temporarily setup the catcodes + needed later on by the parsers, but since no reading is to be done, + no startup code should be called at this point.) + +3. For each line of the data a format-specific code handler, which + depends on the data format, is called. This handler gets the current + line as input and should call `\pgfdatapoint` once for each data + point that is encoded by this line (a line might define multiple + data points or none at all). Empty lines are handled by special + format-specific code. + +4. At the end, format-specific end code is executed. + +For an example of how this works, see the description of the +`\pgfdeclaredataformat` command. + +**Data sets.** There are three options that allow you to create *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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdata" + }, + pgfdeclarearrow = { + arguments = {{meta = "config"}}, + details = [[ +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. + +**Defining a Complete New Arrow Tip Kind.** The ⟨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: + +- `name``=`⟨name⟩ or `name=`⟨start name⟩`-`⟨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 first 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. + +- `parameters``=``{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 ??.) + + 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 ⟨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 + ⟨list of macros⟩ should be set to + `\the\pgfarrowlength,\the\pgfarrowwidth`. (Actually, the comma is + optional, the ⟨list of macros⟩ does not really have to be a list, + just something that can be expanded unambiguously.) + + 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 PGF thinks that it can reuse some code when, + in reality, this code actually depends on a parameter not listed + here. + +- `setup code``=``{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 ⟨code⟩ gets executed (only this once). The code can now + do arbitrarily complicated computations the prepare the later + drawing of the arrow tip. Also the ⟨code⟩ must specify the different + tip and back ends and the convex hull points. This is done by + calling the following macros inside the ⟨code⟩: + +- `drawing code``=``{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 ⟨code⟩ will we stored in a special cache; but in some + cases the ⟨code⟩ gets executed each time the arrow tip is used, so + do not assume anything about it. Inside the ⟨code⟩, you have access + to all values that were saved in the setup code as well as to the + line width. + + The ⟨code⟩ should draw the arrow tip "going right along the + $x$-axis". PGF 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 ⟨code⟩: + + - In the ⟨code⟩ you may *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. + + - 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. + + - When the arrow tip code is executed, it is automatically put + inside a low-level scope, so nothing will "leak out" from the + scope. + + - The high-level coordinate transformation matrix will be set to + the identity matrix when the code is executed for the first + time. + +- `cache``=`⟨true or false⟩ + + When set to `true`, which is the default, the ⟨code⟩ will be + executed only once for a particular value of parameters and the + low-level commands created by the drawing code (using the system + layer protocol subsystem, see Section ??) 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`. + +- `bending mode``=`⟨mode⟩ + + This key is important only when the `bend` option is used with an + arrow, see Section ?? 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 ⟨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 ?? for details. Which of these ways is use can be configured + by setting ⟨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`. + +- `defaults``=`⟨arrow keys⟩ + + The ⟨arrow keys⟩ allow you to configure the default values for the + parameters on which an arrow tip depends. The ⟨arrow keys⟩ will be + executed first before any other arrow tip options are executed, see + Section ?? for the exact sequence. Also see Section ?? below for + more details on arrow options. + +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 example. 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: + + \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 } + } + +We can now use it: + + \tikz \draw [-foo] (0,0) -- (8,0); + + \tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0); + +**Defining a Shorthand.** The `\pgfdeclarearrow` command can also used +to define *shorthands*. This works as follows: + +- First, you must provide a `name` just in the same way as when you + define a full-flung new arrow tip kind. + +- Second, instead of all of the other options listed above, you just + use one more option: + + `means``=`⟨end arrow specification⟩ + + This sets up things so that whenever ⟨name⟩ is now used in an arrow + specification, it will be replaced by the ⟨end arrow specification⟩ + (the problems resulting form the ⟨name⟩ begin used in a start arrow + specification are taken care of automatically). See also Section ?? + for details on the order in which options get executed in such + cases. + + Note that the ⟨end arrow specification⟩ will be executed immediately + to build the so-called arrow option caches, a concept explored in + more detail in Section ??. 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 ⟨end arrow specification⟩ will be + evaluated immediately. For instance, when you write + + \pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] } + + The value `2cm+\mydimen` is evaluated immediately. When `foo` is + used later on and `\mydimen` has changed, this has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarearrow" + }, + pgfdeclaredataformat = { + arguments = { + {meta = "format name"}, + {meta = "catcode code"}, + {meta = "startup code"}, + {meta = "line arguments"}, + {meta = "line code"}, + {meta = "empty line code"}, + {meta = "end code"} + }, + details = [[ +This command defines a new data format called ⟨format name⟩, which can +subsequently be used in the `\pgfdata` command. (The TikZ's `data` maps +directly to `\pgfdata`, so the following applies to TikZ as well.) + +As explained in the description of the `\pgfdata` command, when data is +being parsed that is formatted according to ⟨format name⟩, the following +happens: + +1. The ⟨catcode code⟩ is executed. This code should just contain + catcode changes. The ⟨catcode code⟩ will also be executed when + inline data is read. + +2. Next, the ⟨startup code⟩ is executed. + +3. Next, for each non-empty line of the data, the line is passed to a + macro whose argument list is given by ⟨line arguments⟩ and whose + body is given by ⟨line code⟩. The idea is that you can use TeX's + powerful pattern matching capabilities to parse the non-empty lines. + See also the below example. + +4. Empty lines are not processed by the ⟨line code⟩, but rather by the + ⟨empty line code⟩. Typically, empty lines can simply be ignored and + in this case you can let this parameter be empty. + +5. At the end of the data, the ⟨end code⟩ is executed. + +As an example, let us now define a simple data format for reading files +formatted in the following manner: Each line should contain a coordinate +pair as in `(1.2,3.2)`, so two numbers separated by a comma and +surrounded by parentheses. To make things more interesting, suppose that +the hash mark symbol can be used to indicate comments. Here is an +example of some data given in this format: + + # This is some data formatted according to the "coordinates" format + (0,0) + (0.5,0.25) + (1,1) + (1.5,2.25) + (2,4) + +A format parser for this format could be defined as follows: + + \pgfdeclaredataformat{coordinates} + % First comes the catcode argument. We turn the hash mark into a comment character. + {\catcode`\#=14\relax} + % Second comes the startup code. Since we do not need to setup things, we can leave + % it empty. Note that we could also set it to something like \begingroup, provided we + % put an \endgroup in the end code + {} + % Now comes the arguments for non-empty lines. Well, these should be of the form + % (#1,#2), so we specify that: + {(#1,#2)} + % Now we must do something with a line of this form. We store the #1 argument in + % /data point/x and #2 in /data point/y. Then we call \pgfdatapoint to create a data point. + { + \pgfkeyssetvalue{/data point/x}{#1} + \pgfkeyssetvalue{/data point/y}{#2} + \pgfdatapoint + } + % We ignore empty lines: + {} + % And we also have no end-of-line code. + {} + +This format could now be used as follows: + + \begin{tikzpicture} + \datavisualization[school book axes, visualize as smooth line] + data [format=coordinates] { + # This is some data formatted according + # to the "coordinates" format + (0,0) + (0.5,0.25) + (1,1) + (1.5,2.25) + (2,4) + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaredataformat" + }, + pgfdeclaredecoration = { + arguments = {{meta = "name"}, {meta = "initial state"}, {meta = "states"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaredecoration" + }, + pgfdeclarefading = { + arguments = {{meta = "name"}, {meta = "contents"}}, + details = [[ +This command declares a fading named ⟨name⟩ for later use. The "picture" +on which the fading is based is given by the ⟨contents⟩. The ⟨contents⟩ +are normally typeset in a TeX box. The resulting box is then used as the +"picture". In particular, inside the ⟨contents⟩ you must explicitly open +a `{pgfpicture}` environment if you wish to use PGF commands. + +Let's start with an easy example. Our first fading picture is just some +text: + + \pgfdeclarefading{fading1}{\textcolor{white}{Ti\emph{k}Z}} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + +What's happening here? The "fading picture" is mostly transparent, +except for the pixels that are part of the word Ti*k*Z. Now, these +pixels are *white* and, thus, have a high luminosity. This in turn means +that these pixels of the fading will be highly opaque. For this reason, +only those pixels of the big red rectangle "shine through" that are at +the positions of these opaque pixels. + +It is somewhat counter-intuitive that the white pixels in a fading +picture are opaque in a fading. For this reason, the color +`pgftransparent` is defined to be the same as `black`. This allows one +to write `pgftransparent` for completely transparent parts of a fading +picture and `pgftransparent!0` for the opaque parts and things like +`pgftransparent!20` for parts that are 20% transparent. + +Furthermore, the color `pgftransparent!0` (which is the same as white +and which corresponds to completely opaque) is installed at the +beginning of a fading picture. Thus, in the above example the +`\color{white}` was not really necessary. + +Next, let us create a fading that gets more and more transparent as we +go from left to right. For this, we put a shading inside the fading +picture that has the color `pgftransparent!0` at the left-hand side and +the color `pgftransparent!100` at the right-hand side. + + \pgfdeclarefading{fading2} + {\tikz \shade[left color=pgftransparent!0, + right color=pgftransparent!100] (0,0) rectangle (2,2);} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + +In our final example, we create a fading that is based on a radial +shading. + + \pgfdeclareradialshading{myshading}{\pgfpointorigin} + { + color(0mm)=(pgftransparent!0); + color(5mm)=(pgftransparent!0); + color(8mm)=(pgftransparent!100); + color(15mm)=(pgftransparent!100) + } + \pgfdeclarefading{fading3}{\pgfuseshading{myshading}} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarefading" + }, + pgfdeclarefunctionalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "lower left corner"}, + {meta = "upper right corner"}, + {meta = "init code"}, + {meta = "type 4 function"} + }, + details = [[ +*Warning: These shadings are the least portable of all and they put the +heaviest burden of the renderer. They are slow and, possibly, will not +print correctly!* + +This command creates a *functional shading*. For such a shading, the +color of each point is calculated by calling a function that takes the +coordinates of the point as input and yields the color as an output. +Note that the function is evaluated by the *renderer*, not by PGF or +TeX or someone else at compile-time. This means that the evaluation of +this function has to be done *extremely quickly* and the function should +be *very simple*. For this reason, only a very restricted set of +operations are possible in the function and functions should be kept +small. Any errors in the function will only be noticed by the renderer. + +The syntax for specifying functions is the following: You use a +simplified form of a subset of the PostScript language. This subset will +be understood by the PDF-renderer (yes, PDF-renderers do have a basic +understanding of PostScript) and also by PostScript renders. This subset +is detailed in Section 3.9.4 of the PDF-specification (version 1.7). In +essence, the specification states that these functions may contain +"expressions involving integers, real numbers, and boolean values only. +There are no composite data structures such as strings or arrays, no +procedures, and no variables or names." The allowed operators are +(exactly) the following: `abs`, `add`, `atan`, `ceiling`, `cos`, `cvi`, +`cvr`, `div`, `exp`, `floor`, `idiv`, `ln`, `log`, `mod`, `mul`, `neg`, +`round`, `sin`, `sqrt`, `sub`, `truncate`, `and`, `bitshift`, `eq`, +`false`, `ge`, `gt`, `le`, `lt`, `ne`, `not`, `or`, `true`, `xor`, `if`, +`ifelse`, `copy`, `dup`, `exch`, `index`, `pop`. + +When the function is evaluated, the top two stack elements are the +coordinates of the point for which the color should be computed. The +coordinates are dimensionless and given in big points, so for the +coordinate $(50bp, 72.27pt)$ the top two stack elements would be `50.0` +and `72.0`. Otherwise, the (virtual) stack is 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 for an RGB shading, four colors, representing the cyan, +magenta, yellow, and black color of the point for a CMYK shading, or one +value representing the gray color for a grayscale shading. The numbers +should be 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 the +rectangle ⟨lower left corner⟩ to ⟨upper right corner⟩, which should be a +PGF-point expression like `\pgfpoint{100bp}{100bp}`. A renderer may +choose to evaluate the function at less points, but, in principle, the +function will be evaluated for each pixel independently. + +Because of the rather difficult PostScript syntax, use this macro only +*if you know what you are doing* (or if you are adventurous, of course). + +As for other shadings, the optional ⟨color list⟩ is used to determine +whether a shading needs to be recalculated when a color has changed. + +The ⟨init code⟩ is executed each time a shading is (re)calculated. +Typically, it will contain code to extract coordinates from colors. + + \pgfdeclarefunctionalshading{twospots} + {\pgfpointorigin}{\pgfpoint{4cm}{4cm}}{}{ + % Save coordinates for later + 2 copy + % Compute distance from (40bp,45bp), with x doubled + 45 sub dup mul exch + 40 sub dup mul 0.5 mul add sqrt + % exponential decay + dup mul neg 1.0005 exch exp 1.0 exch sub + % 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 + % Decay + dup mul neg 1.002 exch exp 1.0 exch sub + % red component + 1.0 3 1 roll + } + \pgfuseshading{twospots} + +Inside the PostScript function ⟨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 one of `\pgfshadecolortorgb`, +`\pgfshadecolortocmyk`, or `\pgfshadecolortogray` in the ⟨init code⟩: + + \pgfdeclarefunctionalshading[col1,col2,col3,col4]{bilinear interpolation} + {\pgfpointorigin}{\pgfpoint{100bp}{100bp}} + { + \pgfshadecolortorgb{col1}{\first}\pgfshadecolortorgb{col2}{\second} + \pgfshadecolortorgb{col3}{\third}\pgfshadecolortorgb{col4}{\fourth} + }{ + 100 div exch 100 div 2 copy % Calculate y/100 x/100. + neg 1 add exch neg 1 add % Calculate 1-y/100 1-x/100. + 3 1 roll 2 copy exch 5 2 roll 6 copy 6 copy % Set up stack. + \firstred mul exch \secondred mul add mul % Process red component. + 4 1 roll + \thirdred mul exch \fourthred mul add mul + add + 13 1 roll + \firstgreen mul exch \secondgreen mul add mul % Process green component. + 4 1 roll + \thirdgreen mul exch \fourthgreen mul add mul + add + 7 1 roll + \firstblue mul exch \secondblue mul add mul % Process blue component. + 4 1 roll + \thirdblue mul exch \fourthblue mul add mul + add + } + + \colorlet{col1}{blue} + \colorlet{col2}{yellow} + \colorlet{col3}{red} + \colorlet{col4}{green} + \pgfuseshading{bilinear interpolation} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarefunctionalshading" + }, + pgfdeclarehorizontalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "shading height"}, + {meta = "color specification"} + }, + details = [[ +Declares a horizontal shading named ⟨shading name⟩ of the specified +⟨height⟩ with the specified colors. The width of the bar is deduced +automatically from the maximum dimension in the specification. + + \pgfdeclarehorizontalshading{myshadingA} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)} + \pgfuseshading{myshadingA} + +The effect of the ⟨color list⟩, which is a comma-separated list of +colors, is the following: Normally, when this list is empty, once a +shading has been declared, it becomes "frozen". This means that even if +you change a color that was used in the declaration of the shading later +on, the shading will not change. By specifying a ⟨color list⟩ you can +specify that the shading should be recalculated whenever one of the +colors listed in the list changes (this includes effects like color +mixins and `xcolor` color models). Thus, when you specify a ⟨color +list⟩, whenever the shading is used, PGF first converts the colors in +the list to tuples in the current `xcolor` color model using the current +values of the colors and taking any mixins and blends into account. If +the resulting tuples have not yet been used, a new shading is internally +created and used. Note that if the option ⟨color list⟩ is used, then no +shading is created until the first use of `\pgfuseshading`. In +particular, the colors mentioned in the shading need not be defined when +the declaration is given. + +When a shading is recalculated because of a change in the colors +mentioned in ⟨color list⟩, the complete shading is recalculated. Thus +even colors not mentioned in the list will be used with their current +values, not with the values they had upon declaration. + + \pgfdeclarehorizontalshading[mycolor]{myshadingB} + {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)} + \colorlet{mycolor}{green} + \pgfuseshading{myshadingB} + \colorlet{mycolor}{blue} + \pgfuseshading{myshadingB} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarehorizontalshading" + }, + pgfdeclareimage = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "image name"}, + {meta = "filename"} + }, + details = [[ +Declares an image, but does not paint anything. To draw the image, use +`\pgfuseimage{`⟨image name⟩`}`. The ⟨filename⟩ may not have an +extension. For PDF, the extensions `.pdf`, `.jpg`, and `.png` will +automatically tried. For PostScript, the extensions `.eps`, `.epsi`, and +`.ps` will be tried. + +The following options are possible: + +- `height=`⟨dimension⟩ sets the height of the image. If the width is + not specified simultaneously, the aspect ratio of the image is kept. + +- `width=`⟨dimension⟩ sets the width of the image. If the height is + not specified simultaneously, the aspect ratio of the image is kept. + +- `page=`⟨page number⟩ selects a given page number from a multipage + document. Specifying this option will have the following effect: + first, PGF tries to find a file named + + > ⟨filename⟩`.page`⟨page number⟩`.`⟨extension⟩ + + If such a file is found, it will be used instead of the originally + specified filename. If not, PGF inserts the image stored in + ⟨filename⟩`.`⟨extension⟩ and if a recent version of `pdflatex` is + used, only the selected page is inserted. For older versions of + `pdflatex` and for `dvips` the complete document is inserted and a + warning is printed. + +- `interpolate=`⟨true or false⟩ selects whether the image should be + "smoothed" when zoomed. False by default. + +- `mask=`⟨mask name⟩ selects a transparency mask. The mask must + previously be declared using `\pgfdeclaremask` (see below). This + option only has an effect for `pdf`. Not all viewers support + masking. + +  + + \pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareimage" + }, + pgfdeclarelayer = { + arguments = {{meta = "name"}}, + details = [[ +This command declares a layer named ⟨name⟩ for later use. Mainly, this +will set up some internal bookkeeping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarelayer" + }, + pgfdeclarelindenmayersystem = { + arguments = {{meta = "name"}, {meta = "specification"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarelindenmayersystem" + }, + pgfdeclaremask = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "mask name"}, + {meta = "filename"} + }, + details = [[ +Declares a transparency mask named ⟨mask name⟩ (called a *soft mask* in +the PDF specification). This mask is read from the file ⟨filename⟩. This +file should contain a grayscale image that is as large as the actual +image. A white pixel in the mask will correspond to "transparent", a +black pixel to "solid", and gray values correspond to intermediate +values. The mask must have a single "color channel". This means that the +mask must be a "real" grayscale image, not an RGB-image in which all +RGB-triples happen to have the same components. + +You can only mask images that are in a "pixel format". For drivers with +PDF output, these are `.jpg` and `.png` image files; you cannot mask +`.pdf` images in this way. Pixel images for the `dvips`+`ps2pdf` +workflow must be provided as `.eps` or `.ps` files. Also, again, the +mask file and the image file must have the same size. + +The following options may be given: + +- `matte=``{color components}` sets the so-called *matte* of the + actual image (strangely, this has to be specified together with the + mask, not with the image itself). The matte is the color that has + been used to preblend the image. For example, if the image has been + preblended with a red background, then ⟨color components⟩ should be + set to `{1 0 0}`. The default is `{1 1 1}`, which is white in the + rgb model. + + The matte is specified in terms of the parent's image color space. + Thus, if the parent is a grayscale image, the matte has to be set to + `{1}`. + +  + + %% Draw a large colorful background + \pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red); + color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red); + color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red); + color(14cm)=(green)} + \hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm + \pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm + \pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm + \pgfdeclaremask{mymask}{brave-gnu-world-logo-mask} + \pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaremask" + }, + pgfdeclaremetadecorate = { + arguments = {{meta = "name"}, {meta = "initial state"}, {meta = "states"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclaremetadecorate" + }, + pgfdeclarepattern = { + arguments = {{meta = "config"}}, + details = [[ +This command is used to declare a new pattern. In contrast to the normal +patterns and in the spirit of `arrows.meta` this command takes a list of +keys and values to define the pattern. The following keys are available: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepattern" + }, + pgfdeclarepatternformonly = { + arguments = { + {delimiters = {"[", "]"}, meta = "variables", optional = true}, + {meta = "name"}, + {meta = "bottom left"}, + {meta = "top right"}, + {meta = "tile size"}, + {meta = "code"} + }, + details = [[ +This command declares a new form-only pattern. The ⟨name⟩ is a name for +later reference. The two parameters ⟨lower left⟩ and ⟨upper right⟩ must +describe a bounding box that is large enough to encompass the complete +tile. + +The size of a tile is given by ⟨tile size⟩, that is, a tile is a +rectangle whose lower left corner is the origin and whose upper right +corner is given by ⟨tile size⟩. This might make you wonder why the +second and third parameters are needed. First, the bounding box might be +smaller than the tile size if the tile is larger than the picture on the +tile. Second, the bounding box might be bigger, in which case the +picture will "bleed" over the tile. + +The ⟨code⟩ should be PGF code than can be protocolled. It should not +contain any color code. + + \pgfdeclarepatternformonly{stars} + {\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + {\pgfpoint{1cm}{1cm}} + { + \pgftransformshift{\pgfpoint{.5cm}{.5cm}} + \pgfpathmoveto{\pgfpointpolar{0}{4mm}} + \pgfpathlineto{\pgfpointpolar{144}{4mm}} + \pgfpathlineto{\pgfpointpolar{288}{4mm}} + \pgfpathlineto{\pgfpointpolar{72}{4mm}} + \pgfpathlineto{\pgfpointpolar{216}{4mm}} + \pgfpathclose% + \pgfusepath{fill} + } + \begin{tikzpicture} + \filldraw[pattern=stars] (0,0) rectangle (1.5,2); + \filldraw[pattern=stars,pattern color=red] + (1.5,0) rectangle (3,2); + \end{tikzpicture} + +The optional argument ⟨variables⟩ consists of a comma separated list of +macros, registers or keys, representing the parameters of the pattern +that may vary. If a variable is a key, then the full path name must be +used (specifically, it must start with `/`). As an example, a list might +look like the following: `\mymacro,\mydimen,/pgf/my key`. Note that +macros and keys should be "simple". They should only store values in +themselves. + +The effect of ⟨variables⟩, is the following: 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 ⟨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 pattern is set, PGF checks if the pattern has already been +created with the ⟨variables⟩ set to their current values (PGF is usually +"smart enough" to distinguish between macros, registers and keys). If +so, this already-declared-pattern is used as the fill pattern. If not, a +new instance of the pattern (which will have a unique internal name) is +declared using the current values of ⟨variables⟩. These values are then +saved and the fill pattern set accordingly. + +The following shows an example of a pattern which varies according to +the values of the macro `\size`, the key `/tikz/radius`, and the TeX +dimension `\thickness`. + + \pgfdeclarepatternformonly[/tikz/radius,\thickness,\size]{rings} + {\pgfpoint{-0.5*\size}{-0.5*\size}} + {\pgfpoint{0.5*\size}{0.5*\size}} + {\pgfpoint{\size}{\size}} + { + \pgfsetlinewidth{\thickness} + \pgfpathcircle\pgfpointorigin{\pgfkeysvalueof{/tikz/radius}} + \pgfusepath{stroke} + } + \newdimen\thickness + \tikzset{ + radius/.initial=4pt, + size/.store in=\size, size=20pt, + thickness/.code={\thickness=#1}, + thickness=0.75pt + } + \begin{tikzpicture}[rings/.style={pattern=rings}] + \filldraw [rings, radius=2pt, size=6pt] (0,0) rectangle +(1.5,2); + \filldraw [rings, radius=2pt, size=8pt] (2,0) rectangle +(1.5,2); + \filldraw [rings, radius=6pt, thickness=2pt] (0,2.5) rectangle +(1.5,2); + \filldraw [rings, radius=8pt, thickness=4pt] (2,2.5) rectangle +(1.5,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepatternformonly" + }, + pgfdeclarepatterninherentlycolored = { + arguments = { + {delimiters = {"[", "]"}, meta = "variables", optional = true}, + {meta = "name"}, + {meta = "lower left"}, + {meta = "upper right"}, + {meta = "tile size"}, + {meta = "code"} + }, + details = [[ +This command works like `\pgfdeclarepatternuncolored`, only the pattern +will have an inherent color. To set the color, you should use PGF's +color commands, not the `\color` command, since this fill is not +protocolled. + + \pgfdeclarepatterninherentlycolored{green stars} + {\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + {\pgfpoint{1cm}{1cm}} + { + \pgfsetfillcolor{green!50!black} + \pgftransformshift{\pgfpoint{.5cm}{.5cm}} + \pgfpathmoveto{\pgfpointpolar{0}{4mm}} + \pgfpathlineto{\pgfpointpolar{144}{4mm}} + \pgfpathlineto{\pgfpointpolar{288}{4mm}} + \pgfpathlineto{\pgfpointpolar{72}{4mm}} + \pgfpathlineto{\pgfpointpolar{216}{4mm}} + \pgfpathclose% + \pgfusepath{stroke,fill} + } + \begin{tikzpicture} + \filldraw[pattern=green stars] (0,0) rectangle (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclarepatterninherentlycolored" + }, + pgfdeclareplothandler = { + arguments = {{meta = "macro"}, {meta = "arguments"}, {meta = "configuration"}}, + details = [[ +This command creates a new plot handler that can subsequently be called +using the macro ⟨macro⟩. This macro take the arguments given in +⟨arguments⟩, which can be a list like `# 1# 2` if ⟨macro⟩ should be +invoked with two arguments. Here is a typical example: + + \pgfdeclareplothandler{\myhandler}{#1}{...} + ... + \myhandler{foo} + \pgfplotstreamstart + ... + \pgfplotstreamend + +The ⟨configuration⟩ is used to define the behavior of the handler. It is +a list of key--value pairs, where the following keys are allowed: + +- `start=`⟨code⟩. The ⟨code⟩ will be executed whenever + `\pgfplotstreamstart` is used while the handler ⟨macro⟩ is selected. + Inside the ⟨code⟩, you can use `# 1`, `# 2`, and so on to refer to + the parameters that were given to ⟨macro⟩: + + \pgfdeclareplothandler{\myhandler}{#1}{ + start = Hi #1., + end = Bye #1., + } + \myhandler{foo} + \pgfplotstreamstart + \pgfplotstreamend + \myhandler{bar} + \pgfplotstreamstart + \pgfplotstreamend + +- `end=`⟨code⟩ Works just like `start`. + +- `point=`⟨code⟩. The ⟨code⟩ will be executed whenever + `\pgfplotstreampoint` is used while the handler ⟨macro⟩ is in force. + Inside the ⟨code⟩, you can use `# 1`, `# 2`, and so on to refer to + the arguments give to ⟨macro⟩, while you can use `# # 1` to refer to + the argument given to `\pgfplotstreampoint` itself (this will be the + coordinate). + + \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} + + The ⟨code⟩ will also be called for `\pgfplotstreampointoutlier` when + this command has been configured to `plot` the outliers. + +- `jump=`⟨code⟩ The ⟨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 ⟨code⟩ you can access `# 1` and so + on. + +- `special=`⟨code⟩ Causes ⟨code⟩ to be executed whenever + `\pgfplotstreamspecial``{something}` is used. Inside the ⟨code⟩, you + can access ⟨something⟩ via `# # 1` and the parameters of ⟨macro⟩ as + `# 1`, `# 2`, and so on. + +In addition to the above keys, there exist also "code macro versions" of +them: + +- `point macro=`⟨some macro⟩. Causes `\pgfplotstreampoint` to call + ⟨some macro⟩ directly (actually, `\pgf@plotstreampoint` is set to be + equal to ⟨some macro⟩). Inside the ⟨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 ⟨macro⟩ + that installed the handler. So, ⟨some macro⟩ must take exactly one + argument, namely `# 1`. + +- `special macro=`⟨some macro⟩. As `point macro`, only for specials. + +- `start macro=`⟨some macro⟩. Causes ⟨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 ⟨macro⟩. + +- `end macro=`⟨some macro⟩. As above. + +- `jump macro=`⟨some macro⟩. As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareplothandler" + }, + pgfdeclareplotmark = { + arguments = {{meta = "plot mark name"}, {meta = "code"}}, + details = [[ +Declares a plot mark for later used with the `\pgfuseplotmark` command. + + \pgfdeclareplotmark{my plot mark} + {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke} + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{my plot mark}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareplotmark" + }, + pgfdeclareradialshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "center point"}, + {meta = "color specification"} + }, + details = [[ +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 the circle +will be the color for the maximum dimension given in the ⟨color +specified⟩. This maximum will also be the radius of the circle. If the +⟨center point⟩ is not at the origin, the whole shading inside the circle +(whose size remains exactly the same) will be distorted such that the +given center now has the color specified for 0cm. The effect of ⟨color +list⟩ is the same as for horizontal shadings. + + \pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}% + {rgb(0cm)=(0.9,0,0); + rgb(0.7cm)=(0.7,0,0); + rgb(1cm)=(0.5,0,0); + rgb(1.05cm)=(1,1,1)} + \pgfuseshading{sphere} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareradialshading" + }, + pgfdeclareshape = { + arguments = {{meta = "shape name"}, {meta = "shape specification"}}, + details = [[ +This command declares a new shape named ⟨shape name⟩. The shape name can +later be used in commands like `\pgfnode`. + +The ⟨shape specification⟩ is some TeX code containing calls to special +commands that are only defined inside the ⟨shape specification⟩ +(similarly to commands like `\draw` that are only available inside the +`{tikzpicture}` environment). + +Here is the code of the `coordinate` shape: + + \pgfdeclareshape{coordinate} + { + \savedanchor\centerpoint{% + \pgf@x=.5\wd\pgfnodeparttextbox% + \pgf@y=.5\ht\pgfnodeparttextbox% + \advance\pgf@y by -.5\dp\pgfnodeparttextbox% + } + \anchor{center}{\centerpoint} + \anchorborder{\centerpoint} + } + +The special commands are explained next. In the examples given for the +special commands a new shape will be constructed, which we might call +`simple rectangle`. It should behave like the normal rectangle shape, +only without bothering about the fine details like inner and outer +separations. The skeleton for the shape is the following. + + \pgfdeclareshape{simple rectangle}{ + ... + } + +The following example shows how a shape can be defined that relies +heavily on inheritance: + + \pgfdeclareshape{document}{ + \inheritsavedanchors[from=rectangle] % this is nearly a rectangle + \inheritanchorborder[from=rectangle] + \inheritanchor[from=rectangle]{center} + \inheritanchor[from=rectangle]{north} + \inheritanchor[from=rectangle]{south} + \inheritanchor[from=rectangle]{west} + \inheritanchor[from=rectangle]{east} + % ... and possibly more + \backgroundpath{% this is new + % store lower right in xa/ya and upper right in xb/yb + \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y + \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y + % compute corner of ``flipped page'' + \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter + \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt + % construct main path + \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}} + \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}} + \pgfpathclose + % add little corner + \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}} + \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}} + } + }\hskip-1.2cm + \begin{tikzpicture} + \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark}; + \node[fill=yellow!80!black,draw,ellipse,double] + at ([shift=(-80:3cm)]x) (y) {Use Case}; + + \draw[dashed] (x) -- (y); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareshape" + }, + pgfdeclareverticalshading = { + arguments = { + {delimiters = {"[", "]"}, meta = "color list", optional = true}, + {meta = "shading name"}, + {meta = "shading width"}, + {meta = "color specification"} + }, + details = [[ +Declares a vertical shading named ⟨shading name⟩ of the specified +⟨width⟩. The height of the bar is deduced automatically. The effect of +⟨color list⟩ is the same as for horizontal shadings. + + \pgfdeclareverticalshading{myshadingC} + {4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)} + \pgfuseshading{myshadingC} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdeclareverticalshading" + }, + pgfdecorateaftercode = { + details = [[ +Code executed as ⟨after code⟩, see the description of `\pgfdecorate`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorateaftercode" + }, + pgfdecoratebeforecode = { + details = [[ +Code executed as ⟨before code⟩, see the description of `\pgfdecorate`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratebeforecode" + }, + pgfdecoratecurrentpath = { + arguments = {{meta = "name"}}, + details = [[ +Decorate the preexisting path with the decoration ⟨name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratecurrentpath" + }, + pgfdecoratedangle = { + details = [[ +The angle of the tangent to the decorated path at the *origin* of the +current segment. The transformation matrix applied at the beginning of a +state includes a rotation equivalent to this angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedangle" + }, + pgfdecoratedcompleteddistance = { + details = [[ +The completed distance on the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedcompleteddistance" + }, + pgfdecoratedinputsegmentcompleteddistance = { + details = [[ +The completed distance on the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentcompleteddistance" + }, + pgfdecoratedinputsegmentlength = { + details = [[ +The length of the current input segment of the input path. "Current +input segment" refers to the input segment on which the current point +lies. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentlength" + }, + pgfdecoratedinputsegmentremainingdistance = { + details = [[ +The remaining distance on the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedinputsegmentremainingdistance" + }, + pgfdecoratedpath = { + details = [[ +The (total) input path (that is, the path created by the environment +contents). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedpath" + }, + pgfdecoratedpathlength = { + details = [[ +The length of the input path. If the input path consists of several +input segments, this number is the sum of the lengths of the input +segments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedpathlength" + }, + pgfdecoratedremainingdistance = { + details = [[ +The remaining distance on the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratedremainingdistance" + }, + pgfdecorateexistingpath = { + details = [[ +The preexisting path before the environment was entered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorateexistingpath" + }, + pgfdecoratepath = { + arguments = {{meta = "name"}, {meta = "path commands"}}, + details = [[ +Decorate the path described by ⟨path commands⟩ with the decoration +⟨name⟩. This is equivalent to + + \pgfdecorate{{name}{\pgfdecoratedpathlength} + {\pgfdecoratebeforecode}{\pgfdecorateaftercode}} + // the path commands. + \endpgfdecorate +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecoratepath" + }, + pgfdecorationpath = { + details = [[ +The output path. If the path is used, this macro contains only the last +unused part of the output path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdecorationpath" + }, + pgfdvdeclarestylesheet = { + arguments = {{meta = "name"}, {meta = "keys"}}, + details = [[ +This command executes the ⟨keys⟩ with the path prefix +`/pgf/data visualization/style sheets/`⟨name⟩. The above definition of +the traffic light style sheet could be rewritten as follows: + + \pgfdvdeclarestylesheet{traffic light}{ + 1/.style={green!50!black}, + 2/.style={yellow!90!black}, + 3/.style={red!80!black}, + default style/.style={black} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfdvdeclarestylesheet" + }, + pgferror = { + arguments = {{meta = "message"}}, + details = [[ +Stops the processing of the current document and prints out the +⟨message⟩. In LaTeX, this will be done using `\PackageError`, otherwise +`\errmessage` is used directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgferror" + }, + pgfextra = { + arguments = {{meta = "code"}}, + details = [[ +This command may only be used inside a TikZ path. There it is used like +a normal path operation. The construction of the path is temporarily +suspended and the ⟨code⟩ is executed. Then, the path construction is +resumed. + + \newdimen\mydim + \begin{tikzpicture} + \mydim=1cm + \draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextra" + }, + pgfextractx = { + arguments = {{meta = "dimension"}, {meta = "point"}}, + details = [[ +Sets the TeX-⟨dimension⟩ to the $x$-coordinate of the point. + + \newdimen\mydim + \pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}} + %% \mydim is now 2cm +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextractx" + }, + pgfextracty = { + arguments = {{meta = "dimension"}, {meta = "point"}}, + details = [[ +Like `\pgfextractx`, except for the $y$-coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfextracty" + }, + pgffuncshadingcmyktogray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 4 elements on the stack from CMYK to grayscale. In +combination with the +texttt +textbackslash ifpgfshadingmodelgray conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingcmyktogray" + }, + pgffuncshadingcmyktorgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 4 elements on the stack from CMYK to RGB. In combination +with the +texttt +textbackslash ifpgfshadingmodelrgb conditional this macro can be used to +make functional shading declarations more portable across color models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingcmyktorgb" + }, + pgffuncshadinggraytocmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top element on the stack from grayscale to CMYK. In +combination with the +texttt +textbackslash ifpgfshadingmodelcmyk conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadinggraytocmyk" + }, + pgffuncshadinggraytorgb = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top element on the stack from grayscale to RGB. In +combination with the +texttt +textbackslash ifpgfshadingmodelrgb conditional this macro can be used to +make functional shading declarations more portable across color models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadinggraytorgb" + }, + pgffuncshadingrgbtocmyk = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 3 elements on the stack from RGB to CMYK. In combination +with the +texttt +textbackslash ifpgfshadingmodelcmyk conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingrgbtocmyk" + }, + pgffuncshadingrgbtogray = { + details = [[ +Within the ⟨type 4 function⟩ argument of +texttt +textbackslash pgfdeclarefunctionalshading, this command can be used to +convert the top 3 elements on the stack from RGB to grayscale. In +combination with the +texttt +textbackslash ifpgfshadingmodelgray conditional this macro can be used +to make functional shading declarations more portable across color +models. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgffuncshadingrgbtogray" + }, + pgfgaliasid = { + arguments = {{meta = "1"}, {meta = "2"}}, + details = [[ +Like `\pgfaliasid`, only the alias is set globally. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgaliasid" + }, + pgfgdaddspecificationhook = { + arguments = {{meta = "code"}}, + details = [[ +This command adds the ⟨code⟩ to the code that is executed whenever a +graph drawing scope starts. For instance, the TikZ library +`graphdrawing` uses this macro to add some ⟨code⟩ that will redirect the +`edge` and `edge from parent` path commands to `\pgfgdedge`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdaddspecificationhook" + }, + pgfgdbegineventgroup = { + arguments = {{meta = "parameter"}}, + details = [[ +Starts an event group. This just means that an `Event` of kind `begin` +is created with the given ⟨parameter⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbegineventgroup" + }, + pgfgdbeginlayout = { + details = [[ +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 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 +*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 ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbeginlayout" + }, + pgfgdbeginscope = { + details = [[ +This macro starts a TeX scope inside which the following things happen: + +1. 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. + +2. Inside the TeX scope, nodes are not placed immediately. Rather, + `\pgfpositionnodelater`, see Section ??, is used to call + `InterfaceToDisplay.createVertex` for all nodes created inside the + scope. This will cause them to be put inside some internal table. + +3. Some additional ⟨code⟩ is executed, which has been set using the + following command: + +4. `\pgftransformreset` is called. + +5. The following TeX-if is set to true: + + Will be true inside a graph drawing scope. + +The above has a number of consequences for what can happen inside a +graph drawing scope: + +- Since nodes are not actually created before the end of the scope, + you cannot reference these nodes. Thus, you cannot write + + \tikz [spring layout] { + \node (a) {a}; + \node (b) {b}; + \draw (a) -- (b); + } + + 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). + +- In order to create edges between nodes inside a graph drawing scope, + you need to call the `\pgfgdedge` command, described below. + +Additionally, when TikZ is used, the following things also happen: + +- 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 `graphdrawing` library. + (To be more precise: The keys `new ->` and so on are redefined so + that they call `\pgfgdedge` instead of creating an edge. + +- The `edge` path command is modified so that it also calls + `\pgfgdedge` instead of immediately creating any edges. + +- The `edge from parent` path command is modified so that is also + calls `\pgfgdedge`. + +- 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". + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdbeginscope" + }, + pgfgdedge = { + arguments = { + {meta = "first node"}, + {meta = "second node"}, + {meta = "edge direction"}, + {meta = "edge options"}, + {meta = "edge nodes"} + }, + details = [[ +This command is used to tell the graph drawing engine that there is an +edge between ⟨first node⟩ and ⟨second node⟩ in your graph. The "kind" of +connection is indicated by ⟨direction⟩, which may be one of the +following: + +- `->` indicates a directed edge (also known as an arc) from ⟨first + node⟩ to ⟨second node⟩. + +- `–` indicates an undirected edge between ⟨first node⟩ and ⟨second + node⟩, + +- `<-` indicates a directed edge from ⟨second node⟩ to ⟨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. + +- `<->` indicates a bi-directed edge between ⟨first node⟩ and ⟨second + node⟩. + +- `-!-` indicates that the edge from ⟨first node⟩ to ⟨second node⟩ is + "missing". + +Note that in all cases, the syntactic digraph will contain an arc from +⟨first node⟩ to ⟨second node⟩, regardless of the value of ⟨direction⟩. +The ⟨direction⟩ is "just" a "semantic annotation". + +The parameters ⟨edge options⟩ and ⟨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 ⟨first node⟩ and ⟨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 ⟨edge options⟩ and ⟨edge nodes⟩ store such options. + +Let us start with ⟨edge options⟩. This parameter should be set to a list +of key--value pairs like + + /tikz/.cd, color=red, very thick, orient=down + +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 *before* the algorithm starts, but +the options as a whole are usually only executed during the drawing of +the edges, which is *after* the algorithm has finished. To overcome this +problem, the following happens: + +The options in ⟨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 +⟨edge options⟩ are available once more and then they are executed +normally. + +Note that when the options in ⟨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 ⟨edge nodes⟩ is some "auxiliary" text that is simply stored +away and later directed to `\pgfgdedgecallback`. This is used for +instance by TikZ to store its node labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdedge" + }, + pgfgdendeventgroup = { + details = [[ +Ends an event group. This is done by adding an event of kind `end` +without any parameters to the event string. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendeventgroup" + }, + pgfgdendlayout = { + details = [[ +This command ends the TeX scope of the current layout. Once closed, no +nodes or edges can be added to a layout. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendlayout" + }, + pgfgdendscope = { + details = [[ +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: + +1. The special treatment of newly created boxes is ended. Nodes are + once more created normally. + +2. The effects of the ⟨code⟩ that was inserted via the specification + hook command also ends (provided it had no global effects). + +3. 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 ?? + below. + +4. 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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdendscope" + }, + pgfgdevent = { + arguments = {{meta = "kind"}, {meta = "parameter"}}, + details = [[ +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 ⟨kind⟩ and the `parameters` field to ⟨parameter⟩. You must be inside +a graph drawing scope to use this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdevent" + }, + pgfgdeventgroup = { + arguments = {{meta = "parameters"}}, + details = [[ +Starts an event group just like `\pgfgdbegineventgroup`, but adds a +corresponding closing `end` event at the end of the current TeX group +(using `\aftergroup`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdeventgroup" + }, + pgfgdsetedgecallback = { + arguments = {{meta = "macro"}}, + details = [[ +This command allows you to change the ⟨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 ⟨macro⟩ will be called once for +each edge with the following parameters: + +> ⟨macro⟩`{first node}``{second node}``{direction}``{edge options}``{edge nodes}` +> `{algorithm-generated options}``{bend information}``{animations}` + +The first five parameters are the original values that were passed down +to the `\pgfgdedge` command. + +The ⟨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 ⟨bend information⟩ contains algorithmically-computed +information concerning how the edge should bend. This will be a text +like `(10pt,20pt)–(30pt,40pt)` in TikZ-syntax and may include the path +commands `–`, `..` (followed by Bézier coordinates), and `–cycle`. + +The parameter ⟨animations⟩ contains algorithmically-generated animation +commands (calls to `\pgfanimateattribute`. The `whom` will be set to +`pgf@gd`. + +The default ⟨macro⟩ simply draws a line between the nodes. When the +`graphdrawing` library of the TikZ layer is loaded, a more fancy ⟨macro⟩ +is used that takes all of the parameters into account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetedgecallback" + }, + pgfgdsetlatenodeoption = { + arguments = {{meta = "node name"}}, + details = [[ +This command can only be called when the node named ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetlatenodeoption" + }, + pgfgdsetrequestcallback = { + arguments = {{meta = "macro"}}, + details = [[ +This command sets up ⟨macro⟩ as the macro that is called whenever a +layout key "requests" that a layout and, possibly, a graph drawing scope +is opened. When ⟨macro⟩ is called, it gets two parameters, the ⟨begin +code⟩ and the ⟨end code⟩. In addition to whatever setup the ⟨macro⟩ +would like to do, it should execute the ⟨begin code⟩ at the beginning of +a TeX scope (the code will open graph drawing and layout scopes) and the +⟨end code⟩ at the end of the same TeX scope. + +The need for this slightly strange macro arises from the fact that in +TikZ we often write things like `[spring layout,node sep=2cm]`. The +point is that when the `spring layout` key is executed, we do *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, +TikZ sets up a special ⟨macro⟩ that "delays" the execution of the ⟨begin +code⟩ until the end of the opening of the next scope. + +Because of this, in TikZ layout keys can only be used as an option when +a TikZ 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: + + \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} + +You can *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{tikzpicture} + \scoped [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; + \end{tikzpicture} + +Naturally, the above could have been written more succinctly as + + \tikz [tree layout] + \node {root} + child { node {left child} } + child { node {right child} }; + +Or even more succinctly: + + \tikz \graph [tree layout] { root -- {left child, right child} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsetrequestcallback" + }, + pgfgdsubgraphnode = { + arguments = {{meta = "name"}, {meta = "node options"}, {meta = "node text"}}, + details = [[ +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 available +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 PGF 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 ⟨name⟩ is the node name by which you can refer to this node in the +following. The ⟨node options⟩ are normal PGF options (like `red` or +`draw` or `circle`) that will influence the appearance when it is +created later on. The ⟨node text⟩ is the text that will be passed to +`\pgfnode` upon creation of the node. + +See `InterfaceToDisplay.pushSubgraphVertex` for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgdsubgraphnode" + }, + pgfgetlastxy = { + arguments = {{meta = "macro for $x$"}, {meta = "macro for $y$"}}, + details = [[ +Stores the most recently used $(x,y)$ coordinates into two macros. + + \pgfpoint{2cm}{4cm} + \pgfgetlastxy{\macrox}{\macroy} + Macro $x$ is `\macrox' and macro $y$ is `\macroy'. + +Since $(x,y)$ coordinates are usually assigned globally, it is safe to +use this command after path operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgetlastxy" + }, + pgfgettransform = { + arguments = {{meta = "macro"}}, + details = [[ +This command will (locally) define ⟨macro⟩ to a representation of the +current coordinate transformation matrix. This matrix can later on be +reinstalled using `\pgfsettransform`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgettransform" + }, + pgfgettransformentries = { + arguments = { + {meta = "macro for a"}, + {meta = "macro for b"}, + {meta = "macro for c"}, + {meta = "macro for d"}, + {meta = "macro for shift x"}, + {meta = "macro for shift y"} + }, + details = [[ +This command is similar to `\pgfgettransform` except that it stores the +current coordinate transformation matrix in a set of six macros. + +The matrix can later on be reinstalled using `\pgfsettransformentries`. +Furthermore, all these macros (or just a few of them) can be used as +arguments for `\pgftransformcm`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfgettransformentries" + }, + pgfhorizontaltransformationadjustment = { + details = [[ +When you scale the length of a horizontal line by this factor in the +current transformation, you compensate for the scaling. Formally, it is +$1/\\texttt{\textbackslash mathit\{transform\}(1,0)\textbackslash }_2$, +where $\mathit{transform}$ applies the current transformations matrix to +the given number. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (2,2); + \begin{scope}[xscale=2,thick] + \draw [red] (1,1) -- ++(1,0); + + \pgftransformationadjustments + \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); + \end{scope} + \end{tikzpicture} + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (2,2); + \begin{scope}[xscale=2,thick,rotate=90] + \draw [red] (1,1) -- ++(1,0); + + \pgftransformationadjustments + \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfhorizontaltransformationadjustment" + }, + pgfidrefnextuse = { + arguments = {{meta = "macro"}, {meta = "name"}}, + details = [[ +This command assigns a system layer identifier (the identifier returned +by `\pgfsys@new@id`) to the ⟨macro⟩, namely the one that will be used +the *next* time `\pgfuseid` is used. You use this command for "forward +referencing". + +A typical use case is the following: A key like `whom` for animations +uses this command to get the system identifier that will be used for a +future object. Then, this identifier can be passed to system layer +commands like `\pgfsys@animation@whom`. + +Note that the "next" use need not be on the same page (or there may not +even be any use at all), in which case the reference will not refer to +any object. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfidrefnextuse" + }, + pgfidrefprevuse = { + arguments = {{meta = "macro"}, {meta = "name"}}, + details = [[ +Works like `\pgfidrefnextuse`, only it references the most recent +*previous* use of the ⟨name⟩. As for `\pgfidrefnextuse`, the most recent +use need not be on the same page. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfidrefprevuse" + }, + pgfifidreferenced = { + arguments = {{meta = "name"}, {meta = "then code"}, {meta = "else code"}}, + details = [[ +If ⟨name⟩ has been referenced, ⟨then code⟩ is executed, otherwise ⟨else +code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfifidreferenced" + }, + pgfimage = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "filename"} + }, + details = [[ +Declares the image under the name `pgflastimage` and immediately uses +it. You can "save" the image for later usage by invoking +`\pgfaliasimage` on `pgflastimage`. + + \begin{colormixin}{25!white} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base] + {\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base] + {\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base] + {\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + \end{colormixin} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfimage" + }, + pgfintersectionofpaths = { + arguments = {{meta = "path 1"}, {meta = "path 2"}}, + details = [[ +This command finds the intersection points on the paths ⟨path 1⟩ and +⟨path 2⟩. The number of intersection points ("solutions") that are found +will be stored, and each point can be accessed afterward. The code for +⟨path 1⟩ and ⟨path 2⟩ is executed within a TeX group and so can contain +transformations (which will be in addition to any existing +transformations). The code should not use the path in any way, unless +the path is saved first and restored afterward. PGF will regard +solutions as "a bit special", in that the points returned will be +"absolute" and unaffected by any further transformations. + + \begin{pgfpicture} + \pgfintersectionofpaths + { + \pgfpathellipse{\pgfpointxy{0}{0}}{\pgfpointxy{1}{0}}{\pgfpointxy{0}{2}} + \pgfgetpath\temppath + \pgfusepath{stroke} + \pgfsetpath\temppath + } + { + \pgftransformrotate{-30} + \pgfpathrectangle{\pgfpointorigin}{\pgfpointxy{2}{2}} + \pgfgetpath\temppath + \pgfusepath{stroke} + \pgfsetpath\temppath + } + \foreach \s in {1,...,\pgfintersectionsolutions} + {\pgfpathcircle{\pgfpointintersectionsolution{\s}}{2pt}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionofpaths" + }, + pgfintersectionsolutions = { + details = [[ +After using the `\pgfintersectionofpaths` command, this TeX-macro will +indicate the number of solutions found. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsolutions" + }, + pgfintersectionsortbyfirstpath = { + details = [[ +Using this command will mean the solutions will be sorted along ⟨path +1⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsortbyfirstpath" + }, + pgfintersectionsortbysecondpath = { + details = [[ +Using this command will mean the solutions will be sorted along ⟨path +2⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfintersectionsortbysecondpath" + }, + pgfkeys = { + arguments = {{meta = "key list"}}, + details = [[ +The ⟨key list⟩ should be a list of key--value pairs, separated by +commas. A key--value pair can have the following two forms: +⟨key⟩`=`⟨value⟩ or just ⟨key⟩. Any spaces around the ⟨key⟩ or around the +⟨value⟩ are removed. It is permissible to surround both the ⟨key⟩ or the +⟨value⟩ in curly braces, which are also removed. Especially putting the +⟨value⟩ in curly braces needs to be done quite often, namely whenever +the ⟨value⟩ contains an equal-sign or a comma. + +The key--value pairs in the list are handled in the order they appear. +How this handling is done, exactly, is described in the rest of this +section. + +If a ⟨key⟩ is a partial key, the current value of the default path is +prefixed to the ⟨key⟩ and this "upgraded" key is then used. The default +path is just the root path `/` when the first key is handled, but it may +change later on. At the end of the command, the default path is reset to +the value it had before this command was executed. + +Calls of this command may be nested. Thus, it is permissible to call +`\pgfkeys` inside the code that is executed for a key. Since the default +path is restored after a call of `\pgfkeys`, the default path will not +change when you call `\pgfkeys` while executing code for a key (which is +exactly what you want). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeys" + }, + pgfkeysactivatefamilies = { + arguments = {{meta = "family list"}, {meta = "deactivate macro name"}}, + details = [[ +Activates each family in ⟨family list⟩ and creates a macro ⟨deactivate +macro name⟩ which deactivates each family in ⟨family list⟩. + + \pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename} + \pgfkeysfiltered{foo,bar} + \deactivatename +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamilies" + }, + pgfkeysactivatefamiliesandfilteroptions = { + arguments = {{meta = "family list"}, {meta = "key--value-list"}}, + details = [[ +A simple shortcut macro which activates any family in the comma +separated `{family list}`, invokes `\pgfkeysfiltered`⟨key--value-list⟩ +and deactivates the families afterwards. + +Please note that you will need to install a family key filter, otherwise +family activation has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamiliesandfilteroptions" + }, + pgfkeysactivatefamily = { + arguments = {{meta = "family name"}}, + details = [[ +Equivalent to `\pgfkeys{`⟨family name⟩`/.activate family}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatefamily" + }, + pgfkeysactivatesinglefamilyandfilteroptions = { + arguments = {{meta = "family name"}, {meta = "key--value-list"}}, + details = [[ +A shortcut macro which activates a single family and invokes +`\pgfkeysfiltered`. + +Please note that you will need to install a family key filter, otherwise +family activation has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysactivatesinglefamilyandfilteroptions" + }, + pgfkeysalso = { + arguments = {{meta = "key list"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalso" + }, + pgfkeysalsofiltered = { + arguments = {{meta = "key--value-list"}}, + details = [[ +This command works as `\pgfkeysfiltered`, but it does not change the +current default path. See the documentation of `\pgfkeysalso` for more +details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofiltered" + }, + pgfkeysalsofilteredfrom = { + arguments = {{meta = "macro"}}, + details = [[ +A variant of `\pgfkeysalsofiltered` which loads its key list from +`{macro}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofilteredfrom" + }, + pgfkeysalsofrom = { + arguments = {{meta = "macro"}}, + details = [[ +A variant of `\pgfkeysalso` which loads its key list from `{macro}`. + +It is useful in conjunction with the +`/pgf/key filter handlers/append filtered to=`⟨macro⟩ handler. + +The following example uses the same settings as in the intro section ??. + + \pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} + \def\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} + + Remaining: `\remainingoptions'. + \pgfkeysalsofrom{\remainingoptions} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysalsofrom" + }, + pgfkeysdeactivatefamily = { + arguments = {{meta = "family name"}}, + details = [[ +Equivalent to `\pgfkeys{`⟨family name⟩`/.deactivate family}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdeactivatefamily" + }, + pgfkeysdef = { + arguments = {{meta = "key"}, {meta = "code"}}, + details = [[ +This command temporarily defines a TeX-macro with the argument list +`# 1\pgfeov` and then lets ⟨key⟩`/.@cmd` be equal to this macro. The net +effect of all this is that you have then set up code for the key ⟨key⟩ +so that when you write `\pgfkeys{`⟨key⟩`=`⟨value⟩`}`, then the ⟨code⟩ is +executed with all occurrences of `# 1` in ⟨code⟩ being replaced by +⟨value⟩. (This behavior is quite similar to the `\define@key` command of +`keyval` and `xkeyval`). + + \pgfkeysdef{/my key}{#1, #1.} + \pgfkeys{/my key=hello} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdef" + }, + pgfkeysdefargs = { + arguments = {{meta = "key"}, {meta = "argument pattern"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdefnargs`, but it allows you to provide +an arbitrary ⟨argument pattern⟩ rather than just a number of arguments. + + \pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}} + \pgfkeys{/my key=hello+world} + + |\a| is \a, |\b| is \b. + +Note that `\pgfkeysdefnargs` is *better* when it comes to simple +argument *counts*[1]. + +[1] When the resulting keys are used, the `defnargs` variant allows +spaces between arguments whereas the `defargs` variant does not; it +considers the spaces as part of the argument. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdefargs" + }, + pgfkeysdefnargs = { + arguments = {{meta = "key"}, {meta = "argument count"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdef`, but it allows you to provide an +arbitrary ⟨argument count⟩ between $0$ and $9$ (inclusive). + + \pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}} + \pgfkeys{/my key= + {hello} + {world}} + + |\a| is `\a', |\b| is `\b'. + +The resulting key will expect exactly `{argument count}` arguments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysdefnargs" + }, + pgfkeysedef = { + arguments = {{meta = "key"}, {meta = "code"}}, + details = [[ +This command works like `\pgfkeysdef`, but it uses `\edef` rather than +`\def` when defining the key macro. If you do not know the difference +between the two, then you will not need this command; and if you know +the difference, then you will know when you need this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedef" + }, + pgfkeysedefargs = { + arguments = {{meta = "key"}, {meta = "argument pattern"}, {meta = "code"}}, + details = [[ +The `\edef` version of `\pgfkeysdefargs`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedefargs" + }, + pgfkeysedefnargs = { + arguments = {{meta = "key"}, {meta = "argument count"}, {meta = "code"}}, + details = [[ +The `\edef` version of `\pgfkeysdefnargs`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysedefnargs" + }, + pgfkeysevalkeyfilterwith = { + arguments = {{meta = "full key"}, {literal = "="}, {meta = "filter arguments"}}, + details = [[ +Evaluates a fully qualified key filter ⟨full key⟩ with argument(s) +⟨filter arguments⟩. + + \pgfkeysevalkeyfilterwith{/pgf/key filters/equals=/tikz} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysevalkeyfilterwith" + }, + pgfkeysfiltered = { + arguments = {{meta = "key--value-list"}}, + details = [[ +Processes all options in exactly the same way as +`\pgfkeys``{key–value-list}`, but a key filter is considered as soon as +key identification is complete. + +The key filter tells `\pgfkeysfiltered` whether it should continue to +apply the current option (return value is 'true') or whether something +different shall be done (filter returns 'false'). + +There is exactly one key filter in effect, and it is installed by the +`.install key filter` handler or by `\pgfkeysinstallkeyfilter`. + +If the key filter returns 'false', a unique key filter handler gets +control. This handler is installed by the `.install key filter handler` +method and has access to the key's full name, value and (possibly) path. + +Key filtering applies to any (possibly nested) call to `\pgfkeys`, +`\pgfkeysalso`, `\pgfqkeys` and `\pgfqkeysalso` during the evaluation of +`{key–value-list}`. It does *not* apply to routines like +`\pgfkeyssetvalue` or `\pgfkeysgetvalue`. Furthermore, keys belonging to +`/errors` are always processed. Key filtering routines can't be nested: +you can't combine different key filters automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysfiltered" + }, + pgfkeysgetfamily = { + arguments = {{meta = "full key"}, {meta = "resultmacro"}}, + details = [[ +Returns the family associated to a ⟨full key⟩ into macro ⟨resultmacro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysgetfamily" + }, + pgfkeysgetvalue = { + arguments = {{meta = "full key"}, {meta = "macro"}}, + details = [[ +Retrieves the tokens stored in the ⟨full key⟩ and lets ⟨macro⟩ be equal +to these tokens. If the key has not been set, the ⟨macro⟩ will be equal +to `\relax`. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysgetvalue{/my family/my key}{\helloworld} + \helloworld +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysgetvalue" + }, + pgfkeysifdefined = { + arguments = {{meta = "full key"}, {meta = "if"}, {meta = "else"}}, + details = [[ +Checks whether this key was previously set using either +`\pgfkeyssetvalue` or `\pgfkeyslet`. If so, the code in ⟨if⟩ is +executed, otherwise the code in ⟨else⟩. + +This command will use eTeX's `\ifcsname` command, if available, for +efficiency. This means, however, that it may behave differently for +TeX and for eTeX when you set keys to `\relax`. For this reason you +should not do so. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysifdefined{/my family/my key}{yes}{no} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysifdefined" + }, + pgfkeysiffamilydefined = { + arguments = {{meta = "family"}, {meta = "true case"}, {meta = "false case"}}, + details = [[ +Checks whether the full key ⟨family⟩ is a family and executes either +⟨true case⟩ or ⟨false case⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysiffamilydefined" + }, + pgfkeysinstallkeyfilter = { + arguments = {{meta = "full key"}, {meta = "optional arguments"}}, + details = [[ +The command `\pgfkeysinstallkeyfilter{`⟨full key⟩`}{`⟨optional +arguments⟩`}` has the same effect as `\pgfkeys{`⟨full +key⟩`/.install key filter={`⟨optional arguments⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysinstallkeyfilter" + }, + pgfkeysinstallkeyfilterhandler = { + arguments = {{meta = "full key"}, {meta = "optional arguments"}}, + details = [[ +The command `\pgfkeysinstallkeyfilterhandler{`⟨full key⟩`}{`⟨optional +arguments⟩`}` has the same effect as `\pgfkeys{`⟨full +key⟩`/.install key filter handler={`⟨optional arguments⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysinstallkeyfilterhandler" + }, + pgfkeysisfamilyactive = { + arguments = {{meta = "family"}}, + details = [[ +Sets the TeX-boolean `\ifpgfkeysfiltercontinue` to whether ⟨family⟩ is +active or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysisfamilyactive" + }, + pgfkeyslet = { + arguments = {{meta = "full key"}, {meta = "macro"}}, + details = [[ +Performs a `\let` statement so the ⟨full key⟩ points to the contents of +⟨macro⟩. + + \def\helloworld{Hello, world!} + \pgfkeyslet{/my family/my key}{\helloworld} + \pgfkeysvalueof{/my family/my key} + +You should never let a key be equal to `\relax`. Such a key may or may +not be indistinguishable from an undefined key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyslet" + }, + pgfkeyssavekeyfilterstateto = { + arguments = {{meta = "macro"}}, + details = [[ +Creates `{macro}` which contains commands to re-activate the current key +filter and key filter handler. It can be used to temporarily switch the +key filter. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssavekeyfilterstateto" + }, + pgfkeyssetevalue = { + arguments = {{meta = "full key"}, {meta = "token text"}}, + details = [[ +The `\edef` version of `\pgfkeyssetvalue`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetevalue" + }, + pgfkeyssetfamily = { + arguments = {{meta = "full key"}, {meta = "family"}}, + details = [[ +The command `\pgfkeyssetfamily``{full key}``{family}` has the same +effect as `\pgfkeys{`⟨full key⟩`/.belongs to family=``{family}``}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetfamily" + }, + pgfkeyssetvalue = { + arguments = {{meta = "full key"}, {meta = "token text"}}, + details = [[ +Stores the ⟨token text⟩ in the ⟨full key⟩. The ⟨full key⟩ may not be a +partial key, so no default-path-adding is done. The ⟨token text⟩ can be +arbitrary tokens and may even contain things like `# ` or unbalanced +TeX-ifs. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysvalueof{/my family/my key} + +The setting of a key is always local to the current TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeyssetvalue" + }, + pgfkeysvalueof = { + arguments = {{meta = "full key"}}, + details = [[ +Inserts the value stored in ⟨full key⟩ at the current position into the +text. + + \pgfkeyssetvalue{/my family/my key}{Hello, world!} + \pgfkeysvalueof{/my family/my key} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfkeysvalueof" + }, + pgflibraryfpuifactive = { + arguments = {{meta = "true-code"}, {meta = "false-code"}}, + details = [[ +This command can be used to execute either ⟨true-code⟩ or ⟨false-code⟩, +depending on whether the FPU has been activated or not. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflibraryfpuifactive" + }, + pgflindenmayersystem = { + arguments = {{meta = "name"}, {meta = "axiom"}, {meta = "order"}}, + details = [[ +Runs the L-system called ⟨name⟩ using the input string ⟨axiom⟩ for +⟨order⟩ iterations. 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. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \pgfset{lindenmayer system/.cd, angle=60, step=2pt} + \foreach \x/\y in {0cm/1cm, 1.5cm/1.5cm, 2.5cm/0.5cm, 1cm/0cm}{ + \pgftransformshift{\pgfqpoint{\x}{\y}} + \pgfpathmoveto{\pgfpointorigin} + \pgflindenmayersystem{Koch curve}{F++F++F}{2} + \pgfusepath{stroke} + } + \end{tikzpicture} + +Note that it is perfectly feasible for an L-system to define special +symbols which perform the move-to and use-path operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflindenmayersystem" + }, + pgflowlevel = { + arguments = {{meta = "transformation code"}}, + details = [[ +This command concatenates the canvas transformation matrix with the +coordinate transformation specified by ⟨transformation code⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevel{\pgftransformscale{5}} + \draw (0,0) -- (0.4,.2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevel" + }, + pgflowlevelobj = { + arguments = {{meta = "transformation code"}, {meta = "code"}}, + details = [[ +This command creates a local `{pgfscope}`. Inside this scope, +`\pgflowlevel` is first called with the argument ⟨transformation code⟩, +then the ⟨code⟩ is inserted. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgflowlevelobj{\pgftransformscale{5}} {\draw (0,0) -- (0.4,.2);} + \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevelobj" + }, + pgflowlevelsynccm = { + details = [[ +This command concatenates the canvas transformation matrix with the +current coordinate transformation matrix. Afterward, the coordinate +transformation matrix is reset. + +The effect of this command is to "synchronize" the coordinate +transformation matrix and the canvas transformation matrix. All +transformations that were previously applied by the coordinate +transformations matrix are now applied by the canvas transformation +matrix. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{1pt} + \pgftransformscale{5} + \draw (0,0) -- (0.4,.2); + \pgftransformxshift{0.2cm} + \pgflowlevelsynccm + \draw[red] (0,0) -- (0.4,.2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflowlevelsynccm" + }, + pgflsystemcurrentleftangle = { + details = [[ +The angle the L-system will turn when it turns left. The value stored in +this macro may be changed if `\pgflsystemrandomizeleftangle` is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentleftangle" + }, + pgflsystemcurrentrightangle = { + details = [[ +The angle the L-system will turn when it turns right. The value stored +in this macro may be changed if `\pgflsystemrandomizerightangle` is +used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentrightangle" + }, + pgflsystemcurrentstep = { + details = [[ +The current "step" of the L-system (i.e., how far the system will move +forward if required). This is initially set to the value in the +TeX-dimensions `\pgflsystemstep`, but the actual value may be changed if +`\pgflsystemrandomizestep` is used (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemcurrentstep" + }, + pgflsystemdrawforward = { + details = [[ +Move forward in the current direction, by `\pgflsystemcurrentstep`, +drawing a line in the process. This macro calls +`\pgflsystemrandomizestep`. Internally, PGF simply shifts the +transformation matrix in the positive direction of the current +(transformed) x-axis by `\pgflsystemstep` and then executes a line-to to +the (newly transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemdrawforward" + }, + pgflsystemmoveforward = { + details = [[ +Move forward in the current direction, by `\pgflsystemcurrentstep`, +without drawing a line. This macro calls `\pgflsystemrandomizestep`. PGF +executes a transformation as above, but executes a move-to to the (newly +transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemmoveforward" + }, + pgflsystemrandomizeleftangle = { + details = [[ +Randomizes the value in `\pgflsystemcurrentleftangle` according to the +value of the `randomize angle percent` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizeleftangle" + }, + pgflsystemrandomizerightangle = { + details = [[ +Randomizes the value in `\pgflsystemcurrentrightangle` according to the +value of the `randomize angle` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizerightangle" + }, + pgflsystemrandomizestep = { + details = [[ +Randomizes the value in `\pgflsystemcurrentstep` according to the +current value of the key `randomize step percent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrandomizestep" + }, + pgflsystemrestorestate = { + details = [[ +Restore the last saved position and orientation. Internally, PGF closes +a TeX-group, restoring the transformation matrix of the outer scope, and +a move-to command is executed to the (transformed) origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemrestorestate" + }, + pgflsystemsavestate = { + details = [[ +Save the current position and orientation. Internally, PGF simply starts +a new TeX-group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemsavestate" + }, + pgflsystemturnleft = { + details = [[ +Turn left by `\pgflsystemcurrentleftangle`. Internally, PGF simply +rotates the transformation matrix. This macro calls +`\pgflsystemrandomizeleftangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemturnleft" + }, + pgflsystemturnright = { + details = [[ +Turn right by `\pgflsystemcurrentrightangle`. Internally, PGF simply +rotates the transformation matrix. This macro calls +`\pgflsystemrandomizerightangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgflsystemturnright" + }, + pgfmathaddtocount = { + arguments = {{meta = "count register"}, {meta = "expression"}}, + details = [[ +Adds the *truncated* value of ⟨expression⟩ to the TeX ⟨count register⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtocount" + }, + pgfmathaddtocounter = { + arguments = {{meta = "counter"}, {meta = "expression"}}, + details = [[ +Adds the *truncated* value of ⟨expression⟩ to ⟨counter⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtocounter" + }, + pgfmathaddtolength = { + arguments = {{meta = "register"}, {meta = "expression"}}, + details = [[ +Adds the value of ⟨expression⟩ to the TeX ⟨register⟩. All of the special +consideration mentioned for `\pgfmathsetlength` also apply here in the +same way. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathaddtolength" + }, + pgfmathanglebetweenlines = { + arguments = { + {meta = "$p_1$"}, + {meta = "$q_1$"}, + {meta = "$p_2$"}, + {meta = "$q_2$"} + }, + details = [[ +Returns the clockwise angle between a line going through $p_1$ and $q_1$ +and a line going through $p_2$ and $q_2$. + + \pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} + {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathanglebetweenlines" + }, + pgfmathanglebetweenpoints = { + arguments = {{meta = "p"}, {meta = "q"}}, + details = [[ +Returns the angle of a line from ⟨p⟩ to ⟨q⟩ relative to a line going +straight right from ⟨p⟩. + + \pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathanglebetweenpoints" + }, + pgfmathapproxequalto = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` 1.0 if $\rvert ⟨x⟩ - ⟨y⟩ \lvert < + 0.0001$, but 0.0 otherwise. As a side-effect, the global boolean +`\ifpgfmathcomparison` will be set accordingly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathapproxequalto" + }, + pgfmathbasetoBase = { + arguments = { + {meta = "macro"}, + {meta = "number"}, + {meta = "base-1"}, + {meta = "base-2"} + }, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base-1⟩ +to base ⟨base-2⟩. Alphabetic digits in ⟨number⟩ can be upper or lower +case, but any resulting alphabetic digits are in *upper case*. + + \pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetoBase" + }, + pgfmathbasetobase = { + arguments = { + {meta = "macro"}, + {meta = "number"}, + {meta = "base-1"}, + {meta = "base-2"} + }, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base-1⟩ +to base ⟨base-2⟩. Alphabetic digits in ⟨number⟩ can be upper or lower +case, but any resulting alphabetic digits are in *lower case*. + + \pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetobase" + }, + pgfmathbasetodec = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base ⟨base⟩ to +base 10. Alphabetic digits can be upper or lower case. + + \pgfmathbasetodec\mynumber{107f}{16} \mynumber + +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). + + \pgfmathbasetodec\mynumber{33FC}{20} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathbasetodec" + }, + pgfmathdeclarefunction = { + arguments = { + {literal = "*"}, + {meta = "function name"}, + {meta = "number of arguments"}, + {meta = "code"} + }, + details = [[ +This will set up the parser to recognize a function called ⟨name⟩. The +name of the function can consist of, uppercase or lowercase letters, +numbers or the underscore `_ `. In line with many programming languages, +a function name cannot begin with a number or contain any spaces. The +function may not have been declared earlier, unless the optional star +(`*`) is provided, which forces an "overwriting" of the function by the +new function. Note that you *should never change the arity of standard +functions* and you should normally use `\pgfmathredeclarefunction`, +which does not allow you to do anything wrong here. + +The ⟨number of arguments⟩ can be any positive integer, zero, or the +value `...`, which indicates a variable number of arguments. PGF treats +constants, such as `pi` and `e`, as functions with zero arguments. +Functions with more than nine arguments or with a variable number of +arguments are a "bit special" and are discussed below. + +The effect of ⟨code⟩ should be to set the macro `\pgfmathresult` to the +correct value (namely to the result of the computation without units). +Furthermore, the function should have no other side effects, that is, it +should not change any global values. As an example, consider the +creation of a new function `double`, which takes one argument, and +returns the value of that argument times two. + + \makeatletter + \pgfmathdeclarefunction{double}{1}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by2\relax + \pgfmathreturn\pgf@x + \endgroup + } + \makeatother + \pgfmathparse{double(44.3)}\pgfmathresult + +The macro `\pgfmathreturn`⟨tokens⟩ must be directly followed by an +`\endgroup` and will save the result of the computation, by defining +`\pgfmathresult` as the expansion of ⟨tokens⟩ (without units) outside +the group, so ⟨tokens⟩ must be something that can be assigned to a +dimension register. + +Alternatively, the `\pgfmathsmuggle`⟨macro⟩ can be used. This must also +be directly followed by an `\endgroup` and will simply "smuggle" the +definition of ⟨macro⟩ outside the TeX-group. + +By performing computations within a TeX-group, PGF registers such as +`\pgf@x`, `\pgf@y` and `\c@pgf@counta`, `\c@pgfcountb`, and so forth, +can be used at will. + +Beyond setting up the parser, this command also defines two macros which +provide access to the function independently of the parser: + +- `\pgfmath`⟨function name⟩ + + This macro will provide a "public" interface for the function + ⟨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 macro: + +- `\pgfmath`⟨function name⟩`@` + + 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 ⟨code⟩, + but need not be self-contained. + +For functions that are declared with less than ten arguments, the public +macro is defined in the same way as normal TeX macros using, for +example, `\def\pgfmathNoArgs{`⟨code⟩`}` for a function with no +arguments, or `\def\pgfmathThreeArgs# 1# 2# 3{`⟨code⟩`}` for a function +with three arguments. The private macro is defined in the same way, and +each argument can therefore be accessed in ⟨code⟩ using `# 1`, `# 2` and +so on. + +For functions with more than nine arguments, or functions with a +variable number of arguments, these macros are only defined as taking +*one* argument. The public macro expects its arguments to be comma +separated, for example, `\pgfmathVariableArgs{1.1,3.5,-1.5,2.6}`. Each +argument is parsed and passed on to the private macro as follows: +`\pgfmathVariableArgs@{{1.1}{3.5}{-1.5}{2.6}}`. 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: 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdeclarefunction" + }, + pgfmathdeclarerandomlist = { + arguments = {{meta = "list name"}}, + details = [[ +This creates a list of items with the name ⟨list name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdeclarerandomlist" + }, + pgfmathdectoBase = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base 10 to +base ⟨base⟩. Any resulting alphabetic digits are in *upper case*. + + \pgfmathdectoBase\mynumber{65535}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdectoBase" + }, + pgfmathdectobase = { + arguments = {{meta = "macro"}, {meta = "number"}, {meta = "base"}}, + details = [[ +Defines ⟨macro⟩ as the result of converting ⟨number⟩ from base 10 to +base ⟨base⟩. Any resulting alphabetic digits are in *lower case*. + + \pgfmathdectobase\mynumber{65535}{16} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathdectobase" + }, + pgfmathfloat = { + arguments = {{meta = "op"}}, + details = [[ +Methods of this form constitute the replacement operations where ⟨op⟩ +can be any of the well-known math operations. + +Thus, `\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 *expected* to be floating point numbers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloat" + }, + pgfmathfloatabserror = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatabserror" + }, + pgfmathfloatcreate = { + arguments = {{meta = "flags"}, {meta = "mantissa"}, {meta = "exponent"}}, + details = [[ +Defines `\pgfmathresult` as the floating point number encoded by +⟨flags⟩, ⟨mantissa⟩ and ⟨exponent⟩. + +All arguments are characters and will be expanded using `\edef`. + + \pgfmathfloatcreate{1}{1.0}{327} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatcreate" + }, + pgfmathfloatgetexponent = { + arguments = {{meta = "x"}, {meta = "exponentcount"}}, + details = [[ +Extracts the exponent of ⟨x⟩ into the count register ⟨exponentcount⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetexponent" + }, + pgfmathfloatgetflags = { + arguments = {{meta = "x"}, {meta = "flagscount"}}, + details = [[ +Extracts the flags of ⟨x⟩ into the count register ⟨flagscount⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetflags" + }, + pgfmathfloatgetflagstomacro = { + arguments = {{meta = "x"}, {meta = "macro"}}, + details = [[ +Extracts the flags of ⟨x⟩ into the macro ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetflagstomacro" + }, + pgfmathfloatgetmantissa = { + arguments = {{meta = "x"}, {meta = "mantissadimen"}}, + details = [[ +Extracts the mantissa of ⟨x⟩ into the dimen register ⟨mantissadimen⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetmantissa" + }, + pgfmathfloatgetmantissatok = { + arguments = {{meta = "x"}, {meta = "mantissatoks"}}, + details = [[ +Extracts the mantissa of ⟨x⟩ into the token register ⟨mantissatoks⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatgetmantissatok" + }, + pgfmathfloatifapproxequalrel = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "true-code"}, + {meta = "false-code"} + }, + details = [[ +Computes the relative error between ⟨a⟩ and ⟨b⟩ (assuming ⟨b⟩$\neq 0$) +and invokes ⟨true-code⟩ if the relative error is below +`/pgf/fpu/rel thresh` and ⟨false-code⟩ if that is not the case. + +The input arguments will be parsed with `\pgfmathfloatparsenumber`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatifapproxequalrel" + }, + pgfmathfloatifflags = { + arguments = { + {meta = "floating point number"}, + {meta = "flag"}, + {meta = "true-code"}, + {meta = "false-code"} + }, + details = [[ +Invokes ⟨true-code⟩ if the flag of ⟨floating point number⟩ equals ⟨flag⟩ +and ⟨false-code⟩ otherwise. + +The argument ⟨flag⟩ can be one of + +0 +to test for zero, + +1 +to test for positive numbers, + +\+ +to test for positive numbers, + +2 +to test for negative numbers, + +\- +to test for negative numbers, + +3 +for "not-a-number", + +4 +for $+\infty$, + +5 +for $-\infty$. + +  + + \pgfmathfloatparsenumber{42} + \pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!} + \pgfmathfloatifflags{\pgfmathresult}{1}{It's positive!}{It's not positive!} + \pgfmathfloatifflags{\pgfmathresult}{2}{It's negative!}{It's not negative!} + + % or, equivalently + \pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!} + \pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatifflags" + }, + pgfmathfloatint = { + arguments = {{meta = "x"}}, + details = [[ +Returns the integer part of the floating point number ⟨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. + +See also `\pgfmathfloattoint` which returns the number in integer +format. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatint" + }, + pgfmathfloatlessthan = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Defines `\pgfmathresult` as $1.0$ if $⟨x⟩ < ⟨y⟩$, but $0.0$ otherwise. +It also sets the global TeX-boolean `\pgfmathfloatcomparison` +accordingly. The arguments ⟨x⟩ and ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatlessthan" + }, + pgfmathfloatmultiplyfixed = { + arguments = {{meta = "float"}, {meta = "fixed"}}, + details = [[ +Defines `\pgfmathresult` to be $⟨float⟩ \cdot ⟨fixed⟩$ where ⟨float⟩ is +a floating point number and ⟨fixed⟩ is a fixed point number. The +computation is performed in floating point arithmetics, that means we +compute $m \cdot ⟨fixed⟩$ and renormalize the result where $m$ is the +mantissa of ⟨float⟩. + +This operation renormalizes ⟨float⟩ with +`\pgfmathfloattoextentedprecision` before the operation, that means it +is intended for relatively small arguments of ⟨fixed⟩. The result is a +floating point number. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatmultiplyfixed" + }, + pgfmathfloatparsenumber = { + arguments = {{meta = "x"}}, + details = [[ +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 + + \pgfmathfloatparsenumber{2} + \pgfmathresult + +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 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: + + \pgfmathfloatparsenumber{0} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{0.2} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{42} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{20.5E+2} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{1e6} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + + \pgfmathfloatparsenumber{5.21513e-11} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E. + +The argument ⟨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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatparsenumber" + }, + pgfmathfloatqparsenumber = { + arguments = {{meta = "x"}}, + details = [[ +The same as `\pgfmathfloatparsenumber`, but does not perform sanity +checking. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatqparsenumber" + }, + pgfmathfloatrelerror = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatrelerror" + }, + pgfmathfloatround = { + arguments = {{meta = "x"}}, + details = [[ +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 ??. + +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. + + \pgfmathfloatparsenumber{52.5864} + \pgfmathfloatround{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{9.995} + \pgfmathfloatround{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatround" + }, + pgfmathfloatroundzerofill = { + arguments = {{meta = "x"}}, + details = [[ +A variant of `\pgfmathfloatround` produces always the same number of +digits after the period (it includes zeros if necessary). + + \pgfmathfloatparsenumber{52.5864} + \pgfmathfloatroundzerofill{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{9.995} + \pgfmathfloatroundzerofill{\pgfmathresult} + \pgfmathfloattosci{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatroundzerofill" + }, + pgfmathfloatsetextprecision = { + arguments = {{meta = "shift"}}, + details = [[ +Sets the precision used inside of `\pgfmathfloattoextentedprecision` to +⟨shift⟩. + +The different choices are + + --- ------------------ -------- ----------------- ------------------------------------------------- + 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$ + --- ------------------ -------- ----------------- ------------------------------------------------- +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatsetextprecision" + }, + pgfmathfloatshift = { + arguments = {{meta = "x"}, {meta = "num"}}, + details = [[ +Defines `\pgfmathresult` to be $⟨x⟩ \cdot 10^{⟨num⟩}$. The operation is +an arithmetic shift base ten and modifies only the exponent of ⟨x⟩. The +argument ⟨num⟩ is expected to be a (positive or negative) integer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatshift" + }, + pgfmathfloattoextentedprecision = { + arguments = {{meta = "x"}}, + details = [[ +Renormalizes ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoextentedprecision" + }, + pgfmathfloattofixed = { + arguments = {{meta = "x"}}, + details = [[ +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 ⟨x⟩ as a fixed point number +(of arbitrary precision). + + \pgfmathfloatparsenumber{0.00052} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E + $\to$ + \pgfmathfloattofixed{\pgfmathresult} + \pgfmathresult + + \pgfmathfloatparsenumber{123.456e4} + \pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} + Flags: \F; Mantissa \M; Exponent \E + $\to$ + \pgfmathfloattofixed{\pgfmathresult} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattofixed" + }, + pgfmathfloattoint = { + arguments = {{meta = "x"}}, + details = [[ +Converts a number from low-level floating point representation to an +integer (by truncating the fractional part). + + \pgfmathfloatparsenumber{123456} + \pgfmathfloattoint{\pgfmathresult} + \pgfmathresult + +See also `\pgfmathfloatint` which returns the result as float. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoint" + }, + pgfmathfloattomacro = { + arguments = { + {meta = "x"}, + {meta = "flagsmacro"}, + {meta = "mantissamacro"}, + {meta = "exponentmacro"} + }, + details = [[ +Extracts the flags of a floating point number ⟨x⟩ to ⟨flagsmacro⟩, the +mantissa to ⟨mantissamacro⟩ and the exponent to ⟨exponentmacro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattomacro" + }, + pgfmathfloattoregisters = { + arguments = { + {meta = "x"}, + {meta = "flagscount"}, + {meta = "mantissadimen"}, + {meta = "exponentcount"} + }, + details = [[ +Takes a floating point number ⟨x⟩ as input and writes flags to count +register ⟨flagscount⟩, mantissa to dimen register ⟨mantissadimen⟩ and +exponent to count register ⟨exponentcount⟩. + +Please note that this method rounds the mantissa to TeX-precision. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoregisters" + }, + pgfmathfloattoregisterstok = { + arguments = { + {meta = "x"}, + {meta = "flagscount"}, + {meta = "mantissatoks"}, + {meta = "exponentcount"} + }, + details = [[ +A variant of `\pgfmathfloattoregisters` which writes the mantissa into a +token register. It maintains the full input precision. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattoregisterstok" + }, + pgfmathfloattosci = { + arguments = {{meta = "float"}}, + details = [[ +Converts a number from low-level floating point representation to +scientific format, $1.234e4$. The result will be assigned to the macro +`\pgfmathresult`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloattosci" + }, + pgfmathfloatvalueof = { + arguments = {{meta = "float"}}, + details = [[ +Expands a number from low-level floating point representation to +scientific format, $1.234e4$. + +Use `\pgfmathfloatvalueof` in contexts where only expandable macros are +allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathfloatvalueof" + }, + pgfmathgeneratepseudorandomnumber = { + details = [[ +Defines `\pgfmathresult` as a pseudo-random integer between 1 and +$2^{31}-1$. This uses a linear congruency generator, based on ideas of +Erich Janka. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathgeneratepseudorandomnumber" + }, + pgfmathifisint = { + arguments = { + {meta = "number constant"}, + {meta = "true code"}, + {meta = "false code"} + }, + details = [[ +A command which does the same check as `int detect`, but it invokes +⟨true code⟩ if the ⟨number constant⟩ actually is an integer and the +⟨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 ⟨number constant⟩ will be parsed with +`\pgfmathfloatparsenumber`. + + 15 \pgfmathifisint{15}{is an int: \pgfretval.}{is no int}\hspace{1em} + 15.5 \pgfmathifisint{15.5}{is an int: \pgfretval.}{is no int} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathifisint" + }, + pgfmathlog = { + arguments = {{meta = "x"}}, + details = [[ +Defines `\pgfmathresult` to be the natural logarithm of ⟨x⟩, $\ln(⟨x⟩)$. +This method is logically the same as `\pgfmathln`, but it applies +floating point arithmetics to read number ⟨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 ⟨x⟩ needs to be a number, expression parsing is not +possible here. + +If ⟨x⟩ is *not* a bounded positive real number (for example +$⟨x⟩ \le 0$), `\pgfmathresult` will be *empty*, no error message will be +generated. + + \pgfmathlog{1.452e-7} + \pgfmathresult + + \pgfmathlog{6.426e+8} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathlog" + }, + pgfmathparse = { + arguments = {{meta = "expression"}}, + details = [[ +This macro parses ⟨expression⟩ and returns the result without units in +the macro `\pgfmathresult`. + +`\pgfmathparse{2pt+3.5pt}` will set `\pgfmathresult` to the text `5.5`. + +In the following, the special properties of this command are explained. +The exact syntax of mathematical expressions is explained in Sections ?? +and ??. + +- The result stored in the macro `\pgfmathresult` is a decimal + *without units*. This is true regardless of whether the ⟨expression⟩ + contains any unit specification. All numbers with units are + converted to points first. See Section ?? for details on units. + +- 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. + +- 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. + +- Parenthesis can be used to change the order of the evaluation. + +- 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. + +- 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`). + +- 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 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. + +- An integer with prefix `0b` or `0B` is interpreted as a binary + number and is automatically converted to base 10. + +- 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathparse" + }, + pgfmathpostparse = { + details = [[ +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 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 in `\pgfmathresultunitscale` +(which by default was `1`). + +This scaling can be turned on again using: +`\let\pgfmathpostparse=\pgfmathscaleresult`. Note, however that by +scaling the result, the base conversion functions will not work, and the +`"` character should not be used to quote parts of an expression. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathpostparse" + }, + pgfmathprintnumber = { + arguments = {{meta = "x"}}, + details = [[ +Generates pretty-printed output for the (real) number ⟨x⟩. The input +number ⟨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[`⟨options⟩`]`⟨x⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathprintnumber" + }, + pgfmathprintnumberto = { + arguments = {{meta = "x"}, {meta = "macro"}}, + details = [[ +Returns the resulting number into ⟨macro⟩ instead of typesetting it +directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathprintnumberto" + }, + pgfmathqparse = { + arguments = {{meta = "expression"}}, + details = [[ +This macro is similar to `\pgfmathparse`: it parses ⟨expression⟩ and +returns the result in the macro `\pgfmathresult`. It differs in two +respects. Firstly, `\pgfmathqparse` does not parse functions, scientific +notation, the prefixes for binary octal, or hexadecimal numbers, nor +does it accept the special use of `"`, `?` or `:` characters. Secondly, +numbers in ⟨expression⟩ *must* specify a TeX unit (except in such +instances as `0.5\pgf@x`), which greatly simplifies the problem of +parsing real numbers. As a result of these restrictions `\pgfmathqparse` +is about twice as fast as `\pgfmathparse`. Note that the result will +still be a number without units. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathqparse" + }, + pgfmathrandominteger = { + arguments = {{meta = "macro"}, {meta = "minimum"}, {meta = "maximum"}}, + details = [[ +This defines ⟨macro⟩ as a pseudo-randomly generated integer from the +range ⟨minimum⟩ to ⟨maximum⟩ (inclusive). + + \begin{pgfpicture} + \foreach \x in {1,...,50}{ + \pgfmathrandominteger{\a}{1}{50} + \pgfmathrandominteger{\b}{1}{50} + \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt} + \color{blue!40!white} + \pgfsetstrokecolor{blue!80!black} + \pgfusepath{stroke, fill} + } + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathrandominteger" + }, + pgfmathrandomitem = { + arguments = {{meta = "macro"}, {meta = "list name"}}, + details = [[ +Select an item from a random list ⟨list name⟩. The selected item is +placed in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathrandomitem" + }, + pgfmathreciprocal = { + arguments = {{meta = "x"}}, + details = [[ +Defines `\pgfmathresult` as $1\div⟨x⟩$. This provides greatest accuracy +when x is small. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathreciprocal" + }, + pgfmathredeclarefunction = { + arguments = {{meta = "function name"}, {meta = "code"}}, + details = [[ +This command redefines the `\pgfmath`⟨function name⟩`@` macro with the +new ⟨code⟩. See the description of the `\pgfmathdeclarefunction` for +details. You cannot change the number of arguments for an existing +function. + + \makeatletter + \pgfmathdeclarefunction{foo}{1}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by2\relax + \pgfmathreturn\pgf@x + \endgroup + } + \pgfmathparse{foo(42)}\pgfmathresult + \pgfmathredeclarefunction{foo}{ + \begingroup + \pgf@x=#1pt\relax + \multiply\pgf@x by3\relax + \pgfmathreturn\pgf@x + \endgroup + } + \pgfmathparse{foo(42)}\pgfmathresult + \makeatother +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathredeclarefunction" + }, + pgfmathroundto = { + arguments = {{meta = "x"}}, + details = [[ +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 ??. 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 ⟨x⟩. + + \pgfmathroundto{1} + \pgfmathresult + + \pgfmathroundto{4.685} + \pgfmathresult + + \pgfmathroundto{19999.9996} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathroundto" + }, + pgfmathroundtozerofill = { + arguments = {{meta = "x"}}, + details = [[ +A variant of `\pgfmathroundto` which always uses a fixed number of +digits behind the period. It fills missing digits with zeros. + + \pgfmathroundtozerofill{1} + \pgfmathresult + + \pgfmathroundto{4.685} + \pgfmathresult + + \pgfmathroundtozerofill{19999.9996} + \pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathroundtozerofill" + }, + pgfmathsetbasenumberlength = { + arguments = {{meta = "integer"}}, + details = [[ +Sets the number of digits in the result of a base conversion to +⟨integer⟩. If the result of a conversion has less digits than this +number, it is prefixed with zeros. + + \pgfmathsetbasenumberlength{8} + \pgfmathdectobase\mynumber{15}{2} \mynumber +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetbasenumberlength" + }, + pgfmathsetcount = { + arguments = {{meta = "count register"}, {meta = "expression"}}, + details = [[ +Sets the value of the TeX ⟨count register⟩, to the *truncated* value +specified by ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetcount" + }, + pgfmathsetcounter = { + arguments = {{meta = "counter"}, {meta = "expression"}}, + details = [[ +Sets the value of the LaTeX ⟨counter⟩ to the *truncated* value specified +by ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetcounter" + }, + pgfmathsetlength = { + arguments = {{meta = "register"}, {meta = "expression"}}, + details = [[ +Basically, this command sets the length of the TeX ⟨register⟩ to the +value specified by ⟨expression⟩. However, there is some fine print: + +First, in case ⟨expression⟩ starts with a `+`, a simple TeX assignment +is done. In particular, ⟨register⟩ can be a glue register and +⟨expression⟩ be something like `+1pt plus 1fil` and the ⟨register⟩ will +be assigned the expected value. + +Second, when the ⟨expression⟩ 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 ⟨register⟩ is a `\muskip` register +and will try to assign to ⟨register⟩ the value `\pgfmathresult` followed +by `mu`. Otherwise, in case `mu` was not encountered, it is assumed that +⟨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 + + \muskipdef\mymuskip=0 + \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip + + \dimendef\mydimen=0 + \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen + + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip + +One thing that will *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: + + \skipdef\myskip=0 + \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetlength" + }, + pgfmathsetlengthmacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the value of ⟨expression⟩ LaTeX *in points*. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetlengthmacro" + }, + pgfmathsetmacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the value of ⟨expression⟩. The result is a decimal +without units. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetmacro" + }, + pgfmathsetseed = { + arguments = {{meta = "integer"}}, + details = [[ +Explicitly sets the seed for the pseudo-random number generator. By +default it is set to the value of `\time`$\times$`\year`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathsetseed" + }, + pgfmathtodigitlist = { + arguments = {{meta = "macro"}, {meta = "number"}}, + details = [[ +This command converts ⟨number⟩ into a comma-separated list of digits and +stores the result in ⟨macro⟩. The `{number}` is *not* parsed before +processing. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathtodigitlist" + }, + pgfmathtruncatemacro = { + arguments = {{meta = "macro"}, {meta = "expression"}}, + details = [[ +Defines ⟨macro⟩ as the truncated value of ⟨expression⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmathtruncatemacro" + }, + pgfmatrix = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "name"}, + {meta = "usage"}, + {meta = "shift"}, + {meta = "pre-code"}, + {meta = "matrix cells"} + }, + details = [[ +This command creates a node that contains a matrix. The name of the node +is ⟨name⟩, its shape is ⟨shape⟩ and the node is anchored at ⟨anchor⟩. + +The ⟨matrix cell⟩ parameter contains the cells of the matrix. In each +cell drawing commands may be given, which create a so-called cell +picture. For each cell picture a bounding box is computed and the cells +are aligned according to the rules outlined in the previous section. + +The resulting matrix is used as the `text` box of the node. As for a +normal node, the ⟨usage⟩ commands are applied, so that the path(s) of +the resulting node is (are) stroked or filled or whatever. + +**Specifying the cells and rows. ** Even though this command uses +`\halign` internally, there are two special rules for indicating cells: + +1. Cells in the same row must be separated using the macro + `\pgfmatrixnextcell` rather than `& `. Using `& ` will result in an + error message. + + However, you can make `& ` an active character and have it expand to + `\pgfmatrixnextcell`. This way, it will "look" as if `& ` is used. + +2. Rows are ended using the command `\pgfmatrixendrow`, but `\\` 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". + +3. Every row *including the last row* must be ended using the command + `\\` or `\pgfmatrixendrow`. + +Both `\pgfmatrixnextcell` and `\pgfmatrixendrow` (and, thus, also `\\`) +take an optional argument as explained in the Section ?? + + \begin{tikzpicture} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{} + { + \node {a}; \pgfmatrixnextcell \node {b}; \pgfmatrixendrow + \node {c}; \pgfmatrixnextcell \node {d}; \pgfmatrixendrow + } + \end{tikzpicture} + +**Anchoring matrices at nodes inside the matrix. ** The parameter +⟨shift⟩ is an additional negative shift for the node. Normally, such a +shift could be given beforehand (that is, the shift could be preapplied +to the current transformation matrix). However, when ⟨shift⟩ is +evaluated, you can refer to *temporary* positions of nodes inside the +matrix. In detail, the following happens: When the matrix has been +typeset, all nodes in the matrix temporarily get assigned their +positions in the matrix box. The origin of this coordinate system is at +the left baseline end of the matrix box, which corresponds to the `text` +anchor. The position ⟨shift⟩ is then interpreted inside this coordinate +system and then used for shifting. + +This allows you to use the parameter ⟨shift⟩ in the following way: If +you use `text` as the ⟨anchor⟩ and specify +`\pgfpointanchor{inner node}{some anchor}` for the parameter ⟨shift⟩, +where `inner node` is a node that is created in the matrix, then the +whole matrix will be shifted such that `inner node.some anchor` lies at +the origin of the whole picture. + +**Rotations and scaling. ** The matrix node is never rotated or scaled, +because the current coordinate transformation matrix is reset (except +for the translational part) at the beginning of `\pgfmatrix`. This is +intentional and will not change in the future. If you need to rotate or +scale the matrix, you must install an appropriate canvas transformation +yourself. + +However, nodes and stuff inside the cell pictures can be rotated and +scaled normally. + +**Callbacks. ** At the beginning and at the end of each cell the special +macros `\pgfmatrixbegincode`, `\pgfmatrixendcode` and possibly +`\pgfmatrixemptycode` are called. The effect is explained in Section ??. + +**Executing extra code. ** The parameter ⟨pre-code⟩ is executed at the +beginning of the outermost TeX-group enclosing the matrix node. It is +inside this TeX-group, but outside the matrix itself. It can be used for +different purposes: + +1. It can be used to simplify the next cell macro. For example, saying + `\let\& =\pgfmatrixnextcell` allows you to use `\& ` instead of + `\pgfmatrixnextcell`. You can also set the catcode of `& ` to + active. + +2. It can be used to issue an `\aftergroup` command. This allows you to + regain control after the `\pgfmatrix` command. (If you do not know + the `\aftergroup` command, you are probably blessed with a simple + and happy life.) + +**Special considerations concerning macro expansion. ** As said before, +the matrix is typeset using `\halign` internally. This command does a +lot of strange and magic things like expanding the first macro of every +cell in a most unusual manner. Here are some effects you may wish to be +aware of: + +- It is not necessary to actually mention `\pgfmatrixnextcell` or + `\pgfmatrixendrow` inside the ⟨matrix cells⟩. It suffices that the + macros inside ⟨matrix cells⟩ expand to these macros sooner or later. + +- In particular, you can define clever macros that insert columns and + rows as needed for special effects. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrix" + }, + pgfmatrixbegincode = { + details = [[ +This macro is executed at the beginning of non-empty cells. +Correspondingly, `\pgfmatrixendcode` is added at the end of every +non-empty cell. + + \begin{tikzpicture} + \def\pgfmatrixbegincode{\node[draw]\bgroup} + \def\pgfmatrixendcode{\egroup;} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + a \& b \& c \\ + d \& \& e \\ + } + \end{tikzpicture} + +Note that between `\pgfmatrixbegincode` and `\pgfmatrixendcode` there +will *not* only be the contents of the cell. Rather, PGF will add some +(invisible) commands for book-keeping purposes that involve `\let` and +`\gdef`. In particular, it is not a good idea to have +`\pgfmatrixbegincode` end with `\csname` and `\pgfmatrixendcode` start +with `\endcsname`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixbegincode" + }, + pgfmatrixcurrentcolumn = { + details = [[ +This counter stores the current column of the current cell of the +matrix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixcurrentcolumn" + }, + pgfmatrixcurrentrow = { + details = [[ +This counter stores the current row of the current cell of the matrix. +Do not even think about changing this counter. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixcurrentrow" + }, + pgfmatrixemptycode = { + details = [[ +This macro is executed for empty cells. This means that PGF uses some +macro magic to determine whether a cell is empty (it immediately ends +with `\pgfmatrixemptycode` or `\pgfmatrixendrow`) and, if so, put this +macro inside the cell. + + \begin{tikzpicture} + \def\pgfmatrixemptycode{\node{empty};} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {a}; \& \& \node {b}; \\ + \& \node{c}; \& \node {d}; \& \\ + } + \end{tikzpicture} + +As can be seen, the macro is not executed for empty cells at the end of +row when columns are added only later on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixemptycode" + }, + pgfmatrixendcode = { + details = [[ +See the explanation above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixendcode" + }, + pgfmatrixendrow = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "additional sep list", + optional = true + } + }, + details = [[ +This command ends a line. The optional ⟨additional sep list⟩ is used to +determine the spacing between the row being ended and the next row. The +modes and the computation of $d$ is done in the same way as for columns. +For the last row the optional argument has no effect. + +Inside matrices (and only there) the command `\\` is set up to mean the +same as this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixendrow" + }, + pgfmatrixnextcell = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "additional sep list", + optional = true + } + }, + details = [[ +This command has two purposes: First, it is used to separate cells. +Second, by providing the optional argument ⟨additional sep list⟩ you can +modify the spacing between the columns that are separated by this +command. + +The optional ⟨additional sep list⟩ may only be provided when the +`\pgfmatrixnextcell` command starts a new column. Normally, this will +only be the case in the first row, but sometimes a later row has more +elements than the first row. In this case, the `\pgfmatrixnextcell` +commands that start the new columns in the later row may also have the +optional argument. Once a column has been started, subsequent uses of +this optional argument for the column have no effect. + +To determine the space between the two columns that are separated by +`\pgfmatrixnextcell`, the following algorithm is executed: + +1. Both the default separation list (as set up by + `\pgfsetmatrixcolumnsep`) and the ⟨additional sep list⟩ are + processed, in this order. If the ⟨additional sep list⟩ argument is + missing, only the default separation list is processed. + +2. Both lists may contain dimensions, separated by commas, as well as + occurrences of the keywords `between origins` and `between borders`. + +3. All dimensions occurring in either list are added together to arrive + at a dimension $d$. + +4. The last occurrence of either of the keywords is located. If neither + keyword is present, we proceed as if `between borders` were present. + +At the end of the algorithm, a dimension $d$ has been computed and one +of the two *modes* `between borders` and `between origins` has been +determined. Depending on which mode has been determined, the following +happens: + +- For the `between borders` mode, an additional horizontal space of + $d$ is added between the two columns. Note that $d$ may be negative. + +- 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 set up such that the horizontal distance + between these two lines is exactly $d$. + + This mode may only be used between columns *already introduced in + the first row*. + +All of the above rules boil down to the following effects: + +- A default spacing between columns should be set up using + `\pgfsetmatrixcolumnsep`. For example, you might say + `\pgfsetmatrixcolumnsep{5pt}` to have columns spaced apart by `5pt`. + You could say + + \pgfsetmatrixcolumnsep{1cm,between origins} + + to specify that horizontal space between the origins of cell + pictures in adjacent columns should be 1cm by default -- regardless + of the actual size of the cell pictures. + +- You can now use the optional argument of `\pgfmatrixnextcell` to + locally overrule the spacing between two columns. By saying + `\pgfmatrixnextcell[5pt]` you *add* 5pt to the space between of the + two columns, regardless of the mode. + + You can also (locally) change the spacing mode for these two + columns. For example, even if the normal spacing mode is + `between origins`, you can say + + \pgfmatrixnextcell[5pt,between borders] + + to locally change the mode for these columns to `between borders`. + +  + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1mm} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\ + \node {3}; \& \node{5}; \& \node {7}; \\ + \node {4}; \& \node{9}; \& \node {2}; \\ + } + \end{tikzpicture} + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1mm} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\ + \node {3}; \& \node {5}; \& \node {7}; \\ + \node {4}; \& \node {9}; \& \node {2}; \\ + } + \draw [<->,red,thick,every node/.style=] (a.center) -- (b.center) + node [above,midway] {11mm}; + \end{tikzpicture} + + \begin{tikzpicture}[every node/.style=draw] + \pgfsetmatrixcolumnsep{1cm,between origins} + \pgfmatrix{rectangle}{center}{mymatrix} + {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell} + { + \node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\ + \node {3}; \& \node {5}; \& \node {7}; \\ + \node {4}; \& \node {9}; \& \node {2}; \\ + } + \begin{scope}[every node/.style=] + \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm}; + \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] + {10mm}; + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmatrixnextcell" + }, + pgfmetadecoratedcompleteddistance = { + details = [[ +The completed distance on the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedcompleteddistance" + }, + pgfmetadecoratedinputsegmentcompleteddistance = { + details = [[ +The completed distance on the current input segment of the entire input +path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedinputsegmentcompleteddistance" + }, + pgfmetadecoratedinputsegmentremainingdistance = { + details = [[ +The remaining distance on the current input segment of the entire input +path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedinputsegmentremainingdistance" + }, + pgfmetadecoratedpathlength = { + details = [[ +The entire length of the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedpathlength" + }, + pgfmetadecoratedremainingdistance = { + details = [[ +The remaining distance on the entire input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmetadecoratedremainingdistance" + }, + pgfmultipartnode = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "name"}, + {meta = "path usage command"} + }, + details = [[ +This command is the more general (and less user-friendly) version of the +`\pgfnode` command. While the `\pgfnode` command can only be used for +shapes that have a single part (which is the case for most 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 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 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 shapes. Finally, when the node is drawn, the boxes +are placed at the anchor positions `text` and `lower`. + + \setbox\pgfnodeparttextbox=\hbox{$q_1$} + \setbox\pgfnodepartlowerbox=\hbox{01} + \begin{pgfpicture} + \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}} + \end{pgfpicture} + +*Note:* Be careful when using the `\setbox` command inside a +`{pgfpicture}` command. You will have to use `\pgfinterruptpath` at the +beginning of the box and `\endpgfinterruptpath` at the end of the box to +make sure that the box is typeset correctly. In the above example this +problem was sidestepped by moving the box construction outside the +environment. + +*Note:* It is not necessary to use `\newbox` for every node 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 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 + + \newbox\pgfnodepartlowerbox + \let\pgfnodepartmethodsbox=\pgfnodepartlowerbox + +Also, when you have a node part name with spaces like `class name`, it +may be useful to create an alias: + + \newbox\mybox + \expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfmultipartnode" + }, + pgfnode = { + arguments = { + {meta = "shape"}, + {meta = "anchor"}, + {meta = "label text"}, + {meta = "name"}, + {meta = "path usage command"} + }, + details = [[ +This command creates a new node. The ⟨shape⟩ of the node must have been +declared previously using `\pgfdeclareshape`. + +The shape is shifted such that the ⟨anchor⟩ is at the origin. In order +to place the shape somewhere else, use the coordinate transformation +prior to calling this command. + +The ⟨name⟩ is a name for later reference. If no name is given, nothing +will be "saved" for the node, it will just be drawn. + +The ⟨path usage command⟩ is executed for the background and the +foreground path (if the shape defines them). + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \pgftransformshift{\pgfpoint{1.5cm}{1cm}} + \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}} + } + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } + \end{tikzpicture} + +As can be seen, all coordinate transformations are also applied to the +text of the shape. Sometimes, it is desirable that the transformations +are applied to the point where the shape will be anchored, but you do +not wish the shape itself to be transformed. In this case, you should +call `\pgftransformresetnontranslations` prior to calling the `\pgfnode` +command. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,3); + { + \color{red!20} + \pgftransformrotate{10} + \pgftransformshift{\pgfpoint{3cm}{1cm}} + \pgftransformresetnontranslations + \pgfnode{rectangle}{center} + {\color{black}Hello World}{hellonode}{\pgfusepath{fill}} + } + \end{tikzpicture} + +The ⟨label text⟩ is typeset inside the TeX-box `\pgfnodeparttextbox`. +This box is shown at the `text` anchor of the node, if the node has a +`text` part. See the description of `\pgfmultipartnode` for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnode" + }, + pgfnodealias = { + arguments = {{meta = "new name"}, {meta = "existing node"}}, + details = [[ +This command does not actually create a new node. Rather, it allows you +to subsequently access the node ⟨existing node⟩ using the name ⟨new +name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnodealias" + }, + pgfnodepostsetupcode = { + arguments = {{meta = "node name"}, {meta = "code"}}, + details = [[ +When you call this macro inside a scope for which the +`\pgfpositionnodelater` has been called, the ⟨code⟩ will be stored +internally. Later, when the node named ⟨node name⟩ is actually +positioned using `\pgfpositionnodenow`, the ⟨code⟩ will be executed. +When this macro is called multiple times with the same ⟨node name⟩, the +⟨code⟩ accumulates. However, When `\pgfpositionnodenow` is called, the +code stored for the node is cleared. + +The main purpose of this mechanism is to allow TikZ to store so-called +"late options" with a node that will be positioned only later. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnodepostsetupcode" + }, + pgfnoderename = { + arguments = {{meta = "new name"}, {meta = "existing node"}}, + details = [[ +This command renames an existing node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfnoderename" + }, + pgfooappend = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooappend" + }, + pgfooclass = { + arguments = { + {delimiters = {"(", ")"}, meta = "list of superclasses"}, + {meta = "class name"}, + {meta = "body"} + }, + details = [[ +This command defines a class named ⟨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`. +The ⟨list of superclasses⟩ is optional just like the parenthesis around +it. + +The ⟨body⟩ is actually just executed, so any normal TeX-code is +permissible here. However, while the ⟨body⟩ is 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). + +The definition of a class is local to the scope where the class has been +defined. + + \pgfooclass{stamp}{ + % This is the class stamp + + \attribute text; + \attribute rotation angle=20; + + \method stamp(#1) { % The constructor + ... + } + + \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2) + ... + } + } + + % We can now create objects of type "stamp" + +Concerning the list of base classes, the Method Resolution Order (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 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 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 MRO of $C$ which declares attribute +`attr`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooclass" + }, + pgfooeset = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +Performs the same action as `\pgfooset` but in an `\edef` full expansion +context. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooeset" + }, + pgfoogc = { + details = [[ +This command causes the "garbage collector" to be invoked. The job of +this garbage collector is to free the global TeX-macros that are used by +"dead" objects (objects whose life-time has ended). This macro is called +automatically after every scope in which an object has been created, so +you normally do not need to call this macro yourself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoogc" + }, + pgfooget = { + arguments = {{meta = "attribute"}, {meta = "macro"}}, + details = [[ +Reads the current value of ⟨attribute⟩ and stores the result in ⟨macro⟩. + + ... + \method get rotation (#1) { + \pgfooget{rotation angle}{#1} + } + ... + + \mystamp.get rotation(\therotation) + ``\therotation'' is now ``20'' (or whatever). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooget" + }, + pgfoolet = { + arguments = {{meta = "attribute"}, {meta = "macro"}}, + details = [[ +Sets the ⟨attribute⟩ of the current value to the current value of +⟨macro⟩ using TeX's `\let` command. + + \method foo () { + \pgfoolet{my func}\myfunc + % Changing \myfunc now has no effect on the value of attribute my func + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoolet" + }, + pgfoonew = { + arguments = { + {meta = "object handle or attribute"}, + {literal = "="}, + {literal = "new "}, + {meta = "class name"}, + {delimiters = {"(", ")"}, meta = "constructor arguments"} + }, + details = [[ +Causes a new object to be created. The class of the object will be +⟨class name⟩, which must previously have been declared using +`\pgfooclass`. Once the object has been created, the constructor method +of the object will be called with the parameter list set to ⟨constructor +arguments⟩. + +The resulting object is stored internally and its lifetime will end +exactly at the end of the current scope. + +Here is an example in which three stamp objects are created. + + \pgfoonew \firststamp=new stamp() + \pgfoonew \secondstamp=new stamp() + { + \pgfoonew \thirdstamp=new stamp() + ... + } + % \thirdstamp no longer exists, but \firststamp and \secondstamp do + % even if you try to store \thirdstamp in a global variable, trying + % to access it will result in an error. + +The optional ⟨object handle or attribute⟩ can either be an ⟨object +handle⟩ or an ⟨attribute⟩. When an ⟨object 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 ??). You can use this macro to call +methods of the object as discussed in the following section. When an +⟨attribute⟩ is given, it must be given in curly braces (the curly braces +are used to detect the presence of an attribute). In this case, a handle +to the newly created object is stored in this attribute. + + \pgfooclass{foo} + { + \attribute stamp obj; + \attribute another object; + + \method foo() { + \pgfoonew{stamp obj}=new stamp() + \pgfoonew{another object}=new bar() + } + ... + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoonew" + }, + pgfooobj = { + arguments = {{meta = "id"}}, + details = [[ +Provided that ⟨id⟩ is the id of an existing object (an object whose +life-time has not expired), calling this command yields a handle to this +object. The handle can then be used to call methods: + + % Create a new object: + \pgfoonew \mystamp=new stamp() + + % Get the object's id and store it in \myid: + \mystamp.get id(\myid) + + % The following two calls have the same effect: + \mystamp.apply(1,1) + \pgfooobj{\myid}.apply(1,1) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooobj" + }, + pgfooprefix = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +This method adds the given ⟨value⟩ to the ⟨attribute⟩ at the beginning. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooprefix" + }, + pgfooset = { + arguments = {{meta = "attribute"}, {meta = "value"}}, + details = [[ +Sets the ⟨attribute⟩ of the current object to ⟨value⟩. + + \method set rotation (#1) { + \pgfooset{rotation angle}{#1} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfooset" + }, + pgfoosuper = { + arguments = {{literal = "("}, {meta = "class"}}, + details = [[ +This macro gives you finer control over which method gets invoked in +case of multiple inheritance. This macro calls ⟨method name⟩ of the +object specified by ⟨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 ⟨class⟩ that +defines ⟨method name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoosuper" + }, + pgfoothis = { + details = [[ +This object handle is well-defined only when a method is being executed. +There, it is then set to point to the object for which the method is +being called, which allows you to call another method for the same +object. + + \pgfooclass{stamp}{ + % This is the class stamp + + \method stamp() {} + + \method apply(#1,#2) { + \pgfoothis.shift origin(#1,#2) + + % Draw the stamp: + \node [rotate=20,font=\huge] {Passed}; + } + + % Private method: + \method shift origin(#1,#2) { + \tikzset{xshift=#1,yshift=#2} + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoothis" + }, + pgfoovalueof = { + arguments = {{meta = "attribute"}}, + details = [[ +Expands (eventually) to the current value of ⟨attribute⟩ of the current +object. + + \method apply(#1,#2) { + \pgfoothis.shift origin(#1,#2) + + \node [rotate=\pgfoovalueof{rotation angle},font=\huge] + {\pgfoovalueof{text}}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfoovalueof" + }, + pgfpagescurrentpagewillbelogicalpage = { + arguments = {{meta = "number"}}, + details = [[ +When the current TeX page has been typeset, it will be become the given +logical page ⟨number⟩. This command "interrupts" the normal order of +logical pages, that is, it behaves like the previous command and does +not update the ⟨current logical page⟩ counter. + + \pgfpagesuselayout{two screens with optional second} + ... + Text for main page. + \clearpage + + \pgfpagescurrentpagewillbelogicalpage{2} + Text that goes to second page + \clearpage + + Text for main page. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagescurrentpagewillbelogicalpage" + }, + pgfpagesdeclarelayout = { + arguments = { + {meta = "layout"}, + {meta = "before actions"}, + {meta = "after actions"} + }, + details = [[ +This command predefines a ⟨layout⟩ that can later be installed using the +`\pgfpagesuselayout` command. + +When `\pgfpagesuselayout``{layout}``[options]` is called, the following +happens: First, the ⟨before actions⟩ are executed. They can be used, for +example, to set up default values for keys. Next, +`\setkeys{pgfpagesuselayoutoption}``{options}` is executed. Finally, the +⟨after actions⟩ are executed. + +Here is an example: + + \pgfpagesdeclarelayout{resize to} + { + \def\pgfpageoptionborder{0pt} + } + { + \pgfpagesphysicalpageoptions + {% + logical pages=1,% + physical height=\pgfpageoptionheight,% + physical width=\pgfpageoptionwidth% + } + \pgfpageslogicalpageoptions{1} + {% + resized width=\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + border shrink=\pgfpageoptionborder,% + center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesdeclarelayout" + }, + pgfpageslogicalpageoptions = { + arguments = { + {meta = "logical page number"}, + {keys = "$ref:pgf#/keys/pgf", meta = "options"} + }, + details = [[ +This command is used to specify where the logical page number ⟨logical +page number⟩ will be placed on the physical page. In addition, this +command can be used to install additional "code" to be executed when +this page is put on the physical page. + +The number ⟨logical page number⟩ should be between 1 and ⟨logical +pages⟩, which has previously been installed using the +`\pgfpagesphysicalpageoptions` command. + +The following ⟨options⟩ may be given: + +- `center=`⟨pgf point⟩ specifies the center of the logical page inside + the physical page as a PGF-point. The origin of the coordinate + system of the physical page is at the *lower* left corner. + + \pgfpageslogicalpageoptions{1} + {% center logical page on middle of left side + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + } + +- `resized width=`⟨size⟩ specifies the width that the logical page + should have *at most* on the physical page. To achieve this width, + the pages is scaled down appropriately *or more*. The "or more" part + can happen if the `resize height` option is also used. In this case, + the scaling is chosen such that both the specified height and width + are met. The aspect ratio of a logical page is not modified. + +- `resized height=`⟨height⟩ specifies the maximum height of the + logical page. + +- `original width=`⟨width⟩ specifies the width the TeX "thinks" that + the logical page has. This width is `\paperwidth` at the point of + invocation, by default. Note that setting this width to something + different from `\paperwidth` does *not* change the `\pagewidth` + during TeX's typesetting. You have to do that yourself. + + You need this option only for special logical pages that have a + height or width different from the normal one and for which you will + (later on) set these sizes yourself. + +- `original height=`⟨height⟩ works like `original width`. + +- `scale=`⟨factor⟩ scales the page by at least the given ⟨factor⟩. A + ⟨factor⟩ of `0.5` will half the size of the page, a factor or `2` + will double the size. "At least" means that if options like + `resize height` are given and if the scaling required to meet that + option is less than ⟨factor⟩, that other scaling is used instead. + +- `xscale=`⟨factor⟩ scales the logical page along the $x$-axis by the + given ⟨factor⟩. This scaling is done independently of any other + scaling. Mostly, this option is useful for a factor of `-1`, which + flips the page along the $y$-axis. The aspect ratio is not kept. + +- `yscale=`⟨factor⟩ works like `xscale`, only for the $y$-axis. + +- `rotation=`⟨degree⟩ rotates the page by ⟨degree⟩ around its center. + Use a degree of `90` or `-90` to go from portrait to landscape and + back. The rotation need not be a multiple of `90`. + +- `copy from=`⟨logical page number⟩. Normally, after a physical + shipout has occurred, all logical pages are voided in a loop. + However, if this option is given, the current logical page is filled + with the contents of the old logical page number ⟨logical page + number⟩. + + Have logical page 2 retain its contents: + + \pgfpageslogicalpageoptions{2}{copy from=2} + + Let logical page 2 show what logical page 1 showed on the + just-shipped-out physical page: + + \pgfpageslogicalpageoptions{2}{copy from=1} + +- `border shrink`=⟨size⟩ specifies an additional reduction of the size + to which the page is page is scaled. + +- `border code`=⟨code⟩. When this option is given, the ⟨code⟩ is + executed before the page box is inserted with a path preinstalled + that is a rectangle around the current logical page. Thus, setting + ⟨code⟩ to `\pgfstroke` draws a rectangle around the logical page. + Setting ⟨code⟩ to `\pgfsetlinewidth{3pt}\pgfstroke` results in a + thick (ugly) frame. Adding dashes and filling can result in + arbitrarily funky and distracting borders. + + 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 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 page is + inserted *after* these commands have been executed. + + Add a rectangle around the page: + + \pgfpageslogicalpageoptions{1}{border code=\pgfstroke} + +- `corner width`=⟨size⟩ adds black "rounded corners" to the page. See + the description of the predefined layout `rounded corners` on + page ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpageslogicalpageoptions" + }, + pgfpagesphysicalpageoptions = { + arguments = {{keys = "$ref:pgf#/keys/pgf", meta = "options"}}, + details = [[ +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 specified using the +command `\pgfpageslogicalpageoptions`, described later. + +A layout for putting two portrait pages on a single landscape page: + + \pgfpagesphysicalpageoptions + {% + logical pages=2,% + physical height=\paperwidth,% + physical width=\paperheight,% + } + + \pgfpageslogicalpageoptions{1} + {% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + \pgfpageslogicalpageoptions{2} + {% + resized width=.5\pgfphysicalwidth,% + resized height=\pgfphysicalheight,% + center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}% + }% + +The following ⟨options⟩ may be set: + +- `logical pages=`⟨logical pages⟩ specified how many logical pages + there are, in total. These are numbered 1 to ⟨logical pages⟩. + +- `first logical shipout=`⟨first⟩. See the next option. By default, + ⟨first⟩ is 1. + +- `last logical shipout=`⟨last⟩. Together with the previous option, + these two options define an interval of pages inside the range 1 to + ⟨logical pages⟩. Only this range is used to store the pages that are + shipped out by TeX. This means that after a physical shipout has + just occurred (or at the beginning), the first time TeX wishes to + perform a shipout, the page to be shipped out is stored in logical + page ⟨first⟩. The next time TeX performs a shipout, the page is + stored in logical page $⟨first⟩ +1$ and so on, until the logical + page ⟨last⟩ is also filled. Once this happens, a physical shipout + occurs and the process starts once more. + + Note that logical pages that lie outside the interval between + ⟨first⟩ and ⟨last⟩ are filled only indirectly or when special + commands are used. + + By default, ⟨last⟩ equals ⟨logical pages⟩. + +- `current logical shipout=`⟨current⟩ changes an internal counter such + that TeX's next logical shipout will be stored in logical page + ⟨current⟩. + + This option can be used to "warp" the logical page filling mechanism + to a certain page. You can both skip logical pages and overwrite + already filled logical pages. After the logical page ⟨current⟩ has + been filled, the internal counter is incremented normally as if the + logical page ⟨current⟩ had been "reached" normally. If you specify a + ⟨current⟩ larger than ⟨last⟩, a physical shipout will occur after + the logical page ⟨current⟩ has been filled. + +- `physical height=`⟨height⟩ specifies the height of the physical + pages. This height is typically different from the normal + `\paperheight`, which is used by TeX for its typesetting and page + breaking purposes. + +- `physical width=`⟨width⟩ specifies the physical width. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesphysicalpageoptions" + }, + pgfpagesshipoutlogicalpage = { + arguments = {{meta = "number"}, {meta = "box"}}, + details = [[ +This command sets to logical page ⟨number⟩ to ⟨box⟩. The ⟨box⟩ should be +the code of a TeX box command. This command does not influence the +counter ⟨current logical page⟩ and does not cause a physical shipout. + + \pgfpagesshipoutlogicalpage{0}\vbox{Hi!} + +This command can be used to set the contents of logical pages that are +normally not filled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesshipoutlogicalpage" + }, + pgfpagesuselayout = { + arguments = { + {meta = "layout"}, + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + } + }, + details = [[ +Installs the specified ⟨layout⟩ with the given ⟨options⟩. The predefined +layouts and their permissible options are explained below. + +If this function is called multiple times, only the last call "wins". +You can thereby overwrite any previous settings. In particular, layouts +*do not* accumulate. + +`\pgfpagesuselayout{resize to}[a4paper]` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpagesuselayout" + }, + pgfparserdeffinal = { + arguments = {{meta = "parser name"}, {meta = "action"}}, + details = [[ +Every parser can call a final ⟨action⟩ after the state was switched to +`final`. This ⟨action⟩ is executed after everything else, so you can use +something that grabs more arguments if you want to. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserdeffinal" + }, + pgfparserdefunknown = { + arguments = {{meta = "parser name"}, {meta = "state"}, {meta = "action"}}, + details = [[ +With this macro you can define an ⟨action⟩ for the ⟨parser name⟩ parser +in ⟨state⟩ if no action was defined for the letter which was +encountered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserdefunknown" + }, + pgfparserifmark = { + arguments = {{meta = "arg"}, {meta = "true"}, {meta = "false"}}, + details = [[ +Remember that some of the optional argument types set special marks? +With `\pgfparserifmark` you can test whether ⟨arg⟩ is such a mark. So if +there was no optional argument for the argument types `o` and `d` the +⟨true⟩ branch will be executed, else the ⟨false⟩ branch. For the `t` +type argument the ⟨true⟩ branch is executed if the token was +encountered. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserifmark" + }, + pgfparserletter = { + details = [[ +This macro stores the letter to which `\pgfparsertoken` was let. So if +you'd use `\pgfparserparse{foo}a` this macro would be defined with +`\def\pgfparserletter{a}`. This definition is done before any action +code is executed. There are four special cases: If the next token is of +category code 1, 2, 6, or 10, so with standard category codes the tokens +`{`, `}`, `# `, and  (a space), it would be treated differently. In +those cases this macro expands to `\bgroup`, `\egroup`, `# # `, and  for +the categories 1, 2, 6, and 10, respectively. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserletter" + }, + pgfparserparse = { + arguments = {{meta = "parser name"}, {meta = "text"}}, + details = [[ +This command is used to parse the ⟨text⟩ using the (previously defined) +parser named ⟨parser name⟩. + +The ⟨text⟩ is not contained in curly braces, rather it is all the text +that follows. The end of the text is determined implicitly, namely when +the final state of the parser has been reached. If you defined a final +action for the parser using `\pgfparserdeffinal` it is executed now. + +The parser works as follows: At any moment, it is in a certain *state*, +initially this state is called `initial`. Then, the first letter of the +⟨text⟩ is examined (using the `\futurelet` command). For each possible +state and each possible letter, some action code is stored in the parser +in a table. This code is then executed. This code may, but need not, +trigger a *state switch*, causing a new state to be set. The parser then +moves on to the next character of the text and repeats the whole +procedure, unless it is in the state `final`, which causes the parsing +process to stop immediately. + +In the following example, the parser counts the number of `a`'s in the +text, ignoring any `b`'s. The ⟨text⟩ ends with the first `c`. + + \newcount\mycount + \pgfparserdef{myparser}{initial}{the letter a}% + {\advance\mycount by 1\relax}% + \pgfparserdef{myparser}{initial}{the letter b}% + {} % do nothing + \pgfparserdef{myparser}{initial}{the letter c}% + {\pgfparserswitch{final}}% done! + + \pgfparserparse{myparser}aabaabababbbbbabaabcccc + There are \the\mycount\ a's. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserparse" + }, + pgfparserreinsert = { + details = [[ +You can use this as the final macro in an action of `\pgfparserdef` or +`\pgfparserdefunknown`. This has the effect that the contents of +`\pgfparserletter` will be parsed next. Without any redefinition the +result will be that the last token will be parsed again. You can change +the definition of `\pgfparserletter` just before `\pgfparserreinsert` as +well to parse some specific tokens next. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserreinsert" + }, + pgfparserset = { + arguments = {{meta = "key list"}}, + details = [[ +The `pgfparser` module has a few keys you can access through this macro. +It is just a shortcut for `\pgfset{/pgfparser/.cd,# 1}`. The available +keys are listed in subsection ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserset" + }, + pgfparserstate = { + details = [[ +Expands to the current state of the parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserstate" + }, + pgfparserswitch = { + arguments = {{meta = "state"}}, + details = [[ +This command can be called inside the action code of a parser to cause a +state switch to ⟨state⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparserswitch" + }, + pgfparsertoken = { + details = [[ +This is the macro which is let to the following token with `\futurelet`. +You can use it inside an action code. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparsertoken" + }, + pgfparsetime = { + arguments = {{meta = "time"}}, + details = [[ +This command works like `\pgfmathparse` (indeed, it calls is +internally), but returns the result in the macro `\pgftimeresult` rather +than `\pgfmathresult`. Furthermore, the following changes are installed: + +- The postfix operator `s` is added, which has no effect. + +- The postfix operator `ms` is added, which divides a number by 1000, + so `2ms` equals 0.002s. + +- The postfix operator `min` is added, which multiplies a number + by 60. + +- The postfix operator `h` is added, which multiplies a number + by 3600. + +- The infix operator `:` is redefined, so that it multiplies its first + argument by 60 and adds the second. This implies that `1:20` equals + 80s and `01:00:00` equals 3600s. + +- The parsing of octal numbers is switched off to allow things like + `01:08` for 68s. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfparsetime" + }, + pgfpatharc = { + arguments = { + {meta = "start angle"}, + {meta = "end angle"}, + {literal = "{"}, + {meta = "radius"}, + {literal = " and "}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +This command appends a part of a circle (or an ellipse) to the current +path. Imagine the curve between ⟨start angle⟩ and ⟨end angle⟩ on a +circle of radius ⟨radius⟩ (if $⟨start angle⟩ < ⟨end + angle⟩$, the curve goes around the circle counterclockwise, +otherwise clockwise). This curve is now moved such that the point where +the curve starts is the previous last point of the path. Note that this +command will *not* start a new part of the path, which is important for +example for filling purposes. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{1cm}} + \pgfpatharc{180}{90}{.5cm} + \pgfpathlineto{\pgfpoint{3cm}{1.5cm}} + \pgfpatharc{90}{-45}{.5cm} + \pgfusepath{fill} + \end{tikzpicture} + +Saying `\pgfpatharc{0}{360}{1cm}` "nearly" gives you a full circle. The +"nearly" refers to the fact that the circle will not be closed. You can +close it using `\pgfpathclose`. + +If the optional ⟨y-radius⟩ is given, the ⟨radius⟩ is the $x$-radius and +the ⟨y-radius⟩ the $y$-radius of the ellipse from which the curve is +taken: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm and 1cm} + \pgfusepath{draw} + \end{tikzpicture} + +The axes of the circle or ellipse from which the arc is "taken" always +point up and right. However, the current coordinate transformation +matrix will have an effect on the arc. This can be used to, say, rotate +an arc: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharc{180}{45}{2cm and 1cm} + \pgfusepath{draw} + \end{tikzpicture} + +The command will update the bounding box of the current path and +picture, if necessary. Unless rotation or shearing transformations are +applied, the bounding box will be tight. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharc" + }, + pgfpatharcaxes = { + arguments = { + {meta = "start angle"}, + {meta = "end angle"}, + {meta = "first axis"}, + {meta = "second axis"} + }, + details = [[ +This command is similar to `\pgfpatharc`. The main difference is how the +ellipse or circle is specified from which the arc is taken. The two +parameters ⟨first axis⟩ and ⟨second axis⟩ are the $0^\circ$-axis and the +$90^\circ$-axis of the ellipse from which the path is taken. Thus, +`\pgfpatharc{0}{90}{1cm and 2cm}` has the same effect as + + \pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm); + + \pgfpathmoveto{\pgfpoint{2cm}{5mm}} + \pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharcaxes" + }, + pgfpatharcto = { + arguments = { + {meta = "x-radius"}, + {meta = "y-radius"}, + {meta = "rotation"}, + {meta = "large arc flag"}, + {meta = "counterclockwise flag"}, + {meta = "target point"} + }, + details = [[ +This command (which directly corresponds to the arc-path command of SVG) +is used to add an arc to the path that starts at the current point and +ends at ⟨target point⟩. This arc is part of an ellipse that is +determined in the following way: Imagine an ellipse with radii +⟨x-radius⟩ and ⟨y-radius⟩ that is rotated around its center by +⟨rotation⟩ degrees. When you move this ellipse around in the plane, +there will be exactly two positions such that the two current point and +the target point lie on the border of the ellipse (excluding +pathological cases). The flags ⟨large arc flag⟩ and ⟨clockwise flag⟩ are +then used to decide which of these ellipses should be picked and which +arc on the picked ellipsis should be used. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfpathmoveto{\pgfpoint{0mm}{20mm}} + \pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +Both flags are considered to be false exactly if they evaluate to `0`, +otherwise they are true. If the ⟨large arc flag⟩ is true, then the angle +spanned by the arc will be greater than $180^\circ$, otherwise it will +be less than $180^\circ$. The ⟨clockwise flag⟩ is used to determine +which of the two ellipses should be used: if the flag is true, then the +arc goes from the current point to the target point in a +counterclockwise direction, otherwise in a clockwise fashion. + + \begin{tikzpicture} + \pgfsetlinewidth{2pt} + % Flags 0 0: red + \pgfsetstrokecolor{red} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 0 1: blue + \pgfsetstrokecolor{blue} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 1 0: orange + \pgfsetstrokecolor{orange} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + % Flags 1 1: black + \pgfsetstrokecolor{black} + \pgfpathmoveto{\pgfpointorigin} + \pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}} + \pgfusepath{stroke} + \end{tikzpicture} + +*Warning:* The internal computations necessary for this command are +numerically very unstable. In particular, the arc will not always really +end at the ⟨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 it works quite nicely is when the +resulting angle is a multiple of $90^\circ$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharcto" + }, + pgfpatharctomaxstepsize = { + details = [[ +The quality of arc approximation taken by `\pgfpatharctoprecomputed` by +means of Bézier splines is controlled by a mesh width, which is +initially + +`\def\pgfpatharctoprecomputed{45}`. + +The mesh width is provided in (full!) degrees. The smaller the mesh +width, the more precise the arc approximation. + +Use an empty value to disable spline approximation (uses a single cubic +polynomial for the complete arc). + +The value must be an integer! +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharctomaxstepsize" + }, + pgfpatharctoprecomputed = { + arguments = { + {meta = "center point"}, + {meta = "start angle"}, + {meta = "end angle"}, + {meta = "end point"}, + {meta = "x-radius"}, + {meta = "y-radius"}, + {meta = "ratio x-radius/y-radius"}, + {meta = "ratio y-radius/x-radius"} + }, + details = [[ +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 `\pgfpatharcto`, this routine is numerically stable and +quite fast since it relies on a lot of available information. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \def\cx{1.5cm}% center x + \def\cy{1cm}% center y + \def\startangle{0}% + \def\endangle{270}% + \def\a{1.5cm}% xradius + \def\b{0.5cm}% yradius + \pgfmathparse{\a/\b}\let\abratio=\pgfmathresult + \pgfmathparse{\b/\a}\let\baratio=\pgfmathresult + % + % start point: + \pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}% + \pgfpatharctoprecomputed + {\pgfpoint{\cx}{\cy}} + {\startangle} + {\endangle} + {\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point + {\a} + {\b} + {\abratio} + {\baratio} + \pgfusepath{draw} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpatharctoprecomputed" + }, + pgfpathcircle = { + arguments = {{meta = "center"}, {meta = "radius"}}, + details = [[ +A shorthand for `\pgfpathellipse` applied to ⟨center⟩ and the two axis +vectors $(⟨radius⟩,0)$ and $(0,⟨radius⟩)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcircle" + }, + pgfpathclose = { + details = [[ +This command closes the current part of the path by appending a straight +line to the start point of the current part. Note that there *is* a +difference between closing a path and using the line-to operation to add +a straight line to the start of the current path. The difference is +demonstrated by the upper corners of the triangles in the following +example: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfsetlinewidth{5pt} + \pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{0cm}{-1cm}} + \pgfpathlineto{\pgfpoint{1cm}{-1cm}} + \pgfpathclose + \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}} + \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}} + \pgfpathlineto{\pgfpoint{2.5cm}{1cm}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathclose" + }, + pgfpathcosine = { + arguments = {{meta = "vector"}}, + details = [[ +This command appends a cosine curve in the interval $[0,\pi/2]$ to the +current path. The curve is squeezed or stretched such that the curve +starts at the current point and ends at the current point plus ⟨vector⟩. +Using several sine and cosine operations in sequence allows you to +produce a complete sine or cosine curve + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpoint{0cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfpathcosine{\pgfpoint{1cm}{-1cm}} + \pgfpathsine{\pgfpoint{1cm}{-1cm}} + \pgfpathcosine{\pgfpoint{1cm}{1cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcosine" + }, + pgfpathcurvebetweentime = { + arguments = { + {meta = "time $t_1$"}, + {meta = "time $t_2$"}, + {meta = "point p"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point q"} + }, + details = [[ +This command draws the part of the curve described by $p$, $s_1$, $s_2$ +and $q$ between the times $t_1$ and $t_2$. A time value of 0 indicates +the point $p$ and a time value of 1 indicates point $q$. This command +includes a moveto operation to the first point. + + \begin{tikzpicture} + \draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2); + \pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}} + {\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}} + \pgfsetstrokecolor{red} + \pgfsetstrokeopacity{0.5} + \pgfsetlinewidth{2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurvebetweentime" + }, + pgfpathcurvebetweentimecontinue = { + arguments = { + {meta = "time $t_1$"}, + {meta = "time $t_2$"}, + {meta = "point p"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point q"} + }, + details = [[ +This command works like `\pgfpathcurvebetweentime`, except that a moveto +operation is *not* made to the first point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurvebetweentimecontinue" + }, + pgfpathcurveto = { + arguments = {{meta = "support 1"}, {meta = "support 2"}, {meta = "coordinate"}}, + details = [[ +This command extends the current path with a Bézier curve from the last +point of the path to ⟨coordinate⟩. The ⟨support 1⟩ and ⟨support 2⟩ are +the first and second support point of the Bézier curve. For more +information on Bézier curves, please consult a standard textbook on +computer graphics. + +Like the line-to command, this command may not be the first path +construction command in a path. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +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 ⟨coordinate⟩. This +will guarantee that the curve is completely inside the bounding box, but +the bounding box will typically be quite a bit too large. It is not +clear (to me) how this can be avoided without resorting to "some serious +math" in order to calculate a precise bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathcurveto" + }, + pgfpathellipse = { + arguments = {{meta = "center"}, {meta = "first axis"}, {meta = "second axis"}}, + details = [[ +The effect of this command is to append an ellipse to the current path +(if the path is not empty, a new part is started). The ellipse's center +will be ⟨center⟩ and ⟨first axis⟩ and ⟨second axis⟩ are the axis +*vectors*. The same effect as this command can also be achieved using an +appropriate sequence of move-to, arc, and close operations, but this +command is easier and faster. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1.5cm}{0cm}} + {\pgfpoint{0cm}{1cm}} + \pgfusepath{draw} + \color{red} + \pgfpathellipse{\pgfpoint{1cm}{0cm}} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{-0.5cm}{0.5cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations to all coordinates of +the ellipse. However, the coordinate transformations are applied only +after the ellipse is "finished conceptually". Thus, a transformation of +1cm to the right will simply shift the ellipse one centimeter to the +right; it will not add 1cm to the $x$-coordinates of the two axis +vectors. + +The command will update the bounding box of the current path and +picture, if necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathellipse" + }, + pgfpathgrid = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "first corner"}, + {meta = "second corner"} + }, + details = [[ +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 ⟨first corner⟩ and the ⟨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. + +The following keys influence the grid: + + \begin{pgfpicture} + \pgfsetlinewidth{0.8pt} + \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}] + {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{0.4pt} + \pgfpathgrid[stepx=1mm,stepy=1mm] + {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}} + \pgfusepath{stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. As for ellipses, the transformations are applied to the +"conceptually finished" grid. + + \begin{pgfpicture} + \pgftransformrotate{10} + \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathgrid" + }, + pgfpathlineto = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command extends the current path in a straight line to the given +⟨coordinate⟩. If this command is given at the beginning of path without +any other path construction command given before (in particular without +a move-to operation), the TeX file may compile without an error message, +but a viewer application may display an error message when trying to +render the picture. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +It will update the bounding box of the current path and picture, if +necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathlineto" + }, + pgfpathmoveto = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command expects a PGF-coordinate like `\pgfpointorigin` as its +parameter. When the current path is empty, this operation will start the +path at the given ⟨coordinate⟩. If a path has already been partly +constructed, this command will end the current part of the path and +start a new one. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}} + \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part + \pgfpathlineto{\pgfpoint{3cm}{0.5cm}} + \pgfpathlineto{\pgfpoint{3cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +The command will apply the current coordinate transformation matrix to +⟨coordinate⟩ before using it. + +It will update the bounding box of the current path and picture, if +necessary. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathmoveto" + }, + pgfpathparabola = { + arguments = {{meta = "bend vector"}, {meta = "end vector"}}, + details = [[ +This command appends two half-parabolas to the current path. The first +starts at the current point and ends at the current point plus ⟨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 ⟨end +vector⟩. + +If you set ⟨end vector⟩ to the null vector, you append only a half +parabola that goes from the current point to the bend; by setting ⟨bend +vector⟩ to the null vector, you append only a half parabola that goes +through the current point and ⟨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 that +does not contain the bend. + + \begin{pgfpicture} + % Half-parabola going ``up and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}} + \color{red} + \pgfusepath{stroke} + + % Half-parabola going ``down and right'' + \pgfpathmoveto{\pgfpointorigin} + \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin} + \color{blue} + \pgfusepath{stroke} + + % Full parabola + \pgfpathmoveto{\pgfpoint{-2cm}{2cm}} + \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}} + \color{orange} + \pgfusepath{stroke} + \end{pgfpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathparabola" + }, + pgfpathqcircle = { + arguments = {{meta = "radius"}}, + details = [[ +Adds a radius around the origin of the given ⟨radius⟩. This command is +orders of magnitude faster than +`\pgfcircle{\pgfpointorigin}{`⟨radius⟩`}`. + + \colorlet{examplefill}{yellow!80!black} + \begin{tikzpicture} + \draw[help lines] (0,0) grid (1,1); + \pgfpathqcircle{10pt} + \pgfsetfillcolor{examplefill} + \pgfusepath{stroke,fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqcircle" + }, + pgfpathqcurveto = { + arguments = { + {meta = "$s^1_x$"}, + {meta = "$s^1_y$"}, + {meta = "$s^2_x$"}, + {meta = "$s^2_y$"}, + {meta = "$t_x$"}, + {meta = "$t_y$"} + }, + details = [[ +The quick version of the curve-to operation. The first support point is +$(s^1_x,s^1_y)$, the second support point is $(s^2_x,s^2_y)$, and the +target is $(t_x,t_y)$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathqmoveto{0pt}{0pt} + \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqcurveto" + }, + pgfpathqlineto = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +The quick version of the line-to operation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqlineto" + }, + pgfpathqmoveto = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Either starts a path or starts a new part of a path at the coordinate +$(⟨x dimension⟩,⟨y dimension⟩)$. The coordinate is *not* transformed by +the current coordinate transformation matrix. However, any low-level +transformations apply. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformxshift{1cm} + \pgfpathqmoveto{0pt}{0pt} % not transformed + \pgfpathqlineto{1cm}{1cm} % not transformed + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathqmoveto" + }, + pgfpathquadraticcurveto = { + arguments = {{meta = "support"}, {meta = "coordinate"}}, + details = [[ +This command works like `\pgfpathcurveto`, only it uses a quadratic +Bézier curve rather than a cubic one. This means that only one support +point is needed. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathquadraticcurveto + {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}} + \pgfsetfillcolor{yellow!80!black} + \pgfusepath{fill,stroke} + \end{pgfpicture} + +Internally, the quadratic curve is converted into a cubic curve. The +only noticeable effect of this is that the points used for computing the +bounding box are the control points of the converted curve rather than +⟨support⟩. The main effect of this is that the bounding box will be a +bit tighter than might be expected. In particular, ⟨support⟩ will not +always be part of the bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathquadraticcurveto" + }, + pgfpathrectangle = { + arguments = {{meta = "corner"}, {meta = "diagonal vector"}}, + details = [[ +Adds a rectangle to the path whose one corner is ⟨corner⟩ and whose +opposite corner is given by $⟨corner⟩ + ⟨diagonal vector⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes tightly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathrectangle" + }, + pgfpathrectanglecorners = { + arguments = {{meta = "corner"}, {meta = "opposite corner"}}, + details = [[ +Adds a rectangle to the path whose two opposing corners are ⟨corner⟩ and +⟨opposite corner⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}} + \pgfusepath{draw} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes tightly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathrectanglecorners" + }, + pgfpathsine = { + arguments = {{meta = "vector"}}, + details = [[ +This command appends a sine curve in the interval $[0,\pi/2]$ to the +current path. The sine curve is squeezed or stretched such that the +curve starts at the current point and ends at the current point plus +⟨vector⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,1); + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + + \color{red} + \pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathsine{\pgfpoint{-2cm}{-2cm}} + \pgfusepath{stroke} + \end{tikzpicture} + +The command will apply coordinate transformations and update the +bounding boxes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathsine" + }, + pgfpathsvg = { + arguments = {{meta = "path"}}, + details = [[ +This command extends the current path by a ⟨path⟩ given in the +SVG-path-data syntax. This syntax is described in detail in Section 8.3 +of the SVG-specification, Version 1.1. + +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 are, +however, a few things to be aware of: + +- The computation underlying the arc commands `A` and `a` are not + numerically stable, which may result in quite imprecise arcs. Bézier + curves, both quadratic and cubic, are not affected, neither are arcs + spanning degrees that are multiples of $90^{\circ}$. + +- The dimensionless units of SVG are always interpreted 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 16 000 points. + +- All coordinate and canvas transformations apply to the path in the + usual fashion. + +- The `\pgfpathsvg` command can be freely intermixed with other path + commands. + +  + + \begin{pgfpicture} + \pgfpathsvg{M 0 0 l 20 0 0 20 -20 0 q 10 0 10 10 + t 10 10 10 10 h -50 z} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpathsvg" + }, + pgfplotbarwidth = { + details = [[ +Expands to the value of `/pgf/bar width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotbarwidth" + }, + pgfplotfunction = { + arguments = {{meta = "variable"}, {meta = "sample list"}, {meta = "point"}}, + details = [[ +This command will produce coordinates by iterating the ⟨variable⟩ over +all values in ⟨sample list⟩, which should be a list in the `\foreach` +syntax. For each value of ⟨variable⟩, the ⟨point⟩ is evaluated and the +resulting coordinate is inserted into the plot stream. + + \begin{tikzpicture}[x=3.8cm/360] + \pgfplothandlerlineto + \pgfplotfunction{\x}{0,5,...,360}{\pgfpointxy{\x}{sin(\x)+sin(3*\x)}} + \pgfusepath{stroke} + \end{tikzpicture} + + \begin{tikzpicture}[y=3cm/360] + \pgfplothandlerlineto + \pgfplotfunction{\y}{0,5,...,360}{\pgfpointxyz{sin(2*\y)}{\y}{cos(2*\y)}} + \pgfusepath{stroke} + \end{tikzpicture} + +Be warned that if the expressions that need to evaluated for each point +are complex, then this command can be very slow. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotfunction" + }, + pgfplotgnuplot = { + arguments = { + {delimiters = {"[", "]"}, meta = "prefix", optional = true}, + {meta = "function"} + }, + details = [[ +This command will "try" to call the GNUPLOT program to generate the +coordinates of the ⟨function⟩. In detail, the following happens: + +This command works with two files: ⟨prefix⟩`.gnuplot` and +⟨prefix⟩`.table`. If the optional argument ⟨prefix⟩ is not given, it is +set to `\jobname`. + +Let us start with the situation where none of these files exists. Then +PGF will first generate the file ⟨prefix⟩`.gnuplot`. In this file it +writes + + set table "#1.table"; set format "%.5f" + +where `# 1` is replaced by ⟨prefix⟩. Then, in a second line, it writes +the text ⟨function⟩. + +Next, PGF will try to invoke the program `gnuplot` with the argument +⟨prefix⟩`.gnuplot`. This call may or may not succeed, depending on +whether the `\write18` mechanism (also known as shell escape) is +switched on and whether the `gnuplot` program is available. + +Assuming that the call succeeded, the next step is to invoke +`\pgfplotxyfile` on the file ⟨prefix⟩`.table`; which is exactly the file +that has just been created by `gnuplot`. + + \begin{tikzpicture} + \draw[help lines] (0,-1) grid (4,1); + \pgfplothandlerlineto + \pgfplotgnuplot[plots/pgfplotgnuplot-example]{plot [x=0:3.5] x*sin(x)} + \pgfusepath{stroke} + \end{tikzpicture} + +The more difficult situation arises when the `.gnuplot` file exists, +which will be the case on the second run of TeX on the TeX file. In this +case PGF will read this file and check whether it contains exactly what +PGF "would have written" into this file. If this is not the case, the +file contents is overwritten with what "should be there" and, as above, +`gnuplot` is invoked to generate a new `.table` file. However, if the +file contents is "as expected", the external `gnuplot` program is *not* +called. Instead, the ⟨prefix⟩`.table` file is immediately read. + +As explained in Section ??, the net effect 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotgnuplot" + }, + pgfplothandlerclosedcurve = { + details = [[ +This handler works like the curve-to plot handler, only it will add a +new part to the current path that is a closed curve through the plot +points. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerclosedcurve + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerclosedcurve" + }, + pgfplothandlerconstantlineto = { + details = [[ +This handler works like the line-to plot handler, only it will produce a +connected, piecewise constant path to connect the points. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlineto" + }, + pgfplothandlerconstantlinetomarkmid = { + details = [[ +A variant of `\pgfplothandlerconstantlineto` which places its mark on +the center of the line. + + \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} + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlinetomarkmid" + }, + pgfplothandlerconstantlinetomarkright = { + details = [[ +A variant of `\pgfplothandlerconstantlineto` which places its mark on +the right line ends. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerconstantlinetomarkright + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerconstantlinetomarkright" + }, + pgfplothandlercurveto = { + details = [[ +This handler will issue a `\pgfpathcurveto` command for each point of +the plot, *except* possibly for the first. As for the line-to handler, +what happens with the first point can be specified using +`\pgfsetmovetofirstplotpoint` or `\pgfsetlinetofirstplotpoint`. + +Obviously, the `\pgfpathcurveto` command needs, in addition to the +points on the path, some control points. These are generated +automatically using a somewhat "dumb" algorithm: Suppose you have three +points $x$, $y$, and $z$ on the curve such that $y$ is between $x$ and +$z$: + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +In order to determine the control points of the curve at the point $y$, +the handler computes the vector $z-x$ and scales it by the tension +factor (see below). Let us call the resulting vector $s$. Then $y+s$ and +$y-s$ will be the control points around $y$. The first control point at +the beginning of the curve will be the beginning itself, once more; +likewise the last control point is the end itself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlercurveto" + }, + pgfplothandlerdiscard = { + details = [[ +This handler will simply throw away the stream. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerdiscard" + }, + pgfplothandlergapcycle = { + details = [[ +Works like `\pgfplothandlergaplineto`, but the last point is connected +to the first in the same fashion: + + \begin{tikzpicture} + \pgfplothandlergapcycle + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlergapcycle" + }, + pgfplothandlergaplineto = { + details = [[ +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{tikzpicture} + \pgfplothandlergaplineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlergaplineto" + }, + pgfplothandlerjumpmarkleft = { + details = [[ +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. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkleft + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkleft" + }, + pgfplothandlerjumpmarkmid = { + details = [[ +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{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} + +See `\pgfplothandlerconstantlinetomarkmid` for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkmid" + }, + pgfplothandlerjumpmarkright = { + details = [[ +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 right open pieces. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerjumpmarkright + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerjumpmarkright" + }, + pgfplothandlerlineto = { + details = [[ +This handler will issue a `\pgfpathlineto` command for each point of the +plot, *except* possibly for the first. What happens with the first point +can be specified using the two commands described below. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerlineto" + }, + pgfplothandlermark = { + arguments = {{meta = "mark code"}}, + details = [[ +This command will execute the ⟨mark code⟩ for some points of the plot, +but each time the coordinate transformation matrix will be set up such +that the origin is at the position of the point to be plotted. This way, +if the ⟨mark code⟩ draws a little circle around the origin, little +circles will be drawn at some point of the plot. + +By default, a mark is drawn at all points of the plot. However, two +parameters $r$ and $p$ influence this. First, only every $r$th mark is +drawn. Second, the first mark drawn is the $p$th. These parameters can +be influenced using the commands below. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +Typically, the ⟨code⟩ will be `\pgfuseplotmark{`⟨plot mark name⟩`}`, +where ⟨plot mark name⟩ is the name of a predefined plot mark. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlermark" + }, + pgfplothandlermarklisted = { + arguments = {{meta = "mark code"}, {meta = "index list"}}, + details = [[ +This command works similar to the previous one. However, marks will only +be placed at those indices in the given ⟨index list⟩. The syntax for the +list is the same as for the `\foreach` statement. For example, if you +provide the list `1,3,...,25`, a mark will be placed only at every +second point. Similarly, `1,2,4,8,16,32` yields marks only at those +points that are powers of two. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermarklisted + {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}} + {1,3} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlermarklisted" + }, + pgfplothandlerpolarcomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +origin to the point's coordinate. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerpolarcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerpolarcomb" + }, + pgfplothandlerpolygon = { + details = [[ +This handler works like the line-to plot handler, only the line is +closed at the end using `\pgfpathclose`, resulting in a polygon. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerpolygon" + }, + pgfplothandlerrecord = { + arguments = {{meta = "macro"}}, + details = [[ +When this handler is installed, each time a plot stream command is +called, this command will be appended to ⟨macro⟩. Thus, at the end of +the stream, ⟨macro⟩ will contain all the commands that were issued on +the stream. You can then install another handler and invoke ⟨macro⟩ to +"replay" the stream (possibly many times). + + \begin{pgfpicture} + \pgfplothandlerrecord{\mystream} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfplothandlerlineto + \mystream + \pgfplothandlerclosedcurve + \mystream + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerrecord" + }, + pgfplothandlerxbar = { + details = [[ +This handler converts each point in the plot stream into a rectangle +from the $y$-axis to the point's coordinate. The rectangle is placed +centered at the $y$-axis. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxbar + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxbar" + }, + pgfplothandlerxbarinterval = { + details = [[ +As `\pgfplothandlerybarinterval`, this handler provides bar plots with +relative bar sizes and offsets, one bar for each $y$ coordinate +interval. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxbarinterval" + }, + pgfplothandlerxcomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +$y$-axis to the point's coordinate, resulting in a "horizontal comb". + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerxcomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerxcomb" + }, + pgfplothandlerybar = { + details = [[ +This handler converts each point in the plot stream into a rectangle +from the $x$-axis to the point's coordinate. The rectangle is placed +centered at the $x$-axis. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerybar + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerybar" + }, + pgfplothandlerybarinterval = { + details = [[ +This handler is a variant of `\pgfplothandlerybar` which works with +intervals instead of points. + +Bars are drawn between successive input coordinates and the width is +determined relatively to the interval length. + + \begin{tikzpicture} + \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$}; + \pgfplothandlerybarinterval + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} + +In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote successive +input coordinates, the bar will be placed above the interval +$[x_i,x_{i+1}]$, centered at +$$x_i + ⟨bar interval shift⟩ \cdot (x_{i+1} - x_i)$$ with width +$$⟨bar interval width⟩ \cdot (x_{i+1} - x_i).$$ Here, ⟨bar interval +shift⟩ and ⟨bar interval width⟩ denote the current values of the +associated options. + +If you have $N+1$ input points, you will get $N$ bars (one for each +interval). The $y$ value of the last point will be ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerybarinterval" + }, + pgfplothandlerycomb = { + details = [[ +This handler converts each point in the plot stream into a line from the +$x$-axis to the point's coordinate, resulting in a "vertical comb". + +This handler is useful for creating "bar diagrams". + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlerycomb + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplothandlerycomb" + }, + pgfplotstreamend = { + details = [[ +This command signals that a plot stream ends. It calls +`\pgf@plotstreamend`, which should now do any necessary "cleanup". +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamend" + }, + pgfplotstreamnewdataset = { + details = [[ +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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamnewdataset" + }, + pgfplotstreampoint = { + arguments = {{meta = "point"}}, + details = [[ +This command adds a ⟨point⟩ to the current plot stream. The effect of +this command is to call the internal command `\pgf@plotstreampoint`, +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampoint" + }, + pgfplotstreampointoutlier = { + arguments = {{meta = "point"}}, + details = [[ +An *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 GNUPLOT +when a value is outside the specified range. + +You can configure how outliers are treated using the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampointoutlier" + }, + pgfplotstreampointundefined = { + details = [[ +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 *can* result in a jump in the plot, depending on +the setting of the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreampointundefined" + }, + pgfplotstreamspecial = { + arguments = {{meta = "text"}}, + details = [[ +This command causes `\pgf@plotstreamspecial` to be called with ⟨text⟩ as +its parameter. This allows handler-specific information to be passed to +the handler. All normal handlers ignore this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamspecial" + }, + pgfplotstreamstart = { + details = [[ +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. 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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotstreamstart" + }, + pgfplotxyfile = { + arguments = {{meta = "filename"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxyfile" + }, + pgfplotxyzfile = { + arguments = {{meta = "filename"}}, + details = [[ +This command works like `\pgfplotxyfile`, only *three* numbers are +expected on each non-empty line. They are converted into points in the +$xyz$-coordinate system. Consider, the following file: + + % Some comments + # more comments + 2 -5 1 first entry + 2 -.2 2 o + 2 -5 2 third entry + +It is turned into the following stream: + + \pgfplotstreamstart + \pgfplotstreamnewdataset + \pgfplotstreamnewdataset + \pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}} + \pgfplotstreampointoutlier{\pgfpointxyz{2}{-.2}{2}} + \pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}} + \pgfplotstreamend +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxyzfile" + }, + pgfplotxzerolevelstreamconstant = { + arguments = {{meta = "dimension"}}, + details = [[ +This zero level stream always returns `{dimension}` instead of $x=0$pt. + +It is used for `xcomb` and `xbar`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotxzerolevelstreamconstant" + }, + pgfplotyzerolevelstreamconstant = { + arguments = {{meta = "dimension"}}, + details = [[ +This zero level stream always returns `{dimension}` instead of $y=0$pt. + +It is used for `ycomb` and `ybar`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfplotyzerolevelstreamconstant" + }, + pgfpoint = { + arguments = {{meta = "x coordinate"}, {meta = "y coordinate"}}, + details = [[ +Yields a point location. The coordinates are given as TeX dimensions. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt} + \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt} + \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpoint" + }, + pgfpointadd = { + arguments = {{meta = "$v_1$"}, {meta = "$v_2$"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointadd" + }, + pgfpointanchor = { + arguments = {{meta = "node"}, {meta = "anchor"}}, + details = [[ +This command is another "point command" like the commands described in +Section ??. It returns the coordinate of the given ⟨anchor⟩ in the given +⟨node⟩. The command can be used in commands like `\pgfpathmoveto`. + + \begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +In the above example, you may have noticed something curious: The +rotation transformation is still in force when the anchors are invoked, +but it does not seem to have an effect. You might expect that the +rotation should apply to the already rotated points once more. + +However, `\pgfpointanchor` returns a point that takes the current +transformation matrix into account: *The inverse transformation to the +current coordinate transformation is applied to an anchor point before +returning it.* + +This behavior may seem a bit strange, but you will find it very natural +in most cases. If you really want to apply a transformation to an anchor +point (for example, to "shift it away" a little bit), you have to invoke +`\pgfpointanchor` without any transformations in force. Here is an +example: + + \begin{pgfpicture} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + + { + \pgftransformreset + \pgfpointanchor{x}{east} + \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}} + } + + \pgfpathcircle{\mycoordinate}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +A special situation arises when the ⟨node⟩ lies in a picture different +from the current picture. In this case, if you have not told PGF that +the picture should be "remembered", the ⟨node⟩ will be treated as if it +lay in the current picture. For example, if the ⟨node⟩ was at position +$(3,2)$ in the original picture, it is treated as if it lay at position +$(3,2)$ in the current picture. However, if you have told PGF to +remember the picture position of the node's picture and also of the +current picture, then `\pgfpointanchor` will return a coordinate that +corresponds to the position of the node's anchor on the page, +transformed into the current coordinate system. For examples and more +details see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointanchor" + }, + pgfpointarcaxesattime = { + arguments = { + {meta = "time $t$"}, + {meta = "center"}, + {meta = "0-degree axis"}, + {meta = "90-degree axis"}, + {meta = "start angle"}, + {meta = "end angle"} + }, + details = [[ +Yields a point on the arc between ⟨start angle⟩ and ⟨end angle⟩ on an +ellipse whose center is at ⟨center⟩ and whose two principal axes are +⟨0-degree axis⟩ and ⟨90-degree axis⟩. For $t=0$ the point at the ⟨start +angle⟩ is returned and for $t=1$ the point at the ⟨end angle⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointarcaxesattime" + }, + pgfpointborderellipse = { + arguments = {{meta = "direction point"}, {meta = "corner"}}, + details = [[ +This command works like the corresponding command for rectangles, only +this time the ⟨corner⟩ is the corner of the bounding rectangle of an +ellipse. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointborderellipse" + }, + pgfpointborderrectangle = { + arguments = {{meta = "direction point"}, {meta = "corner"}}, + details = [[ +This command returns a point that lies on the intersection of a line +starting at the origin and going towards the point ⟨direction point⟩ and +a rectangle whose center is in the origin and whose upper right corner +is at ⟨corner⟩. + +The ⟨direction point⟩ should have length "about 1pt", but it will be +normalized automatically. Nevertheless, the "nearer" the length is to +1pt, the less rounding errors. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointborderrectangle" + }, + pgfpointcurveattime = { + arguments = { + {meta = "time $t$"}, + {meta = "point $p$"}, + {meta = "point $s_1$"}, + {meta = "point $s_2$"}, + {meta = "point $q$"} + }, + details = [[ +Yields a point that is on the Bézier 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$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{3cm}{2cm}}]{\t}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurveattime" + }, + pgfpointcurvilinearbezierorthogonal = { + arguments = {{meta = "distance"}, {meta = "offset"}}, + details = [[ +This command computes the following point: Consider the curve last +installed using the command `\pgfsetcurvilinearbeziercurve`. We travel +along this curve by ⟨distance⟩, arriving at a point $p$. Then, we turn +by $90^\circ$ and travel by ⟨offset⟩ units "always 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. + + \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} + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurvilinearbezierorthogonal" + }, + pgfpointcurvilinearbezierpolar = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +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 +$\texttt{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. + + \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} + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcurvilinearbezierpolar" + }, + pgfpointcylindrical = { + arguments = {{meta = "degree"}, {meta = "radius"}, {meta = "height"}}, + details = [[ +This command yields the same as + + \pgfpointadd{\pgfpointpolarxy{degree}{radius}}{\pgfpointxyz{0}{0}{height}} + + \begin{tikzpicture} + \draw [->] (0,0) -- (1,0,0) node [right] {$x$}; + \draw [->] (0,0) -- (0,1,0) node [above] {$y$}; + \draw [->] (0,0) -- (0,0,1) node [below left] {$z$}; + + \pgfpathcircle{\pgfpointcylindrical{80}{1}{.5}}{2pt} + \pgfusepath{fill} + + \draw[red] (0,0) -- (0,0,.5) -- +(80:1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointcylindrical" + }, + pgfpointdecoratedinputsegmentlast = { + details = [[ +The final point of the current input segment of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedinputsegmentlast" + }, + pgfpointdecoratedpathfirst = { + details = [[ +Returns the point corresponding to the start of the current input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedpathfirst" + }, + pgfpointdecoratedpathlast = { + details = [[ +The final point of the input path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecoratedpathlast" + }, + pgfpointdecorationpathlast = { + details = [[ +The final point of the output path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdecorationpathlast" + }, + pgfpointdiff = { + arguments = {{meta = "start"}, {meta = "end"}}, + details = [[ +Returns the difference vector $⟨end⟩ - ⟨start⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointdiff" + }, + pgfpointintersectionofcircles = { + arguments = { + {meta = "$p_1$"}, + {meta = "$p_2$"}, + {meta = "$r_1$"}, + {meta = "$r_2$"}, + {meta = "solution"} + }, + details = [[ +This command returns the intersection of the two circles centered at +$p_1$ and $p_2$ with radii $r_1$ and $r_2$. If ⟨solution⟩ is `1`, the +first intersection is returned, otherwise the second one is returned. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (0.5,0) circle (1); + \draw (1.5,1) circle (.8); + \pgfpathcircle{% + \pgfpointintersectionofcircles + {\pgfpointxy{.5}{0}}{\pgfpointxy{1.5}{1}} + {1cm}{0.8cm}{1}} + {2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionofcircles" + }, + pgfpointintersectionoflines = { + arguments = {{meta = "$p$"}, {meta = "$q$"}, {meta = "$s$"}, {meta = "$t$"}}, + details = [[ +This command returns the intersection of a line going through $p$ and +$q$ and a line going through $s$ and $t$. If the lines do not +intersection, an arithmetic overflow will occur. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (.5,0) -- (2,2); + \draw (1,2) -- (2,0); + \pgfpathcircle{% + \pgfpointintersectionoflines + {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}} + {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}} + {2pt} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionoflines" + }, + pgfpointintersectionsolution = { + arguments = {{meta = "number"}}, + details = [[ +After using the `\pgfintersectionofpaths` command, this command will +return the point for solution ⟨number⟩ or the origin if this solution +was not found. By default, the intersections are simply returned in the +order that the intersection algorithm finds them. Unfortunately, this is +not necessarily a "helpful" ordering. However the following two commands +can be used to order the solutions more helpfully. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointintersectionsolution" + }, + pgfpointlineatdistance = { + arguments = {{meta = "distance"}, {meta = "start point"}, {meta = "end point"}}, + details = [[ +Yields a point that is located ⟨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 ⟨distance⟩ steps from ⟨start point⟩ +towards ⟨end point⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \d in {0pt,20pt,40pt,70pt} + {\pgftext[at= + \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointlineatdistance" + }, + pgfpointlineattime = { + arguments = {{meta = "time $t$"}, {meta = "point $p$"}, {meta = "point $q$"}}, + details = [[ +Yields a point that is the $t$th fraction between $p$ and $q$, that is, +$p + + t(q-p)$. For $t=1/2$ this is the middle of $p$ and $q$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,...,1.25} + {\pgftext[at= + \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointlineattime" + }, + pgfpointmetadecoratedpathfirst = { + details = [[ +When the ⟨before code⟩ is executed, this macro stores the first point on +the current sub-input-path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointmetadecoratedpathfirst" + }, + pgfpointmetadecoratedpathlast = { + details = [[ +When the ⟨after code⟩ is executed, this macro stores the last point on +the current sub-input-path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointmetadecoratedpathlast" + }, + pgfpointnormalised = { + arguments = {{meta = "point"}}, + details = [[ +This command returns a normalised version of ⟨point⟩, that is, a vector +of length 1pt pointing in the direction of ⟨point⟩. If ⟨point⟩ is the +$0$-vector or extremely short, a vector of length 1pt pointing upwards +is returned. + +This command is *not* implemented by calculating the length of the +vector, but rather by calculating the angle of the vector and then using +(something equivalent to) the `\pgfpointpolar` command. This ensures +that the point will really have length 1pt, but it is not guaranteed +that the vector will *precisely* point in the direction of ⟨point⟩ due +to the fact that the polar tables are accurate only up to one degree. +Normally, this is not a problem. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointscale{20} + {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointnormalised" + }, + pgfpointorigin = { + details = [[ +Yields the origin. Same as `\pgfpoint{0pt}{0pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointorigin" + }, + pgfpointpolar = { + arguments = { + {meta = "degree"}, + {literal = "{"}, + {meta = "radius"}, + {literal = "/"}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +Yields a point location given in polar coordinates. You can specify the +angle only in degrees, radians are not supported, currently. + +If the optional ⟨y-radius⟩ is given, the polar coordinate is actually a +coordinate on an ellipse whose $x$-radius is given by ⟨radius⟩ and whose +$y$-radius is given by ⟨y-radius⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}} + \pgfusepath{fill} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm and 2cm}}{2pt}} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointpolar" + }, + pgfpointpolarxy = { + arguments = { + {meta = "degree"}, + {literal = "{"}, + {meta = "radius"}, + {literal = "/"}, + {meta = "y-radius"}, + {literal = "}"} + }, + details = [[ +This command is similar to the `\pgfpointpolar` command, but the +⟨radius⟩ is now a factor to be interpreted in the $xy$-coordinate +system. This means that a degree of `0` is the same as the $x$-vector of +the $xy$-coordinate system times ⟨radius⟩ and a degree of `90` is the +$y$-vector times ⟨radius⟩. As for `\pgfpointpolar`, a ⟨radius⟩ can also +be a pair separated by a slash. In this case, the $x$- and $y$-vectors +are multiplied by different factors. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \begin{scope}[x={(1cm,-5mm)},y=1.5cm] + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolarxy{\angle}{1}}{2pt}} + \pgfusepath{fill} + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointpolarxy" + }, + pgfpointscale = { + arguments = {{meta = "factor"}, {meta = "coordinate"}}, + details = [[ +Returns the vector $⟨factor⟩⟨coordinate⟩$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointscale" + }, + pgfpointshapeborder = { + arguments = {{meta = "node"}, {meta = "point"}}, + details = [[ +This command returns the point on the border of the shape that lies on a +straight line from the center of the node to ⟨point⟩. For complex shapes +it is not guaranteed that this point will actually lie on the border, it +may be on the border of a "simplified" version of the shape. + + \begin{pgfpicture} + \begin{pgfscope} + \pgftransformrotate{30} + \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}} + \end{pgfscope} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt} + \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt} + \pgfusepath{fill} + \end{pgfpicture} + +*Remark:* If the given ⟨point⟩ is almost identical to the center of +⟨node⟩, the node center is returned and a warning message will be +printed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointshapeborder" + }, + pgfpointspherical = { + arguments = {{meta = "longitude"}, {meta = "latitude"}, {meta = "radius"}}, + details = [[ +This command yields a point "on the surface of the earth" specified by +the ⟨longitude⟩ and the ⟨latitude⟩. The radius of the earth is given by +⟨radius⟩. The equator lies in the $xy$-plane. + + \begin{tikzpicture} + \pgfsetfillcolor{lightgray} + + \foreach \latitude in {-90,-75,...,30} + { + \foreach \longitude in {0,20,...,360} + { + \pgfpathmoveto{\pgfpointspherical{\longitude}{\latitude}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude+15}{1}} + \pgfpathlineto{\pgfpointspherical{\longitude}{\latitude+15}{1}} + \pgfpathclose + } + \pgfusepath{fill,stroke} + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointspherical" + }, + pgfpointtransformed = { + arguments = {{meta = "point"}}, + details = [[ +Applies current transformation matrix to `{point}` $(x,y)$ and returns a +transformed point $(ax+cy+s,bx+dy+t)$. Normally, this is done +automatically by commands like `\pgfpathlineto` or `\pgfpathmoveto`, but +sometimes you may wish to access a transformed point yourself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointtransformed" + }, + pgfpointtransformednonlinear = { + arguments = {{meta = "point"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointtransformednonlinear" + }, + pgfpointxy = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}}, + details = [[ +Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ +times the $y$-vector. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointxy" + }, + pgfpointxyz = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}, {meta = "$s_z$"}}, + details = [[ +Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ +times the $y$-vector plus $s_z$ times the $z$-vector. + + \begin{pgfpicture} + \pgfsetarrowsend{to} + + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{0}{1}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{1}{0}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{1}{0}{0}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpointxyz" + }, + pgfpoptype = { + details = [[ +Restores the most recent type from the internal global stack of types. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpoptype" + }, + pgfpositionnodelater = { + arguments = {{meta = "macro name"}}, + details = [[ +This command is not a replacement for `\pgfnode`. Rather, when this +command is used in a scope, all subsequent node creations in this scope +will be affected in the following way: When a node is created, it is not +inserted into the current picture. Instead, it is stored in the box +`\pgfpositionnodelaterbox`. Furthermore, the 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 ⟨macro name⟩ is called with the +following macros set up: + +Once a late node has been created, you can add arbitrary code in the +same picture. Then, at some later point, you call `\pgfpositionnodenow` +to finally position the node at a given position. At this point, the +above macros must have the exact same values they had when ⟨macro name⟩ +was called. Note that the above macros are local to a scope that ends +right after the call to ⟨macro name⟩, so it is your job to copy the +values to safety inside ⟨macro name⟩. + +The following two macros will also be set inside the call to ⟨macro +name⟩, but they are only "informative" in the sense that you need *not* +restore these macros when `\pgfpositionnodenow` is called. + +By setting ⟨macro name⟩ to `\relax` (which is the default), you can +switch off the whole mechanism. When a picture is interrupted, this is +done automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelater" + }, + pgfpositionnodelaterbox = { + details = [[ +A box register number (`0` currently) that stores the node's paths and +texts. You should move the contents of this box to a box of your choice +inside ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterbox" + }, + pgfpositionnodelatermaxx = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatermaxx" + }, + pgfpositionnodelatermaxy = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatermaxy" + }, + pgfpositionnodelaterminx = { + details = [[ +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. It is guaranteed, that this macro will contain a dimension in +the format ⟨number⟩`pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterminx" + }, + pgfpositionnodelaterminy = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterminy" + }, + pgfpositionnodelatername = { + details = [[ +The name of the just-created-node. This name will be the 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelatername" + }, + pgfpositionnodelaterpath = { + details = [[ +This macro stores the path of the background of the node. See Section ?? +for an overview of how these paths are encode. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodelaterpath" + }, + pgfpositionnodenow = { + arguments = {{meta = "coordinate"}}, + details = [[ +This command is used to position a node that has previously been 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 ⟨macro +name⟩ was called. Provided this is the case, this command will insert +the box into the current picture, shifted by ⟨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. + + \newbox\mybox + + \def\mysaver{ + \global\setbox\mybox=\box\pgfpositionnodelaterbox + \global\let\myname=\pgfpositionnodelatername + \global\let\myminx=\pgfpositionnodelaterminx + \global\let\myminy=\pgfpositionnodelaterminy + \global\let\mymaxx=\pgfpositionnodelatermaxx + \global\let\mymaxy=\pgfpositionnodelatermaxy + } + + \begin{tikzpicture} + { + \pgfpositionnodelater{\mysaver} + \node [fill=blue!20,below,rotate=30] (hi) {Hello world}; + } + \draw [help lines] (0,0) grid (3,2); + + \let\pgfpositionnodelatername=\myname + \let\pgfpositionnodelaterminx=\myminx + \let\pgfpositionnodelaterminy=\myminy + \let\pgfpositionnodelatermaxx=\mymaxx + \let\pgfpositionnodelatermaxy=\mymaxy + \setbox\pgfpositionnodelaterbox=\box\mybox + \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}} + + \draw (hi) -- (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpositionnodenow" + }, + pgfprofileend = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Stops (or interrupts) timing of ⟨profiler entry name⟩. + +This command finishes a preceding call to `\pgfprofilestart`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileend" + }, + pgfprofileifisrunning = { + arguments = { + {meta = "profiler entry name"}, + {meta = "true code"}, + {meta = "false code"} + }, + details = [[ +Invokes `{true code}` if `{profiler entry name}` is currently running +and `{false code}` otherwise. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileifisrunning" + }, + pgfprofilenew = { + arguments = {{meta = "name"}}, + details = [[ +Defines a new profiler entry named ⟨name⟩. + +This updates a set of internal registers used to track the profiler +entry. The ⟨name⟩ can be arbitrary, it doesn't need to be related to any +TeX macro. + +The actual job of counting seconds is accomplished using +`\pgfprofilestart``{name}` followed eventually by the command +`\pgfprofileend``{name}`. + +It doesn't hurt if `\pgfprofilenew` is called multiple times with the +same name. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenew" + }, + pgfprofilenewforcommand = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "\\textbackslash macro"}, + {meta = "arguments"} + }, + details = [[ +Defines a new profiler entry which will measure the time spent in +⟨\\macro⟩. This calls `\pgfprofilenew` and replaces the current +definition of ⟨\\macro⟩ with a new one. + +If `[profiler entry name]` has been provided, this defines the argument +for `\pgfprofilenew`. It is allowed to use the same name for multiple +commands; in this case, they are treated as if it where the same +command. If the optional argument is not used, the profiler entry will +be called '`\pgfprofilecs`⟨macro⟩' (⟨macro⟩ without backslash) where +`\pgfprofilecs` is predefined to be ``. + +The replacement macro will collect all required arguments, start +counting, invoke the original macro definition and stop counting. + +The following macro types are supported within +`\pgfprofilenewforcommand`: + +- commands which take one (optional) argument in square brackets + followed by one optional argument which has to be delimited by curly + braces (use an empty argument for ⟨arguments⟩ in this case), + +- commands which take one (optional) argument in square brackets and + *exactly* ⟨arguments⟩ arguments afterwards. + +Take a look at `\pgfprofilenewforcommandpattern` in case you have more +complicated commands. + +Note that the library can't detect if a command has been redefined +somewhere. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforcommand" + }, + pgfprofilenewforcommandpattern = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "\\textbackslash macro"}, + {meta = "argument pattern"}, + {meta = "invocation pattern"} + }, + details = [[ +A variant of `\pgfprofilenewforcommand` which can be used with arbitrary +⟨argument patterns⟩. Example: + + \def\mymacro#1\to#2\in#3{ ... } + \pgfprofilenewforcommandpattern{\mymacro}{#1\to#2\in#3}{{#1}\to{#2}\in{#3}} + +Note that `\pgfprofilenewforcommand` is a special case of +`\pgfprofilenewforcommandpattern`: + + \def\mymacro#1#2{ ... } + \pgfprofilenewforcommand\macro{2} + \pgfprofilenewforcommandpattern{\mymacro}{#1#2}{{#1}{#2}} + +Thus, ⟨argument pattern⟩ is a copy-paste from the definition of your +command. The ⟨invocation pattern⟩ is used by the `profiler` library to +invoke the *original* command, so it is closely related to ⟨argument +pattern⟩, but it needs extra curly braces around each argument. + +The behavior of `\pgfprofilenewforcommandpattern` is the same as +discussed above: it defines a new profiler entry which will measure the +time spent in ⟨\\macro⟩. The details about this definition has already +been described. Note that up to one optional argument in square brackets +is also checked automatically. + +If you like to profile a command which doesn't match here for whatever +reasons, you'll have to redefine it manually and insert +`\pgfprofilestart` and `\pgfprofileend` in appropriate places. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforcommandpattern" + }, + pgfprofilenewforenvironment = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "profiler entry name", + optional = true + }, + {meta = "environment name"} + }, + details = [[ +Defines a new profiler entry which measures time spent in the +environment ⟨environment name⟩. + +This calls `\pgfprofilenew` and handles the begin/end of the environment +automatically. + +The argument for `\pgfprofilenew` is ⟨profiler entry name⟩, or, if this +optional argument is not used, it is '`\pgfprofileenv`⟨environment +name⟩' where `\pgfprofileenv` is predefined as ``. Again, it is +permitted to use the same ⟨profiler entry name⟩ multiple times to merge +different commands into one output section. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilenewforenvironment" + }, + pgfprofilepostprocess = { + details = [[ +For LaTeX, this command is installed automatically in `\end{document}`. +It stops all running timings, evaluates them and returns the result into +the logfile. Furthermore, it generates a text table called +`\jobname.profiler.`⟨YYYY⟩`-`⟨MM⟩`-`⟨DD⟩`_ `⟨HH⟩`h_ `⟨MM⟩`m.dat` with +the same information. + +Note that the `profiler` library predefines two profiler entries, namely +`main job` which counts time from the beginning of the document until +`\pgfprofilepostprocess` and `preamble` which counts time from the +beginning of the document until `\begin{document}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilepostprocess" + }, + pgfprofilesetrel = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Sets the profiler entry whose total time will be used to compute all +other relative times. Thus, ⟨profiler entry name⟩ will use $100\%$ of +the total time per definition, all other relative times are relative to +this one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilesetrel" + }, + pgfprofileshowinvocationsexpandedfor = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +A variant of `\pgfprofileshowinvocationsfor` which will expand all +arguments for ⟨profiler entry name⟩ before showing them. The invocation +as such is not affected by this expansion. + +This expansion (with `\edef`) might yield unrecoverable errors for some +commands. Handle with care. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileshowinvocationsexpandedfor" + }, + pgfprofileshowinvocationsfor = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Enables verbose output for *every* invocation of ⟨profiler entry name⟩. + +This is only available for profiler entries for commands (those created +by `\pgfprofilenewforcommand` for example). It will also show all given +arguments. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofileshowinvocationsfor" + }, + pgfprofilestart = { + arguments = {{meta = "profiler entry name"}}, + details = [[ +Starts (or resumes) timing of ⟨profiler entry name⟩. The argument must +have been declared in the preamble using `\pgfprofilenew`. + +Nested calls of `\pgfprofilestart` with the same argument will be +ignored. + +The invocation of this command doesn't change the environment: it +doesn't introduce any TeX groups nor does it modify the token list. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfprofilestart" + }, + pgfpushtype = { + details = [[ +Pushes the current type on an internal global stack. The idea is to +allow you to temporarily change the current type without having to open +a TeX scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfpushtype" + }, + pgfqbox = { + arguments = {{meta = "box number"}}, + details = [[ +This command inserts a TeX box into a `{pgfpicture}` by "escaping" to +TeX, inserting the box number ⟨box number⟩ at the origin, and then +returning to the typesetting the picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqbox" + }, + pgfqboxsynced = { + arguments = {{meta = "box number"}}, + details = [[ +This command works similarly to the `\pgfqbox` command. However, before +inserting the text in ⟨box number⟩, the current coordinate +transformation matrix is applied to the current canvas transformation +matrix (is it "synced" with this matrix, hence the name). + +Thus, this command basically has the same effect as if you first called +`\pgflowlevelsynccm` followed by `\pgfqbox`. However, this command will +use `\hskip` and `\raise` commands for the "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 ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqboxsynced" + }, + pgfqkeys = { + arguments = {{meta = "default path"}, {meta = "key list"}}, + details = [[ +This command has the same effect as `\pgfkeys{`⟨default path⟩`/.cd,`⟨key +list⟩`}`, it is only marginally quicker. This command should not be used +in user code, but rather in commands like `\tikzset` or `\pgfset` that +get called very often. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeys" + }, + pgfqkeysactivatefamiliesandfilteroptions = { + arguments = { + {meta = "family list"}, + {meta = "default path"}, + {meta = "key--value-list"} + }, + details = [[ +The 'quick' default path variant of +`\pgfkeysactivatefamiliesandfilteroptions`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysactivatefamiliesandfilteroptions" + }, + pgfqkeysactivatesinglefamilyandfilteroptions = { + arguments = { + {meta = "family name"}, + {meta = "default path"}, + {meta = "key--value-list"} + }, + details = [[ +The 'quick' default path variant of +`\pgfkeysactivatesinglefamilyandfilteroptions`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysactivatesinglefamilyandfilteroptions" + }, + pgfqkeysalso = { + arguments = {{meta = "default path"}, {meta = "key list"}}, + details = [[ +This command has the same effect as `\pgfkeysalso{`⟨default +path⟩`/.cd,`⟨key list⟩`}`, it is only quicker. Changing the default path +inside a `\pgfkeyalso` is dangerous, so use with care. A rather safe +place to call this command is at the beginning of a TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysalso" + }, + pgfqkeysfiltered = { + arguments = {{meta = "default-path"}, {meta = "key--value-list"}}, + details = [[ +A variant of `\pgfkeysfiltered` which uses the 'quick' search path +setting. It is the `\pgfqkeys` variant of `\pgfkeysfiltered`, see the +documentation for `\pgfqkeys` for more details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqkeysfiltered" + }, + pgfqpoint = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command does the same as `\pgfpoint`, but ⟨x⟩ and ⟨y⟩ must be +simple dimensions like `1pt` or `1cm`. Things like `2ex` or `2cm+1pt` +are not allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpoint" + }, + pgfqpointscale = { + arguments = {{meta = "factor"}, {meta = "coordinate"}}, + details = [[ +As `\pgfpointscale`, but `{factor}` must be a simple number without +unit, as for the other "quick" commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointscale" + }, + pgfqpointxy = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}}, + details = [[ +This command does the same as `\pgfpointxy`, but ⟨$s_x$⟩ and ⟨$s_y$⟩ +must be simple numbers without unit, like `1.234` or `5.0`. Mathematical +expressions or units are not allowed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointxy" + }, + pgfqpointxyz = { + arguments = {{meta = "$s_x$"}, {meta = "$s_y$"}, {meta = "$s_z$"}}, + details = [[ +As `\pgfqpointxy`, but for three-dimensional coordinates. Any argument +needs to be a number without unit. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfqpointxyz" + }, + pgfrdfabout = { + arguments = {{meta = "text"}}, + details = [[ +Adds the RDF attribute `about="`⟨text⟩`"` to the next id scope (please +see the RDFa specification for details on the semantics of `about` in +the context of the resource description framework). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfabout" + }, + pgfrdfcontent = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfcontent" + }, + pgfrdfdatatype = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfdatatype" + }, + pgfrdfhref = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfhref" + }, + pgfrdfinlist = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfinlist" + }, + pgfrdfprefix = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfprefix" + }, + pgfrdfproperty = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfproperty" + }, + pgfrdfrel = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfrel" + }, + pgfrdfresource = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfresource" + }, + pgfrdfrev = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfrev" + }, + pgfrdfsrc = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfsrc" + }, + pgfrdftypeof = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdftypeof" + }, + pgfrdfvocab = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrdfvocab" + }, + pgfrealjobname = { + arguments = {{meta = "name"}}, + details = [[ +Tells PGF the real name of your job. For instance, if you have a file +called `survey.tex` that contains two graphics that you wish to be +called `survey-graphic1` and `survey-graphic2`, then you should write +the following. + + % This is file survey.tex + \documentclass{article} + ... + \usepackage{tikz} + \pgfrealjobname{survey} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfrealjobname" + }, + pgfresetboundingbox = { + details = [[ +Resets the picture's bounding box. The picture will simply forget any +previous bounding box updates and start collecting from scratch. + +You can use this together with `\pgfusepath{use as bounding box}` to +replace the bounding box by the one of a particular path (ignoring +subsequent paths). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfresetboundingbox" + }, + pgfsetadditionalshadetransform = { + arguments = {{meta = "transformation"}}, + details = [[ +This command allows you to specify an additional transformation that +should be applied to shadings when the `\pgfshadepath` command is used. +The ⟨transformation⟩ should be transformation code like +`\pgftransformrotate{20}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetadditionalshadetransform" + }, + pgfsetarrows = { + arguments = {{meta = "argument"}}, + details = [[ +The ⟨argument⟩ can be of the form ⟨start arrow tip specification⟩`-`⟨end +arrow tip specification⟩. In this case, both the start and the end arrow +specification are set: + + \begin{pgfpicture} + \pgfsetarrows{Latex[length=10pt]->>} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +Alternatively, ⟨argument⟩ can be of the form `[`⟨arrow keys⟩`]`. In this +case, the ⟨arrow keys⟩ will be set for all arrow tips in the current +scope, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrows" + }, + pgfsetarrowsend = { + arguments = {{meta = "end arrow tip specification"}}, + details = [[ +Sets the arrow tip kind used at the end of a path. + + \begin{pgfpicture} + \pgfsetarrowsstart{Latex[length=10pt]} + \pgfsetarrowsend{Computer Modern Rightarrow} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrowsend" + }, + pgfsetarrowsstart = { + arguments = {{meta = "start arrow tip specification"}}, + details = [[ +Sets the arrow tip kind used at the start of a (possibly curved) path. +The syntax of the ⟨start arrow specification⟩ is detailed in Section ??. + +To "clear" the start arrow, say `\pgfsetarrowsstart{}`. + + \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} + +The effect of this command persists only till the end of the current +TeX scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetarrowsstart" + }, + pgfsetbaseline = { + arguments = {{meta = "dimension"}}, + details = [[ +This command specifies a $y$-coordinate of the picture that should be +used as the baseline of the whole picture. When a PGF picture has been +typeset completely, PGF 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 a +different height. + + 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}. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaseline" + }, + pgfsetbaselinepointlater = { + arguments = {{meta = "point"}}, + details = [[ +This command also specifies the baseline indirectly, but the +$y$-coordinate of the given ⟨point⟩ is only computed at the end of the +picture. + + Hello + \begin{pgfpicture} + \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}} + % Note: no shape X, yet + \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaselinepointlater" + }, + pgfsetbaselinepointnow = { + arguments = {{meta = "point"}}, + details = [[ +This command specifies the baseline indirectly, namely as the +$y$-coordinate that the given ⟨point⟩ has when the command is called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbaselinepointnow" + }, + pgfsetbeveljoin = { + details = [[ +Sets the line join to a bevel join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbeveljoin" + }, + pgfsetblendmode = { + arguments = {{meta = "mode"}}, + details = [[ +Sets the blend mode to one of the values described in Section ??. As +described there, blend modes are an advanced feature of PDF and not +always rendered correctly. + + \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); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetblendmode" + }, + pgfsetbuttcap = { + details = [[ +Sets the line cap to a butt cap. See Section ?? for an explanation of +what this is. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetbuttcap" + }, + pgfsetcolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets both the stroke and fill color. The difference to the normal +`\color` command is that the effect lasts till the end of the current +`{pgfscope}`, not only till the end of the current TeX group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcolor" + }, + pgfsetcornersarced = { + arguments = {{meta = "point"}}, + details = [[ +This command causes all subsequent corners to be replaced by little +arcs. The effect of this command lasts till the end of the current +TeX scope. + +The ⟨point⟩ dictates how large the corner arc will be. Consider a corner +made by two lines $l$ and $r$ and assume that the line $l$ comes first +on the path. The $x$-dimension of the ⟨point⟩ decides by how much the +line $l$ will be shortened, the $y$-dimension of ⟨point⟩ decides by how +much the line $r$ will be shortened. Then, the shortened lines are +connected by an arc. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{5mm}{5mm}} + \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfsetcornersarced{\pgfpoint{10mm}{5mm}} + % 10mm entering, + % 5mm leaving. + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0cm}{2cm}} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfpathcurveto + {\pgfpoint{3cm}{0cm}} + {\pgfpoint{2cm}{0cm}} + {\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{tikzpicture} + +If the $x$- and $y$-coordinates of ⟨point⟩ are the same and the corner +is a right angle, you will get a perfect quarter circle (well, not quite +perfect, but perfect up to six decimals). When the angle is not +$90^\circ$, you only get a fair approximation. + +More or less "all" corners will be rounded, even the corner generated by +a `\pgfpathclose` command. (The author is a bit proud of this feature.) + + \begin{pgfpicture} + \pgfsetcornersarced{\pgfpoint{4pt}{4pt}} + \pgfpathmoveto{\pgfpointpolar{0}{1cm}} + \pgfpathlineto{\pgfpointpolar{72}{1cm}} + \pgfpathlineto{\pgfpointpolar{144}{1cm}} + \pgfpathlineto{\pgfpointpolar{216}{1cm}} + \pgfpathlineto{\pgfpointpolar{288}{1cm}} + \pgfpathclose + \pgfusepath{stroke} + \end{pgfpicture} + +To return to normal (unrounded) corners, use +`\pgfsetcornersarced{\pgfpointorigin}`. + +Note that the rounding will produce strange and undesirable effects if +the lines at the corners are too short. In this case the shortening may +cause the lines to "suddenly extend over the other end" which is rarely +desirable. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcornersarced" + }, + pgfsetcurvilinearbeziercurve = { + arguments = { + {meta = "start"}, + {meta = "first support"}, + {meta = "second support"}, + {meta = "end"} + }, + details = [[ +Prior to using any other command from this library, you first call this +function to "install" a Bézier 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. + + \pgfsetcurvilinearbeziercurve + {\pgfpointorigin} + {\pgfpoint{1cm}{1cm}} + {\pgfpoint{2cm}{1cm}} + {\pgfpoint{3cm}{0cm}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetcurvilinearbeziercurve" + }, + pgfsetdash = { + arguments = {{meta = "list of even length of dimensions"}, {meta = "phase"}}, + details = [[ +Sets the dashing of a line. The first entry in the list specifies the +length of the first solid part of the list. The second entry specifies +the length of the following gap. Then comes the length of the second +solid part, following by the length of the second gap, and so on. The +⟨phase⟩ specifies where the first solid part starts relative to the +beginning of the line. + + \begin{pgfpicture} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm} + \pgfpathmoveto{\pgfpoint{0mm}{1mm}} + \pgfpathlineto{\pgfpoint{2cm}{1mm}} + \pgfusepath{stroke} + \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm} + \pgfpathmoveto{\pgfpoint{0mm}{2mm}} + \pgfpathlineto{\pgfpoint{2cm}{2mm}} + \pgfusepath{stroke} + \end{pgfpicture} + +Use `\pgfsetdash{}{0pt}` to get a solid dashing. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetdash" + }, + pgfsetdecorationsegmenttransformation = { + arguments = {{meta = "code"}}, + details = [[ +The ⟨code⟩ will be executed at the very beginning of each segment. Note +when applying multiple decorations, this will be reset between +decorations, so it needs to be specified for each segment. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \begin{pgfdecoration}{ + {curveto}{\pgfdecoratedpathlength/3}, + {zigzag}{\pgfdecoratedpathlength/3} + { + \pgfdecorationsegmentlength=5pt + \pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}} + }, + {curveto}{\pgfdecoratedremainingdistance} + } + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}} + \end{pgfdecoration} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetdecorationsegmenttransformation" + }, + pgfseteorule = { + details = [[ +Dictates that the even-odd rule is used in subsequent fillings in the +current *TeX scope*. Thus, for once, the effect of this command does not +persist past the current TeX scope. + + \begin{pgfpicture} + \pgfseteorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfseteorule" + }, + pgfsetfading = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command sets the graphic state parameter "fading" to a previously +defined fading ⟨name⟩. This graphic state works like other graphic +states, that is, is persists till the end of the 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 picture's original bounding +box will be transparent and, thus, the fading effectively clips against +this bounding box. + +The ⟨transformations⟩ are applied to the fading before it is used. They +contain normal PGF transformation commands like `\pgftransformshift`. +You can also scale the fading using this command. Note, however, that +the transformation needs to be inverted internally, which may result in +inaccuracies and the following graphics may be slightly distorted if you +use a strong ⟨transformation⟩. + + \pgfdeclarefading{fading2} + {\tikz \shade[left color=pgftransparent!0, + right color=pgftransparent!100] (0,0) rectangle (2,2);} + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} + + (0,0) rectangle (2,2);}}] + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}} + \pgftransformrotate{20}} + \fill [red] (0,0) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfading" + }, + pgfsetfadingforcurrentpath = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command works like `\pgfsetfading`, but the fading is scaled and +transformed according to the following rules: + +1. If the current path is empty, the command has the same effect as + `\pgfsetfading`. + +2. Otherwise it is assumed that the fading has a size of 100bp times + 100bp. + +3. The fading is resized and shifted (using appropriate + transformations) such that the position + $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of the + current path and the position $(75\mathrm{bp},75\mathrm{bp})$ lies + at the upper-right corner of the current path. + +Note that these rules are the same as the ones used in `\pgfshadepath` +for shadings. After these transformations, the ⟨transformations⟩ are +executed (typically a rotation). + + \pgfdeclarehorizontalshading{shading}{100bp} + { color(0pt)=(transparent!0); color(25bp)=(transparent!0); + color(75bp)=(transparent!100); color(100bp)=(transparent!100)} + + \pgfdeclarefading{fading}{\pgfuseshading{shading}} + + \begin{tikzpicture} + \fill [black!20] (0,0) rectangle (2,2); + \fill [black!30] (0,0) arc (180:0:1); + + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfsetfadingforcurrentpath{fading}{} + \pgfusepath{discard} + + \fill [red] (0,0) rectangle (2,1); + + \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}} + \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}} + \pgfusepath{discard} + + \fill [red] (0,1) rectangle (2,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfadingforcurrentpath" + }, + pgfsetfadingforcurrentpathstroked = { + arguments = {{meta = "name"}, {meta = "transformations"}}, + details = [[ +This command works like `\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{tikzpicture} + \pgfsetlinewidth{2mm} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{0cm}} + \pgfsetfadingforcurrentpathstroked{fading}{} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfadingforcurrentpathstroked" + }, + pgfsetfillcolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets the color used for filling paths to ⟨color⟩. Like the stroke color, +the effect lasts only till the next use of `\color`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillcolor" + }, + pgfsetfillopacity = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of filling operations. As for stroking, the ⟨value⟩ +should be a number between `0` and `1`. + +The "filling transparency" will also be used for text and images. + + \begin{tikzpicture} + \pgfsetfillopacity{0.5} + \fill[red] (90:1cm) circle (11mm); + \fill[green] (210:1cm) circle (11mm); + \fill[blue] (-30:1cm) circle (11mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillopacity" + }, + pgfsetfillpattern = { + arguments = {{meta = "name"}, {meta = "color"}}, + details = [[ +This command specifies that paths that are filled should be filled with +the "color" by the pattern ⟨name⟩. For an inherently colored pattern, +the ⟨color⟩ parameter is ignored. For form-only patterns, the ⟨color⟩ +parameter specifies the color to be used for the pattern. + + \begin{tikzpicture} + \pgfsetfillpattern{stars}{red} + \filldraw (0,0) rectangle (1.5,2); + + \pgfsetfillpattern{green stars}{red} + \filldraw (1.5,0) rectangle (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetfillpattern" + }, + pgfsetinnerlinewidth = { + arguments = {{meta = "dimension"}}, + details = [[ +This command sets the width of the inner line. Whenever a path is +stroked (and only then), it will be stroked normally and, afterward, it +is stroked once more with the color set to the inner line color and the +line width set to ⟨dimension⟩. + +In case arrow tips are added to a path, the path is first stroked +normally, then the inner line is stroked, and then the arrow tip is +added. In case the main path is shortened because of the added arrow +tip, this shortened path is double stroked, not the original path (which +is exactly what you want). + +When the inner line width is set to 0pt, which is the default, no inner +line is stroked at all (not even a line of width 0pt). So, in order to +"switch off" double stroking, set ⟨dimension⟩ to `0pt`. + +The setting of the inner line width is local to the current TeX group +and *not* to the current PGF scope. + +Note that inner lines will *not* be drawn for paths that are also used +for clipping. However, this may change in the future, so you should not +depend on this. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfsetlinewidth{2pt} + \pgfsetinnerlinewidth{1pt} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetinnerlinewidth" + }, + pgfsetinnerstrokecolor = { + arguments = {{meta = "color"}}, + details = [[ +This command sets the ⟨color⟩ that is to be used when the inner line is +stroked. The effect of this command is also local to the current +TeX group. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfsetlinewidth{2pt} + \pgfsetinnerlinewidth{1pt} + \pgfsetinnerstrokecolor{red!50} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetinnerstrokecolor" + }, + pgfsetlayers = { + arguments = {{meta = "layer list"}}, + details = [[ +This command tells PGF 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: + + \pgfdeclarelayer{background} + \pgfdeclarelayer{foreground} + \pgfsetlayers{background,main,foreground} + +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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlayers" + }, + pgfsetlinetofirstplotpoint = { + details = [[ +Specifies that plot handlers should issue a line-to command for the +first point of the plot. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfsetlinetofirstplotpoint + \pgfplothandlerlineto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{1cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{3cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{2cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlinetofirstplotpoint" + }, + pgfsetlinewidth = { + arguments = {{meta = "line width"}}, + details = [[ +This command sets the line width for subsequent strokes (in the current +`pgfscope`). The line width is given as a normal TeX dimension like +`0.4pt` or `1mm`. + + \begin{pgfpicture} + \pgfsetlinewidth{1mm} + \pgfpathmoveto{\pgfpoint{0mm}{0mm}} + \pgfpathlineto{\pgfpoint{2cm}{0mm}} + \pgfusepath{stroke} + \pgfsetlinewidth{2\pgflinewidth} % double in size + \pgfpathmoveto{\pgfpoint{0mm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}} + \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetlinewidth" + }, + pgfsetmatrixcolumnsep = { + arguments = {{meta = "sep list"}}, + details = [[ +This macro sets the default separation list for columns. The details of +the format of this list are explained in the description of the next +command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmatrixcolumnsep" + }, + pgfsetmatrixrowsep = { + arguments = {{meta = "sep list"}}, + details = [[ +This macro sets the default separation list for rows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmatrixrowsep" + }, + pgfsetmiterjoin = { + details = [[ +Sets the line join to a miter join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmiterjoin" + }, + pgfsetmiterlimit = { + arguments = {{meta = "miter limit factor"}}, + details = [[ +Sets the miter limit to ⟨miter limit factor⟩. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmiterlimit" + }, + pgfsetmovetofirstplotpoint = { + details = [[ +Specifies that the line-to plot handler (and also some other plot +handlers) should issue a move-to command for the first point of the plot +instead of a line-to. This will start a new part of the current path, +which is not always, but often, desirable. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetmovetofirstplotpoint" + }, + pgfsetnonzerorule = { + details = [[ +Dictates that the nonzero winding number rule is used in subsequent +fillings in the current TeX scope. This is the default. + + \begin{pgfpicture} + \pgfsetnonzerorule + \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} + \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} + \pgfusepath{fill} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetnonzerorule" + }, + pgfsetplotmarkphase = { + arguments = {{meta = "phase"}}, + details = [[ +Sets the $p$ parameter to ⟨phase⟩, that is, the first mark to be drawn +is the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarkphase" + }, + pgfsetplotmarkrepeat = { + arguments = {{meta = "repeat"}}, + details = [[ +Sets the $r$ parameter to ⟨repeat⟩, that is, only every $r$th mark will +be drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarkrepeat" + }, + pgfsetplotmarksize = { + arguments = {{meta = "dimension"}}, + details = [[ +This command sets the TeX dimension `\pgfplotmarksize` to ⟨dimension⟩. +This dimension is a "recommendation" for plot mark code at which size +the plot mark should be drawn; plot mark code may choose to ignore this +⟨dimension⟩ altogether. For circles, ⟨dimension⟩ should be the radius, +for other shapes it should be about half the width/height. + +The predefined plot marks all take this dimension into account. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplotmarksize{1ex} + \pgfplothandlermark{\pgfuseplotmark{*}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplotmarksize" + }, + pgfsetplottension = { + arguments = {{meta = "value"}}, + details = [[ +Sets the factor used by the curve plot handlers to determine the +distance of the control points from the points they control. The higher +the curvature of the curve points, the higher this value should be. A +value of $1$ will cause four points at quarter positions of a circle to +be connected using a circle. The default is $0.5$. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfsetplottension{0.75} + \pgfplothandlercurveto + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetplottension" + }, + pgfsetrectcap = { + details = [[ +Sets the line cap to a square cap. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetrectcap" + }, + pgfsetroundcap = { + details = [[ +Sets the line cap to a round cap. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetroundcap" + }, + pgfsetroundjoin = { + details = [[ +Sets the line join to a round join. See again Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetroundjoin" + }, + pgfsetshortenend = { + arguments = {{meta = "dimension"}}, + details = [[ +Works like `\pgfsetshortenstart`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetshortenend" + }, + pgfsetshortenstart = { + arguments = {{meta = "dimension"}}, + details = [[ +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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetshortenstart" + }, + pgfsetstrokecolor = { + arguments = {{meta = "color"}}, + details = [[ +Sets the color used for stroking lines to ⟨color⟩, where ⟨color⟩ is a +LaTeX color like `red` or `black!20!red`. Unlike the `\color` command, +the effect of this command lasts till the end of the current +`{pgfscope}` and not till the end of the current TeX group. + +The color used for stroking may be different from the color used for +filling. However, a `\color` command will always "immediately override" +any special settings for the stroke and fill colors. + +In plain TeX, this command will also work, but the problem of *defining* +a color arises. After all, plain TeX does not provide LaTeX colors. For +this reason, PGF implements a minimalistic "emulation" of the +`\definecolor`, `\colorlet`, and `\color` commands. Only gray-scale and +rgb colors are supported. For most cases this turns out to be enough. + + \begin{pgfpicture} + \pgfsetlinewidth{1pt} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \pgfsetstrokecolor{black} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \color{red} + \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetstrokecolor" + }, + pgfsetstrokeopacity = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of stroking operations. The ⟨value⟩ should be a number +between `0` and `1`, where `1` means "fully opaque" and `0` means "fully +transparent". A value like `0.5` will cause paths to be stroked in a +semitransparent way. + + \begin{pgfpicture} + \pgfsetlinewidth{5mm} + \color{red} + \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke} + \color{black} + \pgfsetstrokeopacity{0.5} + \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetstrokeopacity" + }, + pgfsettransform = { + arguments = {{meta = "macro"}}, + details = [[ +Reinstalls a coordinate transformation matrix that was previously saved +using `\pgfgettransform`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransform" + }, + pgfsettransformentries = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "shiftx"}, + {meta = "shifty"} + }, + details = [[ +Reinstalls a coordinate transformation matrix that was previously saved +using the storage command `\pgfgettransformentries`. This command can +also be used to replace any previously existing coordinate +transformation matrix (it is thus equivalent to `\pgftransformreset` +followed by `\pgftransformcm`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransformentries" + }, + pgfsettransformnonlinearflatness = { + arguments = {{meta = "dimension"}}, + details = [[ +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 ⟨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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsettransformnonlinearflatness" + }, + pgfsetxvec = { + arguments = {{meta = "point"}}, + details = [[ +Sets that current $x$-vector for usage in the $xyz$-coordinate system. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + + \color{red} + \pgfsetxvec{\pgfpoint{0.75cm}{0cm}} + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetxvec" + }, + pgfsetyvec = { + arguments = {{meta = "point"}}, + details = [[ +Works like `\pgfsetxvec`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetyvec" + }, + pgfsetzvec = { + arguments = {{meta = "point"}}, + details = [[ +Works like `\pgfsetxvec`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsetzvec" + }, + pgfshadecolortocmyk = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input, converts it to CMYK and stores +the color's cyan/magenta/yellow/black components real numbers between +0.0 and 1.0 separated by spaces. + +In addition, four macros suffixed with `cyan`, `magenta`, `yellow` and +`black` are defined, which store the individual components of ⟨color +name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortocmyk" + }, + pgfshadecolortogray = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input converts it to grayscale and +stores the color's value as a real number between 0.0 and 1.0. + +Although it's not needed, for consistency a second macro suffixed with +`gray` is also defined. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortogray" + }, + pgfshadecolortorgb = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +This command takes ⟨color name⟩ as input, converts it to RGB and stores +the color's red/green/blue components real numbers between 0.0 and 1.0 +separated by spaces (which is exactly what you need if you want to push +it on a stack) in ⟨macro⟩. This macro can then be used inside the ⟨type +4 function⟩ argument for `\pgfdeclarefunctionalshading`. + + \pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}} + {\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{ + 2 copy % whirl + % Calculate "safe" atan of position + 2 copy abs exch abs add 0.0001 ge { atan } { pop } ifelse + 3 1 roll + dup mul exch + dup mul add sqrt + 30 mul + add + sin + 1 add 2 div + dup + \myrgb % push mycol + 5 4 roll % multiply all components by calculated value + mul + 3 1 roll + 3 index + mul + 3 1 roll + 4 3 roll + mul + 3 1 roll + } + \colorlet{mycol}{white}% + \pgfuseshading{sweep}% + \colorlet{mycol}{red}% + \pgfuseshading{sweep} + +In addition, three macros suffixed with `red`, `green` and `blue` are +defined, which store the individual components of ⟨color name⟩. These +can also be used in the ⟨type 4 function⟩ argument. + + \pgfshadecolortorgb{orange}{\mycol} + |\mycol|=\mycol |\mycolred|=\mycolred |\mycolgreen|=\mycolgreen |\mycolblue|=\mycolblue +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadecolortorgb" + }, + pgfshadepath = { + arguments = {{meta = "shading name"}, {meta = "angle"}}, + details = [[ +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, PGF 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 scope, so it +can be used, for example, to stroke it. + +Now, the ⟨shading name⟩ should be a shading whose width and height are +100 bp, that is, 100 big points. PGF has a look at the bounding box of +the current path. This bounding box is computed automatically when a +path is computed; however, it can sometimes be (quite a bit) too large, +especially when complicated curves are involved. + +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 path (the details are +a bit more complex, see below). Then, the coordinate system is rotated +by ⟨angle⟩. Finally, if the macro `\pgfsetadditionalshadetransform` has +been used, an additional transformation is applied. + +After everything has been set up, the shading is inserted. Due to the +transformations and clippings, the effect will be that the shading seems +to "fill" the path. + +If both the path and the shadings were always rectangles and if +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 rectangle itself. + +For these reasons, things work slightly differently "in reality". The +shading is scaled and translated such that the point +$(50\mathrm{bp},50\mathrm{bp})$, which is the middle of the shading, is +at the middle of the path and such that the point +$(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of the path +and that $(75\mathrm{bp},75\mathrm{bp})$ is at upper right corner. + +In other words, only the center quarter of the shading will actually +"survive the clipping" if the path is a rectangle. If the path is not a +rectangle, but, say, a circle, even less is seen of the shading. Here is +an example that demonstrates this effect: + + \pgfdeclareverticalshading{myshadingE}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \pgfuseshading{myshadingE} + \hskip 1cm + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}} + \pgfshadepath{myshadingE}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} + \pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm} + \pgfshadepath{myshadingE}{45} + \pgfusepath{stroke} + \end{pgfpicture} + +As can be seen above in the last case, the "hidden" part of the shading +actually *can* become visible if the shading is rotated. The reason is +that it is scaled as if no rotation took place, then the rotation is +done. + +The following graphics show which part of the shading are actually +shown: + + \pgfdeclareverticalshading{myshadingF}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \begin{tikzpicture} + \draw (50bp,50bp) node {\pgfuseshading{myshadingF}}; + \draw[white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {first two applications}; + + \begin{scope}[xshift=5cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp); + \draw (50bp,0bp) node[below] {third application}; + \end{scope} + + \begin{scope}[xshift=10cm] + \draw (50bp,50bp) node{\pgfuseshading{myshadingF}}; + \draw[white,thick] (50bp,50bp) circle (25bp); + \draw (50bp,0bp) node[below] {fourth application}; + \end{scope} + \end{tikzpicture} + +An advantage of this approach is that when you rotate a radial shading, +no distortion is introduced: + + \pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}} + {color(0bp)=(red!15!white); color(9bp)=(red!75!white); + color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)} + \pgfuseshading{ballshading} + \hskip 1cm + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{0} + \pgfusepath{} + \pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm} + \pgfshadepath{ballshading}{45} + \pgfusepath{} + \end{pgfpicture} + +If you specify a rotation of $90^\circ$ and if the path is not a square, +but an elongated rectangle, the "desired" effect results: The shading +will exactly vary between the colors at the 25bp and 75bp boundaries. +Here is an example: + + \pgfdeclareverticalshading{myshadingG}{100bp} + {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)} + \begin{pgfpicture} + \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{0} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{90} + \pgfusepath{stroke} + \pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}} + \pgfshadepath{myshadingG}{45} + \pgfusepath{stroke} + \end{pgfpicture} + +As a final example, let us define a "rainbow spectrum" shading for use +with TikZ. + + \pgfdeclareverticalshading{rainbow}{100bp} + {color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow); + color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue); + color(75bp)=(violet); color(100bp)=(violet)} + \begin{tikzpicture}[shading=rainbow] + \shade (0,0) rectangle node[white] {\textsc{pride}} (2,1); + \shade[shading angle=90] (3,0) rectangle +(1,2); + \end{tikzpicture} + +Note that rainbow shadings are *way* too colorful in almost all +applications. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfshadepath" + }, + pgfsnapshot = { + arguments = {{meta = "time"}}, + details = [[ +When this command is used inside a TeX scope, the behavior of +`\pgfanimateattribute` changes: Instead of adding an animation to the +object and the attribute, the object's attribute is set to value it +would have during the animation at time ⟨time⟩. Note that when this +command is used in a TeX scope, no animation is created and no support +by the driver is needed (so, it works with PDF). + + \tikz [make snapshot of=1s, + animate = { myself: = { + :rotate = { 0s = "0", 2s = "90" }, + :color = { 0s = "red", 2s = "green" }, + :line width = { 0s = "0mm", 4s = "4mm" } + }}] + \node [fill=black!20, draw] { Node }; + +**Timing and Events.** The timeline of an animation normally starts at a +"moment `0s`" and the ⟨time⟩ is considered relative to this time. For +instance, if a timeline contains, say, the settings `entry={2s}{0}` and +`entry={3s}{10}` and `{time}` is set to `2.5s`, then the value the +attribute will get is 5. + +It is, however, also possible to specify that animations begin and end +at certain times relative to events like a `click` event. *These events +are not relevant with respect to snapshots.* However, there is one key +that allows you to specify the beginning of the snapshot timeline: + +Note that the `end` keys have no effect with snapshots, that is, with a +snapshot all animations always run till the end of the timeline (which +may or may not be "forever"). + +**Limitations.** For snapshots, the value an animation has at time +⟨time⟩ must be computed by TeX. While in many cases this is easy to +achieve, in some cases this is not trivial such as a timeline for a path +with repeats plus smoothing via splines. An additional complication is +the fact that an animation may be specified at a place far removed from +the actual to-be-animated object. For these reasons, certain limitations +apply to snapshots: + +- The `begin` and `begin on` keys have no effect (but `begin snapshot` + has one. + +- The `end` and `end on` keys have no effect. + +- The `current value` may not be used in a timeline (since PGF cannot + really determine this value). + +- The `accumulating` specification may not be used with paths, views, + or motions. + +- Since the timing computations are done using TeX code, they are not + necessarily stable. For instance, when a time interval is very small + and there are many repeats or when a spline is very complicated, the + calculated values may not be fully accurate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsnapshot" + }, + pgfsnapshotafter = { + arguments = {{meta = "time"}}, + details = [[ +This command works exactly like `\pgfsnapshot` only the "moment" that +⟨time⟩ refers to is conceptually $⟨time⟩ + \epsilon$: When timeline +specifies several values for ⟨time⟩, this command will select the last +value at ⟨time⟩, while `\pgfsnapshot` will select the first value at +⟨time⟩. Similarly, when a timeline ends at ⟨time⟩, `\pgfsnapshot` will +select the last value of the timeline while `\pgfsnapshotafter` will not +apply the animation any more: + + \foreach \t in {0,1,2,3,4} { + \pgfsnapshot{\t} + \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" } + \node [draw=blue, very thick] {f}; } + + \foreach \t in {0,1,2,3,4} { + \pgfsnapshotafter{\t} + \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" } + \node [draw=blue, very thick] {f}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsnapshotafter" + }, + ["pgfsys@animate"] = { + arguments = {{meta = "attribute"}}, + details = [[ +The system layer animation subsystem follows the following philosophy: +An animation always concerns an *attribute* of a *graphic object*. A +*timeline* specifies how the attribute changes its value over time. +Finally, a set of *keys* configures the animation as a whole like +whether the timeline repeats or a event that triggers the start of the +animation. The four parts of an animation, namely the *attribute*, the +*graphic object*, the *timeline*, and the *keys*, are specified in +different ways: + +1. You choose the *attribute* using the system layer command + `\pgfsysanimate`. + +2. The *graphic object* whose attribute is to be animated is *always* + specified by naming the ID of the graphic object *before* this + object is created, see Section ??. (However, in the context of TikZ, + it suffices that the animation is given in the object's options + since these are executed before the actual object is created). + +3. The *timeline* is specified using the commands `\pgfsysanimkeytime`, + which specifies a time in seconds, and `\pgfsys@animation@val...`, + which specify a value at this particular time. The timeline + specifies for a sequence of times the values the attribute will have + at these times. In between these *key times,* the value is + interpolated. + +4. The *animation keys* are specified by commands starting + `\pgfsys@animation@...` and have the following effect: They set some + property (like, say, whether the animation repeats or whether its + effect is additive) to a given value *for the current TeX scope,* + but do not create any animations. Rather, when `\pgfsysanimate` is + called, a snapshot of the current values of all animation keys is + taken and added to this animation of the attribute. + + When you set an animation key to a value, this will replace the + value previously stored for the key (all keys are empty by default + at the beginning). + + Note that animation keys are local to TeX scopes, not graphics + scopes; indeed, they have little to do with the settings of the + graphics scope other than the fact that a graphic scope is also a + TeX scope and thereby influence the values of these keys. + +A typical example of how all of this works is the following: + + \pgfsysanimkeyrepeatindefinite % Both of the following animations + % repeat indefinitely + { + \pgfsysanimkeywhom{\someid}{}% The id of a later object + \pgfsysanimkeyevent{}{}{click}{0}{begin}% Begin on a click ... + \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline starts after 5s + \pgfsysanimvalscalar{0} % With a value of 0 + \pgfsysanimkeytime{8}{1}{1}{0}{0} % Timeline ends after 8s + \pgfsysanimvalscalar{0.9} % With a value of 0.9 + \pgfsysanimate{fillopacity}% ... and the attribute is the fill opacity + } + { + \pgfsysanimkeywhom{\someid}{}% The id of a later object + \pgfsysanimkeyoffset{0}{begin}% Begin right away ... + \pgfsysanimkeytime{1}{1}{1}{0}{0} % Timeline starts after 1s + \pgfsysanimvalcurrent % With the current value + \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline ends after 5s + \pgfsysanimvaldimension{5pt} % With a value of 5pt + \pgfsysanimate{linewidth}% ... and the attribute is the line width + } + +As a real-life example, consider the following definitions, which will +be used in many examples in the rest of this section: Both take three +parameters: The PGF/TikZ name of a to-be animated object, a type +(relevant for objects that have subtypes or parts), and some code for +triggering the actual animation. The animation will always start when +the button is clicked. The second macro sets up things in such a way +that the animation will last two seconds, while the first leaves the +timing open. + + \def\animationexample#1#2#3{ + \tikz[fill=blue!25, draw=blue, ultra thick] { + \pgfidrefnextuse{\objid}{#1} + \pgfsysanimkeywhom{\objid}{#2} + \pgfidrefnextuse{\nodeid}{node} + \pgfsysanimkeyevent{\nodeid}{}{click}{}{begin} + #3 + \node [font=\scriptsize, circle, fill, draw, align=center] + (node) {Click \\ here}; + } + } + +Now the example, where the circle will disappear, when clicked: + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimate{opacity} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animate" + }, + ["pgfsys@animation@accesskey"] = { + arguments = { + {meta = "character"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Begin or end the animation when a certain key is pressed. Note that this +event may not be supported by some browsers for security reasons +(prevent key loggers). + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyaccesskey{s}{}{begin} + \pgfsysanimate{translate} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@accesskey" + }, + ["pgfsys@animation@accumulate"] = { + details = [[ +Specifies that each repeat of an animation works as if the last values +attained during previous repeats are added to the current value. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeyaccumulate + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@accumulate" + }, + ["pgfsys@animation@base"] = { + details = [[ +This command can be used in any place where `\pgfsys@animation@time` is +usually used. The effect is that the next value does not become part of +the timeline, but will become the value used for the attribute when no +animation is active. (Normally, when the animation is not active, no +value is set at all and the value is inherited from the surrounding +scope.) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@base" + }, + ["pgfsys@animation@canvas@transform"] = { + arguments = {{meta = "pre"}, {meta = "post"}}, + details = [[ +In order to animate the canvas, you specify that, for instance, the +canvas should be shifted over, say, one second by 2cm from left to +right. In order to specify this, you specify that an additional shift +should be added to the canvas transformation matrix that starts out as +$(0,0)$ and ends at $(2\,\mathrm{cm},0)$. However, it is not immediately +clear what "to the right" or $(2\,\mathrm{cm},0)$ actually means: +"Right" relative to the paper? "Right" relative to the coordinate system +at the point when the animation is created? "Right" relative to the +object's local coordinate system? + +Using this command you can specify the coordinate system relative to +which all canvas animations are specified. In detail, when you add an +animation $a$ of the canvas of an object foo, the following happens: + +1. We start with the canvas transformation matrix that is installed + when the object starts. More precisely, this is the canvas + transformation matrix that is in force when the command + `\pgfsys@begin@idscope` is called for the object. The canvas + transformation matrix that is in force when the animation is created + (which is typically "way before" the object is created and may even + be in a totally different graphics scope) is irrelevant for the + animation. + +2. Now, when the object is created, the code ⟨pre⟩ is executed. It + should call `\pgfsys@transformcm` at most once. This canvas + transformation is added to the object's canvas transformation. + +3. Now, the animation $a$ of the canvas is relative to the resulting + canvas transformation. That means, when the animation shifts the + object "to the right" the animation will actually be along the + current direction of "right" in the canvas transformation resulting + from the two transformations above. + +4. Finally, at the point of creation of the to-be-animation object the + code ⟨post⟩ is executed. Again, the code should call + `\pgfsys@transformcm` at most once. The resulting transformation is + also added to the object's canvas transformation, but does *not* + influence the animation. + +The net effect of the above is that, normally, you use the ⟨pre⟩ code to +setup a transformation matrix relative to which you wish to perform your +animation and, normally, you use ⟨post⟩ to undo this transformation +(using the inverted matrix) to ensure that when no animation is in +force, the object is placed at the same position as if no animation were +used. + +Let us now have a look at some examples. We use the following macro, +which takes a pre and a post code and animates a red ball over 1cm to +the right in two seconds and rotates the blue ball over 90$^\circ$ +around the origin. The ball is placed at $(1,0)$. + + \def\animationcanvasexample#1#2{% + \animationexample{ball}{}{% + \pgfsysanimkeycanvastransform{#1}{#2}% + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{1cm}{0cm}% + \pgfsysanimate{translate} + \fill [ball color=red,name=ball] (1,0) circle [radius=3mm]; } + \animationexample{ball}{}{% + \pgfsysanimkeycanvastransform{#1}{#2}% + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{90}% + \pgfsysanimate{rotate} + \fill [ball color=blue,name=ball] (1,0) circle [radius=3mm]; } } + + \animationcanvasexample + {} + {} + + \animationcanvasexample + {\pgfsys@transformshift{10mm}{0mm}} + {\pgfsys@transformshift{-10mm}{0mm}} + + \animationcanvasexample + {\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5} + {0pt}{0pt}} + {} + + \animationcanvasexample + {\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5} + {0pt}{0pt}} + {\pgfsys@transformcm{1}{-1}{1}{1} + {0pt}{0pt}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@canvas@transform" + }, + ["pgfsys@animation@event"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "event name"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Specifies that the animation should begin (or end) ⟨time offset⟩ many +seconds after a certain *event* has occurred. Which events are possible +depends on the specific output language, here are the events currently +supported in SVG: + +- `click` occurs when the object with the given ⟨id⟩ and ⟨type⟩ has + been clicked. + +- `focusin` and `focusout` occur when the focus enters or leaves the + object. + +- `mouseup`, `mousedown`, `mouseover`, `mousemove`, and `mouseout` + occur when the mouse is pressed up or down on the object, moved onto + the object, moved over the object, or moved off the object. + +  + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseup}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mousedown}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseover}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mousemove}{}{begin} + \pgfsysanimate{translate} } + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyevent{\nodeid}{}{mouseout}{}{begin} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@event" + }, + ["pgfsys@animation@freezeatend"] = { + details = [[ +When an animation ends, the question is whether the "effect" of the +animation (like changing a color or translating the coordinate system) +should disappear or "remain in force". Using this key, you specify that +at the end of the animation the last value of the attributes stays in +effect. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyfreezeatend + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@freezeatend" + }, + ["pgfsys@animation@movealong"] = { + arguments = {{meta = "path"}}, + details = [[ +Defines the ⟨path⟩ along which the motion will occur. It will simply be +executed and must call `\pgfsys@lineto` and similar path-construction +commands, but should not call other commands. + + \animationexample{node}{}{ + \pgfsysanimkeymovealong{ + \pgfsyssoftpath@movetotoken{0pt}{0pt} + \pgfsyssoftpath@linetotoken{0pt}{-5mm} + \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} } + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimate{motion} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@movealong" + }, + ["pgfsys@animation@noaccumulate"] = { + details = [[ +Specifies that each repeat resets the to-be-animated value. This is the +default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeynoaccumulate + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@noaccumulate" + }, + ["pgfsys@animation@norotatealong"] = { + details = [[ +Indicates that no additional rotation should be added during the +movement. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@norotatealong" + }, + ["pgfsys@animation@offset"] = { + arguments = {{meta = "time offset"}, {meta = "begin or end"}}, + details = [[ +Specifies that (in addition to any other beginnings or endings) the +animation's timeline should begin (or end) ⟨time offset⟩ many seconds +after the graphic is shown. For instance, in the next example the +animation will start automatically after 5 s *or* when then button is +pressed. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyoffset{5}{begin} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@offset" + }, + ["pgfsys@animation@removeatend"] = { + details = [[ +The opposite of `\pgfsysanimkeyfreezeatend`. This is the default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyremoveatend + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@removeatend" + }, + ["pgfsys@animation@repeat"] = { + arguments = {{meta = "number of times"}}, + details = [[ +Specifies that the animation should repeat the specified ⟨number of +times⟩, which may be a fractional number. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeat{2.5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat" + }, + ["pgfsys@animation@repeat@dur"] = { + arguments = {{meta = "seconds"}}, + details = [[ +Specifies that the animation should repeat until ⟨seconds⟩ have elapsed. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeatdur{5} + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@dur" + }, + ["pgfsys@animation@repeat@event"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "repeat count"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +The animation begins (or end) with a certain offset when another +animation has reached a certain repeat count. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimkeyrepeatdur{5} + \pgfsys@new@id{\animationid} + \pgfsys@use@id{\animationid} + \pgfsysanimate{translate} + \global\let\animationid\animationid } + \tikz { + \pgfidrefnextuse{\objid}{other} + \pgfsysanimkeyrepeatevent{\animationid}{}{2}{0}{begin} + \pgfsysanimkeysnapshotstart{4} + \pgfsysanimkeywhom{\objid}{} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-5mm} + \pgfsysanimate{translate} + \node [fill=red, text=white, circle] (other) {Other}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@event" + }, + ["pgfsys@animation@repeat@indefinite"] = { + details = [[ +Specifies that the animation should repeat indefinitely. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrepeatindefinite + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@repeat@indefinite" + }, + ["pgfsys@animation@restart@always"] = { + details = [[ +Defines that the animation can be restarted at any time. This is the +default. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartalways + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@always" + }, + ["pgfsys@animation@restart@never"] = { + details = [[ +Defines that the animation cannot be restarted once it has run. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartnever + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@never" + }, + ["pgfsys@animation@restart@whennotactive"] = { + details = [[ +Defines that the animation cannot be restarted while it is running. + + \animationexample{node}{}{ + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{0cm} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvaltranslate{0cm}{-1cm} + \pgfsysanimkeyrestartwhennotactive + \pgfsysanimate{translate} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@restart@whennotactive" + }, + ["pgfsys@animation@rotatealong"] = { + details = [[ +Indicates that the to-be-animated group should be rotated automatically +so that it points along the path as time progresses. This option is only +applicable to motion animations. + + \animationexample{node}{}{ + \pgfsysanimkeyrotatealong + \pgfsysanimkeymovealong{% + \pgfsyssoftpath@movetotoken{0pt}{0pt}% + \pgfsyssoftpath@linetotoken{0pt}{-5mm}% + \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}% + \pgfsyssoftpath@curvetotoken{-5mm}{-1cm}} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{0}% + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimate{motion} + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@rotatealong" + }, + ["pgfsys@animation@syncbegin"] = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Specifies that the animation should begin ⟨time offset⟩ many seconds +after the ⟨sync base id⟩ with the given ⟨type⟩ has begun. Here, the +⟨sync base id⟩ must have been obtained using `\pgfsys@new@id`. + +The idea behind a sync base is that you setup an animation and name it, +other animations can start alongside this animation. An animation whose +sole purpose is to orchestrate other animations in this way is called a +*sync base*. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@syncbegin" + }, + ["pgfsys@animation@syncend"] = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ +Works like `\pgfsysanimkeysyncbegin` only the animation begin (or ends) +when the sync base ends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@syncend" + }, + ["pgfsys@animation@time"] = { + arguments = { + {meta = "time"}, + {meta = "entry spline control x"}, + {meta = "entry spline control y"}, + {meta = "exit spline control x"}, + {meta = "exit spline control y"} + }, + details = [[ +The ⟨time⟩ is a number representing seconds (so `0.5` means 500 ms). + +The spline between a time--value pair and the next is specified using +the four parameters following the time. The first two of these specify +the second control point of the interval preceding the time--value pair +(called the "entry" control point), the last two parameters specify the +first control point of the interval following the pair (called the +"exit" control point). Consider for instance, the following calls: + + \pgfsysanimkeytime{10}{0.1}{0.2}{0.3}{0.4} + \pgfsysanimvalscalar{100} + \pgfsysanimkeytime{15}{0.5}{0.6}{0.7}{0.8} + \pgfsysanimvalscalar{200} + +This will create (at least) the time interval +$[10\,\mathrm s,15\,\mathrm + s]$ and the control points for this interval will be $(0.3,0.4)$ and +$(0.5,0.6)$. + +Control points are specified in a different "coordinate" system from the +time--value pairs themselves: While the time--value pairs are specified +using a number representing seconds and a value using some special +commands, the control points are specified as numbers between $0$ and +$1$, each time representing a fraction of the time interval or the value +interval. In the example, the time interval is +$[10\,\mathrm s,15\,\mathrm + s]$ and the value interval is $[100,200]$. This means that a control +point of $(0.3,0.4)$ actually refers to the time--value +$(11.5\,\mathrm s,140)$. The "time--value curve" in the interval thus +"`(10s,100) .. controls (11.5s,140) and (12.5s,160) .. (15s,200)`". + +Note that by setting the control points always to $(1,1)$ and $(0,0)$ +you get a linear interpolation between time--value pairs. + +Two special cases are the following: When the two last parameters, the +exit spline, take the special values `stay` and `0`, the attribute's +value "stays" until the next value for the next time (it then "jumps" to +the next value then). This corresponds, roughly, to an "infinite" ⟨exit +spline control x⟩. Similarly, when the entry spline parameters take the +special values `jump` and `1`, the value immediately jumps from the +previous value to the next value when the previous value was specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@time" + }, + ["pgfsys@animation@tip@markers"] = { + arguments = {{meta = "start marker"}, {meta = "end marker"}}, + details = [[ +This command specifies that during a path animation the two markers +provided as parameters should be added (and rotated and moved along with +the path) at the start and end. The ⟨start marker⟩ must either be empty +(in which case no marker is added at the start) or it must be a macro +storing a value returned by the command `\pgfsys@marker@declare`. In +this case, the marker declared symbol will be added to the start during +the animation. The same situation applies to the end of the path. + +As pointed out earlier, only arrow tips / markers added to paths using +this command will be animated along with the path. In particular, you +should *not* add arrow tips to to-be-animated paths using +`\pgfsetarrow`. However, when you use a base value +(`\pgfsys@animation@base`) to set a path, the arrow tips will also be +added to this base path. + +To sum up, the "correct" way of adding arrow tips to a path that is +animated is to proceed as follows: + +1. You specify arrow tips for a path using this command. + +2. You specify times and values of the to-be-animated path, shortened + as necessary to accommodate the length of the arrow tips. + +3. You specify the first (or, possibly, some other) value in the + time--value sequence as a base value. + +4. You create a path animation that applies to a future path. + +5. You create this future path as an empty path without arrow tips and + draw it. Because of the setting of the base value, instead of the + empty path the base path will be used as the "real" path and the + animation's arrow tips will be added as arrow tips. + +When you have more than one animation for a given path, these different +animations may use different arrow tips / markers. This allows you to +animate (change) which arrow tip is used on a path over time. + + % Declare a marker: + \pgfsys@marker@declare\mymarker{% + \pgfscope% + \pgfsetcolor{red!75}% + \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}% + \pgfpathlineto{\pgfpoint{0pt}{0pt}}\pgfpathclose% + \pgfusepathqfill% + \endpgfscope% + \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}% + \pgfpathlineto{\pgfpoint{0pt}{-5pt}}\pgfpathclose% + \pgfusepathqstroke% + }% + \animationexample{my path}{path}{ + \pgfsysanimkeytipmarkers{\mymarker}{\mymarker} + \pgfsysanimkeybase + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}% + \pgfsys@lineto{1cm}{1cm}% + \pgfsys@lineto{2cm}{0cm}} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}% + \pgfsys@lineto{1cm}{1cm}% + \pgfsys@lineto{2cm}{0cm}} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalpath{\pgfsys@moveto{1cm}{1cm}% + \pgfsys@lineto{2cm}{1cm}% + \pgfsys@lineto{1cm}{0cm}} + \pgfsysanimate{path} + \filldraw [ultra thick,draw=blue,fill=blue!20, name=my path]; + \path (1,0) (2,1);} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@tip@markers" + }, + ["pgfsys@animation@val@color@cmy"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Like the `\pgfsysanimvalcolorcmyk` only without the black part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@cmy" + }, + ["pgfsys@animation@val@color@cmyk"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Creates a time--value pairs where the value is color specified by four +fractional values between 0 and 1 for the cyan, magenta, yellow, and +black part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@cmyk" + }, + ["pgfsys@animation@val@color@gray"] = { + arguments = {{meta = "gray value"}}, + details = [[ +Creates a time--value pairs where the value is gray value (a fraction +between 0 and 1). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@gray" + }, + ["pgfsys@animation@val@color@rgb"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Creates a time--value pairs where the value is color specified by three +fractional values between 0 and 1 for the red, the green, and the blue +part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@color@rgb" + }, + ["pgfsys@animation@val@current"] = { + details = [[ +Creates a time--value pairs where the value is the current value that +the attribute has. This command can only be used in conjunction with +"real" animations, when you use it with a snapshot an error is raised. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@current" + }, + ["pgfsys@animation@val@dash"] = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ +Creates a time--value pairs where the value is dash pattern and phase +with the same syntax as `\pgfsys@setdash`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@dash" + }, + ["pgfsys@animation@val@dimension"] = { + arguments = {{meta = "dimension"}}, + details = [[ +Creates a time--value pairs where the value is a TeX dimension like +`0.5pt` or `-2in`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@dimension" + }, + ["pgfsys@animation@val@path"] = { + arguments = {{meta = "low-level path construction command"}}, + details = [[ +Creates a time--value pairs where the value is path. The ⟨low-level +commands⟩ must consist of a sequence of path construction commands like +`\pgfsys@lineto` or `\pgfsyssoftpath@linetotoken` (more precisely, the +commands must form a list of TeX tokens and dimensions surrounded by +braces). For each call of this command, the sequence of tokens and +numbers must be the some. During the animation, only and exactly the +numbers will be interpolated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@path" + }, + ["pgfsys@animation@val@scalar"] = { + arguments = {{meta = "number"}}, + details = [[ +Creates a time--value pairs where the value is a number like `0.5` or +`-2.25`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@scalar" + }, + ["pgfsys@animation@val@scale"] = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ +Creates a time--value pairs where the value is pair of scalar values. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@scale" + }, + ["pgfsys@animation@val@text"] = { + arguments = {{meta = "text"}}, + details = [[ +Creates a time--value pairs where the value is some text. Which texts +are permissible depends on the to-be-animated attribute. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@text" + }, + ["pgfsys@animation@val@translate"] = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ +Creates a time--value pairs where the value is a coordinate. The +dimensions must be TeX dimensions. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@translate" + }, + ["pgfsys@animation@val@viewbox"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"} + }, + details = [[ +Creates a time--value pairs where the value is view box. The lower left +corner is given by $(x_1,y_1)$, consisting of two TeX dimensions, and +the upper right corner is $(x_2,y_2)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@val@viewbox" + }, + ["pgfsys@animation@whom"] = { + arguments = {{meta = "id"}, {meta = "type"}}, + details = [[ +Sets the target of the animation. The `{id}` must previously have been +created using `\pgfsys@new@id`, `{type}` must be a type (the empty type +is also allowed). See Section ?? for details on ids and types. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@animation@whom" + }, + ["pgfsys@append@type"] = { + arguments = {{meta = "text"}}, + details = [[ +Appends the ⟨text⟩ to the current type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@append@type" + }, + ["pgfsys@attach@to@id"] = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "begin code"}, + {meta = "end code"}, + {meta = "setup code"} + }, + details = [[ +Attaches codes to the ⟨id⟩-⟨type⟩-pair, where ⟨id⟩ must have been +created using `\pgfsys@new@id`. The effect is that just before the id +scope for this pair is created, the ⟨setup code⟩ is executed, then the +scope is started, then the ⟨begin code⟩ is executed at the beginning, +and, finally, ⟨end code⟩ gets executed just before the scope ends. +Multiple calls of this macro accumulated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@attach@to@id" + }, + ["pgfsys@begin@idscope"] = { + details = [[ +Starts a (graphics) scope whose sole purpose is to assign it an +id-type-pair so that it can be referenced later. Note that this command +does not always produce a graphics scope: If not id is currently in use +or if the id-type-pair has already been used, a graphic scope may or may +not be created as defined by the driver (but always a TeX scope). This +allows drivers to minimize the number of graphic scopes created. + +When an id scope is created, any code that has been "attached" to it +using `\pgfsys@attach@to@id` gets executed, see that command. + +Note that `\pgfsys@beginscope` does not use the current id-type-pair. +You need to call this command to attach an id to a group. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@begin@idscope" + }, + ["pgfsys@begininvisible"] = { + details = [[ +Between this command and the closing `\pgfsys@endinvisible` all output +should be suppressed. Nothing should be drawn at all, which includes all +paths, images and shadings. However, no groups (neither TeX groups nor +graphic state groups) should be opened by this command. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@begininvisible" + }, + ["pgfsys@beginpicture"] = { + details = [[ +Called at the beginning of a `{pgfpicture}`. This command should "set up +things". + +Most drivers will need to implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginpicture" + }, + ["pgfsys@beginpurepicture"] = { + details = [[ +This version of the `\pgfsys@beginpicture` picture command can be used +for pictures that are guaranteed not to contain any escaped boxes (see +below). In this case, a driver might provide a more compact version of +the command. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginpurepicture" + }, + ["pgfsys@beginscope"] = { + details = [[ +Saves the current graphic state on a graphic state stack. All changes to +the graphic state parameters mentioned for `\pgfsys@stroke` and +`\pgfsys@fill` will be local to the current graphic state and the old +values will be restored after `\pgfsys@endscope` is used. + +*Warning:* PDF and PostScript differ with respect to the question of +whether the current path is part of the graphic state or not. For this +reason, you should never use this command unless the path is currently +empty. For example, it might be a good idea to use `\pgfsys@discardpath` +prior to calling this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beginscope" + }, + ["pgfsys@beveljoin"] = { + details = [[ +Sets the join to a bevel join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@beveljoin" + }, + ["pgfsys@blend@mode"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the blend mode, see Section 7.2.4 of the PDF Specification, +Version 1.7. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@blend@mode" + }, + ["pgfsys@buttcap"] = { + details = [[ +Sets the cap to a butt cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@buttcap" + }, + ["pgfsys@clipfading"] = { + details = [[ +This command has a default implementation and need not be implemented by +driver files other than `pgfsys-dvips.def`. The macro is called in +`\pgfsetfadingforcurrentpath` and `\pgfsetfadingforcurrentpathstroked` +of the basic layer, where it invokes the current path for clipping the +shading just before installing it as an opacity mask for fading. The +default implementation is actually a non-operation, but with `dvips` it +is used to clip the fading as described. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@clipfading" + }, + ["pgfsys@clipnext"] = { + details = [[ +This command should be issued after a path has been constructed, but +before it has been stroked and/or filled or discarded. When the command +is used, the next stroking/filling/discarding command will first be +executed normally. Then, afterwards, the just-used path will be used for +subsequent clipping. If there has already been a clipping region, this +region is intersected with the new clipping path (the clipping cannot +get bigger). The nonzero winding number rule is used to determine +whether a point is inside or outside the clipping area or the even-odd +rule, depending on whether `\ifpgfsys@eorule` holds. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@clipnext" + }, + ["pgfsys@closepath"] = { + details = [[ +Close the current path. This results in joining the current point of the +path with the point specified by the last `\pgfsys@moveto` operation. +Typically, this is preferable over using `\pgfsys@lineto` to the last +point specified by a `\pgfsys@moveto`, since the line starting at this +point and the line ending at this point will be smoothly joined by +`\pgfsys@closepath`. + +Consider + + \pgfsys@moveto{0pt}{0pt} + \pgfsys@lineto{10bp}{10bp} + \pgfsys@lineto{0bp}{10bp} + \pgfsys@closepath + \pgfsys@stroke + +and + + \pgfsys@moveto{0bp}{0bp} + \pgfsys@lineto{10bp}{10bp} + \pgfsys@lineto{0bp}{10bp} + \pgfsys@lineto{0bp}{0bp} + \pgfsys@stroke + +The difference between the above will be that in the second triangle the +corner at the origin will be wrong; it will just be the overlay of two +lines going in different directions, not a sharp pointed corner. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@closepath" + }, + ["pgfsys@closestroke"] = { + details = [[ +This command should have the same effect as first closing the path and +then stroking it. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@closestroke" + }, + ["pgfsys@color@cmy"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for stroking and filling operations to the given cmy +tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy" + }, + ["pgfsys@color@cmy@fill"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for filling operations to the given cmy tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy@fill" + }, + ["pgfsys@color@cmy@stroke"] = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ +Sets the color used for stroking operations to the given cmy tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmy@stroke" + }, + ["pgfsys@color@cmyk"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for stroking and filling operations to the given +cmyk tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk" + }, + ["pgfsys@color@cmyk@fill"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for filling operations to the given cmyk tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk@fill" + }, + ["pgfsys@color@cmyk@stroke"] = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ +Sets the color used for stroking operations to the given cmyk tuple +(numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@cmyk@stroke" + }, + ["pgfsys@color@gray"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for stroking and filling operations to the given +black value, where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray" + }, + ["pgfsys@color@gray@fill"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for filling operations to the given black value, +where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray@fill" + }, + ["pgfsys@color@gray@stroke"] = { + arguments = {{meta = "black"}}, + details = [[ +Sets the color used for stroking operations to the given black value, +where 0 means black and 1 means white. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@gray@stroke" + }, + ["pgfsys@color@reset"] = { + details = [[ +This command will be called when the `\color` command is used. It should +purge any internal settings of stroking and filling color. After this +call, till the next use of a command like `\pgfsys@color@rgb@fill`, the +current color installed by the `\color` command should be used. + +If the TeX-if `\pgfsys@color@reset@inorder` is set to true, this command +may "assume" that any call to a color command that sets the fill or +stroke color came "before" the call to this command and may try to +optimize the output accordingly. + +An example of an incorrect "out of order" call would be using +`\pgfsys@color@reset` at the beginning of a box that is constructed +using `\setbox`. Then, when the box is constructed, no special fill or +stroke color might be in force. However, when the box is later on +inserted at some point, a special fill color might already have been +set. In this case, this command is not guaranteed to reset the color +correctly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset" + }, + ["pgfsys@color@reset@inorderfalse"] = { + details = [[ +Switches off the optimized color resetting. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset@inorderfalse" + }, + ["pgfsys@color@reset@inordertrue"] = { + details = [[ +Sets the optimized "in order" version of the color resetting. This is +the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@reset@inordertrue" + }, + ["pgfsys@color@rgb"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for stroking and filling operations to the given +red/green/blue tuple (numbers between 0 and 1). + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb" + }, + ["pgfsys@color@rgb@fill"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for filling operations to the given red/green/blue +tuple (numbers between 0 and 1). This color may be different from the +stroking color. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb@fill" + }, + ["pgfsys@color@rgb@stroke"] = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the color used for stroking operations to the given red/green/blue +tuple (numbers between 0 and 1). + +Make stroked text dark red: `\pgfsys@color@rgb@stroke{0.5}{0}{0}` + +The special stroking color is only used if the stroking color has been +set since the last `\color` or `\pgfsys@color@...` command. Thus, each +`\color` command will reset both the stroking and filling colors by +calling `\pgfsys@color@reset`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@rgb@stroke" + }, + ["pgfsys@color@unstacked"] = { + arguments = {{meta = "\\LaTeX\\ color"}}, + details = [[ +This slightly obscure command causes the color stack to be tricked. When +called, this command should set the current color to ⟨LaTeX color⟩ +without causing any change in the color stack. + +`\pgfsys@color@unstacked{red}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@color@unstacked" + }, + ["pgfsys@curveto"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x_3$"}, + {meta = "$y_3$"} + }, + details = [[ +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)$. + +Draw a good approximation of a quarter circle: + + \pgfsys@moveto{10pt}{0pt} + \pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt} + \pgfsys@stroke + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@curveto" + }, + ["pgfsys@declarepattern"] = { + arguments = { + {meta = "name"}, + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x$ step"}, + {meta = "$y$ step"}, + {meta = "$a$"}, + {meta = "$b$"}, + {meta = "$c$"}, + {meta = "$d$"} + }, + details = [[ +This command declares a new colored or uncolored pattern, depending on +whether ⟨flag⟩ is `0`, which means uncolored, or `1`, which means +colored. Uncolored patterns have no inherent color, the color is +provided when they are set. Colored patters have an inherent color. + +The ⟨name⟩ is a name for later use when the pattern is to be shown. The +pairs $(x_1,y_1)$ and $(x_2,y_2)$ must describe a bounding box of the +pattern ⟨code⟩. + +The tiling step of the pattern is given by ⟨$x$ step⟩ and ⟨$y$ step⟩. + +The parameters ⟨$a$⟩ to ⟨$f$⟩ are entries of the transformation matrix +that is applied to the pattern, see `\pgfsys@patternmatrix` for more +information. + + \pgfsys@declarepattern + {hori}{-.5pt}{0pt}{.5pt}{3pt}{3pt}{3pt}% + {1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}% + {\pgfsys@moveto{0pt}{0pt}\pgfsys@lineto{0pt}{3pt}\pgfsys@stroke} + {0} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@declarepattern" + }, + ["pgfsys@defineimage"] = { + details = [[ +Called, when an image should be defined. + +This command does not take any parameters. Instead, certain macros will +be preinstalled with appropriate values when this command is invoked. +These are: + +- `\pgf@filename` File name of the image to be defined. + +- `\pgf@imagewidth` Will be set to the desired (scaled) width of the + image. + +- `\pgf@imageheight` Will be set to the desired (scaled) height of the + image. + + If this macro and also the height macro are empty, the image should + have its "natural" size. + + 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 + independently, possibly changing the aspect ratio. + +The following macros presumable mostly make sense for drivers that can +handle PDF: + +- `\pgf@imagepage` The desired page number to be extracted from a + multi-page "image". + +- `\pgf@imagemask` If set, it will be set to `/SMask x 0 R` where `x` + is the PDF object number of a soft mask to be applied to the image. + +- `\pgf@imageinterpolate` If set, it will be set to + `/Interpolate true` or `/Interpolate false`, indicating whether the + image should be interpolated in PDF. + +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. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@defineimage" + }, + ["pgfsys@definemask"] = { + details = [[ +This command declares a fading (known as a soft mask in this context) +based on an image and for usage with images. It works similar to +`\pgfsys@defineimage`: Certain macros are set when the command is +called. The result should be to set the macro `\pgf@mask` to a pdf +object count that can subsequently be used as a transparency mask. The +following macros will be set when this command is invoked: + +- `\pgf@filename` File name of the mask to be defined. + +- `\pgf@maskmatte` The so-called matte of the mask (see the + PDF documentation for details). The matte is a color specification + consisting of 1, 3 or 4 numbers between 0 and 1. The number of + numbers depends on the number of color channels in the image (not in + the mask!). It will be assumed that the image has been preblended + with this color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@definemask" + }, + ["pgfsys@defobject"] = { + arguments = { + {meta = "name"}, + {meta = "lower left"}, + {meta = "upper right"}, + {meta = "code"} + }, + details = [[ +Declares an object for later use. The idea is that the object can be +precached in some way and then be rendered more quickly when used +several times. For example, an arrow head might be defined and +prerendered in this way. + +The parameter ⟨name⟩ is the name for later use. ⟨lower left⟩ and ⟨upper +right⟩ are PGF points specifying a bounding box for the object. ⟨code⟩ +is the code for the object. The code should not be too fancy. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@defobject" + }, + ["pgfsys@discardpath"] = { + details = [[ +Normally, this command should "throw away" the current path. However, +after `\pgfsys@clipnext` has been called, the current path should +subsequently be used for clipping. See `\pgfsys@clipnext` for details. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@discardpath" + }, + ["pgfsys@end@idscope"] = { + details = [[ +Ends the graphics id scope started by `\pgfsys@end@idscope`. It must +nest correctly with other graphic scopes and TeX scopes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@end@idscope" + }, + ["pgfsys@endinvisible"] = { + details = [[ +Ends the invisibility section, unless invisibility blocks have been +nested. In this case, only the "last" one restores visibility. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endinvisible" + }, + ["pgfsys@endpicture"] = { + details = [[ +Called at the end of a `{pgfpicture}`. + +Most drivers will need to implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endpicture" + }, + ["pgfsys@endpurepicture"] = { + details = [[ +Called at the end of a "pure" `{pgfpicture}`. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endpurepicture" + }, + ["pgfsys@endscope"] = { + details = [[ +Restores the last saved graphic state. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endscope" + }, + ["pgfsys@endviewbox"] = { + details = [[ +Ends a viewbox previously started using `\pgfsys@viewboxmeet` or the +`...slice` variant. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@endviewbox" + }, + ["pgfsys@fadingfrombox"] = { + arguments = {{meta = "name"}, {meta = "box"}}, + details = [[ +Declares the fading ⟨name⟩. The ⟨box⟩ is a TeX-box. Its 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fadingfrombox" + }, + ["pgfsys@fill"] = { + details = [[ +This command fills the area surrounded by the current path. If the path +has not yet been closed, it is closed prior to filling. The path itself +is not stroked. For self-intersecting paths or paths consisting of +multiple parts, the nonzero winding number rule is used to determine +whether a point is inside or outside the path, except if +`\ifpgfsys@eorule` holds -- in which case the even-odd rule should be +used. (See the PDF or PostScript manual for details.) + +The following graphic state parameters influence the filling: + +Interior rule +If `\ifpgfsys@eorule` is set, the even-odd rule is used, otherwise the +non-zero winding number rule. + +Fill color +If the fill color is not especially set, the current color is used. + +Clipping area +If a clipping area is established, only those parts of the filling area +that are inside the clipping area will be drawn. + +In addition to filling the path, the path will also be used for clipping +if `\pgfsys@clipnext` is used prior to this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fill" + }, + ["pgfsys@fill@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of filling operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fill@opacity" + }, + ["pgfsys@fillstroke"] = { + details = [[ +First, the path is filled, then the path is stroked. If the fill and +stroke colors are the same (or if they are not specified and the current +color is used), this yields almost the same as a `\pgfsys@fill`. +However, due to the line thickness of the stroked path, the fill-stroked +area will be slightly larger. + +In addition to stroking and filling the path, the path will also be used +for clipping if `\pgfsys@clipnext` is used prior to this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@fillstroke" + }, + ["pgfsys@functionalshading"] = { + arguments = { + {meta = "name"}, + {meta = "lower left corner"}, + {meta = "upper right corner"}, + {meta = "type 4 function"} + }, + details = [[ +Declares a shading using a PostScript-like function that provides a +color for each point. Like the previous macros, this command should set +up the macro `\@pgfshading`⟨name⟩`!` so that it will produce a box +containing the desired shading. + +Parameter ⟨name⟩ is the name of the shading. Parameter ⟨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. +Parameters ⟨lower left corner⟩ and ⟨upper right corner⟩ are PGF points +that specifies the lower left and upper right corners of the shading, +respectively. + +When ⟨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 cvrs at the end if needed) that represent the red, green, and blue +components of the color. + +A buggy function will result is *totally unpredictable chaos* during +rendering. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@functionalshading" + }, + ["pgfsys@getposition"] = { + arguments = {{meta = "name"}, {meta = "macro"}}, + details = [[ +This command retrieves a position that has been marked on an earlier run +of TeX on the current file. The ⟨macro⟩ must be a macro name such as +`\mymacro`. It will be redefined such that it is + +- either just `\relax` or + +- a `\pgfpoint...` command. + +The first case will happen when the position has not been marked at all +or when the file is typeset for the first time, when the coordinates are +not yet available. + +In the second case, executing ⟨macro⟩ yields the position on the page +that is to be interpreted as follows: A coordinate like +`\pgfpoint{2cm}{3cm}` means "2cm to the right and 3cm up from the origin +of the page". The position of the origin of the page is not guaranteed +to be at the lower left corner, it is only guaranteed that all pictures +on a page use the same origin. + +To determine the lower left corner of a page, you can call +`\pgfsys@getposition` with ⟨name⟩ set to the special name +`pgfpageorigin`. By shifting all positions by the amount returned by +this call you can position things absolutely on a page. + +Referencing a point of the page: + + The value of $x$ is \pgfsys@markposition{here}important. + + Lots of text. + + \hbox{\pgfsys@markposition{myorigin}% + \begin{pgfpicture} + % Switch of size protocol + \pgfpathmoveto{\pgfpointorigin} + \pgfusepath{use as bounding box} + + \pgfsys@getposition{here}{\hereposition} + \pgfsys@getposition{myorigin}{\thispictureposition} + + \pgftransformshift{\pgfpointscale{-1}{\thispictureposition}} + \pgftransformshift{\hereposition} + + \pgfpathcircle{\pgfpointorigin}{1cm} + \pgfusepath{draw} + \end{pgfpicture}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@getposition" + }, + ["pgfsys@global@papersize"] = { + arguments = {{meta = "width"}, {meta = "height"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@global@papersize" + }, + ["pgfsys@hbox"] = { + arguments = {{meta = "box number"}}, + details = [[ +Called to insert a (horizontal) TeX box inside a `{pgfpicture}`. + +Most drivers will need to (re-)implement this command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@hbox" + }, + ["pgfsys@hboxsynced"] = { + arguments = {{meta = "box number"}}, + details = [[ +Called to insert a (horizontal) TeX box inside a `{pgfpicture}`, but +with the current coordinate transformation matrix synced with the canvas +transformation matrix. + +This command should do the same as if you used `\pgflowlevelsynccm` +followed by `\pgfsys@hbox`. However, the default implementation of this +command will use a "TeX-translation" for the translation part of the +transformation matrix. This will ensure that hyperlinks "survive" at +least translations. On the other hand, a driver may choose to revert to +a simpler implementation. This is done, for example, for the SVG +implementation, where a TeX-translation makes no sense. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@hboxsynced" + }, + ["pgfsys@horishading"] = { + arguments = {{meta = "name"}, {meta = "height"}, {meta = "specification"}}, + details = [[ +Declares a horizontal shading for later use. The effect of this command +should be the definition of a macro called `\@pgfshading`⟨name⟩`!` (or +`\csname @pdfshading`⟨name⟩`!\endcsname`, to be precise). When invoked, +this new macro should insert a shading at the current position. + +⟨name⟩ is the name of the shading, which is also used in the output +macro name. ⟨height⟩ is the height of the shading and must be given as a +TeX dimension like `2cm` or `10pt`. ⟨specification⟩ is a shading color +specification as specified in Section ??. The shading specification +implicitly fixes the width of the shading. + +When `\@pgfshading`⟨name⟩`!` is invoked, it should insert a box of +height ⟨height⟩ and the width implicit in the shading declaration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@horishading" + }, + ["pgfsys@imagesuffixlist"] = { + details = [[ +This macro should expand to a list of suffixes, separated by ':', that +will be tried when searching for an image. + +`\def\pgfsys@imagesuffixlist{eps:epsi:ps}` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@imagesuffixlist" + }, + ["pgfsys@invoke"] = { + arguments = {{meta = "literals"}}, + details = [[ +This command gets protocolled literals and should insert them into the +`.pdf` or `.dvi` file using an appropriate `\special`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@invoke" + }, + ["pgfsys@lineto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Continue the current path to $(x,y)$ with a straight line. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@lineto" + }, + ["pgfsys@marker@declare"] = { + arguments = {{meta = "macro"}, {meta = "code"}}, + details = [[ +Declares a *marker* symbol for later use. The command is very similar to +`\pgfsys@defobject`, but the use case is slightly different: The graphic +object defined using the ⟨code⟩ is stored in such a way that it can be +used as an *arrow tip marker symbol* in animations. The ⟨macro⟩ is set +to an identifier by which the marker can be referenced later on. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@marker@declare" + }, + ["pgfsys@marker@use"] = { + arguments = {{meta = "macro"}}, + details = [[ +Adds the marker object referenced by the ⟨macro⟩ to the current output. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@marker@use" + }, + ["pgfsys@markposition"] = { + arguments = {{meta = "name"}}, + details = [[ +Marks a position on the page. This command should be given while normal +typesetting is done such as in + + The value of $x$ is \pgfsys@markposition{here}important. + +It causes the position `here` to be saved when the page is shipped out. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@markposition" + }, + ["pgfsys@miterjoin"] = { + details = [[ +Sets the join to a miter join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@miterjoin" + }, + ["pgfsys@moveto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command is used to start a path at a specific point $(x,y)$ or to +move the current point of the current path to $(x,y)$ without drawing +anything upon stroking (the current path is "interrupted"). + +Both ⟨x⟩ and ⟨y⟩ are given as TeX dimensions. It is the driver's job to +transform these to the coordinate system of the backend. Typically, this +means converting the TeX dimension into a dimensionless multiple of +$\frac{1}{72}\mathrm{in}$. The function `\pgf@sys@bp` helps with this +conversion. + +Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the origin of the +picture. + + \pgfsys@moveto{10pt}{10pt} + \pgfsys@lineto{0pt}{0pt} + \pgfsys@stroke + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@moveto" + }, + ["pgfsys@new@id"] = { + arguments = {{meta = "macro"}}, + details = [[ +Creates a new id for later use and stores it in ⟨macro⟩. It is an +internal text created by the driver and may not be changed or modified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@new@id" + }, + ["pgfsys@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of all operations, treating stroking and filling as a +transparency group. Some drivers support this operations, others do not +and set the fill and stroke individually. This difference can only be +seen when a path is stroked and filled at the same time: When the +drawing and fill opacities are set individually, the effect of filling +and drawing a path at the same time is the same as first filling the +path and then drawing it. On the other, if the opacity is set using this +command, the effect should rather be that same as first filling and then +drawing the path without any opacity in an off-screen area and then +copying the result to the target area with a homogeneous opacity of +⟨value⟩. + +Since PDF does not support this form of opacity, this command is only +present on the system layer and not supported in the basic layer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@opacity" + }, + ["pgfsys@papersize"] = { + arguments = {{meta = "width"}, {meta = "height"}}, + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@papersize" + }, + ["pgfsys@patternmatrix"] = { + details = [[ +For convenience PGF defines the transformation matrix that is applied to +all patterns defined with `\pgfdeclarepatternformonly` and +`\pgfdeclarepatterninherentlycolored` in a macro. This can be used as an +extension point for ad-hoc transformation of existing patterns. The +default definition is the identity matrix: + + \def\pgfsys@patternmatrix{{1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}} + +The entries of the enclosed array +`{`⟨$a$⟩`}{`⟨$b$⟩`}{`⟨$c$⟩`}{`⟨$d$⟩`}{`⟨$e$⟩`}{`⟨$f$⟩`}` are entries in +the transformation matrix, identified as in the following transformation +prescription: $$\begin{pmatrix} + x' \\ + y' \\ + 1 \\ + \end{pmatrix} + = + \begin{pmatrix} + a & c & e \\ + b & d & f \\ + 0 & 0 & 1 \\ + \end{pmatrix} + \begin{pmatrix} + x \\ + y \\ + 1 \\ + \end{pmatrix} .$$ Carrying out the matrix multiplication results +in the following system of equations $$\begin{aligned} + x' &= a x + c y + e , \\ + y' &= b x + d y + f . + \end{aligned}$$ Evidently, the parameters `{a}` to `{d}` have to be +dimensionless because they are scaling factors, but the parameters `{e}` +and `{f}` are offsets, therefore they have to carry a unit. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@patternmatrix" + }, + ["pgfsys@pictureboxsynced"] = { + arguments = {{meta = "box number"}}, + details = [[ +Basically, this should do the same as doing a (scoped) low level sync +followed by inserting the box ⟨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 PDFs. Drivers that are sensitive to +picture-in-picture scopes should replace this implementation by + + \pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@pictureboxsynced" + }, + ["pgfsys@pop@type"] = { + details = [[ +Restores the most recently pushed type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@pop@type" + }, + ["pgfsys@push@type"] = { + details = [[ +Pushes the current type on a global "stack of types" without opening a +TeX scope. The is useful when you temporarily wish to change the type +(for instance, by appending something to it), but you cannot create a +new scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@push@type" + }, + ["pgfsys@radialshading"] = { + arguments = { + {meta = "name"}, + {meta = "starting point"}, + {meta = "specification"} + }, + details = [[ +Declares a radial shading. Like the previous macros, this command should +set up the macro `\@pgfshading`⟨name⟩`!`, which upon invocation should +insert a radial shading whose size is implicit in ⟨specification⟩. + +The parameter ⟨starting point⟩ is a PGF point specifying the inner +starting point of the shading. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@radialshading" + }, + ["pgfsys@rdf@about"] = { + arguments = {{meta = "text"}}, + details = [[ +Adds the RDF attribute `about="`⟨text⟩`"` to the next id scope (please +see the RDFa specification for details on the semantics of `about` in +the context of the resource description framework). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@about" + }, + ["pgfsys@rdf@content"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@content" + }, + ["pgfsys@rdf@datatype"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@datatype" + }, + ["pgfsys@rdf@href"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@href" + }, + ["pgfsys@rdf@inlist"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@inlist" + }, + ["pgfsys@rdf@prefix"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@prefix" + }, + ["pgfsys@rdf@property"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@property" + }, + ["pgfsys@rdf@rel"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@rel" + }, + ["pgfsys@rdf@resource"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@resource" + }, + ["pgfsys@rdf@rev"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@rev" + }, + ["pgfsys@rdf@src"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@src" + }, + ["pgfsys@rdf@typeof"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@typeof" + }, + ["pgfsys@rdf@vocab"] = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rdf@vocab" + }, + ["pgfsys@rect"] = { + arguments = {{meta = "x"}, {meta = "y"}, {meta = "width"}, {meta = "height"}}, + details = [[ +Append a rectangle to the current path whose lower left corner is at +$(x,y)$ and whose width and height in big points are given by ⟨width⟩ +and ⟨height⟩. + +This command can be "mapped back" to `\pgfsys@moveto` and +`\pgfsys@lineto` commands, but it is included since PDF has a special, +quick version of this command. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rect" + }, + ["pgfsys@rectcap"] = { + details = [[ +Sets the cap to a rectangular cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@rectcap" + }, + ["pgfsys@roundcap"] = { + details = [[ +Sets the cap to a round cap. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@roundcap" + }, + ["pgfsys@roundjoin"] = { + details = [[ +Sets the join to a round join. See `\pgfsys@stroke`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@roundjoin" + }, + ["pgfsys@setdash"] = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ +Sets the dashing patter. ⟨pattern⟩ should be a list of TeX dimensions +separated by commas. ⟨phase⟩ should be a single dimension. + +`\pgfsys@setdash{3pt,3pt}{0pt}` + +The list of values in ⟨pattern⟩ is used to determine the lengths of the +"on" and "off" phases of the dashing. For example, if ⟨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, ..." If the number of entries is odd, the last one is used twice, so +`3pt` means "3pt on, 3pt off, 3pt on, 3pt off, ..." An empty list means +"always on". + +The second argument determines the "phase" of the pattern. For example, +for a pattern of `3bp,4bp` and a phase of `1bp`, the pattern would +start: "2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, ..." + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setdash" + }, + ["pgfsys@setlinewidth"] = { + arguments = {{meta = "width"}}, + details = [[ +Sets the width of lines, when stroked, to ⟨width⟩, which must be a +TeX dimension. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setlinewidth" + }, + ["pgfsys@setmiterlimit"] = { + arguments = {{meta = "factor"}}, + details = [[ +Sets the miter limit of lines to ⟨factor⟩. See the PDF or PostScript for +details on what the miter limit is. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setmiterlimit" + }, + ["pgfsys@setpatterncolored"] = { + arguments = {{meta = "name"}}, + details = [[ +Sets the fill color to the pattern named ⟨name⟩. This pattern must have +been declared with the `1` flag. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setpatterncolored" + }, + ["pgfsys@setpatternuncolored"] = { + arguments = {{meta = "name"}, {meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ +Sets the fill color to the pattern named ⟨name⟩. This pattern must +previously have been declared with ⟨flag⟩ set to `0`. The color of the +pattern is given in the parameters ⟨red⟩, ⟨green⟩, and ⟨blue⟩ in the +usual way. + +The fill color "pattern" will persist till the next color command that +modifies the fill color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@setpatternuncolored" + }, + ["pgfsys@stroke"] = { + details = [[ +Stroke the current path (as if it were drawn with a pen). A number of +graphic state parameters influence this, which can be set using +appropriate system commands described later. + +Line width +The "thickness" of the line. A width of 0 is the thinnest width +renderable on the device. On a high-resolution printer this may become +invisible and should be avoided. A good choice is 0.4pt, which is the +default. + +Stroke color +This special color is used for stroking. If it is not set, the current +color is used. + +Cap +The cap describes how the endings of lines are drawn. A round cap adds a +little half circle to these endings. A butt cap ends the lines exactly +at the end (or start) point without anything added. A rectangular cap +ends the lines like the butt cap, but the lines protrude over the +endpoint by the line thickness. (See also the PDF manual.) If the path +has been closed, no cap is drawn. + +Join +This describes how a bend (a join) in a path is rendered. A round join +draws bends using small arcs. A bevel join just draws the two lines and +then fills the join minimally so that it becomes convex. A miter join +extends the lines so that they form a single sharp corner, but only up +to a certain miter limit. (See the PDF manual once more.) + +Dash +The line may be dashed according to a dashing pattern. + +Clipping area +If a clipping area is established, only those parts of the path that are +inside the clipping area will be drawn. + +In addition to stroking a path, the path may also be used for clipping +after it has been stroked. This will happen if the `\pgfsys@clipnext` is +used prior to this command, see there for details. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@stroke" + }, + ["pgfsys@stroke@opacity"] = { + arguments = {{meta = "value"}}, + details = [[ +Sets the opacity of stroking operations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@stroke@opacity" + }, + ["pgfsys@thepageheight"] = { + details = [[ +This macro expands to the current page's height, provided LaTeX is used, +otherwise a best guess is returned (currently just `\the\vsize`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@thepageheight" + }, + ["pgfsys@thepagewidth"] = { + details = [[ +As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@thepagewidth" + }, + ["pgfsys@transformcm"] = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "e"}, + {meta = "f"} + }, + details = [[ +Perform a concatenation of the canvas transformation matrix with the +matrix given by the values ⟨a⟩ to ⟨f⟩, see the PDF or PostScript manual +for details. The values ⟨a⟩ to ⟨d⟩ are dimensionless factors, ⟨e⟩ and +⟨f⟩ are TeX dimensions + +`\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}`. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformcm" + }, + ["pgfsys@transformshift"] = { + arguments = {{meta = "x displacement"}, {meta = "y displacement"}}, + details = [[ +This command will change the origin of the canvas to $(x,y)$. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformshift" + }, + ["pgfsys@transformxyscale"] = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ +This command will scale the canvas (and everything that is drawn) by a +factor of ⟨x scale⟩ in the $x$-direction and ⟨y scale⟩ in the +$y$-direction. Note that this applies to everything, including lines. So +a scaled line will have a different width and may even have a different +width when going along the $x$-axis and when going along the $y$-axis, +if the scaling is different in these directions. Usually, you do not +want this. + +This command has a default implementation and need not be implemented by +a driver file. + +This command is protocolled, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transformxyscale" + }, + ["pgfsys@transparencygroupfrombox"] = { + arguments = {{meta = "box"}}, + details = [[ +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 with 50% transparency, then +the overlap will be darker than the rest. By comparison, if the circles +are part of a transparency group, the overlap will get the same color as +the rest. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@transparencygroupfrombox" + }, + ["pgfsys@typesetpicturebox"] = { + arguments = {{meta = "box"}}, + details = [[ +Called *after* a `{pgfpicture}` has been typeset. The picture will have +been put in box ⟨box⟩. This command should insert the box into the +normal text. The box ⟨box⟩ will still be a "raw" box that contains only +the `\special`'s that make up the description of the picture. The job of +this command is to resize and shift ⟨box⟩ according to the baseline +shift and the size of the box. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@typesetpicturebox" + }, + ["pgfsys@use@id"] = { + arguments = {{meta = "id"}}, + details = [[ +"Uses" an id previously created using `\pgfsys@new@id`. This causes the +*next* graphic object to get the ⟨id⟩ (not the current one). Once used, +the id-type-pair becomes *invalid* and will not be attached to any other +graphics objects. It is, however, not an error to try this. If ⟨id⟩ is +empty, no id-type-pair is attached to the next object. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@use@id" + }, + ["pgfsys@use@type"] = { + arguments = {{meta = "type"}}, + details = [[ +Changes the type used with the next graphic object. As mentioned +earlier, the id assigned to the next object is actually a pair +consisting of the currently used id and the currently used type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@use@type" + }, + ["pgfsys@usefading"] = { + arguments = { + {meta = "name"}, + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "e"}, + {meta = "f"} + }, + details = [[ +Installs a previously declared fading ⟨name⟩ in the current graphics +state. Afterwards, all drawings will be masked by the fading. The fading +should be centered on the origin and have its original size, except that +the parameters ⟨a⟩ to ⟨f⟩ specify a transformation matrix that should be +applied additionally to the fading before it is installed. The +transformation should not apply to the following graphics, however. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@usefading" + }, + ["pgfsys@useobject"] = { + arguments = {{meta = "name"}, {meta = "extra code"}}, + details = [[ +Renders a previously declared object. The first parameter is the name of +the object. The second parameter is extra code that should be executed +right *before* the object is rendered. Typically, this will be some +transformation code. + +This command has a default implementation and need not be implemented by +a driver file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@useobject" + }, + ["pgfsys@vertshading"] = { + arguments = {{meta = "name"}, {meta = "width"}, {meta = "specification"}}, + details = [[ +Like the horizontal version, only for vertical shadings. This time, the +height of the shading is implicit in ⟨specification⟩ and the width is +given as ⟨width⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@vertshading" + }, + ["pgfsys@viewboxmeet"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x'_1$"}, + {meta = "$y'_1$"}, + {meta = "$x'_2$"}, + {meta = "$y'_2$"} + }, + details = [[ +Starts a "view box" scope, which must be ended using +`\pgfsys@endviewbox` later on (with matching scopes). + +The effect of this command is as follows: Consider the rectangles $R$ +with lower left corner $(x_1,y_1)$ and upper right corner $(x_2,y_2)$ +and $R'$ with corners $(x'_1,y'_1)$ and $(x'_2,y'_2)$. The command will +install a canvas translation and uniform scaling such that $R'$ then has +the same center as $R$ and additionally, has maximum size such that it +still fits inside $R$. (Think of this as "viewing" $R'$ through $R$ such +that the aspect ratio is kept.) + +This command has a default implementation. Its main purpose is to allow +animations of the view box; for static drawings it is better to compute +the necessary transformations directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@viewboxmeet" + }, + ["pgfsys@viewboxslice"] = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"}, + {meta = "$x'_1$"}, + {meta = "$y'_1$"}, + {meta = "$x'_2$"}, + {meta = "$y'_2$"} + }, + details = [[ +Works like the previous command, but now $R'$ has minimal size such that +it encompasses all of $R$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsys@viewboxslice" + }, + pgfsysanimate = { + arguments = {{meta = "attribute"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimate" + }, + pgfsysanimkeyaccesskey = { + arguments = { + {meta = "character"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyaccesskey" + }, + pgfsysanimkeyaccumulate = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyaccumulate" + }, + pgfsysanimkeybase = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeybase" + }, + pgfsysanimkeycanvastransform = { + arguments = {{meta = "pre"}, {meta = "post"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeycanvastransform" + }, + pgfsysanimkeyevent = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "event name"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyevent" + }, + pgfsysanimkeyfreezeatend = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyfreezeatend" + }, + pgfsysanimkeymovealong = { + arguments = {{meta = "path"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeymovealong" + }, + pgfsysanimkeynoaccumulate = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeynoaccumulate" + }, + pgfsysanimkeynorotatealong = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeynorotatealong" + }, + pgfsysanimkeyoffset = { + arguments = {{meta = "time offset"}, {meta = "begin or end"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyoffset" + }, + pgfsysanimkeyremoveatend = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyremoveatend" + }, + pgfsysanimkeyrepeat = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeat" + }, + pgfsysanimkeyrepeatdur = { + arguments = {{meta = "seconds"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatdur" + }, + pgfsysanimkeyrepeatevent = { + arguments = { + {meta = "id"}, + {meta = "type"}, + {meta = "repeat count"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatevent" + }, + pgfsysanimkeyrepeatindefinite = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrepeatindefinite" + }, + pgfsysanimkeyrestartalways = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartalways" + }, + pgfsysanimkeyrestartnever = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartnever" + }, + pgfsysanimkeyrestartwhennotactive = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrestartwhennotactive" + }, + pgfsysanimkeyrotatealong = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeyrotatealong" + }, + pgfsysanimkeysnapshotstart = { + arguments = {{meta = "time offset"}}, + details = [[ +This command specifies that for the current animation the "moment `0s`" +of the timeline is at ⟨time offset⟩. Thus, it works like +`\pgfsysanimkeyoffset`, only the offset is now solely for the snapshot +timeline. It has no effect on the actual animation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysnapshotstart" + }, + pgfsysanimkeysyncbegin = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysyncbegin" + }, + pgfsysanimkeysyncend = { + arguments = { + {meta = "sync base id"}, + {meta = "type"}, + {meta = "time offset"}, + {meta = "begin or end"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeysyncend" + }, + pgfsysanimkeytime = { + arguments = { + {meta = "time"}, + {meta = "entry spline control x"}, + {meta = "entry spline control y"}, + {meta = "exit spline control x"}, + {meta = "exit spline control y"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeytime" + }, + pgfsysanimkeytipmarkers = { + arguments = {{meta = "start marker"}, {meta = "end marker"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeytipmarkers" + }, + pgfsysanimkeywhom = { + arguments = {{meta = "id"}, {meta = "type"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimkeywhom" + }, + pgfsysanimsnapshot = { + arguments = {{meta = "time"}}, + details = [[ +Use this command in a scope prior to calling any other commands +documented in this section concerning the configuration of animations. +In this case, all uses of `\pgfsysanimate` inside the TeX scope no +longer insert an animation into the output file. Instead, a "snapshot" +is inserted of what the animation "would like at time ⟨time⟩". For +instance, if an animation inserts a movement of an object by 4cm over a +time of 2s and you take a snapshot with $⟨time⟩ = 2\mathrm s$, you get a +picture in which the object is moved by 1cm. + +A lot of care has been taken to make the output produced by the snapshot +be as close as possible as what the animation really would look like at +time ⟨time⟩, but note the following restrictions: + +1. Interactive events of all kinds (like `click` or `mouseover`) make + little sense for snapshots, which are created once and for all + during the typesetting of the document. For this reason, all events + are ignored for snapshots (even sync bases, and `begin` and `end` + events, which might make some sense also in a snapshot setting). + + However, there is one command which helps you with "simulating" the + effect of events: + +2. The command `\pgfsysanimvalcurrent` cannot be used with snapshots + since PGF has no chance of computing the correct current value. You + always have to specify the start value explicitly. + +3. The computation of time splines (entry and exit splines) and the + accumulation of values after a large number of repeats may not be + numerically stable. + +  + + \foreach \t in {0.5,1,1.5,2} { + \pgfsysanimsnapshot{\t} + \tikz { + \pgfidrefnextuse{\objid}{node} + \pgfsysanimkeywhom{\objid}{} + \pgfsysanimkeytime{0}{1}{1}{0}{0} + \pgfsysanimvalscalar{1} + \pgfsysanimkeytime{2}{1}{1}{0}{0} + \pgfsysanimvalscalar{0} + \pgfsysanimate{opacity} + \node (node) [draw = blue, very thick, fill=blue!20, circle] {Hi}; + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimsnapshot" + }, + pgfsysanimsnapshotafter = { + arguments = {{meta = "time"}}, + details = [[ +Works like the previous command, only the "moment" that ⟨time⟩ refers to +is conceptually $⟨time⟩ + \epsilon$: When timeline specifies several +values for ⟨time⟩, this command will select the last value at ⟨time⟩, +while `\pgfsnapshot` will select the first value at ⟨time⟩. Similarly, +when a timeline ends at ⟨time⟩, `\pgfsnapshot` will select the last +value of the timeline while `\pgfsnapshotafter` will not apply the +animation any more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimsnapshotafter" + }, + pgfsysanimvalcolorcmy = { + arguments = {{meta = "cyan"}, {meta = "magenta"}, {meta = "yellow"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorcmy" + }, + pgfsysanimvalcolorcmyk = { + arguments = { + {meta = "cyan"}, + {meta = "magenta"}, + {meta = "yellow"}, + {meta = "black"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorcmyk" + }, + pgfsysanimvalcolorgray = { + arguments = {{meta = "gray value"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorgray" + }, + pgfsysanimvalcolorrgb = { + arguments = {{meta = "red"}, {meta = "green"}, {meta = "blue"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcolorrgb" + }, + pgfsysanimvalcurrent = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalcurrent" + }, + pgfsysanimvaldash = { + arguments = {{meta = "pattern"}, {meta = "phase"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaldash" + }, + pgfsysanimvaldimension = { + arguments = {{meta = "dimension"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaldimension" + }, + pgfsysanimvalpath = { + arguments = {{meta = "low-level path construction commands"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalpath" + }, + pgfsysanimvalscalar = { + arguments = {{meta = "number"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalscalar" + }, + pgfsysanimvalscale = { + arguments = {{meta = "x scale"}, {meta = "y scale"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalscale" + }, + pgfsysanimvaltext = { + arguments = {{meta = "text"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaltext" + }, + pgfsysanimvaltranslate = { + arguments = {{meta = "x dimension"}, {meta = "y dimension"}}, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvaltranslate" + }, + pgfsysanimvalviewbox = { + arguments = { + {meta = "$x_1$"}, + {meta = "$y_1$"}, + {meta = "$x_2$"}, + {meta = "$y_2$"} + }, + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysanimvalviewbox" + }, + pgfsysdriver = { + details = [[ +This macro should expand to the name of the driver to be used by +`pgfsys`. The default from `pgf.cfg` is `pgfsys-\Gin@driver`. This is +very likely to be correct if you are using LaTeX. For plain TeX, the +macro will be set to `pgfsys-pdftex.def` if `pdftex` is used and to +`pgfsys-dvips.def` otherwise. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysdriver" + }, + ["pgfsysprotocol@bufferedfalse"] = { + details = [[ +Turns off protocolling. Subsequent calls of `\pgfsysprotocol@literal` +directly insert their argument into the current `.pdf` or `.ps`. + +Note that if the current protocol is not empty when protocolling is +switched off, the next call to `\pgfsysprotocol@literal` will first +flush the current protocol, that is, insert it into the file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@bufferedfalse" + }, + ["pgfsysprotocol@bufferedtrue"] = { + details = [[ +Turns on protocolling. All subsequent calls of `\pgfsysprotocol@literal` +will append their argument to the current protocol. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@bufferedtrue" + }, + ["pgfsysprotocol@flushcurrentprotocol"] = { + details = [[ +First inserts the current protocol, then sets the current protocol to +the empty string. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@flushcurrentprotocol" + }, + ["pgfsysprotocol@getcurrentprotocol"] = { + arguments = {{meta = "macro name"}}, + details = [[ +Stores the current protocol in ⟨macro name⟩ for later use. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@getcurrentprotocol" + }, + ["pgfsysprotocol@invokecurrentprotocol"] = { + details = [[ +Inserts the text stored in the current protocol into the `.pdf` or +`.dvi` file. This does *not* change the current protocol. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@invokecurrentprotocol" + }, + ["pgfsysprotocol@literal"] = { + arguments = {{meta = "literal text"}}, + details = [[ +First calls `\pgfsysprotocol@literalbuffered` on ⟨literal text⟩. Then, +if protocolling is currently switched off, the ⟨literal text⟩ is passed +on to `\pgfsys@invoke`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@literal" + }, + ["pgfsysprotocol@literalbuffered"] = { + arguments = {{meta = "literal text"}}, + details = [[ +Adds the ⟨literal text⟩ to the current protocol, after it has been +"`\edef`ed". This command will always be protocolled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@literalbuffered" + }, + ["pgfsysprotocol@setcurrentprotocol"] = { + arguments = {{meta = "macro name"}}, + details = [[ +Sets the current protocol to ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsysprotocol@setcurrentprotocol" + }, + ["pgfsyssoftpath@closepath"] = { + details = [[ +Appends a "close-path" segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@closepath" + }, + ["pgfsyssoftpath@curveto"] = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "x"}, + {meta = "y"} + }, + details = [[ +Appends a "curve-to" segment to the current soft path with controls +$(a,b)$ and $(c,d)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@curveto" + }, + ["pgfsyssoftpath@flushcurrentpath"] = { + details = [[ +This command will invoke the current soft path and then set it to be +empty. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@flushcurrentpath" + }, + ["pgfsyssoftpath@getcurrentpath"] = { + arguments = {{meta = "macro name"}}, + details = [[ +This command will store the current soft path in ⟨macro name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@getcurrentpath" + }, + ["pgfsyssoftpath@invokecurrentpath"] = { + details = [[ +This command will turn the current soft path in a "hard" path. To do so, +it iterates over the soft path and calls an appropriate `\pgfsys@xxxx` +command for each element of the path. Note that the current soft path is +*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 seem strange, but it is +often useful to immediately use the last soft path again. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@invokecurrentpath" + }, + ["pgfsyssoftpath@lineto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +Appends a "line-to" segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@lineto" + }, + ["pgfsyssoftpath@moveto"] = { + arguments = {{meta = "x"}, {meta = "y"}}, + details = [[ +This command appends a "move-to" segment to the current soft path. The +coordinates ⟨x⟩ and ⟨y⟩ are given as normal TeX dimensions. + +One way to draw a line: + + \pgfsyssoftpath@moveto{0pt}{0pt} + \pgfsyssoftpath@lineto{10pt}{10pt} + \pgfsyssoftpath@flushcurrentpath + \pgfsys@stroke +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@moveto" + }, + ["pgfsyssoftpath@rect"] = { + arguments = { + {meta = "lower left x"}, + {meta = "lower left y"}, + {meta = "width"}, + {meta = "height"} + }, + details = [[ +Appends a rectangle segment to the current soft path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@rect" + }, + ["pgfsyssoftpath@setcurrentpath"] = { + arguments = {{meta = "macro name"}}, + details = [[ +This command will set the current soft path to be the path stored in +⟨macro name⟩. This macro should store a path that has previously been +extracted using the `\pgfsyssoftpath@getcurrentpath` command and has +possibly been modified subsequently. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfsyssoftpath@setcurrentpath" + }, + pgftext = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:pgf#/keys/pgf", + meta = "options", + optional = true + }, + {meta = "text"} + }, + details = [[ +This command will typeset ⟨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. By default, the +text box is centered at the origin, but this can be changed either by +giving appropriate ⟨options⟩ or by applying an appropriate coordinate +transformation beforehand. + +The ⟨text⟩ may contain verbatim text. (In other words, the ⟨text⟩ +"argument" is not a normal argument, but is put in a box and some +`\aftergroup` hackery is used to find the end of the box.) + +PGF's current (high-level) coordinate transformation is synchronized +with the canvas transformation matrix temporarily when the text box is +inserted. The effect is that if there is currently a high-level rotation +of, say, 30 degrees, the ⟨text⟩ will also be rotated by thirty degrees. +If you do not want this effect, you have to (possibly temporarily) reset +the high-level transformation matrix. + +The ⟨options⟩ keys are used with the path `/pgf/text/`. The following +keys are defined for this path: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftext" + }, + pgftransformarcaxesattime = { + arguments = { + {meta = "time $t$"}, + {meta = "center"}, + {meta = "0-degree axis"}, + {meta = "90-degree axis"}, + {meta = "start angle"}, + {meta = "end angle"} + }, + details = [[ +Shifts coordinates by a specific point on an arc at a specific time, see +Section ?? once more. + +As for the previous commands, `\ifpgfslopedattime` decides whether an +additional rotation should be applied and `\ifpgfallowupsidedowattime` +is also considered. + + \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} + +The value of `\ifpgfresetnontranslationsattime` is also taken into +account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformarcaxesattime" + }, + pgftransformarrow = { + arguments = {{meta = "start"}, {meta = "end"}}, + details = [[ +Shifts coordinates to the end of the line going from ⟨start⟩ to ⟨end⟩ +with the correct rotation. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (3,1); + \pgftransformarrow{\pgfpointorigin}{\pgfpoint{3cm}{1cm}} + \pgftext{tip} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformarrow" + }, + pgftransformationadjustments = { + details = [[ +This command computes "adjustments" for the current transformation +matrix so that even when you install a transformation matrix that scales +everything by a certain factor, you can still draw something of "an +absolute size". Suppose for instance that you install a transformation +matrix that scales everything by a factor of 4 and you now wish to draw +a horizontal line of length 1cm. Then, if you do not reset the +transformation matrix, you can draw a line of logical length 2.5mm, +which will then get scaled to a line of 1cm. Things get more difficult +in case you scale things only, say, vertically. In this case, the +adjustment necessary for horizontal lines is different from the one +needed for vertical lines. + +This function computes two scaling factors, one for horizontal lines and +one for vertical lines, and stores them in the following macros: + +Note that the "right" way to draw a line of absolute length 1cm in a +transformed coordinate system is to first compute the start point and to +then reset the transformation matrix. The transformation adjustments +computed here are important only in situations where you cannot do this, +for instance when an `outer xsep` must be set. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformationadjustments" + }, + pgftransformcm = { + arguments = { + {meta = "a"}, + {meta = "b"}, + {meta = "c"}, + {meta = "d"}, + {meta = "point"} + }, + details = [[ +Applies the transformation matrix given by $a$, $b$, $c$, and $d$ and +the shift ⟨point⟩ to coordinates (in addition to any previous +transformations already in force). + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformcm{1}{1}{0}{1}{\pgfpoint{.25cm}{.25cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformcm" + }, + pgftransformcurveattime = { + arguments = { + {meta = "time"}, + {meta = "start"}, + {meta = "first support"}, + {meta = "second support"}, + {meta = "end"} + }, + details = [[ +Shifts coordinates by a specific point on a curve at a specific time, +see Section ?? once more. + +As for the line-at-time transformation command, `\ifpgfslopedattime` +decides whether an additional rotation should be applied. Again, the +value of `\ifpgfallowupsidedowattime` is also considered. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) .. controls (0,2) and (1,2) .. (2,1); + \pgfslopedattimetrue + \pgftransformcurveattime{.25}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + +The value of `\ifpgfresetnontranslationsattime` is also taken into +account. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformcurveattime" + }, + pgftransforminvert = { + details = [[ +Replaces the coordinate transformation matrix by a coordinate +transformation matrix that "exactly undoes the original transformation". +For example, if the original transformation was "scale by 2 and then +shift right by 1cm" the new one is "shift left by 1cm and then scale by +$1/2$". + +This command will produce an error if the determinant of the matrix is +too small, that is, if the matrix is near-singular. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransforminvert + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransforminvert" + }, + pgftransformlineattime = { + arguments = {{meta = "time"}, {meta = "start"}, {meta = "end"}}, + details = [[ +Shifts coordinates by a specific point on a line at a specific time. The +point by which the coordinate is shifted is calculated by calling +`\pgfpointlineattime`, see Section ??. + +In addition to shifting the coordinate, a rotation *may* also be +applied. Whether this is the case depends on whether the TeX if +`\ifpgfslopedattime` is set to true or not. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + +If `\ifpgfslopedattime` is true, another TeX `\if` is important: +`\ifpgfallowupsidedowattime`. If this is false, PGF will 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 +`\ifpgfresetnontranslationattime` to true, then, between shifting the +coordinate and (possibly) rotating/sloping the coordinate, the command +`\pgftransformresetnontranslations` is called. See the description of +this command for details. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimefalse + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{1.5} + \draw (0,0) -- (2,1); + \pgfslopedattimetrue + \pgfresetnontranslationattimetrue + \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}} + \pgftext{Hi!} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformlineattime" + }, + pgftransformnonlinear = { + arguments = {{meta = "transformation code"}}, + details = [[ +This command adds the ⟨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 ⟨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: + + \def\polartransformation{% + % \pgf@x will contain the radius + % \pgf@y will contain the distance + \pgfmathsincos@{\pgf@sys@tonumber\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% + } + +(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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformnonlinear" + }, + pgftransformreset = { + details = [[ +Resets the coordinate transformation matrix to the identity matrix. +Thus, once this command is given no transformations are applied till the +end of the scope. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformrotate{30} + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformreset + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformreset" + }, + pgftransformresetnontranslations = { + details = [[ +This command sets the $a$, $b$, $c$, and $d$ part of the coordinate +transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, the +current shifting of the matrix is not modified. + +The effect of this command is that any rotation/scaling/slanting is +undone in the current TeX group, but the origin is not "moved back". + +This command is mostly useful directly before a `\pgftext` command to +ensure that the text is not scaled or rotated. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformscale{2} + \pgftransformrotate{30} + \pgftransformxshift{1cm} + {\color{red}\pgftext{rotated}} + \pgftransformresetnontranslations + \pgftext{shifted only} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformresetnontranslations" + }, + pgftransformrotate = { + arguments = {{meta = "angles"}}, + details = [[ +Rotates coordinates counterclockwise by ⟨angles⟩ given in degrees. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformrotate{30} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformrotate" + }, + pgftransformscale = { + arguments = {{meta = "factor"}}, + details = [[ +Scales coordinates by ⟨factor⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformscale" + }, + pgftransformshift = { + arguments = {{meta = "point"}}, + details = [[ +Shifts coordinates by ⟨point⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformshift{\pgfpoint{1cm}{1cm}} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformshift" + }, + pgftransformtriangle = { + arguments = {{meta = "a"}, {meta = "b"}, {meta = "c"}}, + details = [[ +This command transforms the coordinate system in such a way that the +triangle given by the points ⟨a⟩, ⟨b⟩ and ⟨c⟩ lies at the coordinates +$(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and +$(0\mathrm{pt},1\mathrm{pt})$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgftransformtriangle + {\pgfpoint{1cm}{0cm}} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{3cm}{1cm}} + + \draw (0,0) -- (1pt,0pt) -- (0pt,1pt) -- cycle; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformtriangle" + }, + pgftransformxscale = { + arguments = {{meta = "factor"}}, + details = [[ +Scales coordinates by ⟨factor⟩ in the $x$-direction. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxscale{.75} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxscale" + }, + pgftransformxshift = { + arguments = {{meta = "dimensions"}}, + details = [[ +Shifts coordinates by ⟨dimension⟩ along the $x$-axis. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxshift{.5cm} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxshift" + }, + pgftransformxslant = { + arguments = {{meta = "factor"}}, + details = [[ +Slants coordinates by ⟨factor⟩ in the $x$-direction. Here, a factor of +`1` means $45^\circ$. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformxslant{.5} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformxslant" + }, + pgftransformyscale = { + arguments = {{meta = "factor"}}, + details = [[ +Like `\pgftransformxscale`, only for the $y$-axis. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyscale" + }, + pgftransformyshift = { + arguments = {{meta = "dimensions"}}, + details = [[ +Like `\pgftransformxshift`, only for the $y$-axis. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyshift" + }, + pgftransformyslant = { + arguments = {{meta = "factor"}}, + details = [[ +Slants coordinates by ⟨factor⟩ in the $y$-direction. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (2,1) -- (1,0); + \pgftransformyslant{-1} + \draw[red] (0,0) -- (2,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgftransformyslant" + }, + pgfuseid = { + arguments = {{meta = "name"}}, + details = [[ +The ⟨name⟩ is a string by which the object will be referenced (see +`\pgfidrefnextuse`). The next time a graphic object is created in the +current TeX scope, the name will be attached to it (actually, it will +get a system layer identifier attached to it that is automatically +created using `\pgfsys@new@id`, the ⟨name⟩ is bound to that identifier +and it can be retrieved using `\pgfidrefnextuse`). This holds true only +for the next object: If a second object is created, it will not get the +name attached to it. This does not mean, however, that you cannot attach +the same name to different objects; you just need to call `\pgfuseid` +again before each object. + +Besides the ⟨name⟩ (or, more precisely, besides the system layer +identifier is refers to), the current *identifier type* is also +important: Actually, a graphic object is not referenced by a system +layer identifier, but by the combination of the identifier and a type. +You can use the following commands for modifying the type used for the +creation of objects: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseid" + }, + pgfuseimage = { + arguments = {{meta = "image name"}}, + details = [[ +Inserts a previously declared image into the *normal text*. If you wish +to use it in a `{pgfpicture}` environment, you must put a `\pgftext` +around it. + +If the macro `\pgfalternateextension` expands to some nonempty +⟨alternate extension⟩, PGF will first try to use the image named ⟨image +name⟩`.`⟨alternate extension⟩. If this image is not defined, PGF will +next check whether ⟨alternate extension⟩ contains a `!` character. If +so, everything up to this exclamation mark and including it is deleted +from ⟨alternate extension⟩ and the PGF again tries to use the image +⟨image name⟩`.`⟨alternate extension⟩. This is repeated until ⟨alternate +extension⟩ no longer contains a `!`. Then the original image is used. + +The `xxcolor` package sets the alternate extension to the current color +mixin. + + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo} + \pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +The following example demonstrates the effect of using `\pgfuseimage` +inside a colormixin environment. + + \pgfdeclareimage[interpolate=true,width=1cm,height=1cm] + {image1.!25!white}{brave-gnu-world-logo.25} + \pgfdeclareimage[interpolate=true,width=1cm] + {image2.25!white}{brave-gnu-world-logo.25} + \pgfdeclareimage[interpolate=true,height=1cm] + {image3.white}{brave-gnu-world-logo.25} + \begin{colormixin}{25!white} + \begin{pgfpicture} + \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} + \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} + \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} + + \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} + \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} + \pgfusepath{stroke} + \end{pgfpicture} + \end{colormixin} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseimage" + }, + pgfusepath = { + arguments = {{meta = "actions"}}, + details = [[ +Applies the given ⟨actions⟩ to the current path. Afterwards, the current +path is (globally) empty. The following actions are possible: + +- `fill` fills the path. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{fill} + \end{pgfpicture} + +- `stroke` strokes the path. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke} + \end{pgfpicture} + +- `draw` has the same effect as `stroke`. + +- `clip` clips all subsequent drawings against the path. Always + suppresses arrow tips. See Section ?? for further details. + + \begin{pgfpicture} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{1cm}{0cm}} + \pgfusepath{stroke,clip} + \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm} + \pgfusepath{fill} + \end{pgfpicture} + +- `discard` discards the path, that is, it is not used at all. Giving + this option (alone) has the same effect as giving an empty options + list. + +When more than one of the first three actions are given, they are +applied in the above ordering, regardless of their ordering in +⟨actions⟩. Thus, `{stroke,fill}` and `{fill,stroke}` have the same +effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepath" + }, + pgfusepathqclip = { + details = [[ +Clips all subsequent drawings against the current path. The path is not +processed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqclip" + }, + pgfusepathqfill = { + details = [[ +Fills the path without further ado. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqfill" + }, + pgfusepathqfillstroke = { + details = [[ +Fills and then strokes the path without further ado. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqfillstroke" + }, + pgfusepathqstroke = { + details = [[ +Strokes the path without further ado. No arrows are drawn, no corners +are arced. + + \begin{pgfpicture} + \pgfpathqcircle{5pt} + \pgfusepathqstroke + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusepathqstroke" + }, + pgfuseplotmark = { + arguments = {{meta = "plot mark name"}}, + details = [[ +Draws the given ⟨plot mark name⟩ at the origin. The ⟨plot mark name⟩ +must have been previously declared using `\pgfdeclareplotmark`. + + \begin{tikzpicture} + \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z}; + \pgfplothandlermark{\pgfuseplotmark{pentagon}} + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{0cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreamend + \pgfusepath{stroke} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseplotmark" + }, + pgfuseshading = { + arguments = {{meta = "shading name"}}, + details = [[ +Inserts a previously declared shading into the text. If you wish to use +it in a `pgfpicture` environment, you should put a `\pgftext` around it. + + \begin{pgfpicture} + \pgfdeclareverticalshading{myshadingD} + {20pt}{color(0pt)=(red); color(20pt)=(blue)} + \pgftext[at=\pgfpoint{1cm}{0cm}] {\pgfuseshading{myshadingD}} + \pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}} + \end{pgfpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfuseshading" + }, + pgfusetype = { + arguments = {{meta = "type"}}, + details = [[ +Sets the type used for the referencing of graphic objects for the +current scope to ⟨type⟩ or, if ⟨type⟩ starts with a dot, appends ⟨type⟩ +to the current type. + +You use this command with compound graphic objects: Before each part of +a graphic object, set the type to an appropriate value. Now, if the +object is named using `\pgfuseid`, you can later on access all parts of +the compound object using the combination of the ⟨name⟩ used with +`\pgfuseid` and the type of the part. + +As an example, this system is used to give you access to the different +parts of a node: When use say `\pgfuseid{mynode}` and then create a +node, you can use `mynode` with the empty type to reference the graphics +scope that encompasses the whole node, but also `mynode` together with +the type `background` to access the background path of the node. + +In detail, PGF uses this command to set the following types: + +- Inside the command `\pgfviewboxscope`, the type `.view` is used for + the view object. + +- Inside the command `\pgfmultipartnode`, the type + `.behind background` is used for the scope of drawings behind the + background. Similarly, `.before background` and `.behind foreground` + and finally `.before foreground` are used with the respective parts + of a node. + +- Also inside a node, `.background` and `.foreground` are used as + types of the background and foreground paths, respectively. + +- Finally, inside a node, for each text part, the text part's name is + used as a type (so `.text` is used for the main part). + +In addition, TikZ uses this command in the following situations: + +- The type `.path` is used with a named path (named using the `name` + key). This is the graphic object you need to reference when you wish + to morph a path. + +- The type `.path picture` is used with the scope of the optional path + picture. + +- The type `.path fill` is used with the path used for filling. This + is not the same as the normal path in case the path is filled and + patterned, for instance. + +- The type `.path shade` is used with the path used for shading a + path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfusetype" + }, + pgfverticaltransformationadjustment = { + details = [[ +$1/\\texttt{\textbackslash mathit\{transform\}(0,1)\textbackslash }_2$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfverticaltransformationadjustment" + }, + pgfwarning = { + arguments = {{meta = "message"}}, + details = [[ +Prints the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pgfwarning" + }, + usepgflibrary = { + arguments = {{meta = "list of libraries"}}, + details = [[ +Use this command to load further libraries. The list of libraries should +contain the names of libraries separated by commas. Instead of curly +braces, you can also use square brackets. If you try to load a library a +second time, nothing will happen. + +`\usepgflibrary{arrows}` + +This command causes the file `pgflibrary`⟨library⟩`.code.tex` to be +loaded for each ⟨library⟩ in the ⟨list of libraries⟩. This means that in +order to write your own library file, place a file of the appropriate +name somewhere where TeX can find it. LaTeX, plain TeX, and ConTeXt +users can then use your library. + +You should also consider adding a TikZ library that simply includes your +PGF library. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usepgflibrary" + }, + usepgfmodule = { + arguments = {{meta = "module names"}}, + details = [[ +Once the core has been loaded, you can use this command to load further +modules. The modules in the ⟨module names⟩ list should be separated by +commas. Instead of curly braces, you can also use square brackets, which +is something ConTeXt users will like. If you try to load a module a +second time, nothing will happen. + +`\usepgfmodule{matrix,shapes}` + +What this command does is to load the file +`pgfmodule`⟨module⟩`.code.tex` for each ⟨module⟩ in the list of ⟨module +names⟩. Thus, to write your own module, all you need to do is to place a +file of the appropriate name somewhere TeX can find it. LaTeX, plain +TeX, and ConTeXt users can then use your library. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usepgfmodule" + } +} +keys = { + pgf = { + ["/pgfparser/silent"] = { + details = [[ +If `true` then no error will be thrown when a letter is parsed for which +no action is specified, silently ignoring it. This holds true for every +parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/silent", + meta = "⟨boolean⟩" + }, + ["/pgfparser/status"] = { + details = [[ +If `true` every parser prints a status message for every action +executed. This might help in debugging and understanding what the parser +does. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/status", + meta = "⟨boolean⟩" + }, + ["/pgfparser/⟨parser name⟩/silent"] = { + details = [[ +If `true` the parser ⟨parser name⟩ will silently ignore undefined +letters. This is an individual equivalent of `/pgfparser/silent` for +each defined parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgfparser/⟨parser:name⟩/silent", + meta = "⟨boolean⟩" + }, + ["and gate IEC symbol"] = { + details = [[ +Set the symbol for the `and gate`. Note that if the node is filled, this +color will be used for the symbol, making it invisible, so it will be +necessary set ⟨text⟩ to something like `\color{black}\char‘\& `. +Alternatively, the `logic gate IEC symbol color` key can be used to set +the color of all symbols simultaneously. + +In TikZ, when the `use IEC style logic gates` key has been used, this +key can be replaced by `and gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/and:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["animate/events/click"] = { + details = [[ +This is a shorthand for `event=click`. This event gets triggered when +the user clicks on the triggering object with a mouse (or something +equivalent). + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animate/events/click" + }, + ["animation/along"] = { + details = [[ +This key must be used with `motion` attribute to specify a path along +which the transformation matrix will be "moved" (that is, a shift +transformation will be added to the different points on the path). + +The values passed to the `entry` key specify fractions of the distance +along the ⟨path⟩. That means, when you provide a value of `0`, you +reference the start point of the path, a value of `1` references the end +of the path and `0.5` referenced the point halfway along the path. + + \tikz [very thick] { + \pgfanimateattribute{motion}{ + whom = node, begin on = {click}, + along = \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{0mm}{5mm}}, + entry = {0s}{0}, entry = {1s}{0.5}, entry = {2s}{0.25}, entry={3s}{1} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/along", + meta = "⟨path⟩" + }, + ["animation/arrows"] = { + details = [[ +This key specifies arrow tips during the animation of the path. The +syntax for the arrow tips is the same syntax as the `\pgfsetarrow` +command or TikZ's `arrows` key. The specified start and end arrow tips +are rendered as "markers", which are added to the path *only* during the +animation. The markers are rotated along with the path in exactly the +same way as normal arrow tips would be. To be precise, the rules used +for the computation of where arrow tips go and in which direction they +head is not always the same for "static" arrow tips (arrow tips added to +a normal path) and the "dynamic" arrow tips based on markers; namely +when the paths are very short or closed. For this reason, you should add +arrow tips to animated paths only when the paths are "nice and simple" +in the sense that they consist of a single segment whose ends are +reasonably long. + +In addition to adding the arrow tips to the path during the animation, +the path gets shortened as necessary to compensate for the extend of the +arrow tips. However, for this to work, the arrow tips have to be +specified before path values are specified (since the shortening is done +immediately when a path value is parsed). + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw [very thick, blue, name=p] (1,0.5) -- (2,0.5); + } + +Note that the markers that visualize the arrow tips are rendered only +once per animation. In consequence, "bending" arrow tips cannot be +rendered correctly: As a path "morphs" a bend arrow tip needs not only +to rotate along, but must actually "bend along", which is not supported +(neither by PGF nor by SVG). + +As pointed out earlier, an animated path cannot have "static" arrow +tips. However, when you specify a `base` value, which is the path used +whenever there is no active animation, *will* use the arrow tips. As a +result, you can use this to animate a path with an arrow tip: + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw [very thick, blue, name=p]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/arrows", + meta = "⟨start tip spec⟩-⟨end tip spec⟩" + }, + ["animation/begin"] = { + details = [[ +This key specifies when the "moment `0s`" should be relative to the +moment when the current graphic is first displayed. You can use this key +multiple times, in this case the timeline is restarted for each of the +times specified (if it is already running, it will be reset). If no +`begin` key is given at all, the effect is the same as if `begin=0s` had +been specified. + +It is permissible to set ⟨time⟩ to a negative value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/begin", + meta = "⟨time⟩" + }, + ["animation/begin on"] = { + details = [[ +Has the same effect as `/tikz/animate/option/begin on`, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/begin:on", + meta = "⟨options⟩" + }, + ["animation/end"] = { + details = [[ +This key will truncate the timeline so that it ends ⟨time⟩ after the +display of the graphic, provided the timeline begins before the +specified end time. For instance, if you specify a timeline starting at +2 s and ending at 5 s and you set `begin` to 1 s and `end` to 4 s, the +timeline will run, relative to the moment when the graphic is displayed +from 3 s to 4 s. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin = 2s, end = 4s, + entry = {1s}{0}, entry = {2s}{90}, entry = {3s}{180}, entry = {4s}{270} } + \node (node) [fill = blue!20, draw = blue, circle] {Turn after 3s!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/end", + meta = "⟨time⟩" + }, + ["animation/end on"] = { + details = [[ +Works exactly like `begin on`, one possible end of the timeline is +specified using the ⟨options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/end:on", + meta = "⟨options⟩" + }, + ["animation/entry"] = { + details = [[ +You use this key repeatedly to specify the different values that the +⟨attribute⟩ should have over time. At the ⟨time⟩ specified, the +⟨attribute⟩ will have the value specified as ⟨value⟩: + + \tikz { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, + entry = {0s}{0}, entry = {1s}{90}, entry = {1.1s}{45}, entry = {2s}{90} + } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + +You need to call `entry` once for each time in the timeline for which +you want to specify a ⟨value⟩ explicitly. Between these times, the +values get interpolated (see below for details). You need to specify the +⟨time⟩s in non-decreasing order (it is permissible and sometimes also +necessary to specify the same time twice, namely to create a "jump" of +the value of some attribute). + +The ⟨time⟩ is parsed using the command `\pgfparsetime` described later. + +**Start and end of the timeline.** The first and last times of the +timeline are a bit special: The timeline starts on the first time and +the duration of the timeline is the difference between the first and +last time. "Starting" on the start time actually means that any +beginnings (see the `begin` and `end` keys) get offset by the start +time; similarly end times are offset by this value. + +**Syntax of the values.** The syntax of the ⟨value⟩ varies according to +the type of the ⟨attribute⟩. In detail, these are: + + ----------- ---------------------------------------------------------------- + *Type* *Syntax* + color Standard color syntax like `red` or `black!10` + scalar A value parsed using `\pgfmathparse` + dimension A dimension parsed using `\pgfmathparse` + path A sequence of path construction commands + softpath A sequence of soft path construction commands + scaling A scalar value or a pair of scalar values separated by a comma + point A PGF-point like `\pgfpoint{1cm}{5mm}` + viewbox Two PGF-points + boolean `true` or `false` + ----------- ---------------------------------------------------------------- + +**Interpolation between key times.** You use the `entry` key repeatedly, +namely once for each "key time", which is a time point for which you +specify the value of the attribute explicitly. Between these key times, +the attribute's value is interpolated. Normally, this is just a linear +interpolation, but you can influence this using the following keys, see +Section ?? for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/entry", + meta = "{time}{value}" + }, + ["animation/events/begin"] = { + details = [[ +Shorthand for `event=begin`. The "begin" refers to the beginning of +another animation, namely the one referenced by `of` or `of whom`. This +means that the current animation will begin when some other animation +begins. + + \tikz \node [animate = { + myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}}, + myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim} + }, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/begin" + }, + ["animation/events/delay"] = { + details = [[ +Specifies that the timeline should not start with the event, but, +rather, be delayed by ⟨time⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/delay", + meta = "⟨time⟩" + }, + ["animation/events/end"] = { + details = [[ +Shorthand for `event=end`. Again, the "end" refers to the end of another +animation, namely the one referenced by `of` or `of whom`. This means +that the current animation will *begin* when some other animation +*ends*. + + \tikz \node [animate = { + myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}}, + myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim } + }, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/end" + }, + ["animation/events/event"] = { + details = [[ +Specifies the name of the event whose occurrence should start the +timeline. Which events are supported depends on the device on which the +animation is displayed, the output format (SVG or some other format), +and the setup of scripts, but here is a list of events supported by +"plain SVG": `click`, `focusin`, `focusout`, `mousedown`, `mouseup`, +`mouseover`, `mousemove`, `mouseout`, `begin`, `end`. However, the +following keys make using these events simpler: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/event", + meta = "⟨event name⟩" + }, + ["animation/events/focus in"] = { + details = [[ +This is a shorthand for `event=focusin`. This event gets triggered when +the graphic object gets the focus (this usually makes sense only for +text input fields). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/focus:in" + }, + ["animation/events/focus out"] = { + details = [[ +This is a shorthand for `event=focusout`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/focus:out" + }, + ["animation/events/key"] = { + details = [[ +The event is triggered when the keyboard key ⟨key⟩ has been pressed. For +security reasons, a viewer may suppress this. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/key", + meta = "⟨key⟩" + }, + ["animation/events/mouse down"] = { + details = [[ +Shorthand for `event=mousedown`. The event gets triggered when the user +presses a mouse button down on the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:down" + }, + ["animation/events/mouse move"] = { + details = [[ +Shorthand for `event=mousemove`. The event gets triggered lots of times, +namely each time the mouse moves while being "over" the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:move" + }, + ["animation/events/mouse out"] = { + details = [[ +Shorthand for `event=mouseout`. The opposite of `mouse over`: triggered +when the mouse leaves the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:out" + }, + ["animation/events/mouse over"] = { + details = [[ +Shorthand for `event=mouseover`. The event gets triggered the moment the +mouse cursor moves over the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:over" + }, + ["animation/events/mouse up"] = { + details = [[ +Shorthand for `event=mouseup` and gets triggered, of course, when a +pressed button is released on the object. + + \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} } + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/mouse:up" + }, + ["animation/events/of"] = { + details = [[ +This specifies a graphic object id in the same way as the `whom` key, +also with an optional ⟨type⟩. This is the object that "causes" the event +to happen. + +Unlike the `whom` key, which always refers to a not-yet-existing object, +this key always refers to an already existing object, namely to the most +recent use of the ⟨id⟩. In the following example, the referenced object +is the node with the label `2` since it is the most recently referenced +node with ⟨id⟩ `X`. + + \tikz [very thick] { + \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1}; + \node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2}; + \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}} + [fill = red!20, draw = red, rectangle] {Anim}; + \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3}; + \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/of", + meta = "⟨id⟩.⟨type⟩" + }, + ["animation/events/of next"] = { + details = [[ +This key works like the `of` key, only it refers to a future (actually, +the next) object with the given ⟨id⟩, not to a previous one. This, in +the next example, the referenced node is the one with label `3`. + + \tikz [very thick] { + \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1}; + \node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2}; + \node (node) :rotate = { + 0s="0", 2s="90", begin on = {click, of next = X}} + [fill = red!20, draw = red, rectangle] {Anim}; + \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3}; + \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/of:next", + meta = "⟨id⟩.⟨type⟩" + }, + ["animation/events/repeat"] = { + details = [[ +The event is triggered when a repeating animation has been repeated +⟨number⟩ times. + + \tikz + \node [animate = { myself: = { + :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim }, + begin snapshot = 2 }, + :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}}, + fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/events/repeat", + meta = "⟨number⟩" + }, + ["animation/freeze at end"] = { + details = [[ +When set to `true`, whenever a timeline ends (either because the last +time of timeline has been reached or because an `end` or `end of` key +have ended it prematurely), the last value the attribute had because of +the animation "stays put". When set to `false`, which is the initial +value, once an animation ends, its effect will be removed "as if it +never happened". + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, freeze at end = false, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; } + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, freeze at end, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/freeze:at:end", + meta = "⟨true or false⟩" + }, + ["animation/name"] = { + details = [[ +Assigns a name to the animation by which it can be referenced using the +`of` and `of next` keys in another animation. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {end, of next = my move animation, delay = 1s}, + entry = {0s}{0}, entry = {2s}{90}, begin snapshot = 3s, } + \pgfanimateattribute{translate}{ + name = my move animation, whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{0cm}{-5mm}} } + \node (node) [fill = blue!20, draw = blue, circle] {Here!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/name", + meta = "⟨name⟩" + }, + ["animation/origin"] = { + details = [[ +An animation of the canvas transformation is added to all other +transformations from surrounding or interior scopes. This means that, in +particular, the origin of a canvas transformation is, by default, the +origin of the canvas of the scope surrounding the transformation object. + +For some canvas animations, like a rotation or a scaling, you will +typically wish to use a different origin (like the center of an object +that is to be rotated or scaled). You can achieve this effect by +surrounding the object by a scope that shifts the canvas to the desired +origin, followed by a scope whose transformation matrix you animate, +followed by a scope that shifts back the canvas. + +The `origin` key simplifies this process by allowing you to specify the +origin of the transformation directly. Internally, however, all this key +does is to create the above-mentioned scopes with the necessary shifts. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, + origin = \pgfpoint{-5mm}{0mm}, entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/origin", + meta = "⟨pgf point⟩" + }, + ["animation/repeat"] = { + details = [[ +This is an alias for `repeats`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/repeat", + meta = "⟨specification⟩" + }, + ["animation/repeats"] = { + details = [[ +Use this key to specify that the timeline animation should repeat at the +end. The ⟨specification⟩ must consist of two parts, each of which may be +empty. The first part is one of the following: + +- Empty, in which case the timeline repeats forever. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +- A ⟨number⟩ (like `2` or `3.25`), in which case the timeline repeats + ⟨number⟩ times. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = 1.75, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +- The text "`for` ⟨time⟩" (like `for 2s` or `for 300ms`), in which + case the timeline repeats however often necessary so that it stops + exactly after ⟨time⟩. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = for 3.5s, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + +The second part of the specification must be one of the following: + +- Empty, in which case each time the timeline is restarted, the + attribute's value undergoes the same series of values it did + previously. + +- The text `accumulating`. This has the effect that each time the + timeline is restarted, the attribute values specified by the + timeline are *added* to the value from the previous iteration(s). A + typical example is an animation that shifts a scope by, say, 1 cm + over a time of 1 s. Now, if you repeat this five times, normally the + scope will shift 1 cm for 1 s then "jump back", shift again, jump + back, and so on for five times. In contrast, when the repeats are + accumulating, the scope will move by 5 cm over 5 s in total. + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = accumulating, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } + + \tikz [very thick] { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, repeats = 2 accumulating, + entry = {0s}{0}, entry = {2s}{90} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/repeats", + meta = "⟨specification⟩" + }, + ["animation/restart"] = { + details = [[ +Has the same effect as `/tikz/animate/option/restart`, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/restart", + meta = "⟨choice⟩" + }, + ["animation/rotate along"] = { + details = [[ +When set to `true`, the `along` key additionally adds a rotation that +varies in such a way that a tangent to the path always points right. + + \tikz [very thick] { + \pgfanimateattribute{motion}{ + whom = node, begin on = {click}, + rotate along = true, + along = \pgfpathmoveto {\pgfpointorigin} + \pgfpathcurveto{\pgfpoint{5mm}{0cm}}{\pgfpoint{5mm}{0cm}} + {\pgfpoint{5mm}{5mm}}, + entry = {0s}{0}, entry = {2s}{1} } + \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/rotate:along", + meta = "⟨Boolean⟩" + }, + ["animation/shorten <"] = { + details = [[ +Works like `shorten >`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/shorten:<", + meta = "⟨dimension⟩" + }, + ["animation/shorten >"] = { + details = [[ +Just like the normal TikZ key `shorten >`, this key specifies an extra +shortening of to-be-animated paths. Whenever a path is parsed as a value +for a path animation, it gets shortened at the end by the ⟨dimension⟩ +(and, additionally, by the length of the attached arrow tip). Just like +the `arrows` key, this key must be given before the path entries are +specified. + + \tikz { + \pgfanimateattribute{path}{ + whom = p.path, begin on = {click, of next=node}, arrows = ->, + shorten > = 2mm, + base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}, + entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}} + \pgfpathlineto{\pgfpoint{2cm}{1cm}}}, + entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}} + \pgfpathlineto{\pgfpoint{2cm}{5mm}}}} + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw (0.9,-0.1) grid (2.1,1.1); + \draw [help lines] (0.9,-0.1) grid[step=1mm] (2.1,1.1); + \draw [very thick, blue, name=p]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/shorten:>", + meta = "⟨dimension⟩" + }, + ["animation/whom"] = { + details = [[ +You *must* use this key once which each call of the +`\pgfanimateattribute` command. The ⟨id⟩ and the optional ⟨type⟩ (which +is whatever follows the first dot) will be passed to `\pgfidrefnextuse`, +see that command for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animation/whom", + meta = "⟨id⟩.⟨type⟩" + }, + ["animations/entry control"] = { + details = [[ +Works like `exit control`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/entry:control", + meta = "{time fraction}{value fraction}" + }, + ["animations/exit control"] = { + details = [[ +Same as `/tikz/animate/options/exit control`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + exit control={1}{0}, + entry = {0s}{\pgfpointorigin}, + linear, % revert to default + entry = {1s}{\pgfpoint{0cm}{-5mm}}, + entry control={0}{1}, + entry = {2s}{\pgfpoint{0cm}{-10mm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/exit:control", + meta = "{time fraction}{value fraction}" + }, + ["animations/jump"] = { + details = [[ +Same as `/tikz/animate/options/jump`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, + jump, + entry = {1s}{\pgfpoint{0cm}{-1cm}}, + linear, + entry = {2s}{\pgfpoint{0cm}{-2cm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/jump" + }, + ["animations/linear"] = { + details = [[ +A shorthand for `exit control={0}{0}, entry control={1}{1}`. This will +(re)install a linear curve. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/linear" + }, + ["animations/stay"] = { + details = [[ +Same as `/tikz/animate/options/stay`. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \pgfanimateattribute{translate}{ + whom = node, begin on = {click}, + entry = {0s}{\pgfpointorigin}, + stay, + entry = {1s}{\pgfpoint{0cm}{-5mm}}, + linear, + entry = {2s}{\pgfpoint{0cm}{-10mm}}, + entry = {3s}{\pgfpoint{0cm}{-15mm}} } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/animations/stay" + }, + ["arrow box arrows"] = { + details = [[ +Sets the distance that all arrows extend from the node. The +specification in ⟨list⟩ consists of the four compass points `north`, +`south`, `east` or `west`, separated by commas (so the list must be +contained within braces). The distances can be specified after each side +separated by a colon (e.g., `north:1cm`, or `west:5cm from center`). If +an item specifies no distance, the most recently specified distance will +be used (at the start of the list this is `0cm`, so the first item in +the list should specify a distance). Any sides not specified will not be +drawn with an arrow. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:arrows", + meta = "{⟨list⟩}" + }, + ["arrow box east arrow"] = { + details = [[ +Sets the distance the east arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:east:arrow", + meta = "⟨distance⟩" + }, + ["arrow box head extend"] = { + details = [[ +Sets the distance the arrow head extends away from the shaft of the +arrow. This applies to all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:head:extend", + meta = "⟨length⟩" + }, + ["arrow box head indent"] = { + details = [[ +Moves the point where the arrow head joins the shaft of the arrow +*towards* the arrow tip. This applies to all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:head:indent", + meta = "⟨length⟩" + }, + ["arrow box north arrow"] = { + details = [[ +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 ⟨distance⟩ is `0pt` or a negative distance, the arrow will not +be drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:north:arrow", + meta = "⟨distance⟩" + }, + ["arrow box shaft width"] = { + details = [[ +Sets the width of the shaft of all arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:shaft:width", + meta = "⟨length⟩" + }, + ["arrow box south arrow"] = { + details = [[ +Sets the distance the south arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:south:arrow", + meta = "⟨distance⟩" + }, + ["arrow box tip angle"] = { + details = [[ +Sets the angle at the arrow tip for all four arrows. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:tip:angle", + meta = "⟨angle⟩" + }, + ["arrow box west arrow"] = { + details = [[ +Sets the distance the west arrow extends from the node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:box:west:arrow", + meta = "⟨distance⟩" + }, + ["arrow keys/angle"] = { + details = [[ +This key sets the `length` and the `width` of an arrow tip at the same +time. The length will be the cosine of ⟨angle⟩, while the width will be +twice the sine of half the ⟨angle⟩ (this slightly awkward rule ensures +that a `Stealth` arrow will have an opening angle of ⟨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 +⟨dimension⟩ before the sine and cosines are computed. + + \tikz \draw [arrows = {-Stealth[inset=0pt, angle=90:10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[inset=0pt, angle=30:10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/angle", + meta = "⟨angle⟩:⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/angle'"] = { + details = [[ +Sets the width of the arrow to twice the tangent of $⟨angle⟩/2$ times +the arrow length. This results in an arrow tip with an opening angle of +⟨angle⟩ at its tip and with the specified `length` unchanged. + + \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=90]}] + (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=30]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/angle'", + meta = "⟨angle⟩" + }, + ["arrow keys/arc"] = { + details = [[ +Sets the angle of arcs in arrows to ⟨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: + + \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); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/arc", + meta = "⟨degrees⟩" + }, + ["arrow keys/bend"] = { + details = [[ +*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 *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{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} + + \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} + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/bend" + }, + ["arrow keys/cap angle"] = { + details = [[ +Sets `length` to an appropriate multiple of the line width so that the +angle of a `Triangle Cap` is exactly ⟨angle⟩ at the tip. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/cap:angle", + meta = "⟨angle⟩" + }, + ["arrow keys/color"] = { + details = [[ +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=`⟨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 behavior, you usually +do not need to specify anything: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [blue, arrows = {-Stealth}] (0,0) -- (1,0); + +Now, when you provide a ⟨color⟩ with this option, you request that the +arrow tip should get this color *instead* of the color of the main path: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=blue]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[color=black]}] (0,0) -- (1,0); + +Similar to the `color` option used in normal TikZ options, you may omit +the `color=` part of the option. Whenever an ⟨arrow key⟩ is encountered +that TikZ does not recognize, it will test whether the key is the name +of a color and, if so, execute `color=`⟨arrow key⟩. So, the first of the +above examples can be rewritten as follows: + + \tikz [ultra thick] \draw [red, arrows = {-Stealth[blue]}] (0,0) -- (1,0); + +The ⟨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: + + \tikz [ultra thick] \draw [draw=red, fill=red!50, arrows = {-Stealth[length=10pt]}] + (0,0) -- (1,1) -- (2,0); + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/color", + meta = "⟨color or empty⟩" + }, + ["arrow keys/fill"] = { + details = [[ +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: + + \tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=white,length=15pt]}] (0,0) -- (1,0); + } + +You can also specify the special "color" `none`. In this case, the arrow +tip is not filled at all (not even with white): + + \tikz { + \draw [help lines] (0,-.5) grid [step=1mm] (1,.5); + \draw [thick, red, arrows = {-Stealth[fill=none,length=15pt]}] (0,0) -- (1,0); + } + +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. + +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. + + \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); + } + +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.): + + \tikz [ultra thick] \draw [draw=red, fill=red!50, + arrows = {-Stealth[length=15pt, fill=pgffillcolor]}] + (0,0) -- (1,1) -- (2,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/fill", + meta = "⟨color or none⟩" + }, + ["arrow keys/flex"] = { + details = [[ +When the `bending` library is loaded, this key is applied to all arrow +tips by default. It has the following effect: + +1. 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 *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 *exactly* 6.25mm; only something reasonably + close. + +2. The supports of the line are updated accordingly so that the + shortened line will still follow *exactly* the original line. This + means that the curve deformation effect caused by the `quick` + command does not happen here. + +3. 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 *the visual + end lies on the line*: + + \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} + +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 ⟨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{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} + + \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} + +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{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} + +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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/flex", + meta = "⟨factor⟩" + }, + ["arrow keys/flex'"] = { + details = [[ +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{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} + +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{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} + +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{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} + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/flex'", + meta = "⟨factor⟩" + }, + ["arrow keys/harpoon"] = { + details = [[ +The key requests that only the "left half" of the arrow tip should +drawn: + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {->[harpoon]}] (0,0) -- (1,0); + +Unlike the `reversed` 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/harpoon" + }, + ["arrow keys/inset"] = { + details = [[ +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 ⟨dimension⟩ we add ⟨line width factor⟩ times that +line width, where the line width is computed based on the ⟨outer factor⟩ +as described for the `length` key. + + \tikz \draw [arrows = {-Stealth[length=10pt, inset=5pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Stealth[length=10pt, inset=2pt]}] (0,0) -- (1,0); + +For most arrows for which there is no "natural inset" like, say, +`Latex`, this key has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/inset", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/inset'"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/inset'", + meta = "⟨dimension⟩ ⟨length factor⟩ ⟨line width factor⟩" + }, + ["arrow keys/left"] = { + details = [[ +A shorthand for `harpoon`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/left" + }, + ["arrow keys/length"] = { + details = [[ +\[length-arrow-key\] This parameter is usually the most important +parameter that governs the size of an arrow tip: The ⟨dimension⟩ that +you provide dictates the distance from the "very tip" of the arrow to +its "back end" along the line: + + \tikz{ + \draw [-{Stealth[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); + } + + \tikz{ + \draw [-{Latex[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4); + } + + \tikz{ + \draw [-{Classical TikZ Rightarrow[length=5mm]}] (0,0) -- (2,0); + \draw [|<->|] (1.5,.6) -- node[above=1mm] {5mm} (2,.6); + } + +**The Line Width Factors.** Following the ⟨dimension⟩, you may put a +space followed by a ⟨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 ⟨dimension⟩, but rather +$⟨dimension⟩ + ⟨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 `3pt 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 ⟨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 $⟨dimension⟩ + ⟨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 ⟨outer factor⟩ to +decide on one of them or even mix them: TikZ sets +$w = ⟨outer factor⟩ w_o + + (1-⟨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. + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 0]}] (0,0) -- (1,0); + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 .5]}] (0,0) -- (1,0); + + \tikz \draw [line width=1pt, double distance=3pt, + arrows = {-Latex[length=0pt 3 1]} ] (0,0) -- (1,0); + +**The Exact Length.** For an arrow tip kind that is just an outline that +is filled with a color, the specified length should *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: + +1. 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: + + \tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); + } + +2. If, in the above case, the arrow is drawn using a round line join + (see Section ?? 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 want to change the mode. + + \tikz{ + \draw [line width=1mm, -{Stealth[length=10mm, open, round]}] + (0,0) -- (2,0); + \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0); + } + + 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/length", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/line cap"] = { + details = [[ +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: + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=butt]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line cap=round]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=butt]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line cap=round]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:cap", + meta = "⟨round or butt⟩" + }, + ["arrow keys/line join"] = { + details = [[ +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: + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=miter]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[line join=round]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=miter]}] + (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,line join=round]}] + (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:join", + meta = "⟨round or miter⟩" + }, + ["arrow keys/line width"] = { + details = [[ +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`. + + \tikz \draw [arrows = {-Latex[line width=0.1pt, fill=white, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[line width=1pt, fill=white, length=10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:width", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/line width'"] = { + details = [[ +Works like `line width` only the factor is with respect to the `length`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/line:width'", + meta = "⟨dimension⟩ ⟨length factor⟩" + }, + ["arrow keys/n"] = { + details = [[ +Sets the number of rays in a `Rays` arrow tip. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/n", + meta = "⟨number⟩" + }, + ["arrow keys/open"] = { + details = [[ +A shorthand for `fill=none`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/open" + }, + ["arrow keys/quick"] = { + details = [[ +Recall that curves in TikZ are actually Bézier 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 *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 *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{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} + +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{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} + +Note that the third arrow tip does not really lie on the curve any more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/quick" + }, + ["arrow keys/reversed"] = { + details = [[ +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). + + \tikz [ultra thick] \draw [arrows = {-Stealth[reversed]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[reversed, reversed]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/reversed" + }, + ["arrow keys/right"] = { + details = [[ +A shorthand for `harpoon, swap`. + + \tikz [ultra thick] \draw [arrows = {-Stealth[left]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[right]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/right" + }, + ["arrow keys/round"] = { + details = [[ +A shorthand for `line cap=round, line join=round`, resulting in +"rounded" arrow heads. + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[round]}] (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,round]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/round" + }, + ["arrow keys/sep"] = { + details = [[ +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 ⟨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: + + \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); + } + +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. + + \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); + } + +Indeed, adding a `sep` to an arrow tip is *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, *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: + + \tikz \draw [->_>] (0,0) -- (1,0); + + \tikz \draw [->__>] (0,0) -- (1,0); + +However, using the `sep` option will be faster than using the `_ ` arrow +tip and it also allows you to specify the desired length directly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/sep", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/sharp"] = { + details = [[ +A shorthand for `line cap=butt, line join=miter`, resulting in "sharp" +or "pointed" arrow heads. + + \tikz [line width=2mm] + \draw [arrows = {-Computer Modern Rightarrow[sharp]}] (0,0) -- (1,0); + + \tikz [line width=2mm] + \draw [arrows = {-Bracket[reversed,sharp]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/sharp" + }, + ["arrow keys/slant"] = { + details = [[ +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: + + \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); + } + +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: + + \tikz [>={[slant=.3] To[] To[]}] + \graph [math nodes] { A -> B <-> C }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/slant", + meta = "⟨factor⟩" + }, + ["arrow keys/swap"] = { + details = [[ +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. + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0); + + \tikz [ultra thick] \draw [arrows = {-Stealth[harpoon,swap]}] (0,0) -- (1,0); + +Swapping is always possible, no special code is needed on behalf of an +arrow tip implementer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/swap" + }, + ["arrow keys/width"] = { + details = [[ +This key works like 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 ??.) The meaning of the two optional factor +numbers following the ⟨dimension⟩ is the same as for the `length` key. + + \tikz \draw [arrows = {-Latex[width=10pt, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[width=0pt 10, length=10pt]}] (0,0) -- (1,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/width", + meta = "⟨dimension⟩ ⟨line width factor⟩ ⟨outer factor⟩" + }, + ["arrow keys/width'"] = { + details = [[ +The key (note the prime) has a similar effect as the `width` key. The +difference is that the second, still optional parameter ⟨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 + + length = 10pt, width'=5pt 2, length=7pt + +the resulting width will be $19\mathrm{pt} = 5\mathrm{pt} + 2\cdot + 7\mathrm{pt}$. + + \tikz \draw [arrows = {-Latex[width'=0pt .5, length=10pt]}] (0,0) -- (1,0); + + \tikz \draw [arrows = {-Latex[width'=0pt .5, length=15pt]}] (0,0) -- (1,0); + +The third, also optional, parameter allows you to add a multiple of the +line width to the value computed in terms of the length. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrow:keys/width'", + meta = "⟨dimension⟩ ⟨length factor⟩ ⟨line width factor⟩" + }, + ["arrows keys/scale"] = { + details = [[ +After all the other options listed in the previous (and also the +following sections) have been processed, TikZ applies a *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 ⟨factor⟩. + + \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); + } + +Note that scaling has *no* effect on the line width (as usual) and also +not on the arrow padding (the `sep`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale", + meta = "⟨factor⟩" + }, + ["arrows keys/scale length"] = { + details = [[ +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. + + \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); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale:length", + meta = "⟨factor⟩" + }, + ["arrows keys/scale width"] = { + details = [[ +Like `scale length`, but for dimensions related to the width. + + \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); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/arrows:keys/scale:width", + meta = "⟨factor⟩" + }, + aspect = { + details = [[ +The aspect is a recommendation for the quotient of the radii of the +cylinder end. This may be ignored if the shape is enlarged to some +minimum width. + + \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}; + \node [aspect=0.25] at (2,0) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/aspect", + meta = "⟨value⟩" + }, + ["bar interval shift"] = { + details = [[ +\[key-bar-interval-shift\] + +Sets the *relative* shift of `\pgfplothandlerxbarinterval` and +`\pgfplothandlerybarinterval` to ⟨factor⟩. As `/pgf/bar interval width`, +the argument is relative to the interval length of the input +coordinates. + +The argument `{scale}` will be evaluated using the math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:interval:shift", + meta = "{factor}" + }, + ["bar interval width"] = { + details = [[ +\[key-bar-interval-width\] + +Sets the *relative* width of `\pgfplothandlerxbarinterval` and +`\pgfplothandlerybarinterval` to `{scale}`. The argument is relative to +$(x_{i+1} - x_i)$ for $y$ bar plots and relative to $(y_{i+1}-y_i)$ for +$x$ bar plots. + +The argument `{scale}` will be evaluated using the math parser. + + \begin{tikzpicture}[bar interval width=0.5] + \draw[gray] + (0,3) -- (0,-0.1) + (1,3) -- (1,-0.1) + (2,3) -- (2,-0.1) + (4,3) -- (4,-0.1); + \pgfplothandlerybarinterval + \begin{scope}[bar interval shift=0.25,fill=blue] + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{2cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{1cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}} + \pgfplotstreamend + \pgfusepath{fill} + \end{scope} + \begin{scope}[bar interval shift=0.75,fill=red] + \pgfplotstreamstart + \pgfplotstreampoint{\pgfpoint{0cm}{3cm}} + \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}} + \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}} + \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}} + \pgfplotstreamend + \pgfusepath{fill} + \end{scope} + \end{tikzpicture} + +Please note that bars are always centered, so we have to use shifts +$0.25$ and $0.75$ instead of $0$ and $0.5$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:interval:width", + meta = "{scale}" + }, + ["bar shift"] = { + details = [[ +Sets a shift used by `\pgfplothandlerxbar` and `\pgfplothandlerybar` to +`{dimension}`. It has the same effect as `xshift`, but it applies only +to those bar plots. The argument `{dimension}` will be evaluated using +the math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:shift", + meta = "{dimension}" + }, + ["bar width"] = { + details = [[ +Sets the width of `\pgfplothandlerxbar` and `\pgfplothandlerybar` to +`{dimension}`. The argument `{dimension}` will be evaluated using the +math parser. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/bar:width", + meta = "{dimension}" + }, + ["buffer gate IEC symbol"] = { + details = [[ +Set the symbol for the `buffer gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `buffer gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/buffer:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["callout absolute pointer"] = { + details = [[ +Sets the vector of the callout pointer absolutely within the picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:absolute:pointer", + meta = "⟨coordinate⟩" + }, + ["callout pointer arc"] = { + details = [[ +Sets the width of the pointer at the border of the ellipse according to +an arc of length ⟨angle⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:arc", + meta = "⟨angle⟩" + }, + ["callout pointer end size"] = { + details = [[ +Sets the size of the last ellipse in the pointer. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:end:size", + meta = "⟨value⟩" + }, + ["callout pointer segments"] = { + details = [[ +Sets the number of segments in the pointer. Note that PGF will happily +overlap segments if too many are specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:segments", + meta = "⟨number⟩" + }, + ["callout pointer shorten"] = { + details = [[ +Moves the callout pointer towards the center of the callout's main shape +by ⟨distance⟩. + + \begin{tikzpicture} + \tikzset{callout/.style={ellipse callout, callout pointer arc=30, + callout absolute pointer={#1}}} + \draw (0,0) grid (3,2); + \node[callout={(3,1.5)}, fill=red!50] at (0,1.5) {A}; + \node[callout={(3,.5)}, fill=green!50, callout pointer shorten=1cm] + at (0,.5) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:shorten", + meta = "⟨distance⟩" + }, + ["callout pointer start size"] = { + details = [[ +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 +⟨value⟩: + +- A single dimension (e.g., `5pt`), in which case the first ellipse + will have equal diameters of 5pt. + +- Two dimensions (e.g., `10pt and 2.5pt`), which sets the $x$ and $y$ + diameters of the first ellipse. + +- A decimal fraction (e.g., `.2 of callout`), in which case the $x$ + and $y$ diameters of the first ellipse will be set as fractions of + the width and height of the main shape. The keyword `of callout` + cannot be omitted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:start:size", + meta = "⟨value⟩" + }, + ["callout pointer width"] = { + details = [[ +Sets the width of the pointer at the border of the rectangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:pointer:width", + meta = "⟨length⟩" + }, + ["callout relative pointer"] = { + details = [[ +Sets the vector of the callout pointer 'relative' to the callout shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/callout:relative:pointer", + meta = "⟨coordinate⟩" + }, + ["chamfered rectangle angle"] = { + details = [[ +Sets the angle *from the vertical* for the chamfer. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle angle=30] {abc}; + \node[chamfered rectangle angle=60] at (1.5,0) {123}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:angle", + meta = "⟨angle⟩" + }, + ["chamfered rectangle corners"] = { + details = [[ +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 by +braces). Any corners not mentioned in ⟨list⟩ are automatically not +chamfered. Two additional values `chamfer all` and `chamfer none`, are +also permitted. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle corners=north west] {ghi}; + \node[chamfered rectangle corners={north east, south east}] at (1.5,0) {789}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:corners", + meta = "⟨list⟩" + }, + ["chamfered rectangle sep"] = { + details = [[ +Sets both the `xsep` and `ysep` simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:sep", + meta = "⟨length⟩" + }, + ["chamfered rectangle xsep"] = { + details = [[ +Sets the distance that the chamfer extends horizontally beyond the node +contents (which includes the `inner sep`). If ⟨length⟩ is large, such +that the top and bottom chamfered edges would cross, then ⟨length⟩ is +ignored and the chamfered edges are drawn so that they meet in the +middle. + + \begin{tikzpicture} + \tikzset{every node/.style={chamfered rectangle, draw}} + \node[chamfered rectangle xsep=2pt] {def}; + \node[chamfered rectangle xsep=2cm] at (1.5,0) {456}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:xsep", + meta = "⟨length⟩" + }, + ["chamfered rectangle ysep"] = { + details = [[ +Sets the distance that the chamfer extends vertically beyond the node +contents. If ⟨length⟩ is large, such that the left and right chamfered +edges would cross, then ⟨length⟩ is ignored and the chamfered edges are +drawn so that they meet in the middle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/chamfered:rectangle:ysep", + meta = "⟨length⟩" + }, + ["circular sector angle"] = { + details = [[ +Sets the central angle of the sector. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/circular:sector:angle", + meta = "⟨angle⟩" + }, + ["cloud ignores aspect"] = { + details = [[ +Instruct PGF to ignore the `aspect` key. Internally, the TeX-if +`\ifpgfcloudignoresaspect` is set appropriately. The initial value is +`false`. + + \begin{tikzpicture}[aspect=1, every node/.style={cloud, cloud puffs=11, draw}] + \node [fill=gray!20] {rain}; + \node [cloud ignores aspect, fill=white] at (1.5,0) {snow}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:ignores:aspect", + meta = "⟨boolean⟩" + }, + ["cloud puff arc"] = { + details = [[ +Sets the length of the puff arc (in degrees). A shorter arc can produce +better looking joins between puffs for larger line widths. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:puff:arc", + meta = "⟨angle⟩" + }, + ["cloud puffs"] = { + details = [[ +Sets the number of puffs for the cloud. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cloud:puffs", + meta = "⟨integer⟩" + }, + ["cylinder body fill"] = { + details = [[ +Sets the color for the body of the cylinder. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:body:fill", + meta = "⟨color⟩" + }, + ["cylinder end fill"] = { + details = [[ +Sets the color for the end of the cylinder. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:end:fill", + meta = "⟨color⟩" + }, + ["cylinder uses custom fill"] = { + details = [[ +This enables the use of a custom fill for the body and the end of the +cylinder. The background path for the shape should not be filled (e.g., +in TikZ, the `fill` option for the node must be implicity or explicitly +set to `none`). Internally, this key sets the TeX-if +`\ifpgfcylinderusescustomfill` appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/cylinder:uses:custom:fill", + meta = "⟨boolean⟩" + }, + ["dart tail angle"] = { + details = [[ +Sets the angle between the tails of the dart. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/dart:tail:angle", + meta = "⟨angle⟩" + }, + ["dart tip angle"] = { + details = [[ +Sets the angle at the tip of the dart. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/dart:tip:angle", + meta = "⟨angle⟩" + }, + ["data visualization/style sheets/⟨style sheet⟩/default style"] = { + details = [[ +This key gets during styling whenever +`/pgf/data visualization/style sheet/`⟨style sheet⟩`/`⟨value⟩ is not +defined. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data:visualization/style:sheets/⟨style:sheet⟩/default:style", + meta = "⟨value⟩" + }, + ["data/format"] = { + details = [[ +Use this key to locally set the format used for parsing the data. The +⟨format⟩ must be a format that has been previously declared using the +`\pgfdeclaredataformat` command. See the reference section for a list of +the predefined formats. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/format", + meta = "⟨format⟩" + }, + ["data/headline"] = { + details = [[ +When this key is set to a non-empty value, the value of ⟨headline⟩ is +used as the headline and the first line of the data is treated as a +normal line rather than as a headline. + + \begin{tikzpicture} + \datavisualization [school book axes, visualize as line] + data [headline={x, y}] { + 0, 0 + 1, 1 + 2, 1 + 3, 0 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/headline", + meta = "⟨headline⟩" + }, + ["data/inline"] = { + details = [[ +This is a shorthand file `read from file={}`. You can add this to make +it clear(er) to the reader that data follows inline. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/inline" + }, + ["data/new set"] = { + details = [[ +Creates an empty data set called ⟨name⟩. If a data set of the same name +already exists, it is overwritten and made empty. Data sets are global. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/new:set", + meta = "⟨name⟩" + }, + ["data/read from file"] = { + details = [[ +If you set the `read from file` attribute to a non-empty ⟨filename⟩, the +data will be read from this file. In this case, no ⟨inline data⟩ may be +present, not even empty curly braces should be provided. If +`read from file` is empty, the data must directly follow as ⟨inline +data⟩. + + % Data is read from two external files: + \pgfdata[format=table, read from file=file1.csv] + \pgfdata[format=table, read from file=file2.csv] + + % Data is given inline: + \pgfdata[format=table] + { + x, y + 1, 2 + 2, 3 + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/read:from:file", + meta = "⟨filename⟩" + }, + ["data/samples"] = { + details = [[ +Sets the number of samples to be used when no sample number is +specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/samples", + meta = "⟨number⟩" + }, + ["data/separator"] = { + details = [[ +Use this key to change which character is used to separate values in the +headline and in the data lines. To set the separator to a space, either +set this key to an empty value or say `separator=\space`. Note that you +must surround a comma by curly braces if you which to (re)set the +separator character to a space. + + \begin{tikzpicture} + \datavisualization [school book axes, visualize as line] + data [separator=\space] { + x y + 0 0 + 1 1 + 2 1 + 3 0 + } + data [separator=;] { + x; y; z + 3; 1; 0 + 2; 2; 0 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/separator", + meta = "⟨character⟩" + }, + ["data/set"] = { + details = [[ +Shorthand for `/data point/set=`⟨name⟩. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/set", + meta = "⟨name⟩" + }, + ["data/store in set"] = { + details = [[ +When this key is set to any non-empty ⟨name⟩ and if this ⟨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 +⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/store:in:set", + meta = "⟨name⟩" + }, + ["data/use set"] = { + details = [[ +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 ⟨name⟩ is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/data/use:set", + meta = "⟨name⟩" + }, + ["declare function"] = { + details = [[ +This key allows simple functions to be created locally. Its use is +perhaps best illustrated by an example: + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \draw [blue, thick, x=0.0085cm, y=1cm, + declare function={ + sines(\t,\a,\b)=1 + 0.5*(sin(\t)+sin(\t*\a)+sin(\t*\b)); + }] + plot [domain=0:360, samples=144, smooth] (\x,{sines(\x,3,5)}); + \end{tikzpicture} + +Each definition in ⟨function definitions⟩ takes the form +⟨name⟩`(`⟨arguments⟩`)=`⟨definition⟩`;` (note the semicolon at the end, +this is very important). If multiple functions are being defined, the +semicolon is used to separate them (*not* a comma). The function ⟨name⟩ +can be any name that is not already a function name in the current +scope. The list of ⟨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 be used. The ⟨definition⟩ should be an expression +that can be parsed by the mathematical engine and should use the +commands specified in ⟨arguments⟩. + +When specifying multiple functions, functions that appear later on in +⟨function definitions⟩ can refer to earlier functions: + + \begin{tikzpicture}[ + declare function={ + excitation(\t,\w) = sin(\t*\w); + noise = rnd - 0.5; + source(\t) = excitation(\t,20) + noise; + filter(\t) = 1 - abs(sin(mod(\t, 90))); + speech(\t) = 1 + source(\t)*filter(\t); + } + ] + \draw [help lines] (0,0) grid (3,2); + \draw [blue, thick, x=0.0085cm, y=1cm] (0,1) -- + plot [domain=0:360, samples=144, smooth] (\x,{speech(\x)}); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function", + meta = "⟨function definitions⟩" + }, + ["declare function/execute at begin function"] = { + details = [[ +These ⟨tokens⟩ are inserted just before `\pgfmathdeclarefunction` scans +the body of the function definition. This is a rather low-level option, +so you should read the implementation to figure out where the ⟨tokens⟩ +are inserted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/execute:at:begin:function", + meta = "⟨tokens⟩" + }, + ["declare function/execute at end function"] = { + details = [[ +These ⟨tokens⟩ are inserted just after `\pgfmathdeclarefunction` has +finished scanning the body of the function definition. This is a rather +low-level option, so you should read the implementation to figure out +where the ⟨tokens⟩ are inserted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/execute:at:end:function", + meta = "⟨tokens⟩" + }, + ["declare function/ignore spaces"] = { + details = [[ +Uses the two previously described keys +`/pgf/declare function/execute at begin function` and +`/pgf/declare function/execute at end function` to install catcodes such +that spaces inside the body of the function definition of +`\pgfmathdeclarefunction` are ignored. The usual TeX tokenization rules +apply, so if the body of the function had already been tokenized by +other means this will become ineffective. If you want to use a space you +can use ` ` in the function body which has its catcode set to 10 +(space). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/declare:function/ignore:spaces", + meta = "⟨boolean⟩" + }, + decoration = { + details = [[ +This option is used to specify which decoration is used and how it will +look like. Note that this key will *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 be used, in principle. +You can also use this option at the beginning of a picture or a scope to +specify the decoration to be used with each invocation of the `decorate` +path command. Naturally, any local options of the `decorate` path +command override these "global" options. + + \begin{tikzpicture}[decoration=zigzag] + \draw decorate {(0,0) -- (3,2)}; + \draw [red] decorate [decoration=crosses] {(0,2) -- (3,0)}; + \end{tikzpicture} + +The ⟨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 strongly depend on the +decoration, you will have to look up the appropriate options in the +documentation of the decoration, see Section ??. + +There is one option (available only in TikZ) that is special: + +Further options allow you to adjust the position of decorations relative +to the to-be-decorated path. See Section ?? below for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration", + meta = "⟨decoration options⟩" + }, + ["decoration automaton/auto corner on length"] = { + details = [[ +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 ⟨dimension⟩. If so, 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. + +The main idea behind this option is to avoid having decoration segments +"overshoot" past a corner. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/auto:corner:on:length", + meta = "⟨dimension⟩" + }, + ["decoration automaton/auto end on length"] = { + details = [[ +This key is just included for convenience, it does nothing that cannot +be achieved using the previous options. The effect is the following: If +the remaining input path's length is at most ⟨dimension⟩, the decorated +path is ended with a straight line to the end of the input path and, +possibly, it is closed, namely if the input path ended with a closepath +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 ⟨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. + +In all other cases, nothing happens. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/auto:end:on:length", + meta = "⟨dimension⟩" + }, + ["decoration automaton/if input segment is closepath"] = { + details = [[ +This key checks whether the current input segment is a closepath +operation. If so, the ⟨options⟩ get executed; otherwise nothing happens. +You can use this option to handle a closepath in some special way, for +instance, switching to a new state in which `\pgfpathclose` is executed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/if:input:segment:is:closepath", + meta = "⟨options⟩" + }, + ["decoration automaton/next state"] = { + details = [[ +After the ⟨code⟩ for state has been executed for the last time, a state +switch to ⟨new state⟩ is performed. If this option is not given, the +next state is the same as the current state. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/next:state", + meta = "⟨new state⟩" + }, + ["decoration automaton/persistent postcomputation"] = { + details = [[ +Works like the `persistent precomputation` option, only the ⟨postcode⟩ +is executed after (and also outside) the TeX-group of the main ⟨code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/persistent:postcomputation", + meta = "⟨postcode⟩" + }, + ["decoration automaton/persistent precomputation"] = { + details = [[ +If the ⟨code⟩ of the state is executed, the ⟨precode⟩ is executed first +and it is executed outside the TeX-group of the ⟨code⟩. Note that when +the ⟨precode⟩ is executed, the transformation matrix is not set up. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/persistent:precomputation", + meta = "⟨precode⟩" + }, + ["decoration automaton/repeat state"] = { + details = [[ +Tells PGF how long the automaton stays "normally" in the current state. +This count is reset to ⟨repetitions⟩ each time one of the `switch if` +keys causes a state switch. If no state switches occur, the ⟨code⟩ is +executed and the repetition counter is decreased. Then, there is once +more a chance of a state change caused by any of the ⟨options⟩. If no +repetition occurs, the ⟨code⟩ is executed once more and the counter is +decreased once more. When the counter reaches zero, the ⟨code⟩ is +executed once more, but, then, a different state is entered, as +specified by the `next state` option. + +Note, that the maximum number of times the state will be executed is +$⟨repetitions⟩+1$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/repeat:state", + meta = "⟨repetitions⟩" + }, + ["decoration automaton/switch if input segment less than"] = { + details = [[ +When this key is encountered, PGF checks whether the remaining distance +to the end of the current input segment of the input path is less than +⟨dimension⟩. If so, an immediate state switch to ⟨new state⟩ occurs. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/switch:if:input:segment:less:than", + meta = " ⟨dimension⟩ to ⟨new state⟩" + }, + ["decoration automaton/switch if less than"] = { + details = [[ +When this key is encountered, PGF checks whether the remaining distance +to the end of the input path is less than ⟨dimension⟩. If so, an +immediate state switch to ⟨new state⟩ occurs. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/switch:if:less:than", + meta = "⟨dimension⟩ to ⟨new state⟩" + }, + ["decoration automaton/width"] = { + details = [[ +First, this option causes an immediate switch to the state `final` if +the remaining distance on the input path is less than ⟨dimension⟩. The +effect is the same as if you had said +`switch if less than=`⟨dimension⟩` to final` just before the `width` +option. + +If no switch occurs, this option tells PGF the width of the segment. The +current point will travel along the input path (as described earlier) by +this distance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration:automaton/width", + meta = "⟨dimension⟩" + }, + ["decoration/amplitude"] = { + details = [[ +This key determines the "desired height" (or amplitude) of decorations +for which this makes sense. For instance, the initial value of `2.5pt` +means that deforming decorations should deform a path by up to 2.5pt +away from the original path. + +This key sets the TeX-dimension `\pgfdecorationsegmentamplitude`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/amplitude", + meta = "⟨dimension⟩" + }, + ["decoration/anchor"] = { + details = [[ +The anchor used to position the shape backgrounds. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/anchor", + meta = "⟨anchor⟩" + }, + ["decoration/angle"] = { + details = [[ +The way some decorations look like depends on a configurable angle. For +instance, a `wave` decoration consists of arcs and the opening angle of +these arcs is given by the `angle`. + +This key sets the TeX-macro `\pgfdecorationsegmentangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/angle", + meta = "⟨degree⟩" + }, + ["decoration/aspect"] = { + details = [[ +For some decorations there is a natural aspect ratio. For instance, for +a `brace` decoration the aspect ratio determines where the brace point +will be. + +This key sets the TeX-macro `\pgfdecorationsegmentaspect`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/aspect", + meta = "⟨factor⟩" + }, + ["decoration/closepath code"] = { + details = [[ +Set the code to be executed for every closepath input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/closepath:code", + meta = "⟨code⟩" + }, + ["decoration/curveto code"] = { + details = [[ +Set the code to be executed for every curveto input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/curveto:code", + meta = "⟨code⟩" + }, + ["decoration/end radius"] = { + details = [[ +For some decorations there is a natural end radius (of some circle, +presumably). + +This key stores the value directly inside the key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/end:radius", + meta = "⟨dimension⟩" + }, + ["decoration/foot angle"] = { + details = [[ +Footprints are rotated by this much. + + \begin{tikzpicture}[decoration={footprints,foot angle=60}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:angle" + }, + ["decoration/foot length"] = { + details = [[ +The length or size of the footprint itself. A larger value makes the +footprint larger, but does not change the stride length. + + \begin{tikzpicture}[decoration={footprints,foot length=20pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:length" + }, + ["decoration/foot of"] = { + details = [[ +The species whose footprints are shown. Possible values are: + + -------------------- ------------- + *Species* *Result* + `gnome` \[PICTURE\] + `human` \[PICTURE\] + `bird` \[PICTURE\] + `felis silvestris` \[PICTURE\] + -------------------- ------------- +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:of" + }, + ["decoration/foot sep"] = { + details = [[ +The separation in the middle between the footprints. The footprints are +moved away from the path by half this amount. + + \begin{tikzpicture}[decoration={footprints,foot sep=10pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/foot:sep" + }, + ["decoration/lineto code"] = { + details = [[ +Set the code to be executed for every lineto input segment. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/lineto:code", + meta = "⟨code⟩" + }, + ["decoration/mark"] = { + details = [[ +This works similarly to the `at position` version of this option, only +multiple marks are placed, starting at ⟨start pos⟩ and then spaced apart +by ⟨stepping⟩. The ⟨start pos⟩, the ⟨end pos⟩, and also the ⟨stepping⟩ +may all be specified in the same way as for the `at position` version, +that is, either using units or no units and also using positive or +negative values. + +Let us start with a simple example in which we place ten crosses along a +path starting with the beginning of the path ($⟨start pos⟩ = 0$) and +ending at the end ($⟨end pos⟩ = 1$). + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 0.1 + with { \draw (-2pt,-2pt) -- (2pt,2pt); + \draw (2pt,-2pt) -- (-2pt,2pt); }} ] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} + +In the next example we place arrow shapes on the path instead of +crosses. Note the use of the `transform shape` option to ensure that the +nodes are actually rotated. + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 1cm + with { \node [single arrow,fill=red, + single arrow head extend=3pt,transform shape] {};}}] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} + +Using the key `sequence number` we can also "number" the nodes and even +refer to them later on. + + \begin{tikzpicture}[decoration={markings, + mark=between positions 0 and 1 step 1cm with { + \node [draw, + name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}, + transform shape] + {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \draw [red,->] (mark-3) -- (mark-7); + \end{tikzpicture} + +In the following example we use the distance info to place "length +information" on a path: + + \begin{tikzpicture}[decoration={markings, + % Main marks + mark=between positions 0 and 1 step 40pt with + { \draw [help lines] (0,0) -- (0,0.5) + node[above,font=\tiny]{ + \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }, + mark=at position -0.1pt with + { \draw [help lines] (0,0) -- (0,0.5) + node[above,font=\tiny]{ + \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}] + \draw [help lines] grid (5,3); + \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark", + meta = "between positions ⟨start pos⟩ and ⟨end pos⟩ step ⟨stepping⟩ with ⟨code⟩" + }, + ["decoration/mark connection node"] = { + details = [[ +When this key is set to a non-empty ⟨node name⟩ while the decoration is +being processed, the following happens: The marking code should, among +possibly other things, define a node named ⟨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 end is given by the position on the border of ⟨node +name⟩ that lies in the direction "from which the path heads toward the +node" while the other end lies on the border "where the path heads away +from the node". Furthermore, this option causes the decoration to end +with a line-to to the end instead of a move-to. + +The net effect of all this is that when you decorate a straight line +with one or more markings that contain just a node, the line will +effectively connect these nodes. + +Here are two examples that show how this works: + + \begin{tikzpicture}[decoration={markings, + mark connection node=my node, + mark=at position .5 with + {\node [draw,blue,transform shape] (my node) {my node};}}] + \draw [help lines] grid (3,2); + \draw decorate { (0,0) -- (3,2) }; + \end{tikzpicture} + + \begin{tikzpicture}[decoration={markings, + mark connection node=my node, + mark=at position .25 with + {\node [draw,red] (my node) {my node};}}] + \draw [help lines] grid (3,2); + \draw decorate { (0,0) -- (3,2) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:connection:node", + meta = "⟨node name⟩" + }, + ["decoration/mark info/distance from start"] = { + details = [[ +This key can only be read. Its value is the distance of the marking from +the start of the path in points. For instance, if the path length is +100pt and the marking is in the middle of the path, the value of this +key would be `50.0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:info/distance:from:start" + }, + ["decoration/mark info/sequence number"] = { + details = [[ +This key can only be read. Its value (which can be obtained using the +`\pgfkeysvalueof` command) is a "sequence number" of the mark. The first +mark that is added to a path has number `1`, the second number `2`, and +so on. This key is mainly useful in conjunction with repeated markings +(see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mark:info/sequence:number" + }, + ["decoration/meta-amplitude"] = { + details = [[ +This key determines the amplitude for a meta-decoration. + +The key sets the TeX-macro (!) `\pgfmetadecorationsegmentamplitude`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/meta-amplitude", + meta = "⟨dimension⟩" + }, + ["decoration/meta-segment length"] = { + details = [[ +This determined the length of the meta-segments from which a +meta-decoration is made up. + +This key sets the TeX-macro (!) `\pgfmetadecorationsegmentlength`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/meta-segment:length", + meta = "⟨dimension⟩" + }, + ["decoration/mirror"] = { + details = [[ +Causes the segments of the decoration to be mirrored along the +to-be-decorated path. This is done after and in addition to any +transformations set using the `transform` and/or `raise` options. + + \begin{tikzpicture} + \node (a) {A}; + \node (b) at (2,1) {B}; + \draw (a) -- (b); + \draw[decorate,decoration=brace] (a) -- (b); + \draw[decorate,decoration={brace,mirror},red] (a) -- (b); + \draw[decorate,decoration={brace,mirror,raise=5pt},blue] (a) -- (b); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/mirror", + meta = "⟨boolean⟩" + }, + ["decoration/moveto code"] = { + details = [[ +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 *off* when ⟨code⟩ is executed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/moveto:code", + meta = "⟨code⟩" + }, + ["decoration/name"] = { + details = [[ +Use this key to set which decoration is to be used. The ⟨name⟩ can both +be a decoration or a meta-decoration (you need to worry about the +difference only if you wish to define your own decorations). + +If you set ⟨name⟩ to `none`, no decorations are added. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw decorate [decoration={name=zigzag}] + { (0,0) .. controls (0,2) and (3,0) .. (3,2) }; + \end{tikzpicture} + +Since this option is used so often, you can also leave out the `name=` +part. Thus, the above example can be rewritten more succinctly: + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw decorate [decoration=zigzag] + { (0,0) .. controls (0,2) and (3,0) .. (3,2) }; + \end{tikzpicture} + +In general, when ⟨decoration options⟩ are parsed, for each unknown key +it is checked whether that key happens to be a (meta-)decoration and, if +so, the `name` option is executed for this key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/name", + meta = "⟨name⟩" + }, + ["decoration/path has corners"] = { + details = [[ +This is a hint to the decoration code as to whether the path has corners +or not. If a path has a sharp corner, setting this option to `true` may +result in better rendering of the decoration because the joins of input +segments are approached "more carefully" than when this key is set to +false. However, if the path is, say, a smooth circle, setting this key +to `true` will usually look worse. Most decorations ignore this key, +anyway. Internally, it sets the TeX-if `\ifpgfdecoratepathhascorners`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/path:has:corners", + meta = "⟨boolean⟩" + }, + ["decoration/pre"] = { + details = [[ +This key sets a decoration that should be used before the main +decoration starts. The ⟨decoration⟩ will be used for a length of +`pre length`, which `0pt` by default. Thus, for the `pre` option to have +any effect, you also need to set the `pre length` option. + + \tikz [decoration={zigzag,pre=lineto,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=moveto,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=crosses,pre length=1cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + +Note that the default `pre` option is `lineto`, not `curveto`. This +means that the default `pre` decoration will not follow curves (for +efficiency reasons). Change the `pre` key to `curveto` if you have a +curved path. + + \tikz [decoration={zigzag,pre length=3cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); + + \tikz [decoration={zigzag,pre=curveto,pre length=3cm}] + \draw [decorate] (0,0) -- (2,1) arc (90:0:1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/pre", + meta = "⟨decoration⟩" + }, + ["decoration/pre length"] = { + details = [[ +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 evaluates to the same +things such as `0cm`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/pre:length", + meta = "⟨dimension⟩" + }, + ["decoration/radius"] = { + details = [[ +Sets the start and end radius simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/radius", + meta = "⟨dimension⟩" + }, + ["decoration/raise"] = { + details = [[ +The segments of the decoration are raised by ⟨dimension⟩ relative to the +to-be-decorated path. More precisely, the segments of the path are +offset by this much "to the left" of the path as we travel along the +path. This raising is done after and in addition to any transformations +set using the `transform` option (see below). + +A negative ⟨dimension⟩ will offset the decoration "to the right" of the +to-be-decorated path. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + + \draw (0,0) -- (1,1) arc (90:0:2 and 1); + \draw decorate [decoration=crosses] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \draw[red] decorate [decoration={crosses,raise=5pt}] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/raise", + meta = "⟨dimension⟩" + }, + ["decoration/reset marks"] = { + details = [[ +Since `mark` options accumulate, there needs to be a way to "reset" +things, so that any `mark` options set in an enclosing scope do not +interfere. This option does exactly this. Note that when the ⟨code⟩ of a +marking is executed, the markings are automatically reset. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/reset:marks" + }, + ["decoration/reverse path"] = { + details = [[ +This key reverses the path. This is especially useful for typesetting +text along different sides of curves. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [gray, ->] + [postaction={decoration={text along path, + text={a big juicy apple}, text color=red}, decorate}] + [postaction={decoration={text along path, + text={a big juicy apple}, text color=blue, reverse path}, decorate}] + (3,0) .. controls (3,2) and (0,2) .. (0,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/reverse:path", + meta = "⟨boolean⟩" + }, + ["decoration/segment length"] = { + details = [[ +Many decorations are made up of small segments. This key determines the +desired length of such segments. + +This key sets the TeX-dimension `\pgfdecorationsegmentlength`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/segment:length", + meta = "⟨dimension⟩" + }, + ["decoration/shape"] = { + details = [[ +The shape whose background path is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape", + meta = "⟨shape name⟩" + }, + ["decoration/shape end height"] = { + details = [[ +The recommended ending height of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:height", + meta = "⟨length⟩" + }, + ["decoration/shape end size"] = { + details = [[ +Set both the end height and end width simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:size", + meta = "⟨length⟩" + }, + ["decoration/shape end width"] = { + details = [[ +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. + + \tikzset{ + bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}}, + smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}}, + decoration={shape backgrounds, + shape sep={.25cm, between borders},shape scaled} + } + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \fill [decorate,bigger, + decoration={shape sep={.25cm, between borders}}, blue!50] + (0,1.5) -- (3,1.5); + \fill [decorate,smaller, + decoration={shape sep={1cm, between centers}}, red!50] + (0,.5) -- (3,.5); + \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1) + (0,1) -- (3,.625) (0,0) -- (3,.375); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:end:width", + meta = "⟨length⟩" + }, + ["decoration/shape evenly spread"] = { + details = [[ +This key overrides the `shape sep` key and forces the decoration to fit +⟨number⟩ shapes evenly across the path. If ⟨number⟩ is less than `1`, +then no shapes will be used. If ⟨number⟩ equals `1`, then one shape is +put in the middle of the path. The additional keywords `by centers` (the +default, if no keyword is specified) and `by borders` can be used (both +preceded by a comma), to specify how the distance between shapes is +determined. These keywords will only have a noticeable effect if the +shapes sizes differ over time. + + \tikzset{ + paint/.style={draw=#1!50!black, fill=#1!50}, + spreading/.style={ + decorate,decoration={shape backgrounds, shape=rectangle, + shape start size=4mm,shape end size=1mm,shape evenly spread={#1}}} + } + \begin{tikzpicture} + \fill [paint=green,spreading={5, by borders}, + decoration={shape scaled}] (0,2) -- (3,2); + \fill [paint=blue,spreading={5, by centers}, + decoration={shape scaled}] (0,1.5) -- (3,1.5); + \fill [paint=red, spreading=5] (0,1) -- (3,1); + \fill [paint=orange, spreading=4] (0,.5) -- (3,.5); + \fill [paint=gray, spreading=1] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:evenly:spread", + meta = "⟨number⟩" + }, + ["decoration/shape height"] = { + details = [[ +Works like the previous key, only for the height. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:height", + meta = "⟨dimension⟩" + }, + ["decoration/shape scaled"] = { + details = [[ + \tikzset{ + bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}}, + smaller/.style={decoration={shape start size=.5cm, shape end size=.125cm}}, + decoration={shape backgrounds, + shape sep={.25cm, between borders},shape scaled} + } + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \fill [decorate, bigger, red!50] (0,1) -- (3,2); + \fill [decorate, smaller, blue!50] (0,0) -- (3,1); + \end{tikzpicture} + +If this key is set to false (which is the default), then only the start +width and height are used. Note that the keys `shape width` and +`shape height` set the start and end height simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:scaled", + meta = "⟨boolean⟩" + }, + ["decoration/shape sep"] = { + details = [[ +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 the +shapes or between the edges of the *boundaries* of the shape borders. + + \begin{tikzpicture}[ + decoration={shape backgrounds,shape size=.5cm,shape=signal}, + signal from=west, signal to=east, + paint/.style={decorate, draw=#1!50!black, fill=#1!50}] + \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 centers}}] + (0,1) -- (3,1); + \draw [paint=blue, decoration={shape sep={1cm, between borders}}] + (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:sep", + meta = "⟨spacing⟩" + }, + ["decoration/shape size"] = { + details = [[ +Sets the desired width and height simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:size", + meta = "⟨dimension⟩" + }, + ["decoration/shape sloped"] = { + details = [[ +By default, shapes are rotated to the slope of the decorations path. If +⟨boolean⟩ is the value `false`, then this rotation is turned off. +Internally this sets the TeX-if `\ifpgfshapedecorationsloped` +accordingly. + + \tikzset{ + paint/.style={draw=#1!50!black, fill=#1!50} + } + \begin{tikzpicture}[decoration={ + shape width=.65cm, shape height=.45cm, + shape=isosceles triangle, shape sep=.75cm, + shape backgrounds}] + \draw [help lines] grid (3,2); + \draw [paint=red,decorate] (0,0) -- (2,2); + \draw [paint=blue,decorate,decoration={shape sloped=false}] + (1,0) -- (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:sloped", + meta = "⟨boolean⟩" + }, + ["decoration/shape start height"] = { + details = [[ +The starting height of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:height", + meta = "⟨length⟩" + }, + ["decoration/shape start size"] = { + details = [[ +Sets both the start height and start width simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:size", + meta = "⟨length⟩" + }, + ["decoration/shape start width"] = { + details = [[ +The starting width of the shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:start:width", + meta = "⟨length⟩" + }, + ["decoration/shape width"] = { + details = [[ +The desired width of the shapes. For decorations that support varying +shape sizes, this key sets both the start and end width (which can be +overwritten using options like `shape start width`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/shape:width", + meta = "⟨dimension⟩" + }, + ["decoration/start radius"] = { + details = [[ +For some decorations there is a natural start radius (of some circle, +presumably). + +This key stores the value directly inside the key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/start:radius", + meta = "⟨dimension⟩" + }, + ["decoration/stride length"] = { + details = [[ +The length of strides. This is the distance between the beginnings of +left footprints along the path. + + \begin{tikzpicture}[decoration={footprints,stride length=50pt}] + \fill [decorate] (0,0) -- (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/stride:length" + }, + ["decoration/text"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text", + meta = "⟨text⟩" + }, + ["decoration/text align"] = { + details = [[ +This changes the key path to `/pgf/decoration/text align` and executes +⟨alignment options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align", + meta = "{⟨alignment options⟩}" + }, + ["decoration/text align/align"] = { + details = [[ +Aligns the text according to ⟨alignment⟩, which should be one of `left`, +`right`, or `center`. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align={align=right}}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/align", + meta = "⟨alignment⟩" + }, + ["decoration/text align/center"] = { + details = [[ +Aligns the text to the center of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/center" + }, + ["decoration/text align/fit to path"] = { + details = [[ +This key makes the decoration automaton try to fit the text to the +length of the path. The automaton shifts forward by a small amount +between each character in order to fit the text to the path. If, +however, the length of the text is longer than the length of the path +(i.e., the automaton would have to shift *backwards* between characters) +this key will have no effect. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align=fit to path}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/fit:to:path", + meta = "⟨boolean⟩" + }, + ["decoration/text align/fit to path stretching spaces"] = { + details = [[ +This key works like the previous key except the automaton shifts forward +only for space characters (including `\space`, but *excluding* `\`). + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \draw [red, dashed] + [postaction={decoration={text along path, text={a big juicy apple}, + text align={fit to path stretching spaces}}, decorate}] + (0,0) .. controls (0,2) and (3,2) .. (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/fit:to:path:stretching:spaces", + meta = "⟨boolean⟩" + }, + ["decoration/text align/left"] = { + details = [[ +Aligns the text to the left end of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/left" + }, + ["decoration/text align/left indent"] = { + details = [[ +Specifies a distance which the automaton should move along before it +starts typesetting the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/left:indent", + meta = "⟨length⟩" + }, + ["decoration/text align/right"] = { + details = [[ +Aligns the text to the right end of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/right" + }, + ["decoration/text align/right indent"] = { + details = [[ +Specifies a distance before the end of the path, where the automaton +should stop typesetting the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:align/right:indent", + meta = "⟨length⟩" + }, + ["decoration/text color"] = { + details = [[ +The color of the text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:color", + meta = "⟨color⟩" + }, + ["decoration/text effects/character command"] = { + details = [[ +This key specifies a command that is executed when each character is +placed in the node. The ⟨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. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:command", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character count"] = { + details = [[ +Store the number of the character being typeset in ⟨macro⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character total"] = { + details = [[ +Store the total number of the characters in the decoration text in +⟨macro⟩. This key can be used with the `character count` key to produce +some quite pleasing effects: + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:total", + meta = "⟨macro⟩" + }, + ["decoration/text effects/character widths"] = { + details = [[ +Shorthand for the `every character width` style. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:widths", + meta = "{effects}" + }, + ["decoration/text effects/character ⟨number⟩"] = { + details = [[ +Specify additional effects for the character ⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/character:⟨number⟩" + }, + ["decoration/text effects/characters"] = { + details = [[ +Shorthand for the `every character`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/characters", + meta = "{effects}" + }, + ["decoration/text effects/every character"] = { + details = [[ +Set the effects that will be applied to every character in the +decoration text. The effects will typically be TikZ 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:character" + }, + ["decoration/text effects/every character width"] = { + details = [[ +This style is applied to the (invisible) nodes used for calculating the +width of a character node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:character:width" + }, + ["decoration/text effects/every first letter"] = { + details = [[ +Specify additional effects for the first letter in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:first:letter" + }, + ["decoration/text effects/every last letter"] = { + details = [[ +Specify additional effects for the last letter in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:last:letter" + }, + ["decoration/text effects/every letter"] = { + details = [[ +Specify additional effects for every letter (i.e., every character that +isn't the word separator) in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:letter" + }, + ["decoration/text effects/every word"] = { + details = [[ +Specify additional effects for every word in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:word" + }, + ["decoration/text effects/every word separator"] = { + details = [[ +Specify additional effects for every character that is a word separator. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/every:word:separator" + }, + ["decoration/text effects/fit text to path"] = { + details = [[ +This key will make the decoration increase the space between characters +so that the entire path is used by the decoration. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/fit:text:to:path", + meta = "⟨true or false⟩" + }, + ["decoration/text effects/group letters"] = { + details = [[ +Group sequences of letters together so they are treated as a single +'character'. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/group:letters" + }, + ["decoration/text effects/letter count"] = { + details = [[ +Store the number of letter being typeset (i.e., the position of the +character in the word) in ⟨macro⟩. Numbering starts at `1` and the +character acting as a word separator is numbered `0`. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/letter:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/letter ⟨number⟩"] = { + details = [[ +Specify the effects for letter ⟨number⟩ in *every* word. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/letter:⟨number⟩" + }, + ["decoration/text effects/path from text"] = { + details = [[ +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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/path:from:text", + meta = "{true or false}" + }, + ["decoration/text effects/path from text angle"] = { + details = [[ +When used in conjunction with the `path from text` key, the straight +line that is used as the decorated path is rotated by ⟨angle⟩ around the +starting point. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/path:from:text:angle", + meta = "⟨angle⟩" + }, + ["decoration/text effects/repeat text"] = { + details = [[ +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 ⟨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 behavior of the `repeat text` key +is undefined, but typically it will be ignored. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/repeat:text", + meta = "⟨times⟩" + }, + ["decoration/text effects/replace characters"] = { + details = [[ +Replace the node for each character in ⟨characters⟩ with ⟨code⟩. The +⟨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 ⟨characters⟩ (e.g., applied with the `every character` or +`every letter` styles) will also be applied to ⟨code⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/replace:characters", + meta = "⟨characters⟩ with {code}" + }, + ["decoration/text effects/reverse text"] = { + details = [[ +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{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} + +It is important to note that the `reverse text` key reverses the text +*before* doing anything else. This means that the numbering of +characters, letters and words will still be in the normal order, so any +parameterized 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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/reverse:text" + }, + ["decoration/text effects/scale text to path"] = { + details = [[ +This key will make the decoration scale the text so that the entire path +is used by the decoration. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/scale:text:to:path", + meta = "⟨true or false⟩" + }, + ["decoration/text effects/style characters"] = { + details = [[ +This key enables ⟨effects⟩ to be applied to every character in the +decoration text that is specified in ⟨characters⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/style:characters", + meta = "{characters} with {effects}" + }, + ["decoration/text effects/text along path"] = { + details = [[ +This style automatically sets the TikZ 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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/text:along:path" + }, + ["decoration/text effects/word count"] = { + details = [[ +Store the number of words in the decoration text in ⟨macro⟩. Numbering +starts at `1`. When the character is the word separator, ⟨macro⟩ takes +the number of the previous word. If the decoration text starts with a +word separator ⟨macro⟩ will be `0`. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:count", + meta = "⟨macro⟩" + }, + ["decoration/text effects/word separator"] = { + details = [[ +Specify the character that is to be used as the word separator. This +*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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:separator", + meta = "⟨character⟩" + }, + ["decoration/text effects/word total"] = { + details = [[ +Store the total number of words in the decoration text in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:total", + meta = "⟨macro⟩" + }, + ["decoration/text effects/word ⟨m⟩ letter ⟨n⟩"] = { + details = [[ +Specify additional effects for letter ⟨n⟩ in word ⟨m⟩ in the decoration +text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:⟨m⟩:letter:⟨n⟩" + }, + ["decoration/text effects/word ⟨number⟩"] = { + details = [[ +Specify additional effects for word ⟨number⟩ in the decoration text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:effects/word:⟨number⟩" + }, + ["decoration/text format delimiters"] = { + details = [[ +' +texttt + +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 + +11` or `12`. As `+` is used to indicate that the specified format commands are added to any existing ones, you should avoid using `+| +as a delimiter. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \path [decorate, decoration={text along path,text format delimiters={[}{]}, + text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}] + (0,0) .. controls (0,2) and (3,0) .. (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text:format:delimiters", + meta = "{before}{after}" + }, + ["decoration/text/effetcs/letter total"] = { + details = [[ +Store the number of letters in the current word in ⟨macro⟩. When the +character is the word separator, this value is `0`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/text/effetcs/letter:total", + meta = "⟨macro⟩" + }, + ["decoration/transform"] = { + details = [[ +This key allows you to specify general ⟨transformations⟩ to be applied +to the segments of a decoration. These transformations are applied +before and independently of `raise` and `mirror` transformations. The +⟨transformations⟩ should be normal TikZ transformations like `shift` or +`rotate`. + +In the following example the `shift only` transformation is used to make +sure that the crosses are *not* sloped along the path. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + + \draw (0,0) -- (1,1) arc (90:0:2 and 1); + \draw[red,very thick] decorate [decoration={ + crosses,transform={shift only},shape size=1.5mm}] + { (0,0) -- (1,1) arc (90:0:2 and 1) }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decoration/transform", + meta = "⟨transformations⟩" + }, + ["decorations/post"] = { + details = [[ +Works like `pre`, only for the end of the decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decorations/post", + meta = "⟨decoration⟩" + }, + ["decorations/post length"] = { + details = [[ +Works like `pre length`, only for the end of the decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/decorations/post:length", + meta = "⟨dimension⟩" + }, + ["direction ee arrow"] = { + details = [[ +The value of this key will be used for the arrow tip depicted in an +`direction ee` shape. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/direction:ee:arrow", + meta = "⟨right arrow tip name⟩" + }, + ["double arrow head extend"] = { + details = [[ +This sets the distance between the shaft of the arrow and the outer end +of the arrow heads. This may change if the shape is enlarged to some +minimum width. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:head:extend", + meta = "⟨length⟩" + }, + ["double arrow head indent"] = { + details = [[ +This moves the point where the arrow heads join the shaft of the arrow +*towards* the arrow tips, by ⟨length⟩. + + \begin{tikzpicture}[every node/.style={double arrow, draw=none, rotate=-60}] + \node [fill=red!50] {arrow 1}; + \node [fill=blue!50, double arrow head indent=1ex] at (1.5,0) {arrow 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:head:indent", + meta = "⟨length⟩" + }, + ["double arrow tip angle"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/double:arrow:tip:angle", + meta = "⟨angle⟩" + }, + ["every data"] = { + details = [[ +This style is executed by `\pgfdata` before the ⟨options⟩ are parsed. + +Note that the path of this key is just `/pgf/`, not `/pgf/data/`. Also +note that TikZ internally sets the value of this key up in such a way +that the keys `/tikz/every data` and also +`/tikz/data visualization/every data` are executed. The bottom line of +this is that when using TikZ, you should not set this key directly, set +`/tikz/every data` instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/every:data" + }, + ["every decoration"] = { + details = [[ +This style is executed for every decoration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/every:decoration" + }, + ["fixed point arithmetic"] = { + details = [[ +This key will set the key path to `/pgf/fixed point`, and execute +⟨options⟩. Then it will install the necessary commands so that the PGF +parser will use `fp` to perform calculations. The best way to use this +key is as an argument to a scope or picture. This means that `fp` does +not always have to be used, and PGF can use its own mathematical engine +at other times, which can lead to a significant reduction in the time +for a document to compile. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point:arithmetic", + meta = "⟨options⟩" + }, + ["fixed point/scale file plot x"] = { + details = [[ +This key will scale the first column of data read from a file before it +is plotted. It is independent of the `scale results` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:x", + meta = "⟨factor⟩" + }, + ["fixed point/scale file plot y"] = { + details = [[ +This key will scale the second column of data read from a file before it +is plotted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:y", + meta = "⟨factor⟩" + }, + ["fixed point/scale file plot z"] = { + details = [[ +This key will scale the third column of data read from a file before it +is plotted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:file:plot:z", + meta = "⟨factor⟩" + }, + ["fixed point/scale results"] = { + details = [[ +As noted above, `fp` can process a far greater range of numbers than PGF +and TikZ. In order to use results from `fp` in a `{pgfpicture}` or a +`{tikzpicture}` they need to be scaled. When this key is used PGF will +scale results of any evaluation by ⟨factor⟩. However, as it is not +desirable for every part of every expression to be scaled, scaling will +only take place if a special prefix `*` is used. If `*` is used at the +beginning of an expression the evaluation of the expression will +evaluated and then multiplied by ⟨factor⟩. + + \begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}] + \draw [help lines] grid (3,2); + \draw (0,0) -- (2,2); + \draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6); + \end{tikzpicture} + +A special case of scaling involves plots of data containing large +numbers from files. It is possible to "pre-process" a file, typically +using the application that generates the data, to either precede the +relevant column with `*` or to perform the scaling as part of the +calculation process. However, it may be desirable for the data in a plot +to appear in a table as well, so, two files would be required, one +pre-processed for plotting, and one not. This extra work may be +undesirable so the following keys are provided: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fixed:point/scale:results", + meta = "⟨factor⟩" + }, + ["foreach/count"] = { + details = [[ +This key allows ⟨macro⟩ to hold the position in the list of the current +item. The optional `from `⟨value⟩ statement allows the counting to begin +from ⟨value⟩. + + \tikz[x=0.75cm,y=0.75cm] + \foreach \x [count=\xi] in {a,...,e} + \foreach \y [count=\yi] in {\x,...,e} + \node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm] + at (\xi,-\yi) {$\mathstrut\x\y$}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/count", + meta = "⟨macro⟩ from ⟨value⟩" + }, + ["foreach/evaluate"] = { + details = [[ +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 ⟨variables⟩ argument of the `foreach` command. By default, the +result of the evaluation will be stored in ⟨variable⟩. However, the +optional `as `⟨macro⟩ statement can be used to store the result in +⟨macro⟩. + + \foreach \x [evaluate=\x] in {2^0,2^...,2^8}{$\x$, } + + \foreach \x [evaluate=\x as \xeval] in {2^0,2^...,2^8}{$\x=\xeval$, } + +The optional `using `⟨formula⟩ statement means an evaluation does not +have to be explicitly stated for each item in ⟨list⟩. The ⟨formula⟩ +should contain at least one reference to ⟨variable⟩. + + \tikz\foreach \x [evaluate=\x as \shade using \x*10] in {0,1,...,10} + \node [fill=red!\shade!yellow, minimum size=0.65cm] at (\x,0) {\x}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/evaluate", + meta = "⟨variable⟩ as ⟨macro⟩ using ⟨formula⟩" + }, + ["foreach/expand list"] = { + details = [[ +If this key is set to true the contents of the list are fully expanded +with `\edef` before further processing. This allows using complex macros +which generate a list upon expansion without having to use an +intermediate macro. + + \def\Iota#1#2{% + \ifnum\numexpr#1\relax<\numexpr#2\relax + \the\numexpr#1\relax,% + \expandafter\Iota\expandafter{\the\numexpr(#1)+1\relax}{#2}% + \else + \the\numexpr#2\relax + \fi} + \foreach [expand list=true] \x in {\Iota{1}{5}} { + \x + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/expand:list", + meta = "{boolean}" + }, + ["foreach/parse"] = { + details = [[ +If this key is set to true the upper bound in the loop will be fed into +`\pgfmathparse`. This allows to use complex expressions as the upper +bound. However, the expression must be safe for evaluation in +`\pgfmathparse`. It is known that internal TeX registers can cause +trouble. + + \foreach \x [parse=true] in {1,...,1.0e+1 - 1}{ \x } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/parse", + meta = "{boolean}" + }, + ["foreach/remember"] = { + details = [[ +This key allows the item value stored in ⟨variable⟩ to be remembered +during the next iteration, stored in ⟨macro⟩. If a variable is +evaluated, the result of this evaluation is remembered. By default the +value of ⟨variable⟩ is zero for the first iteration, however, the +optional `(initially `⟨value⟩`)` statement, allows the ⟨macro⟩ to be +initially defined as ⟨value⟩. + + \foreach \x [remember=\x as \lastx (initially A)] in {B,...,H}{$\overrightarrow{\lastx\x}$, } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/remember", + meta = "⟨variable⟩ as ⟨macro⟩ (initially ⟨value⟩)" + }, + ["foreach/var"] = { + details = [[ +This key provides an alternative way to specify variables: +`\foreach [var=\x,var=\y]` is the same as `\foreach \x/\y`. If used, +this key should be used before the other keys. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/foreach/var", + meta = "⟨variable⟩" + }, + fpu = { + details = [[ +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`. + + \pgfkeys{/pgf/fpu} + \pgfmathparse{1+1}\pgfmathresult + +The FPU uses a low-level number representation consisting of flags, +mantissa and exponent [1]. 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 PGF processing (like coordinates) or may need to be +typeset. The FPU provides such methods as well. + +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. + +Please note that if the `fixedpointarithmetic` library of PGF will be +activated after the FPU, the FPU will be deactivated automatically. + +[1] Users should *always* use high level routines to manipulate floating +point numbers as the format may change in a future release. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu", + meta = "{boolean}" + }, + ["fpu/handlers/empty number"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/empty:number", + meta = "{input}{unreadable part}" + }, + ["fpu/handlers/invalid number"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/invalid:number", + meta = "{input}{unreadable part}" + }, + ["fpu/handlers/wrong lowlevel format"] = { + details = [[ +This command key is invoked whenever `\pgfmathfloattoregisters` or its +variants encounter something which is not a properly formatted low-level +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 ⟨input⟩. + +The initial setting is to generate an error message. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/handlers/wrong:lowlevel:format", + meta = "{input}{unreadable part}" + }, + ["fpu/install only"] = { + details = [[ +\[fpu-install-only\] Unfortunately, the FPU is currently incompatible +with drawing operations. However, it can still be useful to replace +single definitions with FPU counterparts to avoid errors of the kind +`Dimension too large` which tend to happen when transformation matrices +are inverted. + +This key allows to specify a list of definitions to be pulled into the +current scope. *Note that there is no reverse operation to uninstall +these definitions at the moment*, so it is advisable to do this in a +group. Conveniently, TikZ paths form an implicit group, so you can use +this key on a path as well. + +You have to be aware of the limitations that the FPU imposes. It will +not magically give TeX better precision, but it will avoid overflow or +underflow situations for large or small operands by rescaling them. In +the following example, in the first case the FPU variant performs much +better than the normal variant, however, in the second case where a +rescaling would not in fact be needed the rescaling introduces a small +round-off error. + + \begingroup + \pgfkeys{/pgf/fpu/install only={divide}} + \pgfmathparse{12.34/0.001234}\pgfmathresult (good) + \pgfmathparse{12/4}\pgfmathresult (bad) + \endgroup + +This key is introduced in PGFv3.1.6 and marked stable since PGF v3.1.8. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/install:only", + meta = "{list of names}" + }, + ["fpu/output format"] = { + details = [[ +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. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=float} + \pgfmathparse{exp(50)*42}\pgfmathresult + +The choice `sci` returns numbers in the format ⟨mantissa⟩`e`⟨exponent⟩. +It provides almost no computational overhead. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci} + \pgfmathparse{4.22e-8^-2}\pgfmathresult + +The choice `fixed` returns normal fixed point numbers and provides the +highest compatibility with the PGF engine. It is activated automatically +in case the FPU scales results. + + \pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed} + \pgfmathparse{sqrt(1e-12)}\pgfmathresult +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/output:format", + meta = "⟨float,sci,fixed⟩" + }, + ["fpu/rel thresh"] = { + details = [[ +A threshold used by `\pgfmathfloatifapproxequalrel` to decide whether +numbers are approximately equal. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/rel:thresh", + meta = "{number}" + }, + ["fpu/scale results"] = { + details = [[ +A feature which allows semi-automatic result scaling. Setting this key +has two effects: first, the output format for *any* computation will be +set to `fixed` (assuming results will be processed by PGF's kernel). +Second, any expression which starts with a star, `*`, will be multiplied +with ⟨scale⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/fpu/scale:results", + meta = "{scale}" + }, + ["gap around stream point"] = { + details = [[ +The ⟨dimension⟩ by which the lines between consecutive stream points are +shortened at the beginning and end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/gap:around:stream:point", + meta = "⟨dimension⟩" + }, + ["generic circle IEC/before background"] = { + details = [[ +When a node of shape `generic circle IEC` is created, the current +setting of this key is used as the "before background path". This means +that after the circle's background has been drawn/filled/whatever, the +⟨code⟩ is executed. + +When the ⟨code⟩ is executed, the coordinate system will have been +transformed in such a way that the point $(1\mathrm{pt},0\mathrm{pt})$ +lies at the right end of the circle and $(0\mathrm{pt},1\mathrm{pt})$ +lies at the top of the circle. (More precisely, these points will lie +exactly on the middle of the radial line.) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/generic:circle:IEC/before:background", + meta = "⟨code⟩" + }, + ["generic diode IEC/before background"] = { + details = [[ +Similarly to the `generic circle IEC` shape, when a node of shape +`generic diode IEC` is created, the current setting of this key is used +as the "before background path". When the ⟨code⟩ is executed, the +coordinate system will have been transformed in such a way that the +origin is at the "tip" of the diode's triangle, the point +$(0\mathrm{pt},1\mathrm{pt})$ is exactly half the diode's height above +this origin, and the point $(1\mathrm{pt},0\mathrm{pt})$ is half the +diode's height to the right of the origin. + +The idea is that you use this key to draw different kinds of diode +endings. + + \tikz \node [minimum size=1cm,generic diode IEC, + /pgf/generic diode IEC/before background={ + \pgfpathmoveto{\pgfqpoint{-.5pt}{-1pt}} + \pgfpathlineto{\pgfqpoint{.5pt}{-1pt}} + \pgfpathmoveto{\pgfqpoint{0pt}{-1pt}} + \pgfpathlineto{\pgfqpoint{0pt}{1pt}} + \pgfpathmoveto{\pgfqpoint{-.5pt}{1pt}} + \pgfpathlineto{\pgfqpoint{.5pt}{1pt}} + \pgfusepathqstroke + }, + draw] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/generic:diode:IEC/before:background", + meta = "⟨code⟩" + }, + ["handle new data sets in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `ignore` The command will be completely ignored, just as if the + command had not been used at all. + +- `jump` This causes the internal macro `\pgf@plotstreamjump` to be + called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:new:data:sets:in:plots", + meta = "⟨how⟩" + }, + ["handle outlier points in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `plot` This will cause the outlier to be drawn normally, just as if + `\pgfplotstreampoint` had been used rather than this command. + +- `ignore` The outlier will be completely ignored, just as if the + command had not been used at all. + +- `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 behavior you will be looking for. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:outlier:points:in:plots", + meta = "⟨how⟩" + }, + ["handle undefined points in plots"] = { + details = [[ +You can set ⟨how⟩ to one of the following values: + +- `ignore` The undefined point will be completely ignored, just as if + the command had not been used at all. + +- `jump` This causes the internal macro `\pgf@plotstreamjump` to be + called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/handle:undefined:points:in:plots", + meta = "⟨how⟩" + }, + ["images/external info"] = { + details = [[ +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 +`\pgfexternalwidth` and the height as `\pgfexternalheight`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/images/external:info", + meta = "{boolean}" + }, + ["images/include external"] = { + details = [[ +\[pgf:includeexternalkey\] This key constitutes the public interface to +exchange the `\includegraphics` command used for the image inclusion. + +Redefining this key allows to provide bounding box or viewport options: + + \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}} + +Do not forget the `.code` here which redefines the command. + +One application could be image externalization and bounding box +restrictions: As far as I know, a `.pdf` graphics with restricted +bounding box is always cropped (which is not always desired). One +solution could be to use `latex` and `dvips` which doesn't have this +restriction. Another is to manually provide the `viewport` option as +shown above. + +A possible value for `viewport` can be found in the `.pdf` image, search +for `/MediaBox = [ ... ]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/images/include:external" + }, + ["inner sep"] = { + details = [[ +This style sets both `/pgf/inner xsep` and `/pgf/inner ysep` to +⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:sep", + meta = "⟨dimension⟩" + }, + ["inner xsep"] = { + details = [[ +This key stores the *recommended* horizontal inner separation between +the label text and the background path. As before, this value is just a +recommendation and a shape may choose to ignore this key. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{inner xsep=1cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:xsep", + meta = "⟨dimension⟩" + }, + ["inner ysep"] = { + details = [[ +Works like `/pgf/inner xsep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/inner:ysep", + meta = "⟨dimension⟩" + }, + ["isosceles triangle apex angle"] = { + details = [[ +Sets the angle of the apex of the isosceles triangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/isosceles:triangle:apex:angle", + meta = "⟨angle⟩" + }, + ["isosceles triangle stretches"] = { + details = [[ +By default ⟨boolean⟩ is `false`. This means, that when applying any +minimum width or minimum height requirements, increasing the height will +increase the width (and vice versa), in order to keep the apex angle the +same. + + \begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}] + \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt, + anchor=left corner, shape border rotate=90}} + \draw[help lines] grid(4,2); + \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{ + \node[paint=\c, minimum height=\a cm] at (0,0) {}; + \node[paint=\c, minimum width=\a cm] at (2,0) {}; + } + \end{tikzpicture} + +However, by setting ⟨boolean⟩ to `true`, minimum width and height can be +applied independently. + + \begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}] + \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt, + anchor=south, shape border rotate=90, isosceles triangle stretches}} + \draw[help lines] grid(4,2); + \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{ + \node[paint=\c, minimum height=\a cm, minimum width=1.5cm] at (0.75,0) {}; + \node[paint=\c, minimum width=\a cm, minimum height=1.5cm] at (3,0) {}; + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/isosceles:triangle:stretches", + meta = "⟨boolean⟩" + }, + ["key filter handlers/append filtered to"] = { + details = [[ +Install this filter handler to append any unprocessed options to macro +`{macro}`. + + \pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} + \def\remainingoptions{} + \pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, + /my group/B=b, /my group/C=c, /tikz/color=blue} + + Remaining options: `\remainingoptions'. + +This example uses the same keys as defined in the intro section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/append:filtered:to", + meta = "{macro}" + }, + ["key filter handlers/ignore"] = { + details = [[ +Install this filter handler if you simply want to ignore any unprocessed +option. This is the default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/ignore" + }, + ["key filter handlers/log"] = { + details = [[ +This key filter handler writes messages for any unprocessed option to +your logfile (and terminal). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filter:handlers/log" + }, + ["key filters/active families"] = { + details = [[ +Install this key filter if `\pgfkeysfiltered` should only process +activated families. If a key does not belong to any family, it is not +processed. If a key is completely unknown within the default path, the +normal 'unknown' handlers of `\pgfkeys` are invoked. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families" + }, + ["key filters/active families and known"] = { + details = [[ +A fast alias for + +`/pgf/key filters/active families or no family=` + +`{/pgf/keys filters/false}` + +`{/pgf/keys filters/false}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:and:known" + }, + ["key filters/active families or descendants of"] = { + details = [[ +A fast alias for + +`/pgf/key filters/active families or no family=` + +`{/pgf/keys filters/is descendant of=``{path prefix}``}` + +`{/pgf/keys filters/false}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:descendants:of", + meta = "{path prefix}" + }, + ["key filters/active families or no family"] = { + details = [[ +This key filter configures `\pgfkeysfiltered` to work as follows. + +1. If the current key belongs to a family, set + `\ifpgfkeysfiltercontinue` to true if and only if its family is + active. + +2. If the current key does *not* belong to a family, assign + `\ifpgfkeysfiltercontinue` as result of `{key filter 1}`. + +3. If the current key is unknown within the default path, assign + `\ifpgfkeysfiltercontinue` as result of `{key filter 2}`. + +The arguments `{key filter 1}` and `{key filter 2}` are other key +filters (possibly with options) and allow fine-grained control over the +filtering process. + + \pgfkeysinstallkeyfilter + {/pgf/key filters/active families or no family} + {{/pgf/key filters/is descendant of=/tikz}% for keys without family + {/pgf/key filters/false}% for unknown keys + }% + +This key filter will return true for any option with active family. If +an option has no family, the return value is true if and only if it +belongs to `/tikz`. If the option is unknown, the return value is +`false` and unknown handlers won't be called. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:no:family", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/active families or no family DEBUG"] = { + details = [[ +A variant of `active families or no family` which protocols each action +on your terminal (log-file). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/active:families:or:no:family:DEBUG", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/and"] = { + details = [[ +This key filter returns true if and only if both, `{key filter 1}` and +`{key filter 2}` return true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/and", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/defined"] = { + details = [[ +This key filter returns false if the current key is unknown, which +avoids calling the unknown handlers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/defined" + }, + ["key filters/equals"] = { + details = [[ +Install this key filter to process only the fully qualified option +`{full key}`. The filter returns true for any unknown key or if the key +equals `{full key}`. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/B/.code={(B:#1)}, + /pgf/key filters/equals/.install key filter=/group 1/A} + \pgfqkeysfiltered{/group 1}{A=a,B=b} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/equals", + meta = "{full key}" + }, + ["key filters/false"] = { + details = [[ +This key filter returns always false (including unknown keys). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/false" + }, + ["key filters/is descendant of"] = { + details = [[ +Install this key filter to process only options belonging to the key +tree ⟨path⟩. It returns true for every key whose key path is equal to +⟨path⟩. It also returns true for any unknown key, that means unknown +keys are processed using the standard unknown handlers of PGF. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/foo/bar/B/.code={(B:#1)}, + /group 2/C/.code={(C:#1)}, + /pgf/key filters/is descendant of/.install key filter=/group 1} + \pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/is:descendant:of", + meta = "{path}" + }, + ["key filters/not"] = { + details = [[ +This key filter logically inverts the result of `{key filter}`. + + \pgfkeys{ + /group 1/A/.code={(A:#1)}, + /group 1/foo/bar/B/.code={(B:#1)}, + /group 2/C/.code={(C:#1)}, + /pgf/key filters/not/.install key filter= + {/pgf/key filters/is descendant of=/group 1}} + \pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} + +Please note that unknown keys will be handed to the usual unknown +handlers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/not", + meta = "{key filter}" + }, + ["key filters/or"] = { + details = [[ +This key filter returns true if one of `{key filter 1}` and +`{key filter 2}` returns true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/or", + meta = "{key filter 1}{key filter 2}" + }, + ["key filters/true"] = { + details = [[ +This key filter returns always true. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/key:filters/true" + }, + ["kite lower vertex angle"] = { + details = [[ +Sets the lower internal angle of the kite. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:lower:vertex:angle", + meta = "⟨angle⟩" + }, + ["kite upper vertex angle"] = { + details = [[ +Sets the upper internal angle of the kite. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:upper:vertex:angle", + meta = "⟨angle⟩" + }, + ["kite vertex angles"] = { + details = [[ +This key sets the keys for both the upper and lower vertex angles (it +stores no value itself). ⟨angle specification⟩ can be pair of angles in +the form ⟨upper angle⟩ `and` ⟨lower angle⟩, or a single angle. In this +latter case, both the upper and lower vertex angles will be the same. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/kite:vertex:angles", + meta = "⟨angle specification⟩" + }, + ["l-system"] = { + details = [[ +A more compact version of the previous key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/l-system", + meta = "{keys}" + }, + ["lindenmayer system"] = { + details = [[ +This key changes the key path to `/pgf/lindenmayer systems` and executes +⟨keys⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system", + meta = "{keys}" + }, + ["lindenmayer system/anchor"] = { + details = [[ +Be default, when this key is not used, the L-system will start from the +last specified coordinate. By using this key, the L-system will be +placed inside a special (rectangle) node which can be positioned using +⟨anchor⟩. + + \begin{tikzpicture}[l-system={step=1.75pt, order=5, angle=60}] + \pgfdeclarelindenmayersystem{Sierpinski triangle}{ + \symbol{X}{\pgflsystemdrawforward} + \symbol{Y}{\pgflsystemdrawforward} + \rule{X -> Y-X-Y} + \rule{Y -> X+Y+X} + } + \draw [help lines] grid (3,2); + \draw [red] (0,0) l-system + [l-system={Sierpinski triangle, axiom=+++X, anchor=south west}]; + \draw [blue] (3,2) l-system + [l-system={Sierpinski triangle, axiom=X, anchor=north east}]; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/anchor", + meta = "⟨anchor⟩" + }, + ["lindenmayer system/axiom"] = { + details = [[ +Sets the axiom (or input string) for the L-system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/axiom", + meta = "{string}" + }, + ["lindenmayer system/left angle"] = { + details = [[ +This key sets the angle through which the L-system turns when it turns +left. The value is stored in the TeX macro `\pgflsystemrleftangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/left:angle", + meta = "⟨angle⟩" + }, + ["lindenmayer system/name"] = { + details = [[ +Sets the name for the L-system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/name", + meta = "{name}" + }, + ["lindenmayer system/order"] = { + details = [[ +Sets the number of iterations the L-system will perform. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/order", + meta = "{integer}" + }, + ["lindenmayer system/randomize angle percent"] = { + details = [[ +If the angles are to be randomized, this key specifies by how much. The +value is stored in the TeX macro `\pgflsystemrandomizeanglepercent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/randomize:angle:percent", + meta = "⟨percentage⟩" + }, + ["lindenmayer system/randomize step percent"] = { + details = [[ +If the step is to be randomized, this key specifies by how much. The +value is stored in the TeX macro `\pgflsystemrandomizesteppercent`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/randomize:step:percent", + meta = "⟨percentage⟩" + }, + ["lindenmayer system/right angle"] = { + details = [[ +This key sets the angle through which the L-system turns when it turns +right. The value is stored in the TeX macro `\pgflsystemrrightangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/right:angle", + meta = "⟨angle⟩" + }, + ["lindenmayer system/rule set"] = { + details = [[ +This key allows an (anonymous) L-system to be declared "on-line". There +is, however, a restriction that only the default symbols can be used for +drawing (empty symbols can still be used to control the growth of the +system). The rules in ⟨list⟩ should be separated by commas. + + \tikz[rotate=65]\draw [green!60!black] l-system + [l-system={rule set={F -> F[+F]F[-F]}, axiom=F, order=4, angle=25,step=3pt}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/rule:set", + meta = "{list}" + }, + ["lindenmayer system/step"] = { + details = [[ +How far the L-system moves forward if required. This key sets the TeX +dimension `\pgflsystemstep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/lindenmayer:system/step", + meta = "⟨length⟩" + }, + ["local bounding box"] = { + details = [[ +This defines a new node ⟨node name⟩ whose size is the bounding box +around all objects in the current scope starting at the position where +this option was given. After the end of the scope, the ⟨node name⟩ is +still available. You can use this option to keep track of the size of a +certain area. Note that excessive use of this option (keeping track of +dozens of bounding boxes at the same time) will slow things down. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + { [local bounding box=outer box] + \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5); + } + \draw (outer box.south west) rectangle (outer box.north east); + \draw[red] (inner box.south west) rectangle (inner box.north east); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/local:bounding:box", + meta = "⟨node name⟩" + }, + ["logic gate IEC symbol align"] = { + details = [[ +Set the alignment of the logic gate symbol (in TikZ, when the +`use IEC style logic gates` key has been used, `IEC` can be omitted). +The specification in ⟨align⟩ is a comma separated list from `top`, +`bottom`, `left` or `right`. The distance between the border of the node +and the outer edge of the symbol is determined by the values of the +`inner xsep` and `inner ysep`. + + \begin{tikzpicture}[minimum size=1cm, use IEC style logic gates] + \tikzset{every node/.style={nor gate, draw}} + \node (A) at (0,1.5) {}; + \node [logic gate symbol align={bottom, right}] (B) at (0,0) {}; + \foreach \g in {A, B}{ + \foreach \i in {1,2} + \draw ([xshift=-0.5cm]\g.input \i) -- (\g.input \i); + \draw (\g.output) -- ([xshift=0.5cm]\g.output); + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:IEC:symbol:align", + meta = "⟨align⟩" + }, + ["logic gate IEC symbol color"] = { + details = [[ +This key sets the color for all symbols simultaneously. This color can +be overridden on a case by case basis by specifying a color when setting +the symbol text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:IEC:symbol:color", + meta = "⟨color⟩" + }, + ["logic gate anchors use bounding box"] = { + details = [[ +When set to `true` this key will ensure that the compass point anchors +use the bounding rectangle of the main shape, which, ignore any inverted +inputs or outputs, but includes any `outer sep`. This *only* affects the +compass point anchors and is not set on a shape by shape basis: whether +the bounding box is used is determined by value of this key when the +anchor is accessed. + + \begin{tikzpicture}[minimum height=1.5cm] + \node[xnor gate US, draw, gray!50,line width=2pt] (A) {}; + \foreach \x/\y/\z in {false/blue/1pt, true/red/2pt} + \foreach \a in {north, south, east, west, north east, + south east, north west, south west} + \draw[logic gate anchors use bounding box=\x, color=\y] + (A.\a) circle(\z); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:anchors:use:bounding:box", + meta = "⟨boolean⟩" + }, + ["logic gate input sep"] = { + details = [[ +Set the distance between the *centers* of the inputs to the logic gate. + + \begin{tikzpicture}[minimum size=0.75cm] + \draw [help lines] grid (3,2); + \tikzset{every node/.style={shape=and gate IEC, draw, logic gate inputs=ini}} + \node[logic gate input sep=0.33333cm] at (1,1)(A) {A}; + \node[logic gate input sep=0.5cm] at (3,1) (B) {B}; + \foreach \a in {1,...,3} + \draw (A.input \a -| 0,0) -- (A.input \a) + (B.input \a -| 2,0) -- (B.input \a); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:input:sep", + meta = "⟨length⟩" + }, + ["logic gate inputs"] = { + details = [[ +\[logic-gate-inputs\] Specify the inputs for the logic gate. The keyword +`inverted` indicates an inverted input which will mean PGF will draw a +circle attached to the main shape of the logic gate. Any keyword that is +not `inverted` will be treated as a "normal" or "non-inverted" input +(however, for readability, you may wish to use `normal` or +`non-inverted`), and PGF will not draw the circle. In both cases the +anchors for the inputs will be set up appropriately, numbered from top +to bottom `input 1`, `input 2`, ...and so on. If the gate only supports +one input the anchor is simply called `input` with no numerical index. + + \begin{tikzpicture}[minimum height=0.75cm] + \node[and gate IEC, draw, logic gate inputs={inverted, normal, inverted}] + (A) {}; + \foreach \a in {1,...,3} + \draw (A.input \a -| -1,0) -- (A.input \a); + \draw (A.output) -- ([xshift=0.5cm]A.output); + \end{tikzpicture} + +For multiple inputs it may be somewhat unwieldy to specify a long list, +thus, the following "shorthand" is permitted (this is an extension of +ideas due to Jürgen Werber and Christoph Bartoschek): Using `i` for +inverted and `n` for normal inputs, ⟨input list⟩ can be specified +*without the commas*. So, for example, `ini` is equivalent to +`inverted, normal, inverted`. + + \begin{tikzpicture}[minimum height=0.75cm] + \node[or gate US, draw,logic gate inputs=inini] (A) {}; + \foreach \a in {1,...,5} + \draw (A.input \a -| -1,0) -- (A.input \a); + \draw (A.output) -- ([xshift=0.5cm]A.output); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:inputs", + meta = "⟨input list⟩" + }, + ["logic gate inverted radius"] = { + details = [[ +Set the radius of the circle that is used to indicate inverted inputs. +This is also the radius of the circle used for the inverted output of +the `nand`, `nor`, `xnor` and `not` gates. + + \begin{tikzpicture}[minimum height=0.75cm] + \tikzset{every node/.style={shape=nand gate CDH, draw, logic gate inputs=ii}} + \node[logic gate inverted radius=2pt] {A}; + \node[logic gate inverted radius=4pt] at (0,-1) {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/logic:gate:inverted:radius", + meta = "⟨length⟩" + }, + ["magnetic tape tail"] = { + details = [[ +This key sets the thickness of the 'tail' to be ⟨proportion⟩ times the +radius of the shape. The ⟨proportion⟩ should be between `0.0` and `1.0`. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnetic:tape:tail", + meta = "⟨proportion⟩" + }, + ["magnetic tape tail extend"] = { + details = [[ +This key sets how far the tail extends beyond the radius of the tape. +Negative values will be ignored. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnetic:tape:tail:extend", + meta = "⟨distance⟩" + }, + ["magnifying glass handle angle aspect"] = { + details = [[ +The length of the handle as a multiple of the circle radius. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnifying:glass:handle:angle:aspect", + meta = "⟨factor⟩" + }, + ["magnifying glass handle angle fill"] = { + details = [[ +The angle of the handle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/magnifying:glass:handle:angle:fill", + meta = "⟨degree⟩" + }, + ["mark color"] = { + details = [[ +Defines the additional fill color for the `halfcircle`, `halfcircle*`, +`halfdiamond*` and `halfsquare*` markers. An empty value uses `white` +(which is the initial configuration). The special value `none` disables +filling of the respective parts. + +Note that `halfsquare` will be filled with `mark color`, and the starred +variant `halfsquare*` will be filled half with `mark color` and half +with the actual `fill` color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/mark:color", + meta = "{color}" + }, + ["meta-decoration automaton/next state"] = { + details = [[ +After the code for a state has been executed, a state switch to ⟨new +state⟩ is performed. If this option is not given, the next state is the +same as the current state. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/next:state", + meta = "⟨new state⟩" + }, + ["meta-decoration automaton/switch if less than"] = { + details = [[ +This causes PGF to check whether the remaining distance to the end of +the input path is less than ⟨dimension⟩, and, if so, to immediately +switch to the state ⟨new state⟩. When this key is evaluated, the macro +`\pgfmetadecoratedpathlength` will be defined as the total length of the +decoration path, allowing for values such as +`\pgfmetadecoratedpathlength/8`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/switch:if:less:than", + meta = "⟨dimension⟩ to ⟨new state⟩" + }, + ["meta-decoration automaton/width"] = { + details = [[ +As always, this option will cause an immediate switch to the state +`final` if the remaining distance on the input path is less than +⟨dimension⟩. + +Otherwise, this option tells PGF the width of the "meta-segment", that +is, the length of the sub-input-path which the decoration automaton +specified in ⟨code⟩ will decorate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/meta-decoration:automaton/width", + meta = "⟨dimension⟩" + }, + ["minimum height"] = { + details = [[ +Works like `/pgf/minimum width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:height", + meta = "⟨dimension⟩" + }, + ["minimum size"] = { + details = [[ +This style both `/pgf/minimum width` and `/pgf/minimum height` to +⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:size", + meta = "⟨dimension⟩" + }, + ["minimum width"] = { + details = [[ +This key stores the *recommended* minimum width of a shape. Thus, when a +shape is drawn and when the shape's width would be smaller than +⟨dimension⟩, the shape's width is enlarged by adding some empty space. + +Note that this value is just a recommendation. A shape may choose to +ignore this key. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{minimum width=3cm} + \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/minimum:width", + meta = "⟨dimension⟩" + }, + ["nand gate IEC symbol"] = { + details = [[ +Set the symbol for the `nand gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `nand gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/nand:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["nor gate IEC symbol"] = { + details = [[ +Set the symbol for the `nor gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `nor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/nor:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["not gate IEC symbol"] = { + details = [[ +Set the symbol for the `not gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `not gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/not:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["number format/1000 sep"] = { + details = [[ +Just another name for `set thousands separator`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/1000:sep", + meta = "{text}" + }, + ["number format/1000 sep in fractionals"] = { + details = [[ +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. + + \pgfkeys{/pgf/number format/.cd, + fixed, + precision=999, + set thousands separator={\,}, + 1000 sep in fractionals, + } + \pgfmathprintnumber{1234.1234567} + + \pgfkeys{/pgf/number format/.cd, + fixed,fixed zerofill, + precision=9, + set thousands separator={\,}, + 1000 sep in fractionals, + } + \pgfmathprintnumber{1234.1234567} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/1000:sep:in:fractionals", + meta = "{boolean}" + }, + ["number format/\\protect\\atmarktext dec sep mark"] = { + details = [[ +Will be placed right before the place where a decimal separator belongs +to. However, `{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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/\\protect\\atmarktext:dec:sep:mark", + meta = "{text}" + }, + ["number format/\\protect\\atmarktext sci exponent mark"] = { + details = [[ +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! +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/\\protect\\atmarktext:sci:exponent:mark", + meta = "{text}" + }, + ["number format/assume math mode"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/assume:math:mode", + meta = "{boolean}" + }, + ["number format/dec sep"] = { + details = [[ +Just another name for `set decimal separator`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/dec:sep", + meta = "{text}" + }, + ["number format/every relative"] = { + details = [[ +A style which configures how the `relative` method finally displays its +results. + +The initial configuration is + + \pgfkeys{/pgf/number format/every relative/.style=std} + +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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/every:relative" + }, + ["number format/fixed"] = { + details = [[ +Configures `\pgfmathprintnumber` to round the number to a fixed number +of digits after the period, discarding any trailing zeros. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the appearance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/fixed" + }, + ["number format/fixed zerofill"] = { + details = [[ +Enables or disables zero filling for any number drawn in fixed point +format. + + \pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +This key affects numbers drawn with `fixed` or `std` styles (the latter +only if no scientific format is chosen). + + \pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-05}\hspace{1em} + \pgfmathprintnumber{1}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the appearance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/fixed:zerofill", + meta = "{boolean}" + }, + ["number format/frac"] = { + details = [[ +Displays numbers as fractionals. + + \pgfkeys{/pgf/number format/frac} + \pgfmathprintnumber{0.333333333333333}\hspace{1em} + \pgfmathprintnumber{0.5}\hspace{1em} + \pgfmathprintnumber{2.133333333333325e-01}\hspace{1em} + \pgfmathprintnumber{0.12}\hspace{1em} + \pgfmathprintnumber{2.666666666666646e-02}\hspace{1em} + \pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em} + \pgfmathprintnumber{7.200000000000000e-01}\hspace{1em} + \pgfmathprintnumber{6.666666666666667e-02}\hspace{1em} + \pgfmathprintnumber{1.333333333333333e-01}\hspace{1em} + \pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em} + \pgfmathprintnumber{3.3333333}\hspace{1em} + \pgfmathprintnumber{1.2345}\hspace{1em} + \pgfmathprintnumber{1}\hspace{1em} + \pgfmathprintnumber{-6} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac" + }, + ["number format/frac TeX"] = { + details = [[ +Allows to use a different implementation for `\frac` inside of the +`frac` display type. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:TeX", + meta = "{\\macro}" + }, + ["number format/frac denom"] = { + details = [[ +Allows to provide a custom denominator for `frac`. + + \pgfkeys{/pgf/number format/.cd,frac, frac denom=10} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{0.5}\hspace{1em} + \pgfmathprintnumber{1.2}\hspace{1em} + \pgfmathprintnumber{-0.6}\hspace{1em} + \pgfmathprintnumber{-1.4}\hspace{1em} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:denom", + meta = "⟨int⟩" + }, + ["number format/frac shift"] = { + details = [[ +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. + +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$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:shift", + meta = "{integer}" + }, + ["number format/frac whole"] = { + details = [[ +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. + + \pgfkeys{/pgf/number format/.cd,frac, frac whole=false} + \pgfmathprintnumber{20.1}\hspace{1em} + \pgfmathprintnumber{5.5}\hspace{1em} + \pgfmathprintnumber{1.2}\hspace{1em} + \pgfmathprintnumber{-5.6}\hspace{1em} + \pgfmathprintnumber{-1.4}\hspace{1em} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/frac:whole", + meta = "⟨true,false⟩" + }, + ["number format/int detect"] = { + details = [[ +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. + + \pgfkeys{/pgf/number format/.cd,int detect,precision=2} + \pgfmathprintnumber{15}\hspace{1em} + \pgfmathprintnumber{20}\hspace{1em} + \pgfmathprintnumber{20.4}\hspace{1em} + \pgfmathprintnumber{0.01}\hspace{1em} + \pgfmathprintnumber{0} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/int:detect" + }, + ["number format/int trunc"] = { + details = [[ +Truncates every number to integers (discards any digit after the +period). + + \pgfkeys{/pgf/number format/.cd,int trunc} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/int:trunc" + }, + ["number format/min exponent for 1000 sep"] = { + details = [[ +Defines the smallest exponent in scientific notation which is required +to draw thousand separators. The exponent is the number of digits minus +one, so $⟨number⟩=4$ will use thousand separators starting with $1e4 = + 10000$. + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=0} + \pgfmathprintnumber{5000}; \pgfmathprintnumber{1000000} + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=4} + \pgfmathprintnumber{1000}; \pgfmathprintnumber{5000} + + \pgfkeys{/pgf/number format/.cd, + int detect, + 1000 sep={\,}, + min exponent for 1000 sep=4} + \pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000} + +A value of `0` disables this feature (negative values are ignored). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/min:exponent:for:1000:sep", + meta = "{number}" + }, + ["number format/precision"] = { + details = [[ +Sets the desired rounding precision for any display operation. For +scientific format, this affects the mantissa. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/precision", + meta = "{number}" + }, + ["number format/print sign"] = { + details = [[ +A style which is simply an alias for `showpos=``{boolean}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/print:sign", + meta = "{boolean}" + }, + ["number format/read comma as period"] = { + details = [[ +This is one of the few keys which allows to customize the number parser. +If this switch is turned on, a comma is read just as a period. + + \pgfkeys{/pgf/number format/read comma as period} + \pgfmathprintnumber{1234,56} + +This is typically undesired as it can cause side-effects with math +parsing instructions. However, it is supported to format input numbers +or input tables. Consider `use comma` to typeset the result with a comma +as well. + + \pgfkeys{/pgf/number format/.cd, + read comma as period, + use comma} + \pgfmathprintnumber{1234,56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/read:comma:as:period", + meta = "⟨true,false⟩" + }, + ["number format/relative style"] = { + details = [[ +The same as `every relative/.append style=``{options}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/relative:style", + meta = "{options}" + }, + ["number format/retain unit mantissa"] = { + details = [[ +Allows to omit a unit mantissa. + + \pgfkeys{ + /pgf/number format/.cd, + sci, retain unit mantissa=false} + \pgfmathprintnumber{10.5}; + \pgfmathprintnumber{10}; + \pgfmathprintnumber{1010}; + \pgfmathprintnumber[precision=1]{-1010}; + +The feature is applied after rounding to the desired precision: if the +remaining mantissa is equal to $1$, it will be omitted. It applies to +all styles involving the scientific format (including `std`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/retain:unit:mantissa", + meta = "⟨true,false⟩" + }, + ["number format/sci"] = { + details = [[ +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). + + \pgfkeys{/pgf/number format/.cd,sci,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +See section ?? for how to change the exponential display style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci" + }, + ["number format/sci 10\\textasciicircum e"] = { + details = [[ +The same as '`sci 10e`'. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:10\\textasciicircum:e" + }, + ["number format/sci 10e"] = { + details = [[ +Uses $m \cdot 10^e$ for any number displayed in scientific format. + + \pgfkeys{/pgf/number format/.cd,sci,sci 10e} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:10e" + }, + ["number format/sci E"] = { + details = [[ +The same with an uppercase '`E`'. + + \pgfkeys{/pgf/number format/.cd,sci,sci E} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:E" + }, + ["number format/sci e"] = { + details = [[ +Uses the '$1e{+}0$' format which is generated by common scientific tools +for any number displayed in scientific format. + + \pgfkeys{/pgf/number format/.cd,sci,sci e} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:e" + }, + ["number format/sci generic"] = { + details = [[ +Allows to define an own number style for the scientific format. Here, +⟨keys⟩ can be one of the following choices (omit the long key prefix): + + \pgfkeys{ + /pgf/number format/.cd, + sci, + sci generic={mantissa sep=\times,exponent={10^{#1}}}} + \pgfmathprintnumber{12.345}; + \pgfmathprintnumber{0.00012345} + +The ⟨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 *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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic", + meta = "{keys}" + }, + ["number format/sci generic/exponent"] = { + details = [[ +Provides text to format the exponent. The actual exponent is available +as argument `# 1` (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic/exponent", + meta = "{text}" + }, + ["number format/sci generic/mantissa sep"] = { + details = [[ +Provides the separator between a mantissa and the exponent. It might be +`\cdot`, for example, +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:generic/mantissa:sep", + meta = "{text}" + }, + ["number format/sci precision"] = { + details = [[ +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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:precision", + meta = "⟨number or empty⟩" + }, + ["number format/sci subscript"] = { + details = [[ +Typesets the exponent as subscript for any number displayed in +scientific format. This style requires very little space. + + \pgfkeys{/pgf/number format/.cd,sci,sci subscript} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:subscript" + }, + ["number format/sci superscript"] = { + details = [[ +Typesets the exponent as superscript for any number displayed in +scientific format. This style requires very little space. + + \pgfkeys{/pgf/number format/.cd,sci,sci superscript} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:superscript" + }, + ["number format/sci zerofill"] = { + details = [[ +Enables or disables zero filling for any number drawn in scientific +format. + + \pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2} + \pgfmathprintnumber{4.568}\hspace{1em} + \pgfmathprintnumber{5e-04}\hspace{1em} + \pgfmathprintnumber{0.1}\hspace{1em} + \pgfmathprintnumber{24415.98123}\hspace{1em} + \pgfmathprintnumber{123456.12345} + +As with `fixed zerofill`, this option does only affect numbers drawn in +`sci` format (or `std` if the scientific format is chosen). + +See section ?? for how to change the exponential display style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/sci:zerofill", + meta = "{boolean}" + }, + ["number format/set decimal separator"] = { + details = [[ +Assigns `{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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/set:decimal:separator", + meta = "{text}" + }, + ["number format/set thousands separator"] = { + details = [[ +Assigns `{text}` as thousands separator for any fixed point numbers +(including the mantissa in sci format). + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} + \pgfmathprintnumber{1234.56} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={.}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={,}} + \pgfmathprintnumber{1234567890} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill, + precision=2, + set thousands separator={{{,}}}} + \pgfmathprintnumber{1234567890} + +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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/set:thousands:separator", + meta = "{text}" + }, + ["number format/showpos"] = { + details = [[ +Enables or disables the display of plus signs for non-negative numbers. + + \pgfkeys{/pgf/number format/showpos} + \pgfmathprintnumber{12.345} + + \pgfkeys{/pgf/number format/showpos=false} + \pgfmathprintnumber{12.345} + + \pgfkeys{/pgf/number format/.cd,showpos,sci} + \pgfmathprintnumber{12.345} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/showpos", + meta = "{boolean}" + }, + ["number format/skip 0."] = { + details = [[ +Configures whether numbers like $0.1$ shall be typeset as $.1$ or not. + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.} + \pgfmathprintnumber{0.56} + + \pgfkeys{/pgf/number format/.cd, + fixed, + fixed zerofill,precision=2, + skip 0.=false} + \pgfmathprintnumber{0.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/skip:0.", + meta = "{boolean}" + }, + ["number format/use comma"] = { + details = [[ +A predefined style which installs commas "`,`" as decimal separators and +periods "`.`" as thousands separators. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} + \pgfmathprintnumber{12.3456} + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma} + \pgfmathprintnumber{1234.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/use:comma" + }, + ["number format/use period"] = { + details = [[ +A predefined style which installs periods "`.`" as decimal separators +and commas "`,`" as thousands separators. This style is the default. + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} + \pgfmathprintnumber{12.3456} + + \pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period} + \pgfmathprintnumber{1234.56} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/use:period" + }, + ["number format/verbatim"] = { + details = [[ +A style which configures the number printer to produce verbatim text +output, i.e., it doesn't contain TeX macros. + + \pgfkeys{ + /pgf/fpu, + /pgf/number format/.cd, + sci, + verbatim} + \pgfmathprintnumber{12.345}; + \pgfmathprintnumber{0.00012345}; + \pgfmathparse{exp(15)} + \pgfmathprintnumber{\pgfmathresult} + +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 intend to write output files. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/verbatim" + }, + ["number format/zerofill"] = { + details = [[ +Sets both `fixed zerofill` and `sci zerofill` at once. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/number:format/zerofill", + meta = "{boolean}" + }, + ["or gate IEC symbol"] = { + details = [[ +Set the symbol for the `or gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `or gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/or:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["outer sep"] = { + details = [[ +This option adds an additional (invisible) separation space of +⟨dimension⟩ outside the background path. The main effect of this option +is that all anchors will move a little "to the outside". + +For those familiar with CSS, this is same as *margin*. + +The default for this option is half the line width. When the default is +used and when the background path is draw, the anchors will lie exactly +on the "outside border" of the path (not on the path itself). + + \begin{tikzpicture} + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \draw[->] (1,-1) -- (s); + \end{tikzpicture} + +As the above example demonstrates, the standard settings for the outer +sep are not always "correct". First, when a shape is filled, but not +drawn, the outer sep should actually be `0`. Second, when a node is +scaled, for instance by a factor of 5, the outer separation also gets +scaled by a factor of 5, while the line width stays at its original +width; again causing problems. + +In such cases, you can say `outer sep=auto` to make TikZ *try* to +compensate for the effects described above. This is done by, firstly, +setting the outer sep to `0` when no drawing is done and, secondly, +setting the outer separations to half the line width (as before) times +two adjustment factors, one for the horizontal separations and one for +the vertical separations (see Section ?? for details on these factors). +Note, however, that these factors can compensate only for +transformations that are either scalings plus rotations or scalings with +different magnitudes in the horizontal and the vertical direction. If +you apply slanting, the factors will only approximate the correct +values. + +In general, it is a good idea to say `outer sep=auto` at some early +stage. It is not the default mainly for compatibility with earlier +versions. + + \begin{tikzpicture}[outer sep=auto] + \draw[line width=5pt] + (0,0) node[fill=yellow!80!black] (f) {filled} + (2,0) node[draw] (d) {drawn} + (1,-2) node[draw,scale=2] (s) {scaled}; + + \draw[->] (1,-1) -- (f); + \draw[->] (1,-1) -- (d); + \draw[->] (1,-1) -- (s); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:sep", + meta = "⟨dimension or ``auto''⟩" + }, + ["outer xsep"] = { + details = [[ +This key stores the recommended horizontal separation between the +background path and the "outer anchors". For example, if ⟨dimension⟩ is +`1cm` then the `east` anchor will be 1cm to the right of the right +border of the background path. As before, this value is just a +recommendation. + + \begin{tikzpicture} + \draw[help lines] (-2,0) grid (2,1); + + \pgfset{outer xsep=.5cm} + \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}} + + \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt} + \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt} + \pgfusepath{fill} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:xsep", + meta = "⟨dimension⟩" + }, + ["outer ysep"] = { + details = [[ +Works like `/pgf/outer xsep`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/outer:ysep", + meta = "⟨dimension⟩" + }, + ["pattern keys/angle"] = { + details = [[ +By default the stars are arranged on a regular grid. The whole pattern +is rotated by this angle. The rotation angle is measured in the +mathematically positive sense. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/angle" + }, + ["pattern keys/distance"] = { + details = [[ +Distance between stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/distance" + }, + ["pattern keys/line width"] = { + details = [[ +Thickness of the lines. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/line:width" + }, + ["pattern keys/points"] = { + details = [[ +Number of pointy ends of the stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/points" + }, + ["pattern keys/radius"] = { + details = [[ +Outer radius of the enclosing circle of the stars. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/radius" + }, + ["pattern keys/xshift"] = { + details = [[ +Shifts the whole pattern in $x$-direction (before applying the +rotation). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/xshift" + }, + ["pattern keys/yshift"] = { + details = [[ +Shifts the whole pattern in $y$-direction (before applying the +rotation). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/pattern:keys/yshift" + }, + ["patterns/bottom left"] = { + details = [[ +Bottom left corner of the pattern's bounding box, +e.g. `\pgfqpoint{-.1pt}{-.1pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/bottom:left", + meta = "⟨pgfpoint⟩" + }, + ["patterns/code"] = { + details = [[ +The code should be PGF code that can be protocolled. It should not +contain any color code or nodes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/code", + meta = "⟨code⟩" + }, + ["patterns/defaults"] = { + details = [[ +This list holds default assignments to the parameters passed to the +pattern. The default keys can then be found under the +`/pgf/pattern keys/` prefix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/defaults", + meta = "⟨comma separated list⟩" + }, + ["patterns/name"] = { + details = [[ +The name of the pattern by which it can be used later on. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/name", + meta = "⟨name⟩" + }, + ["patterns/parameters"] = { + details = [[ +A list of parameters that are passed to the pattern. This is usually a +list of TeX macros. It is very important that these macros are fully +expandable because the values they hold are being used for deduplication +in the PDF file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/parameters", + meta = "⟨comma separated list⟩" + }, + ["patterns/set up code"] = { + details = [[ +This code can be set if parameters have to be preprocessed before the +actual pattern code can be run. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/set:up:code", + meta = "⟨code⟩" + }, + ["patterns/tile size"] = { + details = [[ +Width and height of a single of the pattern as a PGF point +specification, i.e. the $x$ coordinate is the width and the $y$ +specification, i.e. the $x$ coordinate is the width and the $y$ +coordinate is the height, e.g. `\pgfqpoint{3pt}{3pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/tile:size", + meta = "⟨pgfpoint⟩" + }, + ["patterns/tile transformation"] = { + details = [[ +A PGF transformation, e.g. `\pgftransformrotate{30}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/tile:transformation", + meta = "⟨pgftransformation⟩" + }, + ["patterns/top right"] = { + details = [[ +Top right corner of the pattern's bounding box, +e.g. `\pgfqpoint{3.1pt}{3.1pt}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/top:right", + meta = "⟨pgfpoint⟩" + }, + ["patterns/type"] = { + details = [[ +The type of the pattern maps to what was called "form only" and +"inherently colored" in the language of the normal patterns. The +available choices are: + +- `uncolored` the pattern will obey the surrounding color. + +- `colored` the pattern will have an intrinsic color. + +- `form only` synonym for `uncolored` + +- `inherently colored` synonym for `colored` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/type", + meta = "⟨type⟩" + }, + ["patterns/x"] = { + details = [[ +Unit vector of the coordinate system in the $x$-direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/x", + meta = "⟨dimension⟩" + }, + ["patterns/y"] = { + details = [[ +Unit vector of the coordinate system in the $y$-direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/patterns/y", + meta = "⟨dimension⟩" + }, + ["plot/gnuplot call"] = { + details = [[ +This key can be used to change the way gnuplot is called. + +Some portable MiKTeX distribution needs something like the following. + + \pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/plot/gnuplot:call", + meta = "⟨gnuplot invocation⟩" + }, + ["random starburst"] = { + details = [[ +Sets the seed for the random number generator for creating the +starburst. The maximum value for ⟨integer⟩ is `16383`. If ⟨integer⟩`=0`, +the random number generator will not be used, and the maximum point +height will be used for all outer points. If ⟨integer⟩ is omitted, a +seed will be randomly chosen. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/random:starburst", + meta = "⟨integer⟩" + }, + ["rectangle split allocate boxes"] = { + details = [[ +This key checks if ⟨number⟩ boxes have been allocated, and if 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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:allocate:boxes", + meta = "⟨number⟩" + }, + ["rectangle split draw splits"] = { + details = [[ +Sets whether the line or lines between node parts will be drawn. +Internally, this sets the TeX-if `\ifpgfrectanglesplitdrawsplits` +appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:draw:splits", + meta = "⟨boolean⟩" + }, + ["rectangle split empty part depth"] = { + details = [[ +Sets the default depth for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:depth", + meta = "⟨length⟩" + }, + ["rectangle split empty part height"] = { + details = [[ +Sets the default height for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:height", + meta = "⟨length⟩" + }, + ["rectangle split empty part width"] = { + details = [[ +Sets the default width for a node part box if it is empty and empty +parts are not ignored. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:empty:part:width", + meta = "⟨length⟩" + }, + ["rectangle split horizontal"] = { + details = [[ +This key determines whether the rectangle is split horizontally or +vertically +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:horizontal", + meta = "⟨boolean⟩" + }, + ["rectangle split ignore empty parts"] = { + details = [[ +When ⟨boolean⟩ is true, PGF will ignore any part that is empty *except +the text part*. This effectively overrides the `rectangle split parts` +key in that, if 3 parts (for example) are specified, but one is empty, +only two will be shown. + + \begin{tikzpicture}[every node/.style={draw, anchor=text, rectangle split, + rectangle split parts=3}] + \node {text \nodepart{second} \nodepart{third}third}; + \node [rectangle split ignore empty parts] at (2,0) + {text \nodepart{second} \nodepart{third}third}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:ignore:empty:parts", + meta = "⟨boolean⟩" + }, + ["rectangle split part align"] = { + details = [[ +Sets the alignment of the boxes inside the node parts. Each item in +⟨list⟩ should be separated by commas (so if there is more than one item +in ⟨list⟩, it must be surrounded by braces). + +When the rectangle is split vertically, the entries in ⟨list⟩ must be +one of `left`, `right`, or `center`. If ⟨list⟩ has less entries than +node parts then the remaining boxes are aligned according to the last +entry in the list. Note that this only aligns the boxes in each part and +*does not* affect the alignment of the contents of the boxes. + + \def\x{one \nodepart{two} 2 \nodepart{three} three \nodepart{four} 4} + \begin{tikzpicture}[ + every node/.style={rectangle split, rectangle split parts=4, + draw} + ] + \node[rectangle split part align={center, left, right}] at (0,0) {\x}; + \node[rectangle split part align={center, left}] at (1.25,0) {\x}; + \node[rectangle split part align={center}] at (2.5,0) {\x}; + \end{tikzpicture} + +When the rectangle is split horizontally, the entries in ⟨list⟩ must be +one of `top`, `bottom`, `center` or `base`. Note that using 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. + + \def\x{\Large w\nodepart{two}x\nodepart{three}\Huge y\nodepart{four}\tiny z} + \begin{tikzpicture}[ + every node/.style={rectangle split, rectangle split parts=4, + draw, rectangle split horizontal} + ] + \node[rectangle split part align={center, top, bottom}] at (0,0) {\x}; + \node[rectangle split part align={center, top}] at (0,-1.25) {\x}; + \node[rectangle split part align={center}] at (0,-2.5) {\x}; + \node[rectangle split part align=base] at (0,-3.75) {\x}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:part:align", + meta = "{⟨list⟩}" + }, + ["rectangle split part fill"] = { + details = [[ +Sets the custom fill color for each node part shape. The items in ⟨list⟩ +should be separated by commas (so if there is more than one item in +⟨list⟩, it must be surrounded by braces). If ⟨list⟩ has less entries +than node 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`. + + \begin{tikzpicture} + \tikzset{every node/.style={rectangle split, draw, minimum width=.5cm}} + \node[rectangle split part fill={red!50, green!50, blue!50, yellow!50}] {}; + \node[rectangle split part fill={red!50, green!50, blue!50}] at (0.75,0) {}; + \node[rectangle split part fill={red!50, green!50}] at (1.5,0) {}; + \node[rectangle split part fill={red!50}] at (2.25,0) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:part:fill", + meta = "{⟨list⟩}" + }, + ["rectangle split parts"] = { + details = [[ +Split the rectangle into ⟨number⟩ parts, which should be in the range +`1` to `20`. If more than four parts are needed, the boxes should be +allocated in advance as described above. + + \begin{tikzpicture}[every text node part/.style={align=center}] + \node[rectangle split, rectangle split parts=3, draw, text width=2.75cm] + {Student + \nodepart{two} + age:int \\ + name:String + \nodepart{three} + getAge():int \\ + getName():String}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:parts", + meta = "⟨number⟩" + }, + ["rectangle split use custom fill"] = { + details = [[ +This enables the use of a custom fill for each of the node parts +(including the area covered by the `inner sep`). The background path for +the shape should not be filled (e.g., in TikZ, the `fill` option for the +node must be implicity or explicitly set to `none`). Internally, this +key sets the TeX-if `\ifpgfrectanglesplitusecustomfill` appropriately. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rectangle:split:use:custom:fill", + meta = "⟨boolean⟩" + }, + ["regular polygon sides"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/regular:polygon:sides", + meta = "⟨integer⟩" + }, + ["rounded rectangle arc length"] = { + details = [[ +Sets the length of the arcs for the rounded ends. Recommended values for +⟨angle⟩ are between `90` and `180`. + + \begin{tikzpicture} + \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{ + \node[rounded rectangle arc length=180] {180}; \\ + \node[rounded rectangle arc length=120] {120}; \\ + \node[rounded rectangle arc length=90] {90}; \\}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:arc:length", + meta = "⟨angle⟩" + }, + ["rounded rectangle east arc"] = { + details = [[ +Sets the style of the rounding for the east side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:east:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle left arc"] = { + details = [[ +Alternative key for specifying the west arc. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:left:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle right arc"] = { + details = [[ +Alternative key for specifying the east arc. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:right:arc", + meta = "⟨arc type⟩" + }, + ["rounded rectangle west arc"] = { + details = [[ +Sets the style of the rounding for the left side. The permitted values +for ⟨arc type⟩ are `concave`, `convex`, or `none`. + + \begin{tikzpicture} + \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{ + \node[rounded rectangle west arc=concave] {Concave}; \\ + \node[rounded rectangle west arc=convex] {Convex}; \\ + \node[rounded rectangle left arc=none] {None}; \\}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/rounded:rectangle:west:arc", + meta = "⟨arc type⟩" + }, + ["shape aspect"] = { + details = [[ +Sets a desired aspect ratio for the shape. For the `diamond` shape, this +option sets the ratio between width and height of the shape. + + \begin{tikzpicture} + \draw (0,0) node[shape aspect=1,diamond,draw] {aspect 1}; + \draw (0,-2) node[shape aspect=2,diamond,draw] {aspect 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:aspect", + meta = "⟨aspect ratio⟩" + }, + ["shape border rotate"] = { + details = [[ +Rotates the border of a shape independently of the node contents, but in +addition to any other transformations. If the shape border is not +constructed using the incircle, the rotation will be rounded to the +nearest integer multiple of 90 degrees when the shape is drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:border:rotate", + meta = "⟨angle⟩" + }, + ["shape border uses incircle"] = { + details = [[ +Determines if the border of a shape is constructed using the incircle. +If no value is given ⟨boolean⟩ will take the default value `true`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/shape:border:uses:incircle", + meta = "⟨boolean⟩" + }, + ["signal from"] = { + details = [[ +Sets which sides take an inward pointer (i.e., that points towards the +center of the shape). The possible values for ⟨direction⟩ and ⟨opposite +direction⟩ are the compass point directions `north`, `south`, `east` and +`west` (or `above`, `below`, `right` and `left`). An additional keyword +`nowhere` can be used to reset the sides so they have no pointers. When +used with `signal from` key, this only resets inward pointers; used with +the `signal to` key, it only resets outward pointers. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:from", + meta = "⟨direction⟩ and ⟨opposite direction⟩" + }, + ["signal pointer angle"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:pointer:angle", + meta = "⟨angle⟩" + }, + ["signal to"] = { + details = [[ +Sets which sides take an outward pointer (i.e., that points away from +the shape). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/signal:to", + meta = "⟨direction⟩ and ⟨opposite direction⟩" + }, + ["single arrow head extend"] = { + details = [[ +This sets the distance between the tail of the arrow and the outer end +of the arrow head. This may change if the shape is enlarged to some +minimum width. + + \begin{tikzpicture} + \node[single arrow, draw, single arrow head extend=.5cm, gray!50, rotate=60] + (a) {Arrow}; + \draw[red, |<->|] (a.before tip) -- (a.before head) + node [midway, below, sloped, black] {head extend}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:head:extend", + meta = "⟨length⟩" + }, + ["single arrow head indent"] = { + details = [[ +This moves the point where the arrow head joins the shaft of the arrow +*towards* the arrow tip, by ⟨length⟩. + + \begin{tikzpicture}[every node/.style={single arrow, draw=none, rotate=60}] + \node [fill=red!50] {arrow 1}; + \node [fill=blue!50, single arrow head indent=1ex] at (1.5,0) {arrow 2}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:head:indent", + meta = "⟨length⟩" + }, + ["single arrow tip angle"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/single:arrow:tip:angle", + meta = "⟨angle⟩" + }, + ["star point height"] = { + details = [[ +Sets the height of the star points. This is the distance between the +inner point and outer point radii. If the star is enlarged to some +specified minimum size, the inner radius is increased to maintain the +point height. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:point:height", + meta = "⟨distance⟩" + }, + ["star point ratio"] = { + details = [[ +Sets the ratio between the inner point and outer point radii. If the +star is enlarged to some specified minimum size, the inner radius is +increased to maintain the ratio. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:point:ratio", + meta = "⟨number⟩" + }, + ["star points"] = { + details = [[ +Sets the number of points for the star. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/star:points", + meta = "⟨integer⟩" + }, + ["starburst point height"] = { + details = [[ +Sets the *maximum* distance between the inner point radius and the outer +point radius. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/starburst:point:height", + meta = "⟨length⟩" + }, + ["starburst points"] = { + details = [[ +Sets the number of outer points for the starburst. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/starburst:points", + meta = "⟨integer⟩" + }, + step = { + details = [[ +Sets the horizontal stepping to the $x$-coordinate of ⟨vector⟩ and the +vertical stepping to its $y$-coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/step", + meta = "⟨vector⟩" + }, + stepx = { + details = [[ +The horizontal stepping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/stepx", + meta = "⟨dimension⟩" + }, + stepy = { + details = [[ +The vertical stepping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/stepy", + meta = "⟨dimension⟩" + }, + ["tape bend bottom"] = { + details = [[ +Specifies how the bottom side bends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:bottom", + meta = "⟨bend style⟩" + }, + ["tape bend height"] = { + details = [[ +Sets the total height for a side with a bend. + + \begin{tikzpicture}[>=stealth] + \draw [help lines] grid(3,2); + \node [tape, fill, minimum size=2cm, red!50, tape bend top=none, + tape bend height=1cm] at (1.5,1.5) (t) {}; + \draw [|<->|, blue] (1.5,0) -- (1.5,1) + node [at end, above, black]{tape bend height}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:height", + meta = "⟨length⟩" + }, + ["tape bend top"] = { + details = [[ +Specifies how the top side bends. The ⟨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 the side will first bend inwards and then +bend outwards. The opposite holds true for `out and in`. + + \begin{tikzpicture}[-stealth] + \node[tape, draw, gray, minimum width=2cm](t){Tape}; + \draw [blue]([yshift=5pt] t.north west) -- ([yshift=5pt]t.north east) + node[midway, above, black]{in and out}; + \draw [blue]([yshift=-5pt]t.south east) -- ([yshift=-5pt]t.south west) + node[sloped, allow upside down, midway, above, black]{in and out}; + \end{tikzpicture} + +This might take a bit of getting used to, but just remember that when +you want the bendy sides to be parallel, the sides take the same bend +style. It is possible for the top and bottom sides to take opposite bend +styles, but the author of this shape cannot think of a single use for +such a combination. + + \begin{tikzpicture}[every node/.style={tape, draw}] + \node [tape bend top=out and in, tape bend bottom=out and in] {Parallel}; + \node at (2,0) [tape bend bottom=out and in] {Why?}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tape:bend:top", + meta = "⟨bend style⟩" + }, + ["tex4ht node/class"] = { + details = [[ +This option allows you to give a class name to the node, allowing it to +be styled by a CSS file (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/class", + meta = "⟨class name⟩" + }, + ["tex4ht node/css"] = { + details = [[ +This option allows you to tell the browser what CSS file it should use +to style the display of the node (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/css", + meta = "⟨filename⟩" + }, + ["tex4ht node/escape"] = { + details = [[ +Selects the rendering method for a text node with the tex4ht driver. + +When this key is set to `false`, text is translated into SVG text, which +is somewhat limited: simple characters (letters, numerals, punctuation, +$\sum$, $\int$, ...), subscripts and superscripts (but not +subsubscripts) will display but everything else will be filtered out, +ignored or will produce invalid HTML code (in the worst case). This +means that two kind of texts render reasonably well: + +1. First, plain text without math mode, special characters or anything + else special. + +2. Second, *very* simple mathematical text that contains subscripts or + superscripts. Even then, variables are not correctly set in italics + and, in general, text simple does not look very nice. + +If you use text that contains anything special, even something as simple +as `\textbackslash alpha`, this may corrupt the graphic. + + \tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$}; + +When you write `node[/pgf/tex4ht node/escape=true] {`⟨text⟩`}`, +PGF escapes back to HTML to render the ⟨text⟩. This method produces +valid HTML code in most cases and the support for complicated text nodes +is much better since code that renders well outside a `{pgfpicture}`, +should also render well inside a text node. Another advantage is that +inside text nodes with fixed width, HTML will produce line breaks for +long lines. On the other hand, you need a browser with good 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, PGF 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. + + \tikz \node[draw,/pgf/tex4ht node/escape=true] + {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/escape", + meta = "⟨boolean⟩" + }, + ["tex4ht node/id"] = { + details = [[ +This option allows you to give a unique id to the node, allowing it to +be styled by a CSS file (only with `tex4ht node/escape=true`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tex4ht:node/id", + meta = "⟨id name⟩" + }, + ["text mark"] = { + details = [[ +Changes the text shown by `mark=text`. + +With `/pgf/text mark=m`: + +With `/pgf/text mark=A`: + +There is no limitation about the number of characters or whatever. In +fact, any TeX material can be inserted as `{text}`, including images. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark", + meta = "{text}" + }, + ["text mark as node"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark:as:node", + meta = "{boolean}" + }, + ["text mark style"] = { + details = [[ +Defines a set of options which control the appearance of `mark=text`. + +If `/pgf/text mark as node=false` (the default), `{options}` is provided +as argument to `\pgftext` -- which provides only some basic keys like +`left`, `right`, `top`, `bottom`, `base` and `rotate`. + +If `/pgf/text mark as node=true`, `{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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text:mark:style", + meta = "{options for mark=text}" + }, + ["text/at"] = { + details = [[ +Translates the origin (that is, the point where the text is shown) to +⟨point⟩. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/at", + meta = "⟨point⟩" + }, + ["text/base"] = { + details = [[ +This key causes the text box to be placed such that its baseline is on +the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/base" + }, + ["text/bottom"] = { + details = [[ +This key causes the text box to be placed such that its bottom is on the +origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[bottom,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/bottom" + }, + ["text/left"] = { + details = [[ +The key causes the text box to be placed such that its left border is on +the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[left] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/left" + }, + ["text/right"] = { + details = [[ +The key causes the text box to be placed such that its right border is +on the origin. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/right" + }, + ["text/rotate"] = { + details = [[ +Rotates the coordinate system by ⟨degree⟩. This will also rotate the +text box. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/rotate", + meta = "⟨degree⟩" + }, + ["text/top"] = { + details = [[ +This key causes the text box to be placed such that its top is on the +origin. This option can be used together with the `left` or `right` +option. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top] {lovely}} + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[top,right] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/top" + }, + ["text/x"] = { + details = [[ +Translates the origin by ⟨dimension⟩ along the $x$-axis. + + \tikz{\draw[help lines] (-1,-.5) grid (1,.5); + \pgftext[base,x=1cm,y=-0.5cm] {lovely}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/x", + meta = "⟨dimension⟩" + }, + ["text/y"] = { + details = [[ +This key works like the `x` option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/text/y", + meta = "⟨dimension⟩" + }, + tips = { + details = [[ +This key governs in what situations arrow tips are added to a path. The +following ⟨values⟩ are permissible: + +- `true` (the value used when no ⟨value⟩ is specified) + +- `proper` + +- `on draw` (the initial value, if the key has not yet been used at + all) + +- `on proper draw` + +- `never` or `false` (same effect) + +Firstly, there are a whole bunch of situations where the setting of +these (or other) options causes no arrow tips to be shown: + +- If no arrow tips have been specified (for instance, by having said + `arrows=-`), no arrow tips are drawn. + +- If the `clip` option is set, no arrow tips are drawn. + +- If `tips` has been set to `never` or `false`, no arrow tips are + drawn. + +- If `tips` has been set to `on draw` or `on proper draw`, but the + `draw` option is not set, no arrow tips are drawn. + +- If the path is empty (as in `\path ;`), no arrow tips are drawn. + +- 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. + +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 consider the last one. Arrow tips will only be added to +this last subpath. + +1. 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. + +2. 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. + +  + + % No path, no arrow tips: + \tikz [<->] \draw; + + % Degenerate path, draw arrow tips (but no path, it is degenerate...) + \tikz [<->] \draw (0,0); + + % Degenerate path, tips=proper suppresses arrows + \tikz [<->] \draw [tips=proper] (0,0); + + % Normal case: + \tikz [<->] \draw (0,0) -- (1,0); + + % Two subpaths, only second gets tips + \tikz [<->] \draw (0,0) -- (1,0) (2,0) -- (3,0); + + % Two subpaths, second degenerate, but still gets tips + \tikz [<->] \draw (0,0) -- (1,0) (2,0); + + % Two subpaths, second degenerate, proper suppresses them + \tikz [<->] \draw [tips=on proper draw] (0,0) -- (1,0) (2,0); + + % 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); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/tips", + meta = "⟨value⟩" + }, + ["trapezium angle"] = { + details = [[ +This key stores no value itself, but sets the value of the previous two +keys to ⟨angle⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:angle", + meta = "⟨angle⟩" + }, + ["trapezium left angle"] = { + details = [[ +Sets the lower internal angle of the left side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:left:angle", + meta = "⟨angle⟩" + }, + ["trapezium right angle"] = { + details = [[ +Sets the lower internal angle of the right side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:right:angle", + meta = "⟨angle⟩" + }, + ["trapezium stretches"] = { + details = [[ +This key controls whether PGF allows the width and the height of the +trapezium to be enlarged independently, when considering any minimum +size specification. This is initially `false`, ensuring that the shape +"looks the same but bigger" when enlarged. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \node [my node=red] {A}; + \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B}; + \node [my node=blue, minimum width=1.5cm] at (2, 0) {C}; + \end{tikzpicture} + +By setting ⟨boolean⟩ to `true`, the trapezium can be stretched +horizontally or vertically. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \tikzset{trapezium stretches=true} + \draw [help lines] grid (3,2); + \node [my node=red] {A}; + \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B}; + \node [my node=blue, minimum width=1.5cm] at (2, 0) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:stretches", + meta = "⟨boolean⟩" + }, + ["trapezium stretches body"] = { + details = [[ +This is similar to the `trapezium stretches` key except that when +⟨boolean⟩ is `true`, PGF enlarges only the body of the trapezium when +applying minimum width. + + \tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}} + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \node [my node=red] at (1.5,.25) {A}; + \node [my node=green, minimum width=3cm, trapezium stretches] + at (1.5,1) {B}; + \node [my node=blue, minimum width=3cm, trapezium stretches body] + at (1.5,1.75) {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trapezium:stretches:body", + meta = "⟨boolean⟩" + }, + ["trig format"] = { + details = [[ +Allows to define whether trigonometric math functions (i.e. all in this +subsection) operate with degrees or with radians. + + \pgfmathparse{cos(45)} \pgfmathresult + + \pgfkeys{/pgf/trig format=rad} + \pgfmathparse{cos(pi/2)} \pgfmathresult + +The initial configuration `trig format=deg` is the base of PGF: almost +all of it is based on degrees. + +Specifying `trig format=rad` is most useful for data visualization where +the angles are typically given in radians. However, it is applied to all +trigonometric functions for which the option applies, including any +drawing instructions which operate on angles. + + \begin{tikzpicture} + \draw[-stealth] + (0:1) -- (45:1) -- (90:1) -- (135:1) -- (180:1); + + \draw[-stealth,trig format=rad,red] + (pi:1) -- (5/4*pi:1) -- (6/4*pi:1) -- (7/4*pi:1) -- (2*pi:1); + \end{tikzpicture} + +#### Warning: + +At the time of this writing, this feature is "experimental". Please +handle it with care: there may be path instructions or libraries in +PGF which rely on `trig format=deg`. The intended usage of +`trig format=rad` is for local scopes -- and as option for data +visualization. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trig:format", + meta = "⟨deg,rad⟩" + }, + ["trim lowlevel"] = { + details = [[ +This affects only the basic level image externalization: the initial +configuration `trim lowlevel=false` stores the normal image, without +trimming, and the trimming into a separate file. This allows reduced +bounding boxes without clipping the rest away. The `trim lowlevel=true` +information causes the image externalization to store the trimmed image, +possibly resulting in clipping. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/trim:lowlevel", + meta = "⟨true,false⟩" + }, + ["xnor gate IEC symbol"] = { + details = [[ +Set the symbol for the `xnor gate`. In TikZ, when the +`use IEC style logic gates` key has been used, this key can be replaced +by `xnor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/xnor:gate:IEC:symbol", + meta = "⟨text⟩" + }, + ["xor gate IEC symbol"] = { + details = [[ +Set the symbol for the `xor gate`. Note the necessity for braces, as the +symbol contains `=`. In TikZ, when the `use IEC style logic gates` key +has been used, this key can be replaced by `xor gate symbol`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./pgf/xor:gate:IEC:symbol", + meta = "⟨text⟩" + } + } +} diff --git a/support/digestif/data/plain.tags b/support/digestif/data/plain.tags new file mode 100644 index 0000000000..fea2e363c9 --- /dev/null +++ b/support/digestif/data/plain.tags @@ -0,0 +1,2753 @@ +-- Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: GFDL-1.3-only +-- +-- Adapted from the book TeX for the Impatient, which can be found at +-- https://www.gnu.org/software/teximpatient. +ctan_package = "plain" +dependencies = {"primitives"} +documentation = { + {summary = "The TeXbook", uri = "https://www.ctan.org/pkg/texbook"}, + { + summary = "TeX for the Impatient", + uri = "texmf:doc/plain/impatient/book.pdf" + } +} +commands = { + ["!"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Negative thin space for math." + }, + ["\""] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Umlaut accent for text, as in ö." + }, + ["#"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Produce # character from current font." + }, + ["$"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Produce $ character from current font." + }, + ["%"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Produce % character from current font." + }, + ["&"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Produce & character from current font." + }, + ["'"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Acute accent for text, as in é." + }, + ["*"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Multiplication symbol that allows a line break." + }, + ["+"] = { + arguments = {delimiters = {"", "\\cr"}, meta = "rows"}, + details = "$ref:teximpatient#/data/+", + documentation = "texmf:doc/plain/impatient/book.pdf#page=196", + summary = "Begin tabbed line." + }, + [","] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Thin space for math." + }, + ["."] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Dot accent for text, as in n." + }, + [";"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Thick space for math." + }, + ["="] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Macron accent for text, as in r̄." + }, + [">"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Medium space for math." + }, + AA = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Scandinavian letter: Å.", + symbol = "Å" + }, + AE = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Æ ligature." + }, + Arrowvert = { + details = "$ref:teximpatient#/data/arrowvert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Vertical portion of an extensible single arrow." + }, + Big = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Make the specified delimiter about 11.5pt tall." + }, + Bigg = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Make specified delimiter about 17.5pt tall." + }, + Biggl = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Bigg, but spaced as an opening." + }, + Biggm = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Bigg, but spaced as a relation." + }, + Biggr = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Bigg, but spaced as a closing." + }, + Bigl = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Big, but spaced as an opening." + }, + Bigm = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Big, but spaced as a relation." + }, + Bigr = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\Big, but spaced as a closing." + }, + Delta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Δ.", + symbol = "Δ" + }, + Downarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇓.", + symbol = "⇓" + }, + Gamma = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Γ.", + symbol = "Γ" + }, + H = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Hungarian umlaut accent for text, as in ő." + }, + Im = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Complex imaginary part symbol: ℑ.", + symbol = "ℑ" + }, + L = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Polish letter: Ł.", + symbol = "Ł" + }, + Lambda = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Λ.", + symbol = "Λ" + }, + Leftarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇐.", + symbol = "⇐" + }, + Leftrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇔.", + symbol = "⇔" + }, + Longleftarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇐.", + symbol = "⇐" + }, + Longleftrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇔.", + symbol = "⇔" + }, + Longrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇒.", + symbol = "⇒" + }, + O = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Danish letter: Ø.", + symbol = "Ø" + }, + OE = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Œ ligature." + }, + Omega = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Ω.", + symbol = "Ω" + }, + P = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Paragraph character for text: ¶.", + symbol = "¶" + }, + Phi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Φ.", + symbol = "Φ" + }, + Pi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Π.", + symbol = "Π" + }, + Pr = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Probability function: Pr ." + }, + Psi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Ψ.", + symbol = "Ψ" + }, + Re = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Complex real part symbol: ℜ.", + symbol = "ℜ" + }, + Rightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇒.", + symbol = "⇒" + }, + S = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Section character for text: §.", + symbol = "§" + }, + Sigma = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Σ.", + symbol = "Σ" + }, + TeX = { + details = "$ref:teximpatient#/data/TeX", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Produce the TeX logo." + }, + Theta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Θ.", + symbol = "Θ" + }, + Uparrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇑.", + symbol = "⇑" + }, + Updownarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇕.", + symbol = "⇕" + }, + Upsilon = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Υ.", + symbol = "Υ" + }, + Vert = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Double bar relation: ‖.", + symbol = "‖" + }, + Xi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter Ξ.", + symbol = "Ξ" + }, + ["^"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Circumflex accent for text, as in ô." + }, + _ = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Underscore: _." + }, + ["`"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Grave accent for text, as in è." + }, + aa = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Scandinavian letter: å.", + symbol = "å" + }, + active = { + details = "$ref:teximpatient#/data/active", + documentation = "texmf:doc/plain/impatient/book.pdf#page=271", + summary = "Category code for active characters, viz., the number 13." + }, + acute = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Acute accent for math, as in x́." + }, + advancepageno = { + details = "$ref:teximpatient#/data/advancepageno", + documentation = "texmf:doc/plain/impatient/book.pdf#page=162", + summary = "If \\pageno is positive, add one; if it’s negative, subtract one." + }, + ae = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "æ ligature." + }, + aleph = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Only Hebrew letter for math: ℵ.", + symbol = "ℵ" + }, + allowbreak = { + details = "$ref:teximpatient#/data/allowbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=156", + summary = "Do \\penalty0, i.e., allow a line or page break where one could not ordinarily occur." + }, + alpha = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter α.", + symbol = "α" + }, + amalg = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Amalgamation operator: ∐.", + symbol = "∐" + }, + angle = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Angle symbol: ∠.", + symbol = "∠" + }, + approx = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Approximation relation: ≈.", + symbol = "≈" + }, + arccos = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Arc cosine function: arccos ." + }, + arcsin = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Arc sine function: arcsin ." + }, + arctan = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Arc tangent function: arctan ." + }, + arg = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Argument (phase) function: arg ." + }, + arrowvert = { + details = "$ref:teximpatient#/data/arrowvert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Vertical portion of an extensible double arrow." + }, + ast = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Asterisk operator: *." + }, + asymp = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Asymptote relation: ≍.", + symbol = "≍" + }, + b = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Bar-under accent for math, as in $\\b x$." + }, + backslash = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Backslash symbol: ∖.", + symbol = "∖" + }, + bar = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Bar accent for math, as in x̄." + }, + beginsection = { + arguments = {{delimiters = {"", "\\par"}, meta = "argument"}}, + details = "$ref:teximpatient#/data/beginsection", + documentation = "texmf:doc/plain/impatient/book.pdf#page=149", + summary = "Begin a major subdivision of a document." + }, + beta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter β.", + symbol = "β" + }, + bf = { + details = "$ref:teximpatient#/data/bf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "Use boldface, i.e., do \\tenbf\\fam=\\bffam." + }, + bffam = { + details = "$ref:teximpatient#/data/itfam", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "Boldface family for math." + }, + bgroup = { + details = "$ref:teximpatient#/data/bgroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=247", + summary = "Implicit beginning-of-group character." + }, + big = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Make the specified delimiter larger than an ordinary one, but still small enough for text." + }, + bigbreak = { + details = "$ref:teximpatient#/data/smallbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Indicate desirable page break with \\penalty-200 and produce \\bigskipamount glue." + }, + bigcap = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large cap operator (no, it doesn’t produce a large capital letter!): ⋂.", + symbol = "⋂" + }, + bigcirc = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Large circle operator: ○.", + symbol = "○" + }, + bigcup = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large cup operator: ⋃.", + symbol = "⋃" + }, + bigg = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Make the specified delimiter about 14.5pt tall." + }, + biggl = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\bigg, but spaced as an opening." + }, + biggm = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\bigg, but spaced as a relation." + }, + biggr = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\bigg, but spaced as a closing." + }, + bigl = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\big, but spaced as an opening." + }, + bigm = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\big, but spaced as a relation." + }, + bigodot = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large circled dot operator: ⨀.", + symbol = "⨀" + }, + bigoplus = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large circled plus operator: ⨁.", + symbol = "⨁" + }, + bigotimes = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large circled times operator: ⨂.", + symbol = "⨂" + }, + bigr = { + details = "$ref:teximpatient#/data/big", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Sized like \\big, but spaced as a closing." + }, + bigskip = { + details = "$ref:teximpatient#/data/smallskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Produce \\bigskipamount glue." + }, + bigskipamount = { + details = "$ref:teximpatient#/data/smallskipamount", + documentation = "texmf:doc/plain/impatient/book.pdf#page=175", + summary = "Glue for a big vertical skip, by default 12pt plus 4pt minus 4pt.", + type = "glue" + }, + bigsqcup = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large square cup operator: ⨆.", + symbol = "⨆" + }, + bigtriangledown = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Triangle operator pointing downward: ▽.", + symbol = "▽" + }, + bigtriangleup = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Triangle operator pointing upward: △.", + symbol = "△" + }, + biguplus = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large cupped plus operator: ⨄.", + symbol = "⨄" + }, + bigvee = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large logical “or” operator: ⋁.", + symbol = "⋁" + }, + bigwedge = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large logical “and” operator: ⋀.", + symbol = "⋀" + }, + bmod = { + details = "$ref:teximpatient#/data/bmod", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Modulus operator, as in n mod  2." + }, + bordermatrix = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=225", + summary = "Produce matrix with labelled rows and columns." + }, + bot = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Lattice bottom symbol: ⊥.", + symbol = "⊥" + }, + bowtie = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Bowtie relation: ⋈.", + symbol = "⋈" + }, + brace = { + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "$n\\brace k$ produces braced notation: $n \\brace k$." + }, + bracevert = { + details = "$ref:teximpatient#/data/arrowvert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Vertical portion of extensible large brace." + }, + brack = { + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "$n\\brack k$ produces bracketed notation: $n \\brack k$." + }, + ["break"] = { + details = "$ref:teximpatient#/data/break", + documentation = "texmf:doc/plain/impatient/book.pdf#page=156", + summary = "Do \\penalty-10000, i.e., force a line or page break." + }, + breve = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Breve accent for math, as in x̆." + }, + buildrel = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce specified formula over the specified relation." + }, + bullet = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Bullet operation: •.", + symbol = "•" + }, + bye = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=266", + summary = "\\vfill the last page with blank space, \\supereject it, and \\end the job." + }, + c = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Cedilla accent for text, as in ç." + }, + cal = { + details = "$ref:teximpatient#/data/cal", + documentation = "texmf:doc/plain/impatient/book.pdf#page=229", + summary = "Use calligraphic font for uppercase letters in math, as in $\\cal XYZ$." + }, + cap = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Cap operator: ∩.", + symbol = "∩" + }, + cases = { + details = "$ref:teximpatient#/data/cases", + documentation = "texmf:doc/plain/impatient/book.pdf#page=221", + summary = "Produce cases for math, as in $\\bigl\\{{\\cdots\\atop\\cdots}$." + }, + cdot = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Centered dot operator: ⋅.", + symbol = "⋅" + }, + cdotp = { + details = "$ref:teximpatient#/data/cdotp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=216", + summary = "Centered dot punctuation: ·.", + symbol = "·" + }, + cdots = { + details = "$ref:teximpatient#/data/ldots", + documentation = "texmf:doc/plain/impatient/book.pdf#page=223", + summary = "Centered dots for math: ⋯.", + symbol = "⋯" + }, + centerline = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/centerline", + documentation = "texmf:doc/plain/impatient/book.pdf#page=128", + summary = "Produce line with its text centered." + }, + check = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Check accent for math, as in x̌." + }, + chi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter χ.", + symbol = "χ" + }, + choose = { + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "$n\\choose k$ produces combinatorial notation: $n \\choose k$." + }, + circ = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Circle operation: ∘.", + symbol = "∘" + }, + cleartabs = { + details = "$ref:teximpatient#/data/cleartabs", + documentation = "texmf:doc/plain/impatient/book.pdf#page=197", + summary = "Clear all the tabs for tabbing alignments." + }, + clubsuit = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Club suit symbol: ♣.", + symbol = "♣" + }, + colon = { + details = "$ref:teximpatient#/data/colon", + documentation = "texmf:doc/plain/impatient/book.pdf#page=216", + summary = "Colon punctation symbol for math: :." + }, + cong = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Congruence relation: ≅.", + symbol = "≅" + }, + coprod = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Coproduct operator: ∐.", + symbol = "∐" + }, + copyright = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Copyright mark: ©.", + symbol = "©" + }, + cos = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Cosine function: cos ." + }, + cosh = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Hyperbolic cosine function: cosh ." + }, + cot = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Cotangent function : cot ." + }, + coth = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Hyperbolic cotangent function: coth ." + }, + csc = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Cosecant function: csc ." + }, + cup = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Cup operator: ∪.", + symbol = "∪" + }, + d = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Underdot accent for text, as in ṛ." + }, + dag = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Dagger symbol for text:." + }, + dagger = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Dagger operator for math: †.", + symbol = "†" + }, + dashv = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Right turnstile relation: ⊣.", + symbol = "⊣" + }, + ddag = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Double dagger symbol for text:." + }, + ddagger = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Double dagger operator for math: ‡.", + symbol = "‡" + }, + ddot = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219" + }, + ddots = { + details = "$ref:teximpatient#/data/ddots", + documentation = "texmf:doc/plain/impatient/book.pdf#page=223", + summary = "Diagonal dots for math:." + }, + deg = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Degree function: deg ." + }, + delta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter δ.", + symbol = "δ" + }, + det = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Determinant function: det ." + }, + diamond = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Diamond operator: ⋄.", + symbol = "⋄" + }, + diamondsuit = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Diamond suit symbol: ♢.", + symbol = "♢" + }, + dim = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Dimension function: dim ." + }, + displaylines = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=228", + summary = "Produce specified multiline display with each line centered." + }, + div = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Division operator: ÷.", + symbol = "÷" + }, + dot = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Dot accent for math, as in ẋ." + }, + doteq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Dotted equality relation: ≐.", + symbol = "≐" + }, + dotfill = { + details = "$ref:teximpatient#/data/dotfill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=195", + summary = "Fill enclosing horizontal space with dots." + }, + dots = { + details = "$ref:teximpatient#/data/dots", + documentation = "texmf:doc/plain/impatient/book.pdf#page=119", + summary = "Ellipsis for sequences: x₁, …, x_(n)." + }, + downarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↓.", + symbol = "↓" + }, + downbracefill = { + details = "$ref:teximpatient#/data/downbracefill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Fill enclosing hbox with a downwards facing brace: to 3.5em." + }, + egroup = { + details = "$ref:teximpatient#/data/bgroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=247", + summary = "Implicit end-of-group character." + }, + eject = { + details = "$ref:teximpatient#/data/eject", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "End current paragraph and force a page break, stretching out current page." + }, + ell = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Script letter for math: ℓ.", + symbol = "ℓ" + }, + empty = { + details = "$ref:teximpatient#/data/empty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=261", + summary = "Macro that expands to nothing." + }, + emptyset = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Empty set symbol: ∅.", + symbol = "∅" + }, + endgraf = { + details = "$ref:teximpatient#/data/endgraf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=131", + summary = "Equivalent to the \\par primitive." + }, + endinsert = { + details = "$ref:teximpatient#/data/endinsert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=167", + summary = "End insertion." + }, + endline = { + details = "$ref:teximpatient#/data/endline", + documentation = "texmf:doc/plain/impatient/book.pdf#page=200", + summary = "Equivalent to the \\cr primitive." + }, + enskip = { + details = "$ref:teximpatient#/data/enskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Horizontal glue with width /2em." + }, + enspace = { + details = "$ref:teximpatient#/data/enspace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Kern /2em." + }, + epsilon = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ϵ.", + symbol = "ϵ" + }, + eqalign = { + details = "$ref:teximpatient#/data/eqalign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=228", + summary = "Produce specified multiline display whose indicated parts are vertically aligned." + }, + eqalignno = { + details = "$ref:teximpatient#/data/eqalign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=228", + summary = "Produce specified multiline display with equation numbers whose indicated parts are vertically aligned." + }, + equiv = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Equivalence relation: ≡.", + symbol = "≡" + }, + eta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter η.", + symbol = "η" + }, + exists = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "“there exists” symbol: ∃.", + symbol = "∃" + }, + exp = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Exponential function: exp ." + }, + filbreak = { + details = "$ref:teximpatient#/data/filbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Force a page break unless the text up to another \\filbreak also fits on the page." + }, + fivebf = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 5-point bold font, cmbx5." + }, + fivei = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 5-point math italic font, cmmi5." + }, + fiverm = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 5-point roman font, cmr5." + }, + fivesy = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 5-point symbol font, cmsy5." + }, + flat = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Flat symbol for music: ♭.", + symbol = "♭" + }, + fmtname = { + details = "$ref:teximpatient#/data/fmtname", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "Name of the current format." + }, + fmtversion = { + details = "$ref:teximpatient#/data/fmtname", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "Version number of the current format." + }, + folio = { + details = "$ref:teximpatient#/data/folio", + documentation = "texmf:doc/plain/impatient/book.pdf#page=163", + summary = "Produce \\pageno as characters; in roman numerals if it’s negative." + }, + footline = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=163", + summary = "Token list that produces line at the bottom of each page." + }, + footnote = { + arguments = {{meta = "argument1"}, {meta = "argument2"}}, + details = "$ref:teximpatient#/data/footnote", + documentation = "texmf:doc/plain/impatient/book.pdf#page=165", + summary = "Produce a specified footnote with a specified reference mark." + }, + forall = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "“for all” symbol: ∀.", + symbol = "∀" + }, + frenchspacing = { + details = "$ref:teximpatient#/data/frenchspacing", + documentation = "texmf:doc/plain/impatient/book.pdf#page=126", + summary = "Make interword spacing independent of punctuation." + }, + frown = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Frown relation: ⌢.", + symbol = "⌢" + }, + gamma = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter γ.", + symbol = "γ" + }, + gcd = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Greatest common denominator function: gcd ." + }, + ge = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Greater than or equal relation: ≥.", + symbol = "≥" + }, + geq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Equivalent to \\ge." + }, + gets = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Gets relation: ←.", + symbol = "←" + }, + gg = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Much greater than relation: ≫.", + symbol = "≫" + }, + goodbreak = { + details = "$ref:teximpatient#/data/goodbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Indicate desirable page break with \\penalty-500." + }, + grave = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Grave accent for math, as in x̀." + }, + hang = { + details = "$ref:teximpatient#/data/hang", + documentation = "texmf:doc/plain/impatient/book.pdf#page=137", + summary = "Indent the current paragraph by \\parindent." + }, + hat = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Hat accent for math, as in x̂." + }, + hbar = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Math symbol: ℏ.", + symbol = "ℏ" + }, + headline = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=163", + summary = "Token list that produces the line at the top of every page." + }, + heartsuit = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Heart suit symbol: ♡.", + symbol = "♡" + }, + hglue = { + arguments = {{delimiters = false, meta = "glue"}}, + details = "$ref:teximpatient#/data/hglue", + documentation = "texmf:doc/plain/impatient/book.pdf#page=176", + summary = "Produce horizontal glue that doesn’t disappear at line breaks." + }, + hidewidth = { + details = "$ref:teximpatient#/data/hidewidth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=204", + summary = "Ignore width of an entry in an alignment, so that it extends out from its box in the direction of the \\hidewidth." + }, + hom = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Homology function: hom ." + }, + hookleftarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↩.", + symbol = "↩" + }, + hookrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↪.", + symbol = "↪" + }, + hphantom = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/hphantom", + documentation = "texmf:doc/plain/impatient/book.pdf#page=189", + summary = "Produce an invisible formula with zero height and depth but natural width." + }, + hrulefill = { + details = "$ref:teximpatient#/data/dotfill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=195", + summary = "Fill enclosing space with a horizontal rule." + }, + i = { + details = "$ref:teximpatient#/data/i", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Dotless letter ‘ı’ for use with accents.", + symbol = "ı" + }, + ialign = { + details = "$ref:teximpatient#/data/ialign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=200", + summary = "Start an \\halign with the \\tabskip glue zero and \\everycr empty." + }, + iff = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "If and only if relation: ⇔.", + symbol = "⇔" + }, + imath = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Dotless letter ‘ı’ for use with math accents.", + symbol = "𝚤" + }, + ["in"] = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Containment relation: ∈.", + symbol = "∈" + }, + inf = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Inferior function: inf ." + }, + infty = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Infinity symbol: ∞.", + symbol = "∞" + }, + int = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Integral symbol: ∫.", + symbol = "∫" + }, + iota = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ι.", + symbol = "ι" + }, + it = { + details = "$ref:teximpatient#/data/bf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "Use italics, i.e., do \\tenit\\fam=\\itfam." + }, + item = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/item", + documentation = "texmf:doc/plain/impatient/book.pdf#page=150", + summary = "Begin a paragraph with hanging indentation of \\parindent and preceded by a specified label." + }, + itemitem = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/item", + documentation = "texmf:doc/plain/impatient/book.pdf#page=150", + summary = "Like \\item, but with indentation of 2\\parindent." + }, + itfam = { + details = "$ref:teximpatient#/data/itfam", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "Italic family for math." + }, + j = { + details = "$ref:teximpatient#/data/i", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Dotless letter ‘ȷ’, for use with accents.", + symbol = "ȷ" + }, + jmath = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Dotless letter ‘ȷ’ for use with math accents.", + symbol = "𝚥" + }, + jot = { + details = "$ref:teximpatient#/data/jot", + documentation = "texmf:doc/plain/impatient/book.pdf#page=235", + summary = "Unit of measure for opening up displays.", + type = "dimen" + }, + kappa = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter κ.", + symbol = "κ" + }, + ker = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Kernel function: ker ." + }, + l = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Polish letter: ł.", + symbol = "ł" + }, + lambda = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter λ.", + symbol = "λ" + }, + land = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Logical “and” operator: ∧.", + symbol = "∧" + }, + langle = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left angle delimiter: ⟨.", + symbol = "⟨" + }, + lbrace = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left brace delimiter: {." + }, + lbrack = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left bracket delimiter: [." + }, + lceil = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left ceiling delimiter: ⌈.", + symbol = "⌈" + }, + ldotp = { + details = "$ref:teximpatient#/data/cdotp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=216", + summary = "Dot on baseline as punctuation: $\\ldotp$." + }, + ldots = { + details = "$ref:teximpatient#/data/ldots", + documentation = "texmf:doc/plain/impatient/book.pdf#page=223", + summary = "Dots on baseline for math: ….", + symbol = "…" + }, + le = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Less than or equal relation: ≤.", + symbol = "≤" + }, + leftarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ←.", + symbol = "←" + }, + leftarrowfill = { + details = "$ref:teximpatient#/data/leftarrowfill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=195", + summary = "Fill enclosing hbox with a \\leftarrow: to 3.5em." + }, + leftharpoondown = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↽.", + symbol = "↽" + }, + leftharpoonup = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↼.", + symbol = "↼" + }, + leftline = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/centerline", + documentation = "texmf:doc/plain/impatient/book.pdf#page=128", + summary = "Produce line with its text pushed to left margin." + }, + leftrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↔.", + symbol = "↔" + }, + leq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Equivalent to \\le." + }, + leqalignno = { + details = "$ref:teximpatient#/data/eqalign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=228", + summary = "Produce specified multiline display with equation numbers on the left whose indicated parts are vertically aligned." + }, + lfloor = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left floor delimiter: ⌊.", + symbol = "⌊" + }, + lg = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Logarithm function: lg ." + }, + lgroup = { + details = "$ref:teximpatient#/data/lgroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=224", + summary = "Left group delimiter (the smallest size is shown here): $\\Big\\lgroup$." + }, + lim = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Limit function: lim ." + }, + liminf = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Inferior limit function: liminf ." + }, + limsup = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Superior limit function: limsup ." + }, + line = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/line", + documentation = "texmf:doc/plain/impatient/book.pdf#page=129", + summary = "Produce a justified line of type." + }, + ll = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Much less than relation: ≪.", + symbol = "≪" + }, + llap = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/llap", + documentation = "texmf:doc/plain/impatient/book.pdf#page=129", + summary = "Produce text (with no width) extending to the left of the current position." + }, + lmoustache = { + details = "$ref:teximpatient#/data/arrowvert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Top half of a large brace: $\\big\\lmoustache$." + }, + ln = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Natural logarithm function: ln ." + }, + lnot = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Logical “not” symbol: ¬.", + symbol = "¬" + }, + log = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Logarithm function: log ." + }, + longleftarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ←.", + symbol = "←" + }, + longleftrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↔.", + symbol = "↔" + }, + longmapsto = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↦.", + symbol = "↦" + }, + longrightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: →.", + symbol = "→" + }, + loop = { + details = "$ref:teximpatient#/data/loop", + documentation = "texmf:doc/plain/impatient/book.pdf#page=260", + summary = "Start a loop to be ended by \\repeat." + }, + lor = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Logical “or” operator: ∨.", + symbol = "∨" + }, + lq = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Left quote character for text: ‘.", + symbol = "‘" + }, + magnification = { + arguments = { + {literal = "=", optional = true}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/magnification", + documentation = "texmf:doc/plain/impatient/book.pdf#page=243", + summary = "Like \\mag, but don’t enlarge the page size." + }, + magstep = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/magstep", + documentation = "texmf:doc/plain/impatient/book.pdf#page=243", + summary = "1000 ⋅ 1.2^(n) for a specified n." + }, + magstephalf = { + details = "$ref:teximpatient#/data/magstephalf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=244", + summary = "$1000\\cdot\\sqrt{1.2}$." + }, + mapsto = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↦.", + symbol = "↦" + }, + mathpalette = { + arguments = {{meta = "argument1"}, {meta = "argument2"}}, + details = "$ref:teximpatient#/data/mathpalette", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Produce a \\mathchoice which expands a specified control sequence depending on the current style." + }, + mathstrut = { + details = "$ref:teximpatient#/data/mathstrut", + documentation = "texmf:doc/plain/impatient/book.pdf#page=188", + summary = "Produce an invisible box with the height and depth of a left parenthesis and no width." + }, + matrix = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=225", + summary = "Produce a specified matrix." + }, + max = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Maximum function: max ." + }, + maxdimen = { + details = "$ref:teximpatient#/data/maxdimen", + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Largest dimension acceptable to TeX." + }, + medbreak = { + details = "$ref:teximpatient#/data/smallbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Indicate desirable page break with \\penalty-100 and produce \\medskipamount glue." + }, + medskip = { + details = "$ref:teximpatient#/data/smallskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Produce \\medskipamount glue." + }, + medskipamount = { + details = "$ref:teximpatient#/data/smallskipamount", + documentation = "texmf:doc/plain/impatient/book.pdf#page=175", + summary = "Glue for a medium vertical skip, by default 6pt plus 2pt minus 2pt.", + type = "glue" + }, + mid = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Middle relation: ∣.", + symbol = "∣" + }, + midinsert = { + arguments = { + { + delimiters = {"", "\\endinsert"}, + meta = "vertical mode material" + } + }, + details = "$ref:teximpatient#/data/topinsert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=166", + summary = "Produce the specified text at the current position if possible, otherwise at the top of the next page." + }, + min = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Minimum function: min ." + }, + mit = { + details = "$ref:teximpatient#/data/cal", + documentation = "texmf:doc/plain/impatient/book.pdf#page=229", + summary = "Use math italics, i.e., do \\fam=1." + }, + models = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Models relation: ⊨.", + symbol = "⊨" + }, + mp = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Minus and plus operator: ∓.", + symbol = "∓" + }, + mu = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter μ.", + symbol = "μ" + }, + multispan = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/multispan", + documentation = "texmf:doc/plain/impatient/book.pdf#page=202", + summary = "Make next alignment entry span a specified number of columns (or rows)." + }, + nabla = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Backwards difference symbol: ∇.", + symbol = "∇" + }, + narrower = { + details = "$ref:teximpatient#/data/narrower", + documentation = "texmf:doc/plain/impatient/book.pdf#page=134", + summary = "Make both left and right margins narrower by \\parindent." + }, + natural = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Natural symbol for music: ♮.", + symbol = "♮" + }, + ne = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Not equal relation: ≠.", + symbol = "≠" + }, + nearrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Northeast arrow relation: ↗.", + symbol = "↗" + }, + neg = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Logical “not” symbol: ¬.", + symbol = "¬" + }, + negthinspace = { + details = "$ref:teximpatient#/data/negthinspace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=173", + summary = "Kern $-\\frac1/6$em." + }, + neq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Not equal relation: ≠.", + symbol = "≠" + }, + newbox = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\box register." + }, + newcount = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\count register." + }, + newdimen = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\dimen register." + }, + newfam = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a math family." + }, + newhelp = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=282", + summary = "Name a specified help message." + }, + newif = { + arguments = {meta = "control sequence"}, + details = "$ref:teximpatient#/data/newif", + documentation = "texmf:doc/plain/impatient/book.pdf#page=260", + summary = "Define a new conditional with the specified name." + }, + newlanguage = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\language." + }, + newmuskip = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\muskip register." + }, + newread = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name an input stream." + }, + newskip = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\skip register." + }, + newtoks = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name a \\toks register." + }, + newwrite = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Reserve and name an output stream." + }, + ni = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "“reverse in” relation: ∋.", + symbol = "∋" + }, + nobreak = { + details = "$ref:teximpatient#/data/nobreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=156", + summary = "Do \\penalty10000, i.e., inhibit a line or page break." + }, + nointerlineskip = { + details = "$ref:teximpatient#/data/nointerlineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=155", + summary = "Inhibit interline glue before the next line." + }, + nonfrenchspacing = { + details = "$ref:teximpatient#/data/frenchspacing", + documentation = "texmf:doc/plain/impatient/book.pdf#page=126", + summary = "Make interword spacing depend on punctuation." + }, + nopagenumbers = { + details = "$ref:teximpatient#/data/nopagenumbers", + documentation = "texmf:doc/plain/impatient/book.pdf#page=162", + summary = "Inhibit printing of page numbers, i.e., do \\footline = {\\hfil}." + }, + normalbaselines = { + details = "$ref:teximpatient#/data/normalbaselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=154", + summary = "Set \\baselineskip, \\line\\-skip, and \\line\\-skip\\-limit to the normal values for the current type size." + }, + normalbaselineskip = { + details = "$ref:teximpatient#/data/normalbaselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=154", + summary = "Value of \\baselineskip for the current type size.", + type = "glue" + }, + normalbottom = { + details = "$ref:teximpatient#/data/raggedbottom", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Make the bottom margin be the same from page to page." + }, + normallineskip = { + details = "$ref:teximpatient#/data/normalbaselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=154", + summary = "Value of \\lineskip for the current type size.", + type = "glue" + }, + normallineskiplimit = { + details = "$ref:teximpatient#/data/normalbaselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=154", + summary = "Value of \\lineskiplimit for the current type size.", + type = "dimen" + }, + ["not"] = { + summary = "A slash with zero width for constructing negations of math relations, as in ≠." + }, + notin = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Noninclusion relation: ∉.", + symbol = "∉" + }, + nu = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ν.", + symbol = "ν" + }, + null = { + details = "$ref:teximpatient#/data/null", + documentation = "texmf:doc/plain/impatient/book.pdf#page=189", + summary = "Expands to an empty hbox." + }, + nwarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Northwest arrow relation: ↖.", + symbol = "↖" + }, + o = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "Danish letter: ø.", + symbol = "ø" + }, + obeylines = { + details = "$ref:teximpatient#/data/obeylines", + documentation = "texmf:doc/plain/impatient/book.pdf#page=142", + summary = "Make each end-of-line in the input file equivalent to \\par." + }, + obeyspaces = { + details = "$ref:teximpatient#/data/obeyspaces", + documentation = "texmf:doc/plain/impatient/book.pdf#page=127", + summary = "Produce space in the output for each space character in the input." + }, + odot = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Centered dot operation: ⊙.", + symbol = "⊙" + }, + oe = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "œ ligature." + }, + offinterlineskip = { + details = "$ref:teximpatient#/data/offinterlineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=155", + summary = "Inhibit interline glue from now on." + }, + oint = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Contour integral operator: ∮.", + symbol = "∮" + }, + oldstyle = { + details = "$ref:teximpatient#/data/cal", + documentation = "texmf:doc/plain/impatient/book.pdf#page=229", + summary = "Use old style digits:." + }, + omega = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ω.", + symbol = "ω" + }, + ominus = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Circled minus operator: ⊖.", + symbol = "⊖" + }, + openup = { + arguments = {{delimiters = false, meta = "dimen"}}, + details = "$ref:teximpatient#/data/openup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=155", + summary = "Increase \\baselineskip, \\lineskip, and \\lineskiplimit by a specified amount." + }, + oplus = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Circled plus operator: ⊕.", + symbol = "⊕" + }, + oslash = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Circled slash operator: ⊘.", + symbol = "⊘" + }, + otimes = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Circled times operator: ⊗.", + symbol = "⊗" + }, + overbrace = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce a brace covering the top of a formula, as in $\\overbrace{h+w}{}$." + }, + overleftarrow = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce a left arrow covering the top of a formula, as in $\\overleftarrow{r+a}$." + }, + overrightarrow = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce a right arrow covering the top of a formula, as in $\\overrightarrow{i+t}$." + }, + owns = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Owns relation: ∋.", + symbol = "∋" + }, + pageinsert = { + arguments = { + { + delimiters = {"", "\\endinsert"}, + meta = "vertical mode material" + } + }, + details = "$ref:teximpatient#/data/topinsert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=166", + summary = "Produce the specified text on the following page, and use up the full page." + }, + pageno = { + details = "$ref:teximpatient#/data/pageno", + documentation = "texmf:doc/plain/impatient/book.pdf#page=162", + summary = "The register \\count0, which contains the (possibly negative) page number.", + type = "number" + }, + parallel = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Parallel relation: ∥.", + symbol = "∥" + }, + partial = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Partial derivative symbol: ∂.", + symbol = "∂" + }, + perp = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Perpendicular relation: ⊥.", + symbol = "⊥" + }, + phantom = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/phantom", + documentation = "texmf:doc/plain/impatient/book.pdf#page=188", + summary = "Produce an invisible formula with the dimensions of a specified subformula." + }, + phi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ϕ.", + symbol = "ϕ" + }, + pi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter π.", + symbol = "π" + }, + plainoutput = { + details = "$ref:teximpatient#/data/plainoutput", + documentation = "texmf:doc/plain/impatient/book.pdf#page=168", + summary = "Plain TeX’s \\output routine." + }, + pm = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Plus and minus operator: ±.", + symbol = "±" + }, + pmatrix = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=225", + summary = "Produce a parenthesized matrix." + }, + pmod = { + details = "$ref:teximpatient#/data/pmod", + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Parenthesized modulus notation to put at the end of a formula, as in x ≡ y + 1 (mod  2)." + }, + prec = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Precedes relation: ≺.", + symbol = "≺" + }, + preceq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Precedes or equals relation: ≼.", + symbol = "≼" + }, + prime = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Prime math symbol, as in r^(′)." + }, + proclaim = { + arguments = { + {delimiters = {"", "."}, meta = "argument"}, + {delimiters = {"", "\\par"}, meta = "general text"} + }, + details = "$ref:teximpatient#/data/proclaim", + documentation = "texmf:doc/plain/impatient/book.pdf#page=151", + summary = "Begin a theorem, lemma, hypothesis, …." + }, + prod = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large product operator: ∏.", + symbol = "∏" + }, + propto = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Proportional to relation: ∝.", + symbol = "∝" + }, + psi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ψ.", + symbol = "ψ" + }, + qquad = { + details = "$ref:teximpatient#/data/enskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Produce horizontal glue with width 2em." + }, + quad = { + details = "$ref:teximpatient#/data/enskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Produce horizontal glue with width 1em." + }, + raggedbottom = { + details = "$ref:teximpatient#/data/raggedbottom", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Allow the bottom margin to vary from page to page." + }, + raggedright = { + details = "$ref:teximpatient#/data/raggedright", + documentation = "texmf:doc/plain/impatient/book.pdf#page=136", + summary = "Allow the right margin to vary from line to line." + }, + rangle = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right angle delimiter: ⟩.", + symbol = "⟩" + }, + rbrace = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right brace delimiter: }." + }, + rbrack = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right bracket delimiter: ]." + }, + rceil = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right ceiling delimiter: ⌉.", + symbol = "⌉" + }, + ["repeat"] = { + details = "$ref:teximpatient#/data/loop", + documentation = "texmf:doc/plain/impatient/book.pdf#page=260", + summary = "End a loop started with \\loop." + }, + rfloor = { + details = "$ref:teximpatient#/data/lbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right floor delimiter: ⌋.", + symbol = "⌋" + }, + rgroup = { + details = "$ref:teximpatient#/data/lgroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=224", + summary = "Right group delimiter (the smallest size is shown here): $\\Big\\rgroup$." + }, + rho = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ρ.", + symbol = "ρ" + }, + rightarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: →.", + symbol = "→" + }, + rightarrowfill = { + details = "$ref:teximpatient#/data/leftarrowfill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=195", + summary = "Fill enclosing hbox with a \\rightarrow: to 3.5em." + }, + rightharpoondown = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇁.", + symbol = "⇁" + }, + rightharpoonup = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇀.", + symbol = "⇀" + }, + rightleftharpoons = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ⇌.", + symbol = "⇌" + }, + rightline = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/centerline", + documentation = "texmf:doc/plain/impatient/book.pdf#page=128", + summary = "Produce line with its text pushed to right margin." + }, + rlap = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/llap", + documentation = "texmf:doc/plain/impatient/book.pdf#page=129", + summary = "Produce text (with no width) extending to the right of the current position." + }, + rm = { + details = "$ref:teximpatient#/data/bf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "Use roman type, i.e., do \\tenrm\\fam=0." + }, + rmoustache = { + details = "$ref:teximpatient#/data/arrowvert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Bottom half of a large brace: $\\big\\rmoustache$." + }, + romannumeral = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/romannumeral", + documentation = "texmf:doc/plain/impatient/book.pdf#page=244", + summary = "Produce the lowercase roman numeral representation of a specified number as characters." + }, + root = { + arguments = { + {delimiters = {"", "\\of"}, meta = "argument1"}, + {meta = "argument2"} + }, + details = "$ref:teximpatient#/data/root", + documentation = "texmf:doc/plain/impatient/book.pdf#page=227", + summary = "Produce a specified root of a specified subformula, as in $\\root 3 \\of 2$." + }, + rq = { + details = "$ref:teximpatient#/data/lq", + documentation = "texmf:doc/plain/impatient/book.pdf#page=118", + summary = "Right quote character for text: ’.", + symbol = "’" + }, + sb = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/sb", + documentation = "texmf:doc/plain/impatient/book.pdf#page=217", + summary = "Implicit subscript character." + }, + searrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Southeast arrow relation: ↘.", + symbol = "↘" + }, + sec = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Secant function: sec ." + }, + setminus = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Set difference operator: \\." + }, + settabs = { + arguments = {{delimiters = {"", "\\cr"}, meta = "sample line"}}, + details = "$ref:teximpatient#/data/settabs", + documentation = "texmf:doc/plain/impatient/book.pdf#page=196", + summary = "Define the tabs for a tabbing alignment." + }, + sevenbf = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 7-point bold font, cmbx7." + }, + seveni = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 7-point math italic font, cmmi5." + }, + sevenrm = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 7-point roman font, cmr7." + }, + sevensy = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 7-point symbol font, cmsy7." + }, + sharp = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Sharp symbol for music: ♯.", + symbol = "♯" + }, + showhyphens = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "Show, in the log and on the terminal, hyphenations in the specified text." + }, + sigma = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter σ.", + symbol = "σ" + }, + sim = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Similarity relation: ∼.", + symbol = "∼" + }, + simeq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Similar or equal relation: ≃.", + symbol = "≃" + }, + sin = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Sine function: sin ." + }, + sinh = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Hyperbolic sine function: sinh ." + }, + skew = { + arguments = { + {delimiters = false, meta = "number"}, + {meta = "argument1"}, + {meta = "argument2"} + }, + details = "$ref:teximpatient#/data/skew", + documentation = "texmf:doc/plain/impatient/book.pdf#page=232", + summary = "Shift a specified accent by a specified amount on a specified accented character." + }, + sl = { + details = "$ref:teximpatient#/data/bf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "Use slanted type, i.e., do \\tensl\\fam=\\slfam." + }, + slash = { + details = "$ref:teximpatient#/data/slash", + documentation = "texmf:doc/plain/impatient/book.pdf#page=142", + summary = "/ character that allows a line break." + }, + slfam = { + details = "$ref:teximpatient#/data/itfam", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "Slanted family for math." + }, + smallbreak = { + details = "$ref:teximpatient#/data/smallbreak", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Indicate somewhat desirable page break with \\penalty-50 and produce \\smallskipamount glue." + }, + smallint = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Small integral symbol: $\\smallint$." + }, + smallskip = { + details = "$ref:teximpatient#/data/smallskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=174", + summary = "Produce \\smallskipamount glue." + }, + smallskipamount = { + details = "$ref:teximpatient#/data/smallskipamount", + documentation = "texmf:doc/plain/impatient/book.pdf#page=175", + summary = "Glue for a small vertical skip, by default 3pt plus 1pt minus 1pt.", + type = "glue" + }, + smash = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/smash", + documentation = "texmf:doc/plain/impatient/book.pdf#page=189", + summary = "Produce formula with zero height and depth." + }, + smile = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Smile relation: ⌣.", + symbol = "⌣" + }, + sp = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/sb", + documentation = "texmf:doc/plain/impatient/book.pdf#page=217", + summary = "Implicit superscript character." + }, + space = { + details = "$ref:teximpatient#/data/space", + documentation = "texmf:doc/plain/impatient/book.pdf#page=125", + summary = "Produce normal interword glue." + }, + spadesuit = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Spade suit symbol: ♠.", + symbol = "♠" + }, + sqcap = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Square cap operator: ⊓.", + symbol = "⊓" + }, + sqcup = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Square cup operator: ⊔.", + symbol = "⊔" + }, + sqrt = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/sqrt", + documentation = "texmf:doc/plain/impatient/book.pdf#page=226", + summary = "Produce square root of a subformula, as in $\\sqrt 2$." + }, + sqsubseteq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Square subset or equal relation: ⊑.", + symbol = "⊑" + }, + sqsupseteq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Square superset or equal relation: ⊒.", + symbol = "⊒" + }, + ss = { + details = "$ref:teximpatient#/data/AA", + documentation = "texmf:doc/plain/impatient/book.pdf#page=117", + summary = "German letter: ß.", + symbol = "ß" + }, + star = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Star operator: ⋆.", + symbol = "⋆" + }, + strut = { + details = "$ref:teximpatient#/data/strut", + documentation = "texmf:doc/plain/impatient/book.pdf#page=187", + summary = "Box with zero width, but height and depth of a standard line, from baseline to baseline, in the current font." + }, + subset = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Subset relation: ⊂.", + symbol = "⊂" + }, + subseteq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Subset or equal relation: ⊆.", + symbol = "⊆" + }, + succ = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Successor relation: ≻.", + symbol = "≻" + }, + succeq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Successor or equal relation: ≽.", + symbol = "≽" + }, + sum = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=214", + summary = "Large summation operator: ∑.", + symbol = "∑" + }, + sup = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Superior function: sup ." + }, + supereject = { + details = "$ref:teximpatient#/data/eject", + documentation = "texmf:doc/plain/impatient/book.pdf#page=157", + summary = "Force a page break, and output all insertions." + }, + supset = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Superset relation: ⊃.", + symbol = "⊃" + }, + supseteq = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Superset or equal relation: ⊇.", + symbol = "⊇" + }, + surd = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Surd symbol: $\\surd$." + }, + swarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Southwest arrow relation: ↙.", + symbol = "↙" + }, + t = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Tie-after accent for text, as in u͡u." + }, + tabalign = { + arguments = {delimiters = {"", "\\cr"}, meta = "rows"}, + details = "$ref:teximpatient#/data/+", + documentation = "texmf:doc/plain/impatient/book.pdf#page=196", + summary = "Equivalent to \\+, except it’s not \\outer." + }, + tan = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Tangent function: tan ." + }, + tanh = { + details = "$ref:teximpatient#/data/cos", + documentation = "texmf:doc/plain/impatient/book.pdf#page=213", + summary = "Hyperbolic tangent function: tanh ." + }, + tau = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter τ.", + symbol = "τ" + }, + tenbf = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point bold font, cmbx10." + }, + tenex = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point math extension font, cmex10." + }, + teni = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point math italic font, cmmi10." + }, + tenit = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point text italic font, cmti10." + }, + tenrm = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point roman text font, cmr10." + }, + tensl = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point slanted roman font, cmsl10." + }, + tensy = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point math symbol font, cmsy10." + }, + tentt = { + details = "$ref:teximpatient#/data/fivebf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Use 10-point typewriter font, cmtt10." + }, + textindent = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/textindent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=132", + summary = "Like \\item, but doesn’t do hanging indentation." + }, + theta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter θ.", + symbol = "θ" + }, + thinspace = { + details = "$ref:teximpatient#/data/thinspace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=173", + summary = "Kern /6em." + }, + tilde = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Tilde accent for math, as in x̃." + }, + times = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Times operator: ×.", + symbol = "×" + }, + to = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Mapping relation: →.", + symbol = "→" + }, + top = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Lattice top symbol: ⊤.", + symbol = "⊤" + }, + topglue = { + arguments = {{delimiters = false, meta = "glue"}}, + details = "$ref:teximpatient#/data/topglue", + documentation = "texmf:doc/plain/impatient/book.pdf#page=176", + summary = "Produce specified vertical glue at the top of a page." + }, + topinsert = { + arguments = { + { + delimiters = {"", "\\endinsert"}, + meta = "vertical mode material" + } + }, + details = "$ref:teximpatient#/data/topinsert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=166", + summary = "Produce the specified text at top of a page." + }, + tracingall = { + details = "$ref:teximpatient#/data/tracingall", + documentation = "texmf:doc/plain/impatient/book.pdf#page=281", + summary = "Turn on maximal tracing." + }, + triangle = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Triangle symbol: △.", + symbol = "△" + }, + triangleleft = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Left triangle operator: ⊲.", + symbol = "⊲" + }, + triangleright = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Right triangle operator: ⊳.", + symbol = "⊳" + }, + tt = { + details = "$ref:teximpatient#/data/bf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "Use typewriter type, i.e., do \\tentt\\fam=\\ttfam." + }, + ttfam = { + details = "$ref:teximpatient#/data/itfam", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "Typewriter family for math." + }, + ttraggedright = { + details = "$ref:teximpatient#/data/raggedright", + documentation = "texmf:doc/plain/impatient/book.pdf#page=136", + summary = "Use typewriter type and allow right margins of paragraphs to vary from line to line." + }, + u = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Breve accent for text, as in r̆." + }, + underbar = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=183", + summary = "Underline the specified text without avoiding any descenders, as in." + }, + underbrace = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce a brace covering the bottom of a formula, as in $\\underbrace{x+x}{}$." + }, + uparrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↑.", + symbol = "↑" + }, + upbracefill = { + details = "$ref:teximpatient#/data/downbracefill", + documentation = "texmf:doc/plain/impatient/book.pdf#page=231", + summary = "Fill enclosing hbox with an upwards facing brace: to 3.5em." + }, + updownarrow = { + details = "$ref:teximpatient#/data/leftarrow", + documentation = "texmf:doc/plain/impatient/book.pdf#page=212", + summary = "Relation: ↕.", + symbol = "↕" + }, + uplus = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Cupped plus operator: ⊎.", + symbol = "⊎" + }, + upsilon = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter υ.", + symbol = "υ" + }, + v = { + details = "$ref:teximpatient#/data/c", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Check accent for text, as in ǒ." + }, + varepsilon = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant math Greek letter ε.", + symbol = "ε" + }, + varphi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant math Greek letter φ.", + symbol = "φ" + }, + varpi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant math Greek letter ϖ.", + symbol = "ϖ" + }, + varrho = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant math Greek letter 𝜚.", + symbol = "𝜚" + }, + varsigma = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant Greek letter ς.", + symbol = "ς" + }, + vartheta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Variant math Greek letter ϑ.", + symbol = "ϑ" + }, + vdash = { + details = "$ref:teximpatient#/data/asymp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=210", + summary = "Left turnstile symbol: ⊢.", + symbol = "⊢" + }, + vdots = { + details = "$ref:teximpatient#/data/vdots", + documentation = "texmf:doc/plain/impatient/book.pdf#page=223", + summary = "Vertical dots for math:." + }, + vec = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Vector accent for math, as in x⃗." + }, + vee = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Logical “or” operator: ∨.", + symbol = "∨" + }, + vert = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Bar relation: |." + }, + vfootnote = { + arguments = {{meta = "argument1"}, {meta = "argument2"}}, + details = "$ref:teximpatient#/data/footnote", + documentation = "texmf:doc/plain/impatient/book.pdf#page=165", + summary = "Produce a specified footnote with a specified reference mark, but don’t produce the reference mark in the text." + }, + vglue = { + arguments = {{delimiters = false, meta = "glue"}}, + details = "$ref:teximpatient#/data/hglue", + documentation = "texmf:doc/plain/impatient/book.pdf#page=176", + summary = "Produce specified vertical glue that doesn’t disappear at page breaks." + }, + vphantom = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/hphantom", + documentation = "texmf:doc/plain/impatient/book.pdf#page=189", + summary = "Produce an invisible formula with zero width but natural height and depth." + }, + wedge = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Logical “and” operator: ∧.", + symbol = "∧" + }, + widehat = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Math accent, as in $\\widehat {y+z+a}$." + }, + widetilde = { + details = "$ref:teximpatient#/data/acute", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Math accent $\\widetilde {b+c+d}$." + }, + wlog = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/wlog", + documentation = "texmf:doc/plain/impatient/book.pdf#page=282", + summary = "\\write the specified token list in the log file." + }, + wp = { + details = "$ref:teximpatient#/data/infty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Weierstraß ‘p’ symbol: ℘.", + symbol = "℘" + }, + wr = { + details = "$ref:teximpatient#/data/vee", + documentation = "texmf:doc/plain/impatient/book.pdf#page=209", + summary = "Wreath product operator: ≀.", + symbol = "≀" + }, + xi = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ξ.", + symbol = "ξ" + }, + zeta = { + details = "$ref:teximpatient#/data/alpha", + documentation = "texmf:doc/plain/impatient/book.pdf#page=207", + summary = "Math Greek letter ζ.", + symbol = "ζ" + }, + ["{"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Left brace delimiter for math: {." + }, + ["|"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=208", + summary = "Parallel lines for math: ‖.", + symbol = "‖" + }, + ["}"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=211", + summary = "Right brace delimiter for math: }." + }, + ["~"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Tilde accent for text, as in ã." + } +} diff --git a/support/digestif/data/primitives.tags b/support/digestif/data/primitives.tags new file mode 100644 index 0000000000..3c68daa40a --- /dev/null +++ b/support/digestif/data/primitives.tags @@ -0,0 +1,2058 @@ +-- Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: GFDL-1.3-only +-- +-- Adapted from the book TeX for the Impatient, which can be found at +-- https://www.gnu.org/software/teximpatient. +ctan_package = "tex" +documentation = { + {summary = "The TeXbook", uri = "https://www.ctan.org/pkg/texbook"}, + { + summary = "TeX for the Impatient", + uri = "texmf:doc/plain/impatient/book.pdf" + } +} +commands = { + ["-"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=146", + summary = "Specify a legal hyphenation point." + }, + ["/"] = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=126", + summary = "Italic correction for the previous character." + }, + above = { + arguments = {{delimiters = false, meta = "dimen"}}, + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "Produce a fraction with a bar of specified thickness." + }, + abovedisplayshortskip = { + details = "$ref:teximpatient#/data/abovedisplayshortskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Glue TeX inserts before a display when the previous line fits in the display’s indentation, by default 0pt plus 3pt.", + type = "glue" + }, + abovedisplayskip = { + details = "$ref:teximpatient#/data/abovedisplayskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Glue TeX inserts before a display when the previous line doesn’t fit in the display’s indentation, by default 12pt plus 3pt minus 9pt.", + type = "glue" + }, + abovewithdelims = { + arguments = { + {delimiters = false, meta = "delim1"}, + {delimiters = false, meta = "delim2"}, + {delimiters = false, meta = "dimen"} + }, + details = "$ref:teximpatient#/data/overwithdelims", + documentation = "texmf:doc/plain/impatient/book.pdf#page=221", + summary = "Produce a fraction with a bar of specified thickness and surrounded by specified delimiters." + }, + accent = { + arguments = {{delimiters = false, meta = "charcode"}}, + details = "$ref:teximpatient#/data/accent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=120", + summary = "Put specified accent over the next character." + }, + adjdemerits = { + details = "$ref:teximpatient#/data/adjdemerits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=145", + summary = "Additional demerits for a line break which would result in adjacent lines with incompatible word spacing, by default 10000.", + type = "number" + }, + advance = { + arguments = { + {delimiters = {"", "by"}, meta = "muskip register"}, + {delimiters = false, meta = "muglue"} + }, + details = "$ref:teximpatient#/data/advance", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Add a number to a \\count register." + }, + afterassignment = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/afterassignment", + documentation = "texmf:doc/plain/impatient/book.pdf#page=249", + summary = "Wait to expand the following token until the next assignment is done." + }, + aftergroup = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/aftergroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=249", + summary = "Wait to expand the following token until the end of the current group." + }, + atop = { + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "Produce a fraction without a fraction bar." + }, + atopwithdelims = { + arguments = { + {delimiters = false, meta = "delim1"}, + {delimiters = false, meta = "delim2"} + }, + details = "$ref:teximpatient#/data/overwithdelims", + documentation = "texmf:doc/plain/impatient/book.pdf#page=221", + summary = "Produce a fraction without a fraction bar and surrounded by specified delimiters." + }, + badness = { + details = "$ref:teximpatient#/data/badness", + documentation = "texmf:doc/plain/impatient/book.pdf#page=190", + summary = "The badness of the glue setting in the last box made." + }, + baselineskip = { + details = "$ref:teximpatient#/data/baselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=153", + summary = "Glue for the normal vertical distance from one baseline to the next, by default 12pt.", + type = "glue" + }, + batchmode = { + details = "$ref:teximpatient#/data/batchmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Don’t stop at errors and don’t output to terminal." + }, + begingroup = { + details = "$ref:teximpatient#/data/begingroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=247", + summary = "Start a group to be ended by \\endgroup." + }, + belowdisplayshortskip = { + details = "$ref:teximpatient#/data/belowdisplayshortskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Glue TeX inserts after a display when the previous line fits in the display’s indentation, by default 7pt plus 0.3pt minus 4pt.", + type = "glue" + }, + belowdisplayskip = { + details = "$ref:teximpatient#/data/belowdisplayskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Glue TeX inserts after a display when the previous line doesn’t fit in the display’s indentation, by default 12pt plus 3pt minus 9pt.", + type = "glue" + }, + binoppenalty = { + details = "$ref:teximpatient#/data/binoppenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=146", + summary = "Additional penalty for breaking after a binary math operator, by default 700.", + type = "number" + }, + botmark = { + details = "$ref:teximpatient#/data/firstmark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "The last mark item on the page just boxed." + }, + box = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/setbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=184", + summary = "Append the box in a specified box register to the current list, and void the register." + }, + boxmaxdepth = { + details = "$ref:teximpatient#/data/boxmaxdepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=183", + summary = "Maximum depth of vboxes, by default \\maxdimen.", + type = "dimen" + }, + brokenpenalty = { + details = "$ref:teximpatient#/data/brokenpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "Penalty for line break at a discretionary item, by default 100.", + type = "number" + }, + catcode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/catcode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=271", + summary = "The category code of a specified character." + }, + char = { + arguments = {{delimiters = false, meta = "charcode"}}, + details = "$ref:teximpatient#/data/char", + documentation = "texmf:doc/plain/impatient/book.pdf#page=119", + summary = "Produce the character from the current font with the specified code." + }, + chardef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "charcode"} + }, + details = "$ref:teximpatient#/data/chardef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=252", + summary = "Define a specified control sequence to be a character’s code, a number between 0 and 255." + }, + cleaders = { + arguments = { + {delimiters = false, meta = "box or rule"}, + {delimiters = false, meta = "skip command"} + }, + details = "$ref:teximpatient#/data/leaders", + documentation = "texmf:doc/plain/impatient/book.pdf#page=194", + summary = "Produce leaders with half of leftover space before the first box, and half after the last." + }, + closein = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=268", + summary = "Close a specified input stream." + }, + closeout = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/closeout", + documentation = "texmf:doc/plain/impatient/book.pdf#page=269", + summary = "Close a specified output stream." + }, + clubpenalty = { + details = "$ref:teximpatient#/data/clubpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Additional penalty for a single line remaining before a page break, by default 150.", + type = "number" + }, + copy = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/copy", + documentation = "texmf:doc/plain/impatient/book.pdf#page=184", + summary = "Like \\box, but don’t void the register." + }, + count = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/count", + documentation = "texmf:doc/plain/impatient/book.pdf#page=262", + summary = "The specified integer register." + }, + countdef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "register"} + }, + details = "$ref:teximpatient#/data/countdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Define a specified control sequence to be a number corresponding to a \\count register." + }, + cr = { + details = "$ref:teximpatient#/data/cr", + documentation = "texmf:doc/plain/impatient/book.pdf#page=200", + summary = "End a row (or column) within an alignment." + }, + crcr = { + details = "$ref:teximpatient#/data/crcr", + documentation = "texmf:doc/plain/impatient/book.pdf#page=200", + summary = "Does nothing if the last command was \\cr or \\noalign; otherwise, equivalent to \\cr." + }, + csname = { + arguments = {{delimiters = {"", "\\endcsname"}, meta = "token list"}}, + details = "$ref:teximpatient#/data/csname", + documentation = "texmf:doc/plain/impatient/book.pdf#page=253", + summary = "Start a control sequence name to be ended by \\endcsname." + }, + day = { + details = "$ref:teximpatient#/data/day", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "Current day of the month, as a number.", + type = "number" + }, + deadcycles = { + details = "$ref:teximpatient#/data/deadcycles", + documentation = "texmf:doc/plain/impatient/book.pdf#page=168", + summary = "Number of \\output initiations since the last \\shipout.", + type = "number" + }, + def = { + action = "def", + arguments = { + {delimiters = false, meta = "control sequence"}, + {delimiters = {"", "{"}, meta = "parameter text"}, + {delimiters = {"", "}"}, meta = "replacement text"} + }, + details = "$ref:teximpatient#/data/def", + documentation = "texmf:doc/plain/impatient/book.pdf#page=250", + summary = "Define a control sequence to be a macro." + }, + defaulthyphenchar = { + details = "$ref:teximpatient#/data/defaulthyphenchar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=149", + summary = "Default hyphenation character code.", + type = "number" + }, + defaultskewchar = { + details = "$ref:teximpatient#/data/defaultskewchar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=233", + summary = "Default accent skewing character code.", + type = "number" + }, + delcode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/delcode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=271", + summary = "The delimiter code of a specified character." + }, + delimiter = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/delimiter", + documentation = "texmf:doc/plain/impatient/book.pdf#page=224", + summary = "Produce a specified delimiter." + }, + delimiterfactor = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=225", + summary = "1000 times the ratio of the minimum size of a delimiter to the size that would completely cover the formula, by default 901." + }, + delimitershortfall = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=225", + summary = "Minimum difference between formula height and delimiter height, by default 5pt." + }, + dimen = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/count", + documentation = "texmf:doc/plain/impatient/book.pdf#page=262", + summary = "The specified dimension register." + }, + dimendef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "register"} + }, + details = "$ref:teximpatient#/data/countdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Define a specified control sequence to be a number corresponding to a \\dimen register." + }, + discretionary = { + arguments = { + {meta = "pre-break text"}, + {meta = "post-break text"}, + {meta = "no-break text"} + }, + details = "$ref:teximpatient#/data/discretionary", + documentation = "texmf:doc/plain/impatient/book.pdf#page=147", + summary = "Specify three texts, the first two for before and after a line break, the third for no line break." + }, + displayindent = { + details = "$ref:teximpatient#/data/displayindent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=236", + summary = "TeX sets this to the indentation of a display.", + type = "dimen" + }, + displaylimits = { + details = "$ref:teximpatient#/data/displaylimits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=215", + summary = "Place limits above and below operators only in display styles." + }, + displaystyle = { + details = "$ref:teximpatient#/data/textstyle", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Use displaystyle size in a formula." + }, + displaywidowpenalty = { + details = "$ref:teximpatient#/data/displaywidowpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Penalty for a single line beginning a page just before a display, by default 50.", + type = "number" + }, + displaywidth = { + details = "$ref:teximpatient#/data/displaywidth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=236", + summary = "TeX sets this to the width of a display.", + type = "dimen" + }, + divide = { + arguments = { + {delimiters = {"", "by"}, meta = "register"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/multiply", + documentation = "texmf:doc/plain/impatient/book.pdf#page=266", + summary = "Divide a specified \\count register by a specified integer." + }, + doublehyphendemerits = { + details = "$ref:teximpatient#/data/doublehyphendemerits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=145", + summary = "Demerits for two consecutive lines ending with hyphens, by default 10000.", + type = "number" + }, + dp = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ht", + documentation = "texmf:doc/plain/impatient/book.pdf#page=187", + summary = "The depth of the box in a specified box register.", + type = "dimen" + }, + dump = { + details = "$ref:teximpatient#/data/dump", + documentation = "texmf:doc/plain/impatient/book.pdf#page=283", + summary = "End the job and produce a format file." + }, + edef = { + action = "def", + arguments = { + {delimiters = false, meta = "control sequence"}, + {delimiters = {"", "{"}, meta = "parameter text"}, + {delimiters = {"", "}"}, meta = "replacement text"} + }, + details = "$ref:teximpatient#/data/edef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=250", + summary = "Define a control sequence to be a macro, immediately expanding the replacement text." + }, + ["else"] = { + details = "$ref:teximpatient#/data/else", + documentation = "texmf:doc/plain/impatient/book.pdf#page=259", + summary = "False or default case alternative for a conditional." + }, + emergencystretch = { + details = "$ref:teximpatient#/data/emergencystretch", + documentation = "texmf:doc/plain/impatient/book.pdf#page=144", + summary = "Additional stretch added to every line if \\tol\\-er\\-ance is not satisfied.", + type = "dimen" + }, + ["end"] = { + details = "$ref:teximpatient#/data/end", + documentation = "texmf:doc/plain/impatient/book.pdf#page=267", + summary = "\\output the last page and end the job." + }, + endcsname = {summary = "End a control sequence name started by \\csname."}, + endgroup = { + details = "$ref:teximpatient#/data/begingroup", + documentation = "texmf:doc/plain/impatient/book.pdf#page=247", + summary = "End a group started by \\begingroup." + }, + endinput = { + details = "$ref:teximpatient#/data/endinput", + documentation = "texmf:doc/plain/impatient/book.pdf#page=267", + summary = "Terminate input from the current file." + }, + endlinechar = { + details = "$ref:teximpatient#/data/endlinechar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=272", + summary = "Character TeX inserts at the end of each input line, by default \\twocarets M.", + type = "number" + }, + eqno = { + details = "$ref:teximpatient#/data/eqno", + documentation = "texmf:doc/plain/impatient/book.pdf#page=227", + summary = "Put a specified equation number on the right of a display." + }, + errhelp = { + details = "$ref:teximpatient#/data/errhelp", + documentation = "texmf:doc/plain/impatient/book.pdf#page=282", + summary = "Token list whose expansion TeX displays when the user asks for help in response to an \\errmessage.", + type = "token list" + }, + errmessage = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/message", + documentation = "texmf:doc/plain/impatient/book.pdf#page=281", + summary = "Give specified error message." + }, + errorcontextlines = { + details = "$ref:teximpatient#/data/errorcontextlines", + documentation = "texmf:doc/plain/impatient/book.pdf#page=283", + summary = "The number of lines of context TeX displays at an error, by default 5.", + type = "number" + }, + errorstopmode = { + details = "$ref:teximpatient#/data/errorstopmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=272", + summary = "Stop for interaction at error messages." + }, + escapechar = { + details = "$ref:teximpatient#/data/escapechar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=246", + summary = "Character with which TeX precedes control sequence names that are displayed.", + type = "number" + }, + everycr = { + details = "$ref:teximpatient#/data/everycr", + documentation = "texmf:doc/plain/impatient/book.pdf#page=205", + summary = "Token list TeX expands after a \\cr, or a \\crcr not following \\cr or \\noalign.", + type = "token list" + }, + everydisplay = { + details = "$ref:teximpatient#/data/everymath", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Token list TeX expands when a math display begins.", + type = "token list" + }, + everyhbox = { + details = "$ref:teximpatient#/data/everyhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=184", + summary = "Token list TeX expands when an hbox begins.", + type = "token list" + }, + everyjob = { + details = "$ref:teximpatient#/data/everyjob", + documentation = "texmf:doc/plain/impatient/book.pdf#page=283", + summary = "Token list TeX expands when a job begins.", + type = "token list" + }, + everymath = { + details = "$ref:teximpatient#/data/everymath", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Token list TeX expands when text math mode begins.", + type = "token list" + }, + everypar = { + details = "$ref:teximpatient#/data/everypar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=133", + summary = "Token list TeX expands when a paragraph begins.", + type = "token list" + }, + everyvbox = { + details = "$ref:teximpatient#/data/everyhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=184", + summary = "Token list TeX expands when a vbox begins.", + type = "token list" + }, + exhyphenpenalty = { + details = "$ref:teximpatient#/data/exhyphenpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=145", + summary = "Additional penalty for a line break after an explicit hyphen, by default 50.", + type = "number" + }, + expandafter = { + arguments = { + {delimiters = false, meta = "token1"}, + {delimiters = false, meta = "token2"} + }, + details = "$ref:teximpatient#/data/expandafter", + documentation = "texmf:doc/plain/impatient/book.pdf#page=253", + summary = "Expand the next token only after expanding the token following it." + }, + fam = { + details = "$ref:teximpatient#/data/fam", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "Font family TeX uses for characters with class seven (i.e., variables) in math.", + type = "number" + }, + fi = { + details = "$ref:teximpatient#/data/fi", + documentation = "texmf:doc/plain/impatient/book.pdf#page=260", + summary = "End a conditional." + }, + finalhyphendemerits = { + details = "$ref:teximpatient#/data/finalhyphendemerits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=146", + summary = "Penalty for the second to last line breaking at a hyphen, by default 5000.", + type = "number" + }, + firstmark = { + details = "$ref:teximpatient#/data/firstmark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "First mark item on the page just boxed." + }, + floatingpenalty = { + details = "$ref:teximpatient#/data/floatingpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "Penalty for insertions that are split across pages, by default 0.", + type = "number" + }, + font = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = {"", "at"}, meta = "fontname"}, + {delimiters = false, meta = "dimen"} + }, + details = "$ref:teximpatient#/data/font", + documentation = "texmf:doc/plain/impatient/book.pdf#page=241", + summary = "Define a specified control sequence to select a font." + }, + fontdimen = { + arguments = { + {delimiters = false, meta = "number"}, + {delimiters = false, meta = "font"} + }, + details = "$ref:teximpatient#/data/fontdimen", + documentation = "texmf:doc/plain/impatient/book.pdf#page=242", + summary = "A specified parameter of a specified font.", + type = "dimen" + }, + fontname = { + arguments = {{delimiters = false, meta = "font"}}, + details = "$ref:teximpatient#/data/fontname", + documentation = "texmf:doc/plain/impatient/book.pdf#page=247", + summary = "Produce the filename of a specified font as characters." + }, + futurelet = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {delimiters = false, meta = "token1"}, + {delimiters = false, meta = "token2"} + }, + details = "$ref:teximpatient#/data/futurelet", + documentation = "texmf:doc/plain/impatient/book.pdf#page=252", + summary = "Assign the third following token to a specified control sequence, then expand the second following token." + }, + gdef = { + action = "def", + arguments = { + {delimiters = false, meta = "control sequence"}, + {delimiters = {"", "{"}, meta = "parameter text"}, + {delimiters = {"", "}"}, meta = "replacement text"} + }, + details = "$ref:teximpatient#/data/gdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=251", + summary = "Equivalent to \\global\\def, i.e., globally define a macro." + }, + global = { + details = "$ref:teximpatient#/data/global", + documentation = "texmf:doc/plain/impatient/book.pdf#page=248", + summary = "Make the following definition global." + }, + globaldefs = { + details = "$ref:teximpatient#/data/globaldefs", + documentation = "texmf:doc/plain/impatient/book.pdf#page=248", + summary = "Overrides \\global prefixes on assignments.", + type = "number" + }, + halign = { + arguments = { + {delimiters = {"to", ""}, meta = "dimen", optional = true}, + {delimiters = {"spread", ""}, meta = "dimen", optional = true}, + {delimiters = {"{", "}"}, meta = "rows"} + }, + details = "$ref:teximpatient#/data/halign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=198", + summary = "Align text in columns." + }, + hangafter = { + details = "$ref:teximpatient#/data/hangafter", + documentation = "texmf:doc/plain/impatient/book.pdf#page=137", + summary = "Starting line number for hanging indentation.", + type = "number" + }, + hangindent = { + details = "$ref:teximpatient#/data/hangafter", + documentation = "texmf:doc/plain/impatient/book.pdf#page=137", + summary = "Space for hanging indentation.", + type = "dimen" + }, + hbadness = { + details = "$ref:teximpatient#/data/hbadness", + documentation = "texmf:doc/plain/impatient/book.pdf#page=190", + summary = "Badness threshold for reporting underfull or overfull hboxes, by default 1000.", + type = "number" + }, + hbox = { + arguments = { + {delimiters = {"to", ""}, meta = "dimen", optional = true}, + {delimiters = {"spread", ""}, meta = "dimen", optional = true}, + {delimiters = {"{", "}"}, meta = "horizontal mode material"} + }, + details = "$ref:teximpatient#/data/hbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=180", + summary = "Produce a specified hbox." + }, + hfil = { + details = "$ref:teximpatient#/data/hfil", + documentation = "texmf:doc/plain/impatient/book.pdf#page=177", + summary = "Produce infinitely stretchable horizontal glue." + }, + hfill = { + details = "$ref:teximpatient#/data/hfil", + documentation = "texmf:doc/plain/impatient/book.pdf#page=177", + summary = "Produce horizontal glue even more infinitely stretchable than that produced by \\hfil." + }, + hfilneg = { + details = "$ref:teximpatient#/data/hfilneg", + documentation = "texmf:doc/plain/impatient/book.pdf#page=179", + summary = "Produce infinitely negative stretchable horizontal glue." + }, + hfuzz = { + details = "$ref:teximpatient#/data/hfuzz", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Space threshold for reporting overfull hboxes, by default 0.1pt.", + type = "dimen" + }, + hoffset = { + details = "$ref:teximpatient#/data/hoffset", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "Page offset relative to one inch from the paper’s left edge.", + type = "dimen" + }, + holdinginserts = { + details = "$ref:teximpatient#/data/holdinginserts", + documentation = "texmf:doc/plain/impatient/book.pdf#page=169", + summary = "If positive, do not remove insertions from the current page.", + type = "number" + }, + hrule = { + arguments = { + {delimiters = {"width", ""}, meta = "dimen", optional = true}, + {delimiters = {"height", ""}, meta = "dimen", optional = true}, + {delimiters = {"depth", ""}, meta = "dimen", optional = true} + }, + details = "$ref:teximpatient#/data/hrule", + documentation = "texmf:doc/plain/impatient/book.pdf#page=192", + summary = "Produce a horizontal rule; legal only in vertical modes." + }, + hsize = { + details = "$ref:teximpatient#/data/hsize", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "Line length, by default 6.5in.", + type = "dimen" + }, + hskip = { + arguments = { + {delimiters = {"", "plus"}, meta = "dimen1"}, + {delimiters = {"", "minus"}, meta = "dimen2"}, + {delimiters = false, meta = "dimen3"} + }, + details = "$ref:teximpatient#/data/hskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=175", + summary = "Produce specified horizontal glue." + }, + hss = { + details = "$ref:teximpatient#/data/hss", + documentation = "texmf:doc/plain/impatient/book.pdf#page=178", + summary = "Produce horizontal glue that is infinitely stretchable and infinitely shrinkable." + }, + ht = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ht", + documentation = "texmf:doc/plain/impatient/book.pdf#page=187", + summary = "The height of the box in a specified box register.", + type = "dimen" + }, + hyphenation = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=147", + summary = "Add specified words to the hyphenation exception dictionary." + }, + hyphenchar = { + arguments = {{delimiters = false, meta = "font"}}, + details = "$ref:teximpatient#/data/hyphenchar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=149", + summary = "The hyphenation character in a specified font.", + type = "number" + }, + hyphenpenalty = { + details = "$ref:teximpatient#/data/hyphenpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=145", + summary = "Additional penalty for a line break at a hyphen, by default 50.", + type = "number" + }, + ["if"] = { + arguments = { + {delimiters = false, meta = "token1"}, + {delimiters = false, meta = "token2"} + }, + details = "$ref:teximpatient#/data/if", + documentation = "texmf:doc/plain/impatient/book.pdf#page=255", + summary = "Test if two specified tokens have the same character code." + }, + ifcase = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=259", + summary = "Expand case n for specified value n." + }, + ifcat = { + arguments = { + {delimiters = false, meta = "token1"}, + {delimiters = false, meta = "token2"} + }, + details = "$ref:teximpatient#/data/ifcat", + documentation = "texmf:doc/plain/impatient/book.pdf#page=255", + summary = "Test if two specified tokens have the same category code." + }, + ifdim = { + arguments = { + {delimiters = false, meta = "dimen1"}, + {delimiters = false, meta = "relation"}, + {delimiters = false, meta = "dimen2"} + }, + details = "$ref:teximpatient#/data/ifdim", + documentation = "texmf:doc/plain/impatient/book.pdf#page=257", + summary = "Test for a specified relationship between two specified dimensions." + }, + ifeof = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/ifeof", + documentation = "texmf:doc/plain/impatient/book.pdf#page=259", + summary = "Test for being at the end of a specified file." + }, + iffalse = { + details = "$ref:teximpatient#/data/iftrue", + documentation = "texmf:doc/plain/impatient/book.pdf#page=259", + summary = "Test that is always false." + }, + ifhbox = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ifhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if a specified box register contains an hbox." + }, + ifhmode = { + details = "$ref:teximpatient#/data/ifhmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if TeX is in a horizontal mode." + }, + ifinner = { + details = "$ref:teximpatient#/data/ifhmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if TeX is in an internal mode." + }, + ifmmode = { + details = "$ref:teximpatient#/data/ifhmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if TeX is in a math mode." + }, + ifnum = { + arguments = { + {delimiters = false, meta = "number1"}, + {delimiters = false, meta = "relation"}, + {delimiters = false, meta = "number2"} + }, + details = "$ref:teximpatient#/data/ifnum", + documentation = "texmf:doc/plain/impatient/book.pdf#page=257", + summary = "Test for a specified relationship between two specified numbers." + }, + ifodd = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/ifodd", + documentation = "texmf:doc/plain/impatient/book.pdf#page=257", + summary = "Test if a specified number is odd." + }, + iftrue = { + details = "$ref:teximpatient#/data/iftrue", + documentation = "texmf:doc/plain/impatient/book.pdf#page=259", + summary = "Test that is always true." + }, + ifvbox = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ifhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if a specified box register contains a vbox." + }, + ifvmode = { + details = "$ref:teximpatient#/data/ifhmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if TeX is in a vertical mode." + }, + ifvoid = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ifhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=258", + summary = "Test if a specified box register is void." + }, + ifx = { + arguments = { + {delimiters = false, meta = "token1"}, + {delimiters = false, meta = "token2"} + }, + details = "$ref:teximpatient#/data/ifx", + documentation = "texmf:doc/plain/impatient/book.pdf#page=256", + summary = "Test if two tokens are the same, or if two macros have the same top-level definition." + }, + ignorespaces = { + details = "$ref:teximpatient#/data/ignorespaces", + documentation = "texmf:doc/plain/impatient/book.pdf#page=272", + summary = "Ignore any following space tokens." + }, + immediate = { + details = "$ref:teximpatient#/data/immediate", + documentation = "texmf:doc/plain/impatient/book.pdf#page=270", + summary = "Perform the specified file operation without delay." + }, + indent = { + details = "$ref:teximpatient#/data/indent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=131", + summary = "Produce an empty box of width \\parindent and enter horizontal mode." + }, + input = { + arguments = {{delimiters = false, meta = "filename"}}, + details = "$ref:teximpatient#/data/input", + documentation = "texmf:doc/plain/impatient/book.pdf#page=267", + summary = "Begin to read from a specified file." + }, + inputlineno = { + details = "$ref:teximpatient#/data/inputlineno", + documentation = "texmf:doc/plain/impatient/book.pdf#page=267", + summary = "The current line number of the current input file." + }, + insert = { + arguments = { + {delimiters = false, meta = "number"}, + {meta = "vertical mode material"} + }, + details = "$ref:teximpatient#/data/insert", + documentation = "texmf:doc/plain/impatient/book.pdf#page=167", + summary = "Produce an insertion of a specified class." + }, + insertpenalties = { + details = "$ref:teximpatient#/data/insertpenalties", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "Sum of penalties due to insertions.", + type = "number" + }, + interlinepenalty = { + details = "$ref:teximpatient#/data/interlinepenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Additional penalty for a page break between lines of a paragraph, by default 0.", + type = "number" + }, + jobname = { + details = "$ref:teximpatient#/data/jobname", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "Base name of the file with which TeX was invoked." + }, + kern = { + arguments = {{delimiters = false, meta = "dimen"}}, + details = "$ref:teximpatient#/data/kern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=177", + summary = "Produce a specified amount of space at which a break is not allowed." + }, + language = { + details = "$ref:teximpatient#/data/language", + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "The current set of hyphenation patterns.", + type = "number" + }, + lastbox = { + details = "$ref:teximpatient#/data/lastkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Retrieve and remove the last item from the current list, if it’s a box." + }, + lastkern = { + details = "$ref:teximpatient#/data/lastkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Retrieve the last item from the current list, if it’s a kern." + }, + lastpenalty = { + details = "$ref:teximpatient#/data/lastkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Retrieve the last item from the current list, if it’s a penalty." + }, + lastskip = { + details = "$ref:teximpatient#/data/lastkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Retrieve the last item from the current list, if it’s glue." + }, + lccode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/lccode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "The character code for the lowercase form of a letter." + }, + leaders = { + arguments = { + {delimiters = false, meta = "box or rule"}, + {delimiters = false, meta = "skip command"} + }, + details = "$ref:teximpatient#/data/leaders", + documentation = "texmf:doc/plain/impatient/book.pdf#page=194", + summary = "Fill a specified horizontal or vertical space by repeating a specified box or rule." + }, + left = { + details = "$ref:teximpatient#/data/left", + documentation = "texmf:doc/plain/impatient/book.pdf#page=224", + summary = "Produce the specified delimiter, sizing it to cover the following subformula ended by \\right." + }, + lefthyphenmin = { + details = "$ref:teximpatient#/data/lefthyphenmin", + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "Size of the smallest word fragment TeX allows before a hyphen at the beginning of a word, by default 2.", + type = "number" + }, + leftskip = { + details = "$ref:teximpatient#/data/leftskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=135", + summary = "Glue TeX inserts at the left of each line.", + type = "glue" + }, + leqno = { + details = "$ref:teximpatient#/data/eqno", + documentation = "texmf:doc/plain/impatient/book.pdf#page=227", + summary = "Put a specified equation number on the left of a display." + }, + let = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "token"} + }, + details = "$ref:teximpatient#/data/let", + documentation = "texmf:doc/plain/impatient/book.pdf#page=252", + summary = "Define a control sequence to be the next token." + }, + limits = { + details = "$ref:teximpatient#/data/limits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=215", + summary = "Place superscript above and subscript below a large operator." + }, + linepenalty = { + details = "$ref:teximpatient#/data/linepenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=145", + summary = "Penalty for line breaking added to each line, by default 10.", + type = "number" + }, + lineskip = { + details = "$ref:teximpatient#/data/baselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=153", + summary = "Vertical glue from one baseline to the next if the lines are closer together than \\lineskiplimit, by default 1pt.", + type = "glue" + }, + lineskiplimit = { + details = "$ref:teximpatient#/data/baselineskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=153", + summary = "Threshold for using \\lineskip instead of \\base\\-line\\-skip, by default 0pt.", + type = "dimen" + }, + long = { + details = "$ref:teximpatient#/data/long", + documentation = "texmf:doc/plain/impatient/book.pdf#page=251", + summary = "Allow \\par tokens in the argument(s) of the following definition." + }, + looseness = { + details = "$ref:teximpatient#/data/looseness", + documentation = "texmf:doc/plain/impatient/book.pdf#page=144", + summary = "Difference between the number of lines you want a paragraph to be relative to the optimal number.", + type = "number" + }, + lower = { + arguments = { + {delimiters = false, meta = "dimen"}, + {delimiters = false, meta = "box"} + }, + details = "$ref:teximpatient#/data/lower", + documentation = "texmf:doc/plain/impatient/book.pdf#page=186", + summary = "Lower a specified box by a specified amount." + }, + lowercase = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/lowercase", + documentation = "texmf:doc/plain/impatient/book.pdf#page=124", + summary = "Convert uppercase letters in the specified text to lowercase." + }, + mag = { + details = "$ref:teximpatient#/data/magnification", + documentation = "texmf:doc/plain/impatient/book.pdf#page=243", + summary = "1000 times the ratio for enlarging all dimensions.", + type = "number" + }, + mark = { + arguments = {{meta = "text"}}, + details = "$ref:teximpatient#/data/mark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "Produce a mark item with a specified text." + }, + mathaccent = { + arguments = {{delimiters = false, meta = "mathcode"}}, + details = "$ref:teximpatient#/data/mathaccent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=219", + summary = "Put specified math accent over the next character." + }, + mathbin = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as a binary operator." + }, + mathchar = { + arguments = {{delimiters = false, meta = "mathcode"}}, + details = "$ref:teximpatient#/data/mathchar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=119", + summary = "Produce the math character with the specified mathcode." + }, + mathchardef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "mathcode"} + }, + details = "$ref:teximpatient#/data/mathchardef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=252", + summary = "Define a specified control sequence to be a mathcode, a number between 0 and 215 − 1." + }, + mathchoice = { + details = "$ref:teximpatient#/data/mathchoice", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Select one of four specified math subformulas depending on the current style." + }, + mathclose = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as a closing delimiter." + }, + mathcode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/mathcode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=271", + summary = "The mathcode of a specified character." + }, + mathinner = { + details = "$ref:teximpatient#/data/mathinner", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as an inner formula, e.g., a fraction." + }, + mathop = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as a large math operator." + }, + mathopen = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as an opening delimiter." + }, + mathord = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as an ordinary character." + }, + mathpunct = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as punctuation." + }, + mathrel = { + details = "$ref:teximpatient#/data/mathord", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Space a specified subformula as a relation." + }, + mathsurround = { + details = "$ref:teximpatient#/data/mathsurround", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Space TeX kerns before and after math in text.", + type = "dimen" + }, + maxdeadcycles = { + details = "$ref:teximpatient#/data/maxdeadcycles", + documentation = "texmf:doc/plain/impatient/book.pdf#page=168", + summary = "Value of \\deadcycles at which TeX complains, and then uses its own output routine, by default 25.", + type = "number" + }, + maxdepth = { + details = "$ref:teximpatient#/data/maxdepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=161", + summary = "Maximum depth of the bottom box on a page, by default 4pt.", + type = "dimen" + }, + meaning = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/meaning", + documentation = "texmf:doc/plain/impatient/book.pdf#page=246", + summary = "Produce the human-understandable meaning of a specified token as characters." + }, + medmuskip = { + details = "$ref:teximpatient#/data/thinmuskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Glue for a medium math space, by default 4mu plus 2mu minus 4mu.", + type = "muglue" + }, + message = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/message", + documentation = "texmf:doc/plain/impatient/book.pdf#page=281", + summary = "Show expansion of the specified text on the terminal." + }, + mkern = { + arguments = {{delimiters = false, meta = "mudimen"}}, + details = "$ref:teximpatient#/data/mkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=235", + summary = "Produce a specified kern in units of mu for math." + }, + month = { + details = "$ref:teximpatient#/data/month", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "Current month, as a number.", + type = "number" + }, + moveleft = { + arguments = { + {delimiters = false, meta = "dimen"}, + {delimiters = false, meta = "box"} + }, + details = "$ref:teximpatient#/data/moveleft", + documentation = "texmf:doc/plain/impatient/book.pdf#page=186", + summary = "Move a specified box left by a specified space; legal only in vertical modes." + }, + moveright = { + arguments = { + {delimiters = false, meta = "dimen"}, + {delimiters = false, meta = "box"} + }, + details = "$ref:teximpatient#/data/moveleft", + documentation = "texmf:doc/plain/impatient/book.pdf#page=186", + summary = "Move a specified box right by a specified space; legal only in vertical modes." + }, + mskip = { + arguments = { + {delimiters = {"", "plus"}, meta = "mudimen1"}, + {delimiters = {"", "minus"}, meta = "mudimen2"}, + {delimiters = false, meta = "mudimen3"} + }, + details = "$ref:teximpatient#/data/mskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=235", + summary = "Produce specified glue in units of mu for math." + }, + multiply = { + arguments = { + {delimiters = {"", "by"}, meta = "register"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/multiply", + documentation = "texmf:doc/plain/impatient/book.pdf#page=266", + summary = "Multiply a specified \\count register by a specified integer." + }, + muskip = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/count", + documentation = "texmf:doc/plain/impatient/book.pdf#page=262", + summary = "The specified muglue register." + }, + muskipdef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "register"} + }, + details = "$ref:teximpatient#/data/countdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Define a specified control sequence to be a number corresponding to a \\muskip register." + }, + newinsert = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=264", + summary = "Name an insertion class, and reserve a corresponding \\box, \\count, \\dimen, and \\skip registers." + }, + newlinechar = { + details = "$ref:teximpatient#/data/newlinechar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=270", + summary = "End-of-line character for \\write, etc..", + type = "number" + }, + noalign = { + arguments = {{meta = "horizontal mode material"}}, + details = "$ref:teximpatient#/data/noalign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=203", + summary = "Insert material between rows (or columns) of an alignment." + }, + noboundary = { + details = "$ref:teximpatient#/data/noboundary", + documentation = "texmf:doc/plain/impatient/book.pdf#page=121", + summary = "Inhibit ligatures or kerns involving the current font’s boundarychar." + }, + noexpand = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/noexpand", + documentation = "texmf:doc/plain/impatient/book.pdf#page=254", + summary = "Suppress expansion of the next token." + }, + noindent = { + details = "$ref:teximpatient#/data/noindent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=132", + summary = "Enter horizontal mode without indenting the paragraph." + }, + nolimits = { + details = "$ref:teximpatient#/data/nolimits", + documentation = "texmf:doc/plain/impatient/book.pdf#page=215", + summary = "Place superscript and subscript after large operators." + }, + nonscript = { + details = "$ref:teximpatient#/data/nonscript", + documentation = "texmf:doc/plain/impatient/book.pdf#page=235", + summary = "Inhibit any following glue or kern when in script and scriptscript styles." + }, + nonstopmode = { + details = "$ref:teximpatient#/data/nonstopmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Don’t stop at errors, even those about missing files." + }, + nulldelimiterspace = { + details = "$ref:teximpatient#/data/nulldelimiterspace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=237", + summary = "Space produced by a null delimiter, by default 1.2pt.", + type = "dimen" + }, + nullfont = { + details = "$ref:teximpatient#/data/nullfont", + documentation = "texmf:doc/plain/impatient/book.pdf#page=122", + summary = "Primitive font with no characters in it." + }, + number = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/number", + documentation = "texmf:doc/plain/impatient/book.pdf#page=244", + summary = "Produce a specified number as characters." + }, + omit = { + details = "$ref:teximpatient#/data/omit", + documentation = "texmf:doc/plain/impatient/book.pdf#page=201", + summary = "Skip a column’s (or row’s) template in an alignment." + }, + openin = { + arguments = { + {delimiters = false, meta = "number"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "filename"} + }, + details = "$ref:teximpatient#/data/openin", + documentation = "texmf:doc/plain/impatient/book.pdf#page=267", + summary = "Prepare a specified input stream to read from a file." + }, + openout = { + arguments = { + {delimiters = false, meta = "number"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "filename"} + }, + details = "$ref:teximpatient#/data/openout", + documentation = "texmf:doc/plain/impatient/book.pdf#page=269", + summary = "Prepare a specified output stream to write to a file." + }, + ["or"] = {summary = "Separate the cases of an \\ifcase."}, + outer = { + details = "$ref:teximpatient#/data/outer", + documentation = "texmf:doc/plain/impatient/book.pdf#page=252", + summary = "Make the following macro definition illegal in contexts in which tokens are absorbed at high speed." + }, + output = { + details = "$ref:teximpatient#/data/output", + documentation = "texmf:doc/plain/impatient/book.pdf#page=168", + summary = "Token list TeX expands when it finds a page break.", + type = "token list" + }, + outputpenalty = { + details = "$ref:teximpatient#/data/outputpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=169", + summary = "If the page break occurred at a penalty, the value of that penalty; otherwise zero.", + type = "number" + }, + over = { + details = "$ref:teximpatient#/data/over", + documentation = "texmf:doc/plain/impatient/book.pdf#page=220", + summary = "Produce a fraction with a bar of default thickness." + }, + overfullrule = { + details = "$ref:teximpatient#/data/overfullrule", + documentation = "texmf:doc/plain/impatient/book.pdf#page=190", + summary = "Width of the rule appended to an overfull box.", + type = "dimen" + }, + overline = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Produce a line covering the top of a formula, as in $\\overline{2b}$." + }, + overwithdelims = { + arguments = { + {delimiters = false, meta = "delim1"}, + {delimiters = false, meta = "delim2"} + }, + details = "$ref:teximpatient#/data/overwithdelims", + documentation = "texmf:doc/plain/impatient/book.pdf#page=221", + summary = "Produce a fraction with a bar of the default thickness and surrounded by specified delimiters." + }, + pagedepth = { + details = "$ref:teximpatient#/data/pagedepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "TeX sets this to the current depth of the current page.", + type = "dimen" + }, + pagefilllstretch = { + details = "$ref:teximpatient#/data/pagestretch", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "TeX sets this to the amount of filll stretch on the current page.", + type = "dimen" + }, + pagefillstretch = { + details = "$ref:teximpatient#/data/pagestretch", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "TeX sets this to the amount of fill stretch on the current page.", + type = "dimen" + }, + pagefilstretch = { + details = "$ref:teximpatient#/data/pagestretch", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "TeX sets this to the amount of fil stretch on the current page.", + type = "dimen" + }, + pagegoal = { + details = "$ref:teximpatient#/data/pagegoal", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "TeX sets this to the desired height for the current page (i.e., \\vsize when the first box is put on the page).", + type = "dimen" + }, + pageshrink = { + details = "$ref:teximpatient#/data/pageshrink", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "TeX sets this to the total amount of shrinkability on the current page.", + type = "dimen" + }, + pagestretch = { + details = "$ref:teximpatient#/data/pagestretch", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "TeX sets this to the total amount of stretchability on the current page.", + type = "dimen" + }, + pagetotal = { + details = "$ref:teximpatient#/data/pagetotal", + documentation = "texmf:doc/plain/impatient/book.pdf#page=159", + summary = "TeX sets this to the natural height of the current page.", + type = "dimen" + }, + par = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=130", + summary = "Finish paragraph and terminate horizontal mode." + }, + parfillskip = { + details = "$ref:teximpatient#/data/parfillskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=131", + summary = "Horizontal glue TeX inserts at the end of a paragraph.", + type = "glue" + }, + parindent = { + details = "$ref:teximpatient#/data/parindent", + documentation = "texmf:doc/plain/impatient/book.pdf#page=133", + summary = "Horizontal space TeX inserts at the start of a paragraph.", + type = "dimen" + }, + parshape = { + details = "$ref:teximpatient#/data/parshape", + documentation = "texmf:doc/plain/impatient/book.pdf#page=138", + summary = "Specify the width and length of each line in the next paragraph." + }, + parskip = { + details = "$ref:teximpatient#/data/parskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=161", + summary = "Vertical glue TeX inserts before a paragraph.", + type = "glue" + }, + pausing = { + details = "$ref:teximpatient#/data/pausing", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "If positive, stop after reading each line of input for a possible replacement.", + type = "number" + }, + penalty = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/penalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=156", + summary = "Produce penalty (or bonus, if negative) for breaking line or page here." + }, + postdisplaypenalty = { + details = "$ref:teximpatient#/data/postdisplaypenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Additional penalty for a line break just after a display, by default 0.", + type = "number" + }, + predisplaypenalty = { + details = "$ref:teximpatient#/data/predisplaypenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Additional penalty for a line break just before a display, by default 0.", + type = "number" + }, + predisplaysize = { + details = "$ref:teximpatient#/data/predisplaysize", + documentation = "texmf:doc/plain/impatient/book.pdf#page=236", + summary = "TeX sets this to the width of the line preceding a display.", + type = "dimen" + }, + pretolerance = { + details = "$ref:teximpatient#/data/pretolerance", + documentation = "texmf:doc/plain/impatient/book.pdf#page=143", + summary = "Badness tolerance for line breaks without hyphenation, by default 100.", + type = "number" + }, + prevdepth = { + details = "$ref:teximpatient#/data/prevdepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=154", + summary = "Depth of the last nonrule box on the current vertical list.", + type = "dimen" + }, + prevgraf = { + details = "$ref:teximpatient#/data/prevgraf", + documentation = "texmf:doc/plain/impatient/book.pdf#page=140", + summary = "TeX sets this to the number of lines in the paragraph so far (in horizontal mode) or in the previous paragraph (in vertical mode).", + type = "number" + }, + radical = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/radical", + documentation = "texmf:doc/plain/impatient/book.pdf#page=227", + summary = "Produce a specified radical symbol." + }, + raise = { + arguments = { + {delimiters = false, meta = "dimen"}, + {delimiters = false, meta = "box"} + }, + details = "$ref:teximpatient#/data/lower", + documentation = "texmf:doc/plain/impatient/book.pdf#page=186", + summary = "Raise a specified box by a specified amount." + }, + read = { + documentation = "texmf:doc/plain/impatient/book.pdf#page=268", + summary = "Read a line from a specified input stream." + }, + relax = { + details = "$ref:teximpatient#/data/relax", + documentation = "texmf:doc/plain/impatient/book.pdf#page=261", + summary = "Do nothing." + }, + relpenalty = { + details = "$ref:teximpatient#/data/relpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=146", + summary = "Additional penalty for breaking after a relation, by default 500.", + type = "number" + }, + right = { + details = "$ref:teximpatient#/data/left", + documentation = "texmf:doc/plain/impatient/book.pdf#page=224", + summary = "Produce the specified delimiter at the right end of a subformula started with \\left." + }, + righthyphenmin = { + details = "$ref:teximpatient#/data/lefthyphenmin", + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "Size of the smallest word fragment TeX allows after a hyphen at the end of a word, by default 3.", + type = "number" + }, + rightskip = { + details = "$ref:teximpatient#/data/leftskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=135", + summary = "Glue TeX inserts at the right of each line.", + type = "glue" + }, + scriptfont = { + arguments = {{delimiters = false, meta = "family"}}, + details = "$ref:teximpatient#/data/textfont", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "The script style font in a specified math family.", + type = "fontname" + }, + scriptscriptfont = { + arguments = {{delimiters = false, meta = "family"}}, + details = "$ref:teximpatient#/data/textfont", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "The scriptscript style font in a specified math family.", + type = "fontname" + }, + scriptscriptstyle = { + details = "$ref:teximpatient#/data/textstyle", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Use scriptscriptstyle size in a formula." + }, + scriptspace = { + details = "$ref:teximpatient#/data/scriptspace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=238", + summary = "Additional space TeX kerns after a subscript or superscript, by default 0.5pt.", + type = "dimen" + }, + scriptstyle = { + details = "$ref:teximpatient#/data/textstyle", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Use scriptstyle size in a formula." + }, + scrollmode = { + details = "$ref:teximpatient#/data/scrollmode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=272", + summary = "Don’t stop at most errors, but do stop at errors about missing files." + }, + setbox = { + arguments = { + {delimiters = false, meta = "register"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "box"} + }, + details = "$ref:teximpatient#/data/setbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=184", + summary = "Define a specified box register to be a box." + }, + setlanguage = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/setlanguage", + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "Change to a specified set of hyphenation rules, but don’t change \\language." + }, + sfcode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/spacefactor", + documentation = "texmf:doc/plain/impatient/book.pdf#page=127", + summary = "The space factor code of a specified character." + }, + shipout = { + arguments = {{delimiters = false, meta = "box"}}, + details = "$ref:teximpatient#/data/shipout", + documentation = "texmf:doc/plain/impatient/book.pdf#page=168", + summary = "Output a box to the .dvi file." + }, + show = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/show", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Show, in the log and on the terminal, the meaning of a specified token." + }, + showbox = { + arguments = {{delimiters = false, meta = "number"}}, + details = "$ref:teximpatient#/data/show", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Display the contents of a specified box register." + }, + showboxbreadth = { + details = "$ref:teximpatient#/data/showboxbreadth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=281", + summary = "Maximum number of items shown on each nesting level, by default 5.", + type = "number" + }, + showboxdepth = { + details = "$ref:teximpatient#/data/showboxdepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=281", + summary = "Maximum nesting level shown, by default 3.", + type = "number" + }, + showlists = { + details = "$ref:teximpatient#/data/show", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Display all lists being worked on." + }, + showthe = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/show", + documentation = "texmf:doc/plain/impatient/book.pdf#page=273", + summary = "Show, in the log and on the terminal, what \\the would produce." + }, + skewchar = { + arguments = {{delimiters = false, meta = "font"}}, + details = "$ref:teximpatient#/data/skewchar", + documentation = "texmf:doc/plain/impatient/book.pdf#page=233", + summary = "Character in a specified font used for positioning accents.", + type = "number" + }, + skip = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/count", + documentation = "texmf:doc/plain/impatient/book.pdf#page=262", + summary = "The specified glue register." + }, + skipdef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "register"} + }, + details = "$ref:teximpatient#/data/countdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Define a specified control sequence to be a number corresponding to a \\skip register." + }, + spacefactor = { + details = "$ref:teximpatient#/data/spacefactor", + documentation = "texmf:doc/plain/impatient/book.pdf#page=127", + summary = "Modifies stretch and shrink of interword glue if not 1000.", + type = "number" + }, + spaceskip = { + details = "$ref:teximpatient#/data/spacefactor", + documentation = "texmf:doc/plain/impatient/book.pdf#page=127", + summary = "If nonzero and \\spacefactor < 2000, overrides the normal interword glue.", + type = "glue" + }, + span = { + details = "$ref:teximpatient#/data/span", + documentation = "texmf:doc/plain/impatient/book.pdf#page=201", + summary = "Either combine entries in an alignment body or expand tokens in a preamble." + }, + special = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/special", + documentation = "texmf:doc/plain/impatient/book.pdf#page=270", + summary = "Write tokens to the .dvi file to be interpreted by a DVI-reading program." + }, + splitbotmark = { + details = "$ref:teximpatient#/data/splitfirstmark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "Last mark item in a box resulting from \\vsplit." + }, + splitfirstmark = { + details = "$ref:teximpatient#/data/splitfirstmark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "First mark item in a box resulting from \\vsplit." + }, + splitmaxdepth = { + details = "$ref:teximpatient#/data/splitmaxdepth", + documentation = "texmf:doc/plain/impatient/book.pdf#page=170", + summary = "Maximum depth of a box resulting from \\vsplit.", + type = "dimen" + }, + splittopskip = { + details = "$ref:teximpatient#/data/splittopskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=170", + summary = "Glue TeX inserts at the top of a box resulting from \\vsplit.", + type = "glue" + }, + string = { + arguments = {{delimiters = false, meta = "control sequence"}}, + details = "$ref:teximpatient#/data/string", + documentation = "texmf:doc/plain/impatient/book.pdf#page=246", + summary = "Produce a specified token, most commonly a control sequence, as characters." + }, + tabskip = { + details = "$ref:teximpatient#/data/tabskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=204", + summary = "Glue between columns (or rows) of an alignment.", + type = "glue" + }, + textfont = { + arguments = {{delimiters = false, meta = "family"}}, + details = "$ref:teximpatient#/data/textfont", + documentation = "texmf:doc/plain/impatient/book.pdf#page=230", + summary = "The text style font in a specified math family.", + type = "fontname" + }, + textstyle = { + details = "$ref:teximpatient#/data/textstyle", + documentation = "texmf:doc/plain/impatient/book.pdf#page=218", + summary = "Use textstyle size in a formula." + }, + the = { + arguments = {{delimiters = false, meta = "token"}}, + details = "$ref:teximpatient#/data/the", + documentation = "texmf:doc/plain/impatient/book.pdf#page=254", + summary = "Give the value of a specified token." + }, + thickmuskip = { + details = "$ref:teximpatient#/data/thinmuskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Glue for a thick math space, by default 5mu plus 5mu.", + type = "muglue" + }, + thinmuskip = { + details = "$ref:teximpatient#/data/thinmuskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=234", + summary = "Glue for a thin math space, by default 3mu.", + type = "muglue" + }, + time = { + details = "$ref:teximpatient#/data/time", + documentation = "texmf:doc/plain/impatient/book.pdf#page=244", + summary = "The time of day, in minutes since midnight.", + type = "number" + }, + toks = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/count", + documentation = "texmf:doc/plain/impatient/book.pdf#page=262", + summary = "The specified token register." + }, + toksdef = { + arguments = { + {delimiters = false, meta = "control sequence"}, + {literal = "=", optional = true}, + {delimiters = false, meta = "register"} + }, + details = "$ref:teximpatient#/data/countdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=265", + summary = "Define a specified control sequence to be a number corresponding to a \\toks register." + }, + tolerance = { + details = "$ref:teximpatient#/data/pretolerance", + documentation = "texmf:doc/plain/impatient/book.pdf#page=143", + summary = "Badness tolerance for line breaks with hyphenation.", + type = "number" + }, + topmark = { + details = "$ref:teximpatient#/data/firstmark", + documentation = "texmf:doc/plain/impatient/book.pdf#page=164", + summary = "\\botmark before the current page was boxed." + }, + topskip = { + details = "$ref:teximpatient#/data/topskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=161", + summary = "Glue between the headline and the first line of text on a page, by default 10pt.", + type = "glue" + }, + tracingcommands = { + details = "$ref:teximpatient#/data/tracingcommands", + documentation = "texmf:doc/plain/impatient/book.pdf#page=277", + summary = "Display execution of commands.", + type = "number" + }, + tracinglostchars = { + details = "$ref:teximpatient#/data/tracinglostchars", + documentation = "texmf:doc/plain/impatient/book.pdf#page=277", + summary = "Display characters that are asked for, but not defined.", + type = "number" + }, + tracingmacros = { + details = "$ref:teximpatient#/data/tracingmacros", + documentation = "texmf:doc/plain/impatient/book.pdf#page=278", + summary = "Display macro expansions.", + type = "number" + }, + tracingonline = { + details = "$ref:teximpatient#/data/tracingonline", + documentation = "texmf:doc/plain/impatient/book.pdf#page=276", + summary = "Show diagnostic output on the terminal as well as in the log file.", + type = "number" + }, + tracingoutput = { + details = "$ref:teximpatient#/data/tracingoutput", + documentation = "texmf:doc/plain/impatient/book.pdf#page=278", + summary = "Display contents of shipped-out boxes.", + type = "number" + }, + tracingpages = { + details = "$ref:teximpatient#/data/tracingpages", + documentation = "texmf:doc/plain/impatient/book.pdf#page=279", + summary = "Display page break calculations.", + type = "number" + }, + tracingparagraphs = { + details = "$ref:teximpatient#/data/tracingparagraphs", + documentation = "texmf:doc/plain/impatient/book.pdf#page=280", + summary = "Display line break calculations.", + type = "number" + }, + tracingrestores = { + details = "$ref:teximpatient#/data/tracingrestores", + documentation = "texmf:doc/plain/impatient/book.pdf#page=280", + summary = "Display values restored at the end of a group.", + type = "number" + }, + tracingstats = { + details = "$ref:teximpatient#/data/tracingstats", + documentation = "texmf:doc/plain/impatient/book.pdf#page=280", + summary = "Display memory usage statistics.", + type = "number" + }, + uccode = { + arguments = { + {delimiters = false, meta = "charcode"}, + {delimiters = false, meta = "number"} + }, + details = "$ref:teximpatient#/data/lccode", + documentation = "texmf:doc/plain/impatient/book.pdf#page=123", + summary = "The character code for the uppercase form of a letter." + }, + uchyph = { + details = "$ref:teximpatient#/data/uchyph", + documentation = "texmf:doc/plain/impatient/book.pdf#page=148", + summary = "If positive, consider hyphenating words that start with a capital letter.", + type = "number" + }, + underline = { + arguments = {{meta = "argument"}}, + details = "$ref:teximpatient#/data/underbrace", + documentation = "texmf:doc/plain/impatient/book.pdf#page=222", + summary = "Underline a math formula below the descenders, as in $\\underline{x+y}$." + }, + unhbox = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/unhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=185", + summary = "Append the contents of the box in a specified box register to the current list, and void the register; legal only in horizontal modes." + }, + unhcopy = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/unhcopy", + documentation = "texmf:doc/plain/impatient/book.pdf#page=185", + summary = "Like \\unhbox, but doesn’t void the register." + }, + unkern = { + details = "$ref:teximpatient#/data/unkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=192", + summary = "If the last item on the current list is a kern, remove it." + }, + unpenalty = { + details = "$ref:teximpatient#/data/unkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=192", + summary = "If the last item on the current list is a penalty, remove it." + }, + unskip = { + details = "$ref:teximpatient#/data/unkern", + documentation = "texmf:doc/plain/impatient/book.pdf#page=192", + summary = "If the last item on the current list is glue, remove it." + }, + unvbox = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/unhbox", + documentation = "texmf:doc/plain/impatient/book.pdf#page=185", + summary = "Append the contents of the box in a specified box register to the current list, and void the register; legal only in vertical modes." + }, + unvcopy = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/unhcopy", + documentation = "texmf:doc/plain/impatient/book.pdf#page=185", + summary = "Like \\unvbox, but doesn’t void the register." + }, + uppercase = { + arguments = {{meta = "token list"}}, + details = "$ref:teximpatient#/data/lowercase", + documentation = "texmf:doc/plain/impatient/book.pdf#page=124", + summary = "Convert lowercase letters in the specified text to uppercase." + }, + vadjust = { + arguments = {{meta = "vertical mode material"}}, + details = "$ref:teximpatient#/data/vadjust", + documentation = "texmf:doc/plain/impatient/book.pdf#page=140", + summary = "Produce vertical mode material after the current line." + }, + valign = { + arguments = { + {delimiters = {"to", ""}, meta = "dimen", optional = true}, + {delimiters = {"spread", ""}, meta = "dimen", optional = true}, + {delimiters = {"{", "}"}, meta = "columns"} + }, + details = "$ref:teximpatient#/data/valign", + documentation = "texmf:doc/plain/impatient/book.pdf#page=199", + summary = "Align text in rows." + }, + vbadness = { + details = "$ref:teximpatient#/data/hbadness", + documentation = "texmf:doc/plain/impatient/book.pdf#page=190", + summary = "Badness threshold for reporting underfull or overfull vboxes, by default 1000.", + type = "number" + }, + vbox = { + arguments = { + {delimiters = {"to", ""}, meta = "dimen", optional = true}, + {delimiters = {"spread", ""}, meta = "dimen", optional = true}, + {delimiters = {"{", "}"}, meta = "vertical mode material"} + }, + details = "$ref:teximpatient#/data/vtop", + documentation = "texmf:doc/plain/impatient/book.pdf#page=181", + summary = "Produce a vbox whose baseline is that of the bottom box enclosed." + }, + vcenter = { + arguments = {{meta = "vertical mode material"}}, + details = "$ref:teximpatient#/data/vcenter", + documentation = "texmf:doc/plain/impatient/book.pdf#page=233", + summary = "Center the specified text on the math axis." + }, + vfil = { + details = "$ref:teximpatient#/data/hfil", + documentation = "texmf:doc/plain/impatient/book.pdf#page=177", + summary = "Produce infinitely stretchable vertical glue." + }, + vfill = { + details = "$ref:teximpatient#/data/hfil", + documentation = "texmf:doc/plain/impatient/book.pdf#page=177", + summary = "Produce even more infinitely stretchable vertical glue than that produced by \\vfil." + }, + vfilneg = { + details = "$ref:teximpatient#/data/hfilneg", + documentation = "texmf:doc/plain/impatient/book.pdf#page=179", + summary = "Produce infinitely negative stretchable vertical glue." + }, + vfuzz = { + details = "$ref:teximpatient#/data/hfuzz", + documentation = "texmf:doc/plain/impatient/book.pdf#page=191", + summary = "Space threshold for reporting overfull vboxes, by default 0.1pt.", + type = "dimen" + }, + voffset = { + details = "$ref:teximpatient#/data/hoffset", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "Vertical offset relative to one inch from the paper’s top edge.", + type = "dimen" + }, + vrule = { + arguments = { + {delimiters = {"width", ""}, meta = "dimen", optional = true}, + {delimiters = {"height", ""}, meta = "dimen", optional = true}, + {delimiters = {"depth", ""}, meta = "dimen", optional = true} + }, + details = "$ref:teximpatient#/data/hrule", + documentation = "texmf:doc/plain/impatient/book.pdf#page=192", + summary = "Produce a vertical rule; legal only in horizontal modes." + }, + vsize = { + details = "$ref:teximpatient#/data/vsize", + documentation = "texmf:doc/plain/impatient/book.pdf#page=160", + summary = "Page height, by default 8.9in.", + type = "dimen" + }, + vskip = { + arguments = { + {delimiters = {"", "plus"}, meta = "dimen1"}, + {delimiters = {"", "minus"}, meta = "dimen2"}, + {delimiters = false, meta = "dimen3"} + }, + details = "$ref:teximpatient#/data/hskip", + documentation = "texmf:doc/plain/impatient/book.pdf#page=175", + summary = "Produce specified vertical glue." + }, + vsplit = { + arguments = { + {delimiters = {"", "to"}, meta = "number"}, + {delimiters = false, meta = "dimen"} + }, + details = "$ref:teximpatient#/data/vsplit", + documentation = "texmf:doc/plain/impatient/book.pdf#page=169", + summary = "Break the contents of a specified box register to the specified height." + }, + vss = { + details = "$ref:teximpatient#/data/hss", + documentation = "texmf:doc/plain/impatient/book.pdf#page=178", + summary = "Produce vertical glue that is infinitely stretchable and infinitely shrinkable." + }, + vtop = { + arguments = { + {delimiters = {"to", ""}, meta = "dimen", optional = true}, + {delimiters = {"spread", ""}, meta = "dimen", optional = true}, + {delimiters = {"{", "}"}, meta = "vertical mode material"} + }, + details = "$ref:teximpatient#/data/vtop", + documentation = "texmf:doc/plain/impatient/book.pdf#page=181", + summary = "Produce a vbox whose baseline is that of the top box enclosed." + }, + wd = { + arguments = {{delimiters = false, meta = "register"}}, + details = "$ref:teximpatient#/data/ht", + documentation = "texmf:doc/plain/impatient/book.pdf#page=187", + summary = "The width of the box in a specified box register.", + type = "dimen" + }, + widowpenalty = { + details = "$ref:teximpatient#/data/widowpenalty", + documentation = "texmf:doc/plain/impatient/book.pdf#page=158", + summary = "Penalty for a single line beginning a page, by default 150.", + type = "number" + }, + write = { + arguments = {{delimiters = false, meta = "number"}, {meta = "token list"}}, + details = "$ref:teximpatient#/data/write", + documentation = "texmf:doc/plain/impatient/book.pdf#page=269", + summary = "Write a line to a specified output stream." + }, + xdef = { + action = "def", + arguments = { + {delimiters = false, meta = "control sequence"}, + {delimiters = {"", "{"}, meta = "parameter text"}, + {delimiters = {"", "}"}, meta = "replacement text"} + }, + details = "$ref:teximpatient#/data/xdef", + documentation = "texmf:doc/plain/impatient/book.pdf#page=251", + summary = "Equivalent to \\global\\edef, i.e., globally define a macro, immediately expanding the replacement text." + }, + xleaders = { + arguments = { + {delimiters = false, meta = "box or rule"}, + {delimiters = false, meta = "skip command"} + }, + details = "$ref:teximpatient#/data/leaders", + documentation = "texmf:doc/plain/impatient/book.pdf#page=194", + summary = "Produce leaders with leftover space distributed equally between the leader boxes." + }, + xspaceskip = { + details = "$ref:teximpatient#/data/spacefactor", + documentation = "texmf:doc/plain/impatient/book.pdf#page=127", + summary = "If nonzero and \\spacefactor ≥ 2000, overrides the normal interword glue.", + type = "glue" + }, + year = { + details = "$ref:teximpatient#/data/year", + documentation = "texmf:doc/plain/impatient/book.pdf#page=245", + summary = "The current year, as a number.", + type = "number" + } +} diff --git a/support/digestif/data/t-pgf.xml.tags b/support/digestif/data/t-pgf.xml.tags new file mode 100644 index 0000000000..37ddeba332 --- /dev/null +++ b/support/digestif/data/t-pgf.xml.tags @@ -0,0 +1,6 @@ +package = { + name = "t-pgf.tex", + dependencies = { + "pgf" + } +} diff --git a/support/digestif/data/t-tikz.xml.tags b/support/digestif/data/t-tikz.xml.tags new file mode 100644 index 0000000000..86687d5582 --- /dev/null +++ b/support/digestif/data/t-tikz.xml.tags @@ -0,0 +1,31 @@ +package = { + name = "t-tikz.tex", + dependencies = { + "tikz" + } +} +environments = { + tikzpicture = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + }, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.tikzpicture" + }, + scope = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + }, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.scope" + }, +} + diff --git a/support/digestif/data/teximpatient.tags b/support/digestif/data/teximpatient.tags new file mode 100644 index 0000000000..229133e1ef --- /dev/null +++ b/support/digestif/data/teximpatient.tags @@ -0,0 +1,3848 @@ +-- Copyright 2003 Paul W. Abrahams, Kathryn A. Hargreaves, Karl Berry +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: GFDL-1.3-only +-- +-- Adapted from the book TeX for the Impatient, which can be found at +-- https://www.gnu.org/software/teximpatient. +data = { + ["+"] = [[ +`\+`, `\tabalign` + +These commands begin a single line in a tabbed alignment. The only +difference between `\+` and `\tabalign` is that `\+` is an outer +macro—you can’t use it when TeX is reading tokens at high speed . + +If you place an ‘`&`’ at a position to the right of all existing tabs in +a tabbing alignment, the ‘`&`’ establishes a new tab at that position. +]], + AA = [[ +`\AA` (Å), `\AE`, `\L` (Ł), `\OE`, `\O` (Ø), `\aa` (å), `\ae`, `\l` (ł), +`\oe`, `\o` (ø), `\ss` (ß) + +These commands produce various letters and ligatures from European +alphabets. They are useful for occasional words and phrases in these +languages—but if you need to typeset a large amount of text in a +European language, you should probably be using a version of TeX adapted +to that language.[1] + +You’ll need a space after these commands when you use them within a +word, so that TeX will treat the following letters as part of the word +rather than as part of the command. You needn’t be in math mode to use +these commands. + +[1] The TeX Users Group can provide you with information about European +language versions of TeX. +]], + TeX = [[ +This command produces the TeX logo. Remember to follow it by `\!vs` or +to enclose it in a group when you want a space after it. +]], + abovedisplayshortskip = [[ +This parameter specifies the amount of vertical glue that TeX inserts +before a math display when the display starts to the right of where the +previous line ends, i.e., when it does not visually overlap the previous +line. Plain TeX sets `\abovedisplayshortskip` to `0pt plus3pt`. See +pages 188–189 of *The TeXbook* for a more detailed explanation of this +parameter. +]], + abovedisplayskip = [[ +This parameter specifies the amount of vertical glue that TeX inserts +before a display when the display starts to the left of where the +previous line ends, i.e., when it visually overlaps the previous line. +Plain TeX sets `\abovedisplayskip` to `12pt plus3pt minus9pt`. See +pages 188–189 of *The TeXbook* for a more detailed explanation of this +parameter. +]], + accent = [[ +This command puts an accent over the character following this command. +The accent is the character at position `charcode` in the current font. +TeX assumes that the accent has been designed to fit over a character +1ex high in the same font as the accent. If the character to be +accented is taller or shorter, TeX adjusts the position accordingly. You +can change fonts between the accent and the next character, thus drawing +the accent character and the character to be accented from different +fonts. If the accent character isn’t really intended to be an accent, +TeX won’t complain; it will just typeset something ridiculous. +]], + active = [[ +This command contains the category code for an active character, namely, +the number 13. +]], + acute = [[ +`\acute`, `\bar`, `\breve`, `\b`, `\check`, `\ddot`, `\dot`, `\grave`, +`\hat`, `\tilde`, `\vec`, `\widehat`, `\widetilde` + +These commands produce accent marks in math formulas. You’ll ordinarily +need to leave a space after any one of them. A wide accent can be +applied to a multicharacter subformula; TeX will center the accent over +the subformula. The other accents are usefully applied only to a single +character. +]], + adjdemerits = [[ +This parameter specifies additional demerits that TeX attaches to a +breakpoint between two adjacent lines that are “visually incompatible”. +Such a pair of lines makes a paragraph appear uneven. Incompatibility is +evaluated in terms of the tightness or looseness of lines: + +1. A line is tight if its glue needs to shrink by at least $50\%$. + +2. A line is decent if its badness is 12 or less. + +3. A line is loose if its glue needs to stretch by more than $50\%$. + +4. A line is very loose if its glue needs to stretch so much that its + badness exceeds 100. + +Two adjacent lines are visually incompatible if their categories are not +adjacent, e.g., a tight line is next to a loose one or a decent line is +next to a very loose one. + +Demerits are in units of badness squared, so you need to assign a rather +large value to this parameter (in the thousands) for it to have any +effect. Plain TeX sets `\adjdemerits` to 10000. +]], + advance = [[ +This command adds a compatible quantity to a register. For `glue` or +`muglue` all three components (natural value, stretch, and shrink) are +added. Any of the quantities can be negative. For purposes of these +calculations (and other assignments as well), `glue` can be converted to +a `dimen` by dropping the stretch and shrink, and a `dimen` can be +converted to a `number` by taking its value in scaled points . You can +omit the word `by` in these commands—TeX will understand them anyway. +]], + advancepageno = [[ +This command adds 1 to the page number $n$ in `\pageno` if $n\ge0$ and +subtracts 1 from it if $n<0$. +]], + afterassignment = [[ +When TeX encounters this command it saves `token` in a special place. +After it next performs an assignment, it inserts `token` into the input +and expands it. If you call `\afterassignment` more than once before an +assignment, only the last call has any effect. One use of +`\afterassignment` is in writing macros for commands intended to be +written in the form of assignments, as in the example below. + +See page 279 of *The TeXbook* for a precise description of the behavior +of `\afterassignment`. +]], + aftergroup = [[ +When TeX encounters this command during input, it saves `token`. After +the end of the current group, it inserts `token` back into the input and +expands it. If a group contains several `\aftergroup`s, the +corresponding tokens are *all* inserted following the end of the group, +in the order in which they originally appeared. + +The example that follows shows how you can use `\aftergroup` to postpone +processing a token that you generate within a conditional test. +]], + allowbreak = [[ +This command tells TeX to allow a page break where one could not +ordinarily occur. `\allowbreak` can also be used in horizontal mode. +]], + alpha = [[ +`\Delta` (Δ), `\Gamma` (Γ), `\Lambda` (Λ), `\Omega` (Ω), `\Phi` (Φ), +`\Pi` (Π), `\Psi` (Ψ), `\Sigma` (Σ), `\Theta` (Θ), `\Upsilon` (Υ), `\Xi` +(Ξ), `\alpha` (α), `\beta` (β), `\chi` (χ), `\delta` (δ), `\epsilon` +(ϵ), `\eta` (η), `\gamma` (γ), `\iota` (ι), `\kappa` (κ), `\lambda` (λ), +`\mu` (μ), `\nu` (ν), `\omega` (ω), `\phi` (ϕ), `\pi` (π), `\psi` (ψ), +`\rho` (ρ), `\sigma` (σ), `\tau` (τ), `\theta` (θ), `\upsilon` (υ), +`\varepsilon` (ε), `\varphi` (φ), `\varpi` (ϖ), `\varrho` (𝜚), +`\varsigma` (ς), `\vartheta` (ϑ), `\xi` (ξ), `\zeta` (ζ) + +These commands produce Greek letters suitable for mathematics. You can +only use them within a math formula, so if you need a Greek letter +within ordinary text you must enclose it in dollar signs (`$`). TeX does +not have commands for Greek letters that look like their roman +counterparts, since you can get them by using those roman counterparts. +For example, you can get a lowercase omicron in a formula by writing the +letter ‘o’, i.e., ‘`{\rm o}`’ or an uppercase beta (‘B’) by writing +‘`{\rm B}`’. + +Don’t confuse the following letters: + +- `\upsilon` (‘$\upsilon$’), `{\rm v}` (‘v’), and `\nu` (‘$\nu$’). + +- `\varsigma` (‘$\varsigma$’) and `\zeta` (‘$\zeta$’). + +You can get slanted capital Greek letters by using the math italic +(`\mit`) font. + +TeX treats Greek letters as ordinary symbols when it’s figuring how much +space to put around them. +]], + arrowvert = [[ +`\Arrowvert`, `\arrowvert`, `\bracevert`, `\lmoustache`, `\rmoustache` + +These commands produce portions of certain large delimiters + +and can themselves be used as delimiters. They refer to characters in +the `cmex10` math font. +]], + asymp = [[ +`\approx` (≈), `\asymp` (≍), `\bowtie` (⋈), `\cong` (≅), `\dashv` (⊣), +`\doteq` (≐), `\equiv` (≡), `\frown` (⌢), `\geq`, `\ge` (≥), `\gg` (≫), +`\in` (∈), `\leq`, `\le` (≤), `\ll` (≪), `\mid` (∣), `\models` (⊨), +`\neq` (≠), `\ne` (≠), `\ni` (∋), `\notin` (∉), `\owns` (∋), `\parallel` +(∥), `\perp` (⊥), `\preceq` (≼), `\prec` (≺), `\propto` (∝), `\simeq` +(≃), `\sim` (∼), `\smile` (⌣), `\sqsubseteq` (⊑), `\sqsupseteq` (⊒), +`\subseteq` (⊆), `\subset` (⊂), `\succeq` (≽), `\succ` (≻), `\supseteq` +(⊇), `\supset` (⊃), `\vdash` (⊢) + +These commands produce the symbols for various relations. Relations are +one of TeX’s classes of math symbols. TeX puts different amounts of +space around different classes of math symbols. When TeX needs to break +a line of text within a math formula, it will consider placing the break +after a relation—but only if the relation is at the outermost level of +the formula, i.e., not enclosed in a group. + +In addition to the commands listed here, TeX treats ‘`=\verb`’ and the +“arrow” commands as relations. + +Certain relations have more than one command that you can use to produce +them: + +- ‘$\ge$’ (|| and `\geq`). + +- ‘$\le$’ (`\le` and `\leq`). + +- ‘$\ne$’ (`\ne`, `\neq`, and `\not=`). + +- ‘$\ni$’ (`\ni` and `\owns`). +]], + badness = [[ +This command yields the numerical value of the badness of the box +(either horizontal or vertical) that TeX has most recently produced. If +the box was overfull, `\badness` will be 1000000; in all other cases +it will be between 0 and 10000. +]], + baselineskip = [[ +`\baselineskip`, `\lineskiplimit`, `\lineskip` + +These three parameters jointly determine how much space TeX leaves +between consecutive boxes of an ordinary vertical list, e.g., the lines +of a paragraph. This space is called “interline glue”. It is also +inserted between the component boxes of a vbox constructed in internal +vertical mode. + +In the usual case, when the boxes aren’t abnormally high or deep, +TeX makes the distance from the baseline of one box to the baseline of +the next one equal to `\baselineskip`. It does this by inserting +interline glue equal to `\baselineskip` minus the depth of the upper box +(as given by `\prevdepth`) and the height of the lower box. But if this +interline glue would be less than `\lineskiplimit`, indicating that the +two boxes are too close together, TeX inserts the `\lineskip` glue +instead.[1] See pages 79–80 of *The TeXbook* for a precise description. + +Note that `\baselineskip` and `\lineskip` measure *different things*: +the distance between baselines on the one hand and the distance between +the bottom of one box and the top of the next box on the other hand. See +page 78 of *The TeXbook* for further details. The first example below +shows the effects of `\lineskiplimit`. + +You can obtain the effect of double spacing by doubling the value of +`\baselineskip` as illustrated in the second example below. A change to +`\baselineskip` at any point before the end of a paragraph affects the +entire paragraph. + +[1] TeX actually accounts for the beginning of a vertical list by +setting `\prevdepth` to $-1000$pt and testing `\prevdepth` before +*every* box. If `\prevdepth`$\>\le-1000$pt it does not insert any +interline glue. +]], + batchmode = [[ +This command tells TeX not to stop for errors and to suppress all +further output to your terminal. Typing ‘`Q`’ or ‘`q`’ in response to an +error message puts you into batch mode. +]], + begingroup = [[ +`\begingroup`, `\endgroup` + +These two commands begin and end a group. A `\begingroup` does not match +up with a right brace, nor an `\endgroup` with a left brace. + +TeX treats `\begingroup` and `\endgroup` like any other control sequence +when it’s scanning its input. In particular, you can define a macro that +contains a `\begingroup` but not an `\endgroup`, and conversely. + +This technique is often useful when you’re defining paired macros, one +of which establishes an environment and the other of which terminates +that environment. You can’t, however, use `\begingroup` and `\endgroup` +as substitutes for braces other than the ones that surround a group. +]], + beginsection = [[ +You can use this command to begin a major subdivision of your document. +`argument` is intended to serve as a section title. `\beginsection` +surrounds `argument` by extra vertical space and sets it in boldface, +left-justified. You can produce the `\par` that ends `argument` with a +blank line. +]], + belowdisplayshortskip = [[ +This parameter specifies the amount of vertical glue that TeX inserts +after a display when the display starts to the right of where the +previous line ends, i.e., when it does not visually overlap the previous +line. Plain TeX sets `\belowdisplayshortskip` to `7pt plus3pt minus4pt`. +See pages 188–189 of *The TeXbook* for a more detailed explanation of +this parameter. +]], + belowdisplayskip = [[ +This parameter specifies the amount of vertical glue that TeX inserts +after a display when the display starts to the left of where the +previous line ends, i.e., when it visually overlaps the previous line. +Plain TeX sets `\belowdisplayskip` to `12pt plus3pt minus9pt`. See +pages 188–189 of *The TeXbook* for a more detailed explanation of this +parameter. +]], + bf = [[ +`\bf`, `\it`, `\rm`, `\sl`, `\tt` + +These commands select a type style without changing the typeface or the +point size.[1] Normally you would enclose one of these type style +commands in a group, together with the text to be set in the selected +font. Outside of a group a type style command is effective until the end +of the document (unless you override it with another such command). + +[1] TeX does not provide predefined commands for changing just the point +size, e.g., `\eightpoint`. Supporting such commands would require a +great number of fonts, most of which would never be used. Such commands +were, however, used in typesetting *The TeXbook*. +]], + bgroup = [[ +`\bgroup`, `\egroup` + +The left and right braces are commands that begin and end a group. The +`\bgroup` and `\egroup` control sequences are equivalent to ‘`{`’ and +‘`}`’, except that TeX treats `\bgroup` and `\egroup` like any other +control sequence when it’s scanning its input. + +`\bgroup` and `\egroup` can be useful when you’re defining paired +macros, one of which starts a brace-delimited construct (not necessarily +a group) and the other one of which ends that construct. + +You can’t define such macros using ordinary braces—if you try, your +macro definitions will contain unmatched braces and will therefore be +unacceptable to TeX. Usually you should use these commands only when you +can’t use ordinary braces. +]], + big = [[ +`\Biggl`, `\Biggm`, `\Biggr`, `\Bigg`, `\Bigl`, `\Bigm`, `\Bigr`, +`\Big`, `\biggl`, `\biggm`, `\biggr`, `\bigg`, `\bigl`, `\bigm`, +`\bigr`, `\big` + +These commands make delimiters bigger than their normal size. The +commands in the four columns produce successively larger sizes. The +difference between `\big`, `\bigl`, `\bigr`, and `bigm` has to do with +the class of the enlarged delimiter: + +- `\big` produces an ordinary symbol. + +- `\bigl` produces an opening symbol. + +- `\bigr` produces a closing symbol. + +- `\bigm` produces a relation symbol. + +TeX uses the class of a symbol in order to decide how much space to put +around that symbol. + +These commands, unlike `\left` and `\right`, do *not* define a group. +]], + binoppenalty = [[ +This parameter specifies the penalty for breaking a math formula after a +binary operator when the formula appears in a paragraph. Plain TeX sets +`\binoppenalty` to 700. +]], + bmod = [[ +This command produces a binary operation for indicating a modulus within +a formula. +]], + boxmaxdepth = [[ +This parameter contains a dimension $D$. TeX will not construct a box +whose depth exceeds $D$. If you produce a box whose depth $d$ would +exceed $D$, TeX will transfer the excess depth to the height of the box, +effectively moving the reference point of the box down by $d-D$. If you +set `\boxmaxdepth` to zero, TeX will line up a row of vboxes so that +their bottom boundaries all lie on the same horizontal line. Plain +TeX sets `\boxmaxdepth` to `\maxdimen` , so `\boxmaxdepth` won’t affect +your boxes unless you change it. +]], + ["break"] = [[ +This command forces a page break. Unless you do something to fill out +the page, you’re likely to get an underfull vbox. `\break` can also be +used in horizontal mode. +]], + brokenpenalty = [[ +This parameter specifies the penalty for breaking a page just after a +line that ends in a discretionary item (usually a hyphen). + +`\brokenpenalty` applies to page breaking, while `\hyphenpenalty` +applies to line breaking. Plain TeX sets `\brokenpenalty` to 100. +]], + c = [[ +`\H`, `\c`, `\d`, `\t`, `\u`, `\v` + +These commands produce accent marks in ordinary text. You’ll usually +need to leave a space after the ones denoted by a single letter ). +]], + cal = [[ +`\cal`, `\mit`, `\oldstyle` + +These commands cause TeX to typeset the following text in the specified +font. You can only use them in math mode. The `\mit` command is useful +for producing slanted capital Greek letters. You can also use the +commands given in “TeX for the Impatient”, Selecting fonts,selfont to +change fonts in math mode. +]], + cases = [[ +This command produces the mathematical form that denotes a choice among +several cases. Each case has two parts, separated by ‘`&`’. TeX treats +the first part as a math formula and the second part as ordinary text. +Each case must be followed by `\cr`. +]], + catcode = [[ +This table entry contains the category code of the character whose +ASCII code is `charcode`. The category codes are listed on in “TeX for +the Impatient”. By changing the category code of a character you can get +TeX to treat that character differently. +]], + cdotp = [[ +`\cdotp` (·), `\ldotp` + +These two commands respectively produce a centered dot and a dot +positioned on the baseline. They are valid only in math mode. TeX treats +them as punctuation, putting no extra space in front of them but a +little extra space after them. In contrast, TeX puts an equal amount of +space on both sides of a centered dot generated by the `\cdot` command. +]], + centerline = [[ +`\centerline`, `\leftline`, `\rightline` + +The `\centerline` command produces an hbox exactly as wide as the +current line and places `argument` at the center of the box. The +`\leftline` and `\rightline` commands are analogous; they place +`argument` at the left end or at the right end of the box. If you want +to apply one of these commands to several consecutive lines, you must +apply it to each one individually. See in “TeX for the Impatient” for an +alternate approach. + +Don’t use these commands within a paragraph—if you do, TeX probably +won’t be able to break the paragraph into lines and will complain about +an overfull hbox. +]], + char = [[ +This command produces the character located at position `charcode` of +the current font. +]], + chardef = [[ +This command defines `control sequence` to be `charcode`. Although +`\chardef` is most often used to define characters, you can also use it +to give a name to a number in the range 0–255 even when you aren’t +using that number as a character code. +]], + cleartabs = [[ +This command clears all the tabs to the right of the current column. Its +main use is in applications such as typesetting computer programs in +which the tab positions change from line to line. +]], + closeout = [[ +This command tells TeX to close the output stream numbered `number`. +i.e., end the association between the output stream and its file. The +output stream with this number then becomes available for use with a +different file. You should close an output stream once you’re finished +using its file. + +A `\closeout` generates a whatsit that becomes part of a box. The +`\closeout` does not take effect until TeX ships out that box to the +.dvi file, unless you’ve preceded the `\closeout` with `\immediate`. +]], + clubpenalty = [[ +This parameter specifies the penalty for breaking a page just after the +first line of a paragraph. A line by itself at the bottom of a page is +called a “club line”. Plain TeX sets `\clubpenalty` to 150. +]], + colon = [[ +This command produces a colon punctation symbol. It is valid only in +math mode. The difference between `\colon` and the colon character (`:`) +is that ‘`:`’ is an operator, so TeX puts extra space to the left of it +whereas it doesn’t put extra space to the left of `\colon`. +]], + copy = [[ +This command produces a copy of box register `register`. This command is +useful when you want to retrieve the contents of a box register but +don’t want to destroy the contents. (Retrieving the register contents +with `\box` makes the register void.) +]], + cos = [[ +`\Pr`, `\arccos`, `\arcsin`, `\arctan`, `\arg`, `\cosh`, `\cos`, +`\coth`, `\cot`, `\csc`, `\deg`, `\det`, `\dim`, `\exp`, `\gcd`, `\hom`, +`\inf`, `\ker`, `\lg`, `\liminf`, `\limsup`, `\lim`, `\ln`, `\log`, +`\max`, `\min`, `\sec`, `\sinh`, `\sin`, `\sup`, `\tanh`, `\tan` + +These commands set the names of various mathematical functions in roman +type, as is customary. If you apply a superscript or subscript to one of +these commands, TeX will in most cases typeset it in the usual place. In +display style, TeX typesets superscripts and subscripts on `\det`, +`\gcd`, `\inf`, `\lim`, `\liminf`, `\limsup`, `\max`, `\min`, `\Pr`, and +`\sup` as though they were limits, i.e., directly above or directly +below the function name. +]], + count = [[ +`\count`, `\dimen`, `\muskip`, `\skip`, `\toks` + +The first six commands listed here assign something to a register. The +`=`’s in the assignments are optional. The remaining five control +sequences are not true commands because they can only appear as part of +an argument. They yield the contents of the specified register. Although +you can’t use these control sequences by themselves as commands in text, +you can use `\the` to convert them to text so that you can typeset their +values. + +You can name and reserve registers with the `\newcount` command and its +relatives . Using these commands is a safe way to obtain registers that +are known not to have any conflicting usage. + +A `\count` register contains an integer, which can be either positive or +negative. Integers can be as large as you’re ever likely to need them to +be.[1] TeX uses count registers 0–9 to keep track of the page number +(see page 119 of *The TeXbook*). `\count255` is the only count register +available for use without a reservation. + +[1] Here’s the only exercise in this book: find out what’s the largest +integer that TeX will accept. +]], + countdef = [[ +`\countdef`, `\dimendef`, `\muskipdef`, `\skipdef`, `\toksdef` + +These commands define `control sequence` to refer to the register of the +indicated category whose number is `register`. Normally you should use +the commands in the previous group (`\newcount`, etc.) in preference to +these commands in order to avoid numbering conflicts. The commands in +the previous group are defined in terms of the commands in this group. +]], + cr = [[ +This command ends the preamble of a horizontal or vertical alignment, a +row of a horizontal or tabbing alignment, or a column of a vertical +alignment. You can cause TeX to take certain actions whenever it sees a +`\cr` by setting the value of the `\everycr` parameter . +]], + crcr = [[ +This command behaves just like `\cr`, except that TeX ignores it if it +comes immediately after a `\cr` or a `\noalign`. Its main application is +as a safety measure to avoid a misleading error message caused by a +macro that expects an argument ending in `\cr`. If you put `\crcr` after +the ‘`#`$n$’ that denotes such an argument in the macro’s definition, +the macro will work properly whether or not the argument ends with +`\cr`. +]], + csname = [[ +This command produces a control sequence from `token list`. It provides +a way of synthesizing control sequences, including ones that you can’t +normally write. `token list` can itself include control sequences; it is +expanded in the same way as the replacement text of an `\edef` +definition. If the final expansion yields anything that isn’t a +character, TeX will complain. `\csname` goes from a list of tokens to a +control sequence; you can go the other way with `\string` . +]], + day = [[ +TeX sets this parameter to the current day of the month. It is a number +between 1 and 31. `\day` is set at the beginning of your run (see +the comments on `\time` above). +]], + ddots = [[ +This command produces three dots on a diagonal. Its most common use is +to indicate repetition along the diagonal of a matrix. +]], + deadcycles = [[ +This parameter contains the number of times that TeX has initiated the +output routine since the last time it did a `\shipout`.[1] If +`\deadcycles` gets too big, you’ve probably gotten TeX into a loop, +e.g., one where the page builder is trying the same page break over and +over again. + +[1] More precisely, TeX sets `\deadcyles` to 0 whenever it executes +`\shipout` and increments it by 1 whenever it executes `\output`. +]], + def = [[ +This command defines `control sequence` as a macro with the specified +`parameter text` and `replacement text`. See in “TeX for the Impatient” +for a full explanation of how to write a macro definition. +]], + defaulthyphenchar = [[ +When TeX reads the metrics file + +for a font in response to a `\font` command, it sets the font’s +`\hyphenchar` to `\defaulthyphenchar`. If the value of +`\defaulthyphenchar` is not in the range 0–255 when you load a font, +TeX won’t hyphenate any words in that font unless you override the +decision by setting the font’s `\hyphenchar` later on. Plain TeX sets +`\defaulthyphenchar` to 45, the ASCII code for ‘`-`’. +]], + defaultskewchar = [[ +When TeX reads the metrics file + +for a font in response to a `\font` command, it sets the font’s +`\skewchar` to `\defaultskewchar`. If the value of `\defaultskewchar` is +not in the range 0–255, TeX does not assign any skew characters by +default. Plain TeX sets `\defaultskewchar` to $-1$, and it’s usually +best to leave it there. +]], + delcode = [[ +This table entry specifies the delimiter code for the input character +whose ASCII code is `charcode`. The delimiter code tells TeX how to find +the best output character to use for typesetting the indicated input +character as a delimiter. + +`number` is normally written in hexadecimal notation. Suppose that +`number` is the hexadecimal number $s_1s_2s_3\, +l_1l_2l_3$. Then when the character is used as a delimiter, TeX takes +the character to have small variant $s_1s_2s_3$ and large variant +$l_1l_2l_3$. Here $s_1s_2s_3$ indicates the math character found in +position $s_2s_3$ of family $s_1$, and similarly for $l_1l_2l_3$. This +is the same convention as the one used for `\mathcode`, except that +`\mathcode` also specifies a class. +]], + delimiter = [[ +This command produces a delimiter whose characteristics are given by +`number`. `number` is normally written in hexadecimal notation. You can +use the `\delimiter` command instead of a character in any context where +TeX expects a delimiter (although the command is rarely used outside of +a macro definition). Suppose that `number` is the hexadecimal number +$cs_1s_2s_3 +l_1l_2l_3$. Then TeX takes the delimiter to have class $c$, small +variant $s_1s_2s_3$, and large variant $l_1l_2l_3$. Here $s_1s_2s_3$ +indicates the math character found in position $s_2s_3$ of family $s_1$, +and similarly for $l_1l_2l_3$. This is the same convention as the one +used for `\mathcode`. +]], + discretionary = [[ +This command specifies a “discretionary break”, namely, a place where +TeX can break a line. It also tells TeX what text to put on either side +of the break. + +- If TeX does not break there, it uses the `no-break text`. + +- If TeX does break there, it puts the `pre-break text` just before + the break and the `post-break text` just after the break. + +Just as with `\-`, TeX isn’t obligated to break a line at a +discretionary break. In fact, `\-` is ordinarily equivalent to +`\discretionary!allowbreak{-}{}{}`. + +TeX sometimes inserts discretionary breaks on its own. For example, it +inserts `\discretionary!allowbreak{}{}{}` after an explicit hyphen or +dash. +]], + displayindent = [[ +This parameter specifies the space by which TeX indents a math display. +TeX sets the value of `\displayindent` when it encounters the ‘`$$`’ +that starts the display. Usually this initial value is zero, but if the +paragraph shape indicates that the display should be shifted by an +amount $s$, TeX will set `\displayindent` to $s$. See pages 188–189 of +*The TeXbook* for a more detailed explanation of this parameter. +]], + displaylimits = [[ +This command tells TeX to place limits above and below all operators +(including the integrals) if in display style, and after all operators +if in text style. + +If you specify more than one of `\limits`, `\nolimits`, and +`\displaylimits`, the last command rules. +]], + displaywidowpenalty = [[ +This parameter specifies the penalty for breaking a page just before the +last line of a partial paragraph that immediately precedes a math +display. Plain TeX sets `\displaywidowpenalty` to 50. +]], + displaywidth = [[ +This parameter specifies the maximum width that TeX allows for a math +display. If TeX cannot fit the display into a space of this width, it +sets an overfull hbox and complains. TeX sets the value of +`\displaywidth` when it encounters the ‘`$$`’ that starts the display. +This initial value is `\hsize` unless it’s overridden by changes to the +paragraph shape. See pages 188–189 of *The TeXbook* for a more detailed +explanation of this parameter. +]], + dotfill = [[ +`\dotfill`, `\hrulefill` + +These commands respectively fill the enclosing horizontal space with a +row of dots on the baseline and with a horizontal line on the baseline. +It’s usually a good idea to leave a space between `\dotfill` or +`\hrulefill` and any text that precedes or follows it (see the example +below). +]], + dots = [[ +This command produces an ellipsis, i.e., three dots, in ordinary text. +It’s intended for use in mathematical writing; for an ellipsis between +ordinary words, you should use `$\ldots$` instead. Since `\dots` +includes its own space, you shouldn’t follow it by `\!vs`. +]], + doublehyphendemerits = [[ +This parameter specifies additional demerits that TeX attaches to a +breakpoint when that breakpoint leads to two consecutive lines that end +in a hyphen. Increasing the value of this parameter has the effect of +discouraging TeX from hyphenating two lines in a row. Demerits are in +units of badness squared, so you need to assign a rather large value to +this parameter (in the thousands) for it to have any effect. Plain +TeX sets `\doublehyphendemerits` to 10000. +]], + downbracefill = [[ +`\downbracefill`, `\upbracefill` + +These commands respectively produce upward-pointing and +downward-pointing extensible horizontal braces. TeX will make the braces +as wide as necessary. These commands are used in the definitions of +`\overbrace` and `\underbrace` . +]], + dump = [[ +This command, which must not appear inside a group, dumps the contents +of TeX’s memory to a format file. By using `virtex`, a special “virgin” +form of TeX, you can then reload the format file at high speed and +continue in the same state that TeX was in at the time of the dump. +`\dump` also ends the run. Since `\dump` can only be used in `initex`, +not in production forms of TeX, it is only useful to people who are +installing TeX. +]], + edef = [[ +This command defines a macro in the same general way as `\def`. The +difference is that TeX expands the `replacement text` of an `\edef` +immediately (but still without executing anything). Thus any definitions +within the `replacement text` are expanded, but assignments and commands +that produce things such as boxes and glue are left as is. For example, +an `\hbox` command within the `replacement text` of an `\edef` remains +as a command and is not turned into a box as TeX is processing the +definition. It isn’t always obvious what’s expanded and what isn’t, but +you’ll find a complete list of expandable control sequences on +pages 212–215 of *The TeXbook*. + +You can inhibit the expansion of a control sequence that would otherwise +be expanded by using `\noexpand`. You can postpone the expansion of a +control sequence by using `\expandafter`. + +The `\write`, `\message`, `\errmessage`, `\wlog`, and `\csname` commands +expand their token lists using the same rules that `\edef` uses to +expand its replacement text. +]], + eject = [[ +`\eject`, `\supereject` + +These commands force a page break at the current position and end the +current paragraph. If you don’t precede them with `\vfil`, + +TeX will try to stretch out the page contents (and will probably +complain about an underfull vbox). The `\supereject` command, in +addition, instructs the plain TeX output routine to force out any +leftover insertions, + +such as long footnotes, so that they are produced before any more input +is processed. Thus `\supereject` is a good command to use at the end of +each chapter or other major unit of your document. +]], + ["else"] = [[ +This command introduces the “false” alternative of a conditional test. +]], + emergencystretch = [[ +By setting this parameter to be greater than zero, you can make it +easier for TeX to typeset your document without generating overfull +hboxes. + +This is a better alternative than setting `\tolerance=10000`, since that +tends to produce really ugly lines. If TeX can’t typeset a paragraph +without exceeding `\tolerance`, it will try again, adding +`\emergencystretch` to the stretch of each line. The effect of the +change is to scale down the badness of each line, enabling TeX to make +spaces wider than they would otherwise be and thus choose line breaks +that are as good as possible under the circumstances. +]], + empty = [[ +This command expands to no tokens at all. It differs from `\relax` in +that it disappears after macro expansion. +]], + ["end"] = [[ +This command tells TeX to produce the last page and end the job. It does +not fill out the page, however, so it’s usually better to use `\bye` +rather than `\end`. +]], + endgraf = [[ +This command is a synonym for the `\par` primitive command. It is useful +when you’ve redefined `\par` but still want access to the original +definition of `\par`. +]], + endinput = [[ +This command tells TeX to stop reading input from the current file when +it next reaches the end of a line. +]], + endinsert = [[ +This command ends an insertion started by `\topinsert`, `\midinsert`, or +`\pageinsert`. +]], + endline = [[ +This command is a synonym for the `\cr` command. It is useful when +you’ve redefined `\cr` but still need access to the original definition. +]], + endlinechar = [[ +This parameter contains the character code for the character that +TeX appends to the end of each input line. + +A value not in the range 0–255 indicates that no character should be +appended. Plain TeX leaves `\endlinechar` at `` `\^^M `` (the ASCII code +for ⟨return⟩). +]], + enskip = [[ +`\enskip`, `\qquad`, `\quad` + +Each of these commands produces a glob of horizontal glue that can +neither stretch nor shrink. TeX can break a line at such glue. The width +of these glues (which are relative to the current font) are as follows +for `cmr10`, the default plain TeX font: +]], + enspace = [[ +This command produces a kern whose width is one en (half of an em, see +in “TeX for the Impatient”). TeX won’t break a line at an `\enspace` +unless it’s followed by glue. In a bulleted list, the bullets are +usually separated from the following text by an `\enspace`. +]], + eqalign = [[ +`\eqalignno`, `\eqalign`, `\leqalignno` + +These commands produce a multiline math display in which certain +corresponding parts of the lines are lined up vertically. The +`\eqalignno` and `\leqalignno` commands also let you provide equation +numbers for some or all of the lines. `\eqalignno` puts the equation +numbers on the right and `\leqalignno` puts them on the left. + +Each line in the display is ended by `\cr`. Each of the parts to be +aligned (most often an equals sign) is preceded by ‘`&`’. An ‘`&`’ also +precedes each equation number, which comes at the end of a line. You can +put more than one of these commands in a single display in order to +produce several groups of equations. In this case, only the rightmost or +leftmost group can be produced by `\eqalignno` or `\leqalignno`. + +You can use the `\noalign` command to change the amount of space between +two lines of a multiline display. +]], + eqno = [[ +`\eqno`, `\leqno` + +These commands attach an equation number to a displayed formula. `\eqno` +puts the equation number on the right and `\leqno` puts it on the left. +The commands must be given at the end of the formula. If you have a +multiline display and you want to number more than one of the lines, use +the `\eqalignno` or `\leqalignno` command . + +These commands are valid only in display math mode. +]], + errhelp = [[ +This parameter contains the token list that TeX displays when you ask +for help in response to an `\errmessage` command. We recommend that when +you’re generating an error message with `\errmessage`, you set +`\errhelp` to a string that describes the nature of the error and use +`\newhelp` to produce that string. You can use the `\newlinechar` +character to produce multiline messages. +]], + errorcontextlines = [[ +This parameter determines the number of pairs of context lines, not +counting the top and bottom pairs, that TeX prints when it encounters an +error. By setting it to 0 you can get rid of long error messages. You +can still force out the full context by typing something like: + + I\errorcontextlines=100\oops + +in response to an error, since the undefined control sequence `\oops` +will cause another error. Plain TeX sets `\errorcontextlines` to 5. +]], + errorstopmode = [[ +This command tells TeX to stop for interaction whenever it finds an +error. This is the normal mode of operation. +]], + escapechar = [[ +This parameter specifies the ASCII code of the character that TeX uses +to represent the escape character + +when it’s converting a control sequence name to a sequence of character +tokens. This conversion occurs when you use the `\string` command and +also when TeX is producing diagnostic messages. The default value of the +escape character is 92, the ASCII character code for a backslash. If +`\escapechar` is not in the range 0–255, TeX does not include an +escape character in the result of the conversion. +]], + everycr = [[ +TeX expands `token list` whenever it executes a `\cr`—at the end of +every preamble, at the end of every row of a horizontal alignment, and +at the end of every column of a vertical alignment. The `\everycr` +commands are expanded just after the `\cr`. Thus you can cause TeX to +execute certain commands at the end of a preamble, row, or column by +assigning a list of those commands to `\everycr`. + +The `\everycr` tokens shouldn’t include any commands other than +`\noalign`. That’s because the `\everycr` tokens will reappear after the +last `\cr` of the alignment. A command other than `\noalign` will then +make TeX think that it’s starting a new row or column. TeX will complain +about a missing `\cr`, insert a `\cr`, insert the `\everycr` tokens +again, and repeat these actions indefinitely. +]], + everyhbox = [[ +`\everyhbox`, `\everyvbox` + +These parameters contain token lists that TeX expands at the start of +every hbox or vbox that it constructs. Any items resulting from the +expansion then become the beginning of the list of items for the box. By +default these token lists are empty. +]], + everyjob = [[ +This parameter contains a token list that TeX expands at the start of +every job. Because an assignment to `\everyjob` cannot affect the +current run (by the time you’ve done the assignment it’s already too +late), it is only useful to people who are preparing format files. +]], + everymath = [[ +`\everydisplay`, `\everymath` + +These parameters specify token lists that TeX inserts at the start of +every text math or display math formula, respectively. You can take +special actions at the start of each math formula by assigning those +actions to `\everymath` or `\everydisplay`. Don’t forget that if you +want both kinds of formulas to be affected, you need to set *both* +parameters. +]], + everypar = [[ +TeX performs the commands in `token list` whenever it enters horizontal +mode, e.g., when it starts a paragraph. By default `\everypar` is empty, +but you can take extra actions at the start of every paragraph by +putting the commands for those actions into a token list and assigning +that token list to `\everypar`. +]], + exhyphenpenalty = [[ +This parameter specifies the penalty that TeX attaches to a breakpoint +at an explicit hyphen such as the one in “helter-skelter”. Increasing +this parameter has the effect of discouraging TeX from ending a line at +an explicit hyphen. Plain TeX sets `\exhyphenpenalty` to 50. +]], + expandafter = [[ +This command tells TeX to expand `token_1` according to its rules for +macro expansion *after* it has expanded `token_2` by one level. It’s +useful when `token_1` is something like ‘`{`’ + +or `\string` that inhibits expansion of `token_2`, but you want to +expand `token_2` nevertheless. +]], + fam = [[ +When TeX is in math mode, it ordinarily typesets a character using the +font family given in its mathcode. + +However, when TeX is in math mode and encounters a character whose class +is 7 (Variable), it typesets that character using the font family +given by the value of `\fam`, provided that the value of `\fam` is +between 0 and 15. If the value of `\fam` isn’t in that range, +TeX uses the family in the character’s mathcode as in the ordinary case. +TeX sets `\fam` to $-1$ whenever it enters math mode. Outside of math +mode, `\fam` has no effect. + +By assigning a value to `\fam` you can change the way that TeX typesets +ordinary characters such as variables. For instance, by setting `\fam` +to `\ttfam`, you cause TeX to typeset variables using a typewriter font. +Plain TeX defines `\tt` as a macro that, among other things, sets `\fam` +to `\ttfam`. +]], + fi = [[ +This command ends the text of a conditional test. +]], + filbreak = [[ +This command provides a kind of conditional page break. It tells TeX to +break the page—but not if the text up to a later `\filbreak` also fits +on the same page. By enclosing a paragraph in a pair of `\filbreak`s, +you can ensure that TeX will keep a paragraph on a single page if it +can. You should not use `\filbreak` within a paragraph, since it forces +TeX into vertical mode and thus ends the paragraph. See in “TeX for the +Impatient” for more advice on this subject. +]], + finalhyphendemerits = [[ +This parameter specifies additional demerits that TeX attaches to a +breakpoint that causes the next to last line of a paragraph to end with +a hyphen. Such a hyphen is generally considered to be unaesthetic +because of the possible blank space from a short last line beneath it. +Increasing the value of this parameter has the effect of discouraging +TeX from ending the next to the last line with a hyphen. Demerits are in +units of badness squared, so you need to assign a rather large value to +this parameter (in the thousands) for it to have any effect. Plain +TeX sets `\finalhyphendemerits` to 5000. +]], + firstmark = [[ +`\botmark`, `\firstmark`, `\topmark` + +These commands expand to the mark text in an item generated by an +earlier `\mark` command. The mark text has the form of a token list. +TeX sets the values of these commands when it finishes placing the +contents of a page into `\box255`, just before calling the output +routine as part of its page breaking actions. TeX determines these +values as follows: + +- `\firstmark` contains the tokens of the first mark on the page. + +- `\botmark` contains the tokens of the last mark on the page. + +- `\topmark` contains the tokens of the mark that is in effect at the + very top of the page. That mark is the last mark that *preceded* the + page, i.e., the `\botmark` of the previous page. It is empty if no + marks preceded the page. + +If a page has no marks on it, TeX will set `\firstmark` and `\botmark` +to the same mark as `\topmark`, i.e., the most recent preceding mark. +The table at the bottom of page 258 of *The TeXbook* illustrates the +relation among `\firstmark`, `\botmark`, and `\topmark`. +]], + fivebf = [[ +`\fivebf`, `\fivei`, `\fiverm`, `\fivesy`, `\sevenbf`, `\seveni`, +`\sevenrm`, `\sevensy`, `\tenbf`, `\tenex`, `\tenit`, `\teni`, `\tenrm`, +`\tensl`, `\tensy`, `\tentt` + +These commands cause TeX to typeset the following text in the specified +font. Normally you would enclose one of these font-selecting commands in +a group, together with the text to be set in the selected font. Outside +of a group a font-selecting command is effective until the end of the +document (unless you override it with another such command). +]], + floatingpenalty = [[ +This parameter specifies the penalty that TeX adds to `\insertpenalties` + +when the page builder is adding an insertion to the current page and +discovers that a previous insertion of the same kind on this page has +been split, leaving part of it for subsequent pages. Plain TeX leaves +`\floatingpenalty` at 0. +]], + fmtname = [[ +`\fmtname`, `\fmtversion` + +These commands produce the name and version number of the TeX format, +e.g., plain TeX or LaTeX, that you’re using. +]], + folio = [[ +This command produces the current page number, whose value is the number +$n$ contained in `\pageno`. If $n\ge0$, TeX produces $n$ as a decimal +number, while if $n<0$, TeX produces $-n$ in lowercase roman numerals. +]], + font = [[ +Used alone, the `\font` control sequence designates the current font. +`\font` isn’t a true command when it’s used alone, since it then can +appear only as an argument to another command. + +For the other three forms of `\font`, `fontname` names a set of files +that define a font. These forms of `\font` are commands. Each of these +forms has two effects: + +1. It defines `control sequence` as a name that selects the font + `fontname`, possibly magnified (see below). + +2. It causes TeX to load the font metrics file (.tfm file) for + `fontname`. + +The name of a font file usually indicates its design size. For example, +`cmr10` indicates Computer Modern roman with a design size of 10 +points. The design size of a font is recorded in its metrics file. + +If neither `scaled` `number` nor `at` `dimen` is present, the font is +used at its design size—the size at which it usually looks best. +Otherwise, a magnified version of the font is loaded: + +- If `scaled` `number` is present, the font is magnified by a factor + of $\texttt{number}/1000$. + +- If `at` `dimen` is present, the font is scaled to `dimen` by + magnifying it by $\texttt{dimen}/ds$, where $ds$ is the design size + of `fontname`. `dimen` and $ds$ are nearly always given in points. + +Magnifications of less than 1 are possible; they reduce the size. + +You usually need to provide a shape file for each magnification of a +font that you load. However, some device drivers can utilize fonts that +are resident in a printer. Such fonts don’t need shape files. + +See “TeX for the Impatient” and “TeX for the Impatient” for further +information. +]], + fontdimen = [[ +These parameters specify various dimensions associated with the font +named by the control sequence `font` (as distinguished from the +`fontname` that names the font files). Values of these parameters are +specified in the metrics file for `font`, but you can retrieve or change +their values during a TeX run. The numbers and meanings of the +parameters are: + +TeX uses the slant per point for positioning accents. It uses the +interword parameters for producing interword spaces ) and the extra +space parameter for the additional space after a period). The values of +these parameters for the plain TeX fonts are enumerated on page 433 of +*The TeXbook*. Math symbol fonts have 15 additional parameters, which +we won’t discuss here. + +Beware: assignments to these parameters are *not* undone at the end of a +group. If you want to change these parameters locally, you’ll need to +save and restore their original settings explicitly. +]], + fontname = [[ +This command produces the filename for `font`. The filename is the +`fontname` that was used to define `font`. +]], + footnote = [[ +`\footnote`, `\vfootnote` + +These commands produce footnotes. `argument_1` is the “reference mark” +for the footnote and `argument_2` is its text. The text can be several +paragraphs long if necessary and can contain constructs such as math +displays, but it shouldn’t contain any insertions (such as other +footnotes). + +You shouldn’t use these commands inside a subformula of a math formula, +in a box within a box being contributed to a page, or in an insertion of +any kind. If you’re unsure whether these restrictions apply, you can be +safe by only using `\footnote` and `\vfootnote` directly within a +paragraph or between paragraphs. + +These restrictions aren’t as severe as they seem because you can use +`\vfootnote` to footnote most anything. Both `\footnote` and +`\vfootnote` insert the reference mark in front of the footnote itself, +but `\vfootnote` doesn’t insert the reference mark into the text. Thus, +when you use `\vfootnote` you can explicitly insert the reference mark +wherever it belongs without concern about the context and place the +`\vfootnote` in the next paragraph. If you find that the footnote lands +on the page following the one where it belongs, move the `\vfootnote` +back to the previous paragraph. There are rare circumstances where +you’ll need to alter the text of your document in order to get a +footnote to appear on the same page as its reference mark. +]], + frenchspacing = [[ +`\frenchspacing`, `\nonfrenchspacing` + +TeX normally adjusts the spacing between words to account for +punctuation marks. For example, it inserts extra space at the end of a +sentence and adds some stretch to the glue following any punctuation +mark there. The `\frenchspacing` command tells TeX to make the interword +spacing independent of punctuation, while the `\nonfrenchspacing` +command tells TeX to use its normal spacing rules. If you don’t specify +`\frenchspacing`, you’ll get TeX’s normal spacing. + +See in “TeX for the Impatient” for advice on how to control TeX’s +treatment of punctuation at the end of sentences. +]], + futurelet = [[ +This command tells TeX to make `token_2` the meaning of +`control sequence` (as would be done with `\let`), and then to process +`token_1` and `token_2` normally. `\futurelet` is useful at the end of +macro definitions because it gives you a way of looking beyond the token +that TeX is about to process before it processes it. +]], + gdef = [[ +This command is equivalent to `\global\def`. +]], + global = [[ +This command makes the following definition or assignment global so that +it becomes effective independent of group boundaries. You can apply a +`\global` prefix to any kind of definition or assignment, including a +macro definition or a register assignment. +]], + globaldefs = [[ +This parameter controls whether or not TeX takes definitions and other +assignments to be global: + +- If `\globaldefs` is zero (as it is by default), a definition is + global if and only if it is preceded by `\global` either explicitly + or implicitly. (The `\gdef` and `\xdef` commands have an implicit + `\global` prefix). + +- If `\globaldefs` is greater than zero, all assignments and + definitions are implicitly prefixed by `\global`. + +- If `\globaldefs` is less than zero, all `\global` prefixes are + ignored. +]], + goodbreak = [[ +This command ends a paragraph and also indicates to TeX that this is a +good place to break the page. +]], + halign = [[ +This command produces a horizontal alignment consisting of a sequence of +rows, where each row in turn contains a sequence of column entries. +TeX adjusts the widths of the column entries to accommodate the widest +one in each column. + +A horizontal alignment can only appear when TeX is in a vertical mode. +We recommend that you first study alignments in general before you +attempt to use this command. + +An alignment consists of a preamble followed by the text to be aligned. +The preamble, which describes the layout of the rows that follow, +consists of a sequence of column templates, separated by ‘`&`’ and ended +by `\cr`. Each row consists of a sequence of column entries, also +separated by ‘`&`’ and ended by `\cr`. Within a template, ‘`#`’ +indicates where TeX should insert the corresponding text of a column +entry. In contrast, `\settabs` uses a fixed implicit template of ‘`#`’, +i.e., it just inserts the text as is. + +TeX typesets each column entry in restricted horizontal mode, i.e., as +the contents of an hbox, and implicitly encloses it in a group. + +The `to` form of this command instructs TeX to make the width of the +alignment be `dimen`, adjusting the space between columns as necessary. +The `spread` form of this command instructs TeX to make the alignment +wider by `dimen` than its natural width. These forms are like the +corresponding forms of `\hbox` . + +See `\tabskip` for an example using the `to` form. +]], + hang = [[ +This command indents the second and subsequent lines of a paragraph by +`\parindent`, the paragraph indentation . Since the first line is +already indented by `\parindent` (unless you’ve cancelled the +indentation with `\noindent`), the entire paragraph appears to be +indented by `\parindent`. +]], + hangafter = [[ +`\hangafter`, `\hangindent` + +These two parameters jointly specify “hanging indentation” for a +paragraph. The hanging indentation indicates to TeX that certain lines +of the paragraph should be indented and the remaining lines should have +their normal width. + +`\hangafter` determines which lines are indented, while `\hangindent` +determines the amount of indentation and whether it occurs on the left +or on the right: + +- Let $n$ be the value of `\hangafter`. If $n < 0$, the first $-n$ + lines of the paragraph will be indented. If $n\ge0$, all but the + first $n$ lines of the paragraph will be indented. + +- Let $x$ be the value of `\hangindent`. If $x\ge0$, the lines will be + indented by $x$ on the left. If $x<0$ the lines will be indented by + $-x$ on the right. + +When you specify hanging indentation, it applies only to the next +paragraph (if you’re in vertical mode) or to the current paragraph (if +you’re in horizontal mode). TeX uses the values of `\hangafter` and +`\hangindent` at the end of a paragraph, when it breaks that paragraph +into lines. + +Unlike most of the other paragraph-shaping parameters, `\hangafter` and +`\hangindent` are reset to their default values at the start of each +paragraph, namely, 1 for `\hangafter` and 0 for `\hangindent`. If +you want to typeset a sequence of paragraphs with hanging indentation, +use `\everypar`. + +If you specify `\hangafter` and `\hangindent` as well as `\parshape`, +TeX ignores the `\hangafter` and `\hangindent`. +]], + hbadness = [[ +`\hbadness`, `\vbadness` + +These parameters specify the thresholds of horizontal and vertical +badness for reporting underfull or overfull boxes. `\hbadness` applies +to hboxes and `\vbadness` applies to vboxes. If the badness of a +constructed box exceeds the threshold, TeX will report an error. If you +raise the thresholds (the plain TeX defaults are both 1000), TeX will +be less likely to complain. Note that the settings of `\hbadness` and +`\vbadness` have no effect on the appearance of your typeset document; +they only affect the error messages that you get. See page 302 of *The +TeXbook* for a precise description of how TeX decides when to complain +about an overfull or underfull box. +]], + hbox = [[ +This command produces an hbox (horizontal box) containing +`horizontal mode material`. The braces around `horizontal mode material` +define a group. TeX doesn’t break the `horizontal mode material` into +lines, since it’s in restricted horizontal mode when it’s assembling the +box. TeX won’t change the size of the box once it’s been produced. + +`\hbox` is often useful when you want to keep some text all on one line. +If your use of `\hbox` prevents TeX from breaking lines in an acceptable +way, TeX will complain about an overfull hbox. + +The width of the hbox depends on the arguments to `\hbox`: + +- If you specify only `horizontal mode material`, the hbox will have + its natural width. + +- If you specify `to` `dimen`, the width of the hbox will be `dimen`. + +- If you specify `spread` `dimen`, the width of the hbox will be its + natural width plus `dimen`, i.e., the hbox will be spread out by + `dimen`. + +The `\hfil` command is useful for filling out an hbox with empty space +when the material in the box isn’t as wide as the width of the box. +]], + hfil = [[ +`\hfill`, `\hfil`, `\vfill`, `\vfil` + +These commands produce infinitely stretchable horizontal and vertical +glue that overwhelms any finite stretch that may be present. `\hfil` and +`\hfill` produce horizontal glue, while `\vfil` and `\vfill` produce +vertical glue. + +`\hfill` is infinitely larger than `\hfil`. If both `\hfill` and `\hfil` +appear in the same box, the `\hfill` will consume all the available +extra space and the `\hfil` will be effectively ignored. `\hfill` can in +turn be overwhelmed by `\hskip 0pt plus 1filll`. The glue produced by +`\hfil` and `\hfill` never shrinks. + +The behavior of `\vfil` and `\vfill` is analogous. +]], + hfilneg = [[ +`\hfilneg`, `\vfilneg` + +These commands cancel the effect of a preceding `\hfil` or `\vfil`. +While `\hfil` and `\vfil` produce infinitely stretchable positive glue, +`\hfilneg` and `\vfilneg` produce infinitely stretchable negative glue. +(Thus, $n$ `\hfilneg`s cancel $n$ `\hfil`s, and similarly for +`\vfilneg`.) The main use of `\hfilneg` and `\vfilneg` is to counteract +the effect of an `\hfil` or `\vfil` inserted by a macro. + +`\hfilneg` and `\vfilneg` have the curious property that if they are the +only infinitely stretchable glue in a box, they produce exactly the same +effect as `\hfil` and `\vfil`. +]], + hfuzz = [[ +`\hfuzz`, `\vfuzz` + +These parameters specify the amount that a box can exceed its natural +size before TeX considers it to be overfull. `\hfuzz` applies to hboxes +and `\vfuzz` applies to vboxes. Plain TeX sets both parameters to +`0.1pt`. +]], + hglue = [[ +`\hglue`, `\vglue` + +The `\hglue` command produces horizontal glue that won’t disappear at a +line break; the `\vglue` command produces vertical glue that won’t +disappear at a page break. In other respects these commands are just +like `\hskip` and `\vskip`. You can use `\vglue` to produce blank space +at the top of a page, e.g., above a title on the first page of a +document, but `\topglue` (next) is usually better for this purpose. +]], + hidewidth = [[ +This command tells TeX to ignore the width of the next column entry in a +horizontal alignment. It’s useful when you have an entry that is longer +than most of the others in the same column, and you’d rather have that +entry stick out of the column than make all the entries in the column +wider. If the `\hidewidth` is at the left of the entry, the entry sticks +out to the left; if the `\hidewidth` is at the right of the entry, the +entry sticks out to the right. +]], + hoffset = [[ +`\hoffset`, `\voffset` + +TeX normally takes the “origin” of a page, that is, the point where it +starts printing, as being one inch down from the top of the page and one +inch to the right of the left end of the page.[1] The values of +`\hoffset` and `\voffset` give the horizontal and vertical offset of the +actual origin from this point. Thus if `\hoffset` and `\voffset` are +both zero, TeX uses its normal origin. + +[1] TeX itself is indifferent to where the origin of the page is, but +this information has to be built into the device drivers + +that convert .dvi files into printable form so that different devices +will yield the same results. +]], + holdinginserts = [[ +If this parameter is greater than 0 when TeX is processing a page +break, TeX will refrain from processing insertions. Setting this +parameter to 1 can be useful when you’re writing an output routine +that needs to reprocess the contents of the page, e.g., an output +routine that uses a value of `\vsize` different from the one used by the +page builder. +]], + hphantom = [[ +`\hphantom`, `\vphantom` + +These commands produce phantom boxes that don’t print anything: + +- `\hphantom` produces a box with the same width as `argument` but + zero height and depth. + +- `\vphantom` produces a box with the same height and depth as + `argument` but zero width. + +Their main purpose is to force a subformula to have a certain minimum +horizontal or vertical dimension. +]], + hrule = [[ +`\hrule`, `\vrule` + +The `\hrule` command produces a horizontal rule; the `\vrule` command +produces a vertical rule. You can specify any or all of the width, +height, and depth of the rule—TeX supplies default values for those that +you omit. You can give the dimensions of the rule in any order; the +forms listed above show just two of the possible combinations. You can +even give a dimension of a given kind more than once—if you do, the last +one is the one that counts. + +If you don’t specify the width of a horizontal rule, the rule is +extended horizontally to the boundaries of the innermost box or +alignment that contains the rule. If you don’t specify the height of a +horizontal rule, it defaults to `0.4pt`; if you don’t specify the depth +of a horizontal rule, it defaults to `0pt`. + +If you don’t specify the width of a vertical rule, it defaults to +`0.4pt`. If you don’t specify the height or the depth of a vertical +rule, the rule is extended to the boundary of the innermost box or +alignment that contains the rule. + +TeX treats a horizontal rule as an inherently vertical item and a +vertical rule as an inherently horizontal item. Thus a horizontal rule +is legal only in a vertical mode, while a vertical rule is legal only in +a horizontal mode. + +If this seems surprising, visualize it—a horizontal rule runs from left +to right and separates vertical items in a sequence, while a vertical +rule runs up and down and separates horizontal items in a sequence. +]], + hsize = [[ +This parameter specifies the current line length. See in “TeX for the +Impatient” for a more complete explanation. +]], + hskip = [[ +`\hskip`, `\vskip` + +These commands produce horizontal and vertical glue respectively. In the +simplest and most common case when only `dimen_1` is present, `\hskip` +skips to the right by `dimen_1` and `\vskip` skips down the page by +`dimen_1`. More generally, these commands produce glue whose natural +size is `dimen_1`, whose stretch is `dimen_2`, and whose shrink is +`dimen_3`. Either the `plus` `dimen_2`, the `minus ``dimen_3`, or both +can be omitted. If both are present, the `plus` must come before the +`minus`. An omitted value is taken to be zero. Any of the `dimen`s can +be negative. + +You can use `\hskip` in math mode, but you can’t use `mu` units for any +of the dimensions. If you want `mu` units, use `\mskip` instead. +]], + hss = [[ +`\hss`, `\vss` + +These commands produce horizontal and vertical glue that is both +infinitely stretchable and infinitely shrinkable. The glue can shrink to +a negative distance, producing the effect of backspacing along a line +(for `\hss`) or moving back up a page (for `\vss`). +]], + ht = [[ +`\dp`, `\ht`, `\wd` + +These parameters refer to the height, depth, and width respectively of +box register `register`. You can use them to find out the dimensions of +a box. You can also change the dimensions of a box, but it’s a tricky +business; if you want to be adventurous you can learn all about it from +pages 388–389 of *The TeXbook*. +]], + hyphenchar = [[ +TeX doesn’t necessarily use the ‘-’ character at hyphenation points. +Instead, it uses the `\hyphenchar` of the current font, which is usually +‘-’ but need not be. If a font has a negative `\hyphenchar` value, +TeX won’t hyphenate words in that font. + +Note that `font` is a control sequence that names a font, not a +`fontname` that names font files. Beware: an assignment to `\hyphenchar` +is *not* undone at the end of a group. If you want to change +`\hyphenchar` locally, you’ll need to save and restore its original +value explicitly. +]], + hyphenpenalty = [[ +This parameter specifies the penalty that TeX attaches to a breakpoint +at an implicit hyphen. Implicit hyphens can come from TeX’s hyphenation +dictionary or from discretionary hyphens that you’ve inserted with +`\-` . + +Increasing this parameter has the effect of discouraging TeX from +hyphenating words. Plain TeX sets `\hyphenpenalty` to 50. +]], + i = [[ +`\i` (ı), `\j` (ȷ) + +These commands produce dotless versions of the letters ‘i’ and ‘j’. You +should use them instead of the ordinary ‘i’ and ‘j’ when you are putting +an accent above those letters in ordinary text. + +Use the `\imath` and `\jmath` commands for dotless ‘i’s and ‘j’s in math +formulas. +]], + ialign = [[ +This command behaves just like `\halign`, except that it first sets the +`\tabskip` glue to zero and sets `\everycr` empty. +]], + ["if"] = [[ +=1em This command tests if `token_1` and `token_2` have the same +character code, independent of their category codes. Before performing +the test, TeX expands tokens following the `\if` until it obtains two +tokens that can’t be expanded further. These two tokens become `token_1` +and `token_2`. The expansion includes replacing a control sequence +`\let` equal to a character token by that character token. A control +sequence that can’t be further expanded is considered to have character +code 256. +]], + ifcat = [[ +This command tests if `token_1` and `token_2` have the same category +code. Before performing the test, TeX expands tokens following the +`\ifcat` until it obtains two tokens that can’t be expanded further. +These two tokens become `token_1` and `token_2`. The expansion includes +replacing a control sequence `\let` equal to a character token by that +character token. A control sequence that can’t be further expanded is +considered to have category code 16. +]], + ifdim = [[ +This command tests if `dimen_1` and `dimen_2` satisfy `relation`, which +must be either ‘`<`’, ‘`=`’, or ‘`>`’. The dimensions can be constants +such as `1in`, dimension registers such as `\dimen6`, or dimension +parameters such as `\parindent`. Before performing the test, TeX expands +tokens following the `\ifdim` until it obtains a sequence of tokens +having the form `dimen_1` `relation` `dimen_2`, followed by a token that +can’t be part of `dimen_2`. +]], + ifeof = [[ +This command tests an input stream for end of file. It is true if input +stream `number` has not been opened, or has been opened and the +associated file has been entirely read in (or doesn’t exist). +]], + ifhbox = [[ +`\ifhbox`, `\ifvbox`, `\ifvoid` + +These commands test the contents of the box register numbered +`register`. Let `register` be $n$. Then: + +- `\ifhbox` is true if `\box`$\,n$ is an hbox. + +- `\ifvbox` is true if `\box`$\,n$ is an vbox. + +- `\ifvoid` is true if `\box`$\,n$ is void, i.e, doesn’t have a box in + it. +]], + ifhmode = [[ +`\ifhmode`, `\ifinner`, `\ifmmode`, `\ifvmode` + +These commands test what mode TeX is in: + +- `\ifhmode` is true if TeX is in ordinary or restricted horizontal + mode. + +- `\ifvmode` is true if TeX is in ordinary or internal vertical mode. + +- `\ifmmode` is true if TeX is in text math or display math mode. + +- `\ifinner` is true if TeX is in an “internal” mode: restricted + horizontal, internal vertical, or text math. +]], + ifnum = [[ +This command tests if `number_1` and `number_2` satisfy `relation`, +which must be either ‘`<`’, ‘`=`’, or ‘`>`’. The numbers can be +constants such as `127`, count registers such as `\pageno` or +`\count22`, or numerical parameters such as `\hbadness`. Before +performing the test, TeX expands tokens following the `\ifnum` until it +obtains a sequence of tokens having the form `number_1` `relation` +`number_2`, followed by a token that can’t be part of `number_2`. +]], + ifodd = [[ +This command tests if `number` is odd. Before performing the test, +TeX expands tokens following the `\ifodd` until it obtains a sequence of +tokens having the form `number`, followed by a token that can’t be part +of `number`. +]], + iftrue = [[ +`\iffalse`, `\iftrue` + +These commands are equivalent to tests that are always true or always +false. The main use of these commands is in defining macros that keep +track of the result of a test. +]], + ifx = [[ +This command tests if `token_1` and `token_2` agree. Unlike `\if` and +`\ifcat`, `\ifx` does *not* expand the tokens following `\ifx`, so +`token_1` and `token_2` are the two tokens immediately after `\ifx`. +There are three cases: + +1. If one token is a macro and the other one isn’t, the tokens don’t + agree. + +2. If neither token is a macro, the tokens agree if: + + 1. both tokens are characters (or control sequences denoting + characters) and their character codes and category codes agree, + or + + 2. both tokens refer to the same TeX command, font, etc. + +3. If both tokens are macros, the tokens agree if: + + 1. their “first level” expansions, i.e., their replacement texts, + are identical, and + + 2. they have the same status with respect to `\long` and `\outer`. + + Note in particular that *any two undefined control sequences agree*. + +This test is generally more useful than `\if`. +]], + ignorespaces = [[ +This command tells TeX to read and expand tokens until it finds one that +is not a space token, ignoring any space tokens that it finds on the +way. `\ignorespaces` is often useful at the end of a macro as a way of +making the macro insensitive to any spaces or ends of line that might +follow calls on it. (An empty line after `\ignorespaces` still produces +a `\par` token, however.) +]], + immediate = [[ +This command should precede an `\openout`, `\closeout`, or `\write`. + +It tells TeX to perform the specified file operation without delay. +]], + indent = [[ +If TeX is in vertical mode, as it is after ending a paragraph, this +command inserts the `\parskip` interparagraph glue, puts TeX into +horizontal mode, starts a paragraph, and indents that paragraph by +`\parindent`. If TeX is already in horizontal mode, this command merely +produces a blank space of width `\parindent`. Two `\indent`s in a row +produce two indentations. + +As the example below shows, an `\indent` at a point where TeX would +start a paragraph anyway is redundant. When TeX is in vertical mode and +sees a letter or some other inherently horizontal command, it starts a +paragraph by switching to horizontal mode, doing an `\indent`, and +processing the horizontal command. +]], + infty = [[ +`\Im` (ℑ), `\Re` (ℜ), `\Vert` (‖), `\aleph` (ℵ), `\angle` (∠), +`\backslash` (∖), `\bot` (⊥), `\clubsuit` (♣), `\diamondsuit` (♢), +`\ell` (ℓ), `\emptyset` (∅), `\exists` (∃), `\flat` (♭), `\forall` (∀), +`\hbar` (ℏ), `\heartsuit` (♡), `\imath` (𝚤), `\infty` (∞), `\jmath` (𝚥), +`\lnot` (¬), `\nabla` (∇), `\natural` (♮), `\neg` (¬), `\partial` (∂), +`\prime`, `\sharp` (♯), `\spadesuit` (♠), `\surd`, `\top` (⊤), +`\triangle` (△), `\vert`, `\wp` (℘) + +These commands produce various symbols. They are called “ordinary +symbols” to distinguish them from other classes of symbols such as +relations. You can only use an ordinary symbol within a math formula, so +if you need an ordinary symbol within ordinary text you must enclose it +in dollar signs (`$`). + +The commands `\imath` and `\jmath` are useful when you need to put an +accent on top of an ‘$i$’ or a ‘$j$’. + +An apostrophe (`'`) is a short way of writing a superscript `\prime`. +(The `\prime` command by itself generates a big ugly prime.) + +The `\|` and `\Vert` commands are synonymous, as are the `\neg` and +`\lnot` commands. + +The `\vert` command produces the same result as ‘`|`’. + +The symbols produced by `\backslash`, `\vert`, and `\Vert` are +delimiters. These symbols can be produced in larger sizes by using +`\bigm` et al. +]], + input = [[ +This command tells TeX to read its input from file `filename`. When that +file is exhausted, TeX returns to reading from its previous input +source. You can nest input files to any level you like (within reason). + +When you’re typesetting a large document, it’s usually a good idea to +structure your main file as a sequence of `\input` commands that refer +to the subsidiary parts of the document. That way you can process the +individual parts easily as you’re working on drafts. It’s also a good +practice to put all of your macro definitions into a separate file and +summon that file with an `\input` command as the first action in your +main file. + +TeX uses different rules for scanning file names than it does for +scanning tokens in general). If your implementation expects file names +to have extensions (usually indicated by a preceding dot), then +TeX provides a default extension of `.tex`. +]], + inputlineno = [[ +This command yields a number (not a string) giving the line number of +the current line, defined to be the number that would appear in an error +message if an error occurred at this point. +]], + insert = [[ +This primitive command provides the underlying mechanism for +constructing insertions, but it is hardly ever used outside of a macro +definition. The definitions of the `\footnote`, `\vfootnote`, +`\topinsert`, `\midinsert`, and `\pageinsert` commands are all built +around `\insert`. + +When you design insertions for a document, you should assign a different +integer code[1] $n$ to each kind of insertion, using the `\newinsert` +command to obtain the integer codes. The `\insert` command itself +appends the `vertical mode material` to the current horizontal or +vertical list. Your output routine is responsible for moving the +inserted material from where it resides in `\box`$\,n$ to an output +page. + +TeX groups together all insertions having the same code number. Each +insertion code $n$ has four registers associated with it: + +- `\box`$\,n$ is where TeX accumulates the material for insertions + with code $n$. When TeX breaks a page, it puts into `\box`$\,n$ as + much insertion $n$ material as will fit on the page. Your output + routine should then move this material to the actual page. You can + use `\ifvoid` to test if there is any material in `\box`$\,n$. If + not all the material fits, TeX saves the leftovers for the next + page. + +- `\count`$\,n$ is a magnification factor $f.$ When TeX is computing + the vertical space occupied on the page by insertion $n$ material, + it multiplies the vertical extent of this material by $f/1000$. Thus + you would ordinarily set $f$ to 500 for a double-column insertion + and to 0 for a marginal note. + +- `\dimen`$\,n$ specifies the maximum amount of insertion $n$ material + that TeX will put on a single page. + +- `\skip`$\,n$ specifies extra space that TeX allocates on the page if + the page contains any insertion $n$ material. This space is in + addition to the space occupied by the insertion itself. For example, + it would account for the space on a page above the footnotes (if + there are any). + +TeX sets `\box`$\,n$, and you should set the other three registers so +that TeX can correctly compute the vertical space required by the +insertion. See pages 122–125 of *The TeXbook* for further details of how +TeX processes this command and of how insertions interact with page +breaking. + +[1] *The TeXbook* uses the term “class” for a code. We use a different +term to avoid confusion with the other meaning of “class”. +]], + insertpenalties = [[ +This parameter contains the sum of certain penalties that +TeX accumulates as it is placing insertions onto the current page. These +penalties are incurred when TeX is processing an `\insert` command and +discovers that a previous insertion of the same kind on this page has +been split, leaving part of it for subsequent pages. See pages 123–125 +of *The TeXbook* for the details of this calculation. + +`\insertpenalties` has an entirely different meaning during an + +output routine—it’s the number of insertions that have been seen but +that don’t fit on the current page (see page 125 of *The TeXbook*). +]], + interlinepenalty = [[ +This parameter specifies the penalty for breaking a page between the +lines of a paragraph. By setting it to 10000 you can force all page +breaks to occur between paragraphs, provided that the pages have enough +stretch so that TeX can still compose them decently. Plain TeX leaves +`\interlinepenalty` at 0. +]], + item = [[ +`\itemitem`, `\item` + +These commands are useful for creating itemized lists. The entire +paragraph following `argument` is indented by `\parindent` + +(for `\item`) or by `2\parindent` (for `\itemitem`). (See in “TeX for +the Impatient” for an explanation of `\parindent`.) Then `argument`, +followed by an en space, is placed just to the left of the text of the +first line of the paragraph so that it falls within the paragraph +indentation as specified by `\parindent`. + +If you want to include more than one paragraph in an item, put `\item{}` +in front of the additional paragraphs. +]], + itfam = [[ +`\bffam`, `\itfam`, `\slfam`, `\ttfam` + +These commands define type families for use in math mode. Their +principal use is in defining the `\it`, `\bf`, `\sl`, and `\tt` commands +so that they work in math mode. +]], + jobname = [[ +This command produces the base name of the file with which TeX was +invoked. For example, if your main input file is `hatter.tex`, +`\jobname` will expand to `hatter`. `\jobname` is most useful when +you’re creating an auxiliary file to be associated with a document. +]], + jot = [[ +This parameter defines a distance that is equal to three points (unless +you change it). The `\jot` is a convenient unit of measure for opening +up math displays. +]], + kern = [[ +The effect of this command depends on the mode that TeX is in when it +encounters it: + +- In a horizontal mode, TeX moves its position to the right (for a + positive kern) or to the left (for a negative kern). + +- In a vertical mode, TeX moves its position down the page (for a + positive kern) or up the page (for a negative kern). + +Thus a positive kern produces empty space while a negative kern causes +TeX to back up over something that it’s already produced. This notion of +a kern is different from the notion of a kern in some computerized +typesetting systems—in TeX, positive kerns push two letters *apart* +instead of bringing them closer together. + +A kern is similar to glue, except that (a) a kern can neither stretch +nor shrink, and (b) TeX will only break a line or a page at a kern if +the kern is followed by glue and is not part of a math formula. If +TeX finds a kern at the end of a line or a page, it discards the kern. +If you want to get the effect of a kern that never disappears, use +`\hglue` or `\vglue`. + +You can use `\kern` in math mode, but you can’t use `mu` units for +`dimen`. If you want `mu` units, use `\mkern` instead. +]], + language = [[ +Different languages have different sets of hyphenation rules. This +parameter determines the set of hyphenation rules that TeX uses. By +changing `\language` you can get TeX to hyphenate portions of text or +entire documents according to the hyphenation rules appropriate to a +particular language. + +Your local information about TeX will tell you if any additional sets of +hyphenation rules are available (besides the ones for English) and what +the appropriate values of `\language` are. The default value of +`\language` is 0. + +TeX sets the current language to 0 at the start of every paragraph, +and compares `\language` to the current language whenever it adds a +character to the current paragraph. If they are not the same, TeX adds a +whatsit indicating the language change. This whatsit is the clue in +later processing that the language rules should change. +]], + lastkern = [[ +`\lastbox`, `\lastkern`, `\lastpenalty`, `\lastskip` + +These control sequences yield the value of the last item on the current +list. They aren’t true commands because they can only appear as part of +an argument. If the last item on the list isn’t of the indicated type, +they yield a zero value (or an empty box, in the case of `\lastbox`). +For example, if the last item on the current list is a kern, `\lastkern` +yields the dimension of that kern; if it isn’t a kern, it yields a +dimension of 0. + +Using `\lastbox` has the additional effect of removing the last box from +the list. If you want the original `\lastbox` to remain on the list, you +have to add a copy of it to the list. `\lastbox` is not permitted in a +math list or in the main vertical list. + +These control sequences are most useful after macro calls that might +have inserted entities of the indicated kinds. +]], + lbrace = [[ +`\langle` (⟨), `\lbrace`, `\lbrack`, `\lceil` (⌈), `\lfloor` (⌊), +`\rangle` (⟩), `\rbrace`, `\rbrack`, `\rceil` (⌉), `\rfloor` (⌋) + +These commands produce left and right delimiters. Mathematicians use +delimiters to indicate the boundaries between parts of a formula. Left +delimiters are also called “openings”, and right delimiters are also +called “closings”. Openings and closings are two of TeX’s classes of +math symbols. TeX puts different amounts of space around different +classes of math symbols. You might expect the space that TeX puts around +openings and closings to be symmetrical, but in fact it isn’t. + +Some left and right delimiters have more than one command that you can +use to produce them: + +- ‘$\{$’ (`\lbrace` and `\{`) + +- ‘$\}$’ (`\rbrace` and `\}`) + +- ‘$[$’ (`\lbrack` and ‘`[`’) + +- ‘$]$’ (`\rbrack` and ‘`]`’) + +You can also use the left and right bracket characters (in either form) +outside of math mode. + +In addition to these commands, TeX treats ‘`(`’ as a left delimiter and +‘`)`’ as a right delimiter. + +You can have TeX choose the size for a delimiter by using `\left` and +`\right`. Alternatively, you can get a delimiter of a specific size by +using one of the `\big`$x$ commands). +]], + lccode = [[ +`\lccode`, `\uccode` + +The `\lccode` and `\uccode` values for the 256 possible input +characters specify the correspondence between the lowercase and +uppercase forms of letters. These values are used by the `\lowercase` +and `\uppercase` commands respectively and by TeX’s hyphenation +algorithm. + +TeX initializes the values of `\lccode` and `\uccode` as follows: + +- The `\lccode` of a lowercase letter is the ASCII code for that + letter. + +- The `\lccode` of an uppercase letter is the ASCII code for the + corresponding lowercase letter. + +- The `\uccode` of an uppercase letter is the ASCII code for that + letter. + +- The `\uccode` of a lowercase letter is the ASCII code for the + corresponding uppercase letter. + +- The `\lccode` and `\uccode` of a nonletter are both zero. + +Most of the time there’s no reason to change these values, but you might +want to change them if you’re using a language that has more letters +than English. +]], + ldots = [[ +`\cdots` (⋯), `\ldots` (…) + +These commands produce three dots in a row. For `\ldots`, the dots are +on the baseline; for `\cdots`, the dots are centered with respect to the +axis). +]], + leaders = [[ +`\cleaders`, `\leaders`, `\xleaders` + +These commands produce leaders, i.e., they fill a horizontal or vertical +space with copies of a pattern . The `box` or `rule` specifies a leader, +i.e., a single copy of the pattern, while the `skip command` specifies a +window to be filled with a row or a column of the leaders. The pattern +is repeated as many times as will fit into the window. If `skip command` +is a horizontal skip, the window contains a row of leaders and TeX must +be in a horizontal mode; if `skip command` is a vertical skip, the +window contains a column of leaders and TeX must be in a vertical mode. + +The commands differ in how they arrange the repeated pattern in the +space and where they put any leftover space: + +- For `\leaders`, TeX aligns a row of leaders with the left end of the + innermost box $B$ that is to contain the result of the `\leaders` + command. It aligns a column of leaders with the top of $B$. Those + leaders that fall entirely within the window are retained. Any + leftover space at the top and bottom of the window is left empty. + +- For `\cleaders`, the leaders are centered within the window. + +- For `\xleaders` the pattern is uniformly distributed throughout the + window. If the leftover space is $l$ and the leader is repeated $n$ + times, TeX puts space of width or height $l/(n+1)$ between adjacent + leaders and at the two ends (left and right or top and bottom) of + the leaders. +]], + left = [[ +`\left`, `\right` + +These commands must be used together in the pattern: + +This construct causes TeX to produce `subformula`, enclosed in the +delimiters `delim_1` and `delim_2`. The vertical size of the delimiter +is adjusted to fit the vertical size (height plus depth) of +`subformula`. `delim_1` and `delim_2` need not correspond. For instance, +you could use ‘`]`’ as a left delimiter and ‘`(`’ as a right delimiter +in a single use of `\left` and `\right`. + +`\left` and `\right` have the important property that they define a +group, i.e., they act like left and right braces. This grouping property +is particularly useful when you put `\over` or a related command between +`\left` and `\right`, since you don’t need to put braces around the +fraction constructed by `\over`. + +If you want a left delimiter but not a right delimiter, you can use +‘`.`’ in place of the delimiter you don’t want and it will turn into +empty space (of width `\nulldelimiterspace`). +]], + leftarrow = [[ +`\Downarrow` (⇓), `\Leftarrow` (⇐), `\Leftrightarrow` (⇔), +`\Longleftarrow` (⇐), `\Longleftrightarrow` (⇔), `\Longrightarrow` (⇒), +`\Rightarrow` (⇒), `\Uparrow` (⇑), `\Updownarrow` (⇕), `\downarrow` (↓), +`\gets` (←), `\hookleftarrow` (↩), `\hookrightarrow` (↪), `\leftarrow` +(←), `\leftharpoondown` (↽), `\leftharpoonup` (↼), `\leftrightarrow` +(↔), `\longleftarrow` (←), `\longleftrightarrow` (↔), `\longmapsto` (↦), +`\longrightarrow` (→), `\mapsto` (↦), `\nearrow` (↗), `\nwarrow` (↖), +`\rightarrow` (→), `\rightharpoondown` (⇁), `\rightharpoonup` (⇀), +`\rightleftharpoons` (⇌), `\searrow` (↘), `\swarrow` (↙), `\to` (→), +`\uparrow` (↑), `\updownarrow` (↕) + +These commands provide arrows of different kinds. They are classified as +relations. The vertical arrows in the list are also delimiters, so you +can make them larger by using `\big` et al. + +The command `\iff` differs from `\Longleftrightarrow` in that it +produces extra space to the left and right of the arrow. + +You can place symbols or other legends on top of a left or right arrow +with `\buildrel`. +]], + leftarrowfill = [[ +`\leftarrowfill`, `\rightarrowfill` + +These commands fill the enclosing horizontal space with left-pointing or +right-pointing arrows. +]], + lefthyphenmin = [[ +`\lefthyphenmin`, `\righthyphenmin` + +These parameters specify the smallest word fragments that TeX allows at +the left and at the right end of a hyphenated word. Plain TeX defaults +them to 2 and 3 respectively; these are the recommended values for +English. +]], + leftskip = [[ +`\leftskip`, `\rightskip` + +These parameters tell TeX how much glue to place at the left and at the +right end of each line of the current paragraph. We’ll just explain how +`\leftskip` works since `\rightskip` is analogous. + +You can increase the left margin by setting `\leftskip` to a fixed +nonzero dimension. If you give `\leftskip` some stretch, you can produce +ragged left text, i.e., text that has an uneven left margin. + +Ordinarily, you should enclose any assignment to `\leftskip` in a group +together with the affected text in order to keep its effect from +continuing to the end of your document. However, it’s pointless to +change `\leftskip`’s value inside a group that is in turn contained +within a paragraph—the value of `\leftskip` at the *end* of a paragraph +is what determines how TeX breaks the paragraph into lines. +]], + let = [[ +This command causes `control sequence` to acquire the current meaning of +`token`. Even if you redefine `token` later, the meaning of +`control sequence` will not change. Although `token` is most commonly a +control sequence, it can also be a character token. +]], + lgroup = [[ +`\lgroup`, `\rgroup` + +These commands produce large left and right parentheses that are defined +as opening and closing delimiters. The smallest available size for these +delimiters is `\Big`. If you use smaller sizes, you’ll get weird +characters. +]], + limits = [[ +In text style, TeX normally places limits after a large operator. This +command tells TeX to place limits above and below a large operator +rather than after it. + +If you specify more than one of `\limits`, `\nolimits`, and +`\displaylimits`, the last command rules. +]], + line = [[ +This command produces an hbox containing `argument`. The hbox is exactly +as wide as the current line, i.e., it extends from the right margin to +the left margin. +]], + linepenalty = [[ +This parameter specifies the penalty that TeX assesses for each line +break when it is breaking a paragraph into lines. The penalty is +independent of where the line break occurs. Increasing the value of this +parameter causes TeX to try harder to set a paragraph with a minimum +number of lines, even at the cost of other aesthetic considerations such +as avoiding overly tight interword spacing. Demerits are in units of +badness squared, so you need to assign a rather large value to this +parameter (in the thousands) for it to have any effect. Plain TeX sets +`\linepenalty` to 10. +]], + llap = [[ +`\llap`, `\rlap` + +These commands enable you to produce text that overlaps whatever happens +to be to the left or to the right of the current position. `\llap` +backspaces by the width of `argument` and then typesets `argument`. +`\rlap` is similar, except that it typesets `argument` first and then +backspaces. `\llap` and `\rlap` are useful for placing text outside of +the current margins. Both `\llap` and `\rlap` do their work by creating +a box of zero width. + +You can also use `\llap` or `\rlap` to construct special characters by +overprinting, but don’t try it unless you’re sure that the characters +you’re using have the same width (which is the case for a monospaced +font such as `cmtt10`, the Computer Modern 10-point typewriter font). +]], + long = [[ +This command is used as a prefix to a macro definition. It tells +TeX that the arguments to the macro are permitted to include `\par` +tokens, which normally indicate the end of a paragraph. + +If TeX tries to expand a macro defined without `\long` and any of the +macro’s arguments include a `\par` token, TeX will complain about a +runaway argument. The purpose of this behavior is to provide you with +some protection against unterminated macro arguments. `\long` gives you +a way of bypassing the protection. +]], + loop = [[ +`\loop`, `\repeat` + +These commands provide a looping construct for TeX. Here $\alpha$ and +$\beta$ are arbitrary sequences of commands and is any of the +conditional tests described in “TeX for the Impatient”, Conditional +tests,conds. The `\repeat` replaces the `\fi` corresponding to the test, +so you must not write an explicit `\fi` to terminate the test. Nor, +unfortunately, can you associate an `\else` with the test. If you want +to use the test in the opposite sense, you need to rearrange the test or +define an auxiliary test with `\newif` (see above) and use that test in +the sense you want (see the second example below). + +TeX expands `\loop` as follows: + +1. $\alpha$ is expanded. + +2. is performed. If the result is false, the loop is terminated. + +3. $\beta$ is expanded. + +4. The cycle is repeated. +]], + looseness = [[ +This parameter gives you a way to change the total number of lines in a +paragraph from what they optimally would be. `\looseness` is so named +because it’s a measure of how loose the paragraph is, i.e., how much +extra space there is in it. + +Normally, `\looseness` is 0 and TeX chooses line breaks in its usual +way. But if `\looseness` is, say, 3, TeX does the following: + +1. It chooses line breaks normally, resulting in a paragraph of $n$ + lines. + +2. It discards these line breaks and tries to find a new set of line + breaks that gives the paragraph $n+3$ lines. (Without the previous + step, TeX wouldn’t know the value of $n$.) + +3. If the previous attempt results in lines whose badness exceeds + `\tolerance`, + + it tries to get $n+2$ lines—and if that also fails, $n+1$ lines, and + finally $n$ lines again. + +Similarly, if looseness is $-n$, TeX attempts to set the paragraph with +$n$ fewer lines than normal. The easiest way for TeX to make a paragraph +one line longer is to put a single word on the excess line. You can +prevent this by putting a tie between the last two words of the +paragraph. + +Setting `\looseness` is the best way to force a paragraph to occupy a +given number of lines. Setting it to a negative value is useful when +you’re trying to increase the amount of text you can fit on a page. +Similarly, setting it to a positive value is useful when you’re trying +to decrease the amount of text on a page. + +TeX sets `\looseness` to 0 when it ends a paragraph, after breaking +the paragraph into lines. If you want to change the looseness of several +paragraphs, you must do it individually for each one or put the change +into `\everypar` . +]], + lower = [[ +`\lower`, `\raise` + +These commands move `box` up or down by `dimen` (which can be negative). +You can only apply `\raise` and `\lower` to a box that’s in a horizontal +list. +]], + lowercase = [[ +`\lowercase`, `\uppercase` + +These commands convert the letters in `token list`, i.e., those tokens +with category code 11, to their lowercase and uppercase forms. The +conversion of a letter is defined by its `\lccode` (for lowercase) or +`\uccode` (for uppercase) table value. Tokens in the list that are not +letters are not affected—even if the tokens are macro calls or other +commands that expand into letters. +]], + lq = [[ +`\P` (¶), `\S` (§), `\copyright` (©), `\dag`, `\ddag`, `\lbrack`, `\lq` +(‘), `\rbrack`, `\rq` (’) + +These commands produce various special characters and marks. The first +five commands are necessary because TeX by default attaches special +meanings to the characters (`#`, `$`, `%`, `&`, `_`). You needn’t be in +math mode to use these commands. + +You can use the dollar sign in the Computer Modern italic fonts to get +the pound sterling symbol, as shown in the example below. +]], + magnification = [[ +`\magnification`, `\mag` + +An assignment to `\magnification` establishes the “scale factor” $f$ +that determines the magnification ratio of your document . The +assignment to `\magnification` must occur before the first page of your +document has been shipped out. + +The assignment sets $f$ to `number` and also sets `\hsize` and `\vsize` + +respectively to `6.5true in` and `8.9true in`, the values appropriate +for an $8 \frac1/2$- by-11-inch page. $f$ must be between 0 and +32768. The magnification ratio of the document is $f/1000$. A scale +factor of 1000 provides unit magnification, i.e., it leaves the size +of your document unchanged. It’s customary to use powers of $1.2$ as +scale factors, and most libraries of fonts are based on such factors. +You can use the `\magstep` and `\magstephalf` commands to specify +magnifications by these factors. + +`\magnification` is not a parameter. You can’t use it to *retrieve* the +scale factor. If you write something like `\dimen0 = \magnification`, +TeX will complain about it. + +The `\mag` parameter contains the scale factor. Changing the value of +`\mag` rescales the page dimensions, which is not usually what you want. +Therefore it’s usually better to change the magnification by assigning +to `\magnification` rather than to `\mag`. +]], + magstep = [[ +This command expands to the magnification ratio needed to magnify +everything in your document (other than `true` dimensions) by $1.2^r$, +where $r$ is the value of `number`. `number` must be between 0 and +5. +]], + magstephalf = [[ +This command expands to the magnification ratio needed to magnify +everything in your document (other than `true` dimensions) by +$\sqrt{1.2}$, i.e., halfway between 1 and $1.2$. +]], + mark = [[ +This command causes TeX to append a mark containing `mark text` to +whatever list it is currently constructing. Generally you shouldn’t use +`\mark` within an “inner” construct such as a math formula or a box +you’ve built with an `\hbox`, `\vbox`, or `\vtop` command, because +TeX won’t see the mark when it’s constructing the main box of the page. +But if you use `\mark` in ordinary horizontal mode or directly in an +hbox that’s part of the main vertical list, the mark migrates out to the +main vertical list. See pages 259–260 of *The TeXbook* for examples +showing how `\mark` can be used. +]], + mathaccent = [[ +This command tells TeX to typeset a math accent whose family and +character code are given by `mathcode`. (TeX ignores the class of the +mathcode.) See Appendix G of *The TeXbook* for the details of how +TeX positions such an accent. The usual way to use `\mathaccent` is to +put it in a macro definition that gives a name to a math accent. +]], + mathchar = [[ +This command produces the math character whose class, family, and font +position are given by `mathcode`. It is only legal in math mode. +]], + mathchardef = [[ +This command defines `control sequence` as a math character with the +given `mathcode`. The control sequence will only be legal in math mode. +]], + mathchoice = [[ +This command tells TeX to typeset one of the subformulas `math_1`, +`math_2`, `math_3`, or `math_4`, making its choice according to the +current style. That is, if TeX is in display style it sets the +`\mathchoice` as `math_1`; in text style it sets it as `math_2`; in +script style it sets it as `math_3`; and in scriptscript style it sets +it as `math_4`. +]], + mathcode = [[ +This table entry contains the mathcode of the character whose ASCII code +is `charcode` . The mathcode specifies that character’s interpretation +in math mode. +]], + mathinner = [[ +This command tells TeX to treat the construct that follows as an “inner +formula”, e.g., a fraction, for spacing purposes. It resembles the class +commands given just above. +]], + mathord = [[ +`\mathbin`, `\mathclose`, `\mathopen`, `\mathop`, `\mathord`, +`\mathpunct`, `\mathrel` + +These commands tell TeX to treat the construct that follows as belonging +to a particular class (see page 154 of *The TeXbook* for the definition +of the classes). They are listed here in the order of the class numbers, +from 0 to 6. Their primary effect is to adjust the spacing around +the construct to be whatever it is for the specified class. +]], + mathpalette = [[ +This command provides a convenient way of producing a math construct +that works in all four styles. To use it, you’ll normally need to define +an additional macro, which we’ll call `\build`. The call on +`\mathpalette` should then have the form `\mathpalette`||`argument`. + +`\build` tests what style TeX is in and typesets `argument` accordingly. +It should be defined to have two parameters. When you call +`\mathpalette`, it will in turn call `\build`, with `#1` being a command +that selects the current style and `#2` being `argument`. Thus, within +the definition of `\build` you can typeset something in the current +style by preceding it with ‘`#1`’. See page 360 of *The TeXbook* for +examples of using `\mathpalette` and page 151 of *The TeXbook* for a +further explanation of how it works. +]], + mathstrut = [[ +This command produces a phantom formula whose width is zero and whose +height and depth are the same as those of a left parenthesis. +`\mathstrut` is in fact defined as ‘`\vphantom(`’. Its main use is for +getting radicals, underbars, and overbars to line up with other +radicals, underbars, and overbars in a formula. It is much like +`\strut`, except that it adjusts itself to the different styles that can +occur in math formulas. +]], + mathsurround = [[ +This parameter specifies the amount of space that TeX inserts before and +after a math formula in text mode (i.e., a formula surrounded by single +`$`’s). See page 162 of *The TeXbook* for further details about its +behavior. Plain TeX leaves `\mathsurround` at `0pt`. +]], + maxdeadcycles = [[ +If the value of `\deadcycles` exceeds the value of `\maxdeadcycles`, +TeX assumes that the output routine has gotten into a loop. TeX then +complains and runs its own simple output routine, equivalent to +`\shipout!allowbreak\box255`, that is likely to break the loop. Plain +TeX sets `\maxdeadcycles` to 25. +]], + maxdepth = [[ +This parameter specifies the maximum depth of the bottom box on a page. +It is related to `\boxmaxdepth`. If the depth of the bottom box on a +page exceeds `\maxdepth`, TeX moves the box’s reference point down so +that it’s `\maxdepth` from the bottom of that box. Without this +adjustment, the bottom box on a page could extend well into the bottom +margin or even off the page entirely. Plain TeX sets `\maxdepth` to +`4pt`. +]], + maxdimen = [[ +This control sequence yields a `dimen` that is the largest dimension +acceptable to TeX (nearly 18 feet). It is not a true command because it +can only appear as part of an argument to another command. +]], + meaning = [[ +This command produces the meaning of `token`. It is useful for +diagnostic output. You can use the `\the` command in a similar way to +get information about the values of registers and other TeX entities. +]], + message = [[ +`\errmessage`, `\message` + +These commands display the message given by `token list` on your +terminal and also enter it into the log. Any macros in the message are +expanded, but no commands are executed. This is the same rule that +TeX uses for `\edef`. + +For `\errmessage`, TeX pauses in the same way that it does for one of +its own error messages and displays the `\errhelp` tokens if you ask for +help. + +You can generate multiline messages by using the `\newlinechar` +character. +]], + mkern = [[ +This command produces a kern, i.e., blank space, of width `mudimen`. The +kern is measured in mathematical units, which vary according to the +style. Aside from its unit of measurement, this command behaves just +like `\kern` does in horizontal mode. +]], + month = [[ +TeX sets this parameter to the current month. It is a number between 1 +and 12. `\month` is set at the beginning of your run (see the comments +on `\time` above). +]], + moveleft = [[ +`\moveleft`, `\moveright` + +These commands move `box` left or right by `dimen` (which can be +negative). You can only apply `\moveleft` and `\moveright` to a box +that’s in a vertical list. +]], + mskip = [[ +This command produces horizontal glue that has natural width +`mudimen_1`, stretch `mudimen_2`, and shrink `mudimen_3`. The glue is +measured in mathematical units, which vary according to the style. Aside +from its units of measurement, this command behaves just like `\hskip`. +]], + multiply = [[ +`\divide`, `\multiply` + +These commands multiply and divide the value in `register` by `number` +(which can be negative). The register can be a `\count`, `\dimen`, +`\skip`, or `\muskip` register. For a `\skip` or `\muskip` register, all +three components of the glue in the register are modified. You can omit +the word `by` in these commands—TeX will understand them anyway. + +You can also obtain a multiple of a `dimen` by preceding it by a +`number` + +or decimal constant, e.g., `-2.5\dimen2`. You can also use this notation +for `glue`, but watch out—the result is a `dimen`, not `glue`. Thus +`2\baselineskip` yields a `dimen` that is twice the natural size of +`\baselineskip`, with no stretch or shrink. +]], + multispan = [[ +This command tells TeX that the following `number` columns in a row of a +horizontal alignment, or `number` rows in a column of a vertical +alignment, should be combined into a single column or row (as with +`\span`) and that their templates should be omitted (as with `\omit`). +]], + narrower = [[ +This command makes paragraphs narrower, increasing the left and right +margins by `\parindent`, the current paragraph indentation. It achieves +this by increasing both `\leftskip` and `\rightskip` by `\parindent`. +Normally you place `\narrower` at the beginning of a group containing +the paragraphs that you want to make narrower. If you forget to enclose +`\narrower` within a group, you’ll find that all the rest of your +document will have narrow paragraphs. + +`\narrower` affects just those paragraphs that end after you invoke it. +If you end a `\narrower` group before you’ve ended a paragraph, +TeX won’t make that paragraph narrower. +]], + negthinspace = [[ +This command produces a negative kern whose width is one-sixth of an em +, i.e., it causes TeX to move its position left by that amount. It is +useful for bringing together characters that are a little too far apart. +TeX won’t break a line at a `\negthinspace`. +]], + newif = [[ +This command names a trio of control sequences with names `\alphatrue`, +`\alphafalse`, and `\ifalpha`, where `alpha` is `test name`. You can use +them to define your own tests by creating a logical variable that +records true/false information: + +- `\alphatrue` sets the logical variable `alpha` true. + +- `\alphafalse` sets the logical variable `alpha` false + +- `\ifalpha` is a conditional test that is true if the logical + variable `alpha` is true and false otherwise. + +The logical variable `alpha` doesn’t really exist, but TeX behaves as +though it did. After `\newif\ifalpha`, the logical variable is initially +false. + +`\newif` is an outer command, so you can’t use it inside a macro +definition. +]], + newlinechar = [[ +This parameter contains a character that indicates a new line on output. +When TeX encounters this character while reading the argument of a +`\write`, `\message`, or `\errmessage` command, it starts a new line. If +`\newlinechar` is not in the range 0–255, there is no character that +indicates a new line on output. Plain TeX sets `\newlinechar` to $-1$. +]], + noalign = [[ +This command inserts `vertical mode material` after the current row of a +horizontal alignment or `horizontal mode material` after the current +column of a vertical alignment. The material can be text, glue, a rule, +or anything else. + +The most common use of `\noalign` is to put extra space after a row or +column. If you want to put extra space after *every* row of a horizontal +alignment, use `\openup`. +]], + noboundary = [[ +You can defeat a ligature or kern that TeX applies to the first or last +character of a word by putting `\noboundary` just before or just after +the word. Certain fonts intended for languages other than English +contain a special boundary character that TeX puts at the beginning and +end of each word. The boundary character occupies no space and is +invisible when printed. It enables TeX to provide different +typographical treatment to characters at the beginning or end of a word, +since the boundary character can be part of a sequence of characters to +be kerned or replaced by a ligature. (None of the standard TeX fonts +contain this boundary character.) The effect of `\noboundary` is to +delete the boundary character if it’s there, thus preventing TeX from +recognizing the ligature or kern. +]], + nobreak = [[ +This command prevents a page break where it otherwise might occur. +`\nobreak` can also be used in horizontal mode. +]], + noexpand = [[ +This command tells TeX to suppress expansion of `token` if `token` is a +control sequence that can be expanded. If `token` can’t be expanded, +e.g., it’s a letter, TeX acts as though the `\noexpand` wasn’t there and +processes `token` normally. In other words the expansion of +‘`\noexpand``token`’ is simply `token` no matter what `token` happens to +be. +]], + noindent = [[ +If TeX is in vertical mode, as it is after ending a paragraph, this +command inserts the `\parskip` interparagraph glue, puts TeX into +horizontal mode, and starts an unindented paragraph. It has no effect in +horizontal mode, i.e., within a paragraph. Starting a paragraph with +`\noindent` thus cancels the indentation by `\parindent` that would +normally occur there. + +A common use of `\noindent` is to cancel the indentation of the first +line of a paragraph when the paragraph follows some displayed material. +]], + nointerlineskip = [[ +This command tells TeX not to insert interline glue in front of the next +line. It has no effect on subsequent lines. +]], + nolimits = [[ +In display style, TeX normally places limits above and below a large +operator. This command tells TeX to place limits after a large operator +rather than above and below it. + +The integral operators `\int` and `\oint` are exceptions—TeX places +limits after them in all cases, unless overridden, as in `\int\limits`. +(plain TeX defines `\int` and `\oint` as macros that specify the +operator symbol followed by `\nolimits`—this is what causes them to +behave differently by default.) + +If you specify more than one of `\limits`, `\nolimits`, and +`\displaylimits`, the last command rules. +]], + nonscript = [[ +When TeX is currently typesetting in script or scriptscript style and +encounters this command immediately in front of glue or a kern, it +cancels the glue or kern. `\nonscript` has no effect in the other +styles. + +This command provides a way of “tightening up” the spacing in script and +scriptscript styles, which generally are set in smaller type. It is of +little use outside of macro definitions. +]], + nonstopmode = [[ +This command tells TeX not to stop for errors, even those pertaining to +files that it can’t find, but to continue displaying the error messages +on your terminal. Typing ‘`R`’ or ‘`r`’ in response to an error message +puts you into nonstop mode. +]], + nopagenumbers = [[ +By default, plain TeX produces a footer containing a centered page +number. This command tells TeX to produce a blank footer instead. +]], + normalbaselineskip = [[ +`\normalbaselineskip`, `\normalbaselines`, `\normallineskiplimit`, +`\normallineskip` + +The three parameters contain values for `\baselineskip`, `\lineskip`, +and `\lineskiplimit` respectively. + +The `\normalbaselines` command sets `\baselineskip`, `\lineskip`, and +`\lineskiplimit` to the values contained in the three parameters. +]], + null = [[ +This command produces an empty hbox. +]], + nulldelimiterspace = [[ +This parameter specifies the width of the space produced by a null +delimiter. Plain TeX sets `\nulldelimiterspace` to `1.2pt`. +]], + nullfont = [[ +This command selects a font, built into TeX, that has no characters in +it. TeX uses it as a replacement for an undefined font in a family of +math fonts. +]], + number = [[ +This command produces the representation of a number as a sequence of +character tokens. The number can be either an explicit integer, a +`number` parameter, or a `number` register. +]], + obeylines = [[ +TeX normally treats an end of line as a space. `\obeylines` instructs +TeX to treat each end of line as an end of paragraph, thus forcing a +line break. `\obeylines` is often useful when you’re typesetting verse +or computer programs. + +If any of your lines are longer than the effective line length (`\hsize` +- `\parindent`), however, you may get an extra line break within those +lines. + +Because TeX inserts the `\parskip` glue between lines controlled by +`\obeylines` (since it thinks each line is a paragraph), you should +normally set `\parskip` to zero when you’re using `\obeylines`. + +You can use the `\obeyspaces` command to get TeX to take spaces within a +line literally. `\obeylines` and `\obeyspaces` are often used together. +]], + obeyspaces = [[ +TeX normally condenses a sequence of several spaces to a single space. +`\obeyspaces` instructs TeX to produce a space in the output for each +space in the input. `\obeyspaces` does not cause spaces at the beginning +of a line to show up, however; for that we recommend the +`\obeywhitespace` command defined in `eplain.tex` . + +`\obeyspaces` is often useful when you’re typesetting something, +computer input for example, in a monospaced font (one in which each +character takes up the same amount of space) and you want to show +exactly what each line of input looks like. + +You can use the `\obeylines` command to get TeX to follow the line +boundaries of your input. `\obeylines` is often used in combination with +`\obeyspaces`. +]], + offinterlineskip = [[ +This command tells TeX to stop inserting interline glue from now on. +Unless you want it to be in effect for the rest of the document (which +you probably don’t), you should enclose it in a group together with the +text you want it to affect. Its main purpose is to let you do interline +spacing yourself, e.g., using struts, without interference from TeX’s +normal interline glue. `\offinterlineskip` is often useful when you’re +constructing a horizontal alignment. +]], + omit = [[ +This command tells TeX to ignore a template in a horizontal or vertical +alignment while processing a particular column or row entry +respectively. `\omit` must appear as the first item in a column or row +entry; in effect, it overrides the template from the preamble with the +simple template ‘`#`’. +]], + openin = [[ +This command tells TeX to open the file named `filename` and make it +available for reading via the input stream designated by `number`. + +`number` must be between 0 and 15. Once you’ve opened a file and +connected it to an input stream, you can read from the file using the +`\read` command with the input stream’s number. + +You can associate more than one input stream with the same file. You can +then read from several different positions within the file, one for each +input stream. + +You should allocate stream numbers for `\openin` using `\newread`. +]], + openout = [[ +This command tells TeX to open the file named `filename` and make it +available for writing via the output stream designated by `number`. +`number` must be between 0 and 15. Once you’ve opened a file and +connected it to an output stream, you can write to the file using the +`\write` command with the output stream’s number. + +An `\openout` generates a whatsit that becomes part of a box. The +`\openout` does not take effect until TeX ships out that box to the .dvi +file, unless you’ve preceded the `\openout` with `\immediate`. + +TeX won’t complain if you associate more than one output stream with the +same file, but you’ll get garbage in the file if you try it! + +You should allocate stream numbers for `\openout` using `\newwrite`. +]], + openup = [[ +This command increases `\baselineskip` by `dimen`. An `\openup` command +before the end of a paragraph affects the entire paragraph, so you +shouldn’t use `\openup` to change `\baselineskip` within a paragraph. +`\openup` is most useful for typesetting tables and math displays—a +little extra space between rows often makes them more readable. +]], + outer = [[ +This command is used as a prefix to a macro definition. It tells +TeX that the macro is outer and cannot be used in certain contexts. If +the macro is used in a forbidden context, TeX will complain. +]], + output = [[ +This parameter contains the current output routine, i.e., the token list +that TeX expands when it finds a page break. TeX puts the page into +`\box255`, so `\output` is responsible for doing something with +`\box255`—either shipping it out or putting it somewhere else. The +output routine is also responsible for attaching things such as headers +and footers. +]], + outputpenalty = [[ +TeX sets this parameter when it breaks a page. If the breakpoint was at +a penalty item, TeX removes the penalty item and sets `\outputpenalty` +to the penalty value at the breakpoint; otherwise it sets +`\outputpenalty` to 0. + +Suppose that you are undoing a page break in order to break the page at +a different place than the one that TeX has just chosen. In order to +reconstruct the page, you need to recreate the penalty at TeX’s chosen +breakpoint. You can accomplish this with the command +`\penalty!allowbreak\outputpenalty`. +]], + over = [[ +`\above`, `\atop`, `\brace`, `\brack`, `\choose`, `\over` + +These commands stack one subformula on top of another one. We will +explain how `\over` works, and then relate the other commands to it. + +`\over` is the command that you’d normally use to produce a fraction. + +If you write something in one of the following forms: + + $$⟨formula1⟩\over⟨formula2⟩$$ + $⟨formula1⟩\over⟨formula2⟩$ + \left!⟨formula1⟩\over⟨formula2⟩\right! + {⟨formula1⟩\over⟨formula2⟩} + +you’ll get a fraction with numerator `formula_1` and denominator +`formula_2`, i.e., `formula_1` over `formula_2`. In the first three of +these forms the `\over` is not implicitly contained in a group; it +absorbs everything to its left and to its right until it comes to a +boundary, namely, the beginning or end of a group. + +You can’t use `\over` or any of the other commands in this group more +than once in a formula. Thus a formula such as: + + $$a \over n \choose k$$ + +isn’t legal. This is not a severe restriction because you can always +enclose one of the commands in braces. The reason for the restriction is +that if you had two of these commands in a single formula, TeX wouldn’t +know how to group them. + +The other commands are similar to `\over`, with the following +exceptions: + +- `\atop` leaves out the fraction bar. + +- `\above` provides a fraction bar of thickness `dimen`. + +- `\choose` leaves out the fraction bar and encloses the construct in + parentheses. (It’s called “choose” because $n \choose k$ is the + notation for the number of ways of choosing $k$ things out of $n$ + things.) + +- `\brace` leaves out the fraction bar and encloses the construct in + braces. + +- `\brack` leaves out the fraction bar and encloses the construct in + brackets. +]], + overfullrule = [[ +This parameter specifies the width of the rule that TeX appends to an +overfull hbox. Plain TeX sets it to `5pt`. +]], + overwithdelims = [[ +`\abovewithdelims`, `\atopwithdelims`, `\overwithdelims` + +Each of these commands stacks one subformula on top of another one and +surrounds the entire construct with `delim_1` on the left and `delim_2` +on the right. These commands follow the same rules as `\over`, `\atop`, +and `\above`. The `dimen` in `\abovewithdelims` specifies the thickness +of the fraction bar. +]], + pagedepth = [[ +This parameter specifies the depth of the current page. TeX updates +`\pagedepth` as it adds items to the main vertical list. +]], + pagegoal = [[ +This parameter specifies the desired height for the current page. +TeX sets `\pagegoal` to the current value of `\vsize` when it first puts +a box or an insertion on the current page. You can shorten a page while +TeX is working on it by changing the value of `\pagegoal`—even if the +new value is less than the height of the material already on that page. +TeX will just put the extra material on the next page. But +remember—`\pagegoal` is reset to `\vsize` again when TeX starts the next +page. +]], + pageno = [[ +This parameter contains the current page number as an integer. The page +number is normally negative for front-matter pages that are numbered +with small roman numerals instead of arabic numerals. If you change the +page number within a page, the changed number will be used in any +headers or footers that appear on that page. The actual printing of page +numbers is handled by TeX’s output routine, which you can modify. + +Plain TeX keeps the page number in the register `\count0`. (`\pageno` +is, in fact, a synonym for `\count0`.) Whenever it ships out a page to +the .dvi file, + +TeX displays the current value of `\count0` on your terminal so that you +can tell which page it is working on. It’s possible to use registers +`\count1`–`\count9` for nested levels of page numbers (you must program +this yourself). If any of these registers are nonzero, TeX displays them +on your terminal also.[1] + +[1] More precisely, it displays all registers in sequence from `\count0` +to `\count9`, but omits trailing zero registers. For instance, if the +values of `\count0`–`\count3` are $(17, 0 , 0, 7)$ and the others are +0, TeX displays the page number as \[17.0.0.7\]. +]], + pageshrink = [[ +This parameter specifies the amount of shrink in the accumulated glue on +the current page. TeX updates `\pageshrink` as it adds items to the main +vertical list. +]], + pagestretch = [[ +`\pagefilllstretch`, `\pagefillstretch`, `\pagefilstretch`, +`\pagestretch` + +These four parameters together specify the amount of stretch in the glue +on the current page. The amount of stretch has the form +$n_0 + n_1fil + n_2fill + n_3filll$, with the four parameters giving the +values of the four $n_i$. TeX updates these parameters as it adds items +to the main vertical list. +]], + pagetotal = [[ +This parameter specifies the accumulated natural height of the current +page. TeX updates `\pagetotal` as it adds items to the main vertical +list. +]], + parfillskip = [[ +This parameter specifies the horizontal glue that TeX inserts at the end +of a paragraph. The default value of `\parfillskip` is `0pt plus 1fil`, +which causes the last line of a paragraph to be filled out with blank +space. A value of `0pt` forces TeX to end the last line of a paragraph +at the right margin. +]], + parindent = [[ +This parameter specifies the amount by which the first line of each +paragraph is to be indented. As the example below shows, it’s a bad idea +to set both `\parindent` and `\parskip` to zero since then the paragraph +breaks are no longer apparent. +]], + parshape = [[ +This command specifies the shape of the first $n$ lines of a paragraph— +the next paragraph if you’re in vertical mode and the current paragraph +if you’re in horizontal mode. The $i$’s and $l$’s are all dimensions. +The first line is indented by $i_1$ and has length $l_1$, the second +line is indented by $i_2$ and has length $l_2$, and so forth. If the +paragraph has more than $n$ lines, the last indentation/ length pair is +used for the extra lines. To achieve special effects such as the one +shown here, you usually have to experiment a lot, insert kerns here and +there, and choose your words to fit the shape. + +`\parshape`, like `\hangafter` and `\hangindent`, is effective only for +one paragraph. If you specify `\hangafter` and `\hangindent` as well as +`\parshape`, TeX ignores the `\hangafter` and `\hangindent`. +]], + parskip = [[ +This parameter specifies the “paragraph skip”, i.e., the vertical glue +that TeX inserts at the start of a paragraph. + +See `\par` for more information about what happens when TeX starts a +paragraph. Plain TeX sets `\parskip` to `0pt plus 0.1pt`. +]], + pausing = [[ +If this parameter is greater than zero, TeX will pause at each line of +input to give you an opportunity to replace it with a different line. If +you type in a replacement, TeX will use that line instead of the +original one; if you respond with ⟨return⟩, TeX will use the original +line. + +Setting `\pausing` to 1 can be useful as a way of patching a document +as TeX is processing it. For example, you can use this facility to +insert `\show` commands (see below). +]], + penalty = [[ +This command produces a penalty item. The penalty item makes TeX more or +less willing to break a page at the point where that item occurs. A +negative penalty, i.e., a bonus, encourages a page break; a positive +penalty discourages a page break. A penalty of 10000 or more prevents +a break altogether, while a penalty of $-10000$ or less forces a break. +`\penalty` can also be used in horizontal mode. +]], + phantom = [[ +This command produces an empty box having the same size and placement +that `argument` would have were it typeset. One use of `\phantom` is for +reserving space for a symbol that for some reason needs to be drawn in +by hand. +]], + plainoutput = [[ +This command invokes plain TeX’s output routine. + +Plain TeX defines `\output` as a token list containing the single token +`\plainoutput`. +]], + pmod = [[ +This command provides a notation for indicating a modulus in parentheses +at the end of a formula. +]], + postdisplaypenalty = [[ +This parameter specifies the penalty for breaking a page just after a +math display. Plain TeX leaves `\postdisplaypenalty` at 0. +]], + predisplaypenalty = [[ +This parameter specifies the penalty for breaking a page just before a +math display. Plain TeX sets `\predisplaypenalty` to 10000. +]], + predisplaysize = [[ +TeX sets this parameter to the width of the line preceding a math +display. TeX uses `\predisplaysize` to determine whether or not the +display starts to the left of where the previous line ends, i.e., +whether or not it visually overlaps the previous line. If there is +overlap, it uses the `\abovedisplayskip` and `\belowdisplayskip` glue in +setting the display; otherwise it uses the `\abovedisplayshortskip` and +`\belowdisplayshortskip` glue. See pages 188–189 of *The TeXbook* for a +more detailed explanation of this parameter. +]], + pretolerance = [[ +`\pretolerance`, `\tolerance` + +These parameters determine the badness that TeX will tolerate on each +line when it is choosing line breaks for a paragraph. The badness is a +measure of how far the interword spacing deviates from the ideal. +`\pretolerance` specifies the tolerable badness for line breaks without +hyphenation; `\tolerance` specifies the tolerable badness for line +breaks with hyphenation. The tolerable badness can be exceeded in either +of two ways: a line is too tight (the interword spaces are too small) or +it is too loose (the interword spaces are too big). + +- If TeX must set a line too loosely, it complains about an “underfull + hbox”. + +- If TeX must set a line too rightly, it lets the line run past the + right margin and complains about an “overfull hbox”. + +TeX chooses line breaks in the following steps: + +1. It attempts to choose line breaks without hyphenating. If none of + the resulting lines have a badness exceeding `\pretolerance`, the + line breaks are acceptable and the paragraph can now be set. + +2. Otherwise, it tries another set of line breaks, this time allowing + hyphenation. If none of the resulting lines have a badness exceeding + `\tolerance`, the new set of line breaks is acceptable and the + paragraph can now be set. + +3. Otherwise, it adds `\emergencystretch` (see below) to the stretch of + each line and tries again. + +4. If none of these attempts have produced an acceptable set of line + breaks, it sets the paragraph with one or more overfull hboxes and + complains about them. + +Plain TeX sets `\tolerance` to 200 and `\pretolerance` to 100. If +you set `\tolerance` to 10000, TeX becomes infinitely tolerant and +accepts any spacing, no matter how bad (unless it encounters a word that +won’t fit on a line, even with hyphenation). Thus by changing +`\tolerance` you can avoid overfull and underfull hboxes, but at the +cost of making the spacing worse. By making `\pretolerance` larger you +can get TeX to avoid hyphenation (and also run faster), again at the +cost of possibly worse spacing. If you set `\pretolerance` to $-1$, +TeX will not even try to set the paragraph without hyphenation. + +The `\hbadness` parameter determines the level of badness that TeX will +tolerate before it complains, but `\hbadness` does not affect the way +that TeX typesets your document. The `\hfuzz` parameter determines the +amount that an hbox can exceed its specified width before TeX considers +it to be erroneous. +]], + prevdepth = [[ +When TeX adds a box to a vertical list, it sets `\prevdepth` to the +depth of that box. TeX sets `\prevdepth` to $-1000$pt at the start of a +vertical list, indicating that the usual interline glue should be +suppressed. +]], + prevgraf = [[ +In horizontal mode, this parameter specifies the number of lines in the +paragraph so far; in vertical mode, it specifies the number of lines in +the previous paragraph. TeX only sets `\prevgraf` after it has finished +breaking some text into lines, i.e., at a math display or at the end of +a paragraph. See page 103 of *The TeXbook* for more details about it. +]], + proclaim = [[ +This command “proclaims” a theorem, lemma, hypothesis, etc. It sets +`argument` in boldface type and the following paragraph in italics. +`argument` must be followed by a period and a space token, which serve +to set off `argument` from `general text`. `general text` consists of +the text up to the next paragraph boundary. You can include multiple +paragraphs by using `\endgraf` instead of a blank line or `\par`. +]], + radical = [[ +This command produces a radical sign whose characteristics are given by +`number`. It uses the same representation as the delimiter code + +in the `\delcode` command. +]], + raggedbottom = [[ +`\normalbottom`, `\raggedbottom` + +Normally TeX tries hard to ensure that all pages have the same depth, +i.e., that their bottom margins are equal. The `\raggedbottom` command +tells TeX to allow some variability among the bottom margins on +different pages. It’s often appropriate to use `\raggedbottom` when you +have material that contains large blocks of material that should not be +split across pages. The `\normalbottom` command cancels the effect of +`\raggedbottom`. +]], + raggedright = [[ +`\raggedright`, `\ttraggedright` + +These commands cause TeX to typeset your document “ragged right”. +Interword spaces all have their natural size, i.e., they all have the +same width and don’t stretch or shrink. Consequently the right margin is +generally not even. The alternative, which is TeX’s default, is to +typeset your document justified, + +i.e., with uniform left and right margins. In justified text, interword +spaces are stretched in order to make the right margin even. Some +typographers prefer ragged right because it avoids distracting “rivers” +of white space on the printed page. + +You should use the `\ttraggedright` command when typesetting text in a +monospaced font and the `\raggedright` command when typesetting text in +any other font. + +Most of the time you’ll want to apply these commands to an entire +document, but you can limit their effects by enclosing them in a group. +]], + relax = [[ +This command tells TeX to do nothing. It’s useful in a context where you +need to provide a command but there’s nothing that you want TeX to do. +]], + relpenalty = [[ +This parameter specifies the penalty for breaking a math formula after a +relation when the formula appears in a paragraph. Plain TeX sets +`\relpenalty` to 500. +]], + romannumeral = [[ +This command produces the roman numeral representation of a number as a +sequence of character tokens. The number can be either an explicit +integer, a `number` parameter, or a `number` register. If the number is +zero or negative, `\romannumeral` produces no tokens. +]], + root = [[ +This command produces the notation for a root of `argument_2`, where the +root is given by `argument_1`. +]], + sb = [[ +`\sb`, `\sp` + +The commands in each column are equivalent. The commands in the first +column typeset `argument` as a subscript, and those in the second column +typeset `argument` as a superscript. The `\sb` and `\sp` commands are +mainly useful if you’re working on a terminal that lacks an underscore +or caret, or if you’ve redefined ‘`_`’ or ‘`\verb`’ and need access to +the original definition. These commands are also used for setting lower +and upper limits on summations and integrals. + +If a subscript or superscript is not a single token, you need to enclose +it in a group. TeX does not prioritize subscripts or superscripts, so it +will reject formulas such as `a_i_j`, `a^i^j`, or `a^i_j`. + +Subscripts and superscripts are normally typeset in script style, or in +scriptscript style if they are second-order, e.g., a subscript on a +subscript or a superscript on a a subscript. You can set *any* text in a +math formula in a script or scriptscript style with the `\scriptstyle` +and `\scriptscriptstyle` commands. + +You can apply a subscript or superscript to any of the commands that +produce named mathematical functions in roman type). In certain cases +(again, see ) the subscript or superscript appears directly above or +under the function name as shown in the examples of `\lim` and `\det` +below. +]], + scriptspace = [[ +This parameter specifies the amount of space that TeX inserts before and +after a subscript or superscript. The `\nonscript` command after a +subscript or superscript cancels this space. Plain TeX sets +`\scriptspace` to `0.5pt`. +]], + scrollmode = [[ +This command tells TeX not to stop for most errors, but to continue +displaying the error messages on your terminal. Typing ‘`S`’ or ‘`s`’ in +response to an error message puts you into scroll mode. +]], + setbox = [[ +`\box`, `\setbox` + +These commands respectively set and retrieve the contents of the box +register whose number is `register`. Note that you set a box register a +little differently than you set the other kinds of registers: you use +`\setbox`$\,n$ `=` rather than `\box`$\,n$ `=`. + +*Retrieving the contents of a box register with these commands has the +side effect of emptying it, so that the box register become void.* If +you don’t want that to happen, you can use `\copy` (see below) to +retrieve the contents. You should use `\box` in preference to `\copy` +when you don’t care about what’s in a box register after you’ve used it, +so as not to exhaust TeX’s memory by filling it with obsolete boxes. +]], + setlanguage = [[ +This command sets the current language to `number` by inserting the same +whatsit that you’d get by changing `\language`. However, it does not +change the value of `\language`. +]], + settabs = [[ +The first form of this command defines a set of tab stops for a tabbing +alignment. It tells TeX to set the tab stops so as to divide each line +into `number` equal parts. TeX takes the length of a line to be +`\hsize`, as usual. You can make the alignment narrower by decreasing +`\hsize`. +]], + shipout = [[ +This command instructs TeX to send `box` to the .dvi file. + +TeX expands any `\write` command in `box` as part of `\shipout`. + +The principal use of `\shipout` is in the output routine, but you can +use it anywhere. +]], + show = [[ +`\showbox`, `\showlists`, `\showthe`, `\show` + +These commands record information in the log of your TeX run: + +- `\show` records the meaning of `token`. + +- `\showthe` records whatever tokens would be produced by `\the` + `argument`). + +- `\showbox` records the contents of the box register numbered + `number`. The number of leading dots in the log indicates the number + of levels of nesting of inner boxes. + +- `\showlists` records the contents of each list that TeX is currently + constructing. (These lists are nested one within another.) See + pages 88–89 of *The TeXbook* for further information about + interpreting the output of `\showlists`. + +For `\show` and `\showthe`, TeX also displays the information at your +terminal. For `\showbox` and `\showlists`, TeX displays the information +at your terminal only if `\tracingonline` is greater than zero; if +`\tracingonline` is zero or less (the default case), the information is +not displayed. + +Whenever TeX encounters a `\show`-type command it stops for interaction. +The request for interaction does *not* indicate an error, but it does +give you an opportunity to ask TeX to show you something else. If you +don’t want to see anything else, just press ⟨return⟩. + +You can control the amount of output produced by `\showbox` by setting +`\showboxbreadth` and `\showboxdepth`. + +These parameters respectively have default values of 5 and 3, which +is why just five items appear for each box described in the log output +below. (The ‘`..etc.`’ indicates additional items within the boxes that +aren’t displayed.) +]], + showboxbreadth = [[ +This parameter specifies the maximum number of list items that +TeX displays for one level of one box when it is producing the output +for `\showbox` or `\tracingoutput`. Plain TeX sets `\showboxbreadth` to +5. +]], + showboxdepth = [[ +This parameter specifies the level of the deepest list that TeX displays +when it is producing the output for `\showbox` or `\showlists`. Plain +TeX sets `\showboxdepth` is 3. +]], + skew = [[ +This command shifts the accent `argument_1` by `number` mathematical +units to the right of its normal position with respect to `argument_2`. +The most common use of this command is for modifying the position of an +accent that’s over another accent. +]], + skewchar = [[ +The `\skewchar` of a font is the character in the font whose kerns, as +defined in the font’s metrics file, determine the positions of math +accents. That is, suppose that TeX is applying a math accent to the +character ‘`x`’. TeX checks if the character pair ‘`x\skewchar`’ has a +kern; if so, it moves the accent by the amount of that kern. The +complete algorithm that TeX uses to position math accents (which +involves many more things) is in Appendix G of *The TeXbook*. + +If the value of `\skewchar` is not in the range 0–255, TeX takes the +kern value to be zero. + +Note that `font` is a control sequence that names a font, not a +`fontname` that names font files. Beware: an assignment to `\skewchar` +is *not* undone at the end of a group. If you want to change `\skewchar` +locally, you’ll need to save and restore its original value explicitly. +]], + slash = [[ +This command produces a solidus (/) and also tells TeX that it can break +the line after the solidus, if necessary. +]], + smallbreak = [[ +`\bigbreak`, `\medbreak`, `\smallbreak` + +These commands indicate increasingly desirable places for TeX to break a +page. They also cause TeX to insert a `\smallskip`, `\medskip`, or +`\bigskip` if the page break doesn’t actually happen. TeX suppresses +this skip if it occurs just after an equal or larger skip. +]], + smallskip = [[ +`\bigskip`, `\medskip`, `\smallskip` + +These commands produce successively larger amounts of vertical space: + +`\smallskip` skips by 3 points and can stretch or shrink by 1 point. +`\medskip` is equivalent to two `\smallskip`s and `\bigskip` is +equivalent to two `\medskip`s. + +These commands end a paragraph since they are inherently vertical. The +skips that they produce are in addition to the normal interparagraph +skip. +]], + smallskipamount = [[ +`\bigskipamount`, `\medskipamount`, `\smallskipamount` + +These parameters specify the amounts of glue produced by the +`\smallskip`, `\medskip`, and `\bigskip` commands. By changing these +parameters you change the effect of the commands. The default values +(for plain TeX) correspond to a quarter of a linespace, half a +linespace, and a full linespace. We recommend that you maintain this +ratio by changing these values whenever you change `\baselineskip`. +]], + smash = [[ +This command typesets `argument`, but forces the height and depth of its +containing box to be zero. You can use `\smash` and `\vphantom` in +combination to give a subformula any height and depth that you wish. +]], + space = [[ +This command is equivalent to an input space character. It differs from +`\ ` in that its width *can* be affected by preceding punctuation. +]], + spacefactor = [[ +`\sfcode`, `\spacefactor`, `\spaceskip`, `\xspaceskip` + +These primitive parameters affect how much space TeX puts between two +adjacent words, i.e., the interword spacing. The normal interword +spacing is supplied by the current font. As TeX is processing a +horizontal list, it keeps track of the space factor $f$ in +`\spacefactor`. As it processes each input character $c$, it updates $f$ +according to the value of $f_c$, the space factor code of $c$ (see +below). For most characters, $f_c$ is 1000 and TeX sets $f$ to 1000. +(The initial value of $f$ is also 1000.) When TeX sees an interword +space, it adjusts the size of that space by multiplying the stretch and +shrink of that space by $f/1000$ and $1000/f$ respectively. Thus: + +1. If $f=1000$, the interword space keeps its normal value. + +2. If $f<1000$, the interword space gets less stretch and more shrink. + +3. If $f>1000$, the interword space gets more stretch and less shrink. + +In addition, if $f\ge2000$ the interword space is further increased by +the “extra space” parameter associated with the current font. + +Each input character $c$ has an entry in the `\sfcode` (space factor +code) table. The `\sfcode` table entry is independent of the font. +Usually TeX just sets $f$ to $f_c$ after it processes $c$. However: + +- If $f_c$ is zero, TeX leaves $f$ unchanged. Thus a character such as + ‘`)`’ in plain TeX, for which $f_c$ is zero, is essentially + transparent to the interword space calculation. + +- If $f<1000}}, + mark=at position -1cm with {\arrowreversed[black]{stealth}}} + ] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} + +Here is a more useful example: + + \begin{tikzpicture}[decoration={ + markings,% switch on markings + mark=between positions 0 and .75 step 4mm with {\arrow{stealth}}, + mark=between positions .75 and 1 step 4mm with {\arrowreversed{stealth}}} + ] + \draw [help lines] grid (3,2); + \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/arrow" + }, + arrowreversed = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + {meta = "arrow end tip"} + }, + details = [[ +As above, only the arrow end tip is flipped and points in the other +direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/arrowreversed" + }, + attribute = { + arguments = { + {meta = "attribute name"}, + {literal = "="}, + {meta = "initial value"}, + {literal = ";"} + }, + details = [[ +This command can only be given inside the body of an `\pgfooclass` +command. It declares the attribute named ⟨attribute name⟩. This name, +like method or class names, can be quite arbitrary, but should not +contain periods. Valid names are `an_ attribute?` or `my attribute`. + +You can optionally specify an ⟨initial value⟩ for the attribute; if none +is given, the empty string is used automatically. The initial value is +the value that the attribute will have just after the object has been +created and before the constructor is called. + + \pgfooclass{stamp}{ + % This is the class stamp + + \attribute text; + \attribute rotation angle = 20; + + \method stamp(#1) { + \pgfooset{text}{#1} % Set the text + } + + \method apply(#1,#2) { + \pgfoothis.shift origin(#1,#2) + + % Draw the stamp: + \node [rotate=\pgfoovalueof{rotation angle},font=\huge] + {\pgfoovalueof{text}}; + } + + \method shift origin(#1,#2) { ... } + + \method set rotation (#1) { + \pgfooset{rotation angle}{#1} + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/attribute" + }, + backgroundpath = { + arguments = {{meta = "code"}}, + details = [[ +This command specifies the path that "makes up" the background of the +shape. Note that the shape cannot prescribe what is going to happen with +the path: It might be drawn, shaded, filled, or even thrown away. If you +want to specify that something should "always" happen when this shape is +drawn (for example, if the shape is a stop-sign, we *always* want it to +be filled with a red color), you can use commands like +`\beforebackgroundpath`, explained below. + +When the ⟨code⟩ is executed, all saved anchors will be in effect. The +⟨code⟩ should contain path construction commands. + +For our `simple rectangle`, the following code might be used: + + \backgroundpath{ + \pgfpathrectanglecorners + {\upperrightcorner} + {\pgfpointscale{-1}{\upperrightcorner}} + } + +As the name suggests, the background path is used "behind" the text +labels. Thus, this path is used first, then the text labels are drawn, +possibly obscuring part of the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/backgroundpath" + }, + beforebackgroundpath = { + arguments = {{meta = "code"}}, + details = [[ +This command works like `\behindbackgroundpath`, only the ⟨code⟩ is +executed after the background path has been used, but before the texts +label are drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/beforebackgroundpath" + }, + beforedecoration = { + arguments = {{meta = "before code"}}, + details = [[ +Defines ⟨before code⟩ as (typically) PGF 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 such +as segment length, or segment amplitude, then they can be set in ⟨before +code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/beforedecoration" + }, + beforeforegroundpath = { + arguments = {{meta = "code"}}, + details = [[ +This ⟨code⟩ is executed at the very end. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/beforeforegroundpath" + }, + behindbackgroundpath = { + arguments = {{meta = "code"}}, + details = [[ +Unlike the previous two commands, ⟨code⟩ should not only construct a +path, it should also use this path in whatever way is appropriate. For +example, the ⟨code⟩ might fill some area with a uniform color. + +Whatever the ⟨code⟩ does, it does it first. This means that any drawing +done by ⟨code⟩ will be even behind the background path. + +Note that the ⟨code⟩ is protected with a `{pgfscope}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/behindbackgroundpath" + }, + behindforegroundpath = { + arguments = {{meta = "code"}}, + details = [[ +The ⟨code⟩ is executed after the text labels have been drawn, but before +the foreground path is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/behindforegroundpath" + }, + breakforeach = { + details = [[ +If this command is given inside a `\foreach` command, no further +executions of the ⟨commands⟩ will occur. However, the current execution +of the ⟨commands⟩ is continued normally, so it is probably best to use +this command only at the end of a `\foreach` command. + + \begin{tikzpicture} + \foreach \x in {1,...,4} + \foreach \y in {1,...,4} + { + \fill[red!50] (\x,\y) ellipse (3pt and 6pt); + + \ifnum \x<\y + \breakforeach + \fi + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/breakforeach" + }, + calendar = { + arguments = {{meta = "calendar specification"}, {literal = ";"}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/calendar" + }, + chainin = { + arguments = { + {delimiters = {"(", ")"}, meta = "existing name"}, + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + } + }, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/chainin" + }, + clip = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This option causes all subsequent drawings to be clipped against the +current path and the size of subsequent paths will not be important for +the picture size. If you clip against a self-intersecting path, the +even-odd rule or the nonzero winding number rule is used to determine +whether a point is inside or outside the clipping region. + +The clipping path is a graphic state parameter, so it will be reset at +the end of the current scope. Multiple clippings accumulate, that is, +clipping is always done against the intersection of all clipping areas +that have been specified inside the current scopes. The only way of +enlarging the clipping area is to end a `{scope}`. + + \begin{tikzpicture} + \draw[clip] (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); + \end{tikzpicture} + +It is usually a *very* good idea to apply the `clip` option only to the +first path command in a scope. + +If you "only wish to clip" and do not wish to draw anything, you can use +the `\clip` command, which is a shorthand for `\path[clip]`. + + \begin{tikzpicture} + \clip (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); + \end{tikzpicture} + +To keep clipping local, use `{scope}` environments as in the following +example: + + \begin{tikzpicture} + \draw (0,0) -- ( 0:1cm); + \draw (0,0) -- (10:1cm); + \draw (0,0) -- (20:1cm); + \draw (0,0) -- (30:1cm); + \begin{scope}[fill=red] + \fill[clip] (0.2,0.2) rectangle (0.5,0.5); + + \draw (0,0) -- (40:1cm); + \draw (0,0) -- (50:1cm); + \draw (0,0) -- (60:1cm); + \end{scope} + \draw (0,0) -- (70:1cm); + \draw (0,0) -- (80:1cm); + \draw (0,0) -- (90:1cm); + \end{tikzpicture} + +There is a slightly annoying catch: You cannot specify certain graphic +options for the command used for clipping. For example, in the above +code we could not have moved the `fill=red` to the `\fill` command. The +reasons for this have to do with the internals of the PDF specification. +You do not want to know the details. It is best simply not to specify +any options for these commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/clip", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path[clip]`." + }, + colorcurrentmixin = { + details = [[ +Expands to the current accumulated mix-in. Each nesting of a +`colormixin` adds a mix-in to this list. + + \begin{minipage}{\linewidth-6pt}\raggedright + \begin{colormixin}{75!white} + \colorcurrentmixin\ should be ``!75!white''\par + \begin{colormixin}{75!black} + \colorcurrentmixin\ should be ``!75!black!75!white''\par + \begin{colormixin}{50!white} + \colorcurrentmixin\ should be ``!50!white!75!black!75!white''\par + \end{colormixin} + \end{colormixin} + \end{colormixin} + \end{minipage} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/colorcurrentmixin" + }, + coordinate = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for `\path coordinate`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/coordinate" + }, + datavisualization = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This command is available only inside a `{tikzpicture}` environment. + +The ⟨data visualization options⟩ are used to configure the data +visualization, that is, how the data is to be depicted. The options are +executed with the path prefix `/tikz/data visualization`. This means +that normal TikZ options like `thin` or `red` cannot be used here. +Rather, a large number of options specific to data visualizations are +available. + +As a minimum, you should specify at least two options: First, you should +use an option that selects an axis system that is appropriate for your +plot. Typical possible keys are `school book axes` or `scientific axes`, +detailed information on them can be found in Section ??. + +Second, you use an option to select *how* the data should be visualized. +This is done using a key like `visualize as line` which will, as the +name suggests, visualize the data by connecting data points in the plane +using a line. Similarly, `visualize as smooth cycle` will try to fit a +smooth cycle through the data points. Detailed information on possible +visualizers can be found in Section ??. + +Following these options, the ⟨data specification⟩ is used to provide the +actual to-be-visualized data. The syntax is somewhat similar to commands +like `\path`: The ⟨data specification⟩ is a sequence of keywords +followed by local options and parameters, terminated with a semicolon. +(Indeed, like for the `\path` command, the ⟨data visualizers options⟩ +need not be specified at the beginning, but additional option surrounded +by square brackets may be given anywhere inside the ⟨data +specification⟩.) + +The different possible keywords inside the ⟨data specification⟩ are +explained in the following. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/datavisualization" + }, + decoration = { + arguments = {{meta = "name"}}, + details = [[ +This sets the decoration for the current state to ⟨name⟩. If this +command is omitted, the `moveto` decoration will be used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/decoration" + }, + deferredanchor = { + arguments = {{meta = "name"}, {meta = "code"}}, + details = [[ +This command declares an anchor named ⟨name⟩. It works like `\anchor`. +However, unlike for anchors declared by `\anchor`, ⟨name⟩ will *not* be +expanded during the shape declaration (i.e. not during +`\pgfdeclareshape`). Rather, the ⟨name⟩ is expanded when the *node* is +actually used (with `\pgfnode` or more likely with `\node`). This may be +useful if the anchor name is context dependent (depending, for example, +on the value of a key). + + \makeatletter + \def\foo{foo} + \pgfdeclareshape{simple shape}{% + \savedanchor{\center}{% + \pgfpointorigin} + \anchor{center}{\center} + \savedanchor{\anchorfoo}{% + \pgf@x=1cm + \pgf@y=0cm} + \deferredanchor{anchor \foo}{\anchorfoo}} + + \begin{tikzpicture} + \node[simple shape] (Test1) at (0,0) {}; + \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor}; + % + \def\foo{bar} + \node[simple shape] (Test2) at (2,2) {}; + \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/deferredanchor" + }, + draw = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Causes the path to be drawn. "Drawing" (also known as "stroking") can be +thought of as picking up a pen and moving it along the path, thereby +leaving "ink" on the canvas. + +There are numerous parameters that influence how a line is drawn, like +the thickness or the dash pattern. These options are explained below. + +If the optional ⟨color⟩ argument is given, drawing is done using the +given ⟨color⟩. This color can be different from the current filling +color, which allows you to draw and fill a path with different colors. +If no ⟨color⟩ argument is given, the last usage of the `color=` option +is used. + +If the special color name `none` is given, this option causes drawing to +be "switched off". This is useful if a style has previously switched on +drawing and you locally wish to undo this effect. + +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 *not* cause all paths +to be drawn. Instead, this just sets the ⟨color⟩ to be used for drawing +paths inside the environment. + + \begin{tikzpicture} + \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/draw", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path[draw]`." + }, + fill = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This option causes the path to be filled. All unclosed parts of the path +are first closed, if necessary. Then, the area enclosed by the path is +filled with the current filling color, which is either the last color +set using the general `color=` option or the optional color ⟨color⟩. For +self-intersection paths and for paths consisting of several closed +areas, the "enclosed area" is somewhat complicated to define and two +different definitions exist, namely the nonzero winding number rule and +the even odd rule, see the explanation of these options, below. + +Just as for the `draw` option, setting ⟨color⟩ to `none` disables +filling locally. + + \begin{tikzpicture} + \fill (0,0) -- (1,1) -- (2,1); + \fill (4,0) circle (.5cm) (4.5,0) circle (.5cm); + \fill[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm); + \fill (8,0) -- (9,1) -- (10,0) circle (.5cm); + \end{tikzpicture} + +If the `fill` option is used together with the `draw` option (either +because both are given as options or because a `\filldraw` command is +used), the path is filled *first*, then the path is drawn *second*. This +is especially useful if different colors are selected for drawing and +for filling. Even if the same color is used, there is a difference +between this command and a plain `fill`: A "filldrawn" area will be +slightly larger than a filled area because of the thickness of the +"pen". + + \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); + \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/fill", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path[fill]`." + }, + filldraw = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for `\path[fill,draw]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/filldraw" + }, + foreach = { + arguments = {{literal = " "}, {meta = "variables"}, {literal = " "}}, + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/foreach" + }, + foregroundpath = { + arguments = {{meta = "code"}}, + details = [[ +This command works like `\backgroundpath`, only it is invoked after the +text labels have been drawn. This means that this path can possibly +obscure (part of) the text labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/foregroundpath" + }, + graph = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside a `{tikzpicture}` this is an abbreviation for `\path graph`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/graph" + }, + ifdate = { + arguments = {{meta = "tests"}, {meta = "code"}, {meta = "else code"}}, + details = [[ +\[ifdate\] This command has the same effect as calling +`\pgfcalendarifdate` for the current date. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/ifdate" + }, + inheritanchor = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"}, + {meta = "name"} + }, + details = [[ +Inherits the code of one specific anchor named ⟨name⟩ from ⟨another +shape name⟩. Thus, unlike saved anchors, which must be inherited +collectively, normal anchors can and must be inherited individually. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritanchor" + }, + inheritanchorborder = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the border anchor code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritanchorborder" + }, + inheritbackgroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the background path code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritbackgroundpath" + }, + inheritbeforebackgroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the before background path code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritbeforebackgroundpath" + }, + inheritbeforeforegroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the before foreground path code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritbeforeforegroundpath" + }, + inheritbehindbackgroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +This command can be used to inherit the code used for the drawings +behind the background path from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritbehindbackgroundpath" + }, + inheritbehindforegroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the behind foreground path code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritbehindforegroundpath" + }, + inheritforegroundpath = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +Inherits the foreground path code from ⟨another shape name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritforegroundpath" + }, + inheritsavedanchors = { + arguments = { + {literal = "[from="}, + {meta = "another shape name"}, + {literal = "]"} + }, + details = [[ +This command allows you to inherit the code for saved anchors from +⟨another shape name⟩. The idea is that if you wish to create a new shape +that is just a small modification of a another shape, you can recycle +the code used for ⟨another shape name⟩. + +The effect of this command is the same as if you had called +`\savedanchor` and `\saveddimen` for each saved anchor or saved +dimension declared in ⟨another shape name⟩. Thus, it is not possible to +"selectively" inherit only some saved anchors, you always have to +inherit all saved anchors from another shape. However, you can inherit +the saved anchors of more than one shape by calling this command several +times. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/inheritsavedanchors" + }, + jobname = { + details = [[ +The value of `\jobname` is one of `\tikzexternalrealjob` or +`\pgfactualjobname`, depending on the configuration. In short: if +auxiliary file support (`\label` and `\ref`) is activated, +`\jobname=\tikzexternalrealjob` (since that's the base file name of +auxiliary files). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/jobname" + }, + matrix = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This option can be passed to a `node` path command. It signals that the +node will contain a matrix. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,2); + \node [matrix,fill=red!20,draw=blue,very thick] (my matrix) at (2,1) + { + \draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\ + \draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\ + }; + + \draw [very thick,->] (0,0) |- (my matrix.west); + \end{tikzpicture} + +The exact syntax of the matrix is explained in the course of this +section. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/matrix", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path node[matrix]`." + }, + method = { + arguments = { + {meta = "method name"}, + {delimiters = {"(", ")"}, meta = "parameter list"}, + {meta = "method body"} + }, + details = [[ +This macro, which is only defined inside a class definition, defines a +new method named ⟨method name⟩. Just like class names, method names can +contain spaces and other characters, so ⟨method names⟩ like +`put_ stamp_ here` or `put stamp here` are both legal. + +Three method names are special: First, a method having either the same +name as the class or having the name `init` is called the *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 ??. + +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 ⟨method name⟩ must be followed by a ⟨parameter list⟩ in parentheses, +which must be present even when the ⟨parameter list⟩ is empty. The +⟨parameter list⟩ is actually a normal TeX parameter list that will be +matched against the parameters inside the parentheses upon method +invocation and, thus, could be something like `# 1# 2 foo # 3 bar.`, but +a list like `# 1,# 2,# 3` is more customary. By setting the parameter +list to just `# 1` and then calling, say, `\pgfkeys{# 1}` at the +beginning of a method, you can implement Objective-C-like named +parameters. + +When a method is called, the ⟨body⟩ of the method will be executed. The +main difference to a normal macro is that while the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/method" + }, + n = { + arguments = {{meta = "number register"}}, + details = [[ +When this macro is used on the left-hand side of an `=`-sign in a let +operation, it has no effect and is just there for readability. When the +macro is used on the right-hand side of an `=`-sign or in the body of +the let operation, then it expands to the value stored in the ⟨number +register⟩. This will either be a dimensionless number like `2.0` or a +dimension like `5.6pt`. + +For instance, if we say `let \n1={1pt+2pt}, \n2={1+2} in ...`, then +inside the `...` part the macro `\n1` will expand to `3pt` and `\n2` +expands to `3`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/n" + }, + node = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for `\path node`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/node" + }, + nodepart = { + arguments = { + {literal = "["}, + {keys = "$ref:tikz#/keys/tikz", meta = "options"}, + {literal = "]"}, + {meta = "part name"} + }, + details = [[ +This command can only be used inside the ⟨text⟩ argument of a `node` +path operation. It works a little bit like a `\part` command in LaTeX. +It will stop the typesetting of whatever node part was typeset until now +and then start putting all following text into the node part named ⟨part +name⟩ -- until another `\partname` is encountered or until the node +⟨text⟩ ends. The ⟨options⟩ will be local to this part. + + \begin{tikzpicture} + \node [circle split,draw,double,fill=red!20] + { + % No \nodepart has been used, yet. So, the following is put in the + % ``text'' node part by default. + $q_1$ + \nodepart{lower} % Ok, end ``text'' part, start ``output'' part + $00$ + }; % output part ended. + \end{tikzpicture} + +You will have to lookup which parts are defined by a shape. + +The following styles influences node parts: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/nodepart" + }, + nodeparts = { + arguments = {{meta = "list of node parts"}}, + details = [[ +This command declares which parts make up nodes of this shape. A *node +part* is a (possibly empty) text label that is drawn when a node of the +shape is created. + +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 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 ⟨list of node parts⟩. For each node 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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/nodeparts" + }, + p = { + arguments = {{meta = "point register"}}, + details = [[ +When this macro is used on the left-hand side of an `=`-sign in a let +operation, it has no effect and is just there for readability. When the +macro is used on the right-hand side of an `=`-sign or in the body of +the let operation, then it expands to the $x$-part (measured in +TeX points) of the coordinate stored in the ⟨register⟩, followed, by a +comma, followed by the $y$-part. + +For instance, if we say `let \p1=(1pt,1pt+2pt) in ...`, then inside the +`...` part the macro `\p1` will expand to exactly the seven characters +"1pt,3pt". This means that you when you write `(\p1)`, this expands to +`(1pt,3pt)`, which is presumably exactly what you intended. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/p" + }, + path = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This command is available only inside a `{tikzpicture}` environment. + +The ⟨specification⟩ is a long stream of *path operations*. Most of these +path operations tell TikZ how the path is built. For example, when you +write `–(0,0)`, you use a *line-to operation* and it means "continue the +path from wherever you are to the origin". + +At any point where TikZ expects a path operation, you can also give some +graphic options, which is a list of options in brackets, such as +`[rounded corners]`. These options can have different effects: + +1. Some options take "immediate" effect and apply to all subsequent + path operations on the path. For example, the `rounded corners` + option will round all following corners, but not the corners + "before" and if the `sharp corners` is given later on the path (in a + new set of brackets), the rounding effect will end. + + \tikz \draw (0,0) -- (1,1) + [rounded corners] -- (2,0) -- (3,1) + [sharp corners] -- (3,0) -- (2,1); + + Another example are the transformation options, which also apply + only to subsequent coordinates. + +2. The options that have immediate effect can be "scoped" by putting + part of a path in curly braces. For example, the above example could + also be written as follows: + + \tikz \draw (0,0) -- (1,1) + {[rounded corners] -- (2,0) -- (3,1)} + -- (3,0) -- (2,1); + +3. Some options only apply to the path as a whole. For example, the + `color=` option for determining the color used for, say, drawing the + path always applies to all parts of the path. If several different + colors are given for different parts of the path, only the last one + (on the outermost scope) "wins": + + \tikz \draw (0,0) -- (1,1) + [color=red] -- (2,0) -- (3,1) + [color=blue] -- (3,0) -- (2,1); + + Most options are of this type. In the above example, we would have + had to "split up" the path into several `\path` commands: + + \tikz{\draw (0,0) -- (1,1); + \draw [color=red] (1,1) -- (2,0) -- (3,1); + \draw [color=blue] (3,1) -- (3,0) -- (2,1);} + +By default, the `\path` command does "nothing" with the path, it just +"throws it away". Thus, if you write `\path(0,0)–(1,1);`, nothing is +drawn in your picture. The only effect is that the area occupied by the +picture is (possibly) enlarged so that the path fits inside the area. To +actually "do" something with the path, an option like `draw` or `fill` +must be given somewhere on the path. Commands like `\draw` do this +implicitly. + +Finally, it is also possible to give *node specifications* on a path. +Such specifications can come at different locations, but they are always +allowed when a normal path operation could follow. A node specification +starts with `node`. Basically, the effect is to typeset the node's text +as normal TeX text and to place it at the "current location" on the +path. The details are explained in Section ??. + +Note, however, that the nodes are *not* part of the path in any way. +Rather, after everything has been done with the path what is specified +by the path options (like filling and drawing the path due to a `fill` +and a `draw` option somewhere in the ⟨specification⟩), the nodes are +added in a post-processing step. + +*Note:* When scanning for path operations TikZ expands tokens looking +for valid path operations. This however implies that these tokens has to +be fully expandable up to the point where it results in a valid path +operation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/path" + }, + pattern = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +This option causes the path to be filled with a pattern. If the ⟨name⟩ +is given, this pattern is used, otherwise the pattern set in the +enclosing scope is used. As for the `draw` and `fill` options, setting +⟨name⟩ to `none` disables filling locally. + +The pattern works like a fill color. In particular, setting a new fill +color will fill the path with a solid color once more. + +Strangely, no ⟨name⟩s are permissible by default. You need to load for +instance the `patterns` library, see Section ??, to install predefined +patterns. + + \begin{tikzpicture} + \draw[pattern=dots] (0,0) circle (1cm); + \draw[pattern=fivepointed stars] (0,0) rectangle (3,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pattern", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path[pattern]`." + }, + pic = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for `\path pic`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/pic" + }, + rule = { + arguments = {{literal = "{"}, {meta = "head"}}, + details = [[ +Declare a rule. ⟨head⟩ should consist of a single symbol, which 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). ⟨body⟩ +consists of a string of symbols, which again need not necessarily have +any code associated with them. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/rule" + }, + savedanchor = { + arguments = {{meta = "command"}, {meta = "code"}}, + details = [[ +This command declares a saved anchor. The argument ⟨command⟩ should be a +TeX macro name like `\centerpoint`. + +The ⟨code⟩ will be executed each time `\pgfnode` (or +`\pgfmultipartnode`) is called to create a node of the shape ⟨shape +name⟩. When the ⟨code⟩ 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 set up when the ⟨code⟩ is executed. + +The ⟨code⟩ can use the width, height, and depth of the box(es) to +compute the location of the saved anchor. In addition, the ⟨code⟩ can +take into account the values of dimensions like `\pgfshapeminwidth` or +`\pgfshapeinnerxsep`. Furthermore, the ⟨code⟩ can take into +consideration the values of any further shape-specific variables that +are set at the moment when `\pgfnode` is called. + +The net effect of the ⟨code⟩ should be to set the two TeX dimensions +`\pgf@x` and `\pgf@y`. One way to achieve this is to say `\pgfpoint{`⟨x +value⟩`}{`⟨y value⟩`}` at the end of the ⟨code⟩, but you can also just +set these variables. The values that `\pgf@x` and `\pgf@y` have after +the code has been executed, let us call them $x$ and $y$, will be +recorded and stored together with the node that is created by the +command `\pgfnode`. + +The macro ⟨command⟩ is defined to be `\pgfpoint{`$x$`}{`$y$`}`. However, +the ⟨command⟩ is only locally defined while anchor positions are being +computed. Thus, it is possible to use very simple names for ⟨command⟩, +like `\center` or `\a`, without causing a name-clash. (To be precise, +very simple ⟨command⟩ names will clash with existing names, but only +locally inside the computation of anchor positions; and we do not need +the normal `\center` command during these computations.) + +For our `simple rectangle` shape, we will need only one saved anchor: +The upper right corner. The lower left corner could either be the origin +or the "mirrored" upper right corner, depending on whether we want the +text label to have its lower left corner at the origin or whether the +text label should be centered on the origin. Either will be fine, for +the final shape this will make no difference since the shape will be +shifted anyway. So, let us assume that the text label is centered on the +origin (this will be specified later on using the `text` anchor). We get +the following code for the upper right corner: + + \savedanchor{\upperrightcorner}{ + \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth + \pgf@x=.5\wd\pgfnodeparttextbox % width of the box + } + +If we wanted to take, say, the `\pgfshapeminwidth` into account, we +could use the following code: + + \savedanchor{\upperrightcorner}{ + \pgf@y=.\ht\pgfnodeparttextbox % height of the box + \pgf@x=.\wd\pgfnodeparttextbox % width of the box + \setlength{\pgf@xa}{\pgfshapeminwidth} + \ifdim\pgf@x<.5\pgf@xa + \pgf@x=.5\pgf@xa + \fi + } + +Note that we could not have written `.5\pgfshapeminwidth` since the +minimum width is stored in a "plain text macro", not as a real +dimension. So if `\pgfshapeminwidth` depth were 2cm, writing +`.5\pgfshapeminwidth` would yield the same as `.52cm`. + +In the "real" `rectangle` shape the code is somewhat more complex, but +you get the basic idea. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/savedanchor" + }, + saveddimen = { + arguments = {{meta = "command"}, {meta = "code"}}, + details = [[ +This command is similar to `\savedanchor`, only instead of setting +⟨command⟩ to `\pgfpoint{`$x$`}{`$y$`}`, the ⟨command⟩ is set just to +(the value of) $x$. + +In the `simple rectangle` shape we might use a saved dimension to store +the depth of the shape box. + + \saveddimen{\depth}{ + \pgf@x=\dp\pgfnodeparttextbox + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/saveddimen" + }, + savedmacro = { + arguments = {{meta = "command"}, {meta = "code"}}, + details = [[ +This command is similar to `\saveddimen`, only at some point in ⟨code⟩, +⟨command⟩ should be defined appropriately, (this could be a value, or +some text). + +In the `regular polygon` shape, a saved macro is used to store the +number of sides of the polygon. + + \savedmacro{\sides}{\let\sides\pgfpolygonsides} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/savedmacro" + }, + scoped = { + arguments = { + {meta = "animations spec"}, + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + {meta = "path command"} + }, + details = [[ +This command works like `\tikz`, only you can use it inside a +`{tikzpicture}`. It will take the following ⟨path command⟩ and put it +inside a `{scope}` with the ⟨options⟩ set. The ⟨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{tikzpicture} + \node [fill=white] at (1,1) {Hello world}; + \scoped [on background layer] + \draw (0,0) grid (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/scoped" + }, + shade = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Causes the path to be shaded using the currently selected shading (more +on this later). If this option is used together with the `draw` option, +then the path is first shaded, then drawn. + +It is not an error to use this option together with the `fill` option, +but it makes no sense. + + \tikz \shade (0,0) circle (1ex); + + \tikz \shadedraw (0,0) circle (1ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/shade", + summary = "Inside `{tikzpicture}` this is an abbreviation for `\\path[shade]`." + }, + shadedraw = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for `\path[shade,draw]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/shadedraw" + }, + spy = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + {literal = "on"}, + {meta = "coordinate"} + }, + details = [[ +This command can only be used inside a `spy scope`. Let us start with +the syntax: + +- The `\spy` command is not a special case of `\path`. Rather, it has + a small parser of its own. + +- Following the optional ⟨options⟩, you must write `on`, followed by a + coordinate. This coordinate will be the center of the area that is + to be magnified. + +- Following the ⟨coordinate⟩, you must write `in node` followed by + some ⟨node options⟩. The syntax for these options is the same as for + a normal `node` path command, such as `[left]` or + `(foo) [red] at (bar)`. *However*, ⟨node options⟩ are *not* followed + by a curly brace. Rather, the ⟨node options⟩ must directly be + followed by a semicolon. + +The effect of this command is the following: The ⟨options⟩, +⟨coordinate⟩, and ⟨node options⟩ are stored internally till the end of +the current `spy scope`. This means that, in particular, you can +reference any node inside the `spy scope`, even if it is not yet defined +when the `\spy` command is given. At the end of the current `spy scope`, +two nodes are created, called the *spy-in node* and the *spy-on node*. + +- The *spy-in node* is the node that contains a magnified part of the + picture (the node *in* which we see on what we spy). This node is, + indeed, a normal TikZ node, so you can use all standard options to + style this node. In particular, you can specify a shape or a border + color or a drop shadow or whatever. The only thing that is special + about this node is that instead of containing some normal text, its + "text" is the magnified picture. + + 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 is shifted in such a way that the ⟨coordinate⟩ lies at + the center of the spy-on node. + +- The *spy-on node* is a node that is centered on the ⟨coordinate⟩ and + whose size reflects exactly the area shown inside the spy-in node + (the node containing *on* what we spy). + +Let us now go over what happens in detail when the two nodes are +created: + +1. A scope is started. Two sets of options are used with this scope: + First, the options passed to the enclosing `spy scope` and then the + ⟨options⟩ (which will, thus, overrule the options of the + `spy scope`). + +2. Then, the spy-on node is created. However, we will first discuss the + spy-in node. + +3. The spy-in node is created after the spy-on node (and, hence, will + cover the spy-on node in case they overlap). When this node is + created, the ⟨node options⟩ are used in addition to the effect + caused by the ⟨options⟩ and the options of the `{spy scope}`. + Additionally, the following style is used: + + The position of the node (the `at` option) is set to the + ⟨coordinate⟩ by default, so that it will cover the to-be-magnified + area. You can change this by providing the `at` option yourself: + + \begin{tikzpicture} + [spy using outlines={circle, magnification=3, size=1cm}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node; + \spy [blue] on (1,1) in node at (1,-1); + \end{tikzpicture} + + No "text" can be specified for the node. Rather, the "text" shown + inside this node is the picture of the current `spy scope`, but + canvas-transformed according to the following key: + + Since the most common transformation is undoubtedly a simple + scaling, there is a special style for this: + + Now, usually the size of a node is determined in such a way that it + "fits" around the text of the node. For a spy-on node this is not a + good approach since the "text" of this node would contain "the whole + picture". Because of this, TikZ acts as if the "text" of the node + has zero size. You must then use keys like `minimum size` to cause + the node to have a certain 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 + node is (also) always named `tikzspyinnode`. Following the spy + scope, you can use this node like any other node: + + \begin{tikzpicture} + \begin{scope} + [spy using outlines={circle, magnification=3, size=2cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node (a) [left] at (3.5,-1.25); + + \spy [blue, size=1cm] on (1,1) in node (b) [right] at (0,-1.25); + \end{scope} + \draw [ultra thick, green!50!black] (b) -- (a.north west); + \end{tikzpicture} + +4. Once both nodes have been created, the current value of the + following key is used to connect them: + +Returning to the creation of the spy-in node: This node is centered on +⟨coordinate⟩ (more precisely, its anchor is set to `center` and the `at` +option is set to ⟨coordinate⟩). Its size and shape are initially +determined in the same way as the size and shape of the spy-on node +(unless, of course, you explicitly provide a different shape for, say, +the spy-on node locally, which is not really a good idea). Then, +additionally, the *inverted* transformation done by the `lens` option is +applied, resulting in a node whose size and shape exactly corresponds to +the area in the picture that is shown in the spy-on node. + + \begin{tikzpicture} + [spy using outlines={lens={scale=3,rotate=20}, size=2cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node at (2.5,-1.25); + \end{tikzpicture} + +Like for the spy-in node, a style can be used to format the spy-on node: + +The spy-on node is named `tikzspyonnode` (but, as always, this node is +only available after the spy scope). If you have multiple spy-on nodes +and you would like to access all of them, you need to use the `name` key +inside the `every spy on node` style. + +The `inner sep` and `outer sep` of both spy-in and spy-on nodes are set +to `0pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/spy" + }, + state = { + arguments = { + {meta = "name"}, + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + {meta = "code"} + }, + details = [[ +Declares the state ⟨name⟩ inside the current meta-decoration automaton. +Unlike decorations, states in meta-decorations are not executed within a +group, which makes the persistent computation options superfluous. +Consider using an initial state with `width=0pt` to do precalculations +that could speed the execution of the meta-decoration. + +The ⟨options⟩ are executed with the key path set to +`/pgf/meta-decorations automaton/`, and the following keys are defined +for this path: + +The code in ⟨code⟩ is quite different from the code in a decoration +state. In almost all cases only the following three macros will be +required: + +There are some macros that may be useful when creating meta-decorations +(note that they are all macros): +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/state" + }, + symbol = { + arguments = {{meta = "name"}, {meta = "code"}}, + details = [[ +This defines a symbol called ⟨name⟩ for a specific L-system, and +associates it with ⟨code⟩. + +A symbol should consist of a single alpha-numeric character (i.e., +`A`-`Z`, `a`-`z` or `0`-`9`). The symbols `F`, `f`, `+`, `-`, `[` and +`]` are available by default so do not need to be defined for each +L-system. However, if you are feeling adventurous, they can be redefined +for specific L-systems if required. The L-system treats the default +symbols as follows (the commands they execute are described below): + +- `F` move forward a certain distance, drawing a line. Uses + `\pgflsystemdrawforward`. + +- `f` move forward a certain distance, without drawing a line. Uses + `\pgflsystemmoveforward`. + +- `+` turn left by some angle. Uses `\pgflsystemturnleft`. + +- `-` turn right by some angle. Uses `\pgflsystemturnright`. + +- `[` save the current state (i.e., the position and direction). Uses + `\pgflsystemsavestate`. + +- `]` restore the last saved state. Uses `\pgflsystemrestorestate`. + +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 ⟨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, +they do not store values in themselves. + +For speed and convenience, when the code for a symbol is executed, the +following commands are available. + +The following commands may be useful if you wish to define your own +symbols. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/symbol" + }, + tikz = { + arguments = { + {meta = "animations spec"}, + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + }, + {meta = "path commands"} + }, + details = [[ +This command places the ⟨path commands⟩ inside a `{tikzpicture}` +environment. The ⟨path commands⟩ may contain paragraphs and fragile +material (like verbatim text). + +If there is only one path command, it need not be surrounded by curly +braces, if there are several, you need to add them (this is similar to +the `\foreach` statement and also to the rules in programming languages +like Java or C concerning the placement of curly braces). + +`\tikz{\draw (0,0) rectangle (2ex,1ex);}` yields \[PICTURE\] + +`\tikz \draw (0,0) rectangle (2ex,1ex);` yields \[PICTURE\] +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikz" + }, + tikzaliascoordinatesystem = { + arguments = {{meta = "new name"}, {meta = "old name"}}, + details = [[ +Creates an alias of ⟨old name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzaliascoordinatesystem" + }, + tikzappendtofigurename = { + arguments = {{meta = "suffix"}}, + details = [[ +Appends ⟨suffix⟩ to the actual value of `figure name`. + +It is a shortcut for +`\tikzset{external/figure name/.add={}``{suffix}``}` (a shortcut which +is also supported if TikZ is not installed, see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzappendtofigurename" + }, + tikzdeclarecoordinatesystem = { + arguments = {{meta = "name"}, {meta = "code"}}, + details = [[ +This command declares a new coordinate system named ⟨name⟩ that can +later on be used by writing `(`⟨name⟩` cs:`⟨arguments⟩`)`. When +TikZ encounters a coordinate specified in this way, the ⟨arguments⟩ are +passed to ⟨code⟩ as argument `# 1`. + +It is now the job of ⟨code⟩ to make sense of the ⟨arguments⟩. At the end +of ⟨code⟩, the two TeX dimensions `\pgf@x` and `\pgf@y` should be have +the $x$- and $y$-canvas coordinate of the coordinate. + +It is not necessary, but customary, to parse ⟨arguments⟩ using the +key--value syntax. However, you can also parse it in any way you like. + +In the following example, a coordinate system `cylindrical` is defined. + + \makeatletter + \define@key{cylindricalkeys}{angle}{\def\myangle{#1}} + \define@key{cylindricalkeys}{radius}{\def\myradius{#1}} + \define@key{cylindricalkeys}{z}{\def\myz{#1}} + \tikzdeclarecoordinatesystem{cylindrical}% + {% + \setkeys{cylindricalkeys}{#1}% + \pgfpointadd{\pgfpointxyz{0}{0}{\myz}}{\pgfpointpolarxy{\myangle}{\myradius}} + } + \begin{tikzpicture}[z=0.2pt] + \draw [->] (0,0,0) -- (0,0,350); + \foreach \num in {0,10,...,350} + \fill (cylindrical cs:angle=\num,radius=1,z=\num) circle (1pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzdeclarecoordinatesystem" + }, + tikzdeclarepattern = { + arguments = {{meta = "config"}}, + details = [[ +A pattern declared with `\pgfdeclarepattern` can only execute PGF code. +This command extends the functionality to also allow TikZ code. All the +same keys of `\pgfdeclarepattern` are valid, but some of them have been +overloaded to give a more natural TikZ syntax. + +In addition to the overloaded keys, some new keys have been added. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzdeclarepattern" + }, + tikzdvdeclarestylesheetcolorseries = { + arguments = { + {meta = "name"}, + {meta = "color model"}, + {meta = "initial color"}, + {meta = "step"} + }, + details = [[ +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 ⟨initial color⟩ and +having a stepping of ⟨step⟩. Note that when the value of the attribute +is `1`, which it is the first data set, the *second* color in the color +series is used (since counting starts at `0` for color series). Thus, in +general, you need to start the ⟨initial color⟩ "one early". + + 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] + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzdvdeclarestylesheetcolorseries" + }, + tikzexternaldisable = { + details = [[ +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. + +The externalization remains disabled until the end of the next TeX group +(or environment) or until the next call to `\tikzexternalenable`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzexternaldisable" + }, + tikzexternalenable = { + details = [[ +Re-enables a previously running externalization after +`\tikzexternaldisable`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzexternalenable" + }, + tikzexternalfiledependsonfile = { + arguments = {{meta = "external graphics"}, {meta = "file name"}}, + details = [[ +A variant of `\tikzpicturedependsonfile` which adds a dependency for an +⟨external graphics⟩. The argument ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzexternalfiledependsonfile" + }, + tikzexternalize = { + arguments = { + { + delimiters = {"[", "]"}, + meta = "optional arguments", + optional = true + } + }, + details = [[ +This command activates the externalization. It installs commands to +replace every TikZ-picture. It needs to be called before +`\begin{document}` because it may need to install its separate shipout +routine. + +The ⟨optional arguments⟩ can be any of the keys described below. + +Note that the generation/modification of auxiliary files like `.aux`, +`.toc` etc. is usually suppressed while a single image is externalized +(details for `\label` support follow). + +It is also possible to write `\tikzexternalize``{main job name}` if the +argument is delimited by curly braces. This case is mainly for backwards +compatibility and is no longer necessary. Since it might be useful in +rare circumstances, it is documented in section ??. + +A detailed description about the process of externalization is provided +in section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzexternalize" + }, + tikzexternalrealjob = { + details = [[ +After the library is loaded, this macro will *always* contain the +correct main job's name (in the example above, it is `main`). It is to +be used instead of `\jobname` when the externalization is in effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzexternalrealjob" + }, + tikzfading = { + arguments = { + { + delimiters = {"[", "]"}, + keys = "$ref:tikz#/keys/tikz", + meta = "options", + optional = true + } + }, + details = [[ +This command is used to define a fading similarly to the way a shading +is defined. In the ⟨options⟩ you should + +1. use the `name=`⟨name⟩ option to set a name for the fading, + +2. use the `shading` option to set the name of the shading that you + wish to use, + +3. extra options for setting the colors of the shading (typically you + will set them to the color `transparent!`⟨percentage⟩). + +Then, a new fading named ⟨name⟩ will be created based on the shading. + + \tikzfading[name=fade right, + left color=transparent!0, + right color=transparent!100] + + % Now we use the fading in another picture: + \begin{tikzpicture} + % Background + \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2); + \path [pattern=checkerboard,pattern color=black!30] + (-1.2,-1.2) rectangle (1.2,1.2); + + \fill [red,path fading=fade right] (-1,-1) rectangle (1,1); + \end{tikzpicture} + + \tikzfading[name=fade out, + inner color=transparent!0, + outer color=transparent!100] + + % Now we use the fading in another picture: + \begin{tikzpicture} + % Background + \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2); + \path [pattern=checkerboard,pattern color=black!30] + (-1.2,-1.2) rectangle (1.2,1.2); + + \fill [blue,path fading=fade out] (-1,-1) rectangle (1,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzfading" + }, + tikzgraphforeachcolorednode = { + arguments = {{meta = "color name"}, {meta = "macro"}}, + details = [[ +When this command is called inside ⟨code⟩, the following will happen: +TikZ will iterate over all nodes inside the just-specified group that +have the color ⟨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 ⟨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`. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphforeachcolorednode" + }, + tikzgraphnodefullname = { + details = [[ +This macro contains the concatenation of the above two. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphnodefullname" + }, + tikzgraphnodename = { + details = [[ +This macro expands to the name of the current node without the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphnodename" + }, + tikzgraphnodepath = { + details = [[ +This macro expands to the current path of the node. These paths result +from the use of the `name` key as described above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphnodepath" + }, + tikzgraphnodetext = { + details = [[ +This macro expands to the ⟨text⟩ to the right of the double underscore +or slash in a direct node specification or, if there is no slash, to the +⟨node name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphnodetext" + }, + tikzgraphpreparecolor = { + arguments = {{meta = "color name"}, {meta = "counter"}, {meta = "prefix"}}, + details = [[ +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 ⟨color name⟩ in the current group and the result +is stored in ⟨counter⟩. Next, macros named ⟨prefix⟩`1`, ⟨prefix⟩`2`, and +so on are defined, that store the names of the first, second, third, and +so on node having the color ⟨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: + + \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} + +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). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphpreparecolor" + }, + tikzgraphsset = { + arguments = {{keys = "$ref:tikz#/keys/tikz", meta = "options"}}, + details = [[ +Executes the ⟨options⟩ with the path prefix `/tikz/graphs`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzgraphsset" + }, + tikzifexternalizing = { + arguments = {{meta = "true code"}, {meta = "false code"}}, + details = [[ +This command can be used to check whether an image is currently written +to its separate graphics file (if the "grab" procedure is running). If +so, the `{true code}` will be executed. If not, that means if the main +document is being typeset normally, the `{false code}` will be invoked. + +This command must be used *after* `\tikzexternalize`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzifexternalizing" + }, + tikzifexternalizingnext = { + arguments = {{meta = "true code"}, {meta = "false code"}}, + details = [[ +Like `\tikzifexternalizing`, but this variant also checks if the next +following figure is the one which is about to be written to its separate +graphics file. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzifexternalizingnext" + }, + tikzinputsegmentfirst = { + details = [[ +The first point on the current input segment path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzinputsegmentfirst" + }, + tikzinputsegmentlast = { + details = [[ +The last point on the current input segment path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzinputsegmentlast" + }, + tikzinputsegmentsupporta = { + details = [[ +The first support on the curveto input segment path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzinputsegmentsupporta" + }, + tikzinputsegmentsupportb = { + details = [[ +The second support on the curveto input segment path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzinputsegmentsupportb" + }, + tikzlastnode = { + details = [[ +Expands to the last node on the path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzlastnode" + }, + tikzmath = { + details = [[ +This command process a series of ⟨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 *every statement should end with a semi-colon*. This +is likely to be the most common reason why the `\tikzmath` command +fails. + + \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, }; + }; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzmath" + }, + tikzpicturedependsonfile = { + arguments = {{meta = "file name"}}, + details = [[ +Adds a dependency for the *next* picture which is about to be +externalized. If the command is invoked within a picture environment, it +adds a dependency for the surrounding picture. Dependencies are written +into ⟨target file⟩`.dep` in the format + +⟨target file⟩`.\tikzexternalimgextension: `⟨file name⟩. + +The effect is that if ⟨file name⟩ changes, the external graphics +associated with the picture shall be remade. + +This command uses the contents of `\tikzexternalimgextension` to check +for graphics. If you encounter difficulties with image extensions, +consider redefining this macro (after `\tikzexternalize`). + +#### Limitations: + +this command is currently only supported for `mode=list and make` and +the generated `makefile`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzpicturedependsonfile" + }, + tikzrdfhashmark = { + details = [[ +Expands to `# ` with catcode 11. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzrdfhashmark" + }, + tikzset = { + arguments = {{keys = "$ref:tikz#/keys/tikz", meta = "options"}}, + details = [[ +This command will process the ⟨options⟩ using the `\pgfkeys` command, +documented in detail in Section ??, with the default path set to +`/tikz`. Under normal circumstances, the ⟨options⟩ will be lists of +comma-separated pairs of the form ⟨key⟩`=`⟨value⟩, but more fancy things +can happen when you use the power of the `pgfkeys` mechanism, see +Section ?? once more. + +When a pair ⟨key⟩`=`⟨value⟩ is processed, the following happens: + +1. If the ⟨key⟩ is a full key (starts with a slash) it is handled + directly as described in Section ??. + +2. Otherwise (which is usually the case), it is checked whether + `/tikz/`⟨key⟩ is a key and, if so, it is executed. + +3. Otherwise, it is checked whether `/pgf/`⟨key⟩ is a key and, if so, + it is executed. + +4. Otherwise, it is checked whether ⟨key⟩ is a color and, if so, + `color=`⟨key⟩ is executed. + +5. Otherwise, it is checked whether ⟨key⟩ contains a dash and, if so, + `arrows=`⟨key⟩ is executed. + +6. Otherwise, it is checked whether ⟨key⟩ is the name of a shape and, + if so, `shape=`⟨key⟩ is executed. + +7. Otherwise, an error message is printed. + +Note that by the above description, all keys starting with `/tikz` and +also all keys starting with `/pgf` can be used as ⟨key⟩s in an ⟨options⟩ +list. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzset" + }, + tikzsetexternalprefix = { + arguments = {{meta = "file name prefix"}}, + details = [[ +Assigns a common prefix used by all file names. For example, + + \tikzsetexternalprefix{figures/} + +will prepend `figures/` to every external graphics file name. + +Please note that `\tikzsetexternalprefix` is the *only* way to assign a +prefix in case you want to prepare your document for environments where +PGF is not installed (see section ??). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzsetexternalprefix" + }, + tikzsetfigurename = { + arguments = {{meta = "name"}}, + details = [[ +Changes the names of *all* following figures. It is possible to change +`figure name` during the document either using +`\tikzset{external/figure name`=`{name}``}` or with this command. A +unique counter will be used for each different `{name}`, and each +counter will start at $0$. + +The value of `prefix` will be applied after `figure name` has been +evaluated. + + \documentclass{article} + % main document, called main.tex + \usepackage{tikz} + + \usetikzlibrary{external} + \tikzexternalize % activate + + \begin{document} + + \begin{tikzpicture} % will be written to 'main-figure0.pdf' + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; + \end{tikzpicture} + + { + \tikzsetfigurename{subset_} + A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf' + + \begin{tikzpicture} % will be written to 'subset_1.pdf' + \draw[help lines] (0,0) grid (5,5); + \end{tikzpicture} + }% here, the old file name will be restored: + + \begin{tikzpicture} % will be written to 'main-figure1.pdf' + \draw (0,0) -- (5,5); + \end{tikzpicture} + \end{document} + +The scope of `figure name` ends with the next closing brace. + +Remark: Use `\tikzset{external/figure name/.add={prefix_ }{_ suffix_ }}` +to add a `prefix_ ` and a `_ suffix_ ` to the actual value of +`figure name`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzsetfigurename" + }, + tikzsetnextfilename = { + arguments = {{meta = "file name"}}, + details = [[ +Sets the file name for the *next* TikZ picture or `\tikz` short command. +It will *only* be used for the next picture. + +Pictures for which no explicit file name has been set (or the next file +name is empty) will get automatically generated file names. + +Please note that `prefix` will still be prepended to `{file name}`. + + \documentclass{article} + % main document, called main.tex + \usepackage{tikz} + + \usetikzlibrary{external} + \tikzexternalize[prefix=figures/] % activate + + \begin{document} + + \tikzsetnextfilename{trees} + \begin{tikzpicture} % will be written to 'figures/trees.pdf' + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; + \end{tikzpicture} + + \tikzsetnextfilename{simple} + A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/simple.pdf' + + \begin{tikzpicture} % will be written to 'figures/main-figure0.pdf' + \draw[help lines] (0,0) grid (5,5); + \end{tikzpicture} + \end{document} + + pdflatex -shell-escape main +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/tikzsetnextfilename" + }, + useasboundingbox = { + action = "tikzpath", + arguments = {{delimiters = {"", ";"}, meta = "specification"}}, + details = [[ +Inside `{tikzpicture}` this is an abbreviation for +`\path[use as bounding box]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/useasboundingbox" + }, + usegdlibrary = { + arguments = {{meta = "list of libraries"}}, + details = [[ +This command is used to load the special graph drawing libraries (the +`gd` in the name of the command stands for "graph drawing"). The ⟨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 ⟨name⟩ in the ⟨list +of libraries⟩ we do: + +1. Check whether LuaTeX can call `require` on the library file + `pgf.gd.`⟨name⟩`.library`. LuaTeX'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. + +2. If the above failed, try to `require` the string `pgf.gd.`⟨name⟩. + +3. If this fails, try to `require` the string ⟨name⟩`.library`. + +4. If this fails, try to `require` the string ⟨name⟩. If this fails, + print an error message. + +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`. + + \usetikzlibrary{graphdrawing} + \usegdlibrary{trees,force} + +The different graph drawing libraries are documented in the following +Sections ?? to ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usegdlibrary" + }, + usetikzlibrary = { + arguments = {{meta = "list of libraries"}}, + details = [[ +Once TikZ has been loaded, you can use this command to load further +libraries. The list of libraries should contain the names of libraries +separated by commas. Instead of curly braces, you can also use square +brackets, which is something ConTeXt users will like. If you try to load +a library a second time, nothing will happen. + +`\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`⟨library⟩`.code.tex` for each ⟨library⟩ in the ⟨list of +libraries⟩. If this file does not exist, the file +`pgflibrary`⟨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 ConTeXt +users can then use your library. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/usetikzlibrary" + }, + value = { + arguments = {{meta = "variable"}}, + details = [[ +This expands to the current value of the key `/data point/`⟨variable⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/value" + }, + x = { + arguments = {{meta = "point register"}}, + details = [[ +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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/x" + }, + y = { + arguments = {{meta = "point register"}}, + details = [[ +Works like `\x`, only for the $y$-part. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf.back/y" + } +} +keys = { + ["data visualization"] = { + about = { + details = [[ +This key asks the data visualization to place *about* ⟨number⟩ many +ticks on an axis. It is not guaranteed that *exactly* ⟨number⟩ many +ticks will be used, rather the actual number will be the closest number +of ticks to ⟨number⟩ so that their stepping is still "good". For +instance, when you say `about=10`, it may happen that exactly `10`, but +perhaps even `13` ticks are actually selected, provided that these +numbers of ticks lead to good stepping values like `5` or `2.5` rather +than numbers like `3.4` or `7`. The method that is used to determine +which steppings a deemed to be "good" depends on the current tick +placement strategy. + +**Linear steps.** Let us start with `linear steps`: First, the +difference between the maximum value $v_{\max}$ and the minimum value +$v_{\min}$ on the axis is computed; let us call it $r$ for "range". +Then, $r$ is divided by ⟨number⟩, yielding a target stepping $s$. If $s$ +is a number like $1$ or $5$ or $10$, then this number could be used +directly as the new value of `step`. However, $s$ will typically +something strange like $0.023\,45$ or $345\,223.76$, so $s$ must be +replaced by a better value like $0.02$ in the first case and perhaps +$250\,000$ in the second case. + +In order to determine which number is to be used, $s$ is rewritten in +the form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For +instance, $0.023\,45$ would be rewritten as $2.345 \cdot 10^{-2}$ and +$345\,223.76$ as $3.452\,2376 \cdot 10^5$. The next step is to replace +the still not-so-good number $m$ like $2.345$ or $3.452\,237$ by a +"good" value $m'$. For this, the current value of the `about strategy` +is used: + +Once $m'$ has been determined, the stepping is set to +$s' = m' \cdot 10^k$. + +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 `about=5` +(corresponding to the `some` option) and then having axes where the +minimum value is always `0` and where the maximum value ranges from `10` +to `100` and, second, setting `about` to the values from `3` +(corresponding to the `few` option) and to `10` (corresponding to the +`many` option) while having the minimum at `0` and the maximum at `100`: + +**Exponential steps.** For `exponential steps` the strategy for +determining a good stepping value is similar to `linear steps`, but with +the following differences: + +- Naturally, since the stepping value refers to the exponent, the + whole computation of a good stepping value needs to be done "in the + exponent". Mathematically spoken, instead of considering the + difference $r = v_{\max} - v_{\min}$, we consider the difference $r + = \log v_{\max} - \log v_{\min}$. With this difference, + we still compute $s = r / ⟨number⟩$ and let $s = m \cdot 10^k$ with + $1 + \le m < 10$. + +- It makes no longer sense to use values like $2.5$ for $m'$ since + this would yield a fractional exponent. Indeed, the only sensible + values for $m'$ seem to be $1$, $3$, $6$, and $10$. Because of this, + the `about strategy` is ignored and one of these values or a + multiple of one of them by a power of ten is used. + +The following example shows the chosen steppings for a maximum varying +from $10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as well as for +$10^{100}$ for `about=3`: + +**Alternative strategies.** + +In addition to the standard `about strategy`, there are some additional +strategies that you might wish to use instead: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/about", + meta = "⟨number⟩" + }, + ["about strategy"] = { + details = [[ +The ⟨list⟩ is a comma-separated sequence of pairs ⟨threshold⟩/⟨value⟩ +like for instance `1.5/1.0` or `2.3/2.0`. When a good value $m'$ is +sought for a given $m$, we iterate over the list and find the first pair +⟨threshold⟩/⟨value⟩ where ⟨threshold⟩ exceeds $m$. Then $m'$ is set to +⟨value⟩. For instance, if ⟨list⟩ is `1.5/1.0,2.3/2.0,4/2.5,7/5,11/10`, +which is the default, then for $m=3.141$ we would get $m'=2.5$ since +$4 > + 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/about:strategy", + meta = "⟨list⟩" + }, + ["after creation"] = { + details = [[ +This code is executed right after the object has just been created. A +handle to the just-created object is available in `\tikzdvobj`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/after:creation", + meta = "⟨code⟩" + }, + ["after survey"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/after:survey", + meta = "⟨code⟩" + }, + ["after visualization"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/after:visualization", + meta = "⟨code⟩" + }, + ["all axes"] = { + details = [[ +This key passes the ⟨options⟩ to all axes inside the current scope, just +as if you had written ⟨some axis name⟩`=`⟨options⟩ for each ⟨some axis +name⟩ in the current scope, including the just-created name ⟨axis name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/all:axes", + meta = "⟨options⟩" + }, + ["also at"] = { + details = [[ +This key is similar to `at`, but it causes ticks or grid lines to be +placed at the positions in the ⟨list⟩ *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. + + \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; + }; + +As for `at`, there are some shorthands available: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/also:at", + meta = "⟨list⟩" + }, + arg1 = { + details = [[ +The value to be passed as the first parameter to the constructor. +Similarly, the keys `arg2` to `arg8` specify further parameters passed. +Naturally, only as many arguments are passed as parameters are set. Here +is an example: + + \tikzdatavisualizationset{ + new object={ + class = example class, + arg1 = foo, + arg2 = \bar + } + } + +causes the following object creation code to be executed later on: + + \pgfoonew \tikzdvobj=new example class(foo,\bar) + +Note that you key mechanisms like `.expand once` to pass the value of a +macro instead of the macro itself: + + \tikzdatavisualizationset{ + new object={ + class = example class, + arg1 = foo, + arg2/.expand once = \bar + } + } + +Now, if `\bar` is set to `This \emph{is} it.`at the moment to object is +created later on, the following object creation code is executed: + + \pgfoonew \tikzdvobj=new example class(foo,This \emph{is} it) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/arg1", + meta = "⟨value⟩" + }, + ["arg1 from key"] = { + details = [[ +Works like the `arg1`, only the value that is passed to the constructor +is the current value of the specified ⟨key⟩ at the moment when the +object is created. + + \tikzdatavisualizationset{ + new object={ + class = example class, + arg1 from key = /tikz/some key + } + } + \tikzset{some key/.initial=foobar} + +causes the following to be executed: + + \pgfoonew \tikzdvobj=new example class(foobar) + +Naturally, the keys `arg2 from key` to `arg8 from key` are also +provided. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/arg1:from:key", + meta = "⟨key⟩" + }, + ["arg1 handle from key"] = { + details = [[ +Works like the `arg1 from key`, only the key must store an object and +instead of the object a handle to the object is passed to the +constructor. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/arg1:handle:from:key", + meta = "⟨key⟩" + }, + at = { + details = [[ +Basically, the ⟨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 ⟨list⟩. Here is an example: + + \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; + }; + +When this option is used, any previously specified tick positions are +overwritten by the values in ⟨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 ⟨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 ?? details how this works. + +It is often a bit cumbersome that one has to write things like + + some axis = {ticks = {major = {at = {...}}}} + +A slight simplification is given by the following keys, which can be +passed directly to `ticks` and `grid`: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/at", + meta = "⟨list⟩" + }, + ["at end survey"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/at:end:survey", + meta = "⟨code⟩" + }, + ["at end visualization"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/at:end:visualization", + meta = "⟨code⟩" + }, + ["at start survey"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/at:start:survey", + meta = "⟨code⟩" + }, + ["at start visualization"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/at:start:visualization", + meta = "⟨code⟩" + }, + ["axis layer"] = { + details = [[ +The layer on which the axis is drawn. See the description of +`grid layer` on page ?? for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:layer" + }, + ["axis option/anchor at max"] = { + details = [[ +Like `anchor at min`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:option/anchor:at:max" + }, + ["axis option/anchor at min"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:option/anchor:at:min" + }, + ["axis options/attribute"] = { + details = [[ +Specifies that the axis is used to transform the data points according +the different values of the key `/data point/`⟨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: + + [new axis base=x axis, + new axis base=y axis, + x axis={attribute=x}, + y axis={attribute=y}] + +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: + + [new axis base=x axis, + new axis base=y axis, + x axis={attribute=time}, + y axis={attribute=height}] + +During the data visualization, the ⟨attribute⟩ will be "monitored" +during the survey phase. This means that for each data point, the +current value of `/data point/`⟨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. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/attribute", + meta = "⟨attribute⟩" + }, + ["axis options/degrees"] = { + details = [[ +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. + + \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} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/degrees" + }, + ["axis options/exponential steps"] = { + details = [[ +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, major 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 *linearly* between major steps. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/exponential:steps" + }, + ["axis options/function"] = { + details = [[ +The ⟨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 ⟨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 ??, 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 + + some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}} + +This specifies that the function $f$ is the logarithm function. + + \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} + }; + +Another possibility might be to use the square-root function, instead: + + \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} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/function", + meta = "⟨code⟩" + }, + ["axis options/goto"] = { + details = [[ +The key can be passed to an axis. It will set the attribute monitored by +the axis to the given ⟨value⟩, which is usually some number. However, +⟨value⟩ may also be one of the following, which causes a special +behavior: + +- `min`: The attribute is set to the minimal value that the attribute + has attained along this axis. + +- `max`: Like `min`. + +- `padded min`: This will also set the ⟨attribute⟩ monitored by the + axis to the same value as `min`. Additionally, however, the subkey + `/data point/`⟨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. + +- `padded max`: Like `padded min`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/goto", + meta = "⟨value⟩" + }, + ["axis options/goto pos"] = { + details = [[ +The key works like `goto`, only the ⟨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 ⟨fraction⟩ of `0`, +the mapping process would choose value $1$ from the reasonable interval, +for a ⟨fraction⟩ of `1` the position $3$ from the reasonable interval, +and for a ⟨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 ⟨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. + + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/goto:pos", + meta = "⟨fraction⟩" + }, + ["axis options/grid"] = { + details = [[ +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 ⟨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 ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/grid", + meta = "⟨options⟩" + }, + ["axis options/include value"] = { + details = [[ +This key "fakes" data points for which the attribute's values are in the +comma-separated ⟨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. + + \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; + }; + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/include:value", + meta = "⟨list of value⟩" + }, + ["axis options/label"] = { + details = [[ +This key sets the label of an axis to ⟨text⟩. This text will typically +be placed inside a `node` and the ⟨options⟩ can be used to further +configure the way this node is rendered. The ⟨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 ??. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/label", + meta = "{[⟨options⟩]}⟨text⟩" + }, + ["axis options/length"] = { + details = [[ +Sets `scaling` to `min at 0cm and max at `⟨dimension⟩. The effect is +that the range of all values of the axis's attribute will be mapped to +an interval of exact length ⟨dimension⟩. + + \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 + }; + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/length", + meta = "⟨dimension⟩" + }, + ["axis options/linear steps"] = { + details = [[ +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 +*stepping* be $s$ (the stepping is set using the `step` option, see +below) and let the current *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 *major* 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 major ticks (and also before and after the last major +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 major ticks. Use a value of $9$ (not $10$) to partition the +interval between two major ticks into ten equally sized minor intervals. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/linear:steps" + }, + ["axis options/logarithmic"] = { + details = [[ +When this key is used with an axis, three things happen: + +1. The transformation `function` of the axis is setup to the logarithm. + +2. The strategy for automatically generating ticks and grid lines is + set to the `exponential strategy`, see Section ?? for details. + +3. The default scaling is setup sensibly. + +All told, to turn an axis into a logarithmic axis, you just need to add +this option to the axis. + + \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; + }; + +Note that this will work with any axis, including, say, the degrees on a +polar axis: + + \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} + }; + + \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} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/logarithmic" + }, + ["axis options/max value"] = { + details = [[ +Works like `min value`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/max:value", + meta = "⟨value⟩" + }, + ["axis options/min value"] = { + details = [[ +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 ⟨value⟩, they will still be depicted, but typically outside the +normal visualization area. Usually, saying `include value=`⟨value⟩ will +achieve the same as saying `min value=`⟨value⟩, but with less danger of +creating ill-formed visualizations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/min:value", + meta = "⟨value⟩" + }, + ["axis options/padding"] = { + details = [[ +Sets both `padding min` to the negated value of ⟨dimension⟩ and +`padding max` to ⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/padding", + meta = "⟨dimension⟩" + }, + ["axis options/padding max"] = { + details = [[ +Works like `padding min`, but ⟨dimension⟩ should typically be positive. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/padding:max", + meta = "⟨dimension⟩" + }, + ["axis options/padding min"] = { + details = [[ +This is the dimension that is used whenever `goto=padded min` is used. +The ⟨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 ⟨dimension⟩ is interpreted as +an additional angle rather than as an additional distance). Note that +⟨dimension⟩ should typically be negative since "adding the ⟨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{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} + +Using padded and using the `padded` key, we can visualize our axis "a +little removed from the actual data": + + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/padding:min", + meta = "⟨dimension⟩" + }, + ["axis options/power unit length"] = { + details = [[ +This key is used in conjunction with the `logarithmic` setting. It cases +the `scaling` to be set to `1 at 0cm and 10 at `⟨dimension⟩. This causes +a "power unit", that is, one power of ten in a logarithmic plot, to get +a length of ⟨dimension⟩. Again, this key is useful for ensuring that the +same scaling is used across multiple axes or pictures. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/power:unit:length", + meta = "⟨dimension⟩" + }, + ["axis options/radians"] = { + details = [[ +In contrast to `degrees`, this option sets up things so that a value of +`2*pi` on this axis corresponds to a complete circle. + + \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} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/radians" + }, + ["axis options/scaling"] = { + details = [[ +The ⟨scaling spec⟩ must have the following form: + +> ⟨$s_1$⟩` at `⟨$t_1$⟩` and `⟨$s_2$⟩` at `⟨$t_2$⟩ + +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 + + [y axis = {scaling = 1900 at 0cm and 2000 at 5cm}] + +in order to map dates between 1900 and 2000 to the dimension interval +$[0\mathrm{cm},5\mathrm{cm}]$. + + \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 + }; + +So much for the basic idea. Let us now have a detailed look at what +happens. + +**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 ??, 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 + + scaling = min at 0cm and max at 5cm + +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 +⟨attribute⟩ may attain. It is permissible that values are less than +$s_1$ or more than $s_2$. + +**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/`⟨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/`⟨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 + + [x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}] + +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. + +**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 + + [x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}] + +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 *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{aligned} + v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}. + \end{aligned}$$ + +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. + +**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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/scaling", + meta = "⟨scaling spec⟩" + }, + ["axis options/scaling/default"] = { + details = [[ +The ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/scaling/default", + meta = "⟨text⟩" + }, + ["axis options/tick placement strategy"] = { + details = [[ +This key can be used to install a so-called *tick placement strategy*. +Whenever `visualize ticks` is used to request some ticks to be +visualized, it is checked whether some automatic ticks should be +created. This is the case when the following key is set: + +Provided `compute step` is set to some nonempty value, upon +visualization of ticks the ⟨macro⟩ is executed. Typically, ⟨macro⟩ will +first call the ⟨code⟩ stored in the key `compute step`. Then, it should +implement some strategy then uses the value of the computed or desired +stepping to create appropriate `at` commands. To be precise, it should +set the keys `major`, `minor`, and/or `subminor` with some appropriate +`at` values. + +Inside the call of ⟨macro⟩, the macro `\tikzdvaxis` will have 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. + + \def\silly{ + \tikzdatavisualizationset{major={at={ + 2,3,5,7,11,13}}} + } + \begin{tikzpicture} + \datavisualization [ + scientific axes, visualize as scatter, + x axis={tick placement strategy=\silly} + ] + data { + x, y + 0, 0 + 15, 15 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/tick:placement:strategy", + meta = "⟨macro⟩" + }, + ["axis options/ticks"] = { + details = [[ +This key can be passed to an axis in order to configure which ticks are +present for the axis. The possible ⟨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 ??, which is +typically done only internally by an axis system. + +The ⟨options⟩ will be executed with the path prefix +`/tikz/data visualization/`. When the `ticks` key is used multiple times +for an axis, the ⟨options⟩ accumulate. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/ticks", + meta = "⟨options⟩" + }, + ["axis options/ticks and grid"] = { + details = [[ +This key passes the ⟨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. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/ticks:and:grid", + meta = "⟨options⟩" + }, + ["axis options/unit length"] = { + details = [[ +Sets `scaling` to `0 at 0cm and 1 at `⟨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. + + \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 + }; + +The optional `per `⟨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`: + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/unit:length", + meta = "⟨dimension⟩ per ⟨number⟩ units" + }, + ["axis options/unit vector"] = { + details = [[ +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 +⟨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 ⟨coordinate⟩. + +The bottom line is that the ⟨coordinate⟩ should usually denote a point +that is at distance `1pt` from the origin and that points into the +direction of the axis. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/unit:vector", + meta = "⟨coordinate⟩" + }, + ["axis options/unit vectors"] = { + details = [[ +Both the ⟨unit vector 0 degrees⟩ and the ⟨unit vector 90 degrees⟩ are +TikZ coordinates: + + \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} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/unit:vectors", + meta = " {⟨unit vector 0 degrees⟩}{⟨unit vector 90 degrees⟩}" + }, + ["axis options/visualize axis"] = { + details = [[ +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 ⟨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`. + +**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: + + left axis={ visualize axis={ x axis={ goto=min } } + +As can be seen, we can pass another axis as an ⟨option⟩ to +`visualize axis`, where we pass the following key to the axis in turn: + +The `right axis` would be visualized the same way, only at `goto=max`. +The $x$-axis actually needs to be visualized *twice*: Once at the bottom +and once at the top. Thus, we need to call `visualize axis` twice for +this axis: + + \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}; + +There is another key that is similar to `goto`, but has a slightly +different semantics: + +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: + +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: + +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. + +**The axis line.** When an axis is drawn, TikZ 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. + +**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 *style* the axis in a manner +similar to styling ticks and grid lines, see Section ??. In detail, the +following styles get executed: + +1. `axis layer` + +2. `every axis` + +3. `styling` + +Additionally, even before `every axis` is executed, `low=min` and +`high=max` are executed. + +Recall that the `styling` key is set using the `style` key, see +Section ??. + + \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}; + +**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 *padding* can be specified for axes: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/visualize:axis", + meta = "⟨options⟩" + }, + ["axis options/visualize grid"] = { + details = [[ +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 ⟨options⟩ +govern where and how the grid lines will be drawn. + +**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: + +1. 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 *line*. Consider for instance a three + dimensional axis system. A "grid line" for the $x$-coordinate `3` + would actually be a "grid plane". + +2. 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. + +The `visualize grid` command addresses these complications as follows: + +1. 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. + +2. 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. + +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: + +The `low` and `high` keys are the same as the ones used in the +`visualize axis` key. + + \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 + }; + + \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 + }; + +**Styling the grid lines.** When a grid line is draw, styles are applied +as described in Section ??. + +**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 ⟨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. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/visualize:grid", + meta = "⟨options⟩" + }, + ["axis options/visualize label"] = { + details = [[ +The ⟨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. + + \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}; + +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 +TikZ 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: + + \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}; + +Two additional keys are useful for positioning axis labels: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/visualize:label", + meta = "⟨options⟩" + }, + ["axis options/visualize ticks"] = { + details = [[ +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`: + + \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; + }; + +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. + +**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: + +- The `visualize ticks` key will have setup attribute $a$ to be equal + to $v$. + +- You should now use the `goto` or `goto pos` key together with all + *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: + + \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}; + +- 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: + + 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`: + + \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}; + +In order to style the tick mark, use the styling mechanism that is +detailed in Section ??. + +**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 ??. + +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: + +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: + +- 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. + +- The tick label node is styled. The styles that are applied are + described in Section ??. + +- 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 ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/axis:options/visualize:ticks", + meta = "⟨options⟩" + }, + ["before creation"] = { + details = [[ +This code is executed right before the object is finally created. It can +be used to compute values that are then passed to the constructor. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/before:creation", + meta = "⟨code⟩" + }, + ["before survey"] = { + details = [[ +The ⟨code⟩ is passed to the `before survey` method of the data +visualization object and then executed at the appropriate time (see +Section ?? for details). + +The following commands work likewise: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/before:survey", + meta = "⟨code⟩" + }, + ["before visualization"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/before:visualization", + meta = "⟨code⟩" + }, + class = { + details = [[ +The class of the to-be-created object. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/class", + meta = "⟨class name⟩" + }, + common = { + details = [[ +This key allows you to specify ⟨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: + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/common", + meta = "⟨options⟩" + }, + ["compute step"] = { + details = [[ +The ⟨code⟩ should compute a suitable value for the stepping to be used +by the ⟨macro⟩ in the tick placement strategy. + +For instance, the `step` key sets `compute step` to +`\def\tikz@lib@dv@step{# 1}`. Thus, when you say `step=5`, then the +desired stepping of `5` is communicated to the ⟨macro⟩ via the macro +`\tikz@lib@dv@step`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/compute:step", + meta = "⟨code⟩" + }, + ["data point"] = { + details = [[ +This key is the "key version" of the previous command. The difference is +that this key can be used internally inside styles. + + \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 ]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/data:point", + meta = "⟨options⟩" + }, + ["decimal about strategy"] = { + details = [[ +The only permissible value for $m'$ is $1$. This is an even more radical +version of the previous strategy. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/decimal:about:strategy" + }, + ["direction axis"] = { + details = [[ +You must pass this key as an ⟨option⟩ each time you use +`visualize axis`. When the grid line is drawn, the attribute $a$ is set +to $v$ and the axis ⟨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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/direction:axis", + meta = "⟨axis name⟩" + }, + ["euro about strategy"] = { + details = [[ +Permissible values for $m'$ are: $1$, $2$, and $5$. These are the same +values as for the Euro coins, hence the name. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/euro:about:strategy" + }, + ["every axis"] = { + details = [[ +Put styling of the axis here. It is usually a good idea to set this +style to `style={black!50}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:axis" + }, + ["every data set label"] = { + details = [[ +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. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:data:set:label" + }, + ["every grid"] = { + details = [[ +This style provides overall configuration options for grid lines. By +default, it is set to the following: + + low=min, high=max + +This causes grid lines to span all possible values when they are +visualized, which is usually the desired behavior (the `low` and `high` +keys are explained in Section ??. You can append the `style` key to this +style to configure the overall appearance of grid lines. It should be +noted that settings to `style` inside `every grid` will take precedence +over ones in `every major grid` and `every minor grid`. 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). + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:grid" + }, + ["every label in data"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:label:in:data" + }, + ["every label in legend"] = { + details = [[ +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: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:label:in:legend" + }, + ["every major grid"] = { + details = [[ +This style configures the appearance of major grid lines. It does so by +calling the `style` key to setup appropriate TikZ options for +visualizing major grid lines. The default definition of this style is: + + style = {help lines, thin, black!25} + +In the following example, we use thin major blue grid lines: + + \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; + }; + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:major:grid" + }, + ["every major ticks"] = { + details = [[ +The default is + + style={line cap=round}, tick length=2pt +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:major:ticks" + }, + ["every minor grid"] = { + details = [[ +Works like `every major grid`. The default is + + style = {help lines, black!25} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:minor:grid" + }, + ["every minor ticks"] = { + details = [[ +The default is + + style={help lines,thin, line cap=round}, tick length=1.4pt +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:minor:ticks" + }, + ["every scientific axes"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:scientific:axes" + }, + ["every subminor grid"] = { + details = [[ +Works like `every major grid`. The default is + + style = {help lines, black!10} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:subminor:grid" + }, + ["every subminor ticks"] = { + details = [[ +The default is + + style={help lines, line cap=round}, tick length=0.8pt +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:subminor:ticks" + }, + ["every ticks"] = { + details = [[ +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: + + node style={ + font=\footnotesize, + inner sep=1pt, + outer sep=.1666em, + rounded corners=1.5pt + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:ticks" + }, + ["every visualizer"] = { + details = [[ +This style is used with every visualizer. Note that it should contain +normal TikZ keys. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:visualizer" + }, + ["every ⟨axis system name⟩"] = { + details = [[ +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/`⟨axis system name⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/every:⟨axis:system:name⟩" + }, + few = { + details = [[ +This is an abbreviation for `about=3`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/few" + }, + ["grid layer"] = { + details = [[ +\[section-dv-grid-layer\] This key is used to specified the *layer* on +which grid lines should be drawn (layers are explained in Section ??). +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": + + \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; + }; + +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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/grid:layer" + }, + ["half about strategy"] = { + details = [[ +Permissible values for $m'$: $1$ and $5$. Use this strategy if only +powers of $10$ or halves thereof seem logical. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/half:about:strategy" + }, + high = { + details = [[ +Like `low`, only for where the axis ends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/high", + meta = "⟨value⟩" + }, + ["int about strategy"] = { + details = [[ +Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/int:about:strategy" + }, + legend = { + details = [[ +This is a shorthand for `new legend=main legend, main legend=`⟨options⟩. +In other words, this key creates a new `main legend` and immediately +passes the configuration ⟨options⟩ to this legend. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend", + meta = "⟨options⟩" + }, + ["legend entry options/circular label in legend line"] = { + details = [[ +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. + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/circular:label:in:legend:line" + }, + ["legend entry options/default label in legend closed path"] = { + details = [[ +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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/default:label:in:legend:closed:path" + }, + ["legend entry options/default label in legend mark"] = { + details = [[ +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`. + + \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}}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/default:label:in:legend:mark" + }, + ["legend entry options/default label in legend path"] = { + details = [[ +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`. + + \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]; + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/default:label:in:legend:path" + }, + ["legend entry options/gap circular label in legend line"] = { + details = [[ +This style is especially tailored to for the `gap cycle` style and +automatically selected by it: + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/gap:circular:label:in:legend:line" + }, + ["legend entry options/label in legend line coordinates"] = { + details = [[ +This key takes a ⟨list of coordinates⟩, which are TikZ-coordinates +separated by commas like `(0,0),``(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 ⟨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 ⟨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 ⟨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: + + \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]; + +Now let us make this a bit more fancy and useful by using shifted lines: + + \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]; + +In the final example, we use a little "hat" to represent lines: + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/label:in:legend:line:coordinates", + meta = " {list of coordinates}" + }, + ["legend entry options/label in legend mark coordinates"] = { + details = [[ +This key is similar to `label in legend line coordinates`, but now the +⟨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 ⟨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. + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/label:in:legend:mark:coordinates", + meta = " {list of coordinates}" + }, + ["legend entry options/label in legend one mark"] = { + details = [[ +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. + + \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}}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/label:in:legend:one:mark" + }, + ["legend entry options/label in legend three marks"] = { + details = [[ +An alternative to the previous style, where several marks are shown. + + \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}}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/label:in:legend:three:marks" + }, + ["legend entry options/legend"] = { + details = [[ +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 ⟨name⟩ is automatically created if it nodes +not yet exist. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/legend", + meta = "⟨name⟩" + }, + ["legend entry options/node style"] = { + details = [[ +This key adds ⟨options⟩ to the styling of the text nodes of the label. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/node:style", + meta = "⟨options⟩" + }, + ["legend entry options/setup"] = { + details = [[ +Some code to be executed at this point. Mostly, it is used to setup +attributes for style sheets. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/setup" + }, + ["legend entry options/straight label in legend line"] = { + details = [[ +Just gives a straight line and two plot marks. + + \tikz \datavisualization [visualize as line, + line={style={mark=x}, label in legend={text=example, + straight label in legend line}}]; + +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. + + \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}}]; + +For this reason, this option is not the default, but rather the next +one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/straight:label:in:legend:line" + }, + ["legend entry options/text"] = { + details = [[ +Use this key to setup the ⟨text⟩ that is shown as the label of the data +set. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/text", + meta = "⟨text⟩" + }, + ["legend entry options/text colored"] = { + details = [[ +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. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/text:colored" + }, + ["legend entry options/text left"] = { + details = [[ +Placed the text node to the left of the data set style visualization. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/text:left" + }, + ["legend entry options/text only"] = { + details = [[ +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. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/text:only" + }, + ["legend entry options/text right"] = { + details = [[ +Placed the text node to the right of the data set style visualization. +This is the default for most, but not all, legends. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/text:right" + }, + ["legend entry options/visualizer in legend"] = { + details = [[ +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. + + \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]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/visualizer:in:legend" + }, + ["legend entry options/visualizer in legend style"] = { + details = [[ +Calls to this key accumulate ⟨options⟩ that will be executed with the +path prefix `/tikz` at this point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/visualizer:in:legend:style", + meta = " {options}" + }, + ["legend entry options/zig zag label in legend line"] = { + details = [[ +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. + + \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}}]; + +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: + + \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}}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:entry:options/zig:zag:label:in:legend:line" + }, + ["legend options/above"] = { + details = [[ +This is an easier-to-remember alias. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/above" + }, + ["legend options/above left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/above:left:of", + meta = "⟨data point⟩" + }, + ["legend options/above of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/above:of", + meta = "⟨data point⟩" + }, + ["legend options/above right of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/above:right:of", + meta = "⟨data point⟩" + }, + ["legend options/anchor"] = { + details = [[ +The whole legend is a TikZ-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 ⟨anchor⟩ of +the node lies at the current `at` position. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/anchor", + meta = "⟨anchor⟩" + }, + ["legend options/at"] = { + details = [[ +Configures the ⟨coordinate⟩ at which the ⟨anchor⟩ of the legend's node +should lie. + +It may seem hard to predict a good ⟨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 ??. + +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: + + { + 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); + } + };}, + ] + \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}; + +As can be seen, a bit of an additional shift might have been in order, +but the result is otherwise quite satisfactory. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/at", + meta = "⟨coordinate⟩" + }, + ["legend options/at values"] = { + details = [[ +This key allows you to specify the desired center of the legend in terms +of a data point. The ⟨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. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/at:values", + meta = "⟨data point⟩" + }, + ["legend options/below"] = { + details = [[ +This is an easier-to-remember alias. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/below" + }, + ["legend options/below left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/below:left:of", + meta = "⟨data point⟩" + }, + ["legend options/below of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/below:of", + meta = "⟨data point⟩" + }, + ["legend options/below right of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/below:right:of", + meta = "⟨data point⟩" + }, + ["legend options/columns"] = { + details = [[ +Shorthand for `ideal number of columns=`⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/columns", + meta = "⟨number⟩" + }, + ["legend options/down then left"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/down:then:left" + }, + ["legend options/down then right"] = { + details = [[ +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. + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + +In the example, the `legend example` is the following style: + + \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}} + } + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/down:then:right" + }, + ["legend options/east inside"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/east:inside" + }, + ["legend options/east outside"] = { + details = [[ +Placing the legend to the right of the data visualization is the +default: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/east:outside" + }, + ["legend options/every legend inside"] = { + details = [[ +Executed the keys `opaque` by default and sets the text size to the size +of footnotes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/every:legend:inside" + }, + ["legend options/every new legend"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/every:new:legend" + }, + ["legend options/ideal number of columns"] = { + details = [[ +Specifies, that the entries should be split into ⟨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. + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/ideal:number:of:columns", + meta = "⟨number⟩" + }, + ["legend options/ideal number of rows"] = { + details = [[ +Works like `ideal number of columns`. + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/ideal:number:of:rows", + meta = "⟨number⟩" + }, + ["legend options/label style"] = { + details = [[ +This key can be used with a legend. It will simply add the ⟨options⟩ to +the `every label in legend` style for the given legend. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/label:style", + meta = "⟨options⟩" + }, + ["legend options/left"] = { + details = [[ +This is an easier-to-remember alias. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/left" + }, + ["legend options/left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/left:of", + meta = "⟨data point⟩" + }, + ["legend options/left then down"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/left:then:down" + }, + ["legend options/left then up"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/left:then:up" + }, + ["legend options/matrix node style"] = { + details = [[ +Adds the ⟨options⟩ to the list of options that will be executed when the +legend's node is created. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/matrix:node:style", + meta = "⟨options⟩" + }, + ["legend options/max columns"] = { + details = [[ +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. + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/max:columns", + meta = "⟨number⟩" + }, + ["legend options/max rows"] = { + details = [[ +As the legend matrix is being filled, whenever the number of rows in the +current column would exceed ⟨number⟩, a new column is started. + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; + + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/max:rows", + meta = "⟨number⟩" + }, + ["legend options/north east inside"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:east:inside" + }, + ["legend options/north east outside"] = { + details = [[ +A variant, where the legend is to the right, but aligned with the +northern end of the data visualization: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:east:outside" + }, + ["legend options/north inside"] = { + details = [[ +As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:inside" + }, + ["legend options/north outside"] = { + details = [[ +The legend is placed above the data. Note that the legend entries now +for a row rather than a column. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:outside" + }, + ["legend options/north west inside"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:west:inside" + }, + ["legend options/north west outside"] = { + details = [[ + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/north:west:outside" + }, + ["legend options/opaque"] = { + details = [[ +When this key is used, the legend's node will be filled with the ⟨color⟩ +and its corners will be rounded. Additionally, the inner and outer +separations will be set to sensible values. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/opaque", + meta = "⟨color⟩" + }, + ["legend options/right"] = { + details = [[ +This is an easier-to-remember alias. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/right" + }, + ["legend options/right of"] = { + details = [[ +Works like `at values`, but the anchor is set to `west`: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/right:of", + meta = "⟨data point⟩" + }, + ["legend options/right then down"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/right:then:down" + }, + ["legend options/right then up"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/right:then:up" + }, + ["legend options/rows"] = { + details = [[ +Shorthand for `ideal number of rows=`⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/rows", + meta = "⟨number⟩" + }, + ["legend options/south east inside"] = { + details = [[ +Puts the legend in the upper right corner of the data. + + { + 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); + } + };}, + ] + \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}; + +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 behavior is triggered by the following style key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:east:inside" + }, + ["legend options/south east outside"] = { + details = [[ + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:east:outside" + }, + ["legend options/south inside"] = { + details = [[ +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. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:inside" + }, + ["legend options/south outside"] = { + details = [[ + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:outside" + }, + ["legend options/south west inside"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:west:inside" + }, + ["legend options/south west outside"] = { + details = [[ + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/south:west:outside" + }, + ["legend options/transparent"] = { + details = [[ +Sets the filling of the legend node to `none`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/transparent" + }, + ["legend options/up then left"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/up:then:left" + }, + ["legend options/up then right"] = { + details = [[ + { + var set : {1,...,8}; + var x : interval [0:50]; + func y = sin(\value x * (\value{set}+10))/(\value{set}+5); + } + };% + \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}} + } + }}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/up:then:right" + }, + ["legend options/west inside"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/west:inside" + }, + ["legend options/west outside"] = { + details = [[ +The legend is placed left. Note that the text also swaps its position. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/legend:options/west:outside" + }, + low = { + details = [[ +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 ⟨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 ⟨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 ⟨dimension⟩ is +increased by the current values of keys like +`tick text even low padding`, see Section ?? for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/low", + meta = "⟨dimension⟩" + }, + major = { + details = [[ +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 +⟨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. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/major", + meta = "⟨options⟩" + }, + ["major also at"] = { + details = [[ +A shorthand for `major={also at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/major:also:at", + meta = "⟨list⟩" + }, + ["major at"] = { + details = [[ +A shorthand for `major={at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/major:at", + meta = "⟨list⟩" + }, + many = { + details = [[ +This is an abbreviation for `about=10`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/many" + }, + minor = { + details = [[ +Like `major`, only for minor ticks/grid lines. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/minor", + meta = "⟨options⟩" + }, + ["minor also at"] = { + details = [[ +A shorthand for `major={also at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/minor:also:at", + meta = "⟨list⟩" + }, + ["minor at"] = { + details = [[ +A shorthand for `major={at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/minor:at", + meta = "⟨list⟩" + }, + ["minor steps between steps"] = { + details = [[ +Specifies that between any two major steps (whose positions are +specified by the `step` key), there should be ⟨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 ?? for further details. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/minor:steps:between:steps", + meta = "⟨number⟩" + }, + ["new Cartesian axis"] = { + details = [[ +This key creates a new "Cartesian" axis, named ⟨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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:Cartesian:axis", + meta = "⟨name⟩" + }, + ["new axis base"] = { + details = [[ +This key defines a new axis for the current data visualization called +⟨name⟩. This has two effects: + +1. A so called *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.) + +2. The ⟨axis name⟩ is made available as a key that can be used to + configure the axis: + +3. The ⟨axis name⟩ becomes part of the current set of axes. This set + can be accessed through the following key: + +There are many ⟨options⟩ that can be passed to a newly created axis. +They are explained in the rest of this section. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:axis:base", + meta = "⟨axis name⟩" + }, + ["new axis system"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:axis:system", + meta = "{axis system name}{axis setup}{default options} {application options}" + }, + ["new legend"] = { + details = [[ +This key is used to create a new legend named ⟨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 ⟨legend name⟩ nothing +happens. + +When a legend is created, a new key is created that can subsequently be +used to configure the legend: + +In the end, the legend is just a TikZ node, a `matrix` node, to be +precise. The following key is used to style this node: + +The following style allows you to configure the default appearance of +every newly created legend: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:legend", + meta = "⟨legend name⟩" + }, + ["new legend entry"] = { + details = [[ +This key will add a new entry to the legend that is identified by the +⟨options⟩. For this, the ⟨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 ⟨options⟩ are stored away for the time +being. + +Later, when the legend is created, the ⟨options⟩ get executed once more. +This time, however, the `legend` key is no longer important. Instead, +the ⟨options⟩ that setup keys like `text` or `visualizer in legend` now +play a role. + +In detail, the following happens: + +- For the legend entry, a little cell picture is created in the matrix + of the legend (see Section ?? for details on cell pictures). + +- Inside this picture, a node is created whose text is taken from the + key + + /tikz/data visualization/legend entry options/text + +- Also inside the picture, the code stored in the following key gets + executed: + +The following styles are applied in the following order before the cell +picture is filled: + +1. `/tikz/data visualization/every data set label` with path + `/tikz/data visualization` + +2. `/tikz/data visualization/every label in legend` with path + `/tikz/data visualization/legend entry options`. + +3. The ⟨options⟩. + +4. The code in the following key: + +5. A styling signal is emitted. + +6. Only for the node: The current value of `node style`. + +7. Only for the visualizer in legend: The styling that has been + accumulated by calls to the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:legend:entry", + meta = "⟨options⟩" + }, + ["new object"] = { + details = [[ +This key serves two purposes: + +1. This method makes it easy to create a new object as part of the + rendering pipeline, using ⟨options⟩ to specify arguments rather that + directly calling `\pgfoonew`. Since you have the full power of the + keys mechanism at your disposal, it is easy, for instance, to + control whether or not parameters to the constructor are expanded or + not. + +2. The object is not created immediately, but only just before the + visualization starts. This allows you to specify that an object must + be created, but the parameter values of for its constructor may + depend on keys that are not yet set. A typical application is the + creating of an axis object: When you say `scientific axes`, the + `new object` command is used internally to create two objects + representing these axes. However, keys like `x={length=5cm}` can + only *later* be used to specify the parameters that need to be + passed to the constructor of the objects. + +The following keys may be used inside the ⟨options⟩: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:object", + meta = "⟨options⟩" + }, + ["new polar axes"] = { + details = [[ +This key actually creates two axes, whose names are give as parameters: +An *angle axis* and a *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 ⟨angle axis name⟩ or the ⟨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$. + + \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} + }; + +In detail, the ⟨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 ⟨angle axis⟩: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:polar:axes", + meta = "{⟨angle axis name⟩}{⟨radius axis name⟩}" + }, + ["new visualizer"] = { + details = [[ +This key configures a new visualizer named ⟨name⟩. This entails the +following actions: + +- The key `/tikz/data visualization/`⟨name⟩ is created. As described + earlier, this key can be used to pass for instance `style` options + to the visualizer. + +- The style key + `/tikz/data visualization/visualizers/`⟨name⟩`/styling` is created + and made empty. This is the key in which the `style` key will store + the options passed to the visualizer. + +- The style key + `/tikz/data visualization/visualizers/`⟨name⟩`/label in legend options` + is set to ⟨legend entry options⟩. These options are used to + configure how the visualizer should be rendered in a legend, see + Section ?? for details. + +- The key `/data point/set/`⟨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 ??. + +- The key `/data point/`⟨name⟩`/execute at begin` is set to code that + creates a `{scope}` that executes the following styles as options: + + 1. The ⟨options⟩ passed to the `new visualizer` key. + + 2. The `every visualizer` style. + + 3. The styling from the currently active style sheets, see + Section ??. + + 4. The styling stored in the `styling` key mentioned above. + +- The key `/data point/`⟨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. + +All of the above mean the following in practice: + +- 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. + +- The new `visualize as ...` key should also create a visualizer + object using `new object`. + +- 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. + +Everything else is usually taken care of by the `new visualizer` key +automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/new:visualizer", + meta = "{name}{options}{legend entry options}" + }, + ["no tick text"] = { + details = [[ +Shorthand for `tick text at low=false, tick text at high=false`. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/no:tick:text" + }, + ["no tick text at"] = { + details = [[ +Shorthand for `options at=`⟨value⟩` as [no tick text]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/no:tick:text:at", + meta = "⟨value⟩" + }, + ["node style"] = { + details = [[ +This key works like `style`, but it has an effect only on nodes that are +created during a data visualization. This includes tick labels and axis +labels: + + \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; + }; + +Note that in the example the ticks themselves (the little thicker lines) +are not red. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/node:style", + meta = "⟨tikzoptions⟩" + }, + ["node styling"] = { + details = [[ +Executing this key will cause all "accumulated" node stylings to be +executed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/node:styling" + }, + none = { + details = [[ +Switches off the automatic step computation. Unless you use `step=` +explicitly to set a stepping, no ticks will be (automatically) added. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/none" + }, + ["options at"] = { + details = [[ +This key causes the ⟨options⟩ to be executed for any tick mark(s) at +⟨value⟩ in addition to any options given already for this position: + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/options:at", + meta = "⟨value⟩ as [⟨options⟩]" + }, + padded = { + details = [[ +Shorthand for `low=padded min, high=padded max`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/padded" + }, + phase = { + details = [[ +See Section ?? for details on how the phase of steps influences the tick +placement. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/phase", + meta = "⟨value⟩" + }, + ["quarter about strategy"] = { + details = [[ +Permissible values for $m'$ are: $1$, $2.5$, and $5$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/quarter:about:strategy" + }, + ["school book axes"] = { + details = [[ +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 scaling is done to ensure +that the lengths of units are the same in all directions. + +This axis system must be used with care -- it is nearly always necessary +to specify the desired unit length by hand using the option +`unit length`. If the magnitudes of the units on the two axes differ, +different unit lengths typically need to be specified for the different +axes. + +Finally, if the data is "far removed" from the origin, this axis system +will also "look bad". + + \begin{tikzpicture} + \datavisualization [school book axes, visualize as smooth line] + data [format=function] { + var x : interval [-1.3:1.3]; + func y = \value x*\value x*\value x; + }; + \end{tikzpicture} + +The stepping of the ticks is one unit by default. Using keys like +`ticks=some` may help to give better steppings. + +The ⟨options⟩ are executed with the key itself as path prefix. Thus, the +following subkeys are permissible options: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/school:book:axes", + meta = "⟨options⟩" + }, + ["school book axes/standard labels"] = { + details = [[ +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. + + \begin{tikzpicture} + \datavisualization [school book axes={standard labels}, + visualize as smooth line, + clean ticks, + x axis={label=$x$}, + y axis={label=$f(x)$}] + data [format=function] { + var x : interval [-1:1]; + func y = \value x*\value x + 1; + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/school:book:axes/standard:labels" + }, + ["school book axes/unit"] = { + details = [[ +Sets the scaling so that 1 cm corresponds to ⟨value⟩ units. At the same +time, the stepping of the ticks will also be set to ⟨value⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/school:book:axes/unit", + meta = "⟨value⟩" + }, + ["scientific axes"] = { + details = [[ +This key installs a two-dimensional coordinate system based on the +attributes `/data point/x` and `/data point/y`. + + \begin{tikzpicture} + \datavisualization [scientific axes, + visualize as smooth line] + data [format=function] { + var x : interval [0:100]; + func y = sqrt(\value x); + }; + \end{tikzpicture} + +This axis system is usually a good choice to depict "arbitrary two +dimensional data". Because the axes are automatically scaled, you do not +need to worry about how large or small the values will be. The name +`scientific axes` is intended to indicate that this axis system is often +used in scientific publications. + +You can use the ⟨options⟩ to fine tune the axis system. The ⟨options⟩ +will be executed with the following path prefix: + + /tikz/data visualization/scientific axes + +All keys with this prefix can thus be passed as ⟨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": + + \begin{tikzpicture} + \datavisualization [visualize as smooth line, + scientific axes, + all axes={unit length=1cm per 10 units, ticks={few}}] + data [format=function] { + var x : interval [0:100]; + func y = sqrt(\value x); + }; + \end{tikzpicture} + +The `scientific axes` have the following properties: + +- The `x`-values are surveyed and the $x$-axis is then scaled and + shifted so that it has the length specified by the following key. + + The minimum value is at the left end of the axis and at the canvas + origin. The maximum value is at the right end of the axis. + +- The `y`-values are surveyed and the $y$-axis is then scaled so that + is has the length specified by the following key. + + The minimum value is at the bottom of the axis and at the canvas + origin. The maximum value is at the top of the axis. + +- Lines (forming a frame) are depicted at the minimum and maximum + values of the axes in 50% black. + +The following keys are executed by default as options: `outer ticks` and +`standard labels`. + +You can use the following style to overrule the defaults: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes", + meta = "⟨options⟩" + }, + ["scientific axes/clean"] = { + details = [[ +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. + + \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; + }; + +The distance of the axes from the actual plot is given by the padding of +the axes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/clean" + }, + ["scientific axes/end labels"] = { + details = [[ +Places the labels at the end of the $x$- and the $y$-axis, similar to +the axis labels of a school book axis system. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/end:labels" + }, + ["scientific axes/height"] = { + details = [[ +By default, the `height` is the golden ratio times the `width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/height", + meta = "⟨dimension⟩" + }, + ["scientific axes/inner ticks"] = { + details = [[ +This axis system works like `scientific axes`, only the ticks are on the +"inside" of the frame. + + \begin{tikzpicture} + \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; + }; + \end{tikzpicture} + +This axis system is also common in publications, but the ticks tend to +interfere with marks if they are near to the border as can be seen in +the following example: + + \begin{tikzpicture} + \datavisualization [scientific axes={inner ticks, width=3.2cm}, + style sheet=cross marks, + visualize as scatter/.list={a,b}] + data [set=a] { + x, y + 0, 0 + 1, 1 + 0.5, 0.5 + 2, 1 + } + data [set=b] { + x, y + 0.05, 0 + 1.5, 1 + 0.5, 0.75 + 2, 0.5 + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/inner:ticks" + }, + ["scientific axes/outer ticks"] = { + details = [[ +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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/outer:ticks" + }, + ["scientific axes/standard labels"] = { + details = [[ +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. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/standard:labels" + }, + ["scientific axes/upright labels"] = { + details = [[ +Works like `scientific axes standard labels`, only the label of the +$y$-axis is not rotated. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/upright:labels" + }, + ["scientific axes/width"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:axes/width", + meta = "⟨dimension⟩" + }, + ["scientific polar axes"] = { + details = [[ +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 ⟨options⟩ will be executed with the path prefix + + /tikz/data visualization/scientific polar axes + +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 ?? 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. + + \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}; + }; + +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 ??. +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:polar:axes", + meta = "⟨options⟩" + }, + ["scientific polar axes/clean"] = { + details = [[ +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. + + \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}; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:polar:axes/clean" + }, + ["scientific polar axes/inner ticks"] = { + details = [[ +This key causes the ticks to be "turned to the inside". I do not +recommend using this key. + + \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}; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:polar:axes/inner:ticks" + }, + ["scientific polar axes/outer ticks"] = { + details = [[ +This key, which is the default, causes ticks to be drawn "outside" the +outer "ring" of the polar axes: + + \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}; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/scientific:polar:axes/outer:ticks" + }, + some = { + details = [[ +This is an abbreviation for `about=5`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/some" + }, + stack = { + details = [[ +Shorthand for `tick text even padding=`⟨dimension⟩. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/stack", + meta = "⟨dimension⟩" + }, + ["stack'"] = { + details = [[ +Shorthand for `tick text odd padding=`⟨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`. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/stack'", + meta = "⟨dimension⟩" + }, + ["standard about strategy"] = { + details = [[ +Permissible values for $m'$ are: $1$, $2$, $2.5$, and $5$. This strategy +is the default strategy. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/standard:about:strategy" + }, + step = { + details = [[ +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, see the explanations in Section ?? for details. Basically, +all ticks are placed at all multiples of ⟨value⟩ that lie in the +attribute range interval. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/step", + meta = "⟨value⟩" + }, + store = { + details = [[ +If the ⟨key name⟩ is not empty, once the object has been created, a +handle to the object will be stored in ⟨key name⟩. If a handle is +already stored in ⟨key name⟩, the object is not created twice. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/store", + meta = "⟨key name⟩" + }, + style = { + details = [[ +This key takes options whose path prefix is `/tikz`, not +`/tikz/data visualization`. These options will be *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 +TikZ layer to draw something (this placed will be indicated in the +following). + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/style", + meta = "⟨tikzoptions⟩" + }, + ["style sheet"] = { + details = [[ +Adds the ⟨style sheet⟩ to the list of style sheets attached to the `set` +attribute. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/style:sheet", + meta = "⟨style sheet⟩" + }, + styling = { + details = [[ +Executing this key will cause all "accumulated" TikZ options from +previous calls to the key `/tikz/data visualization/style` to be +executed. Thus, you use `style` to set TikZ 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/styling" + }, + subminor = { + details = [[ +Like `major`, only for subminor ticks/grid lines. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/subminor", + meta = "⟨options⟩" + }, + ["subminor also at"] = { + details = [[ +A shorthand for `major={also at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/subminor:also:at", + meta = "⟨list⟩" + }, + ["subminor at"] = { + details = [[ +A shorthand for `major={at={`⟨list⟩`}}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/subminor:at", + meta = "⟨list⟩" + }, + ["tick layer"] = { + details = [[ +Like `grid layer`, this key specifies on which layer the ticks should be +placed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:layer" + }, + ["tick length"] = { + details = [[ +Shorthand for `low=-`⟨dimension⟩`, high=`⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:length", + meta = "⟨dimension⟩" + }, + ["tick node layer"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:node:layer" + }, + ["tick prefix"] = { + details = [[ +The ⟨text⟩ will be put in front of every typeset tick: + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:prefix", + meta = "⟨text⟩" + }, + ["tick suffix"] = { + details = [[ +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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:suffix", + meta = "⟨text⟩" + }, + ["tick text at high"] = { + details = [[ +Like `tick text at low`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:at:high", + meta = "⟨true or false⟩" + }, + ["tick text at low"] = { + details = [[ +Pass this option to `visualize ticks` when you want tick label nodes to +be placed at the `low` position of each tick mark. + + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:at:low", + meta = "⟨true or false⟩" + }, + ["tick text even padding"] = { + details = [[ +A shorthand for setting `tick text even low padding` and +`tick text even high padding` at the same time. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:even:padding", + meta = "⟨dimension⟩" + }, + ["tick text high even padding"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:high:even:padding", + meta = "⟨dimension⟩" + }, + ["tick text high odd padding"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:high:odd:padding", + meta = "⟨dimension⟩" + }, + ["tick text low even padding"] = { + details = [[ +When a tick label is shown at the low position of an even tick, the +⟨distance⟩ is added to the `low` value, see also Section ??. + + \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; + }; + +Note that ⟨dimension⟩ should usually be non-positive. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:low:even:padding", + meta = "⟨dimension⟩" + }, + ["tick text low odd padding"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:low:odd:padding", + meta = "⟨dimension⟩" + }, + ["tick text odd padding"] = { + details = [[ +A shorthand for setting `tick text odd low padding` and +`tick text odd high padding` at the same time. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:odd:padding", + meta = "⟨dimension⟩" + }, + ["tick text padding"] = { + details = [[ +Sets all text paddings to ⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:text:padding", + meta = "⟨dimension⟩" + }, + ["tick typesetter"] = { + details = [[ +The key gets called for each number that should be typeset. The argument +⟨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 ??. + +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$: + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:typesetter", + meta = "⟨value⟩" + }, + ["tick unit"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/tick:unit", + meta = "⟨roman math text⟩" + }, + ["uv Cartesian"] = { + details = [[ +This axis system works like `xy Cartesian`, but it introduces two axes +called `u axis` and `v axis` rather than the `x axis` and the `y axis`. +The idea is that in addition to a "major" $xy$-coordinate system this is +also a "smaller" or "minor" coordinate system in use for depicting, say, +small vectors with respect to this second coordinate system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/uv:Cartesian" + }, + ["uv axes"] = { + details = [[ +Applies the ⟨options⟩ to both the `u axis` and the `y axis`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/uv:axes", + meta = "⟨options⟩" + }, + ["uvw Cartesian cabinet"] = { + details = [[ +Like `xyz Cartesian cabinet`, but for the $uvw$-system. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/uvw:Cartesian:cabinet" + }, + ["uvw axes"] = { + details = [[ +Like `xyz axes`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/uvw:axes", + meta = "⟨options⟩" + }, + ["visualizer label options/auto"] = { + details = [[ +This key is executed automatically by default. It works like the `pos` +option, where the ⟨fraction⟩ is set to $(⟨data set's + index⟩-1/2)/⟨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. + + \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; + }; + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/auto" + }, + ["visualizer label options/index"] = { + details = [[ +This key chooses the ⟨number⟩th data point belonging to the visualizer's +data set. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/index", + meta = "⟨number⟩" + }, + ["visualizer label options/node style"] = { + details = [[ +Just passes the options to `/tikz/data visualization/node style`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/node:style", + meta = "⟨options⟩" + }, + ["visualizer label options/pin angle"] = { + details = [[ +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: + +- When an ⟨angle⟩ is specified using the present key, the shift is by + the current value of `pin length` in the direction of ⟨angle⟩. + +- When ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/pin:angle", + meta = "⟨angle⟩" + }, + ["visualizer label options/pin length"] = { + details = [[ +See the description of `pin angle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/pin:length", + meta = "⟨dimension⟩" + }, + ["visualizer label options/pos"] = { + details = [[ +This key chooses the first data point belonging to the data set whose +index is at least ⟨fraction⟩ times the number of all data points in the +data set. + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/pos", + meta = "⟨fraction⟩" + }, + ["visualizer label options/text"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/text", + meta = "⟨text⟩" + }, + ["visualizer label options/text colored"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/text:colored" + }, + ["visualizer label options/text'"] = { + details = [[ +Like `text`, only the text will be to the "right" of the data. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/text'", + meta = "⟨text⟩" + }, + ["visualizer label options/when"] = { + details = [[ +This key causes the value of the ⟨attribute⟩ to be monitored in the +stream of data points. The chosen is data point is the first data point +where the ⟨attribute⟩ is at least ⟨number⟩ (if this never happens, the +last data point is used). + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:label:options/when", + meta = "⟨attribute⟩ is⟨number⟩" + }, + ["visualizer options/gap cycle"] = { + details = [[ +Like `gapped line`, only with a cycle: + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/gap:cycle" + }, + ["visualizer options/gap line"] = { + details = [[ +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 ??. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/gap:line" + }, + ["visualizer options/ignore style sheets"] = { + details = [[ +This option, which should be passed to a visualizer after its creation +before another visualizer is created, causes style sheets *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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/ignore:style:sheets" + }, + ["visualizer options/label in data"] = { + details = [[ +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 ⟨options⟩ determine which text is shown and where it is shown. They +are executed with the following path prefix: + + /tikz/data visualization/visualizer label options + +In order to configure which text is shown and where, use the following +keys inside the ⟨options⟩: + +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 +⟨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: + +The following keys allow you to style labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/label:in:data", + meta = "⟨options⟩" + }, + ["visualizer options/label in legend"] = { + details = [[ +This key is passed to a data set, similar to options like `pin in data` +or `smooth line`. The ⟨options⟩ are used to configure the following: + +- The legend in which the data set should be visualized. + +- The text that is to be shown in the legend for the data set. + +- The appearance of the legend entries. + +In detail, the ⟨options⟩ are executed with the path prefix + + /tikz/data visualization/legend entry options + +To configure in which legend the label should appear, use the following +key: + +In addition to the two keys described above, there are further keys that +are described in Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/label:in:legend", + meta = "⟨options⟩" + }, + ["visualizer options/label in legend options"] = { + details = [[ +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 ⟨options⟩ to setup the `visualizer in legend` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/label:in:legend:options", + meta = "⟨options⟩" + }, + ["visualizer options/no lines"] = { + details = [[ +Suppresses the line. This option only makes sense when the `mark` option +is used. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/no:lines" + }, + ["visualizer options/pin in data"] = { + details = [[ +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). + + \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; + }; + +The following keys can be used additionally: + + { + 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); + } + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/pin:in:data", + meta = "⟨options⟩" + }, + ["visualizer options/polygon"] = { + details = [[ +This is an alias for `straight cycle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/polygon" + }, + ["visualizer options/smooth cycle"] = { + details = [[ +Causes the data points to be connected by a circular line that is +smoothed at the joins: + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/smooth:cycle" + }, + ["visualizer options/smooth line"] = { + details = [[ +Causes the data points to be connected by a line that is smoothed at the +joins: + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/smooth:line" + }, + ["visualizer options/straight cycle"] = { + details = [[ +Causes the data points to be connected by a polygon. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/straight:cycle" + }, + ["visualizer options/straight line"] = { + details = [[ +Causes the data points to be connected by straight lines. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/straight:line" + }, + ["visualizer options/style"] = { + details = [[ +The ⟨options⟩ given to this key should be normal TikZ options. They will +be executed when the visualizer is used. + + \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); + }; + +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 ??. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/visualizer:options/style", + meta = "⟨options⟩" + }, + when = { + details = [[ +This key is used to specify when the object is to be created. As +described above, the object is not created immediately, but at some time +during the rendering process. You can specify any of the phases defined +by the data visualization object, see Section ?? for details. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/when", + meta = "⟨phase name⟩" + }, + ["xy Cartesian"] = { + details = [[ +This axis system creates two axes called `x axis` and `y axis` that +point right and up, respectively. By default, one unit is mapped to one +cm. + + \begin{tikzpicture} + \datavisualization [xy Cartesian, visualize as smooth line] + data [format=function] { + var x : interval [-1.25:1.25]; + func y = \value x*\value x*\value x; + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/xy:Cartesian" + }, + ["xy axes"] = { + details = [[ +This key applies the ⟨options⟩ both to the `x axis` and the `y axis`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/xy:axes", + meta = "⟨options⟩" + }, + ["xyz Cartesian cabinet"] = { + details = [[ +This axis system works like `xy Cartesian`, only it *additionally* +creates an axis called `z axis` that points left and down. For this +axis, one unit corresponds to $\frac{1}{2}\sin 45^\circ\mathrm{cm}$. +This is also known as a cabinet projection. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/xyz:Cartesian:cabinet" + }, + ["xyz axes"] = { + details = [[ +This key applies the ⟨options⟩ both to the `x axis` and the `y axis`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/xyz:axes", + meta = "⟨options⟩" + }, + ["⟨axis name⟩"] = { + details = [[ +This key becomes available once `new axis base=`metaaxis name has been +called. It will execute the ⟨options⟩ with the path prefix +`/tikz/data visualization/axis options`. + + [new axis base=my axis, + my axis={attribute=some attribute}] +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/⟨axis:name⟩", + meta = "⟨options⟩" + }, + ["⟨axis system name⟩"] = { + details = [[ +When the key ⟨axis system name⟩ is used, the following keys will be +executed in the following order: + +1. The ⟨axis setup⟩ with the path prefix `/tikz/data visualization/`. + +2. The ⟨default options⟩ with the same path prefix. + +3. The following style: + +4. The ⟨options⟩ with the path prefix `/tikz/data visualization/`⟨axis + system name⟩. + +5. The ⟨application options⟩ with the path prefix + `/tikz/data visualization/` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/⟨axis:system:name⟩", + meta = "⟨options⟩" + }, + ["⟨legend name⟩"] = { + details = [[ +When this key is used, the ⟨options⟩ are executed with the path prefix + + /tikz/data visualization/legend options + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/⟨legend:name⟩", + meta = "⟨options⟩" + }, + ["⟨visualizer name⟩"] = { + details = [[ +For each visualizer, a key of the same name is created with the path +prefix `/tikz/data visualization`. This key takes the ⟨options⟩ and +executes them with the path prefix + + /tikz/data visualization/visualizer options/ + +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 ??, the first option below. + + \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); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualization/⟨visualizer:name⟩", + meta = "⟨options⟩" + } + }, + graphs = { + ["--"] = { + details = [[ +Sets the `default edge kind` to `–`. + + \tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/--" + }, + ["->"] = { + details = [[ +Sets the `default edge kind` to `->`. + + \tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/->" + }, + ["-\\protect\\exclamationmarktext-"] = { + details = [[ +Sets the `default edge kind` to `-!-`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/-\\protect\\exclamationmarktext-" + }, + ["<-"] = { + details = [[ +Sets the `default edge kind` to `<-`. + + \tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/<-" + }, + ["<->"] = { + details = [[ +Sets the `default edge kind` to `<->`. + + \tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/<->" + }, + ["Cartesian placement"] = { + details = [[ +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 `graphs` library. Just ignore the arcane +code that is used to print these numbers. + + \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 + }; + +You will find a detailed description of how these logical units are +computed, exactly, in Section ??. + +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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/Cartesian:placement" + }, + V = { + details = [[ +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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/V", + meta = "{list of vertices}" + }, + W = { + details = [[ +Sets the list of vertices for the `W` set. The elements and their number +are available in the macros `\tikzgraphW` and `\tikzgraphWnum`, +respectively. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/W", + meta = "{list of vertices}" + }, + as = { + details = [[ +The ⟨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. + + \tikz \graph { a [as=$x$] -- b [as=$y_5$] -> c [red, as={a--b}] }; + +This key always takes precedence over all of the mechanisms described +below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/as", + meta = "⟨text⟩" + }, + ["branch down"] = { + details = [[ + \tikz \graph [branch down=7mm] { a -> b -> {c, d, e}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:down", + meta = "⟨distance⟩" + }, + ["branch down sep"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:down:sep", + meta = "⟨distance⟩" + }, + ["branch left"] = { + details = [[ + \tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:left", + meta = "⟨distance⟩" + }, + ["branch left sep"] = { + details = [[ + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:left:sep", + meta = "⟨distance⟩" + }, + ["branch right"] = { + details = [[ + \tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:right", + meta = "⟨distance⟩" + }, + ["branch right sep"] = { + details = [[ +This key works like `grow right sep`, only it affects groups rather than +chains. + + \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 + }; + +When both this key and, say, `grow down sep` are set, instead of the +`west` anchor, the `north west` anchor will be selected automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:right:sep", + meta = "⟨distance⟩" + }, + ["branch up"] = { + details = [[ +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 ⟨distance⟩. + + \tikz \graph [branch up=7mm] { a -> b -> {c, d, e} }; + +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". +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:up", + meta = "⟨distance⟩" + }, + ["branch up sep"] = { + details = [[ + \tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/branch:up:sep", + meta = "⟨distance⟩" + }, + butterfly = { + details = [[ +The `butterfly` connector is used to create the kind of connections +present between layers of a so-called *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 *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`): + + \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] + }; + +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 ⟨options⟩, which are executed with the +path prefix `/tikz/graphs/butterfly`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/butterfly", + meta = "⟨options⟩" + }, + ["butterfly/from"] = { + details = [[ +Sets the color class of the from nodes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/butterfly/from", + meta = "⟨color⟩" + }, + ["butterfly/level"] = { + details = [[ +Sets the level $l$ for the connections. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/butterfly/level", + meta = "⟨level⟩" + }, + ["butterfly/to"] = { + details = [[ +Sets the color class of the to nodes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/butterfly/to", + meta = "⟨color⟩" + }, + ["chain polar shift"] = { + details = [[ +Under the regime of the `circular placement` strategy, each node on a +chain is shifted by `(`⟨logical width⟩⟨angle⟩`:`⟨logical +width⟩⟨angle⟩`)`. + + \tikz \graph [circular placement] { + a -> b -> c; + d -> e; + f -> g -> h; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/chain:polar:shift", + meta = "(⟨angle⟩:⟨radius⟩)" + }, + ["chain shift"] = { + details = [[ +Under the regime of the `Cartesian placement` strategy, each node is +shifted by the current logical width times this ⟨coordinate⟩. + + \tikz \graph [chain shift=(45:1)] { + a -> b -> c; + d -> e; + f -> g -> h; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/chain:shift", + meta = "⟨coordinate⟩" + }, + ["circular placement"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/circular:placement" + }, + ["clear <"] = { + details = [[ +A more easy-to-remember shorthand for `source edge clear`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/clear:<" + }, + ["clear >"] = { + details = [[ +A more easy-to-remember shorthand for `target edge clear`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/clear:>" + }, + clique = { + details = [[ +Adds an edge between all vertices of the current group having the +(logical) color ⟨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. + + \tikz \graph [clockwise, n=5] { + a, + b, + { + [clique] + c, d, e + } + }; + + \tikz \graph [color class=red, clockwise, n=5] { + [clique=red, ->] + a, b[red], c[red], d, e[red] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/clique", + meta = "⟨color⟩" + }, + clockwise = { + details = [[ +This key sets the `group shift` so that if there are exactly ⟨number⟩ +many nodes in a group, they will form a complete circle. If you do not +provide a ⟨number⟩, the current value of `\tikzgraphVnum` is used, which +is exactly what you want when you use predefined graph macros like +`subgraph K_ n`. + + \tikz \graph [clockwise=4] { a, b, c, d }; + + \tikz \graph [clockwise] { subgraph K_n [n=5] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/clockwise", + meta = "⟨number⟩" + }, + ["color class"] = { + details = [[ +This sets up a new color class called ⟨color class name⟩. Nodes and +whole groups of nodes can now be colored with ⟨color class name⟩. This +is done using the following keys, which become available inside the +current scope: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/color:class", + meta = "⟨color class name⟩" + }, + ["complete bipartite"] = { + details = [[ +Adds all possible edges from every node having color ⟨from color⟩ to +every node having color ⟨to color⟩: + + \tikz \graph { {a, b} ->[complete bipartite] + {c, d, e} --[complete bipartite] + {g, h, i, j} --[complete bipartite] + k }; + + \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] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/complete:bipartite", + meta = "⟨from color⟩⟨to color⟩" + }, + counterclockwise = { + details = [[ +Works like `clockwise`, only the direction is inverted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/counterclockwise", + meta = "⟨number⟩" + }, + cycle = { + details = [[ +Connects the nodes colored ⟨color⟩ is a cyclic fashion. The ordering is +the ordering in which they appear in the whole graph specification. + + \tikz \graph [clockwise, n=6, phase=60] { + { [cycle, ->] a, b, c }, + { [cycle, <-] d, e, f } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/cycle", + meta = "⟨color⟩" + }, + declare = { + details = [[ +This key declares that ⟨graph name⟩ can subsequently be used as a +replacement for a ⟨node name⟩. Whenever the ⟨graph name⟩ is used in the +following, a graph group will be inserted instead whose content is +exactly ⟨specification⟩. In case ⟨graph name⟩ is used together with some +⟨options⟩, they are executed prior to inserting the ⟨specification⟩. + + \tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] { + a; + claw; + b; + }; + +In the next example, we use a key to configure a subgraph: + + \tikz \graph [ n/.code=\def\n{#1}, branch down=4mm, + declare={star}{root -- { \foreach \i in {1,...,\n} {\i} }}] + { star [n=5]; }; + +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. + + \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] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/declare", + meta = "{graph name}{specification}" + }, + ["default edge kind"] = { + details = [[ +This key stores one of the five edge kinds `–`, `<-`, `->`, `<->`, and +`-!-`. When an operator wishes to create a new edge, it should typically +set + + \tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...} + +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 ⟨edge specification⟩ when a joining operator is +called, see the discussion of joining operators in Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/default:edge:kind", + meta = "⟨value⟩" + }, + ["default edge operator"] = { + details = [[ +This key stores the name of a ⟨key⟩ that is executed for every ⟨edge +specification⟩ whose ⟨options⟩ do not contain the `operator` key. + + \tikz \graph [default edge operator=matching] { + {a, b} ->[matching and star] + {c, d, e} --[complete bipartite] + {f, g, h} -- + {i, j, k} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/default:edge:operator", + meta = "⟨key⟩" + }, + edge = { + details = [[ +This is an alias for `edges`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge", + meta = "⟨options⟩" + }, + ["edge label"] = { + details = [[ +This key is an abbreviation for `edge node=node[auto]{`⟨text⟩`}`. The +net effect is that the `text` is placed next to the newly created edges. + + \tikz \graph [edge label=x] { a -> b -> {c,d} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:label", + meta = "⟨text⟩" + }, + ["edge label'"] = { + details = [[ +This key is an abbreviation for `edge node=node[auto,swap]{`⟨text⟩`}`. + + \tikz \graph [edge label=out, edge label'=in] + { subgraph C_n [clockwise, n=5] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:label'", + meta = "⟨text⟩" + }, + ["edge node"] = { + details = [[ +This key specifies that the ⟨node specification⟩ should be added to each +newly created edge as an implicitly placed node. + + \tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c }; + +Again, multiple uses of this key accumulate. + + \tikz \graph [edge node={node [near end] {X}}, + edge node={node [near start] {Y}}] { a -> b -> c }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:node", + meta = "⟨node specification⟩" + }, + ["edge quotes"] = { + details = [[ +A shorthand for setting the style `every edge quotes` to ⟨options⟩. + + \tikz \graph [edge quotes={blue,auto}] { + a ->["x"] b ->["y"'] c ->["b" red] d; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:quotes", + meta = "⟨options⟩" + }, + ["edge quotes center"] = { + details = [[ +A shorthand for `edge quotes` to `anchor=center`. + + \tikz \graph [edge quotes center] { + a ->["x"] b ->["y"] c ->["z" red] d; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:quotes:center" + }, + ["edge quotes mid"] = { + details = [[ +A shorthand for `edge quotes` to `anchor=mid`. + + \tikz \graph [edge quotes mid] { + a ->["x"] b ->["y"] c ->["z" red] d; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edge:quotes:mid" + }, + edges = { + details = [[ +This option causes the ⟨options⟩ to be applied to each newly created +edge inside the ⟨group specification⟩. + + \tikz \graph [edges={red,thick}] { a -> b -> c }; + +Again, multiple uses of this key accumulate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/edges", + meta = "⟨options⟩" + }, + ["empty nodes"] = { + details = [[ +Just sets `typeset` to nothing, which causes all nodes to have an empty +text (unless, of course, the `as` option is used): + + \tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/empty:nodes" + }, + ["every graph"] = { + details = [[ +This style is executed at the beginning of every `graph` path command +prior to the ⟨options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/every:graph" + }, + ["fresh nodes"] = { + details = [[ +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: + + \tikz \graph [branch down=5mm] { + { [fresh nodes] + a -> { + b -> {c, c}, + b -> {c, c}, + b -> {c, c}, + } + }, + b' -- b'' + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/fresh:nodes", + meta = "⟨true or false⟩" + }, + ["grid placement"] = { + details = [[ +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{\texttt{\string\texttt{V\textbackslash string}}}$. $N$ is the +number of rows needed to lay out the graph in a grid with $M$ columns. + + % An example with 6 nodes, 3 columns and therefor 2 rows + \tikz \graph [grid placement] { subgraph I_n[n=6, wrap after=3] }; + + % An example with 9 nodes with columns and rows computed automatically + \tikz \graph [grid placement] { subgraph Grid_n [n=9] }; + + % Directions can be changed + \tikz \graph [grid placement, branch up, grow left] { subgraph Grid_n [n=9] }; + +In case a user-defined graph instead of a pre-defined `subgraph` is to +be laid out using `grid placement`, `n` has to be specified explicitly: + + \tikz \graph [grid placement] { + [n=6, wrap after=3] + a -- b -- c -- d -- e -- f + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grid:placement" + }, + ["group polar shift"] = { + details = [[ +Like for `group shift`, each node on a chain is shifted by `(`⟨logical +depth⟩⟨angle⟩`:`⟨logical depth⟩⟨angle⟩`)`. + + \tikz \graph [circular placement, group polar shift=(30:0)] { + a -> b -> c; + d -> e; + f -> g -> h; + }; + + \tikz \graph [circular placement, + chain polar shift=(30:0), + group polar shift=(0:1cm)] { + a -- b -- c; + d -- e; + f -- g -- h; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/group:polar:shift", + meta = "(⟨angle⟩:⟨radius⟩)" + }, + ["group shift"] = { + details = [[ +Like for `chain shift`, each node is shifted by the current logical +depth times this ⟨coordinate⟩. + + \tikz \graph [chain shift=(45:7mm), group shift=(-45:7mm)] { + a -> b -> c; + d -> e; + f -> g -> h; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/group:shift", + meta = "⟨coordinate⟩" + }, + ["grow down"] = { + details = [[ +Like `grow up`. + + \tikz \graph [grow down=7mm] { a -> b -> c}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:down", + meta = "⟨distance⟩" + }, + ["grow down sep"] = { + details = [[ +As above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:down:sep", + meta = "⟨distance⟩" + }, + ["grow left"] = { + details = [[ +Like `grow up`. + + \tikz \graph [grow left=7mm] { a -> b -> c}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:left", + meta = "⟨distance⟩" + }, + ["grow left sep"] = { + details = [[ + \tikz \graph [grow left sep] { long -- longer -- longest }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:left:sep", + meta = "⟨distance⟩" + }, + ["grow right"] = { + details = [[ +Like `grow up`. + + \tikz \graph [grow right=7mm] { a -> b -> c}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:right", + meta = "⟨distance⟩" + }, + ["grow right sep"] = { + details = [[ +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 ⟨distance⟩ from the right end of the previous node: + + \tikz \graph [grow right sep, left anchor=east, right anchor=west] { + start -- { + long text -- {short, very long text} -- more text, + long -- longer -- longest + } -- end + }; + +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)`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:right:sep", + meta = "⟨distance⟩" + }, + ["grow up"] = { + details = [[ +Sets the `chain shift` to `(0,`⟨distance⟩`)`, 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 ⟨distance⟩. + + \tikz \graph [grow up=7mm] { a -> b -> c}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:up", + meta = "⟨distance⟩" + }, + ["grow up sep"] = { + details = [[ + \tikz \graph [grow up sep] { + a / $a=x$ -- + b / {$b=\displaystyle \int_0^1 x dx$} -- + c [draw, circle, inner sep=7mm] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/grow:up:sep", + meta = "⟨distance⟩" + }, + ["induced complete bipartite"] = { + details = [[ +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). + + \tikz \graph [simple] { + subgraph K_n [n=5, clockwise]; % Lots of edges + + {2, 3} ->[induced complete bipartite] {4, 5} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/induced:complete:bipartite" + }, + ["induced cycle"] = { + details = [[ +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. + + \tikz \graph [simple] { + subgraph K_n [n=7, clockwise]; % create lots of edges + + { [induced cycle, ->, edge=red] 2, 3, 4, 6, 7 }, + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/induced:cycle", + meta = "⟨color⟩" + }, + ["induced independent set"] = { + details = [[ +This key is the "opposite" of a `clique`: It removes all edges in the +current group having belonging to color class ⟨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. + + \tikz \graph [simple] { + subgraph K_n [<->, n=7, clockwise]; % create lots of edges + + { [induced independent set] 1, 3, 4, 5, 6 } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/induced:independent:set", + meta = "⟨color⟩" + }, + ["induced path"] = { + details = [[ +Works like `induced cycle`, only there is no edge from the last to the +first vertex. + + \tikz \graph [simple] { + subgraph K_n [n=7, clockwise]; % create lots of edges + + { [induced path, ->, edges=red] 2, 3, 4, 6, 7 }, + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/induced:path", + meta = "⟨color⟩" + }, + ["left anchor"] = { + details = [[ +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 ⟨anchor⟩ is stored in +the macro `\tikzgraphleftanchor` with a leading dot. + + \tikz \graph { + {a,b,c} -> [complete bipartite] {e,f,g} + }; + + \tikz \graph [left anchor=east, right anchor=west] { + {a,b,c} -- [complete bipartite] {e,f,g} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/left:anchor", + meta = "⟨anchor⟩" + }, + m = { + details = [[ +This is an abbreviation for +`W={1,...,`⟨number⟩`}, name shore W/.style={name=W}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/m", + meta = "⟨number⟩" + }, + matching = { + details = [[ +This joining operator forms a maximum *matching* between the nodes of +the two sets of nodes having colors ⟨from color⟩ and ⟨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 *perfect matching*, +otherwise only a maximum, but not perfect matching results. + + \tikz \graph { + {a, b, c} ->[matching] + {d, e, f} --[matching] + {g, h} --[matching] + {i, j, k} + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/matching", + meta = "⟨from color⟩⟨to color⟩" + }, + ["matching and star"] = { + details = [[ +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 *star* in +graph theory. This simple rule allows for some powerful effects (since +this connector is the one initially set, there is no need to add it +here): + + \tikz \graph { a -> {b, c} -> {d, e} -- f}; + +The `matching and star` connector also makes it easy to create trees and +series-parallel graphs. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/matching:and:star", + meta = "⟨from color⟩⟨to color⟩" + }, + ["math nodes"] = { + details = [[ +Sets `typeset` to `\textbackslash tikzgraphnodetext`, which causes all +nodes names to be typeset in math mode: + + \tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/math:nodes" + }, + multi = { + details = [[ +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: + + \tikz \graph [multi] { % "multi" is not really necessary here + a ->[bend left, red] b; + a ->[bend right, blue] b; + }; + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/multi" + }, + n = { + details = [[ +This is an abbreviation for +`V={1,...,`⟨number⟩`}, name shore V/.style={name=V}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/n", + meta = "⟨number⟩" + }, + name = { + details = [[ +This key prepends the ⟨text⟩, followed by a separating symbol (a space +by default), to all ⟨node name⟩s inside a ⟨full node name⟩. Repeated +calls of this key accumulate, leading to ever-longer "name paths": + + \begin{tikzpicture} + \graph { + { [name=first] 1, 2, 3} -- + { [name=second] 1, 2, 3} + }; + \draw [red] (second 1) circle [radius=3mm]; + \end{tikzpicture} + +Note that, indeed, in the above example six nodes are created even +though the first and second set of nodes have the same ⟨node name⟩. The +reason is that the full names of the six nodes are all different. Also +note that only the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/name", + meta = "⟨text⟩" + }, + ["name separator"] = { + details = [[ +Changes the symbol that is used to separate the ⟨text⟩ from the ⟨node +name⟩. The default is `\space`, resulting in a space. + + \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} + + \begin{tikzpicture} + \graph [name separator=-] { + { [name=first] 1, 2, 3} -- + { [name=second] 1, 2, 3} + }; + \draw [red] (second-1) circle [radius=3mm]; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/name:separator", + meta = "⟨symbols⟩" + }, + ["name shore V"] = { + details = [[ +Set this style to, say, `name=my V set` in order to set a name for the +`V` set. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/name:shore:V" + }, + ["name shore W"] = { + details = [[ +Same as for `name shore V`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/name:shore:W" + }, + ["new --"] = { + details = [[ +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 `-`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/new:--", + meta = "{left node}{right node}{edge options}{edge nodes}" + }, + ["new ->"] = { + details = [[ +This key will be called for a `->` edge specification with the following +four parameters: + +1. ⟨left node⟩ is the name of the "left" node, that is, the name of + $l_i$. + +2. ⟨right node⟩ is the name of the right node. + +3. ⟨edge options⟩ are the accumulated options from all calls of + `/tikz/graph/edges` in groups that surround the edge specification. + +4. ⟨edge nodes⟩ is text like `node {A} node {B}` that specifies some + nodes that should be put as labels on the edge using TikZ's implicit + positioning mechanism. + +By default, the key executes the following code: + +> `\path [->,every new ->]` +> `(`⟨left node⟩`\tikzgraphleftanchor) edge [` ⟨edge options⟩`]` ⟨edge +> nodes⟩`` +> `(`⟨right node⟩`\tikzgraphrightanchor);` + +You are welcome to change the code underlying the key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/new:->", + meta = "{left node}{right node}{edge options}{edge nodes}" + }, + ["new -\\protect\\exclamationmarktext-"] = { + details = [[ +Called for `-!-` with the same parameters as above. Does nothing by +default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/new:-\\protect\\exclamationmarktext-", + meta = "{left node}{right node}{edge options}{edge nodes}" + }, + ["new <-"] = { + details = [[ +Called for `<-` with the same parameters as above. [1] + +[1] 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/new:<-", + meta = "{left node}{right node}{edge options}{edge nodes}" + }, + ["new <->"] = { + details = [[ +Called for `<->` with the same parameters as above. The `->` is replaced +by `<-` +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/new:<->", + meta = "{left node}{right node}{edge options}{edge nodes}" + }, + ["no placement"] = { + details = [[ +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: + + \tikz \graph [no placement] + { + a[at={(0:0)}] -> b[at={(1,0)}] -> c[yshift=1cm]; + }; + +Since the syntax and the many braces and parentheses are a bit +cumbersome, the following two keys might also be useful: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/no:placement" + }, + nodes = { + details = [[ +This option causes the ⟨options⟩ to be applied to each newly created +node inside the ⟨group specification⟩. + + \tikz \graph [nodes=red] { a -> b -> c }; + +Multiple uses of this key accumulate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/nodes", + meta = "⟨options⟩" + }, + ["not ⟨color class name⟩"] = { + details = [[ +Sets up an operator for the current scope so that all nodes in it loose +the color ⟨color class name⟩. You can also use `!`⟨color class name⟩ as +an alias for this key. + + \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] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/not:⟨color:class:name⟩" + }, + ["number nodes"] = { + details = [[ +When this key is used in a scope, each encountered node name will get +appended a new number, starting with ⟨start⟩. Typically, this ensures +that all node names are different. Between the original node name and +the appended number, the setting of the following will be inserted: + + \tikz \graph [branch down=5mm] { + { [number nodes] + a -> { + b -> {c, c}, + b -> {c, c}, + b -> {c, c}, + } + }, + b 2 -- b 5 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/number:nodes", + meta = "⟨start number⟩" + }, + ["number nodes sep"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/number:nodes:sep", + meta = "⟨text⟩" + }, + operator = { + details = [[ +This key has an effect in three places: + +1. It can be used in the ⟨options⟩ of a ⟨direct node specification⟩. + +2. It can be used in the ⟨options⟩ of a ⟨group specification⟩. + +3. It can be used in the ⟨options⟩ of an ⟨edge specification⟩. + +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 ⟨options⟩ of a group are given at the beginning of the +⟨group specification⟩, the ⟨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 ⟨options⟩, the effect +accumulates, that is, all code passed to the different calls of +`operator` gets executed in the order it is encountered. + +The ⟨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: + +When the ⟨code⟩ of an operator is executed, the following commands can +be used to find the nodes that should be connected: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/operator", + meta = "⟨code⟩" + }, + path = { + details = [[ +Works like `cycle`, only there is no edge from the last to the first +vertex. + + \tikz \graph [clockwise, n=6] { + { [path, ->] a, b, c }, + { [path, <-] d, e, f } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/path", + meta = "⟨color⟩" + }, + phase = { + details = [[ +This is an initial value that is added to the total computed angle when +the polar shift of a node has been calculated. + + \tikz \graph [circular placement] { a, b, c, d }; + + \tikz \graph [circular placement, phase=0] { a, b, c, d }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/phase", + meta = "⟨angle⟩" + }, + ["placement/chain count"] = { + details = [[ +This key stores a number that tells us the sequence number of the chain +in the current group. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/chain:count" + }, + ["placement/compute position"] = { + details = [[ +The ⟨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 ⟨code⟩ is called, all of the +keys described above will hold numbers computed in the way described +above. + +The job of the ⟨code⟩ is to setup node options appropriately so that the +to-be-created node will be placed correctly. Thus, the ⟨code⟩ should +typically set the key `nodes={shift=`⟨coordinate⟩`}` where ⟨coordinate⟩ +is the computed position for the node. The ⟨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.) + + \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 + } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/compute:position", + meta = "⟨code⟩" + }, + ["placement/depth"] = { + details = [[ +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: + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/depth" + }, + ["placement/element count"] = { + details = [[ +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. + + \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 + }; + +As can be seen, each group resets the element counter. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/element:count" + }, + ["placement/level"] = { + details = [[ +This key stores a number that is increased for each element on a chain, +but gets reset at the end of a group: + + \tikz \graph [ branch down=5mm, typeset= + \tikzgraphnodetext:\pgfkeysvalueof{/tikz/graphs/placement/level}] + { + a -> { + b, + c -> { + d, + e -> {f,g}, + h + }, + j + } + }; + +Unlike the parameters `depth` and `width` described in the next section, +the key `level` is always available. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/level" + }, + ["placement/logical node depth"] = { + details = [[ +The code behind this key should return the "logical height" of the node +⟨full node name⟩ in the macro `\pgfmathresult`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/logical:node:depth", + meta = "⟨full node name⟩" + }, + ["placement/logical node width"] = { + details = [[ +This key is called to compute a physical or logical width of the node +⟨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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/logical:node:width", + meta = "⟨full node name⟩" + }, + ["placement/place"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/place" + }, + ["placement/width"] = { + details = [[ +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 *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: + +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. + + \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 + }; + +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. + + \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 + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/placement/width" + }, + ["put node text on incoming edges"] = { + details = [[ +When this key is used with a node or a group, the following happens: + +1. The command + `target edge node={node[`⟨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. + +2. The command `as={}` is executed. This means that the node itself + will display nothing. + +Here is an example that show how this command is used. + + \tikz \graph [put node text on incoming edges, + math nodes, nodes={circle,draw}] + { a -> b -> {c, d} }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/put:node:text:on:incoming:edges", + meta = "⟨options⟩" + }, + ["put node text on outgoing edges"] = { + details = [[ +Works like the previous key, only with `target` replaced by `source`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/put:node:text:on:outgoing:edges", + meta = "⟨options⟩" + }, + quick = { + details = [[ +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 *will* still work: + +1. A quick graph consists of a sequence of either nodes, edges + sequences, or groups. These are separated by commas or semicolons. + +2. Every node is of the form + + > `"`⟨node name⟩`"``/"`⟨node text⟩`"[`⟨options⟩`]` + + The quotation marks are mandatory. The part `/"`⟨node text⟩`"` may + be missing, in which case the node name is used as the node text. + The ⟨options⟩ may also be missing. The ⟨node name⟩ may not contain + any "funny" characters (unlike in the normal graph command). + +3. Every chain is of the form + + > ⟨node spec⟩ ⟨connector⟩ ⟨node spec⟩ ⟨connector⟩ ...⟨connector⟩ + > ⟨node spec⟩`;` + + Here, the ⟨node spec⟩ are node specifications as described above, + the ⟨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. + +4. Every group is of the form + + > `{ [`⟨options⟩`]` ⟨chains and groups⟩ `};` + + The ⟨options⟩ are compulsory. The semicolon can, again, be replaced + by a comma. + +5. The `number nodes` option will work as expected. + +Here is a typical way this syntax might be used: + + \tikz \graph [quick] { "a" --["foo"] "b"[x=1] }; + + \tikz \graph [quick] { + "a"/"$a$" -- "b"[x=1] --[red] "c"[x=2]; + { [nodes=blue] "a" -- "d"[y=1]; }; + }; + +Let us now have a look at the most important things that will *not* work +when the `quick` option is used: + +- Connecting a node and a group as in `a->{b,c}`. + +- Node names without quotation marks as in `a–b`. + +- 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. + +- 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`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/quick" + }, + radius = { + details = [[ +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 ⟨radius⟩ of the innermost circle. + + \tikz \graph [circular placement, radius=5mm] { a, b, c, d }; + + \tikz \graph [circular placement, radius=1cm] { a, b, c, d }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/radius", + meta = "⟨dimension⟩" + }, + ["recolor ⟨color class name⟩ by"] = { + details = [[ +Causes all keys having color ⟨color class name⟩ to get ⟨new color⟩ +instead. They loose having color ⟨color class name⟩, but other colors +are not affected. + + \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] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/recolor:⟨color:class:name⟩:by", + meta = "⟨new color⟩" + }, + ["right anchor"] = { + details = [[ +Works like `left anchor`, only for `\tikzgraphrightanchor`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/right:anchor", + meta = "⟨anchor⟩" + }, + simple = { + details = [[ +In contrast a multi-graph, in a simple graph, at most one edge gets +created for every pair of vertices: + + \tikz \graph [simple]{ + a ->[bend left, red] b; + a ->[bend right, blue] b; + }; + +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: + + \tikz \graph [simple, grow right=2cm] { + {a,b,c,d} ->[complete bipartite] {e,f,g,h}; + + { [edges={red,thick}] a -> e -> d -> g -> a }; + }; + +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: + + \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; + }; + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/simple" + }, + ["source edge clear"] = { + details = [[ +Works like `target edge clear`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/source:edge:clear", + meta = "⟨node specification⟩" + }, + ["source edge node"] = { + details = [[ +Works like `source edge style` and `target edge node`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/source:edge:node", + meta = "⟨node specification⟩" + }, + ["source edge style"] = { + details = [[ +Works exactly like `target edge style`, only now the ⟨options⟩ are only +added when the node is a source of a newly created edge: + + \tikz \graph { + { a, b } -> + { c [source edge style=red], d } -> + { e, f } + }; + +If both for the source and also for the target of an edge ⟨options⟩ have +been specified, the options are applied in the following order: + +1. First come the options from the edge itself. + +2. Then come the options contributed by the source node using this key. + +3. Then come the options contributed by the target node using + `target node style`. + +  + + \tikz \graph { + a [source edge style=red] ->[green] + b [target edge style=blue] % blue wins + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/source:edge:style", + meta = "⟨options⟩" + }, + ["target edge clear"] = { + details = [[ +Clears all ⟨options⟩ for edges with the node as a target and also edge +labels (see below) for this node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/target:edge:clear" + }, + ["target edge node"] = { + details = [[ +This key works like `target edge style`, only the ⟨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. + + \tikz \graph { + { a, b } -> + { c [target edge node=node{X}], d } -> + { e, f } + }; + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/target:edge:node", + meta = "⟨node specification⟩" + }, + ["target edge style"] = { + details = [[ +This key can (only) be used with a *node* inside a graph specification. +When used, the ⟨options⟩ will be added to every edge that is created by +a connector like `->` in which the node is a *target*. Consider the +following example: + + \tikz \graph { + { a, b } -> + { c [target edge style=red], d } -> + { e, f } + }; + +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 ⟨options⟩ are +executed after these direct options, thus, they "overrule" them: + + \tikz \graph { + { a, b } -> [blue, thick] + { c [target edge style=red], d } -> + { e, f } + }; + +The ⟨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: + + \tikz \graph { + { a, b } -> + { c [target edge style=red], d } -> + { e, f }, + b -> c + }; + +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 ⟨options⟩ to be added when some further edges are added. +This can be achieved using the following key: + + \tikz \graph { + { a, b } -> + { c [target edge style=red], d }, + b -> c[target edge clear] + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/target:edge:style", + meta = "⟨options⟩" + }, + trie = { + details = [[ +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 ⟨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 + +1. two nodes of the same name but in different parts of a chain will be + different, + +2. while if another chain starts with the same nodes, no new nodes get + created. + +In total, this is exactly the behavior you would expect of a trie: + + \tikz \graph [trie] { + a -> { + a, + c -> {a, b}, + b + } + }; + +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 LuaTeX. + + \tikz \graph [trie, simple, layered layout] { + a -> b -> a, + a -> b -> c, + a -> {d,a} + }; + +In the following example, we setup the `typeset` key so that it shows +the complete names of the nodes: + + \tikz \graph [trie, simple, layered layout, + typeset=\tikzgraphnodefullname] { + a -> b -> a, + a -> b -> c, + a -> {d,a} + }; + +You can also use the `trie` key locally and later reference nodes using +their full name: + + \tikz \graph { + { [trie, simple] + a -> { + b, + c -> a + } + }, + a b ->[red] a c a + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/trie", + meta = "⟨true or false⟩" + }, + typeset = { + details = [[ +The macro or code stored in this key is used as the ⟨text⟩ of the node. +Inside the ⟨code⟩, the following macros are available: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/typeset", + meta = "⟨code⟩" + }, + ["use existing nodes"] = { + details = [[ +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. It also implies that +an error is raised if you reference a node which has not been defined +previously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/use:existing:nodes", + meta = "⟨true or false⟩" + }, + ["wrap after"] = { + details = [[ +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`. + + \tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=1] }; + \tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=3] }; + + \tikz \graph [grid placement] { subgraph Grid_n [n=4,wrap after=2] }; + \tikz \graph [grid placement] { subgraph Grid_n [n=4] }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/wrap:after", + meta = "⟨number⟩" + }, + x = { + details = [[ +When you use this key, it will have the same effect as if you had +written `at={(`⟨x dimension⟩`,`⟨y dimension⟩`)}`, where ⟨y dimension⟩ is +a value set using the `y` key: + + \tikz \graph [no placement] + { + a[x=0,y=0] -> b[x=1,y=0] -> c[x=0,y=1]; + }; + +Note that you can specify an `x` or a `y` key for a whole scope and then +vary only the other key: + + \tikz \graph [no placement] + { + a -> + { [x=1] % group option + b [y=0] -> c[y=1] + }; + }; + +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 TikZ, which are used to specify the basic lengths of vectors. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/x", + meta = "⟨x dimension⟩" + }, + y = { + details = [[ +See above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/y", + meta = "⟨y dimension⟩" + }, + ["⟨color class name⟩"] = { + details = [[ +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" ⟨color class name⟩. Nodes retain this color in all encompassing +scopes, unless it is explicitly changed (see below) or unset (again, see +below). + + \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 + }; + + \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 } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graphs/⟨color:class:name⟩" + } + }, + tikz = { + ["'"] = { + details = [[ +This is a very short alias for `swap`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/'" + }, + ["3d view"] = { + details = [[ +With the `3d view` option, the projection of the 3D coordinates on the +2D page is defined. It is determined by rotating the coordinate system +by $-⟨azimuth⟩$ around the $z$-axis, and by ⟨elevation⟩ around the (new) +$x$-axis, as shown below. + +For example, when both ⟨azimuth⟩ and ⟨elevation⟩ are 0$^\circ$, $+z$ +will be pointing upward, and $+x$ will be pointing right. The default is +as shown below. + + \begin{tikzpicture}[3d view] + \draw[->] (-1,0,0) -- (1,0,0) node[pos=1.1]{x}; + \draw[->] (0,-1,0) -- (0,1,0) node[pos=1.1]{y}; + \draw[->] (0,0,-1) -- (0,0,1) node[pos=1.1]{z}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/3d:view", + meta = "{azimuth}{elevation}" + }, + [">"] = { + details = [[ +This is a short way of saying `<->/.tip=`⟨end arrow specification⟩. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/>", + meta = "⟨end arrow specification⟩" + }, + above = { + details = [[ +With the `positioning` library loaded, the `above` option does not take +a simple ⟨dimension⟩ as its parameter. Rather, it can (also) take a more +elaborate ⟨specification⟩ as parameter. This ⟨specification⟩ has the +following general form: It starts with an optional ⟨shifting part⟩ and +is followed by an optional ⟨of-part⟩. Let us start with the ⟨shifting +part⟩, which can have three forms: + +1. It can simply be a ⟨dimension⟩ (or a mathematical expression that + evaluates to a dimension) like `2cm` or `3cm/2+4cm`. In this case, + the following happens: the node's anchor is set to `south` and the + node is vertically shifted upwards by ⟨dimension⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \node at (1,1) [above=2pt+3pt,draw] {above}; + \end{tikzpicture} + + This use of the `above` option is the same as if the `positioning` + library were not loaded. + +2. It can be a ⟨number⟩ (that is, any mathematical expression that does + not include a unit like `pt` or `cm`). Examples are `2` or + `3+sin(60)`. In this case, the anchor is also set to `south` and the + node is vertically shifted by the vertical component of the + coordinate `(0,`⟨number⟩`)`. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \node at (1,1) [above=.2,draw] {above}; + % south border of the node is now 2mm above (1,1) + \end{tikzpicture} + +3. It can be of the form ⟨number or dimension 1⟩` and `⟨number or + dimension 2⟩. This specification does not make particular sense for + the `above` option, it is much more useful for options like + `above left`. The reason it is allowed for the `above` option is + that it is sometimes automatically used, as explained later. + + The effect of this option is the following. First, the point + `(`⟨number or dimension 2⟩`,`⟨number or dimension 1⟩`)` is computed + (note the inverted 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 anchor is set to + `south`. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \node at (1,1) [above=.2 and 3mm,draw] {above}; + % south border of the node is also 2mm above (1,1) + \end{tikzpicture} + +The ⟨shifting part⟩ can optionally be followed by a ⟨of-part⟩, which has +one of the following forms: + +1. The ⟨of-part⟩ can be `of`` `⟨coordinate⟩, where ⟨coordinate⟩ is + *not* in parentheses and it is *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 + ⟨coordinate⟩. Second, the node is shifted according to the + ⟨shift-part⟩. Third, the anchor is set to `south`. + + Here is a basic example: + + \begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,2); + \node (somenode) at (1,1) {some node}; + + \node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east}; + \node [above=1cm of somenode.north] {\tiny 1cm of somenode.north}; + \end{tikzpicture} + + As can be seen the `above=5mm of somenode.north east` option does, + indeed, place the node 5mm above the north east anchor of + `somenode`. The same effect could have been achieved writing + `above=5mm` followed by `at=(somenode.north east)`. + + If the ⟨shifting-part⟩ is missing, the shift is not zero, but rather + the value of the `node distance` key is used, see below. + +2. The ⟨of-part⟩ can be `of `⟨node name⟩. An example would be + `of somenode`. In this case, the following usually happens: + + - The anchor is set to `south`. + + - The node is shifted according to the ⟨shifting part⟩ or, if it + is missing, according to the value of `node distance`. + + - The node's `at` parameter is set to ⟨node name⟩`.north`. + + The net effect of all this is that the new node will be placed in + such a way that the distance between its south border and ⟨node + name⟩'s north border is exactly the given distance. + + \begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,2); + \node (some node) at (1,1) {some node}; + + \node (other node) [above=1cm of some node] {\tiny above=1cm of some node}; + + \draw [<->] (some node.north) -- (other node.south) + node [midway,right,draw=none] {1cm}; + \end{tikzpicture} + + It is possible to change the behavior of this ⟨specification⟩ rather + drastically, using the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above", + meta = "⟨specification⟩" + }, + ["above delimiter"] = { + details = [[ +This option allows you to add a delimiter above the node. It is +implemented by rotating a left delimiter. + + \begin{tikzpicture} + \matrix [matrix of math nodes,% + left delimiter=\|,right delimiter=\rmoustache,% + above delimiter=(,below delimiter=\}] + { + a_8 & a_1 & a_6 \\ + a_3 & a_5 & a_7 \\ + a_4 & a_9 & a_2 \\ + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:delimiter", + meta = "⟨delimiter⟩" + }, + ["above left"] = { + details = [[ +Does the same as `anchor=south east`. Note that giving both `above` and +`left` options does not have the same effect as `above left`, rather +only the last `left` "wins". Actually, this option also takes an +⟨offset⟩ parameter, but using this parameter without using the +`positioning` library is deprecated. (The `positioning` library changes +the meaning of this parameter to something more sensible.) + + \tikz \fill (0,0) circle (2pt) node[above left] {above left}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:left" + }, + ["above left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:left:of", + meta = "⟨node⟩" + }, + ["above of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:of", + meta = "⟨node⟩" + }, + ["above right"] = { + details = [[ +Works similar to `above left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:right", + meta = "⟨specification⟩" + }, + ["above right of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/above:right:of", + meta = "⟨node⟩" + }, + absolute = { + details = [[ +When this key is set, the ⟨angle⟩ is interpreted differently: We still +use a point on the border of the `main node`, but the angle is measured +"absolutely", that is, an angle of `0` refers to the point on the border +that lies on a straight line from the `main node`'s center to the right +(relative to the paper, not relative to the local coordinate system of +either the node or the scope). + +The difference can be seen in the following example: + + \tikz [rotate=-80,every label/.style={draw,red}] + \node [transform shape,rectangle,draw,label=right:label] {main node}; + + \tikz [rotate=-80,every label/.style={draw,red},absolute] + \node [transform shape,rectangle,draw,label=right:label] {main node}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/absolute", + meta = "⟨true or false⟩" + }, + accepting = { + details = [[ +This style is used to draw accepting states. You can replace this by the +style `accepting by arrow` to get accepting states with an arrow leaving +them. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting" + }, + ["accepting above"] = { + details = [[ +This is a shorthand for `accepting by arrow,accepting where=above`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:above" + }, + ["accepting below"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:below" + }, + ["accepting by arrow"] = { + details = [[ +This style causes an arrow and, possibly, some text to be added to the +node. The arrow points to the text from the node. + +The same options as for initial states can be used, only with `initial` +replaced by `accepting`: + + \begin{tikzpicture} + [shorten >=1pt,node distance=2cm,on grid,>={Stealth[round]},initial text=, + every state/.style={draw=blue!50,very thick,fill=blue!20}, + accepting/.style=accepting by arrow] + + \node[state,initial] (q_0) {$q_0$}; + \node[state] (q_1) [above right=of q_0] {$q_1$}; + \node[state] (q_2) [below right=of q_0] {$q_2$}; + \node[state,accepting](q_3) [below right=of q_1] {$q_3$}; + + \path[->] (q_0) edge node [above left] {0} (q_1) + edge node [below left] {1} (q_2) + (q_1) edge node [above right] {1} (q_3) + edge [loop above] node {0} () + (q_2) edge node [below right] {0} (q_3) + edge [loop below] node {1} (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:by:arrow" + }, + ["accepting by double"] = { + details = [[ +This style causes a double line to be drawn around a state. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:by:double" + }, + ["accepting left"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:left" + }, + ["accepting right"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:right" + }, + ["accepting text"] = { + details = [[ +This key sets the text to be used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:text", + meta = "⟨text⟩" + }, + ["accepting where"] = { + details = [[ +Set the place where the text should be shown. Allowed values are +`above`, `below`, `left`, and `right`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/accepting:where", + meta = "⟨direction⟩" + }, + alias = { + details = [[ +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 `node also` syntax, you can also assign an alias name +to a node at a later point, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/alias", + meta = "⟨another node name⟩" + }, + align = { + details = [[ +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 *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 ⟨alignment option⟩. If `text width` is not set (that is, set to the +empty string; let us call this *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 ⟨alignment option⟩ and the +resulting node's width will be minimal to encompass the resulting lines. + +In detail, you can set ⟨alignment option⟩ to one of the following +values: + +`align=``left` +For alignment without line breaking, the different lines are simply +aligned such that their left borders are below one another. + + \tikz \node[fill=yellow!80!black,align=left] + {This is a\\ demonstration text for\\ alignments.}; + +For alignment with line breaking, the same will happen; only the lines +will now, additionally, be broken automatically: + + \tikz \node[fill=yellow!80!black,text width=3cm,align=left] + {This is a demonstration text for showing how line breaking works.}; + +`align=``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 original plain TeX definition of a +ragged right border, in which TeX will try to balance the right border +as well as possible, `flush left` causes the right border to be ragged +in the LaTeX-style, in which no balancing occurs. This looks ugly, but +it may be useful for very narrow boxes and when you wish to avoid +hyphenations. + + \tikz \node[fill=yellow!80!black,text width=3cm,align=flush left] + {This is a demonstration text for showing how line breaking works.}; + +`align=``right` +Works like `left`, only for right alignment. + + \tikz \node[fill=yellow!80!black,align=right] + {This is a\\ demonstration text for\\ alignments.}; + + \tikz \node[fill=yellow!80!black,text width=3cm,align=right] + {This is a demonstration text for showing how line breaking works.}; + +`align=``flush right` +Works like `flush left`, only for right alignment. + + \tikz \node[fill=yellow!80!black,text width=3cm,align=flush right] + {This is a demonstration text for showing how line breaking works.}; + +`align=``center` +Works like `left` or `right`, only for centered alignment. + + \tikz \node[fill=yellow!80!black,align=center] + {This is a\\ demonstration text for\\ alignments.}; + + \tikz \node[fill=yellow!80!black,text width=3cm,align=center] + {This is a demonstration text for showing how line breaking works.}; + +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 +(more precisely, I have thought long and hard about this and have not +been able to figure out a sensible way to avoid this). For this reason, +TikZ 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: + +`align=``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` *unless* you have longer text, in which case `center` will give +the typographically better results. + + \tikz \node[fill=yellow!80!black,text width=3cm,align=flush center] + {This is a demonstration text for showing how line breaking works.}; + +`align=``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 rather broad nodes. + + \tikz \node[fill=yellow!80!black,text width=3cm,align=justify] + {This is a demonstration text for showing how line breaking works.}; + +In the above example, TeX complains (rightfully) about three very badly +typeset lines. (For this manual I asked TeX to stop complaining by using +`\hbadness=10000`, but this is a foul deed, indeed.) + +`align=``none` +Disables all alignments and `\\` will not be redefined. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/align", + meta = "⟨alignment option⟩" + }, + ["allow upside down"] = { + details = [[ +If set to `true`, TikZ will not "righten" upside down text. + + \tikz [allow upside down] + \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) + node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; + + \begin{tikzpicture}[->,allow upside down] + \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; + \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/allow:upside:down", + meta = "⟨boolean⟩" + }, + ["ampersand replacement"] = { + details = [[ +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: + + \tikz + \matrix [ampersand replacement=\&] + { + \draw (0,0) circle (4mm); \& \node[rotate=10] {Hello}; \\ + \draw (0.2,0) circle (2mm); \& \fill[red] (0,0) circle (3mm); \\ + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ampersand:replacement", + meta = "⟨macro name or empty⟩" + }, + anchor = { + details = [[ +Causes the node to be shifted such that its anchor ⟨anchor name⟩ lies on +the current coordinate. + +The only anchor that is present in all shapes is `center`. However, most +shapes will at least define anchors in all "compass directions". +Furthermore, the standard shapes also define a `base` anchor, as well as +`base west` and `base east`, for placing things on the baseline of the +text. + +The standard shapes also define a `mid` anchor (and `mid west` and +`mid east`). This anchor is half the height of the character "x" above +the base line. This anchor is useful for vertically centering multiple +nodes that have different heights and depth. Here is an example: + + \begin{tikzpicture}[scale=3,transform shape] + % First, center alignment -> wobbles + \draw[anchor=center] (0,1) node{x} -- (0.5,1) node{y} -- (1,1) node{t}; + % Second, base alignment -> no wobble, but too high + \draw[anchor=base] (0,.5) node{x} -- (0.5,.5) node{y} -- (1,.5) node{t}; + % Third, mid alignment + \draw[anchor=mid] (0,0) node{x} -- (0.5,0) node{y} -- (1,0) node{t}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/anchor", + meta = "⟨anchor name⟩" + }, + ["and gate"] = { + details = [[ +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 gate is +dictated by the which circuit environment is used. To further configure +the appearance of the `and gate`, see Section ??. + + \tikz [circuit logic IEC] \node [and gate] {$A$}; + + \tikz [circuit logic US] + { + \node [and gate,point down] {$A$}; + \node [and gate,point down,info=center:$A$] at (1,0) {}; + } + +**Inputs.** 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 to 1024, which should be *way* more than would ever +be needed. + +The following key is used to configure the inputs. It is available only +inside a `circuit logic` environment. + +(This key is just a shorthand for `logic gate inputs`, described in +detail on page ??. There you will also find descriptions of how to +configure the size of the inverted circles and the way the symbol size +increases when there are too many inputs.) + +**Output.** Every logic gate has one anchor called `output`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/and:gate" + }, + ["angle eccentricity"] = { + details = [[ + \tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic ["$\alpha$", draw, ->] {angle}; + + \tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic ["$\alpha$", draw, angle eccentricity=1] {angle}; + + \tikz { + \draw (2,0) coordinate (A) -- (0,0) coordinate (B) + -- (1,1) coordinate (C) + pic (alpha) ["$\alpha$", draw] {angle}; + + \draw (alpha) circle [radius=5pt]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/angle:eccentricity", + meta = "⟨factor⟩" + }, + ["angle radius"] = { + details = [[ +The length of the sides of the angle's wedge: + + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/angle:radius", + meta = "⟨dimension⟩" + }, + animate = { + details = [[ +You must place all specifications of animations inside uses of +`animate`. You can, and usually should, place the specification of all +timelines of a single picture inside a single use of this key since it +will reset the time and the fork time (explained in Section ??). You +can, however, use this key several times, in principle. Note that if you +animate the same attribute of the same object in two different uses of +`animate`, two separate timelines will result (and complicated rules are +used to determine which one "wins" in case they specify conflicting +values for the attribute at different times). + +The key can be used at all places where a TikZ key is used; typically +you will use it with a `{scope}` environment, inside the options of a +node, or directly with the `\tikz` command: + + \tikz \node [fill, text = white, animate = { + myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me}; + + \tikz [animate = {a node:fill = {0s = "red", 2s = "blue", + begin on = click}}] + \node (a node) [fill, text = white] {Click me}; + +The details of what, exactly, happens in the ⟨animation specification⟩ +will be described in the rest of this section. However, basically, an +⟨animation specification⟩ is just a sequence of normal TikZ key--value +pairs that get executed with the path prefix `/tikz/animate` and with +some special syntax handlers installed. In particular, you can define +styles for this key path and use them. For instance, we can define a +`shake` animation like this: + + \tikzset{ + animate/shake/.style = {myself:xshift = { begin on=click, + 0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}} + \tikz \node [fill = blue!20, draw=blue, very thick, circle, + animate = {shake = 1mm}] {Shake}; + \tikz \node [fill = blue!20, draw=blue, very thick, circle, + animate = {shake = 2mm}] {SHAKE}; + +Note that, as stressed earlier, you can only use the `animate` key to +specify animations for objects that do not yet exist. The node and +object names mentioned in a specification always refer to "upcoming" +objects; already existing objects of the same name are not influenced. + +You can use the `name` key inside `animate` to "name" the animation. +Once named, you can later reference the animation in other animations; +for instance, you can say that another animation should start when the +present animation has ended. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate", + meta = "⟨animation specification⟩" + }, + ["animate/arrows"] = { + details = [[ +This key only has an effect on `:path` animations. It causes the arrow +tips specified in ⟨arrow spec⟩ to be added to the path during the +animation (the syntax is the same as for the normal `arrows` key). If +you have several different animations for a paths, these may contain +different arrow tips, but each animation must stick to one kind of arrow +tips. + +What happens internally when this key is used is the following: The +specified arrow tips are rendered internally as so-called *markers,* +which are small graphics that can be placed at the beginning and ends of +paths and which "rotate along" as a path changes. Note that these +markers are used *only* in the context of animated paths, the arrow tips +of normal, "static" paths are drawn without the use of markers. +Normally, there is no visual difference between an arrow tip drawn using +markers or those drawn for static paths, but in rare cases there may be +differences. You should only add arrows to open path consisting of a +single segment with sufficiently long first and last segments (so that +TikZ can shorten these segments correctly when necessary). + +As pointed out earlier, the only way to add arrow tips to a path that is +animated is using this key, you can *not* say something like + + \draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" } + [->] (0,0) -- (1,0); + +This will raise an error since you try to animate a path (`:path = ...`) +that has normal arrow tips attached (`[->]`). + +Instead, you must specify the arrow tips inside the animation command: + + \draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> } + (0,0) -- (1,0); + +However, the above code now has a big shortcoming: While the animation +is *not* running, *no* arrow tip is shown (the `arrows` key only applies +to the animation. + +The trick is to use the `base` key. It allows you to install a path as +the "base" path that is used when no animation is running and the arrows +specified for the animation will also be used for the base. All told, +the "correct" way to specify the animation is the following (note that +no static path is specified, any specified path would be overruled by +the `base` path anyway): + + \draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> }; + +Here is an example: + + \tikz [very thick] { + \node (node) at (-2,0) + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + \draw :path = { + 0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base, + 2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}", + arrows = <.<->, begin on = {click, of=node} }; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/arrows", + meta = "⟨arrow spec⟩" + }, + ["animate/attribute"] = { + details = [[ +The list of attributes must be a comma-separated list of attribute +names. The timelines specified later will apply to all of these +attributes (and to all objects previously selected using `object`). +Possible attributes include colors, positions, line width, but even the +paths themselves. The exact list of possible attributes is documented in +Section ??. + + \tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue", + begin on = click } }] + \node (n) [fill, text = white] {The node}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/attribute", + meta = "⟨list of attributes⟩" + }, + ["animate/base"] = { + details = [[ +A "base" value is a value that is used for the attribute whenever the +timeline is *not* active: + + \tikz \node [fill = green, text = white] :fill = + { 1s = "red", 2s = "blue", base = "orange", begin on = click } + {Click me}; + +Syntactically, the `base` key works much like special time syntax: It +sets up a local `sync` scope and executes the ⟨options⟩ in it and +creates an `entry`. However, instead of setting the `time` attribute to +a time, it sets it to a special value that tells TikZ that when the +entry is created, the current ⟨value⟩ should be used as the `base` +value. + +This means that you can write `base = "orange"` as in the above example +to set the base. However, you can also use the `base` key in other ways; +most noticeably, you can use it *after* some value: + + \tikz \node [fill = green, text = white] :fill = + { 1s = {"red" = base}, 2s = "blue", begin on = click } + {Click me}; + +Instead of using `base` as a key, you can also add `base` directly after +the quotes of a value. This is particularly useful for setting up a base +value that is also used in a timeline: + + \tikz \node [fill = green, text = white] :fill = + { 1s = "red" base, 2s = "blue", begin on = click } + {Click me}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/base", + meta = "⟨options⟩" + }, + ["animate/entry"] = { + details = [[ +Each time this key is used in the options of `animate`, TikZ checks +whether the five keys `object`, `attribute`, `id`, `time`, and `value` +are set. If one of them is not set, nothing happens. (The `id` key is +set to the value `default` by default, all other keys must be set +explicitly.) + +If all of these keys are set, a *time--value* pair is created and added +to the timeline of attribute of the object. Additionally, all options +starting with `/tikz/animate/options/`, which also influence the +timeline like `begin on`, are also added to the timeline of the +object--attribute pair. + + \tikz [animate = { + object = node, attribute = fill, time = 0s, value = red, entry, + object = node, attribute = fill, time = 2s, value = blue, entry, + object = node, attribute = fill, begin on = click, entry}] + \node (node) [fill, text=white] { Click me }; + +In the above example, it would not have been necessary the specify the +object and the attribute in each line, they retain their values unless +they are overwritten. Thus, we could also have written: + + \tikz [animate = { + object = node, attribute = fill, time = 0s, value = red, entry, + time = 2s, value = blue, entry, + begin on = click, entry}] + \node (node) [fill, text=white] { Click me }; + +Note, however, that in both examples we actually add the time--value +pair $(2\mathrm{s}, \mathrm{blue})$ twice since the `time` and `value` +keys also retain their settings and, thus, for the third `entry` they +have the same values as before and a new pair is added. While this +superfluous pair is not a problem in the example (it has no visual +effect), we will see later on how such pairs can be avoided by using the +`scope` key. + +A sequence of calls of `entry` can freely switch between objects and +attributes (that is, between timelines), but the times for any given +timeline must be given in non-decreasing order: + + \tikz [animate = { + object = node, attribute = fill, time = 0s, value = red, entry, + object = node2, attribute = draw, entry, + object = node, attribute = fill, time = 2s, value = blue, entry, + object = node2, attribute = draw, entry, + object = node, attribute = fill, begin on = click, entry, + object = node2, attribute = draw, begin on = click, entry}] { + \node (node) [fill, text=white] { Node 1 }; + \node (node2) [draw, ultra thick] at (0,-1) { Node 2 }; + } + +In the above example, we could not have exchanged the first two lines of +the `animate` options with the third and fourth line since the values +for time `0s` must come before the values for time `2s`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/entry" + }, + ["animate/fork"] = { + details = [[ +Sets the fork time for the local scope to ⟨t⟩ and sets the current time +to `0s`. In this scope, when you use "absolute" times like `0s` or `2s`, +you actually refer to later times that have started as ⟨t⟩. + +One application of forks is in the definition of keys that add a certain +part to a longer animation. Consider for instance the definition of a +`highlight` key: + + \tikz [animate/highlight/.style = { + scope = { fork = #1, + :fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} } + }] + \node [animate = { myself: = { + :fill = { 0s = "black", begin on = click }, + highlight = 1s, highlight = 2s } }, + fill = blue, text=white, very thick, circle] { Click me }; + +In the above example, we could also have written `0.1s later` instead of +`0.2s` and, indeed, the whole style could have been defined using only +times with `later`, eliminating the need for the `fork` key. However, +using forks you can specify absolute times for things happening in a +conceptual "subprocess" and also relative times. The name `fork` for the +key is also borrowed from operating system theory, where a "fork" is the +spawning of an independent process. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/fork", + meta = "⟨t⟩" + }, + ["animate/id"] = { + details = [[ +Timelines are use to defined how the values of an attribute of an object +change over time. In many cases, you will have at most one timeline for +each object--attribute pair, but, sometimes, you may wish to have more +than one timeline for the same object and the same attribute. For +instance, you might have a timeline that specifies a changing `shift` of +a node in some direction and, at the same time, another timeline that +specifies an additional `shift` in some other direction(s). The problem +is that there is only one `shift` attribute and it would be difficult to +compute the joint effect of the two timelines. + +For this purpose, timelines are actually identified not only by the +object--attribute pair but, in reality, by the triple consisting of the +object, the attribute, and the value of this key. We can now specify two +separate timelines: + + \tikz [animate = { + id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click }, + id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click } + }] + \node (n) [fill = blue!20, draw=blue, very thick] {The node}; + +The default value of `id` is `default`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/id", + meta = "⟨id⟩" + }, + ["animate/object"] = { + details = [[ +The ⟨list of objects⟩ is a comma-separated list of strings of the form +⟨object⟩`.`⟨type⟩. All of the objects in the list are selected as +to-be-animate object for the next use of the `entry` key. The objects +referred to by ⟨object⟩ will be the *next* objects with the `name` key +set to ⟨object⟩. You can apply the `name` key to nodes (where you can +also use the special parentheses-syntax and put the name in parentheses, +it has the same effect), but also to scopes and paths. (The `name path` +key is not the same as `name`; it is an older key from the intersections +package and not related.) + + \tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue", + begin on = click }}] { + \node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a}; + \node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b}; + \node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; } + + \tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue", + begin on = click }, + object = c, :fill = {0s = "green", 2s = "blue", + begin on = click } }] { + \scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm); + \scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm); + \scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); } + +If the ⟨object⟩ name is never used later in the file, no animation is +created. + +The ⟨object⟩ may also be the special text `myself`. In this case, the +referenced object is the scope or object to which the `animate` key is +given. If an object is named `myself` (as in `\node (myself) ...`), you +cannot reference this node using the `object` key, `myself` *always* +refers to the object where the `animate` key is given (of course, you +can animate the node named `myself` by placing the `animate` key inside +the options of this node; you only cannot "remotely" add an animation to +it). + +The ⟨object⟩ may be followed by a dot and a *type*. This is need in rare +cases where you want to animate only a special "part" of an object that +is not accessible in other ways. Normally, TikZ takes care of choosing +these types automatically, you only need to set these "if you know what +you are doing". +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/object", + meta = "⟨list of objects⟩" + }, + ["animate/options/along"] = { + details = [[ +Use this key with a `:shift` (or a `:position`) to make TikZ shift the +object by the coordinates along the ⟨path⟩. When this key is used, the +values may no longer be coordinates, but must be fractions of the +distance along the path. A value of `"0"` refers to the beginning of the +path and `"1"` refers to the end: + + \tikz { + \draw [help lines] (-0.2,-0.2) grid (2.2,1.2); + \draw (1,.5) circle [radius=1mm]; + \node :shift = { + along = {(0,0) circle[radius=5mm]} upright, + 0s="0", 2s=".25", begin on=click } + at (1,.5) [fill = blue, opacity=.5, circle] {Click}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/along", + meta = "{path}⟨sloped or upright⟩ in⟨time⟩" + }, + ["animate/options/begin"] = { + details = [[ +This key specifies when the "moment `0s`" should be relative to the +moment when the current graphic is first displayed. You can use this key +multiple times, in this case the timeline is restarted for each of the +times specified (if it is already running, it will be reset). If no +`begin` key is given at all, the effect is the same as if `begin=0s` had +been specified. + +It is permissible to set ⟨time⟩ to a negative value. + +Note that this key has no effect for snapshots. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/begin", + meta = "⟨time⟩" + }, + ["animate/options/begin on"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/begin:on", + meta = "⟨options⟩" + }, + ["animate/options/begin snapshot"] = { + details = [[ +Use this key on a timeline to specify that, only for purposes of taking +snapshots, the timeline starts at ⟨start time⟩ rather than at "moment +zero". (Think of this as saying that the animation starts when a virtual +user clicks on the animation and this click occurs ⟨start time⟩ seconds +after the general "moment zero", causing the animation to "lag behind" +by this amount of time.) Computationally, for the timeline the ⟨start +time⟩ is subtracted from the snapshot's ⟨time⟩ when the value needs to +be determined: + + \tikz [make snapshot of = 1s] { + \fill :fill = { 0s = "black", 2s = "white", + begin snapshot = 1s } (0,0) rectangle ++(1,1); + \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/begin:snapshot", + meta = "⟨start time⟩" + }, + ["animate/options/ease"] = { + details = [[ +A shorthand for `ease in=`⟨fraction⟩`, ease out=`⟨fraction⟩. + +Note that since for the first time the entry control is ignored and, +similarly, for the last time the exit control is ignored, using the +`ease` key with an animation having only two times is particularly easy, +since we only need to set `ease` once: + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/ease", + meta = "{fraction}" + }, + ["animate/options/ease in"] = { + details = [[ +A shorthand for `entry control={1-`⟨fraction⟩`}{1}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/ease:in", + meta = "{fraction}" + }, + ["animate/options/ease out"] = { + details = [[ +A shorthand for `exit control={`⟨fraction⟩`}{1}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/ease:out", + meta = "{fraction}" + }, + ["animate/options/end"] = { + details = [[ +This key will truncate the timeline so that it ends ⟨time⟩ after the +display of the graphic, provided the timeline begins before the +specified end time. For instance, if you specify a timeline starting at +2 s and ending at 5 s and you set `begin` to 1 s and `end` to 4 s, the +timeline will run, relative to the moment when the graphic is displayed +from 3 s to 4 s. + + \tikz \node [fill = green!50!black, text = white] + :rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s } + {Click me}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/end", + meta = "⟨time⟩" + }, + ["animate/options/end on"] = { + details = [[ +Works exactly like `begin on`, one possible end of the timeline is +specified using the ⟨options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/end:on", + meta = "⟨options⟩" + }, + ["animate/options/entry control"] = { + details = [[ +Works like `exit control`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/entry:control", + meta = "{time fraction}{value fraction}" + }, + ["animate/options/exit control"] = { + details = [[ +Specifies an exit control using two values as above. The spline from +above would be specified as follows: + + exit control={0.5}{0}, + entry control={0.9}{1}, + 0s = "50", + 10s = "100" + +Note that the curve specified using exit and entry controls must be +"well-behaved" in the sense that exactly one value must be specified for +each point in time in the time interval. + +In the next three example, we first specify a "smooth" exit from the +start position, then a smooth arrival at the end position, and, finally +both. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, + 0s = { exit control = {1}{0}, "0cm" }, + 1s = "-5mm", + 2s = "-10mm" } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, + 0s = "0cm", + 1s = "-5mm", + 2s = { entry control = {0}{1}, "-10mm" } } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, + 0s = { exit control = {1}{0}, "0cm" }, + 1s = "-5mm", + 2s = { entry control = {0}{1}, "-10mm" } } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/exit:control", + meta = "{time fraction}{value fraction}" + }, + ["animate/options/forever"] = { + details = [[ +This key causes the timeline to continue "forever" after the last time +with the last value. You can also think of this as having the animation +"freeze" at the end. + + \tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click} + [fill = green!50!black, text = white] {Click me}; + + \tikz \node [fill = green!50!black, text = white] + :fill = { 1s = "red", 2s = "blue", begin on = click } + {Click me}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/forever" + }, + ["animate/options/freeze"] = { + details = [[ +An alias for `forever`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/freeze" + }, + ["animate/options/jump"] = { + details = [[ +Works like the `stay` key, but will cause the value to "jump to" the new +value right at the beginning of the time interval. It is similar to an +entry control specifying a "flat" curve. + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, + 0s = "0cm", + 1s = {jump, "-5mm"}, + 2s = "-10mm" } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/jump" + }, + ["animate/options/origin"] = { + details = [[ +Shifts the animation coordinate system by ⟨coordinate⟩. This has the +effect that the "origin" for scalings and rotations gets shifted by this +amount. In the following example, the point around which the rotation is +done is the right border at `(2,1)` since the origin of the animation is +at `(1,1)` relative to the picture's origin and the `origin` key shifts +it one centimeter to the right. + + \tikz { + \draw [help lines] (-0.2,-0.2) grid (2.2,2.2); + \node :rotate = { 0s="0", 2s="45", begin on=click, + origin = {(1,0)}} + at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/origin", + meta = "⟨coordinate⟩" + }, + ["animate/options/repeat"] = { + details = [[ +An alias for `repeats`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/repeat", + meta = "⟨specification⟩" + }, + ["animate/options/repeats"] = { + details = [[ +Use this key to specify that the timeline animation should repeat at the +end. The ⟨specification⟩ must consist of two parts, each of which may be +empty. The first part is one of the following: + +- Empty, in which case the timeline repeats forever. + + \tikz \node :rotate = { 0s = "0", 2s = "90", + repeats, begin on = click } + [fill = blue!20, draw = blue, ultra thick, circle] {Click me!}; + +- A ⟨number⟩ (like `2` or `3.25`), in which case the timeline repeats + ⟨number⟩ times. + + \tikz \node :rotate = { 0s = "0", 2s = "90", + repeats = 1.75, begin on = click } + [fill = blue!20, draw = blue, ultra thick, circle] {Click me!}; + +- The text "`for` ⟨time⟩" (like `for 2s` or `for 300ms`), in which + case the timeline repeats however often necessary so that it stops + exactly after ⟨time⟩. + + \tikz \node :rotate = { 0s = "0", 2s = "90", + repeats = for 3.5s, begin on = click } + [fill = blue!20, draw = blue, ultra thick, circle] {Click me!}; + +The second part of the specification must be one of the following: + +- Empty, in which case each time the timeline is restarted, the + attribute's value undergoes the same series of values it did + previously. + +- The text `accumulating`. This has the effect that each time the + timeline is restarted, the last values specified by the timeline is + *added* to the value from the previous iteration(s). A typical + example is an animation that shifts a scope by, say, 1 cm over a + time of 1 s. Now, if you repeat this five times, normally the scope + will shift 1 cm for 1 s then "jump back", shift again, jump back, + and so on for five times. In contrast, when the repeats are + accumulating, the scope will move by 5 cm over 5 s in total. + + \tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click, + repeats = accumulating } + [fill = blue!20, draw = blue, ultra thick, circle] {Click me!}; + + \tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click, + repeats = for 4s accumulating } + [fill = blue!20, draw = blue, ultra thick, circle] {Click me!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/repeats", + meta = "⟨specification⟩" + }, + ["animate/options/restart"] = { + details = [[ +You can set ⟨choice⟩ to one of the following: + +- `true` means that the animation will restart each time the event is + triggered. If the animation is already running, it will be reset to + its beginning. + +- `false` means that once the animation has started once, it will + never be restarted. + + \tikz \node :rotate = { 0s="0", 2s="90", + restart = false, begin on = {click}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; + +- `never` means the same as `false`. + +- `when not active` means that the animation will restart when the + event is triggered, but *not* while the animation is running. + + \tikz \node :rotate = { 0s="0", 2s="90", + restart = when not active, begin on = {click}} + [fill = blue!20, draw = blue, circle, ultra thick] {Here!}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/restart", + meta = "⟨choice⟩" + }, + ["animate/options/stay"] = { + details = [[ +Specifies that inside the time interval the value "stays put" at the +first value till the end of the interval, where it will jump to the +second value. This is similar to an exit control where the curve is +"infinitely flat". + + \tikz { + \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0); + \node :yshift = { begin on = click, + 0s = "0cm", + 1s = {stay, "-5mm"}, + 2s = "-10mm" } + [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/stay" + }, + ["animate/options/transform"] = { + details = [[ +While the `origin` key does only a shift, the `transform` key allows you +to add an arbitrary transformation to the animation coordinate system +using keys like `shift`, `rotate` or even `reset cm` and `cm`. In +particular, `origin=`⟨c⟩ has the same effect as `transform` `=` +`{shift=`⟨c⟩`}`. Note that the transformation only influences the +animation, not the object itself. + +As an example, when you say `transform={scale=2}`, an `:xshift` with a +value of `"1cm"` will actually shift the object by 2cm. Similarly, after +you say `transform={rotate=90,scale=2}`, the same `:xshift` of `"1cm"` +will actually shift the object by 2cm upwards. + +Note that, internally, TikZ has to invert the transformation matrix +resulting from the ⟨transformation keys⟩ (plus the original animation +transformation matrix), which can by numerically instable when you use +ill-conditioned transformations. + + \tikz { + \draw [help lines] (-0.2,-0.2) grid (2.2,2.2); + \node :xshift = { 0s="0cm", 2s="5mm", begin on=click, + transform = {rotate=-90} } + at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me}; + } + + \tikz { + \draw [help lines] (-0.2,-0.2) grid (2.2,2.2); + \node :xshift = { 0s="0cm", 2s="5mm", begin on=click, + transform = {rotate=-45, scale=2} } + at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/options/transform", + meta = "⟨transformation keys⟩" + }, + ["animate/remember"] = { + details = [[ +This key stores the current time (the time of the last use of the `time` +key) globally in the macro ⟨macroname⟩. This time will include the +offset of the fork time: + + time = 2s, + fork = 2s later, % fork time is now 4s + time = 1s, % local time is 1s, absolute time is 5s (1s + fork time) + time = 1s later, % local time is 2s, absolute time is 6s (2s + fork time) + remember = \mytime % \mytime is now 6s +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/remember", + meta = "⟨macroname⟩" + }, + ["animate/resume"] = { + details = [[ +The ⟨absolute time⟩ is evaluated using `\pgfparsetime` and, then, the +current time is set to the resulting time minus the fork time. When the +⟨absolute time⟩ is a macro previously set using `remember`, the net +effect of this is that we return to the exact "moment" in the global +time line when `remember` was used. + + fork = 4s, + time = 1s, + remember = \mytime % \mytime is now 5s + fork = 2s, % fork time is now 2s, local time is 0s + resume = \mytime % fork time is still 2s, local time is 3s + +Using resume you can easily implement a "join" operation for forked +times. You simply remember the times at the ends of the forks and then +resume the maximum time of these remembered times: + + scope = { + fork, + time = 1s later, + ... + remember = \forka + }, + scope = { + fork, + time = 5s later, + ... + remember = \forkb + }, + scope = { + fork, + time = 2s later, + ... + remember = \forkc + }, + resume = {max(\forka,\forkb,\forkc)} % "join" the three forks +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/resume", + meta = "⟨absolute time⟩" + }, + ["animate/scope"] = { + details = [[ +Executed the ⟨options⟩ inside a TeX scope. In particular, all settings +made inside the scope have no effect after the end of the `scope`. + + \tikz \node [animate = { myself: = { begin on = click, + scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" }, + scope = { attribute = draw, 0s = "red", 2s = "red!50" } + }}, + fill=blue!20, draw=blue, very thick, circle] {Click me}; + +Without the use of the `scope` key, the `repeats` key would also affect +the draw attribute. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/scope", + meta = "⟨options⟩" + }, + ["animate/shorten < "] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/shorten:<:", + meta = " ⟨dimension⟩" + }, + ["animate/shorten > "] = { + details = [[ +For animated paths, just as the key `arrows` has to be passed to the +animation (to `:path`) instead of to the static path, the keys +`shorten >` and `shorten <` also have to be passed to the `:path` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/shorten:>:", + meta = " ⟨dimension⟩" + }, + ["animate/sync"] = { + details = [[ +A shorthand for `scope={` ⟨options⟩ `, remember=\temp},resume=\temp` +where `\temp` is actually an internal name. The effect is that after a +`sync` the local time just continues as if the scope where not present +-- but regarding everything else the effects are local to the `sync` +scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/sync", + meta = "⟨options⟩" + }, + ["animate/time"] = { + details = [[ +Sets the time for the next time--value pair in a call of `entry` to +⟨time⟩ plus the current fork time. The text `later` is optional. Both +"fork times" and the optional `later` will be explained in a moment. + +**Time Parsing.** The ⟨time⟩ is parsed using the command +`\pgfparsetime`, which is essentially the same as the usual math parser +of TikZ, and the result is interpreted as a time in seconds. Thus, a +⟨time⟩ of `2+3` means "5 seconds" and a ⟨time⟩ of `2*(2.1)` means "4.2 +seconds". (You could even specify silly times like `1in`, which results +in the time "72.27 seconds". Please do not do that.) The "essentially" +refers to the fact that some extras are installed when the time parser +is running: + +- The postfix operator `s` is added, which has no effect. Thus, when + you write `5s` you get the same results as `5`, which is exactly 5 + seconds as desired. + +- The postfix operator `ms` is added, which divides a number by 1000, + so `2ms` equals 0.002s. + +- The postfix operator `min` is added, which multiplies a number + by 60. + +- The postfix operator `h` is added, which multiplies a number + by 3600. + +- The infix operator `:` is redefined, so that it multiplies its first + argument by 60 and adds the second. This implies that `1:20` equals + 80s and `01:00:00` equals 3600s. + +- The parsing of octal numbers is switched off to allow things like + `01:08` for 68s. + +Note that you cannot use the colon syntax for times in things like +`01:20 = "0"` would (falsely) be interpreted as: "For the object named +`01` and its attribute named `20`, do something." You can, however, use +`01:20` in arguments to the `time` key, meaning that you would have to +write instead: `time = 1:20, "0"`, possibly surround by a `scope`. + +**Relative Times.** You can suffix a `time` key with "`later`". In this +case, the ⟨time⟩ is interpreted as an offset to the time in the previous +use of the time key: + + \tikz \node :fill = { begin on = click, + 0s = "white", + 500ms later = "red", + 500ms later = "green", % same as 1s = "-5mm" + 500ms later = "blue"} % same as 1.5s = "-2.5mm" + [fill=blue!20, draw=blue, very thick, circle] {Click me}; + +In reality, the offset is not taken to just any previous use of the +`time` key, but to the most recent use of this key or of the `resume` +key in the current local TeX scope. Here is an example: + + time = 2s, + time = 1s later, % same as time = 3s + time = 500ms later, % same as time = 3.5s + time = 4s, + time = 1s later, % same as time = 5s + scope = { % opens a local scope + time = 1s later, % same as time = 6s + time = 10s + time = 1s later % same as time = 11s + }, % closes the scope, most recent time is 5s once more + time = 2s later % same as time = 7s + +**Fork Times.** The time meant by the value ⟨time⟩ passed to the `time` +key is not used directly. Rather, TikZ adds the current *fork time* to +it, which is `0s` by default. You can change the fork time using the +following key: + +**Remembering and Resuming Times.** When you have a complicated +animation with a long timeline, you will sometimes wish to start some +animation when some other animation has reached a certain moment; but +this moment is only reached through heavy use of `later` times and/or +forks. In such situations, the following keys are useful: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/time", + meta = "⟨time⟩later" + }, + ["animate/value"] = { + details = [[ +This key sets the value of the next time--value pair created by `entry` +to ⟨value⟩. The syntax of the ⟨value⟩ is not fixed, it depends on the +type of the attribute. For instance, for an attribute like `opacity` the +⟨value⟩ must be an expression that can be evaluated to a number between +0 and 1; for the attribute `color` the ⟨value⟩ must, instead, be a +color; and so on. Take care that when a value contains a comma, you must +surround it by braces as in `"{(1,1)}"`. + +The allowed texts for the ⟨value⟩ is always the same as the one you +would pass to the TikZ option of the same name. For instance, since the +TikZ option `shift` expects a coordinate, you use coordinates as ⟨value⟩ +with the usual TikZ syntax (including all sorts of extensions, the +animation system calls the standard TikZ parsing routines). The same is +true of dimensions, scalar values, colors, and so on. + +In addition to the values normally use for setting the attribute, you +can also (sometimes) use the special text `current value` as ⟨value⟩. +This means that the value of the point in the timeline should be +whatever the value the attribute has at the beginning of the timeline. +For instance, when you write + + animate = { obj:color = { 0s = "current value", 2s = "white" } } + +the color of `obj` will change from whatever color it currently has to +white in two seconds. This is especially useful when several animations +are triggered by user events and the current color of `obj` cannot be +determined beforehand. + +There are several limitations on the use of the text `current value`, +which had to be imposed partly because of the limited support of this +feature in SVG: + +- You can use `current value` only with the first time in a timeline. + +- You can only have two times in a timeline that starts with + `current value`. + +- You cannot use `current value` for timelines of which you wish to + take a snapshot. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animate/value", + meta = "⟨value⟩" + }, + ["animations/base"] = { + details = [[ +The syntax of the ⟨value⟩ is the same as for the `entry` key. The +⟨value⟩ is installed as the value of the object's attribute whenever the +timeline is not active. This makes it easy to specify the value of an +attribute when the animation is "not running". + + \tikz { + \pgfanimateattribute{rotate}{ + whom = node, begin on = {click}, + entry = {0s}{90}, entry = {2s}{180}, + base = 45 + } + \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animations/base", + meta = "⟨value⟩" + }, + ["animations/begin snapshot"] = { + details = [[ +When this key is used inside the options of `\pgfanimateattribute`, with +respect to snapshots, the timeline begins at ⟨begin time⟩. This means +that, if the snapshot time is set to ⟨time⟩ and the beginning of the +snapshot's timeline is set to ⟨begin time⟩, the attribute is set to the +value of the timeline at time $⟨time⟩ - + ⟨begin time⟩$. + +The idea is that when you make a snapshot of several animations and all +of them have started at different times because of different events, you +use `begin snapshot` with each object and attribute to directly specify +when these different events have happened. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/animations/begin:snapshot", + meta = "⟨begin time⟩" + }, + annotation = { + details = [[ +This style indicates that a node is an annotation node. It includes the +style `every annotation`, which allows you to change this style in a +convenient fashion. + + \begin{tikzpicture} + [mindmap,concept color=blue!80, + every annotation/.style={fill=red!20}] + \node [concept] (root) {Root concept}; + + \node [annotation,right] at (root.east) + {The root concept is, in general, the most important concept.}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/annotation" + }, + ["annotation arrow"] = { + details = [[ +This style should set the default `>` arrow to some nice value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/annotation:arrow" + }, + ["append after command"] = { + details = [[ +Some of the path commands described in the following sections take +optional arguments. For these commands, when you use this key inside +these options, the ⟨path⟩ will be inserted *after* the path command is +done. For instance, when you give this command in the option list of a +node, the ⟨path⟩ will be added after the node. This is used by, for +instance, the `label` option to allow you to specify a label in the +option list of a node, but have this `label` cause a node to be added +after another node. + + \tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo}; + +If this key is called multiple times, the effects accumulate, that is, +all of the paths are added in the order to keys were found. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/append:after:command", + meta = "⟨path⟩" + }, + arrows = { + details = [[ +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 ⟨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: + + \tikz [arrows={[bend]}] ... % Bend all arrows +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/arrows", + meta = "[⟨arrow keys⟩]" + }, + at = { + details = [[ +If this option is explicitly set inside the ⟨options⟩ (or indirectly via +the `every circle` style), the ⟨coordinate⟩ is used as the center of the +circle instead of the current point. Setting `at` to some value in an +enclosing scope has no effect. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/at", + meta = "⟨coordinate⟩" + }, + ["at end"] = { + details = [[ +Set to `pos=1`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/at:end" + }, + ["at start"] = { + details = [[ +Set to `pos=0`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/at:start" + }, + attribute = { + details = [[ +This style is used to indicate that a node is an attribute. To connect +an attribute to its entity, you can use, for example, the `child` +command or the `pin` option. + + \begin{tikzpicture} + \node[entity] (sheep) {Sheep} + child {node[attribute] {name}} + child {node[attribute] {color}}; + \end{tikzpicture} + + \begin{tikzpicture}[every pin edge/.style=draw] + \node[entity,pin={[attribute]60:name},pin={[attribute]120:color}] {Sheep}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/attribute" + }, + auto = { + details = [[ +This option causes an anchor position to be calculated automatically +according to the following rule. Consider a line between two points. If +the ⟨direction⟩ is `left`, then the anchor is chosen such that the node +is to the left of this line. If the ⟨direction⟩ is `right`, then the +node is to the right of this line. Leaving out ⟨direction⟩ causes +automatic placement to be enabled with the last value of `left` or +`right` used. A ⟨direction⟩ of `false` disables automatic placement. +This happens also whenever an anchor is given explicitly by the `anchor` +option or by one of the `above`, `below`, etc. options. + +This option only has an effect for nodes that are placed on lines or +curves. + + \begin{tikzpicture} + [scale=.8,auto=left,every node/.style={circle,fill=blue!20}] + \node (a) at (-1,-2) {a}; + \node (b) at ( 1,-2) {b}; + \node (c) at ( 2,-1) {c}; + \node (d) at ( 2, 1) {d}; + \node (e) at ( 1, 2) {e}; + \node (f) at (-1, 2) {f}; + \node (g) at (-2, 1) {g}; + \node (h) at (-2,-1) {h}; + + \foreach \from/\to in {a/b,b/c,c/d,d/e,e/f,f/g,g/h,h/a} + \draw [->] (\from) -- (\to) + node[midway,fill=red!20] {\from--\to}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/auto", + meta = "⟨direction⟩" + }, + ["background grid"] = { + details = [[ +This style dictates how the background grid path is drawn. + + \begin{tikzpicture} + [background grid/.style={thick,draw=red,step=.5cm}, + show background grid] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/background:grid" + }, + ["background rectangle"] = { + details = [[ +This style dictates how the background rectangle is drawn or filled. The +default setting causes the path of the background rectangle to be drawn +in the usual way. Setting this style to, say, `fill=blue!20` causes a +light blue background to be added to the picture. You can also use more +fancy settings as shown in the following example: + + \begin{tikzpicture} + [background rectangle/.style= + {double,ultra thick,draw=red,top color=blue,rounded corners}, + show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} + +Naturally, no one in their right mind would use the above, but here is a +nice background: + + \begin{tikzpicture} + [background rectangle/.style= + {draw=blue!50,fill=blue!20,rounded corners=1ex}, + show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/background:rectangle" + }, + ["background top"] = { + details = [[ + \tikzset{background rectangle/.style={fill=blue!20}, + background top/.style={draw=blue!50,line width=1ex}} + \begin{tikzpicture}[framed,show background top] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/background:top" + }, + ["badness warnings for centered text"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/badness:warnings:for:centered:text", + meta = "⟨true or false⟩" + }, + ["ball color"] = { + details = [[ +This option sets the color used for the ball shading. It sets the +`shade` and `shading=ball` options. Note that the ball will never +"completely" have the color ⟨color⟩. At its "highlight" spot a certain +amount of white is mixed in, at the border a certain amount of black. +Because of this, it also makes sense to say `ball color=white` or +`ball color=black` + + \begin{tikzpicture} + \shade[ball color=white] (0,0) circle (2ex); + \shade[ball color=red] (1,0) circle (2ex); + \shade[ball color=black] (2,0) circle (2ex); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ball:color", + meta = "⟨color⟩" + }, + ["base left"] = { + details = [[ +This key works like the `left` key, only instead of the `east` anchor, +the `base east` anchor is used and, when the second form of an ⟨of-part⟩ +is used, the corresponding `base west` anchor. + +This key is useful for chaining together nodes so that their base lines +are aligned. + + \begin{tikzpicture}[node distance=1ex] + \draw[help lines] (0,0) grid (3,1); + \huge + \node (X) at (0,1) {X}; + \node (a) [right=of X] {a}; + \node (y) [right=of a] {y}; + + \node (X) at (0,0) {X}; + \node (a) [base right=of X] {a}; + \node (y) [base right=of a] {y}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/base:left", + meta = "⟨specification⟩" + }, + ["base right"] = { + details = [[ +Works like `base left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/base:right", + meta = "⟨specification⟩" + }, + baseline = { + details = [[ +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);`, PGF will find out that the 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: \[PICTURE\]. + +Using this option, you can specify that the picture should be raised or +lowered such that the height ⟨dimension⟩ is on the baseline. For +example, `\tikz[baseline=0pt]\draw(0,0)circle(.5ex);` yields \[PICTURE\] +since, now, the baseline is on the height of the $x$-axis. + +This options is often useful for "inlined" graphics as in + + $A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$ + +Instead of a ⟨dimension⟩ you can also provide a coordinate in +parentheses. Then the effect is to put the baseline on the +$y$-coordinate that the given ⟨coordinate⟩ has *at the end of the +picture*. This means that, at the end of the picture, the ⟨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 baseline of nodes. + + Hello + \tikz[baseline=(X.base)] + \node [cross out,draw] (X) {world.}; + + Top align: + \tikz[baseline=(current bounding box.north)] + \draw (0,0) rectangle (1cm,1ex); + +Use `baseline=default` to reset the `baseline` option to its initial +configuration. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/baseline", + meta = "⟨dimension or coordinate or default⟩" + }, + ["behind path"] = { + details = [[ +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, TikZ 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 another, 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). + + \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}; + +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 `backgrounds` +library in Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/behind:path" + }, + below = { + details = [[ +This key is redefined in the same manner as `above`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below", + meta = "⟨specification⟩" + }, + ["below delimiter"] = { + details = [[ +Works as above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:delimiter", + meta = "⟨delimiter⟩" + }, + ["below left"] = { + details = [[ +Similar to `above left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:left" + }, + ["below left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:left:of", + meta = "⟨node⟩" + }, + ["below of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:of", + meta = "⟨node⟩" + }, + ["below right"] = { + details = [[ +Similar to `above left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:right" + }, + ["below right of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/below:right:of", + meta = "⟨node⟩" + }, + bend = { + details = [[ +Has the same effect as saying `bend`⟨coordinate⟩ outside the ⟨options⟩. +The option specifies that the bend of the parabola should be at the +given ⟨coordinate⟩. You have to take care yourself that the bend +position is a "valid" position; which means that if there is no parabola +of the form $f(x) = a x^2 + b x + c$ that goes through the old current +point, the given bend, and the new current point, the result will not be +a parabola. + +There is one special property of the ⟨coordinate⟩: When a relative +coordinate is given like `+(0,0)`, the position relative 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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend", + meta = "⟨coordinate⟩" + }, + ["bend angle"] = { + details = [[ +Sets the angle to be used by the `bend left` or `bend right`, but +without actually selecting the `curve to` or the `relative` option. This +is useful for globally specifying a `bend angle` for a whole picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:angle", + meta = "⟨angle⟩" + }, + ["bend at end"] = { + details = [[ +This places the bend at the end of a parabola. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:at:end" + }, + ["bend at start"] = { + details = [[ +This places the bend at the start of a parabola. It is a shortcut for +the following options: `bend pos=0,bend={+(0,0)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:at:start" + }, + ["bend left"] = { + details = [[ +This option sets `out=`⟨angle⟩`,in=`$180-⟨angle⟩$`,relative`. If no +⟨angle⟩ is given, the last given `bend left` or `bend right` angle is +used. + + \begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid] + \node[state,initial] (q_0) {$q_0$}; + \node[state] (q_1) [right=of q_0] {$q_1$}; + \node[state,accepting](q_2) [right=of q_1] {$q_2$}; + + \path[->] (q_0) edge node [above] {0} (q_1) + edge [loop above] node {1} () + edge [bend left] node [above] {1} (q_2) + edge [bend right] node [below] {0} (q_2) + (q_1) edge node [above] {1} (q_2); + \end{tikzpicture} + + \begin{tikzpicture} + \foreach \angle in {0,45,...,315} + \node[rectangle,draw=black!50] (\angle) at (\angle:2) {\angle}; + + \foreach \from/\to in {0/45,45/90,90/135,135/180, + 180/225,225/270,270/315,315/0} + \path (\from) edge [->,bend right=22,looseness=0.8] (\to) + edge [<-,bend left=22,looseness=0.8] (\to); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:left", + meta = "⟨angle⟩" + }, + ["bend pos"] = { + details = [[ +Specifies where the "previous" point is relative to which the bend is +calculated. The previous point will be at the ⟨fraction⟩th part of the +line from the old current point to the new current point. + +The idea is the following: If you say `bend pos=0` and `bend +(0,0)`, +the bend will be at the old current point. If you say `bend pos=1` and +`bend +(0,0)`, the bend will be at the new current point. If you say +`bend pos=0.5` and `bend +(0,2cm)` the bend will be 2cm above the middle +of the line between the start and end point. This is most useful in +situations such as the following: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0); + \end{tikzpicture} + +In the above example, the `bend +(0,2)` essentially means "a parabola +that is 2cm high" and `+(3,0)` means "and 3cm wide". Since this +situation arises often, there is a special shortcut option: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:pos", + meta = "⟨fraction⟩" + }, + ["bend right"] = { + details = [[ +Works like the `bend left` option, only the bend is to the other side. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bend:right", + meta = "⟨angle⟩" + }, + ["blend group"] = { + details = [[ +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 ⟨mode⟩. + + \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); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/blend:group", + meta = "⟨mode⟩" + }, + ["blend mode"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/blend:mode", + meta = "⟨mode⟩" + }, + ["bottom color"] = { + details = [[ +This option works like `top color`, only for the bottom color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/bottom:color", + meta = "⟨color⟩" + }, + ["callout absolute pointer"] = { + details = [[ +The TikZ version of the `callout absolute pointer` key. Here, +⟨coordinate⟩ can be specified using the TikZ format for coordinates. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/callout:absolute:pointer", + meta = "⟨coordinate⟩" + }, + ["callout relative pointer"] = { + details = [[ +The TikZ version of the `callout relative pointer` key. Here, +⟨coordinate⟩ can be specified using the TikZ format for coordinates. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/callout:relative:pointer", + meta = "⟨coordinate⟩" + }, + ["canvas is plane"] = { + details = [[ +Perform the transformation into the new canvas plane using the units +above. Note that you have to set the units *before* calling +`canvas is plane`. + + \begin{tikzpicture}[ + ->, + plane x={(0.707,-0.707)}, + plane y={(0.707,0.707)}, + canvas is plane, + ] + \draw (0,0) -- (1,0); + \draw (0,0) -- (0,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:plane" + }, + ["canvas is xy plane at z"] = { + details = [[ +A plane with + +- `plane origin={(0,0,`⟨dimension⟩`)}`, + +- `plane x={(1,0,`⟨dimension⟩`)}`, and + +- `plane y={(0,1,`⟨dimension⟩`)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:xy:plane:at:z", + meta = "⟨dimension⟩" + }, + ["canvas is xz plane at y"] = { + details = [[ +A plane with + +- `plane origin={(0,`⟨dimension⟩`,0)}`, + +- `plane x={(1,`⟨dimension⟩`,0)}`, and + +- `plane y={(0,`⟨dimension⟩`,1)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:xz:plane:at:y", + meta = "⟨dimension⟩" + }, + ["canvas is yx plane at z"] = { + details = [[ +A plane with + +- `plane origin={(0,0,`⟨dimension⟩`)}`, + +- `plane x={(0,1,`⟨dimension⟩`)}`, and + +- `plane y={(1,0,`⟨dimension⟩`)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:yx:plane:at:z", + meta = "⟨dimension⟩" + }, + ["canvas is yz plane at x"] = { + details = [[ +A plane with + +- `plane origin={(`⟨dimension⟩`,0,0)}`, + +- `plane x={(`⟨dimension⟩`,1,0)}`, and + +- `plane y={(`⟨dimension⟩`,0,1)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:yz:plane:at:x", + meta = "⟨dimension⟩" + }, + ["canvas is zx plane at y"] = { + details = [[ +A plane with + +- `plane origin={(0,`⟨dimension⟩`,0)}`, + +- `plane x={(0,`⟨dimension⟩`,1)}`, and + +- `plane y={(1,`⟨dimension⟩`,0)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:zx:plane:at:y", + meta = "⟨dimension⟩" + }, + ["canvas is zy plane at x"] = { + details = [[ +A plane with + +- `plane origin={(`⟨dimension⟩`,0,0)}`, + +- `plane x={(`⟨dimension⟩`,0,1)}`, and + +- `plane y={(`⟨dimension⟩`,1,0)}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/canvas:is:zy:plane:at:x", + meta = "⟨dimension⟩" + }, + cells = { + details = [[ +This key adds the ⟨options⟩ to the style `every cell`. It is mainly just +a shorthand for the code `every cell/.append style=`⟨options⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cells", + meta = "⟨options⟩" + }, + centered = { + details = [[ +A shorthand for `anchor=center`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/centered" + }, + ["chain default direction"] = { + details = [[ +This ⟨direction⟩ is used in a `chain` option, if no other ⟨direction⟩ is +specified. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/chain:default:direction", + meta = "⟨direction⟩" + }, + ["child anchor"] = { + details = [[ +Specifies the anchor where the edge from parent meets the child node by +setting the macro `\tikzchildanchor` to `.`⟨anchor⟩. + +If you specify `border` as the ⟨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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/child:anchor", + meta = "⟨anchor⟩" + }, + ["children are tokens"] = { + details = [[ +The idea behind this style is to use trees mechanism for placing tokens. +Every token lying on a place is treated as a child of the node. Normally +this would have the effect that the tokens are placed below the place +and they would be connected to the place by an edge. The +`children are tokens` style, however, redefines the growth function of +trees such that it places the children next to each other inside (or, +rather, on top) of the place node. Additionally, the edge from the +parent node is not drawn. + + \begin{tikzpicture} + \node[place,label=above:$p_1$] {} + [children are tokens] + child {node [token] {1}} + child {node [token] {2}} + child {node [token] {3}}; + \end{tikzpicture} + +In detail, what happens is the following: Tree growth functions tell +TikZ where it should place the children of nodes. These functions get +passed the number of children that a node has an the number of the child +that should be placed. The special tree growth function for tokens has a +special mapping for each possible number of children up to nine +children. This mapping decides for each child where it should be placed +on top of the place. For example, a single child is placed directly on +top of the place. Two children are placed next to each other, separated +by the `token distance`. Three children are placed in a triangle whose +side lengths are `token distance`; and so on up to nine tokens. If you +wish to place more than nice tokens on a place, you will have to write +your own placement code. + + \begin{tikzpicture} + \node[place,label=above:$p_2$] {} + [children are tokens] + child {node [token] {1}} + child {node [token,fill=red] {2}} + child {node [token,fill=red] {2}} + child {node [token] {1}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/children:are:tokens" + }, + ["circle connection bar"] = { + details = [[ +This style installs a rather involved to-path. Unlike normal to-paths, +this path requires that the start and the target of the to-path are +named nodes of shape `circle` -- if this is not the case, this path will +produce errors. + +Assuming that the start and the target are circles, the to-path will +first compute the radii of these circles (by measuring the distance from +the `center` anchor to some anchor on the border) and will set the +`start circle` keys accordingly. Next, the `fill` option is set to the +`concept color` while `draw=none` is set. The decoration is set to +`circle connection bar`. Finally, the following style is included: + + \begin{tikzpicture}[concept color=blue!50,blue!50,outer sep=0pt] + \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick] {}; + \node (n2) at (2.5,0) [circle,minimum size=1cm,fill,draw,thick] {}; + + \path (n1) to[circle connection bar] (n2); + \end{tikzpicture} + +Note that it is not a good idea to have more than one `to` operation +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circle:connection:bar" + }, + ["circle connection bar switch color"] = { + details = [[ +This style works similarly to the `circle connection bar`. The only +difference is that instead of filling the path with a single color a +shading is used. + + \begin{tikzpicture}[outer sep=0pt] + \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick,red] {}; + \node (n2) at (30:2.5) [circle,minimum size=1cm,fill,draw,thick,blue] {}; + + \path (n1) to[circle connection bar switch color=from (red) to (blue)] (n2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circle:connection:bar:switch:color", + meta = "from (⟨first color⟩) to (⟨second color⟩)" + }, + ["circle through"] = { + details = [[ +When this key is given as an option to a node, the following happens: + +1. The `inner sep` and the `outer sep` are set to zero. + +2. The shape is set to `circle`. + +3. The `minimum size` is set such that the circle around the center of + the node (which is specified using `at`), goes through ⟨coordinate⟩. + +  + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \node (a) at (2,1.5) {$a$}; + \node [draw] at (1,1) [circle through={(a)}] {$c$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circle:through", + meta = "⟨coordinate⟩" + }, + ["circuit declare annotation"] = { + details = [[ +This key is used to declare an annotation named ⟨name⟩. Once declared, +it can be used as an argument of a symbol and will add the drawing in +⟨path⟩ to the symbol. In detail, the following happens: + +**The Main Keys.** Two keys called ⟨name⟩ and ⟨name⟩`’` are defined. The +second causes the annotation to be "mirrored and placed on the other +side" of the symbol. Both of these keys may also take further keys as +parameter like `info` keys. Whenever the ⟨name⟩ key is used, a local +scope is opened and in this scope the following things are done: + +1. The style `every` ⟨name⟩ is executed. + +2. The following style is executed and then `arrows=->`: + +3. The coordinate system is shifted such that the origin is at the + north anchor of the symbol. (For the ⟨name⟩`’` key the coordinate + system is flipped and shifted such that the origin is at the south + anchor of the symbol.) + +4. The `label distance` is locally set to ⟨distance⟩. + +5. The parameter options given to the ⟨name⟩ key are executed. + +6. The ⟨path⟩ is executed. + +**Usage.** What all of the above amounts to is best explained by an +example. Suppose we wish to create an annotation that looks like a +little circular arrow (like \[PICTURE\]). We could then say: + + \tikzset{circuit declare annotation= + {circular annotation} + {9pt} + {(0pt,8pt) arc (-270:80:3.5pt)} + } + +We can then use it like this: + + \tikz[circuit ee IEC] + \draw (0,0) to [resistor={circular annotation}] (3,0); + +Well, not very impressive since we do not see anything. This is due to +the fact that the ⟨path⟩ becomes part of a path that contains the symbol +node an nothing else. This path is not drawn or filled, so we do not see +anything. What we must do is to use an `edge` path operation: + + \tikzset{circuit declare annotation={circular annotation}{9pt} + {(0pt,8pt) edge[to path={arc(-270:80:3.5pt)}] ()} + } + \tikz[circuit ee IEC] + \draw (0,0) to [resistor={circular annotation}] (3,0) + to [capacitor={circular annotation'}] (3,2); + +The ⟨distance⟩ is important for the correct placement of additional +`info` labels. When an annotation is present, the info labels may need +to be moved further away from the symbol, but not always. For this +reason, an annotation defines an additional ⟨distance⟩ that is applied +to all info labels given as parameters to the annotation. Here is an +example, that shows the difference: + + \tikz[circuit ee IEC] + \draw (0,0) to [resistor={circular annotation,ohm=5}] (2,0) + to [resistor={circular annotation={ohm=5}}] (4,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:declare:annotation", + meta = "{name}{distance}{path}" + }, + ["circuit declare symbol"] = { + details = [[ +This key is used to declare a symbol. It does not cause this symbol to +be shown nor does it set a graphic to be used for the symbol, it simply +"prepares" several keys that can later be used to draw a symbol and to +configure it. + +In detail, the first key that is defined is just called ⟨name⟩. This key +should be given as an option to a `node` or on a `to` path, as explained +below. The key will take options, which can be used to influence the way +the symbol graphic is rendered. + +Let us have a look at an example. Suppose we want to define a symbol +called `foo`, which just looks like a simple rectangle. We could then +say + + \tikzset{circuit declare symbol=foo} + +The symbol could now be used like this: + + \node [foo] at (1,1) {}; + \node [foo={red}] at (2,1) {}; + +However, in the above example we would not actually see anything 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` ⟨name⟩ +`graphic`. This key gets graphic options as parameter that will be set +when a symbol `foo` should be shown: + + \begin{tikzpicture} + [circuit declare symbol=foo, + set foo graphic={draw,shape=rectangle,minimum size=5mm}] + + \node [foo] at (1,1) {}; + \node [foo={red}] at (2,1) {}; + \end{tikzpicture} + +In detail, when you use the key ⟨name⟩=⟨options⟩ with a node, the +following happens: + +1. The `inner sep` is set to `0.5pt`. + +2. The following style is executed: + +3. The graphic options that have been set using `set` ⟨name⟩ `graphic` + are set. + +4. The style `every `⟨name⟩ is executed. You can use it to configure + the symbol further. + +5. The ⟨options⟩ are executed. + +The key ⟨name⟩ will have a different effect when it is used on a `to` +path command inside a `circuit` environment (the `circuit` environment +sets up `to` paths in such a way that the use of a key declared using +`circuit declare symbol` is automatically detected). When ⟨name⟩ is used +on a `to` path, the above actions also happen (setting the inner +separation, using the symbol graphic, and so on), but they are passed to +the key `circuit handle symbol`, which is explained next. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:declare:symbol", + meta = "⟨name⟩" + }, + ["circuit declare unit"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:declare:unit", + meta = "{name}{unit}" + }, + ["circuit ee"] = { + details = [[ +This style calls the keys `circuit` (which internally calls +`every circuit` and the following style: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:ee" + }, + ["circuit ee IEC"] = { + details = [[ +This style calls `circuit ee` and installs the IEC-like graphics for the +logical symbols like `resistor`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:ee:IEC" + }, + ["circuit handle symbol"] = { + details = [[ +This key is mostly used internally. Its purpose is to render a symbol. +The effect of this key differs, depending on whether it is used as the +optional argument of a `to` path command or elsewhere. + +If the key is not used as an argument of a `to` path command, the +⟨options⟩ are simply executed. + +The more interesting case happens when the key is given on a `to` path +command. In this case, several things happen: + +1. The `to` path is locally changed and set to an internal path (which + you should not try to change) that consists mostly of a single + straight line. + +2. The ⟨options⟩ are tentatively executed with filtering switched on. + Everything is filtered out, except for the key `pos` and also the + styles `at start`, `very near start`, `near start`, `midway`, + `near end`, `very near end`, and `at end`. If none of them is found, + `midway` is used. + +3. The filtered option is used to determine a position for the symbol + on the path. At the given position (with `pos=0` representing the + start and `pos=1` representing the end), a node will be added to the + path (in a manner to be described presently). + +4. This node gets ⟨options⟩ as its option list. + +5. The node is added by virtue of a special `markings` decoration. This + means that a `mark` command is executed that causes the node to be + placed as a mark on the path. + +6. The marking decoration will automatically subdivide the path 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 path. + +7. The marking decoration will also take care of the case that multiple + marks are present on a path, in this case the lines from and to the + borders of the nodes are only between consecutive nodes. + +8. The marking decoration will also rotate the coordinate system in + such a way that the $x$-axis points along the path. Thus, if you use + the `transform shape` option, the node will "point along" the path. + +9. In case a node is at `pos=0` or at `pos=1` some special code will + suppress the superfluous lines to the start or end of the path. + +The net effect of all of the above is that a node will be placed "on the +path" and the path will have a "gap" just large enough to encompass the +node. Another effect is that you can use this key multiple times on a +path to add several node to a path, provided they do not overlap. + + \begin{tikzpicture}[circuit] + \draw (0,0) to [circuit handle symbol={draw,shape=rectangle,near start}, + circuit handle symbol={draw,shape=circle,near end}] (3,2); + \end{tikzpicture} + + \begin{tikzpicture}[transform shape,circuit] + \draw (0,0) to [circuit handle symbol={draw,shape=rectangle,at start}, + circuit handle symbol={draw,shape=circle,near end}] (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:handle:symbol", + meta = "⟨options⟩" + }, + ["circuit logic"] = { + details = [[ +This style calls the keys `circuit` (which internally calls +`every circuit`, then it defines the `inputs` key and it calls the +`every circuit logic` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:logic" + }, + ["circuit logic CDH"] = { + details = [[ +This key calls `circuit logic US` and installs the two special and- and +nand-gates, that is, it uses `set and gate graphic` with +`and gate CDH graphic` and likewise for nand-gates. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:logic:CDH" + }, + ["circuit logic IEC"] = { + details = [[ +This key calls `circuit logic` and installs the IEC-like graphics for +the logical symbols like `and gate`. + +As explained in Section ??, for each graphic symbol of the library there +is also a style that stores this particular appearance. These keys are +called `and gate IEC graphic`, `or gate IEC graphic`, and so on. + + \begin{tikzpicture}[circuit logic IEC, + every circuit symbol/.style={ + logic gate IEC symbol color=black, + fill=blue!20,draw=blue,very thick}] + \matrix[column sep=7mm] + { + \node (i0) {0}; & & \\ + & \node [and gate] (a1) {}; & \\ + \node (i1) {0}; & & \node [or gate] (o) {};\\ + & \node [nand gate] (a2) {}; & \\ + \node (i2) {1}; & & \\ + }; + \draw (i0.east) -- ++(right:3mm) |- (a1.input 1); + \draw (i1.east) -- ++(right:3mm) |- (a1.input 2); + \draw (i1.east) -- ++(right:3mm) |- (a2.input 1); + \draw (i2.east) -- ++(right:3mm) |- (a2.input 2); + \draw (a1.output) -- ++(right:3mm) |- (o.input 1); + \draw (a2.output) -- ++(right:3mm) |- (o.input 2); + \draw (o.output) -- ++(right:3mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:logic:IEC" + }, + ["circuit logic US"] = { + details = [[ +This style calls `circuit logic` and installs US-like graphics for the +logical symbols like `and gate`. For instance, it says + + set and gate graphic = and gate US graphic + +Here is an example: + + \begin{tikzpicture}[circuit logic CDH, + tiny circuit symbols, + every circuit symbol/.style={ + fill=white,draw}] + \matrix[column sep=7mm] + { + \node (i0) {0}; & & \\ + & \node [and gate] (a1) {}; & \\ + \node (i1) {0}; & & \node [or gate] (o) {};\\ + & \node [nand gate] (a2) {}; & \\ + \node (i2) {1}; & & \\ + }; + \draw (i0.east) -- ++(right:3mm) |- (a1.input 1); + \draw (i1.east) -- ++(right:3mm) |- (a1.input 2); + \draw (i1.east) -- ++(right:3mm) |- (a2.input 1); + \draw (i2.east) -- ++(right:3mm) |- (a2.input 2); + \draw (a1.output) -- ++(right:3mm) |- (o.input 1); + \draw (a2.output) -- ++(right:3mm) |- (o.input 2); + \draw (o.output) -- ++(right:3mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:logic:US" + }, + ["circuit symbol filled"] = { + details = [[ +This style is used with symbols that are completely filled. For +instance, the variant IEC version of an inductor is a filled, black +rectangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:filled" + }, + ["circuit symbol lines"] = { + details = [[ +This style is used with symbols that consist only of lines that do not +surround anything. Examples are a capacitor. + + \tikz [circuit ee IEC, + circuit symbol lines/.style={thick,draw=red}] + \draw (0,0) to [capacitor] ++(right:3) to [resistor] ++(up:2); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:lines" + }, + ["circuit symbol open"] = { + details = [[ +This style is used with symbols that consist of lines that surround some +area. For instance, the IEC version of a resistor is an open symbol. + + \tikz [circuit ee IEC, + circuit symbol open/.style={thick,draw,fill=yellow}] + \draw (0,0) to [inductor] ++(right:3) to [resistor] ++(up:2); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:open" + }, + ["circuit symbol size"] = { + details = [[ +This key sets `minimum height` to ⟨height⟩ times the current value of +the circuit symbol unit and the `minimum width` to ⟨width⟩ times this +value. Thus, this option can be used with a node command to set the size +of the node as a multiple of the circuit symbol unit. + + \begin{tikzpicture}[circuit ee IEC] + \draw (0,1) to [resistor] (2,1) to[inductor] (4,1); + + \begin{scope} + [every resistor/.style={circuit symbol size=width 3 height 1}] + \draw (0,0) to [resistor] (2,0) to[inductor] (4,0); + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:size", + meta = "width ⟨width⟩ height ⟨height⟩" + }, + ["circuit symbol unit"] = { + details = [[ +This dimension is a "unit" for the size of symbols. The libraries +generally define the sizes of symbols relative to this dimension. For +instance, the longer side of an inductor is, by default, in the IEC +library equal to five times this ⟨dimension⟩. When you change this +⟨dimension⟩, the size of all symbols will automatically change +accordingly. + +Note, that it is still possible to overwrite the size of any particular +symbol. These settings apply only to the default sizes. + + \begin{tikzpicture}[circuit ee IEC] + \draw (0,1) to [resistor] (3.5,1); + \draw[circuit symbol unit=14pt] + (0,0) to [resistor] (3.5,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:unit", + meta = "⟨dimension⟩" + }, + ["circuit symbol wires"] = { + details = [[ +This style is used for symbols that consist only of "wires". The +difference to the previous style is that a symbol consisting of wires +will look strange when the lines are thicker than the lines of normal +wires, while for symbols consisting of lines (but not wires) it may look +nice to make them thicker. An example is the `make contact` symbol. + +Compare + + \tikz [circuit ee IEC,circuit symbol lines/.style={draw,very thick}] + \draw (0,0) to [capacitor={near start}, + make contact={near end}] (3,0); + +to + + \tikz [circuit ee IEC,circuit symbol wires/.style={draw,very thick}] + \draw (0,0) to [capacitor={near start}, + make contact={near end}] (3,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuit:symbol:wires" + }, + circuits = { + details = [[ +This key should be passed as an option to a picture or a scope that +contains a circuit. It will do some internal setups. This key is +normally called by more specialized keys like `circuit ee IEC`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circuits" + }, + ["circular drop shadow"] = { + details = [[ +This shadow works like a drop shadow, only it adds a circular fading to +the shadow. This means that the shadow will fade out at the border. The +following options are preset for this shadow: + + shadow scale=1.1, shadow xshift=.3ex, shadow yshift=-.3ex, + fill=black, path fading={circle with fuzzy edge 15 percent}, + every shadow, + + \begin{tikzpicture} + \foreach \i in {1,...,8} + \node[circle,circular drop shadow,draw=blue,fill=blue!20,thick] + at (\i*45:1) {Circle \i}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circular:drop:shadow", + meta = "⟨shadow options⟩" + }, + ["circular glow"] = { + details = [[ +This shadow works much like the `circular shadow`, only it is not +shifted. This creates a visual effect of a "glow" behind the circle. The +following options are preset for this shadow: + + shadow scale=1.25, shadow xshift=0pt, shadow yshift=0pt, + fill=black, path fading={circle with fuzzy edge 15 percent}, + every shadow, + + \begin{tikzpicture} + \foreach \i in {1,...,8} + \node[circle,circular glow,fill=red!20,draw=red,thick] + at (\i*45:1) {Circle \i}; + \end{tikzpicture} + + \begin{tikzpicture} + \foreach \i in {1,...,8} + \node[circle,circular glow={fill=white},fill=red!20,draw=red,thick] + at (\i*45:1) {Circle \i}; + \end{tikzpicture} + + \begin{tikzpicture} + \foreach \i in {1,...,8} + \node[circle,circular glow={fill=green},fill=black,text=green!50!black] + at (\i*45:1) {Circle \i}; + \end{tikzpicture} + +An especially interesting effect can be achieved by only using the glow +and not filling the path: + + \begin{tikzpicture} + \foreach \i in {1,...,8} + \node[circle,circular glow={fill=red!\i0}] + at (\i*45:1) {Circle \i}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/circular:glow", + meta = "⟨shadow options⟩" + }, + clip = { + details = [[ +This option causes all subsequent drawings to be clipped against the +current path and the size of subsequent paths will not be important for +the picture size. If you clip against a self-intersecting path, the +even-odd rule or the nonzero winding number rule is used to determine +whether a point is inside or outside the clipping region. + +The clipping path is a graphic state parameter, so it will be reset at +the end of the current scope. Multiple clippings accumulate, that is, +clipping is always done against the intersection of all clipping areas +that have been specified inside the current scopes. The only way of +enlarging the clipping area is to end a `{scope}`. + + \begin{tikzpicture} + \draw[clip] (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); + \end{tikzpicture} + +It is usually a *very* good idea to apply the `clip` option only to the +first path command in a scope. + +If you "only wish to clip" and do not wish to draw anything, you can use +the `\clip` command, which is a shorthand for `\path[clip]`. + + \begin{tikzpicture} + \clip (0,0) circle (1cm); + \fill[red] (1,0) circle (1cm); + \end{tikzpicture} + +To keep clipping local, use `{scope}` environments as in the following +example: + + \begin{tikzpicture} + \draw (0,0) -- ( 0:1cm); + \draw (0,0) -- (10:1cm); + \draw (0,0) -- (20:1cm); + \draw (0,0) -- (30:1cm); + \begin{scope}[fill=red] + \fill[clip] (0.2,0.2) rectangle (0.5,0.5); + + \draw (0,0) -- (40:1cm); + \draw (0,0) -- (50:1cm); + \draw (0,0) -- (60:1cm); + \end{scope} + \draw (0,0) -- (70:1cm); + \draw (0,0) -- (80:1cm); + \draw (0,0) -- (90:1cm); + \end{tikzpicture} + +There is a slightly annoying catch: You cannot specify certain graphic +options for the command used for clipping. For example, in the above +code we could not have moved the `fill=red` to the `\fill` command. The +reasons for this have to do with the internals of the PDF specification. +You do not want to know the details. It is best simply not to specify +any options for these commands. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/clip" + }, + ["clockwise from"] = { + details = [[ +This option also causes children to be arranged on a circle. However, +the rule for placing children is simpler than with the `grow cyclic` +style: The first child is placed at ⟨angle⟩ at a distance of +`\tikzleveldistance`. The second child is placed at the same distance +from the parent, but at angle ⟨angle⟩${}-{}$`\tikzsiblingangle`. The +third child is displaced by another `\tikzsiblingangle` in a clockwise +fashion, and so on. + +Note that this function will not rotate the coordinate system. + + \begin{tikzpicture} + \node {root} + [clockwise from=30,sibling angle=30] + child {node {$30$}} + child {node {$0$}} + child {node {$-30$}} + child {node {$-60$}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/clockwise:from", + meta = "⟨angle⟩" + }, + cm = { + details = [[ +applies the following transformation to all coordinates: Let $(x,y)$ be +the coordinate to be transformed and let ⟨coordinate⟩ specify the point +$(t_x,t_y)$. Then the new coordinate is given by +$\left(\begin{smallmatrix} a & c \\ b & d\end{smallmatrix}\right) + \left(\begin{smallmatrix} x \\ y \end{smallmatrix}\right) + + \left(\begin{smallmatrix} t_x \\ t_y \end{smallmatrix}\right)$. +Usually, you do not use this option directly. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[cm={1,1,0,1,(0,0)},blue] (0,0) -- (1,1) -- (1,0); + \draw[cm={0,1,1,0,(1cm,1cm)},red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cm", + meta = "{⟨$a$⟩,⟨$b$⟩,⟨$c$⟩,⟨$d$⟩,⟨coordinate⟩}" + }, + color = { + details = [[ +This option sets the color that is used for fill, drawing, and text +inside the current scope. Any special settings for filling colors or +drawing colors are immediately "overruled" by this option. + +The ⟨color name⟩ is the name of a previously defined color. For +LaTeX users, this is just a normal "LaTeX-color" and the `xcolor` +extensions are allowed. Here is an example: + + \tikz \fill[color=red!20] (0,0) circle (1ex); + +It is possible to "leave out" the `color=` part and you can also write: + + \tikz \fill[red!20] (0,0) circle (1ex); + +What happens is that every option that TikZ does not know, like +`red!20`, gets a "second chance" as a color name. + +For plain TeX users, it is not so easy to specify colors since plain +TeX has no "standardized" color naming mechanism. Because of this, +PGF emulates the `xcolor` package, though the emulation is *extremely +basic* (more precisely, what I could hack together in two hours or so). +The emulation allows you to do the following: + +- Specify a new color using `\definecolor`. Only the color models + `gray`, `rgb`, and `RGB` are supported[1]. + `\definecolor{orange}{rgb}{1,0.5,0}` + +- Use `\colorlet` to define a new color based on an old one. Here, the + `!` mechanism is supported, though only "once" (use multiple + `\colorlet` for more fancy colors). `\colorlet{lightgray}{black!25}` + +- Use `\color``{color name}` to set the color in the current + TeX group. `\aftergroup`-hackery is used to restore the color after + the group. + +[1] ConTeXt users should be aware that `\definecolor` has a different +meaning in ConTeXt. There is a low-level equivalent named +`\pgfutil@definecolor` which can be used instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/color", + meta = "⟨color name⟩" + }, + ["colored tokens"] = { + details = [[ +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 as there are colors in this list, each filled +correspondingly. + + \tikz \node[place,colored tokens={black,black,red,blue}] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/colored:tokens", + meta = "⟨color list⟩" + }, + ["column sep"] = { + details = [[ +This option sets a default space that is added between every two +columns. This space can be positive or negative and is zero by default. +The ⟨spacing list⟩ normally contains a single dimension like `2pt`. + + \begin{tikzpicture} + \matrix [draw,column sep=1cm,nodes=draw] + { + \node(a) {123}; & \node (b) {1}; & \node {1}; \\ + \node {12}; & \node {12}; & \node {1}; \\ + \node(c) {1}; & \node (d) {123}; & \node {1}; \\ + }; + \draw [red,thick] (a.east) -- (a.east |- c) + (d.west) -- (d.west |- b); + \draw [<->,red,thick] (a.east) -- (d.west |- b) + node [above,midway] {1cm}; + \end{tikzpicture} + +More generally, the ⟨spacing list⟩ may contain a whole list of numbers, +separated by commas, and occurrences of the two key words +`between origins` and `between borders`. The effect of specifying such a +list is the following: First, all numbers occurring in the list are +simply added to compute the final spacing. Second, concerning the two +keywords, the last occurrence of one of the keywords is important. If +the last occurrence is `between borders` or if neither occurs, then the +space is inserted between the two columns normally. However, if the last +occurs is `between origins`, then the following happens: The distance +between the columns is adjusted such that the difference between the +origins of all the cells in the first column (remember that they all lie +on straight line) and the origins of all the cells in the second column +is exactly the given distance. + +*The* `between origins` *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.* + + \begin{tikzpicture} + \matrix [draw,column sep={1cm,between origins},nodes=draw] + { + \node(a) {123}; & \node (b) {1}; & \node {1}; \\ + \node {12}; & \node {12}; & \node {1}; \\ + \node {1}; & \node {123}; & \node {1}; \\ + }; + \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {1cm}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/column:sep", + meta = "⟨spacing list⟩" + }, + ["column ⟨number⟩"] = { + details = [[ +This style is used for every cell in column ⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/column:⟨number⟩" + }, + concept = { + details = [[ +This style should be used with all nodes that are concepts, although +some styles like `extra concept` install this style automatically. + +Basically, this style makes the concept node circular and installs a +uniform color called `concept color`, see below. Additionally, the style +`every concept` is called. + + \tikz[mindmap,concept color=red!50] \node [concept] {Some concept}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/concept" + }, + ["concept color"] = { + details = [[ +We saw already that this option is used to change the color of concepts. +We now have a look at its effect when used on child nodes of a concept. +Normally, this option simply changes the color of the children. However, +when the option is given as an option to the `child` operation (and not +to the `node` operation and also not as an option to all children via +the `level 1` style), TikZ will smoothly change the concept color from +the parent's color to the color of the child concept. + +Here is an example: + + \tikz[mindmap,concept color=blue!80] + \node [concept] {Root concept} + child[concept color=red,grow=30] {node[concept] {Child concept}} + child[concept color=orange,grow=0] {node[concept] {Child concept}}; + +In order to have a concept color which changes with the hierarchy level, +a tiny bit of magic is needed: + + \tikz[mindmap,text=white, + root concept/.style={concept color=blue}, + level 1 concept/.append style= + {every child/.style={concept color=blue!50}}] + \node [concept] {Root concept} + child[grow=30] {node[concept] {child}} + child[grow=0 ] {node[concept] {child}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/concept:color", + meta = "⟨color⟩" + }, + ["concept connection"] = { + details = [[ +This style can be used for lines between two concepts. Feel free to +redefine this style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/concept:connection" + }, + ["connect spies"] = { + details = [[ +Causes the spy-in and the spy-on nodes to be connected by a thin line. + + \begin{tikzpicture} + [spy using overlays={circle, magnification=3, size=1cm}] + + \draw [decoration=Koch curve type 2] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [green] on (1.6,0.1) in node at (3,1); + \spy [red,connect spies] on (0.5,0.4) in node at (1,1.5); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/connect:spies" + }, + ["const plot"] = { + details = [[ +This option causes the points on the path to be connected using +piecewise constant series of lines: + + \tikz\draw plot[const plot] file{plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/const:plot" + }, + ["const plot mark left"] = { + details = [[ +Just an alias for `/tikz/const plot`. + + \tikz\draw plot[const plot mark left,mark=*] file{plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/const:plot:mark:left" + }, + ["const plot mark mid"] = { + details = [[ +A variant of `/tikz/const plot` which places its mark in the middle of +the horizontal lines: + + \tikz\draw plot[const plot mark mid,mark=*] file{plots/pgfmanual-sine.table}; + +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"). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/const:plot:mark:mid" + }, + ["const plot mark right"] = { + details = [[ +A variant of `/tikz/const plot` which places its mark on the right ends: + + \tikz\draw plot[const plot mark right,mark=*] file{plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/const:plot:mark:right" + }, + ["continue branch"] = { + details = [[ +This option works like the `continue chain` option, only ⟨current +chain⟩`/`⟨branch name⟩ is used as the chain name, rather than just +⟨branch name⟩. + + \begin{tikzpicture}[every on chain/.style=join,every join/.style=->, + node distance=2mm and 1cm] + { [start chain=trunk] + \node [on chain] {A}; + \node [on chain] {B}; + { [start branch=numbers going below] } % just a declaration, + { [start branch=greek going above] } % we will come back later + \node [on chain] {C}; + + % Now come the branches... + { [continue branch=numbers] + \node [on chain] {1}; + \node [on chain] {2}; + } + { [continue branch=greek] + \node [on chain] {$\alpha$}; + \node [on chain] {$\beta$}; + } + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/continue:branch", + meta = "⟨branch name⟩⟨direction⟩" + }, + ["continue chain"] = { + details = [[ +This option allows you to (re)activate an existing chain and to possibly +change the default direction. If the `chain name` is missing, the name +of the innermost activated chain is used. If no chain is activated, +`chain` is used. + +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 being constructed. +For this, just give this option somewhere inside the scope of the chain. + + \begin{tikzpicture}[start chain=going right,node distance=5mm] + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,continue chain=going below,on chain] {,}; + \node [draw,on chain] {this}; + \node [draw,on chain] {is}; + \end{tikzpicture} + +The second application is to reactivate a chain after it "has already +been closed down". + + \begin{tikzpicture}[node distance=5mm, + every node/.style=draw] + { [start chain=1] + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; + } + + { [start chain=2 going below] + \node [on chain=2] at (0.5,-.5) {0}; + \node [on chain=2] {1}; + \node [on chain=2] {2}; + } + + { [continue chain=1] + \node [on chain] {D}; + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/continue:chain", + meta = "⟨chain name⟩⟨direction⟩" + }, + controls = { + details = [[ +This option causes the ⟨coordinate⟩s to be used as control points. + + \tikz \draw (0,0) to [controls=+(90:1) and +(90:1)] (3,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/controls", + meta = "⟨coordinate⟩ and ⟨coordinate⟩" + }, + ["copy shadow"] = { + details = [[ +This shadow installs the following default options: + + shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, every shadow + +Furthermore, the options `fill=`⟨fill color⟩ and `draw=`⟨draw color⟩ are +also set, where the ⟨fill color⟩ and ⟨draw color⟩ are the fill and draw +colors used for the main path. + + \begin{tikzpicture} + \node [copy shadow,fill=blue!20,draw=blue,thick] {Hello World!}; + + \node at (0,-1) [copy shadow={shadow xshift=1ex,shadow yshift=1ex}, + fill=blue!20,draw=blue,thick] + {Hello World!}; + + \node at (0,-2) [copy shadow={opacity=.5},tape, + fill=blue!20,draw=blue,thick] + {Hello World!}; + + % We have to repeat the left color since shadings are not + % automatically applied to shadows + \node at (0,-3) [copy shadow={left color=blue!50}, + left color=blue!50,draw=blue,thick] + {Hello World!}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/copy:shadow", + meta = "⟨shadow options⟩" + }, + ["counterclockwise from"] = { + details = [[ +Works the same way as `clockwise from`, but sibling angles are added +instead of subtracted. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/counterclockwise:from", + meta = "⟨angle⟩" + }, + ["cs/angle"] = { + details = [[ +Same as `longitude`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/angle", + meta = "⟨degrees⟩" + }, + ["cs/first line"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/first:line", + meta = "{(⟨first % coordinate⟩)--(⟨second coordinate⟩)}" + }, + ["cs/first node"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/first:node", + meta = "⟨node⟩" + }, + ["cs/horizontal line through"] = { + details = [[ +Specifies that one line is a horizontal line that goes through the given +coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/horizontal:line:through", + meta = "{(⟨coordinate⟩)}" + }, + ["cs/latitude"] = { + details = [[ +Angle of the coordinate between the $y$- and $z$-vector, measured from +the $y$-vector. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/latitude", + meta = "⟨degrees⟩" + }, + ["cs/longitude"] = { + details = [[ +Angle of the coordinate between the $x$- and $y$-vector, measured from +the $y$-vector. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/longitude", + meta = "⟨degrees⟩" + }, + ["cs/name"] = { + details = [[ +Specifies the node that you wish to use to specify a coordinate. The +⟨node name⟩ is the name that was previously used to name the node using +the `name=`⟨node name⟩ option or the special node name syntax. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/name", + meta = "⟨node name⟩" + }, + ["cs/node"] = { + details = [[ +This key specifies the node on whose border the tangent should lie. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/node", + meta = "⟨node⟩" + }, + ["cs/point"] = { + details = [[ +This key specifies the point through which the tangent should go. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/point", + meta = "⟨point⟩" + }, + ["cs/radius"] = { + details = [[ +Factor by which the $x$-, $y$-, and $z$-vector are multiplied. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/radius", + meta = "⟨number⟩" + }, + ["cs/second line"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/second:line", + meta = "{(⟨first % coordinate⟩)--(⟨second coordinate⟩)}" + }, + ["cs/second node"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/second:node", + meta = "⟨node⟩" + }, + ["cs/solution"] = { + details = [[ +Specifies which solution should be used if there are more than one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/solution", + meta = "⟨number⟩" + }, + ["cs/vertical line through"] = { + details = [[ +Specifies that the other line is vertical and goes through the given +coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/vertical:line:through", + meta = "{(⟨coordinate⟩)}" + }, + ["cs/x"] = { + details = [[ +The $x$ component of the coordinate. Should be given *without* unit. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/x", + meta = "⟨number⟩" + }, + ["cs/x radius"] = { + details = [[ +A specific factor by which only the $x$-vector is multiplied. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/x:radius", + meta = "⟨dimension⟩" + }, + ["cs/y"] = { + details = [[ +Distance by which the coordinate is above the origin. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/y", + meta = "⟨dimension⟩" + }, + ["cs/y radius"] = { + details = [[ +Works like `x radius`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/y:radius", + meta = "⟨dimension⟩" + }, + ["cs/z"] = { + details = [[ +Works like `x`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/cs/z", + meta = "⟨factor⟩" + }, + ["current point is local"] = { + details = [[ +Normally, the scope path operation has no effect on the current point. +That is, curly braces on a path have no effect on the current position: + + \begin{tikzpicture} + \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0); + \draw[red] (2,0) -- ++(1,0) { -- ++(0,1) } -- ++(-1,0); + \end{tikzpicture} + +If you set this key to `true`, this behavior changes. In this case, at +the end of a group created on a path, the last current position reverts +to whatever value it had at the beginning of the scope. More precisely, +when TikZ encounters `}` on a path, it checks whether at this particular +moment the key is set to `true`. If so, the current position reverts to +the value it had when the matching `{` was read. + + \begin{tikzpicture} + \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0); + \draw[red] (2,0) -- ++(1,0) + { [current point is local] -- ++(0,1) } -- ++(-1,0); + \end{tikzpicture} + +In the above example, we could also have given the option outside the +scope, for instance as a parameter to the whole scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/current:point:is:local", + meta = "⟨boolean⟩" + }, + ["curve to"] = { + details = [[ +Specifies that the `to path` should be a curve. This curve will leave +the start coordinate at a certain angle, which can be specified using +the `out` option. It reaches the target coordinate also at a certain +angle, which is specified using the `in` option. The control points of +the curve are at a certain distance that is computed in different ways, +depending on which options are set. + +All of the following options implicitly cause the `curve to` style to be +installed. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/curve:to" + }, + dash = { + details = [[ +Sets the dashing pattern and phase at the same time. + + \begin{tikzpicture} + \draw [dash=on 20pt off 10pt phase 0pt] (0pt,3pt) -- (3.5cm,3pt); + \draw [dash=on 20pt off 10pt phase 10pt] (0pt,0pt) -- (3.5cm,0pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash", + meta = "⟨dash pattern⟩phase⟨dash phase⟩" + }, + ["dash dot"] = { + details = [[ +Shorthand for setting a dashed and dotted dash pattern. + + \tikz \draw[dash dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash:dot" + }, + ["dash dot dot"] = { + details = [[ +Shorthand for setting a dashed and dotted dash pattern with more dots. + + \tikz \draw[dash dot dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash:dot:dot" + }, + ["dash expand off"] = { + details = [[ +Makes the `off` part of a dash pattern expandable such that it can +stretch. This only works when there is a single `on` and a single `off` +field and requires the `decorations` library. Right now this option has +to be specified on the path where it is supposed to take effect after +the `dash pattern` option because the dash pattern has to be known at +the point where it is applied. + + \begin{tikzpicture}[|-|, dash pattern=on 4pt off 2pt] + \draw [dash expand off] (0pt,30pt) -- (26pt,30pt); + \draw [dash expand off] (0pt,20pt) -- (24pt,20pt); + \draw [dash expand off] (0pt,10pt) -- (22pt,10pt); + \draw [dash expand off] (0pt, 0pt) -- (20pt, 0pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash:expand:off" + }, + ["dash pattern"] = { + details = [[ +Sets the dashing pattern. The syntax is the same as in METAFONT. For +example following pattern `on 2pt off 3pt on 4pt off 4pt` means "draw +2pt, then leave out 3pt, then draw 4pt once more, then leave out 4pt +again, repeat". + + \begin{tikzpicture}[dash pattern=on 2pt off 3pt on 4pt off 4pt] + \draw (0pt,0pt) -- (3.5cm,0pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash:pattern", + meta = "⟨dash pattern⟩" + }, + ["dash phase"] = { + details = [[ +Shifts the start of the dash pattern by ⟨phase⟩. + + \begin{tikzpicture}[dash pattern=on 20pt off 10pt] + \draw[dash phase=0pt] (0pt,3pt) -- (3.5cm,3pt); + \draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dash:phase", + meta = "⟨dash phase⟩" + }, + dashed = { + details = [[ +Shorthand for setting a dashed dash pattern. + + \tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dashed" + }, + ["data visualizers/visualize as line"] = { + details = [[ +Creates a new visualizer named ⟨visualizer name⟩. Basically, this +visualizer connects all data points for which the `/data point/set` +attribute equals ⟨visualizer name⟩ by a line that is styled by the +visualizer's style. + +In more detail, the following happens: + +1. 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 ⟨visualizer name⟩. + +2. During the end of the data visualization, PGF's plotting mechanism + (see Section ??) is used to plot the stream of recorded data points. + + This means that, in principle, all of the plot handlers available in + TikZ 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. + +3. Additionally, plot marks can be drawn at the collected data points. + Here, all of the options available to TikZ for drawing plot marks + are available. To configure them, all options offered by TikZ for + configuring marks are available such as `mark repeat`: + + \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); + }; + +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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualizers/visualize:as:line", + meta = "⟨visualizer name⟩" + }, + ["data visualizers/visualize as scatter"] = { + details = [[ +A shorthand `visualize as line=`⟨visualizer name⟩ followed ⟨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. + + \tikz \datavisualization + [scientific axes=clean, + visualize as scatter] + data [format=function] { + var x : interval [0:pi] samples 10; + func y = sin(\value x r); + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualizers/visualize:as:scatter", + meta = "⟨visualizer name⟩" + }, + ["data visualizers/visualize as smooth line"] = { + details = [[ +A shorthand `visualize as line=`⟨visualizer name⟩ followed ⟨visualizer +name⟩`=smooth line`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/data:visualizers/visualize:as:smooth:line", + meta = "⟨visualizer name⟩" + }, + dates = { + details = [[ +This option specifies the date range. Both the start and end date are +specified and described on page ??. In short: You can provide ISO-format +type dates like `2006-01-02`, you can replace the day of month by `last` +to refer to the last day of a month (so `2006-02-last` is the same as +`2006-02-28`), and you can add a plus sign followed by a number to +specify an offset (so `2006-01-01+-1` is the same as `2005-12-31`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dates", + meta = "⟨start date⟩ to ⟨end date⟩" + }, + ["day code"] = { + details = [[ +This option allows you to change the code that is executed for each day. +The default is to create a node with an appropriate name, but you can +change this: + + \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list, + day code={\fill[blue] (0,0) circle (2pt);}]; + +The default code is the following: + + \node[name=\pgfcalendarsuggestedname,every day]{\tikzdaytext}; + +The first part causes the day nodes to be accessible via the following +names: If ⟨name⟩ is the name given to the calendar via a `name=` option +or via the specification element `(`⟨name⟩`)`, then +`\pgfcalendarsuggestedname` will expand to ⟨name⟩`-`⟨date⟩, where ⟨date⟩ +is the date of the day that is currently being processed in ISO format. + +For example, if January 1, 2006 is being processed and the calendar has +been named `mycal`, then the node containing the `1` for this date will +be names `mycal-2006-01-01`. You can later reference this node. + + \begin{tikzpicture} + \calendar (mycal) [dates=2000-01-01 to 2000-01-31,week list]; + + \draw[red] (mycal-2000-01-20) circle (4pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:code", + meta = "⟨code⟩" + }, + ["day list downward"] = { + details = [[ +This style causes the days of a month to be typeset one below the other. +The shift between days is given by `day yshift`. Between month an +additional shift of `month yshift` is added. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list downward,month yshift=1em]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:list:downward" + }, + ["day list left"] = { + details = [[ +As above, but the list grows left. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:list:left" + }, + ["day list right"] = { + details = [[ +This style also works as before, but the list of days grows to the +right. Instead of `day yshift` and `month yshift`, the values of +`day xshift` and `month xshift` are used. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list right,month xshift=1em]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:list:right" + }, + ["day list upward"] = { + details = [[ +Works as above, only the list grows upward instead of downward. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list upward,month yshift=1em]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:list:upward" + }, + ["day text"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:text", + meta = "⟨text⟩" + }, + ["day xshift"] = { + details = [[ +Specifies the horizontal shift between days. This is not the gap between +days, but the shift between the anchors of their nodes. + + \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day xshift=3ex]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:xshift", + meta = "⟨dimension⟩" + }, + ["day yshift"] = { + details = [[ +Specifies the vertical shift between days. Again, this is the shift +between the anchors of their nodes. + + \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day yshift=2ex]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/day:yshift", + meta = "⟨dimension⟩" + }, + decorate = { + details = [[ +When this key is set, the whole path is decorated after it has been +finished. The decoration used for decorating the path is set via the +`decoration` way, in exactly the same way as for the `decorate` path +command. Indeed, the following two commands have the same effect: + +1. `\path decorate[`⟨options⟩`] {`⟨path⟩`};` + +2. `\path [decorate,`⟨options⟩`] `⟨path⟩`;` + +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 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). + + \begin{tikzpicture}[decoration=zigzag] + \draw [help lines] (0,0) grid (3,5); + + \draw [fill=blue!20,decorate] (1.5,4) circle (1cm); + + \node at (1.5,2.5) [fill=red!20,decorate,ellipse] {Ellipse}; + + \node at (1.5,1) [inner sep=6mm,fill=red!20,decorate,ellipse,decoration= + {text along path,text={This is getting silly}}] {Ellipse}; + \end{tikzpicture} + +In the last example, the `text along path` decoration removes the path. +In such cases it is useful to use a pre- or postaction to cause the +decoration to be applied only before or after the main path has been +used. Incidentally, this is another application of the `decorate` option +that you cannot achieve with the decorate path command. + + \begin{tikzpicture}[decoration=zigzag] + \node at (1.5,1) [inner sep=6mm,fill=red!20,ellipse, + postaction={decorate,decoration= + {text along path,text={This is getting silly}}}] {Ellipse}; + \end{tikzpicture} + +Here is more useful example, where a postaction is used to add the path +after the main path has been drawn. + + \begin{tikzpicture} + \draw [help lines] grid (3,2); + \fill [draw=red,fill=red!20, + postaction={decorate,decoration={raise=2pt,text along path, + text=around and around and around and around we go}}] + (0,1) arc (180:-180:1.5cm and 1cm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/decorate", + meta = "⟨boolean⟩" + }, + ["delta angle"] = { + details = [[ +Sets the delta angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/delta:angle", + meta = "⟨degrees⟩" + }, + ["densely dash dot"] = { + details = [[ +Shorthand for setting a densely dashed and dotted dash pattern. + + \tikz \draw[densely dash dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/densely:dash:dot" + }, + ["densely dash dot dot"] = { + details = [[ +Shorthand for setting a densely dashed and dotted dash pattern with more +dots. + + \tikz \draw[densely dash dot dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/densely:dash:dot:dot" + }, + ["densely dashed"] = { + details = [[ +Shorthand for setting a densely dashed dash pattern. + + \tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/densely:dashed" + }, + ["densely dotted"] = { + details = [[ +Shorthand for setting a densely dotted dash pattern. + + \tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/densely:dotted" + }, + distance = { + details = [[ +Set the minimum and maximum distance to the same value ⟨distance⟩. Note +that this causes any computed distance $d$ to be ignored and ⟨distance⟩ +to be used instead. + + \begin{tikzpicture}[out=45,in=135,distance=1cm] + \draw (0,0) to (1,0) + (0,0) to (2,0) + (0,0) to (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/distance", + meta = "⟨distance⟩" + }, + domain = { + details = [[ +Sets the domain from which the samples are taken. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/domain", + meta = "⟨start⟩:⟨end⟩" + }, + dotted = { + details = [[ +Shorthand for setting a dotted dash pattern. + + \tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/dotted" + }, + double = { + details = [[ +This option causes "two" lines to be drawn instead of a single one. +However, this is not what really happens. In reality, the path is drawn +twice. First, with the normal drawing color, secondly with the ⟨core +color⟩, which is normally `white`. Upon the second drawing, the line +width is reduced. The net effect is that it appears as if two lines had +been drawn and this works well even with complicated, curved paths: + + \tikz \draw[double] + plot[smooth cycle] coordinates{(0,0) (1,1) (1,0) (0,1)}; + +You can also use the doubling option to create an effect in which a line +seems to have a certain "border": + + \begin{tikzpicture} + \draw (0,0) -- (1,1); + \draw[draw=white,double=red,very thick] (0,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/double", + meta = "⟨core color⟩" + }, + ["double copy shadow"] = { + details = [[ +This shadow works like a `copy shadow`, only the shadow is added twice, +the second time with the double `xshift` and `yshift`. + + \begin{tikzpicture} + \node [double copy shadow,fill=blue!20,draw=blue,thick] {Hello World!}; + + \node at (0,-1) [double copy shadow={shadow xshift=1ex,shadow yshift=1ex}, + fill=blue!20,draw=blue,thick] + {Hello World!}; + + \node at (0,-2) [double copy shadow={opacity=.5},tape, + fill=blue!20,draw=blue,thick] + {Hello World!}; + + \node at (0,-3) [double copy shadow={left color=blue!50}, + left color=blue!50,draw=blue,thick] + {Hello World!}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/double:copy:shadow", + meta = "⟨shadow options⟩" + }, + ["double distance"] = { + details = [[ +Sets the distance the "two" lines are spaced apart. In reality, this is +the thickness of the line that is used to draw the path for the second +time. The thickness of the *first* time the path is drawn is twice the +normal line width plus the given ⟨dimension⟩. As a side-effect, this +option "selects" the `double` option. + + \begin{tikzpicture} + \draw[very thick,double] (0,0) arc (180:90:1cm); + \draw[very thick,double distance=2pt] (1,0) arc (180:90:1cm); + \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/double:distance", + meta = "⟨dimension⟩" + }, + ["double distance between line centers"] = { + details = [[ +This option works like `double distance`, only the distance is not the +distance between (inner) borders of the two main lines, but between +their centers. Thus, the thickness the *first* time the path is drawn is +the normal line width plus the given ⟨dimension⟩, while the line width +of the *second* line that is drawn is ⟨dimension⟩ minus the normal line +width. As a side-effect, this option "selects" the `double` option. + + \begin{tikzpicture}[double distance between line centers=3pt] + \foreach \lw in {0.5,1,1.5,2,2.5} + \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0); + \end{tikzpicture} + + \begin{tikzpicture}[double distance=3pt] + \foreach \lw in {0.5,1,1.5,2,2.5} + \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/double:distance:between:line:centers", + meta = "⟨dimension⟩" + }, + ["double equal sign distance"] = { + details = [[ +This style selects a double line distance such that it corresponds to +the distance of the two lines in an equal sign. + + \Huge $=\implies$\tikz[baseline,double equal sign distance] + \draw[double,thick,-{Implies[]}](0,0.55ex) --++(3ex,0); + + \normalsize $=\implies$\tikz[baseline,double equal sign distance] + \draw[double,-{Implies[]}](0,0.6ex) --++(3ex,0); + + \tiny $=\implies$\tikz[baseline,double equal sign distance] + \draw[double,very thin,-{Implies[]}](0,0.5ex) -- ++(3ex,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/double:equal:sign:distance" + }, + draw = { + details = [[ +Causes the path to be drawn. "Drawing" (also known as "stroking") can be +thought of as picking up a pen and moving it along the path, thereby +leaving "ink" on the canvas. + +There are numerous parameters that influence how a line is drawn, like +the thickness or the dash pattern. These options are explained below. + +If the optional ⟨color⟩ argument is given, drawing is done using the +given ⟨color⟩. This color can be different from the current filling +color, which allows you to draw and fill a path with different colors. +If no ⟨color⟩ argument is given, the last usage of the `color=` option +is used. + +If the special color name `none` is given, this option causes drawing to +be "switched off". This is useful if a style has previously switched on +drawing and you locally wish to undo this effect. + +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 *not* cause all paths +to be drawn. Instead, this just sets the ⟨color⟩ to be used for drawing +paths inside the environment. + + \begin{tikzpicture} + \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/draw", + meta = "⟨color⟩" + }, + ["draw opacity"] = { + details = [[ +This option sets "how transparent" lines should be. A value of `1` means +"fully opaque" or "not transparent at all", a value of `0` means "fully +transparent" or "invisible". A value of `0.5` yields lines that are +semitransparent. + +Note that when you use PostScript as your output format, this option +works only with recent versions of Ghostscript. + + \begin{tikzpicture}[line width=1ex] + \draw (0,0) -- (3,1); + \filldraw [fill=yellow!80!black,draw opacity=0.5] (1,0) rectangle (2,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/draw:opacity", + meta = "⟨value⟩" + }, + ["drop shadow"] = { + details = [[ +This option adds a drop shadow to a `\path` or a `node`. It uses the +`general shadow` and passes the ⟨shadow options⟩ to it, plus, before +them, the following extra options: + + shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, + opacity=.5, fill=black!50, every shadow + + \tikz [even odd rule] + \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5); + + \begin{tikzpicture} + \foreach \i in {1,...,4} + \node[starburst,drop shadow,fill=white,draw] at (0,\i) {Burst \i}; + \end{tikzpicture} + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/drop:shadow", + meta = "⟨shadow options⟩" + }, + ["edge from parent"] = { + details = [[ +This style is inserted right before the `edge from parent path` and +before the ⟨options⟩ are inserted. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent" + }, + ["edge from parent fork down"] = { + details = [[ +This style will draw a line from the parent downwards (for half the +level distance) and then on to the child using only horizontal and +vertical lines. + + \begin{tikzpicture} + \node {root} + [edge from parent fork down] + child {node {left}} + child {node {right} + child[child anchor=north east] {node {child}} + child {node {child}} + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:fork:down" + }, + ["edge from parent fork left"] = { + details = [[ +Behaves similarly to the previous styles. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:fork:left" + }, + ["edge from parent fork right"] = { + details = [[ +This style behaves similarly, only it will first draw its edge to the +right. + + \begin{tikzpicture} + \node {root} + [edge from parent fork right,grow=right] + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:fork:right" + }, + ["edge from parent fork up"] = { + details = [[ +Behaves similarly to the previous styles. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:fork:up" + }, + ["edge from parent macro"] = { + details = [[ +The ⟨macro⟩ gets expanded each time the `edge from parent` path +operation is used. This ⟨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 ⟨options⟩ that where passed to the +`edge from parent` command, the second parameter will be the ⟨node +specifications⟩ that following the command. + +The standard behavior of drawing a straight line from the parent node to +the child node could be achieved by setting the ⟨macro⟩ to the +following: + + \def\mymacro#1#2{ + [style=edge from parent, #1] + (\tikzparentnode\tikzparentanchor) -- #2 (\tikzchildnode\tikzchildanchor) + } + +Note that `# 2` is placed between `–` and the node to ensure that nodes +are put "on top" of the line. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:macro", + meta = "⟨macro⟩" + }, + ["edge from parent path"] = { + details = [[ +This option allows you to set the `edge from parent path` to a new path. +Initially, this path is the following: + + (\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor) + +The `\tikzparentnode` is a macro that will expand to the name of the +parent node. This works even when you have not assigned a name to the +parent node, in this case an internal name is automatically generated. +The `\tikzchildnode` is a macro that expands to the name of the child +node. The two `...anchor` macros are empty by default. So, what is +essentially inserted is just the path segment +`(\tikzparentnode) – (\tikzchildnode)`; which is exactly an edge from +the parent to the child. + +You can modify this edge from parent path to achieve all sorts of +effects. For example, we could replace the straight line by a curve as +follows: + + \begin{tikzpicture}[level distance=15mm, sibling distance=15mm, + edge from parent path= + {(\tikzparentnode.south) .. controls +(0,-1) and +(0,1) + .. (\tikzchildnode.north)}] + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; + \end{tikzpicture} + +Further useful `edge from parent path`s are defined in the tree library, +see Section ??. + +The nodes in a ⟨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 ??. + +As an example, consider the following code: + + \node (root) {} child {node (child) {} edge to parent node {label}}; + +The `edge to parent` operation and the following `node` operation will, +together, have the same effect as if we had said: + + (root) -- (child) node [pos=0.5] {label} + +Here is a more complicated example: + + \begin{tikzpicture} + \node {root} + child { + node {left} + edge from parent + node[left] {a} + node[right] {b} + } + child { + node {right} + child { + node {child} + edge from parent + node[left] {c} + } + child {node {child}} + edge from parent + node[near end] {x} + }; + \end{tikzpicture} + +As said before, the anchors in the default `edge from parent path` are +empty. However, you can set them using the following keys: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:from:parent:path", + meta = "⟨path⟩" + }, + ["edge label"] = { + details = [[ +A shorthand for `edge node={node[auto]{`⟨text⟩`}}`. + + \tikz \draw (0,0) to [edge label=x] (3,2); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:label", + meta = "⟨text⟩" + }, + ["edge label'"] = { + details = [[ +A shorthand for `edge node={node[auto,swap]{`⟨text⟩`}}`. + + \tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:label'", + meta = "⟨text⟩" + }, + ["edge node"] = { + details = [[ +This key can be used inside the ⟨options⟩ of a `to` path command. It +will add the ⟨node specification⟩ to the list of nodes to be placed on +the connecting line, just as if you had written the ⟨node specification⟩ +directly after the `to` keyword: + + \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} + +This key is mostly useful to create labels automatically using other +keys. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/edge:node", + meta = "⟨node specification⟩" + }, + ["end angle"] = { + details = [[ +Sets the end angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/end:angle", + meta = "⟨degrees⟩" + }, + entity = { + details = [[ +This style is to be used with nodes that represent entity types. It +causes the node's shape to be set to a rectangle that is drawn and whose +minimum size and width are set to sensible values. + +Note that this style is called `entity` despite the fact that it is to +be used for nodes representing entity *types* (the difference between an +entity and an entity type is the same as the difference between an +object and a class in object-oriented programming). If this bothers you, +feel free to define a style `entity type` instead. + + \begin{tikzpicture} + \node[entity] (sheep) {Sheep}; + \node[entity] (genome) [right=of sheep] {Genome}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/entity" + }, + evaluate = { + details = [[ +This key simply executes `\tikzmath{`⟨statements⟩`}`. + + \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); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/evaluate", + meta = "{⟨statements⟩}" + }, + ["even odd rule"] = { + details = [[ +This option causes a different method to be used for determining the +inside and outside of paths. While it is less flexible, it turns out to +be more intuitive. + +With this method, we also shoot rays from the point for which we wish to +determine whether it is inside or outside the filling area. However, +this time we only count how often we "hit" the path and declare the +point to be "inside" if the number of hits is odd. + +Using the even-odd rule, it is easy to "drill holes" into a path. + + \begin{tikzpicture} + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/even:odd:rule" + }, + ["every above delimiter"] = { + details = [[ +Works as above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:above:delimiter" + }, + ["every accepting by arrow"] = { + details = [[ +Executed at the beginning of every path that contains the arrow and the +text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:accepting:by:arrow" + }, + ["every annotation"] = { + details = [[ +This style is included by `annotation`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:annotation" + }, + ["every attribute"] = { + details = [[ +This style is used with every attribute, and therefore also for every +key attribute. + + \begin{tikzpicture} + [text depth=1pt, + every attribute/.style={fill=black!20,draw=black}, + every entity/.style={fill=blue!20,draw=blue,thick}, + every relationship/.style={fill=orange!20,draw=orange,thick,aspect=1.5}] + + \node[entity] (sheep) at (0,0) {Sheep} + child {node [key attribute] {name}}; + \node[entity] (genome) at (2,0) {Genome}; + \node[relationship] at (1,1.5) {has} + edge (sheep) + edge (genome); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:attribute" + }, + ["every below delimiter"] = { + details = [[ +Works as above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:below:delimiter" + }, + ["every calendar"] = { + details = [[ +This style is used with every calendar. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:calendar" + }, + ["every cell"] = { + details = [[ +This style is installed at the beginning of each cell picture with the +two parameters being the current ⟨row⟩ and ⟨column⟩ of the cell. Note +that setting this style to `draw` will *not* cause all nodes to be drawn +since the `draw` option has to be passed to each node individually. + +Inside this style (and inside all cells), the current ⟨row⟩ and ⟨column⟩ +number are also accessible via the counters `\pgfmatrixcurrentrow` and +`\pgfmatrixcurrentcolumn`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:cell", + meta = "{row}{column}" + }, + ["every child"] = { + details = [[ +This style is used at the beginning of each child, as if you had given +the style's contents as options to the `child` operation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:child" + }, + ["every child node"] = { + details = [[ +This style is used at the beginning of each child node in addition to +the `every node` style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:child:node" + }, + ["every circle"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:circle" + }, + ["every circle connection bar"] = { + details = [[ +Redefine this style to change the appearance of circle connection bar +to-paths. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:circle:connection:bar" + }, + ["every circuit ee"] = { + details = [[ +Use this key to configure the appearance of logical circuits. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:circuit:ee" + }, + ["every circuit logic"] = { + details = [[ +Use this key to configure the appearance of logical circuits. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:circuit:logic" + }, + ["every circuit symbol"] = { + details = [[ +Use this style to set up things in general. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:circuit:symbol" + }, + ["every concept"] = { + details = [[ +In order to change the appearance of concept nodes, you should change +this style. Note, however, that the color of a concept should be uniform +for some of the connection bar stuff to work, so you should not change +the color or the draw/fill state of concepts using this option. It is +mostly useful for changing the text color and font. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:concept" + }, + ["every cut"] = { + details = [[ +Executed for every line that should be cut using scissors. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:cut" + }, + ["every data"] = { + details = [[ +This key is executed for every `data` command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:data" + }, + ["every day"] = { + details = [[ +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: + + \tikz[every day/.style=red] + \calendar[dates=2000-01-01 to 2000-01-31,week list]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:day" + }, + ["every delimiter"] = { + details = [[ +This style is executed for every delimiter. You can use it to shift or +color delimiters or do whatever. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:delimiter" + }, + ["every edge"] = { + details = [[ +Executed for each `edge`. + + \begin{tikzpicture}[every edge/.style={draw,dashed}] + \path (0,0) edge (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:edge" + }, + ["every edge quotes"] = { + details = [[ +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. + + \tikz \draw (0,0) edge ["left", ->] (2,0); + +In order to place all labels to the right by default, change this style +to `auto=right`: + + \tikz [every edge quotes/.style={auto=right}] + \draw (0,0) edge ["right", ->] (2,0); + +To place all nodes "on" the edge, just make this style empty (and, +possibly, make your labels opaque): + + \tikz [every edge quotes/.style={fill=white,font=\footnotesize}] + \draw (0,0) edge ["mid", ->] (2,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:edge:quotes" + }, + ["every entity"] = { + details = [[ +This style is evoked by the style `entity`. To change the appearance of +entities, you can change this style. + + \begin{tikzpicture} + [every entity/.style={draw=blue!50,fill=blue!20,thick}] + \node[entity] (sheep) {Sheep}; + \node[entity] (genome) [right=of sheep] {Genome}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:entity" + }, + ["every even column"] = { + details = [[ +This style is used for every cell in an even column. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:even:column" + }, + ["every even row"] = { + details = [[ +This style is used for every cell in an even row. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:even:row" + }, + ["every extra concept"] = { + details = [[ +Change this style to change the appearance of extra concepts. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:extra:concept" + }, + ["every fit"] = { + details = [[ +Set this style to change the appearance of a node that uses the `fit` +option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:fit" + }, + ["every fold"] = { + details = [[ +Executed for every line that should be folded. + + \tikz \pic[ + every cut/.style=red, + every fold/.style=dotted, + folding line length=6mm + ] { tetrahedron folding }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:fold" + }, + ["every info"] = { + details = [[ +Set this style to configure the styling of info labels. Since this key +is *not* used with normal labels, it provides an easy way of changing +the way info labels look without changing other labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:info" + }, + ["every initial by arrow"] = { + details = [[ +This style is executed at the beginning of every path that contains the +arrow and the text. You can use it to, say, make the text red or +whatever. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:initial:by:arrow" + }, + ["every join"] = { + details = [[ +This style is executed each time this command is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:join" + }, + ["every label"] = { + details = [[ +This style is used in every node created by the `label` option. The +default is `draw=none,fill=none`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:label" + }, + ["every label quotes"] = { + details = [[ + \tikz [every label quotes/.style=red] + \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:label:quotes" + }, + ["every left delimiter"] = { + details = [[ +This style is additionally executed for every left delimiter. + + \begin{tikzpicture} + [every left delimiter/.style={red,xshift=1ex}, + every right delimiter/.style={xshift=-1ex}] + \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}] + { + a_8 & a_1 & a_6 \\ + a_3 & a_5 & a_7 \\ + a_4 & a_9 & a_2 \\ + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:left:delimiter" + }, + ["every loop"] = { + details = [[ +This style is installed at the beginning of every loop. + + \begin{tikzpicture}[every loop/.style={}] + \draw (0,0) to [loop above] () to [loop right] () + to [loop below] () to [loop left] (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:loop" + }, + ["every mark"] = { + details = [[ +This style is installed before drawing plot marks. For example, you can +scale (or otherwise transform) the plot mark or set its color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:mark" + }, + ["every matrix"] = { + details = [[ +This style is used in every matrix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:matrix" + }, + ["every mindmap"] = { + details = [[ +This style is included by the `mindmap` style. Change this style to add +special settings to your mindmaps. + + \tikz[large mindmap,concept color=red!50] + \node [concept] {Root concept} + child[grow=right] {node[concept] {Child concept}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:mindmap" + }, + ["every month"] = { + details = [[ +This style can be used to change the appearance of month labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:month" + }, + ["every new --"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:new:--" + }, + ["every new ->"] = { + details = [[ +This key gets executed by default for a `new ->`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:new:->" + }, + ["every new <-"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:new:<-" + }, + ["every new <->"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:new:<->" + }, + ["every node"] = { + details = [[ +This style is installed at the beginning of every node. + + \begin{tikzpicture}[every node/.style={draw}] + \draw (0,0) node {A} -- (1,1) node {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:node" + }, + ["every odd column"] = { + details = [[ +This style is used for every cell in an odd column. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:odd:column" + }, + ["every odd row"] = { + details = [[ +This style is used for every cell in an odd row. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:odd:row" + }, + ["every on background layer"] = { + details = [[ +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. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:on:background:layer" + }, + ["every on chain"] = { + details = [[ +This key is executed for every node on a chain, including the first one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:on:chain" + }, + ["every outer matrix"] = { + details = [[ +While the `every matrix` key also applies to the matrix contents, this +only applies to the outer node which holds the matrix. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:outer:matrix" + }, + ["every path"] = { + details = [[ +This style is installed at the beginning of every path. This can be +useful for (temporarily) adding, say, the `draw` option to everything in +a scope. + + \begin{tikzpicture} + [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); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:path" + }, + ["every pic"] = { + details = [[ +This style is installed at the beginning of every pic. + + (0,0) to [bend left] (3mm,0); + }, + }}] + \begin{tikzpicture}[every pic/.style={scale=2,transform shape}] + \pic foreach \x in {1,2,3} at (\x,0) {seagull}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:pic" + }, + ["every pic quotes"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:pic:quotes" + }, + ["every picture"] = { + details = [[ +This style is installed at the beginning of each picture. + + \tikzset{every picture/.style=semithick} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:picture" + }, + ["every pin"] = { + details = [[ +This style is used in every node created by the `pin` option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:pin" + }, + ["every pin edge"] = { + details = [[ +This style is used in every edge created by the `pin` options. + + \tikz [pin distance=15mm, + every pin edge/.style={<-,shorten <=1pt,decorate, + decoration={snake,pre length=4pt}}] + \node [circle,draw,pin=right:X, + pin=above right:Y, + pin=above:Z] {my circle}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:pin:edge" + }, + ["every pin quotes"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:pin:quotes" + }, + ["every place"] = { + details = [[ +This style is evoked by the style `place`. To change the appearance of +places, you can change this style. + + \begin{tikzpicture} + [every place/.style={draw=blue,fill=blue!20,thick,minimum size=9mm}] + \node[place,tokens=7,label=above:$p_1$] (p1) {}; + \node[place,structured tokens={3,2,9}, + label=below:$p_2\ge1$,right=of p1] (p2) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:place" + }, + ["every plot"] = { + details = [[ +This style is installed in each plot, that is, as if you always said + + plot[every plot,...] + +This is most useful for globally setting a prefix for all plots by +saying: + + \tikzset{every plot/.style={prefix=plots/}} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:plot" + }, + ["every relationship"] = { + details = [[ +Works like `every entity`. + + \begin{tikzpicture} + [every entity/.style={fill=blue!20,draw=blue,thick}, + every relationship/.style={fill=orange!20,draw=orange,thick,aspect=1.5}] + \node[entity] (sheep) at (0,0) {Sheep}; + \node[entity] (genome) at (2,0) {Genome}; + \node[relationship] at (1,1.5) {has} + edge (sheep) + edge (genome); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:relationship" + }, + ["every right delimiter"] = { + details = [[ +Works as above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:right:delimiter" + }, + ["every scope"] = { + details = [[ +This style is installed at the beginning of every scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:scope" + }, + ["every shadow"] = { + details = [[ +This style is executed in addition to any ⟨shadow options⟩ for each +shadow. Use this style to reconfigure the way shadows are drawn. + + \begin{tikzpicture}[every shadow/.style={opacity=.8,fill=blue!50!black}] + \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:shadow" + }, + ["every spy in node"] = { + details = [[ +This style is used with every spy-in node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:spy:in:node" + }, + ["every spy on node"] = { + details = [[ +This style is used with every spy-on node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:spy:on:node" + }, + ["every state"] = { + details = [[ +This style is used by `state with output` and also by +`state without output`. By default, it does nothing, but you can use it +to make your state look more fancy: + + \begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid,>={Stealth[round]}, + every state/.style={draw=blue!50,very thick,fill=blue!20}] + + \node[state,initial] (q_0) {$q_0$}; + \node[state] (q_1) [above right=of q_0] {$q_1$}; + \node[state] (q_2) [below right=of q_0] {$q_2$}; + + \path[->] (q_0) edge node [above left] {0} (q_1) + edge node [below left] {1} (q_2) + (q_1) edge [loop above] node {0} () + (q_2) edge [loop below] node {1} (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:state" + }, + ["every subgraph node"] = { + details = [[ +Set a subgraph node style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:subgraph:node" + }, + ["every to"] = { + details = [[ +This style is installed at the beginning of every to. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:to" + }, + ["every token"] = { + details = [[ +Change this style to change the appearance of tokens. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:token" + }, + ["every transition"] = { + details = [[ +This style is evoked by the style `transition`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:transition" + }, + ["every year"] = { + details = [[ +Works like `every month`, only for years. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:year" + }, + ["every ⟨part name⟩ node part"] = { + details = [[ +This style is installed at the beginning of every node part named ⟨part +name⟩. + + \tikz [every lower node part/.style={red}] + \node [circle split,draw] {$q_1$ \nodepart{lower} $00$}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:⟨part:name⟩:node:part" + }, + ["every ⟨shape⟩ node"] = { + details = [[ +These styles are installed at the beginning of a node of a given +⟨shape⟩. For example, `every rectangle node` is used for rectangle +nodes, and so on. + + \begin{tikzpicture} + [every rectangle node/.style={draw}, + every circle node/.style={draw,double}] + \draw (0,0) node[rectangle] {A} -- (1,1) node[circle] {B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/every:⟨shape⟩:node" + }, + ["execute after day scope"] = { + details = [[ +This is executed at the very end of the current date, outside the scope. +The accumulation is also in reverse. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:after:day:scope", + meta = "⟨code⟩" + }, + ["execute at begin cell"] = { + details = [[ +The code will be executed at the beginning of each nonempty cell. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:cell", + meta = "⟨code⟩" + }, + ["execute at begin day scope"] = { + details = [[ +This code is execute before everything else inside the scope of the +current date. Again, the effect is accumulative. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:day:scope", + meta = "⟨code⟩" + }, + ["execute at begin node"] = { + details = [[ +This option causes ⟨code⟩ to be executed at the beginning of a node. +Using this option multiple times will cause the code to accumulate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:node", + meta = "⟨code⟩" + }, + ["execute at begin picture"] = { + details = [[ +This option causes ⟨code⟩ to be executed at the beginning of the +picture. This option must be given in the argument of the +`{tikzpicture}` environment itself since this option will not have an +effect otherwise. After all, the picture has already "started" later on. +The effect of multiply setting this option accumulates. + +This option is mainly used in styles like the `every picture` style to +execute certain code at the start of a picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:picture", + meta = "⟨code⟩" + }, + ["execute at begin scope"] = { + details = [[ +This option install some code that will be executed at the beginning of +the scope. This option must be given in the argument of the `{scope}` +environment. + +The effect applies only to the current scope, not to subscopes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:scope", + meta = "⟨code⟩" + }, + ["execute at begin to"] = { + details = [[ +The ⟨code⟩ is executed prior to the `to`. This can be used to draw one +or more additional paths or to do additional computations. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:begin:to", + meta = "⟨code⟩" + }, + ["execute at empty cell"] = { + details = [[ +The code will be executed inside each empty cell. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:empty:cell", + meta = "⟨code⟩" + }, + ["execute at end cell"] = { + details = [[ +The code will be executed at the end of each nonempty cell. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:cell", + meta = "⟨code⟩" + }, + ["execute at end day scope"] = { + details = [[ +This code is executed just before the day scope is closed. The effect is +also accumulative, however, in reverse order. This is useful to pair, +say, `\scope` and `\endscope` commands in at-begin- and at-end-code. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:day:scope", + meta = "⟨code⟩" + }, + ["execute at end node"] = { + details = [[ +This option installs ⟨code⟩ that will be executed at the end of the +node. Using this option multiple times will cause the code to +accumulate. + + \begin{tikzpicture} + [execute at begin node={A}, + execute at end node={D}] + \node[execute at begin node={B}] {C}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:node", + meta = "⟨code⟩" + }, + ["execute at end picture"] = { + details = [[ +This option installs ⟨code⟩ that will be executed at the end of the +picture. Using this option multiple times will cause the code to +accumulate. This option must also be given in the optional argument of +the `{tikzpicture}` environment. + + \begin{tikzpicture}[execute at end picture=% + { + \begin{pgfonlayer}{background} + \path[fill=yellow,rounded corners] + (current bounding box.south west) rectangle + (current bounding box.north east); + \end{pgfonlayer} + }] + \node at (0,0) {X}; + \node at (2,1) {Y}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:picture", + meta = "⟨code⟩" + }, + ["execute at end scope"] = { + details = [[ +This option installs some code that will be executed at the end of the +current scope. Using this option multiple times will cause the code to +accumulate. This option must also be given in the optional argument of +the `{scope}` environment. + +Again, the effect applies only to the current scope, not to subscopes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:scope", + meta = "⟨code⟩" + }, + ["execute at end to"] = { + details = [[ +Works like the previous option, only this code is executed after the to +path has been added. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:at:end:to", + meta = "⟨code⟩" + }, + ["execute before day scope"] = { + details = [[ +The ⟨code⟩ is executed before everything else for each date. Multiple +calls of this option have an accumulative effect. Thus, if you use this +option twice, the code from the first use is used first for each day, +followed by the code given the second time. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/execute:before:day:scope", + meta = "⟨code⟩" + }, + ["external/aux in dpth"] = { + details = [[ +Allows to enable or disable the feature which handles references and +labels as part of image externalization. Disabling it will safe one +`\newwrite` command, i.e. a write register. + +Also see the `disable dependency files` feature. + +Here are some implementation details on how references within/from +external graphics work for those who would like to know the details: + +For point a), a `\ref` inside of an externalized graphics works by +reading the main document's `.aux` file. To this end, the standard +`mode=convert with system call` detects such references and reschedules +the externalization to `\end{document}.`[1] Other values of `mode` +require just one attempt to externalize the picture. + +Note that `\pageref` is not supported (sorry). + +Point b) works as follows: a `\label` inside of an externalized graphics +causes the `external` library to generate separate auxiliary files for +every external image. These files are called ⟨imagename⟩`.dpth`. The +extension `.dpth` indicates that the file also contains the image's +depth (the `baseline` key of TikZ). Furthermore, anything which would +have been written to an `.aux` file will be redirected to the `.dpth` +file -- but only things which occur inside of the externalized +`tikzpicture` environment. When the main document loads the image, it +will copy the `.dpth` file into the main `.aux` file. Then, successive +compilations of the main document contain the external `\label` +information. In other words, a `\label` in an external graphics needs +the following work flow: + +1. The external graphics needs to be generated together with its + `.dpth` (usually automatically by TikZ). + +2. The main document includes the external graphics and copies the + `.dpth` content into its main `.aux` file. + +3. The main document needs to be translated once again to re-read its + `.aux` file[2]. + +This does also work if a `\label`/`\ref` combination is implemented +itsself by a `tikzpicture` (a feature offered by `pgfplots`). + +[1] Note that this requires the `atveryend` package. The purpose to +reschedule the externalization is to access the main job's aux file, but +only after it has been written completely. + +[2] Note that it is not possible to activate the content of an auxiliary +file after `\ begin{document}` in LaTeX. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/aux:in:dpth", + meta = "{boolean}" + }, + ["external/disable dependency files"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/disable:dependency:files" + }, + ["external/export"] = { + details = [[ +A boolean which can be used to disable the export mechanism for all +pictures inside of the current TeX-scope. + + \begin{document} + \begin{tikzpicture} % will be exported + ... + \end{tikzpicture} + + { + \tikzset{external/export=false} + \begin{tikzpicture} % won't be exported + ... + \end{tikzpicture} + ... + } + + \begin{tikzpicture} % will be exported + ... + \end{tikzpicture} + \end{document} + +For LaTeX, the feature lasts until the next `\end``{\cdot}` (this holds +for every call to `\tikzset`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/export", + meta = "{boolean}" + }, + ["external/export next"] = { + details = [[ +A boolean which can be used to disable the export mechanism for single +pictures. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/export:next", + meta = "{boolean}" + }, + ["external/figure list"] = { + details = [[ +A boolean which configures whether a figure list shall be generated. A +figure list is an output file named `{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 ``{picture file name}` +`{main file}` manually (or in a script). See section ?? for the details +about the expected system call (or activate +`mode=convert with system call` and inspect your log file). + + \documentclass{article} + % main document, called main.tex + \usepackage{tikz} + + \usetikzlibrary{external} + \tikzexternalize[ + mode=graphics if exists, + figure list=true, + prefix=figures/] + + \begin{document} + + \tikzsetnextfilename{trees} + \begin{tikzpicture} + \node {root} + child {node {left}} + child {node {right} + child {node {child}} + child {node {child}} + }; + \end{tikzpicture} + + \tikzsetnextfilename{simple} + A simple image is \tikz \fill (0,0) circle(5pt);. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (5,5); + \end{tikzpicture} + \end{document} + + pdflatex main + +generates `main.figlist` containing + + figures/trees + figures/simple + figures/main-figure0 +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/figure:list", + meta = "{boolean}" + }, + ["external/figure name"] = { + details = [[ +Same as `\tikzsetfigurename``{name}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/figure:name", + meta = "{name}" + }, + ["external/force remake"] = { + details = [[ +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. + + \tikzset{external/force remake} + \begin{tikzpicture} + \draw (0,0) circle(5pt); + \end{tikzpicture} + +You can also use `force remake` inside of a local TeX group to remake +only selected pictures. The example + + \tikz \draw (0,0) -- (1,1); + + { + \tikzset{external/force remake} + \begin{tikzpicture} + \draw (0,0) circle(5pt); + \end{tikzpicture} + } + + \tikz \draw (0,0) -- (1,1); + +will only apply `force remake` to the second figure. + +Up-to-date checks are applied for `mode=convert with system call` and +the makefile generated by `mode=list and make`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/force:remake", + meta = "{boolean}" + }, + ["external/mode"] = { + details = [[ +Configures what to do with TikZ 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 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 + + pdflatex -shell-escape + +while other TeX variants may need other switches. The feature is +sometimes called `\write18`. + +The choice `only graphics` always tries to replace pictures with +external graphics. It is an error if the graphics file does not exist. + +The choice `no graphics` (or, equivalently, `only pictures`) typesets +TikZ pictures without checking for external graphics. + +A mixture is `graphics if exists`, it checks whether a suitable graphics +file exists and includes it if that is the case. If it does not exist, +the picture is typeset using TeX. + +Mode `list only` skips every TikZ picture; it only generates the file +`{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 `{main file}``.figlist`, but any images which exist already +are included as graphics instead of ignoring them. Furthermore, this +mode generates an additional file: `{main file}`.makefile. This allows +to use a work flow like + + % step 1: generate main.makefile: + pdflatex main + % step 2: generate ALL graphics on 2 processors: + make -j 2 -f main.makefile + % step 3: include the graphics: + pdflatex main + +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/mode", + meta = "{choice}" + }, + ["external/only named"] = { + details = [[ +If enabled, only pictures for which file names have been set explicitly +using `\tikzsetnextfilename` will be considered, no file names will be +generated automatically. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/only:named", + meta = "{boolean}" + }, + ["external/optimize"] = { + details = [[ +Configures whether the conversion process shall be optimized. This +affects only the case when `\jobname` differs from the main file name, +i.e. when single pictures are converted. + +In that case, the main file is compiled as usual -- but everything +except the selected picture is thrown away. If optimization is enabled, +all other pictures won't be processed at all. Furthermore, expensive +commands which do not contribute to the selected picture will be thrown +away as well. + +The default implementation discards `\includegraphics` commands which +are *not* inside of the selected picture to reduce conversion time. + +It is possible to add commands which shall be optimized away, see below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/optimize", + meta = "{boolean}" + }, + ["external/optimize command away"] = { + details = [[ +Installs commands to optimize ⟨\\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 `{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 ⟨\\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 +⟨\\command⟩ are supported: + +1. If `{required argument count}` is empty (the default), ⟨\\command⟩ + may take one optional argument in square brackets and one in curly + braces (which is also optional). + +2. If `{required argument count}` is not empty, `{\command}` may take + one optional argument in square brackets. Furthermore, it expects + exactly `{required argument count}` following arguments. + +Example: + + \tikzset{external/optimize command away=\includegraphics} + + \newcommand{\myExpensiveMacro}[1]{Very expensive!} + + \tikzset{external/optimize command away=\myExpensiveMacro} + + \newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!} + + \tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}} + + % A command with optional argument: + \newcommand{\aFurtherExample}[3][]{Very expensive!} + + % consume only two arguments: the first optional one will be processed + % anyway: + \tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}} + +The argument ⟨\\command⟩ must be the name of a single macro. Any +occurrence of this macro, together with its arguments, will be removed. + + \begin{tikzpicture} + % this picture is currently converted! + \end{tikzpicture} + + This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded. + + This call: \myExpensiveMacro[argument=value]{Argument} as well. + And this here: \myExpensiveMacro{Argument} also. + +The default is to optimize `\includegraphics` away. + +This key is actually a style which sets the `optimize/install` and +`optimize/restore` keys. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/optimize:command:away", + meta = "⟨\\command⟩{required argument count}" + }, + ["external/optimize/install"] = { + details = [[ +A command key which contains code to install optimizations. You can +append code here (or clear the macro) if you need to modify the +optimization. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/optimize/install" + }, + ["external/optimize/restore"] = { + details = [[ +A command key which contains code to undo optimizations. You can append +code here (or clear the macro) if you need to modify the optimization. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/optimize/restore" + }, + ["external/prefix"] = { + details = [[ +A shortcut for `\tikzsetexternalprefix``{file name prefix}`, see below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/prefix", + meta = "{file name prefix}" + }, + ["external/remake next"] = { + details = [[ +A variant of `force remake` which applies only to the next image. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/remake:next", + meta = "{boolean}" + }, + ["external/shell escape"] = { + details = [[ +Contains the command line option for `latex` which enables the +`\write18` feature. For TeX-Live, this is `-shell-escape`. For MiKTeX, +you should use `\tikzexternalize[shell escape=-enable-write18]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/shell:escape", + meta = "{command-line arg}" + }, + ["external/system call"] = { + details = [[ +\[extlib:systemcall:option\] A template string used to generate system +calls. Inside of `{template}`, the macro `\image` can be used as +placeholder for the image which is about to be generated while +`\texsource` contains the main file name (in truth, it contains +`\input``{main file name}`, but that doesn't matter). + +The default depends on the value of `\pgfsysdriver`. For +`pgfsys-pdftex.def`, it is + + \tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error + -interaction=batchmode -jobname "\image" "\texsource"}} + +where `\tikzexternalcheckshellescape` inserts the value of the +configuration key `shell escape` if and only if the current document has +been typeset with `-shell-escape`[1]. + +Other drivers result in slightly different calls. There is support for +`lualatex`, `xelatex`, and `dvips`. The precise values are written to +the `.log` file as soon as you attempt to compile a document. + +The argument `{template}` will be expanded using `\edef`, so any control +sequences will be expanded. During this evaluation, '`\\`' will result +in a normal backslash, '`\`'. Furthermore, double quotes '`"`', single +quotes '`’`', semicolons and dashes '`-`' will be made to normal +characters if any package uses them as macros. This ensures +compatibility with the `german` package, for example. + +[1] Note that this is always true for the default configuration. This +security consideration applies mainly for `mode=list and make` which +will also work *without* shell escapes. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/system:call", + meta = "{template}" + }, + ["external/up to date check"] = { + details = [[ +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 simple is based on the existence of the file: the file is +up-to-date if and only if it exists. + +The choice 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 +pdfTeX method `\pdfmdfivesum`. If it is unavailable for some reason, the +choice `diff` will be used instead. + +The choice 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. + +#### 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. Example: Suppose we have the following picture +which depends on a command `\mycommand`: + + \def\mycommand{My comment} + + \begin{tikzpicture} + + \node at (0,0) {\mycommand}; + + \end{tikzpicture} + +What happens if you change "My comment" to "My super comment"? Well, +`external` will *not* pick it up; you will need to handle this manually. +However, if you modify anything between `\begin{tikzpicture}` and +`\end{tikzpicture}`, the `external` library *will* pick it up and +regenerate the picture. + +The `up to date check` is applied for `mode=convert with system call` +and `mode=list and make`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/up:to:date:check", + meta = "{choice}" + }, + ["external/verbose"] = { + details = [[ +Sets all verbosity flags to ⟨boolean⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/verbose", + meta = "{boolean}" + }, + ["external/verbose IO"] = { + details = [[ +A boolean which configures whether I/O operations shall be listed in the +logfile. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/verbose:IO", + meta = "{boolean}" + }, + ["external/verbose optimize"] = { + details = [[ +A boolean which configures whether optimization operations shall be +listed in the logfile. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/external/verbose:optimize", + meta = "{boolean}" + }, + ["extra concept"] = { + details = [[ +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 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 additional, you +can use this style. + + \begin{tikzpicture}[mindmap,concept color=blue!80] + \node [concept] {Root concept}; + \node [extra concept] at (10,0) {extra concept}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/extra:concept" + }, + ["face 1"] = { + details = [[ +The ⟨code⟩ is executed for the first face of the dodecahedron. When it +is executed, the coordinate system will have been shifted and rotated +such that it lies at the middle of the first face of the dodecahedron. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/face:1", + meta = "⟨code⟩" + }, + ["face 2"] = { + details = [[ +Same as `face 1`, but for the second face. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/face:2", + meta = "⟨code⟩" + }, + ["face 3"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/face:3", + meta = "⟨code⟩" + }, + ["face 4"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/face:4", + meta = "⟨code⟩" + }, + ["fading angle"] = { + details = [[ +A shortcut for `fading transform={rotate=`⟨degree⟩`}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fading:angle", + meta = "⟨degree⟩" + }, + ["fading transform"] = { + details = [[ +The ⟨transformation options⟩ are applied to the fading before it is +used. For instance, if ⟨transformation options⟩ is set to `rotate=90`, +the fading is rotated by 90 degrees. + + \begin{tikzpicture}[path fading=fade down] + % Checker board + \fill [black!20] (0,0) rectangle (4,1.5); + \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,1.5); + + \fill [red,path fading,fading transform={rotate=90}] + (1,0.75) ellipse (.75 and .5); + \fill [red,path fading,fading transform={rotate=30}] + (3,0.75) ellipse (.75 and .5); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fading:transform", + meta = "⟨transformation options⟩" + }, + fill = { + details = [[ +This option causes the path to be filled. All unclosed parts of the path +are first closed, if necessary. Then, the area enclosed by the path is +filled with the current filling color, which is either the last color +set using the general `color=` option or the optional color ⟨color⟩. For +self-intersection paths and for paths consisting of several closed +areas, the "enclosed area" is somewhat complicated to define and two +different definitions exist, namely the nonzero winding number rule and +the even odd rule, see the explanation of these options, below. + +Just as for the `draw` option, setting ⟨color⟩ to `none` disables +filling locally. + + \begin{tikzpicture} + \fill (0,0) -- (1,1) -- (2,1); + \fill (4,0) circle (.5cm) (4.5,0) circle (.5cm); + \fill[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm); + \fill (8,0) -- (9,1) -- (10,0) circle (.5cm); + \end{tikzpicture} + +If the `fill` option is used together with the `draw` option (either +because both are given as options or because a `\filldraw` command is +used), the path is filled *first*, then the path is drawn *second*. This +is especially useful if different colors are selected for drawing and +for filling. Even if the same color is used, there is a difference +between this command and a plain `fill`: A "filldrawn" area will be +slightly larger than a filled area because of the thickness of the +"pen". + + \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); + \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fill", + meta = "⟨color⟩" + }, + ["fill opacity"] = { + details = [[ +This option sets the opacity of fillings. In addition to filling +operations, this opacity also applies to text and images. + +Note, again, that when you use PostScript as your output format, this +option works only with recent versions of Ghostscript. + + \begin{tikzpicture}[thick,fill opacity=0.5] + \filldraw[fill=red] (0:1cm) circle (12mm); + \filldraw[fill=green] (120:1cm) circle (12mm); + \filldraw[fill=blue] (-120:1cm) circle (12mm); + \end{tikzpicture} + + \begin{tikzpicture} + \fill[red] (0,0) rectangle (3,2); + + \node at (0,0) {\huge A}; + \node[fill opacity=0.5] at (3,2) {\huge B}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fill:opacity", + meta = "⟨value⟩" + }, + fit = { + details = [[ +This option must be given to a `node` path command. The ⟨coordinates or +nodes⟩ should be a sequence of TikZ coordinates or node names, one +directly after the other without commas (like with the +`plot coordinates` path operation). Examples 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 ⟨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 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 a circular node. Note how the +circle encompasses exactly the same bounding box. + + \begin{tikzpicture}[inner sep=0pt,thick, + dot/.style={fill=blue,circle,minimum size=3pt}] + \draw[help lines] (0,0) grid (3,2); + \node[dot] (a) at (1,1) {}; + \node[dot] (b) at (2,2) {}; + \node[dot] (c) at (1,2) {}; + \node[dot] (d) at (1.25,0.25) {}; + \node[dot] (e) at (1.75,1.5) {}; + + \node[draw=red, fit=(a) (b) (c) (d) (e)] {box}; + \node[draw,circle,fit=(a) (b) (c) (d) (e)] {}; + \end{tikzpicture} + +Every time the `fit` option is used, the following style is also applied +to the node: + +The exact effects of the `fit` option are the following: + +1. A minimal bounding box containing all coordinates is computed. Note + that if a coordinate like `(a)` is used that 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. + +2. The `text width` option is set to the width of this bounding box. + +3. The `align=center` option is set. + +4. The `anchor` is set to `center`. + +5. The `at` position of the node is set to the center of the computed + bounding box. + +6. After the node has been typeset, its height and depth are adjusted + such that they add up to the height of the computed bounding box and + such that the text of the node is vertically centered inside the + box. + +The above means that, generally speaking, if the node contains text like +`box` in the above example, it will be centered inside the box. It will +be difficult to put the text elsewhere, in particular, changing the +`anchor` of the node will not have the desired effect. Instead, what you +should do is to create a node with the `fit` option that does not +contain any text, give it a name, and then use normal nodes to add text +at the desired positions. Alternatively, consider using the `label` or +`pin` options. + +Suppose, for instance, that in the above example we want the word "box" +to appear inside the box, but at its top. This can be achieved as +follows: + + \begin{tikzpicture}[inner sep=0pt,thick, + dot/.style={fill=blue,circle,minimum size=3pt}] + \draw[help lines] (0,0) grid (3,2); + \node[dot] (a) at (1,1) {}; + \node[dot] (b) at (2,2) {}; + \node[dot] (c) at (1,2) {}; + \node[dot] (d) at (1.25,0.25) {}; + \node[dot] (e) at (1.75,1.5) {}; + + \node[draw=red,fit=(a) (b) (c) (d) (e)] (fit) {}; + \node[below] at (fit.north) {box}; + \end{tikzpicture} + +Here is a real-life example that uses fitting: + + \begin{tikzpicture} + [vertex/.style={minimum size=2pt,fill,draw,circle}, + open/.style={fill=none}, + sibling distance=1.5cm,level distance=.75cm, + every fit/.style={ellipse,draw,inner sep=-2pt}, + leaf/.style={label={[name=#1]below:$#1$}},auto] + + \node [vertex] (root) {} + child { node [vertex,open] {} + child { node [vertex,open] {} + child { node [vertex] (b's parent) {} + child { node [vertex] {} + child { node [vertex,leaf=d] {} } + child { node [vertex,leaf=e] {} } } + child { node [vertex,leaf=b] {} } } + child { node [vertex,leaf=a] {} } } + child { node [coordinate] {} + child[missing] + child { node [vertex] (f's parent) {} + child { node [vertex,leaf=c] {} } + child { node [vertex,leaf=f] {} } } } + edge from parent node {$\rho$} }; + + \node [fit=(d) (e) (b) (b's parent),label=above left:$F^{(b,R)}$] {}; + \node [fit=(c) (f) (f's parent),label=above right:$F^{(c,R)}$] {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fit", + meta = "⟨coordinates or nodes⟩" + }, + ["fit fading"] = { + details = [[ +When set to `true`, the fading is shifted and resized (in exactly 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 "punch out" something. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/fit:fading", + meta = "⟨boolean⟩" + }, + ["folding line length"] = { + details = [[ +Sets the length of the base line for folding. For the dodecahedron this +is the length of all the sides of the pentagons. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/folding:line:length", + meta = "⟨dimension⟩" + }, + font = { + details = [[ +Sets the font used for the text inside nodes. However, this font will +*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{tikzpicture} + \node [font=\itshape] {italic}; + \end{tikzpicture} + + \tikz \node [font=\tiny, minimum height=3em, draw] {tiny}; + \tikz \node [font=\small, minimum height=3em, draw] {small}; + +A useful example of how the `font` option can be used is the following: + + \tikz [every text node part/.style={font=\itshape}, + every lower node part/.style={font=\footnotesize}] + \node [circle split,draw] {state \nodepart{lower} output}; + +As can be seen, the font can be changed for each node part. This does +*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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/font", + meta = "⟨font commands⟩" + }, + framed = { + details = [[ +This is a shorthand for `show background rectangle`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/framed" + }, + ["general shadow"] = { + details = [[ +This option should be given to a `\path` or a `node`. It has the +following effect: Before the path is used normally, it is used once with +the ⟨shadow options⟩ in force. Furthermore, when the path is "preused" +in this way, it is shifted and scaled a little bit. + +In detail, the following happens: A `preaction` is used to paint the +path in a special manner before it is actually painted. This "special" +manner is as follows: The options in ⟨shadow options⟩ are used for +painting this path. Typically, the ⟨shadow options⟩ will contain options +like `fill=black` to create, say, a black shadow. Furthermore, after the +⟨shadow 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`. + +Note that since scaling and shifting is done using canvas +transformations, shadows are not taken into account when the picture's +bounding box is computed. + + \tikz [even odd rule] + \draw [general shadow={fill=red}] (0,0) circle (.5) (0.5,0) circle (.5); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/general:shadow", + meta = "⟨shadow options⟩" + }, + ["graph/level"] = { + details = [[ +This key gets executed for each newly created node with ⟨level⟩ set to +the current level of the node. You can use this key to, say, reconfigure +the node distance or the node color. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graph/level", + meta = "⟨level⟩" + }, + ["graph/level ⟨level⟩"] = { + details = [[ +This key also gets executed for each newly created node with ⟨level⟩ set +to the current level of the node. + + \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 + } + }; + + \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 + } + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graph/level:⟨level⟩" + }, + ["graph/parse"] = { + details = [[ +This key can only be used inside the ⟨options⟩ of a ⟨group +specification⟩. Its effect is that the ⟨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 ⟨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. + + \def\mychain{ a -> b -> c; } + \tikz \graph { [parse/.expand once=\mychain] d -> e }; + +In the following, more fancy example we use a loop to create a chain of +dynamic length. + + \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] }; + +Multiple uses of this key accumulate, that is, all the texts given in +the different uses is inserted in the order it is given. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/graph/parse", + meta = "⟨text⟩" + }, + gridded = { + details = [[ +This is a shorthand for `show background grid`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/gridded" + }, + grow = { + details = [[ +This key is used to define the ⟨direction⟩ in which the tree will grow. +The ⟨direction⟩ can either be an angle in degrees or one of the +following special text strings: `down`, `up`, `left`, `right`, `north`, +`south`, `east`, `west`, `north east`, `north west`, `south east`, and +`south west`. All of these have "their obvious meaning", so, say, +`south west` is the same as the angle $-135^\circ$. + +As a side effect, this option installs the default growth function. + +In addition to setting the direction, this option also has a seemingly +strange effect: It sets the sibling distance for the current level to +`0pt`, but leaves the sibling distance for later levels unchanged. + +This somewhat strange behavior has a highly desirable effect: If you +give this option before the list of children of a node starts, the +"current level" is still the parent level. Each child will be on a later +level and, hence, the sibling distance will be as specified originally. +This will cause the children to be neatly aligned in a line orthogonal +to the given ⟨direction⟩. However, if you give this option locally to a +single child, then "current level" will be the same as the child's +level. The zero sibling distance will then cause the child to be placed +exactly at a point at distance `level distance` in the direction +⟨direction⟩. However, the children of the child will be placed +"normally" on a line orthogonal to the ⟨direction⟩. + +These placement effects are best demonstrated by some examples: + + \tikz \node {root} [grow=right] child child; + + \tikz \node {root} [grow=south west] child child; + + \begin{tikzpicture}[level distance=10mm,sibling distance=5mm] + \node {root} + [grow=down] + child + child + child[grow=right] { + child child child + }; + \end{tikzpicture} + + \begin{tikzpicture}[level distance=2em] + \node {C} + child[grow=up] {node {H}} + child[grow=left] {node {H}} + child[grow=down] {node {H}} + child[grow=right] {node {C} + child[grow=up] {node {H}} + child[grow=right] {node {H}} + child[grow=down] {node {H}} + edge from parent[double] + coordinate (wrong) + }; + \draw[<-,red] ([yshift=-2mm]wrong) -- +(0,-1) + node[below]{This is wrong!}; + \end{tikzpicture} + + \begin{tikzpicture} + \node[rectangle,draw] (a) at (0,0) {start node}; + \node[rectangle,draw] (b) at (2,1) {end}; + + \draw (a) -- (b) + node[coordinate,midway] {} + child[grow=100,<-] {node[above] {the middle is here}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/grow", + meta = "⟨direction⟩" + }, + ["grow cyclic"] = { + details = [[ +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 on points on a circle. Instead of +a sibling distance, there is a `sibling angle` that denotes the angle +between two given children. + +Note that this function will rotate the coordinate system of the +children to ensure that the grandchildren will grow in the right +direction. + + \begin{tikzpicture} + [grow cyclic, + level 1/.style={level distance=8mm,sibling angle=60}, + level 2/.style={level distance=4mm,sibling angle=45}, + level 3/.style={level distance=2mm,sibling angle=30}] + \coordinate [rotate=-90] % going down + child foreach \x in {1,2,3} + {child foreach \x in {1,2,3} + {child foreach \x in {1,2,3}}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/grow:cyclic" + }, + ["grow via three points"] = { + details = [[ +This option installs a growth function that works as follows: If a +parent node has just one child, this child is placed at ⟨x⟩. If the +parent node has two children, these are placed at ⟨y⟩ and ⟨z⟩. If the +parent node has more than two children, the children are placed at +points that are linearly extrapolated from the three points ⟨x⟩, ⟨y⟩, +and ⟨z⟩. In detail, the position is $x + \frac{n-1}{2}(y-x) + + (c-1)(z-y)$, where $n$ is the number of children and $c$ is the +number of the current child (starting with $1$). + +The net effect of all this is that if you have a certain "linear +arrangement" in mind and use this option to specify the placement of a +single child and of two children, then any number of children will be +placed correctly. + +Here are some arrangements based on this growth function. We start with +a simple "above" arrangement: + + \begin{tikzpicture}[grow via three points={% + one child at (0,1) and two children at (-.5,1) and (.5,1)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; + \end{tikzpicture} + +The next arrangement places children above, but "grows only to the +right". + + \begin{tikzpicture}[grow via three points={% + one child at (0,1) and two children at (0,1) and (1,1)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; + \end{tikzpicture} + +In the final arrangement, the children are placed along a line going +down and right. + + \begin{tikzpicture}[grow via three points={% + one child at (-1,-.5) and two children at (-1,-.5) and (0,-.75)}] + \node at (0,0) {one} child; + \node at (0,-1.5) {two} child child; + \node at (0,-3) {three} child child child; + \node at (0,-4.5) {four} child child child child; + \end{tikzpicture} + +These examples should make it clear how you can create new styles to +arrange your children along a line. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/grow:via:three:points", + meta = "one child at (⟨x⟩ ) and two children at (⟨y⟩) and (⟨z⟩)" + }, + ["grow'"] = { + details = [[ +This key has the same effect as `grow`, only the children are arranged +in the opposite order. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/grow'", + meta = "⟨direction⟩" + }, + ["growth function"] = { + details = [[ +This rather low-level option allows you to set a new growth function. +The ⟨macro name⟩ must be the name of a macro without parameters. This +macro will be called for each child of a node. The initial function is +an internal function that corresponds to downward growth. + +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 set up such that the +anchor of the parent node is in the origin. Thus, in each call, the +⟨macro name⟩ must essentially do a shift to the child's origin. When the +macro is called, the TeX counter `\tikznumberofchildren` will be set to +the total number of children of the parent node and the counter +`\tikznumberofcurrentchild` will be set to the number of the current +child. + +The macro may, in addition to shifting the coordinate system, also +transform the coordinate system further. For example, it could be +rotated or scaled. + +Additional growth functions are defined in the library, see Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/growth:function", + meta = "⟨macro name⟩" + }, + ["growth parent anchor"] = { + details = [[ +This key allows you to specify which anchor of the parent node is to be +used for computing the children's position. For example, when there is +only one child and the `level distance` is `2cm`, then the child node +will be placed two centimeters below the ⟨anchor⟩ of the parent node. +"Being placed" means that the child node's anchor (which is the anchor +specified using the `anchor=` option in the `node` command of the child) +is two centimeters below the parent node's ⟨anchor⟩. + +In the following example, the two red lines both have length `1cm`. + + \begin{tikzpicture}[level distance=1cm] + \node [rectangle,draw] (a) at (0,0) {root} + [growth parent anchor=south] child; + + \node [rectangle,draw] (b) at (2,0) {root} + [growth parent anchor=north east] child; + + \draw [red,thick,dashed] (a.south) -- (a-1); + \draw [red,thick,dashed] (b.north east) -- (b-1); + \end{tikzpicture} + +In the next example, the top and bottom nodes are aligned at the top and +the bottom, respectively. + + \begin{tikzpicture} + [level distance=2cm,growth parent anchor=north, + every node/.style={anchor=north,rectangle,draw} + every child node/.style={anchor=south}] + + \node at (0,0) {root} child {node {small}}; + + \node at (2,0) {big root} child {node {\large big}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/growth:parent:anchor", + meta = "⟨anchor⟩" + }, + ["handle active characters in code"] = { + details = [[ +When this key is set, at the beginning of every `\tikz` command and +every `{tikzpicture}`, the character codes of all symbols used by +TikZ are reset to their normal values. Furthermore, at the beginning of +each node, the catcodes are restored to the values they had prior to the +current picture. + +The net effect of this is that, in most cases, symbols having a special +character code can be used nicely both in TikZ code and also in node +texts. + +In the following, slightly silly, example we make the dot an active +character and define it in some strange way. Now, in the later +TikZ command, the dot in `3.0cm` may no longer be active and setting the +`handle...` option achieves exactly this. However, as can be seen, the +dot is once more active inside the node. + + \catcode`\.=\active + \def.{\o} + + \tikz [handle active characters in code] + \node [draw, minimum width=3.0cm] {hall. pe.ple}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/handle:active:characters:in:code", + meta = "⟨true or false⟩" + }, + ["handle active characters in nodes"] = { + details = [[ +This key is needed for a special situation: As explained for the +`handle ... code` key, that key switches off all special meaning of +symbols and switches them back on again at the beginning of nodes. +However, there is one situation when this is not possible: When some +text has already been read by TeX, the catcodes can no longer change. +Now, for normal nodes this is not a problem since their contents has not +been read at the moment the catcodes are restored. In contrast for label +nodes for edges, nodes produced by the `graph` and `quotes` libraries, +and some others nodes, their text *has* already been read when the +catcodes get adjusted. + +The present key may help in such situations: It causes the text of all +such "indirectly created" nodes to be surrounded by a call to the +`\scantokens` command. This command attempts to reread an already read +text, but allows catcodes to change. As users of this command will know, +it is not a perfect substitute for directly reading the text by TeX, but +it normally has the desired effect. + + \catcode`\.=\active + \def.{\o} + + \tikz [handle active characters in code, + handle active characters in nodes] + \node [draw, label=f..] {hall. pe.ple}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/handle:active:characters:in:nodes", + meta = "⟨true or false⟩" + }, + height = { + details = [[ +Inside a `spy scope`, this is a shortcut for `minimum height`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/height", + meta = "⟨dimension⟩" + }, + ["help lines"] = { + details = [[ +This style makes lines "subdued" by using thin gray lines for them. +However, this style is not installed automatically and you have to say +for example: + + \tikz \draw[help lines] (0,0) grid (3,3); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/help:lines" + }, + ["huge circuit symbols"] = { + details = [[ +This style sets the default circuit symbol unit to `10pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/huge:circuit:symbols" + }, + ["huge mindmap"] = { + details = [[ +This style causes concepts to be even bigger and it is best used with A2 +paper and above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/huge:mindmap" + }, + id = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/id", + meta = "⟨id⟩" + }, + ["if"] = { + details = [[ +This option has the same effect as giving a corresponding if in the +⟨calendar specification⟩. The option is mostly useful for use in the +`every calendar` style, where you cannot provide if conditionals +otherwise. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/if", + meta = "(⟨conditions⟩)⟨code or options⟩else⟨else code or options⟩" + }, + ["in"] = { + details = [[ +The angle at which the curve reaches the target coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in", + meta = "⟨angle⟩" + }, + ["in control"] = { + details = [[ +This option causes the ⟨coordinate⟩ to be used as the target control +point. You can use a coordinate like `+(1,0)` to specify a point +relative to the *end* coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:control", + meta = "⟨coordinate⟩" + }, + ["in distance"] = { + details = [[ +Sets the minimum and maximum in distance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:distance", + meta = "⟨distance⟩" + }, + ["in front of path"] = { + details = [[ +This is the opposite of `behind path`: It causes nodes to be drawn on +top of the path. Since this is the default behavior, 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 behavior. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:front:of:path" + }, + ["in looseness"] = { + details = [[ +Specifies the looseness factor for the in distance only. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:looseness", + meta = "⟨number⟩" + }, + ["in max distance"] = { + details = [[ +The maximum distance set only for the target coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:max:distance", + meta = "⟨distance⟩" + }, + ["in min distance"] = { + details = [[ +The minimum distance set only for the target coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/in:min:distance", + meta = "⟨distance⟩" + }, + info = { + details = [[ +This key has nearly the same effect as the `label` key, only the +following style is used additionally automatically: + +The ⟨options⟩ and ⟨angle⟩ are passed directly to the `label` command. + + \begin{tikzpicture}[circuit ee IEC,every info/.style=red] + \node [resistor,info=$3\Omega$] {}; + \end{tikzpicture} + +You will find a detailed discussion of the `label` option on page ??. + +Hint: To place some text *on* the main node, use `center` as the +⟨angle⟩: + + \begin{tikzpicture}[circuit ee IEC,every info/.style=red] + \node [resistor,info=center:$3\Omega$] {}; + \node [resistor,point up,info=center:$R_1$] at (2,0) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/info", + meta = "[⟨options⟩]⟨angle⟩:⟨text⟩" + }, + ["info sloped"] = { + details = [[ +This key works like `info`, only the `transform shape` option is set +when the label is drawn, causing it to follow the sloping of the main +node. + + \begin{tikzpicture}[circuit ee IEC,every info/.style=red] + \draw (0,0) to[resistor={info sloped={$3\Omega$}}] (3,0) + to[resistor={info sloped={$4\Omega$}}] (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/info:sloped", + meta = "[⟨options⟩]⟨angle⟩:⟨text⟩" + }, + ["info'"] = { + details = [[ +This key works exactly like the `info` key, only in case the ⟨angle⟩ is +missing, it defaults to `below` instead of the current value of +`label position`, which is usually `above`. This means that when you use +`info`, you get a label above the node, while when you use the `info’` +key you get a label below the node. In case the node has been rotated, +the positions of the info nodes are rotated accordingly. + + \begin{tikzpicture}[circuit ee IEC,every info/.style=red] + \draw (0,0) to[resistor={info={$3\Omega$},info'={$R_1$}}] (3,0) + to[resistor={info={$4\Omega$},info'={$R_2$}}] (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/info'", + meta = "[⟨options⟩]⟨angle⟩:⟨text⟩" + }, + ["info' sloped"] = { + details = [[ +This is a combination of `info’` and `info sloped`. + + \begin{tikzpicture}[circuit ee IEC,every info/.style=red] + \draw (0,0) to[resistor={info' sloped={$3\Omega$}}] (3,0) + to[resistor={info' sloped={$4\Omega$}}] (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/info':sloped", + meta = "" + }, + initial = { + details = [[ +This style is used to draw initial states. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial" + }, + ["initial above"] = { + details = [[ +This is a shorthand for `initial by arrow,initial where=above`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:above" + }, + ["initial below"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:below" + }, + ["initial by arrow"] = { + details = [[ +This style causes an arrow and, possibly, some text to be added to the +node. The arrow points from the text to the node. The node text and the +direction and the distance can be set using the following key: + + \begin{tikzpicture}[every initial by arrow/.style={text=red,->>}] + \node[state,initial,initial distance=2cm] {$q_0$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:by:arrow" + }, + ["initial by diamond"] = { + details = [[ +This style uses a diamond to indicate an initial node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:by:diamond" + }, + ["initial distance"] = { + details = [[ +Sets the length of the arrow leading from the text to the state node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:distance", + meta = "⟨distance⟩" + }, + ["initial left"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:left" + }, + ["initial right"] = { + details = [[ +Works similarly to the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:right" + }, + ["initial text"] = { + details = [[ +This key sets the text to be used. Use an empty text to suppress all +text. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:text", + meta = "⟨text⟩" + }, + ["initial where"] = { + details = [[ +Set the place where the text should be shown. Allowed values are +`above`, `below`, `left`, and `right`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/initial:where", + meta = "⟨direction⟩" + }, + ["inner color"] = { + details = [[ +This option sets the color used at the center of a `radial` shading. +When this option is used, the `shade` and `shading=radial` options are +set. + + \tikz \draw[inner color=red] (0,0) rectangle (2,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/inner:color", + meta = "⟨color⟩" + }, + ["inner frame sep"] = { + details = [[ +Sets the horizontal and vertical separator distances simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/inner:frame:sep", + meta = "⟨dimension⟩" + }, + ["inner frame xsep"] = { + details = [[ +Sets the additional horizontal separator distance for the background +rectangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/inner:frame:xsep", + meta = "⟨dimension⟩" + }, + ["inner frame ysep"] = { + details = [[ +Same for the vertical separator distance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/inner:frame:ysep", + meta = "⟨dimension⟩" + }, + inputs = { + details = [[ +This key is defined only inside the scope of a `circuit logic`. There, +it has the same effect as `logic gate inputs`, described on page ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/inputs", + meta = "⟨inputs⟩" + }, + ["insert path"] = { + details = [[ +This key can be used inside an option to add something to the current +path. This is mostly useful for defining styles that create graphic +contents. This option should be used with care, for instance it should +not be used as an argument of, say, a `node`. In the following example, +we use a style to add little circles to a path. + + \tikz [c/.style={insert path={circle[radius=2pt]}}] + \draw (0,0) -- (1,1) [c] -- (3,2) [c]; + +The effect is the same as of +`(0,0) – (1,1) circle[radius=2pt] – (3,2) circle[radius=2pt]`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/insert:path", + meta = "⟨path⟩" + }, + ["intersection/by"] = { + details = [[ +This key allows you to specify a list of names for the intersection +coordinates. The intersection coordinates will still be named +⟨prefix⟩`-`⟨number⟩, but additionally the first coordinate will also be +named by the first element of the ⟨comma-separated list⟩. What happens +is that the ⟨comma-separated list⟩ is passed to the `\foreach` statement +and for ⟨list member⟩ a coordinate is created at the already-named +intersection. + + \begin{tikzpicture} + \clip (-2,-2) rectangle (2,2); + \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1); + \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2); + + \fill [name intersections={of=curve 1 and curve 2, by={a,b}}] + (a) circle (2pt) + (b) circle (2pt); + \end{tikzpicture} + +You can also use the `...` notation of the `\foreach` statement inside +the ⟨comma-separated list⟩. + +In case an element of the ⟨comma-separated list⟩ starts with options in +square brackets, these options are used when the coordinate is created. +A coordinate name can still, but need not, follow the options. This +makes it easy to add labels to intersections: + + \begin{tikzpicture} + \clip (-2,-2) rectangle (2,2); + \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1); + \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2); + + \fill [name intersections={ + of=curve 1 and curve 2, + by={[label=center:a],[label=center:...],[label=center:i]}}]; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/intersection/by", + meta = "⟨comma-separated list⟩" + }, + ["intersection/name"] = { + details = [[ +This key specifies the prefix name for the coordinate nodes placed at +each intersection. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/intersection/name", + meta = "⟨prefix⟩" + }, + ["intersection/of"] = { + details = [[ +This key is used to specify the names of the paths to use for the +intersection. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/intersection/of", + meta = "⟨name path 1⟩ and ⟨name path 2⟩" + }, + ["intersection/sort by"] = { + details = [[ +By default, the intersections are simply returned in the order that the +intersection algorithm finds them. Unfortunately, this is not +necessarily a "helpful" ordering. This key can be used to sort the +intersections along the path specified by ⟨path name⟩, which should be +one of the paths mentioned in the `/tikz/intersection/of` key. + + \begin{tikzpicture} + \clip (-0.5,-0.75) rectangle (3.25,2.25); + \foreach \pathname/\shift in {line/0cm, curve/2cm}{ + \tikzset{xshift=\shift} + \draw [->, name path=curve] (1,1.5) .. controls (-1,1) and (2,0.5) .. (0,0); + \draw [->, name path=line] (0,-.5) -- (1,2) ; + \fill [name intersections={of=line and curve,sort by=\pathname, name=i}] + [red, opacity=0.5, every node/.style={left=.25cm, black, opacity=1}] + \foreach \s in {1,2,3}{(i-\s) circle (2pt) node {\footnotesize\s}}; + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/intersection/sort:by", + meta = "⟨path name⟩" + }, + ["intersection/total"] = { + details = [[ +This key means that the total number of intersections found will be +stored in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/intersection/total", + meta = "⟨macro⟩" + }, + ["isometric view"] = { + details = [[ +A special kind of `3d view` is isometric, which can be set with the +`isometric view` style. It simply sets `3d view={-45}{35.26}`. The value +for ⟨elevation⟩ is determined with $\arctan(1/\sqrt{2})$. In isometric +projection the angle between any pair of axes is 120$^\circ$, as shown +below. + + \begin{tikzpicture}[isometric view] + \draw[->] (-1,0,0) -- (1,0,0) node[pos=1.1]{x}; + \draw[->] (0,-1,0) -- (0,1,0) node[pos=1.1]{y}; + \draw[->] (0,0,-1) -- (0,0,1) node[pos=1.1]{z}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/isometric:view" + }, + join = { + details = [[ +When this key is given to any node on a chain (except possibly for the +first node), an `edge` command is added after the node. The `with` part +specifies which node should be used for the start point of the edge; if +the `with` part is omitted, the `\tikzchainprevious` is used. This +`edge` command gets the ⟨options⟩ as parameter and the current node as +its target. If there is no previous node and no `with` is given, no +`edge` command gets executed. + +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{tikzpicture}[start chain,node distance=5mm, + every join/.style={->,red}] + \node [draw,on chain,join] {}; + \node [draw,on chain,join] {Hallo}; + \node [draw,on chain,join] {Welt}; + \node [draw,on chain=going below, + join,join=with chain-1 by {blue,<-}] {foo}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/join", + meta = "with ⟨with⟩ by ⟨options⟩" + }, + ["jump mark left"] = { + details = [[ +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: + + \tikz\draw plot[jump mark left, mark=*] file{plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/jump:mark:left" + }, + ["jump mark mid"] = { + details = [[ +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: + + \tikz\draw plot[jump mark mid, mark=*] file{plots/pgfmanual-sine.table}; + +In case of non-constant mesh widths, the same remarks as for +`const plot mark mid` apply. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/jump:mark:mid" + }, + ["jump mark right"] = { + details = [[ +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: + + \tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/jump:mark:right" + }, + ["key attribute"] = { + details = [[ +This style is intended for key attributes. By default, the will cause +the attribute to be typeset in italics. Typically, underlining is used +instead, but that looks ugly and it is difficult to implement in TeX. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/key:attribute" + }, + label = { + details = [[ +\[label-option\] When this option is given to a `node` operation, it +causes *another* node to be added to the path after the current node has +been finished. This extra node will have the text ⟨text⟩. It is placed, +in principle, in the direction ⟨angle⟩ relative to the main node, but +the exact rules are a bit complex. Suppose the `node` currently under +construction is called `main node` and let us call the label node +`label node`. Then the following happens: + +1. The ⟨angle⟩ is used to determine a position on the border of the + `main node`. If the ⟨angle⟩ is missing, the value of the following + key is used instead: + + The ⟨angle⟩ determines the position on the border of the shape in + two different ways. Normally, the border position is given by + `main node.`⟨angle⟩. This means that the ⟨angle⟩ can either be a + number like `0` or `-340`, but it can also be an anchor like + `north`. Additionally, the special angles `above`, `below`, `left`, + `right`, `above left`, and so on are automatically replaced by the + corresponding angles `90`, `270`, `180`, `0`, `135`, and so on. + + A special case arises when the following key is set: + +2. 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 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. You can set the anchor "by hand" using the + `anchor` key or indirect keys like `left`. + + \tikz + \node [circle, draw, + label=default, + label=60:$60^\circ$, + label=below:$-90^\circ$, + label=3:$3^\circ$, + label=2:$2^\circ$, + label={[below]180:$180^\circ$}, + label={[centered]135:$135^\circ$}] {my circle}; + +3. One ⟨angle⟩ is special: If you set the ⟨angle⟩ to `center`, then the + label will be placed on the center of the main node. This is mainly + useful for adding a label text to an existing node, especially if it + has been rotated. + + \tikz \node [transform shape,rotate=90, + rectangle,draw,label={[red]center:R}] {main node}; + +You can pass ⟨options⟩ to the node `label node`. For this, you provide +the options in square brackets before the ⟨angle⟩. If you do so, you +need to add braces around the whole argument of the `label` option and +this is also the case if you have brackets or commas or semicolons or +anything special in the ⟨text⟩. + + \tikz \node [circle,draw,label={[red]above:X}] {my circle}; + + \begin{tikzpicture} + \node [circle,draw,label={[name=label node]above left:$a,b$}] {}; + \draw (label node) -- +(1,1); + \end{tikzpicture} + +If you provide multiple `label` options, then multiple extra label nodes +are added in the order they are given. + +The following styles influence how labels are drawn: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/label", + meta = "[⟨options⟩]⟨angle⟩:⟨text⟩" + }, + ["label distance"] = { + details = [[ +The ⟨distance⟩ is additionally inserted between the main node and the +label node. + + \tikz[label distance=5mm] + \node [circle,draw,label=right:X, + label=above right:Y, + label=above:Z] {my circle}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/label:distance", + meta = "⟨distance⟩" + }, + ["label position"] = { + details = [[ +Sets the default position for labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/label:position", + meta = "⟨angle⟩" + }, + ["large circuit symbols"] = { + details = [[ +This style sets the default circuit symbol unit to `8pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/large:circuit:symbols" + }, + ["large mindmap"] = { + details = [[ +This style includes the `mindmap` style, but additionally changes the +default size of concepts, fonts and distances so that a medium-sized +mindmap will fit on an A3 page (A3 pages are twice as large as A4 +pages). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/large:mindmap" + }, + ["late options"] = { + details = [[ +This option can be given on a path (but not as an argument to a `node` +path command) and has the same effect as the `node also` path command. +Inside the ⟨options⟩, you should use the `name` option to specify the +node for which you wish to add late options: + + \begin{tikzpicture} + \node [draw,circle] (a) {Hello}; + \path [late options={name=a, label=above:world}]; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/late:options", + meta = "⟨options⟩" + }, + left = { + details = [[ +Similar to `above`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/left", + meta = "⟨offset⟩" + }, + ["left color"] = { + details = [[ +This option does exactly the same as `top color`, except that the +shading angle is set to $90^\circ$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/left:color", + meta = "⟨color⟩" + }, + ["left delimiter"] = { + details = [[ +This option can be given to a any node that has the standard anchors +`north`, `south` and so on. The ⟨delimiter⟩ can be any delimiter that is +acceptable to TeX's `\left` command. + + \begin{tikzpicture} + \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}] + { + a_8 & a_1 & a_6 \\ + a_3 & a_5 & a_7 \\ + a_4 & a_9 & a_2 \\ + }; + \end{tikzpicture} + + \begin{tikzpicture} + \node [fill=red!20,left delimiter=(,right delimiter=\}] + {$\displaystyle\int_0^1 x\,dx$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/left:delimiter", + meta = "⟨delimiter⟩" + }, + ["left of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/left:of", + meta = "⟨node⟩" + }, + lens = { + details = [[ +The ⟨options⟩ should contain transformation commands like `scale` or +`rotate`. These transformations are applied to the picture when it is +shown inside the spy-on node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/lens", + meta = "⟨options⟩" + }, + level = { + details = [[ +This style is executed at the beginning of each set of children, where +⟨number⟩ is the current level in the current tree. For example, when you +say `\node {x} child child;`, then `level=1` is used before the first +`child`. The style or code of this key will be passed ⟨number⟩ as its +first parameter. If this first `child` has children itself, then +`level=2` would be used for them. + + \begin{tikzpicture}[level/.style={sibling distance=20mm/#1}] + \node {root} + child { child child } + child { child child child }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level", + meta = "⟨number⟩" + }, + ["level 1 concept"] = { + details = [[ +The `mindmap` style adds this style to the `level 1` style. This means +that the first level children of a mindmap tree will use this style. + + \tikz + [root concept/.append style={concept color=blue!80}, + level 1 concept/.append style={concept color=red!50}, + mindmap] + \node [concept] {Root concept} + child[grow=30] {node[concept] {child}} + child[grow=0 ] {node[concept] {child}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:1:concept" + }, + ["level 2 concept"] = { + details = [[ +Works like `level 1 concept`, only for second level children. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:2:concept" + }, + ["level 3 concept"] = { + details = [[ +Works like `level 1 concept`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:3:concept" + }, + ["level 4 concept"] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:4:concept" + }, + ["level distance"] = { + details = [[ +This key determines the distance between different levels of the tree, +more precisely, between the parent and the line on which its children +are arranged. When given to a single child, this will set the distance +for this child only. + + \begin{tikzpicture} + \node {root} + [level distance=20mm] + child + child { + [level distance=5mm] + child + child + child + } + child[level distance=10mm]; + \end{tikzpicture} + + \begin{tikzpicture} + [level 1/.style={level distance=10mm}, + level 2/.style={level distance=5mm}] + \node {root} + child + child { + child + child[level distance=10mm] + child + } + child; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:distance", + meta = "⟨distance⟩" + }, + ["level ⟨number⟩"] = { + details = [[ +This style is used in addition to the `level` style. So, when you say +`\node {x} child child;`, then the following key list is executed: +`level=1,level 1`. + + \begin{tikzpicture} + [level 1/.style={sibling distance=20mm}, + level 2/.style={sibling distance=5mm}] + \node {root} + child { child child } + child { child child child }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/level:⟨number⟩" + }, + ["light emitting"] = { + details = [[ +Like a unit, an annotation should be given as an additional option to a +node. It causes some drawings (in this case, two parallel lines) to be +placed next to the node. + + \tikz [circuit ee IEC] \draw (0,0) to [diode=light emitting] (2,0); + +The ⟨options⟩ can be used for three different things: + +1. You can use keys like `red` to change the appearance of this + annotation, locally. + +2. You can use keys like `<-` or `-latex` to change the direction and + kinds of arrows used in the annotation. + +3. You can use info labels like `ohm=5` or `info=foo` inside the + ⟨options⟩. These info labels will be added to the main node (not to + the annotation itself), but the label distance will have been + changed to accommodate for the space taken up by the annotation. + + \tikz [circuit ee IEC] + { + \draw (0,2) to [diode={light emitting,info=not good}] (2,2); + \draw (0,0) to [diode={light emitting={info=better}, + info'=also good}] (2,0); + } + +In addition to `light emitting` there is also a key called +`light emitting’`, which simply places the annotation on the other side +of the node. + +You can configure the appearance of annotations in three ways: + +- You can set the `every circuit annotation` style. + +- You can set the `every light emitting` style. + +- You can set the following key: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/light:emitting", + meta = "⟨options⟩" + }, + ["line cap"] = { + details = [[ +Specifies how lines "end". Permissible ⟨type⟩ are `round`, `rect`, and +`butt`. They have the following effects: + + \begin{tikzpicture} + \begin{scope}[line width=10pt] + \draw[line cap=round] (0,1 ) -- +(1,0); + \draw[line cap=butt] (0,.5) -- +(1,0); + \draw[line cap=rect] (0,0 ) -- +(1,0); + \end{scope} + \draw[white,line width=1pt] + (0,0 ) -- +(1,0) (0,.5) -- +(1,0) (0,1 ) -- +(1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/line:cap", + meta = "⟨type⟩" + }, + ["line join"] = { + details = [[ +Specifies how lines "join". Permissible ⟨type⟩ are `round`, `bevel`, and +`miter`. They have the following effects: + + \begin{tikzpicture}[line width=10pt] + \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); % enlarge bounding box + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/line:join", + meta = "⟨type⟩" + }, + ["line to"] = { + details = [[ +Causes a straight line to be added to the path upon a `to` or an `edge` +operation. + + \tikz {\draw (0,0) to[line to] (1,0);} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/line:to" + }, + ["line width"] = { + details = [[ +Specifies the line width. Note the space. + + \tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/line:width", + meta = "⟨dimension⟩" + }, + loop = { + details = [[ +This key is similar to the `curve to` key, but differs in the following +ways: First, the actual target coordinate is ignored and the start +coordinate is used as the target coordinate. Thus, it is allowed not to +provide any target coordinate, which can be useful with unnamed nodes. +Second, the `looseness` is set to `8` and the `min distance` to `5mm`. +These settings result in rather nice loops when the opening angle +(difference between `in` and `out`) is 30$^\circ$. + + \begin{tikzpicture} + \node [circle,draw] {a} edge [in=30,out=60,loop] (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loop" + }, + ["loop above"] = { + details = [[ +Sets the `loop` style and sets in and out angles such that loop is above +the node. Furthermore, the `above` option is set, which causes a node +label to be placed at the correct position. + + \begin{tikzpicture} + \node [circle,draw] {a} edge [loop above] node {x} (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loop:above" + }, + ["loop below"] = { + details = [[ +Works like the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loop:below" + }, + ["loop left"] = { + details = [[ +Works like the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loop:left" + }, + ["loop right"] = { + details = [[ +Works like the previous option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loop:right" + }, + ["loose background"] = { + details = [[ +Sets the inner frame separator to 2ex. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loose:background" + }, + ["loosely dash dot"] = { + details = [[ +Shorthand for setting a loosely dashed and dotted dash pattern. + + \tikz \draw[loosely dash dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loosely:dash:dot" + }, + ["loosely dash dot dot"] = { + details = [[ +Shorthand for setting a loosely dashed and dotted dash pattern with more +dots. + + \tikz \draw[loosely dash dot dot] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loosely:dash:dot:dot" + }, + ["loosely dashed"] = { + details = [[ +Shorthand for setting a loosely dashed dash pattern. + + \tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loosely:dashed" + }, + ["loosely dotted"] = { + details = [[ +Shorthand for setting a loosely dotted dash pattern. + + \tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/loosely:dotted" + }, + looseness = { + details = [[ +This number specifies how "loose" the curve will be. In detail, the +following happens: TikZ computes the distance between the start and the +target coordinate (if the start and/or target coordinate are nodes, the +distance is computed between the points on their border). This distance +is then multiplied by a fixed factor and also by the factor ⟨number⟩. +The resulting distance, let us call it $d$, is then used as the distance +of the control points from the start and target coordinates. + +The fixed factor has been chosen in such a way that if ⟨number⟩ is `1`, +if the `in` and `out` angles differ by 90$\circ$, then a quarter circle +results: + + \tikz \draw (0,0) to [out=0,in=-90] (1,1); + \tikz \draw (0,0) to [out=0,in=-90,looseness=0.5] (1,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/looseness", + meta = "⟨number⟩" + }, + ["lower left"] = { + details = [[ +Sets the color to be used in a `bilinear interpolation` shading for the +lower left corner. Also, this options selects this shading and sets the +`shade` option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/lower:left", + meta = "⟨color⟩" + }, + ["lower right"] = { + details = [[ +Works like `lower left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/lower:right", + meta = "⟨color⟩" + }, + magnification = { + details = [[ +This has the same effect as saying `lens={scale=`⟨number⟩`}`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/magnification", + meta = "⟨number⟩" + }, + ["make snapshot after"] = { + details = [[ +Works exactly like `make snapshot of`, only the ⟨time⟩ is interpreted as +$⟨time⟩ + \epsilon$. This only makes a difference at the end of a +timeline and when there are two or more values specified for the same +time: When there are several values specified for time $t$, a normal +snapshot for time $t$ uses the first value given for the attribute. In +contrast, this command would use the last one given. Similarly, when an +animation timeline ends at time $t$, a normal snapshot of time $t$ would +use the last value of the timeline, while this key would not apply the +animation at all (it has already ended at time $t + \epsilon$). + + \tikz [make snapshot of = 2s] + \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1); + \tikz [make snapshot after = 2s] + \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/make:snapshot:after", + meta = "⟨time⟩" + }, + ["make snapshot if necessary"] = { + details = [[ +This key makes a snapshot of ⟨time⟩ only when the output format does not +provide support for animations; if the output format supports animations +(like SVG), then the command has no effect and animations are created +normally. + +This manual is typeset with the following being set once are for all in +preamble: + + \tikzset{make snapshot if necessary} + +Because of this setting, in the PDF version of this document, all +animations are shown at the value they would have at moment $0s$. In +contrast, in the SVG version, the animations are created normally. + +In both versions, the smaller pictures showing how the animation +proceeds over time are created using `make snapshot of` for the +indicated times. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/make:snapshot:if:necessary", + meta = "⟨time⟩" + }, + ["make snapshot of"] = { + details = [[ +When this key is used in a TeX scope, animation commands given in the +scope do not add animation code to the output. Instead, TikZ computes +the values the attributes of the animation would have at the specified +⟨time⟩ and inserts the necessary system layer command to set the +attribute to the computed values (some care has been taken to make this +computation match the computations done by viewer applications as best +as possible). + + \tikz [make snapshot of = 1s] { + \fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1); + \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1); + } + +The moment ⟨time⟩ is best thought of as ⟨time⟩ seconds after the "moment +zero" where all timelines start by default. Now, "real" animation may +start at different time through user interaction, which clearly makes no +sense for snapshots. Nevertheless, you will sometimes wish to have more +control over when a timeline starts for the purposes of taking +snapshots. You can use the following key for this: + +The computations of the values the animation "would have" are done +entirely by TikZ, which has the big advantage is that no support from +the viewer application or the output format is needed -- snapshots work +with all output formats, not just with SVG. However, computations done +by TikZ are not always very precise and can be slow because of TeX's +limitations. In addition, there are some further limitations when it +comes to TikZ's computation of snapshot values: + +- As mentioned above, except for `begin snapshot`, other commands for + specifying the beginning or end of a timeline based on user + interaction make no sense for timelines: The keys `begin`, + `begin on`, `end`, and `end on` are silently ignored. + +- The value `current value` for a value is forbidden since this value + is almost impossible to compute by TikZ. + +- Accumulating repeats of a motion are (currently) not supported, but + should not rely on this. + +When ⟨time⟩ is empty, "snapshot taking" is switched off and animation +commands are inserted once more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/make:snapshot:of", + meta = "⟨time⟩" + }, + mark = { + details = [[ +Sets the mark to a mnemonic that has previously been defined using the +`\pgfdeclareplotmark`. By default, `*`, `+`, and `x` are available, +which draw a filled circle, a plus, and a cross as marks. Many more +marks become available when the library `plotmarks` is loaded. +Section ?? lists the available plot marks. + +One plot mark is special: the `ball` plot mark is available only in +TikZ. 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. + + Option Effect + --------------------- -------- + height14pt width0pt +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark", + meta = "⟨mark mnemonic⟩" + }, + ["mark indices"] = { + details = [[ +This option allows you to specify explicitly the indices at which a mark +should be placed. Counting starts with 1. You can use the `\foreach` +syntax, that is, `...` can be used. + + \tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth] + file {plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark:indices", + meta = "⟨list⟩" + }, + ["mark options"] = { + details = [[ +Redefines `every mark` such that it sets `{options}`. + + \tikz \fill[fill=blue!20] + plot[mark=triangle*,mark options={color=blue,rotate=180}] + file{plots/pgfmanual-sine.table} |- (0,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark:options", + meta = "⟨options⟩" + }, + ["mark phase"] = { + details = [[ +This option tells TikZ that the first mark to be draw should be the +$p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on. + + \tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark:phase", + meta = "⟨p⟩" + }, + ["mark repeat"] = { + details = [[ +This option tells TikZ that only every $r$th mark should be drawn. + + \tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark:repeat", + meta = "⟨r⟩" + }, + ["mark size"] = { + details = [[ +Sets the size of the plot marks. For circular plot marks, ⟨dimension⟩ is +the radius, for other plot marks ⟨dimension⟩ should be about half the +width and height. + +This option is not really necessary, since you achieve the same effect +by specifying `scale=`⟨factor⟩ as a local option, where ⟨factor⟩ is the +quotient of the desired size and the default size. However, using +`mark size` is a bit faster and more natural. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mark:size", + meta = "⟨dimension⟩" + }, + matrix = { + details = [[ +This option can be passed to a `node` path command. It signals that the +node will contain a matrix. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (4,2); + \node [matrix,fill=red!20,draw=blue,very thick] (my matrix) at (2,1) + { + \draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\ + \draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\ + }; + + \draw [very thick,->] (0,0) |- (my matrix.west); + \end{tikzpicture} + +The exact syntax of the matrix is explained in the course of this +section. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix", + meta = "⟨true or false⟩" + }, + ["matrix anchor"] = { + details = [[ +This option has the same effect as `anchor`, but the option applies only +to the matrix itself, not to the cells inside. If you just say +`anchor=north` as an option to the matrix node, all nodes inside matrix +will also have this anchor, unless it is explicitly set differently for +each node. By comparison, `matrix anchor` sets the anchor for the +matrix, but for the nodes inside the value of `anchor` remain unchanged. + + \begin{tikzpicture} + \matrix [matrix anchor=west] at (0,0) + { + \node {123}; \\ % still center anchor + \node {12}; \\ + \node {1}; \\ + }; + \matrix [anchor=west] at (0,-2) + { + \node {123}; \\ % inherited west anchor + \node {12}; \\ + \node {1}; \\ + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix:anchor", + meta = "⟨anchor⟩" + }, + ["matrix of math nodes"] = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix:of:math:nodes" + }, + ["matrix of nodes"] = { + details = [[ +Conceptually, this key adds `\node{` at the beginning and `};` at the +end of each cell and sets the `anchor` of the node to `base`. +Furthermore, it adds the option `name` option to each node, where the +name is set to ⟨matrix name⟩`-`⟨row number⟩`-`⟨column number⟩. For +example, if the matrix has the name `my matrix`, then the node in the +upper left cell will get the name `my matrix-1-1`. + + \begin{tikzpicture} + \matrix (magic) [matrix of nodes] + { + 8 & 1 & 6 \\ + 3 & 5 & 7 \\ + 4 & 9 & 2 \\ + }; + + \draw[thick,red,->] (magic-1-1) |- (magic-2-3); + \end{tikzpicture} + +You may wish to add options to certain nodes in the matrix. This can be +achieved in three ways. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix:of:nodes" + }, + ["matrix/inner style order"] = { + details = [[ +The order in which these styles are applied to the matrix cells is +specified by this key. By default it is + + \tikzset{ + matrix/inner style order={ + every cell, + column, + even odd column, + row, + even odd row, + cell, + }, + } + +You can use this to install your own styles here, but only *names* of +styles are permitted here. The style specification has to be placed +outside of `matrix/inner style order` and unless it is installed inside +`/tikz/matrix/inner style/`, it has to be fully qualified. + + \tikzset{ + my style/.code={% + \ifnum\pgfmatrixcurrentcolumn=2 + \tikzset{font=\itshape}% + \fi + }, + matrix/inner style order={ + every cell, + even odd column, + even odd row, + column, + row, + cell, + /tikz/my style, + }, + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style:order" + }, + ["matrix/inner style/cell"] = { + details = [[ +Wraps `/tikz/row `⟨number⟩` column `⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/cell" + }, + ["matrix/inner style/column"] = { + details = [[ +Wraps `/tikz/column `⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/column" + }, + ["matrix/inner style/even odd column"] = { + details = [[ +Wraps `/tikz/every even column` and `/tikz/every odd column`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/even:odd:column" + }, + ["matrix/inner style/even odd row"] = { + details = [[ +Wraps `/tikz/every even row` and `/tikz/every odd row`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/even:odd:row" + }, + ["matrix/inner style/every cell"] = { + details = [[ +Wraps `/tikz/every cell`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/every:cell" + }, + ["matrix/inner style/row"] = { + details = [[ +Wraps `/tikz/row `⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/matrix/inner:style/row" + }, + ["max distance"] = { + details = [[ +If the computed distance for the start and target coordinates are above +⟨distance⟩, then ⟨distance⟩ is used instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/max:distance", + meta = "⟨distance⟩" + }, + ["medium circuit symbols"] = { + details = [[ +This style sets the default circuit symbol unit to `7pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/medium:circuit:symbols" + }, + meet = { + details = [[ +Use this key with a scope to establish a view for the scope. In the +argument to the `meet` key, both `rectangle` texts are optional. Also, +everything following `at` is optional; when it is missing, the ⟨window +corner⟩s are assumed to be the same as the ⟨to-be-viewed corner⟩s. The +latter are two corners of a rectangle that should be transformed in such +a way that it fits inside the rectangle described by the two window +corners. + +More precisely, at the beginning of the scope a canvas transformation is +installed that scales and translates the canvas is such a way that + +1. the center of the to-be-viewed rectangle lies at the center of the + window rectangle and + +2. the to-be-viewed rectangle has maximum size that it still fits + inside the window rectangle. + +  + + \tikz { + \draw [red, very thick] (0,0) rectangle (20mm,20mm); + \begin{scope}[meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}] + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi}; + \end{scope} } + + \tikz { + \draw [red, very thick] (0,0) rectangle (20mm,20mm); + \begin{scope}[slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}] + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi}; + \end{scope} } + +As mentioned earlier, the main use of views is in conjunction with +animations. In order to animate a view, you specify the scope containing +the `meet` command as the target object and then animate its `:view` +attribute: + + \tikz [animate = { + my scope:view = { + begin on = { click, of next = here }, + 0s = "{(0.5,0.5) (2.5,1.5)}", + 2s = "{(0.5,0) (1.5,2)}", forever + }}] { + \draw [red, fill=red!20, very thick, name=here] + (0,0) rectangle (20mm,20mm); + \begin{scope}[name = my scope, + meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}] + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi}; + \end{scope} } + +You can, of course, also specify the animation using the +`animate myself:` key when you specify the animation inside the scope: + + \tikz [animate = { + my scope:view = { + }}] { + \draw [red, fill=red!20, very thick, name=here] + (0,0) rectangle (20mm,20mm); + \begin{scope}[animate = { myself: = { :view = { + begin on = { click, of = here }, + 0s = "{(0.5,0.5) (2.5,1.5)}", + 2s = "{(0.5,0) (1.5,2)}", forever }}}, + slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}] + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi}; + \end{scope} } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/meet", + meta = "⟨to-be-viewed corner⟩ rectangle ⟨to-be-viewed corner⟩ at ⟨window corner⟩ rectangle ⟨window corner⟩" + }, + ["mid left"] = { + details = [[ +Works like `base left`, but with `mid east` and `mid west` anchors +instead of `base east` and `base west`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mid:left", + meta = "⟨specification⟩" + }, + ["mid right"] = { + details = [[ +Works like `mid left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mid:right", + meta = "⟨specification⟩" + }, + ["middle color"] = { + details = [[ +This option specifies the color for the middle of an axis shading. It +also sets the `shade` and `shading=axis` options, but it does not change +the rotation angle. + +*Note:* Since both `top color` and `bottom color` change the middle +color, this option should be given *last* if all of these options need +to be given: + + \tikz \draw[top color=white,bottom color=black,middle color=red] + (0,0) rectangle (2,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/middle:color", + meta = "⟨color⟩" + }, + midway = { + details = [[ +This has the same effect as `pos=0.5`. + + \tikz \draw (0,0) .. controls +(up:2cm) and +(left:3cm) .. (1,5) + 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}}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/midway" + }, + ["min distance"] = { + details = [[ +If the computed distance for the start and target coordinates are below +⟨distance⟩, then ⟨distance⟩ is used instead. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/min:distance", + meta = "⟨distance⟩" + }, + mindmap = { + details = [[ +Use this style with all pictures or at least scopes that contain a +mindmap. It installs a whole bunch of settings that are useful for +drawing mindmaps. + + \tikz[mindmap,concept color=red!50] + \node [concept] {Root concept} + child[grow=right] {node[concept] {Child concept}}; + +The sizes of concepts are predefined in such a way that a medium-size +mindmap will fit on an A4 page (more or less). + +#### 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 + +`level 1 concept/.append style={font=\small}` + +or + +`level 2 concept/.append style={sibling distance=90}` + +*after* the `mindmap` style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/mindmap" + }, + missing = { + details = [[ +If this option is given to a child, the current child counter is +increased, but the child is otherwise ignored. In particular, the normal +contents of the child is completely ignored. + + \begin{tikzpicture}[level distance=10mm,sibling distance=5mm] + \node {root} [grow=down] + child { node {1} } + child { node {2} } + child { node {3} } + child[missing] { node {4} } + child { node {5} } + child { node {6} }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/missing", + meta = "⟨true or false⟩" + }, + ["miter limit"] = { + details = [[ +When you use the miter join and there is a very sharp corner (a small +angle), the miter join may protrude very far over the actual joining +point. In this case, if it were to protrude by more than ⟨factor⟩ times +the line width, the miter join is replaced by a bevel join. + + \begin{tikzpicture}[line width=5pt] + \draw (0,0) -- ++(5,.5) -- ++(-5,.5); + \draw[miter limit=25] (6,0) -- ++(5,.5) -- ++(-5,.5); + \useasboundingbox (14,0); % make bounding box bigger + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/miter:limit", + meta = "⟨factor⟩" + }, + ["month code"] = { + details = [[ +This option allows you to specify what the macro `\tikzmonthcode` should +expand to. + +By default, the `\tikzmonthcode` it is set to + + \node[every month]{\tikzmonthtext}; + +Note that this node is not named by default. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:code", + meta = "⟨code⟩" + }, + ["month label above centered"] = { + details = [[ +Works as above, only the label is centered above the row containing the +first day. + + \tikz + \calendar [dates=2000-02-01 to 2000-02-last, + day list right,month label above centered]; + + \tikz + \calendar [dates=2000-01-20 to 2000-02-10, + week list,month label above centered]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:above:centered" + }, + ["month label above left"] = { + details = [[ +This style places the month label above of the row of the first day, +flushed left to the leftmost column. The amount by which the label is +raised is fixed to `1.25em`; use the `yshift` option with the month node +to modify this. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list right,month xshift=1em, + month label above left]; + + \tikz + \calendar [dates=2000-01-20 to 2000-02-10, + week list,month label above left]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:above:left" + }, + ["month label above right"] = { + details = [[ +Works as above, but flushed right + + \tikz + \calendar [dates=2000-01-20 to 2000-02-10, + week list,month label above right]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:above:right" + }, + ["month label below centered"] = { + details = [[ +Works like `month label above centered`, only below. + + \tikz + \calendar [dates=2000-02-01 to 2000-02-last, + day list right,month label below centered]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:below:centered" + }, + ["month label below left"] = { + details = [[ +Works like `month label above left`, only the label is placed below the +row. This placement is not really useful with the `week list` +arrangement, but rather with the `day list right` or `month list` +arrangement. + + \tikz + \calendar [dates=2000-02-01 to 2000-02-last, + day list right,month label below left]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:below:left" + }, + ["month label left"] = { + details = [[ +Places the month label to the left of the first day of the month. (For +`week list` and `month list` where a month does not start on a Monday, +the position is chosen "as if" the month had started on a Monday -- +which is usually exactly what you want.) + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list downward,month yshift=1em, + month label left]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:left" + }, + ["month label left vertical"] = { + details = [[ +This style works like the above style, only the label is rotated +counterclockwise by 90 degrees. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list downward,month yshift=1em, + month label left vertical]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:left:vertical" + }, + ["month label right"] = { + details = [[ +This style places the month label to the right of the row in which the +first day of the month lies. This means that for a day list the label is +to the right of the first day, for a week list it is to the right of the +first week, and for a month list it is to the right of the whole month. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list downward,month yshift=1em, + month label right]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:right" + }, + ["month label right vertical"] = { + details = [[ +Works as above, only the label is rotated clockwise by 90 degrees. + + \tikz + \calendar [dates=2000-01-28 to 2000-02-03, + day list downward,month yshift=1em, + month label right vertical]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:label:right:vertical" + }, + ["month list"] = { + details = [[ +In this arrangement there is a row for each month. As for the +`week list`, the `day xshift` is used for the horizontal distance. For +the vertical shift, `month yshift` is used. + +In each row, all days of the month are listed alongside each other. +However, it is once more ensured that days in each column lie on the +same day of week. Thus, the very first column contains only Mondays. If +a month does not start with a Monday, its days are shifted to the right +such that the days lie on the correct columns. + + \sffamily\scriptsize + \tikz + \calendar [dates=2000-01-01 to 2000-12-31, + month list,month label left,month yshift=1.25em] + if (Sunday) [black!50]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:list" + }, + ["month text"] = { + details = [[ +This option allows you to change the macro `\tikzmonthtext`. By default, +the month text is a long textual presentation of the current month being +typeset. + + \tikz \calendar[dates=2000-01-01 to 2000-01-31,week list, + month label above centered, + month text=\textcolor{red}{\%mt} \%y-]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:text", + meta = "⟨text⟩" + }, + ["month xshift"] = { + details = [[ +Specifies an additional horizontal shift between different months. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:xshift", + meta = "⟨dimension⟩" + }, + ["month yshift"] = { + details = [[ +Specifies an additional vertical shift between different months. + + \tikz \calendar[dates=2000-01-01 to 2000-02-last,week list, + month yshift=0pt]; + + \tikz \calendar[dates=2000-01-01 to 2000-02-last,week list, + month yshift=1cm]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/month:yshift", + meta = "⟨dimension⟩" + }, + ["move to"] = { + details = [[ +Causes a move to be added to the path upon a `to` or an `edge` +operation. + + \tikz \draw (0,0) to[line to] (1,0) + to[move to] (2,0) to[line to] (3,0); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/move:to" + }, + name = { + details = [[ +Assigns a name to the node for later reference. Since this is a +"high-level" name (drivers never know of it), you can use spaces, +number, letters, or whatever you like when naming a node. Thus, you can +name a node just `1` or perhaps `start of chart` or even `y_ 1`. Your +node name should *not* contain any punctuation like a dot, a comma, or a +colon since these are used to detect what kind of coordinate you mean +when you reference a node. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/name", + meta = "⟨node name⟩" + }, + ["name intersections"] = { + details = [[ +This key changes the key path to `/tikz/intersection` and processes +⟨options⟩. These options determine, among other things, which paths to +use for the intersection. Having processed the options, any +intersections are then found. A coordinate is created at each +intersection, which by default, will be named `intersection-1`, +`intersection-2`, and so on. Optionally, the prefix `intersection` can +be changed, and the total number of intersections stored in a TeX-macro. + + \begin{tikzpicture}[every node/.style={opacity=1, black, above left}] + \draw [help lines] grid (3,2); + \draw [name path=ellipse] (2,0.5) ellipse (0.75cm and 1cm); + \draw [name path=rectangle, rotate=10] (0.5,0.5) rectangle +(2,1); + \fill [red, opacity=0.5, name intersections={of=ellipse and rectangle}] + (intersection-1) circle (2pt) node {1} + (intersection-2) circle (2pt) node {2}; + \end{tikzpicture} + +The following keys can be used in ⟨options⟩: + + \begin{tikzpicture} + \clip (-2,-2) rectangle (2,2); + \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1); + \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2); + + \fill [name intersections={of=curve 1 and curve 2, name=i, total=\t}] + [red, opacity=0.5, every node/.style={above left, black, opacity=1}] + \foreach \s in {1,...,\t}{(i-\s) circle (2pt) node {\footnotesize\s}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/name:intersections", + meta = "{options}" + }, + ["name prefix"] = { + details = [[ +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 `(`⟨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: + + \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); + } + +As can be seen, name prefixing makes it easy to write reusable code. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/name:prefix", + meta = "⟨text⟩" + }, + ["name prefix .."] = { + details = [[ +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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/name:prefix:.." + }, + ["name suffix"] = { + details = [[ +Works as `name prefix`, only the ⟨text⟩ is appended to every node name +in the current scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/name:suffix", + meta = "⟨text⟩" + }, + ["near end"] = { + details = [[ +Set to `pos=0.75`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/near:end" + }, + ["near start"] = { + details = [[ +Set to `pos=0.25`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/near:start" + }, + ["nearly opaque"] = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/nearly:opaque" + }, + ["nearly transparent"] = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/nearly:transparent" + }, + ["new set"] = { + details = [[ +This will setup a node set named ⟨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 +*outside* the `graph` command. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/new:set", + meta = "⟨set name⟩" + }, + ["no markers"] = { + details = [[ +Disables markers (the same as `mark=none`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/no:markers" + }, + ["no marks"] = { + details = [[ +Disables markers (the same as `mark=none`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/no:marks" + }, + ["node contents"] = { + details = [[ +\[option-node-contents\] This key sets the 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 ⟨node contents⟩ may not contain fragile stuff since the +catcodes get fixed upon reading the options. Here is an example: + + \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] ; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/node:contents", + meta = "⟨node contents⟩" + }, + ["node distance"] = { + details = [[ +The value of this key is used as ⟨shifting part⟩ is used if and only if +a ⟨of-part⟩ is present, but no ⟨shifting part⟩. + + \begin{tikzpicture}[every node/.style=draw,node distance=5mm] + \draw[help lines] (0,0) grid (2,3); + + % Not gridded + \node (a1) at (0,0) {not gridded}; + \node (b1) [above=of a1] {fooy}; + \node (c1) [above=of b1] {a}; + + % gridded + \begin{scope}[on grid] + \node (a2) at (2,0) {gridded}; + \node (b2) [above=of a2] {fooy}; + \node (c2) [above=of b2] {a}; + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/node:distance", + meta = "⟨shifting part⟩" + }, + ["node font"] = { + details = [[ +This option sets the font used for all text used in a node. + + \begin{tikzpicture} + \draw[node font=\itshape] (1,0) -- +(1,1) node[above] {italic}; + \end{tikzpicture} + +Since the ⟨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 +⟨font commands⟩: + + \tikz \node [node font=\tiny, minimum height=3em, draw] {tiny}; + \tikz \node [node font=\small, minimum height=3em, draw] {small}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/node:font", + meta = "⟨font commands⟩" + }, + ["node halign header"] = { + details = [[ +This is the key that is used by `align` internally for alignment without +line breaking. Read the following only if you are familiar with the +`\halign` command. + +This key only has an effect if `text width` is empty, otherwise it is +ignored. Furthermore, if ⟨macro storing a header⟩ is empty, then this +key also has no effect. So, suppose `text width` is empty, but ⟨header⟩ +is not. In this case the following happens: + +When the node text is parsed, the command `\\` is redefined internally. +This redefinition is done in such a way that the text from the start of +the node to the first occurrence of `\\` is put in an `\hbox`. Then the +text following `\\` up to the next `\\` is put in another `\hbox`. This +goes on until the text between the last `\\` and the closing `}` is also +put in an `\hbox`. + +The ⟨macro storing a header⟩ should be a macro that contains some text +suitable for use as a header for the `\halign` command. For instance, +you might define + + \def\myheader{\hfil\hfil##\hfil\cr} + \tikz [node halign header=\myheader] ... + +You cannot just say `node halign header=\hfil\hfil# \hfil\cr` because +this confuses TeX inside matrices, so this detour via a macro is needed. + +Next, conceptually, all these boxes are recursively put inside an +`\halign` command. Assuming that ⟨first⟩ is the first of the above +boxes, the command `\halign{`⟨header⟩ `\box`⟨first⟩ `\cr}` is used to +create a new box, which we will call the ⟨previous box⟩. Then, the +following box is created, where ⟨second⟩ is the second input box: +`\halign{`⟨header⟩ `\box`⟨previous box⟩ `\cr` `\box`⟨second⟩`\cr}`. Let +us call the resulting box the ⟨previous box⟩ once more. Then the next +box that is created is `\halign{`⟨header⟩ `\box`⟨previous box⟩ `\cr` +`\box`⟨third⟩`\cr}`. + +All of this means that if ⟨header⟩ is an `\halign` header like +`\hfil# \hfil\cr`, then all boxes will be centered relative to one +another. Similarly, a ⟨header⟩ of `\hfil# \cr` causes the text to be +flushed right. + +Note that this mechanism is not flexible enough to all multiple columns +inside ⟨header⟩. You will have to use a `tabular` or a `matrix` in such +cases. + +One further note: Since the text of each line is placed in a box, +settings will be local to each "line". This is very similar to the way a +cell in a `tabular` or a `matrix` behaves. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/node:halign:header", + meta = "⟨macro storing a header⟩" + }, + ["node quotes mean"] = { + details = [[ +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 + +> `"`⟨text⟩`"``’`⟨options⟩ + +is encountered, the following happens: The above string gets replaced by +⟨replacement⟩ where inside the ⟨replacement⟩ the parameter `# 1` is +⟨text⟩ and `# 2` is ⟨options⟩. If the apostrophe is present (see also +the discussion of `quotes mean label`), the ⟨options⟩ start with `’,`. + +The ⟨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`: + + \tikzset{node quotes mean={label={[#2,name={#1}]#1}}} + + \tikz { + \node ["1", "2" label position=left, circle, draw] {circle}; + \draw (1) -- (2); + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/node:quotes:mean", + meta = "⟨replacement⟩" + }, + nodes = { + details = [[ +This key adds the ⟨options⟩ to the style `every node`. It is mainly just +a shorthand for the code `every node/.append style=`⟨options⟩. + +The main use of this option is the install some options for the nodes +*inside* the matrix that should not apply to the matrix *itself*. + + \begin{tikzpicture} + \matrix [nodes={fill=blue!20,minimum size=5mm}] + { + \node {8}; & \node{1}; & \node {6}; \\ + \node {3}; & \node{5}; & \node {7}; \\ + \node {4}; & \node{9}; & \node {2}; \\ + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/nodes", + meta = "⟨options⟩" + }, + ["nodes in empty cells"] = { + details = [[ +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`. + + \begin{tikzpicture} + \matrix [matrix of math nodes,nodes={circle,draw}] + { + a_8 & & a_6 \\ + a_3 & & a_7 \\ + a_4 & a_9 & \\ + }; + \end{tikzpicture} + + \begin{tikzpicture} + \matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells] + { + a_8 & & a_6 \\ + a_3 & & a_7 \\ + a_4 & a_9 & \\ + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/nodes:in:empty:cells", + meta = "⟨true or false⟩" + }, + ["nonzero rule"] = { + details = [[ +If this rule is used (which is the default), the following method is +used to determine whether a given point is "inside" the path: From the +point, shoot a ray in some direction towards infinity (the direction is +chosen such that no strange borderline cases occur). Then the ray may +hit the path. Whenever it hits the path, we increase or decrease a +counter, which is initially zero. If the ray hits the path as the path +goes "from left to right" (relative to the ray), the counter is +increased, otherwise it is decreased. Then, at the end, we check whether +the counter is nonzero (hence the name). If so, the point is deemed to +lie "inside", otherwise it is "outside". Sounds complicated? It is. + + \begin{tikzpicture} + \filldraw[fill=yellow!80!black] + % Clockwise rectangle + (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle + % Counter-clockwise rectangle + (0.25,0.25) -- (0.75,0.25) -- (0.75,0.75) -- (0.25,0.75) -- cycle; + + \draw[->] (0,1) -- (.4,1); + \draw[->] (0.75,0.75) -- (0.3,.75); + + \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$}; + + \begin{scope}[yshift=-3cm] + \filldraw[fill=yellow!80!black] + % Clockwise rectangle + (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle + % Clockwise rectangle + (0.25,0.25) -- (0.25,0.75) -- (0.75,0.75) -- (0.75,0.25) -- cycle; + + \draw[->] (0,1) -- (.4,1); + \draw[->] (0.25,0.75) -- (0.4,.75); + + \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $1+1 = 2$}; + \end{scope} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/nonzero:rule" + }, + ["numbered faces"] = { + details = [[ +Sets `face `⟨i⟩ to `\node {`⟨i⟩`};` for all $i$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/numbered:faces" + }, + ohm = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ohm", + meta = "⟨value⟩" + }, + ["on background layer"] = { + details = [[ +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 ⟨options⟩ will be executed *inside* background scope. This is useful +since *other* options passed to the `{scope}` environment will be +executed *before* the actual background material starts and, thus, will +have no effect on it. + + \begin{tikzpicture} + % On main layer: + \fill[blue] (0,0) circle (1cm); + + \begin{scope}[on background layer={color=yellow}] + \fill (-1,-1) rectangle (1,1); + \end{scope} + + \begin{scope}[on background layer] + \fill[black] (-.8,-.8) rectangle (.8,.8); + \end{scope} + + % On main layer again: + \fill[blue!50] (-.5,-1) rectangle (.5,1); + \end{tikzpicture} + +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 ?? 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: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/on:background:layer", + meta = "⟨options⟩" + }, + ["on chain"] = { + details = [[ +This key should be given as an option to a node. When the option is +used, the ⟨chain name⟩ must be the name of a chain that has been started +using the `start chain` option. If ⟨chain name⟩ is the empty string, the +current value of the innermost activated chain is used. If this option +is used several times for a node, only the last invocation "wins". (To +place a node on several chains, use the `\chainin` command repeatedly.) + +The ⟨direction⟩ part is optional. If present, it sets the direction used +for this node, otherwise the ⟨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 default). + +The effects of this option are the following: + +1. 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. + + The value of this internal counter is globally stored in the macro + `\tikzchaincount`. + +2. 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 + ⟨chain name⟩`-`⟨value of the internal chain counter⟩. For instance, + if the chain is called `nums`, the first node would be named + `nums-1`, the second `nums-2`, and so on. For the default chain name + `chain`, the first node is named `chain-1`, the second `chain-2`, + and so on. + +3. Independently of whether the name has been provided automatically or + via the `name` option, the name of the node is globally stored in + the macro `\tikzchaincurrent`. + +4. Except for the first node, the macro `\tikzchainprevious` is now + globally set to the name of the node of the previous node on the + chain. For the first node of the chain, this macro is globally set + to the empty string. + +5. Except possibly for the first node of the chain, the placement rule + is now executed. The placement rule is just a TikZ option that is + applied automatically to each node on the chain. Depending on the + form of the ⟨direction⟩ parameter (either the locally given one or + the one given to the `start chain` option), different things happen. + + First, it makes a difference whether the ⟨direction⟩ starts with + `going` or with `placed`. The difference is that in the first case, + the placement rule is not applied to the first node of the chain, + while in the second case the placement rule is applied also to this + first node. The idea is that a `going`-direction indicates that we + are "going somewhere relative to the previous node" whereas a + `placed` indicates that we are "placing nodes according to their + number". + + Independently of which form is used, the ⟨text⟩ inside ⟨direction⟩ + that follows `going` or `placed` (separated by a compulsory space) + can have two different effects: + + 1. If it contains an equal sign, then this ⟨text⟩ is used as the + placement rule, that is, it is simply executed. + + 2. If it does not contain an equal sign, then + ⟨text⟩`=of \tikzchainprevious` is used as the placement rule. + + Note that in the first case, inside the ⟨text⟩ you have access to + `\tikzchainprevious` and `\tikzchaincount` for doing your + positioning calculations. + + \begin{tikzpicture}[start chain=circle placed {at=(\tikzchaincount*30:1.5)}] + \foreach \i in {1,...,10} + \node [on chain] {\i}; + + \draw (circle-1) -- (circle-10); + \end{tikzpicture} + +6. The following style is executed: + +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`. + + \begin{tikzpicture}[start chain,node distance=5mm] + \node [draw,on chain] {}; + \node [draw,on chain] {Hallo}; + \node [draw,on chain] {Welt}; + \end{tikzpicture} + +The optional ⟨direction⟩ allows us to temporarily change the direction +in the middle of a chain: + + \begin{tikzpicture}[start chain,node distance=5mm] + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,on chain=going below] {,}; + \node [draw,on chain] {this}; + \node [draw,on chain] {is}; + \end{tikzpicture} + +You can also use more complicated computations in the ⟨direction⟩: + + \begin{tikzpicture}[start chain=going {at=(\tikzchainprevious),shift=(30:1)}] + \draw [help lines] (0,0) grid (3,2); + \node [draw,on chain] {1}; + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,on chain] {.}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/on:chain", + meta = "⟨chain name⟩⟨direction⟩" + }, + ["on grid"] = { + details = [[ +When this key is set to `true`, an ⟨of-part⟩ of the current form behaves +differently: The anchors set for the current node as well as the anchor +used for the other ⟨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 will be placed in such a way that +its center is 1cm above the center of `somenode`. Repeatedly placing +nodes in this way will result in nodes that are centered on "grid +coordinate", hence the name of the option. + + \begin{tikzpicture}[every node/.style=draw] + \draw[help lines] (0,0) grid (2,3); + + % Not gridded + \node (a1) at (0,0) {not gridded}; + \node (b1) [above=1cm of a1] {fooy}; + \node (c1) [above=1cm of b1] {a}; + + % gridded + \node (a2) at (2,0) {gridded}; + \node (b2) [on grid,above=1cm of a2] {fooy}; + \node (c2) [on grid,above=1cm of b2] {a}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/on:grid", + meta = "⟨boolean⟩" + }, + ["only marks"] = { + details = [[ +This option causes only marks to be shown; no path segments are added to +the actual path. This can be useful for quickly adding some marks to a +path. + + \tikz \draw (0,0) sin (1,1) cos (2,0) + plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/only:marks" + }, + opacity = { + details = [[ +Sets both the drawing and filling opacity to ⟨value⟩. + +The following predefined styles make it easier to use this option: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/opacity", + meta = "⟨value⟩" + }, + opaque = { + details = [[ +This yields completely opaque drawings, which is the default. + + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[opaque] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/opaque" + }, + out = { + details = [[ +The angle at which the curve leaves the start coordinate. If the start +coordinate is a node, the start coordinate is the point on the border of +the node at the given ⟨angle⟩. The control point will, thus, lie at a +certain distance in the direction ⟨angle⟩ from the start coordinate. + + \begin{tikzpicture}[out=45,in=135] + \draw (0,0) to (1,0) + (0,0) to (2,0) + (0,0) to (3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out", + meta = "⟨angle⟩" + }, + ["out control"] = { + details = [[ +This option causes the ⟨coordinate⟩ to be used as the start control +point. All computations of $d$ are ignored. You can use a coordinate +like `+(1,0)` to specify a point relative to the start coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out:control", + meta = "⟨coordinate⟩" + }, + ["out distance"] = { + details = [[ +Sets the minimum and maximum out distance. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out:distance", + meta = "⟨distance⟩" + }, + ["out looseness"] = { + details = [[ +Specifies the looseness factor for the out distance only. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out:looseness", + meta = "⟨number⟩" + }, + ["out max distance"] = { + details = [[ +The maximum distance set only for the start coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out:max:distance", + meta = "⟨distance⟩" + }, + ["out min distance"] = { + details = [[ +The minimum distance set only for the start coordinate. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/out:min:distance", + meta = "⟨distance⟩" + }, + ["outer color"] = { + details = [[ +This option sets the color used at the border and outside of a `radial` +shading. + + \tikz \draw[outer color=red,inner color=white] + (0,0) rectangle (2,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/outer:color", + meta = "⟨color⟩" + }, + ["outer frame sep"] = { + details = [[ +Sets both the $x$- and $y$-separation. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/outer:frame:sep", + meta = "⟨dimension⟩" + }, + ["outer frame xsep"] = { + details = [[ +The ⟨dimension⟩ is added at the left and right side of the line. + + \begin{tikzpicture} + [background rectangle/.style={fill=yellow}, + framed, + show background top, + outer frame xsep=1ex] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/outer:frame:xsep", + meta = "⟨dimension⟩" + }, + ["outer frame ysep"] = { + details = [[ +This option does not apply to the top line, but to the left and right +lines, see below. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/outer:frame:ysep", + meta = "⟨dimension⟩" + }, + overlay = { + details = [[ +This option is mainly intended for use when nodes in other pictures are +referenced, but you can also use it in other situations. The effect of +this option is that everything within the current scope is not taken +into consideration when the bounding box of the current picture is +computed. + +You need to specify this option on all paths (or at least on all parts +of paths) that contain a reference to a node in another picture. The +reason is that, otherwise, TikZ will attempt to make the current picture +large enough to encompass *the node in the other picture*. However, on a +second run of TeX this will create an even bigger picture, leading to +larger and larger pictures. Unless you know what you are doing, I +suggest specifying the `overlay` option with all pictures that contain +references to other pictures. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/overlay", + meta = "⟨boolean⟩" + }, + ["parabola height"] = { + details = [[ +This option has the same effect as +`[bend pos=0.5,bend={+(0pt,`⟨dimension⟩`)}]`. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (-1,0) parabola[parabola height=2cm] +(3,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/parabola:height", + meta = "⟨dimension⟩" + }, + parametric = { + details = [[ +Sets whether the plot is a parametric plot. If true, then `t` must be +used instead of `x` as the parameter and two comma-separated functions +must be given in the ⟨gnuplot formula⟩. An example is the following: + + \tikz \draw[scale=0.5,domain=-3.141:3.141,smooth] + plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/parametric", + meta = "⟨boolean⟩" + }, + ["parent anchor"] = { + details = [[ +This option works the same way as the `child anchor`, only for the +parent. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/parent:anchor", + meta = "⟨anchor⟩" + }, + ["path fading"] = { + details = [[ +This option tells TikZ that the current path should be faded with the +fading ⟨name⟩. If no ⟨name⟩ is given, the ⟨name⟩ set for the whole scope +is used. Similarly to options like `draw` or `fill`, this option is +reset for each path, so you have to add it to each path that should be +faded. You can also specify `none` as ⟨name⟩, in which case fading for +the path will be switched off in case it has been switched on by +previous options or styles. + + \begin{tikzpicture}[path fading=south] + % Checker board + \fill [black!20] (0,0) rectangle (4,3); + \pattern [pattern=checkerboard,pattern color=black!30] + (0,0) rectangle (4,3); + + \fill [color=blue] (0.5,1.5) rectangle +(1,1); + \fill [color=blue,path fading=north] (2.5,1.5) rectangle +(1,1); + + \fill [color=red,path fading] (1,0.75) ellipse (.75 and .5); + \fill [color=red] (3,0.75) ellipse (.75 and .5); + \end{tikzpicture} + +Note that you can "fade just about anything". In particular, you can +fade a shading. + + \begin{tikzpicture} + % Checker board + \fill [black!20] (0,0) rectangle (4,4); + \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4); + + \shade [ball color=blue,path fading=south] (2,2) circle (1.8); + \end{tikzpicture} + +The `fade inside` of the following example is more transparent in the +middle than on the outside. + + \tikzfading[name=fade inside, + inner color=transparent!80, + outer color=transparent!30] + \begin{tikzpicture} + % Checker board + \fill [black!20] (0,0) rectangle (4,4); + \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4); + + \shade [ball color=red] (3,3) circle (0.8); + \shade [ball color=white,path fading=fade inside] (2,2) circle (1.8); + \end{tikzpicture} + +Note that adding the `path fading` option to a node fades the +(background) path, not the text itself. To fade the text, you need to +use a scope fading (see below). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/path:fading", + meta = "⟨name⟩" + }, + ["path picture"] = { + details = [[ +When this option is given on a path and when the ⟨code⟩ is not empty, +the following happens: After all other "filling" operations are done +with the path, which are caused by the options `fill`, `pattern` and +`shade`, a local scope is opened and the path is temporarily installed +as a clipping path. Then, the ⟨code⟩ is executed, which can now draw +something. Then, the local scope ends 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 no effect (the +path picture is cleared at the beginning of each path). + +The ⟨code⟩ can be any normal TikZ code like `\draw ...` 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 was when +the path was being constructed and not -- as one might expect -- at the +lower left corner of the path. However, you can use the following +special node to access the size of the path: + +path picture bounding box This node is of shape `rectangle`. Its size +and position are those of `current path bounding box` just before the +⟨code⟩ of the path picture started to be executed. The ⟨code⟩ can +construct its own paths, so accessing the `current path bounding box` +inside the ⟨code⟩ yields the bounding box of any path that is currently +being constructed inside the ⟨code⟩. + + \begin{tikzpicture} + \draw [help lines] (0,0) grid (3,2); + \filldraw [fill=blue!10,draw=blue,thick] (1.5,1) circle (1) + [path picture={ + \node at (path picture bounding box.center) { + This is a long text. + };} + ]; + \end{tikzpicture} + + \begin{tikzpicture}[cross/.style={path picture={ + \draw[black] + (path picture bounding box.south east) -- + (path picture bounding box.north west) + (path picture bounding box.south west) -- + (path picture bounding box.north east); + }}] + \draw [help lines] (0,0) grid (3,2); + \filldraw [cross,fill=blue!10,draw=blue,thick] (1,1) circle (1); + \path [cross,top color=red,draw=red,thick] (2,0) -- (3,2) -- (3,0); + \end{tikzpicture} + + \begin{tikzpicture}[path image/.style={ + path picture={ + \node at (path picture bounding box.center) { + \includegraphics[height=3cm]{#1} + };}}] + \draw [help lines] (0,0) grid (3,2); + + \draw [path image=brave-gnu-world-logo,draw=blue,thick] + (0,1) circle (1); + \draw [path image=brave-gnu-world-logo,draw=red,very thick,->] + (1,0) parabola[parabola height=2cm] (3,0); + + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/path:picture", + meta = "⟨code⟩" + }, + pattern = { + details = [[ +This option causes the path to be filled with a pattern. If the ⟨name⟩ +is given, this pattern is used, otherwise the pattern set in the +enclosing scope is used. As for the `draw` and `fill` options, setting +⟨name⟩ to `none` disables filling locally. + +The pattern works like a fill color. In particular, setting a new fill +color will fill the path with a solid color once more. + +Strangely, no ⟨name⟩s are permissible by default. You need to load for +instance the `patterns` library, see Section ??, to install predefined +patterns. + + \begin{tikzpicture} + \draw[pattern=dots] (0,0) circle (1cm); + \draw[pattern=fivepointed stars] (0,0) rectangle (3,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pattern", + meta = "⟨name⟩" + }, + ["pattern color"] = { + details = [[ +This option is used to set the color to be used for form-only patterns. +This option has no effect on inherently colored patterns. + + \begin{tikzpicture} + \draw[pattern color=red,pattern=fivepointed stars] (0,0) circle (1cm); + \draw[pattern color=blue,pattern=fivepointed stars] (0,0) rectangle (3,1); + \end{tikzpicture} + + \begin{tikzpicture} + \def\mypath{(0,0) -- +(0,1) arc (180:0:1.5cm) -- +(0,-1)} + \fill [red] \mypath; + \pattern[pattern color=white,pattern=bricks] \mypath; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pattern:color", + meta = "⟨color⟩" + }, + ["patterns/bottom left"] = { + details = [[ +Instead of a PGF name point, this key takes a TikZ point, +e.g. `(-.1,-.1)`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/bottom:left", + meta = "⟨point⟩" + }, + ["patterns/bounding box"] = { + details = [[ +This is a shorthand to set the bounding box. It will assign the first +point to `bottom left` and the second point to `top right`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/bounding:box", + meta = "⟨point⟩ and ⟨point⟩" + }, + ["patterns/infer tile bounding box"] = { + details = [[ +Instead of specifying the bounding box by hand, you can ask TikZ to +infer the size of the bounding box for you. The ⟨dimension⟩ parameter is +padding that is added around the bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/infer:tile:bounding:box", + meta = "⟨dimension⟩" + }, + ["patterns/tile size"] = { + details = [[ +Instead of a PGF name point, this key takes a TikZ point, e.g. `(3,3)`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/tile:size", + meta = "⟨point⟩" + }, + ["patterns/tile transformation"] = { + details = [[ +Instead of a PGF transformation, this key takes a list of keys and value +and extracts the resulting transformation from them, e.g. `rotate=30`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/tile:transformation", + meta = "⟨transformation⟩" + }, + ["patterns/top right"] = { + details = [[ +Instead of a PGF name point, this key takes a TikZ point, +e.g. `(3.1,3.1)`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/patterns/top:right", + meta = "⟨point⟩" + }, + perspective = { + details = [[ +The 'strength' of the perspective can be determined by setting the +location of the vanishing points. The default values have a stronger +perspective towards $x$ and $y$ than towards $z$, as shown below. + + \begin{tikzpicture}[3d view,perspective] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} + +From this example it also shows that the maximum dimensions of the +cuboid are no longer 2 by 2 by 2. This is inherent to the perspective +projection. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/perspective", + meta = "⟨vanishing points⟩" + }, + ["perspective/p"] = { + details = [[ +The location of the vanishing point that determines the 'strength' of +the perspective in $x$-direction can be set with the `p` key. + + \begin{tikzpicture}[ + 3d view, + perspective={ + p = {(5,0,0)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} + +Note also that when only `p` is provided, the perspective in $y$ and $z$ +direction is turned off. + +To turn off the perspective in $x$-direction, one must set the $x$ +component of `p` to `0` (e.g. `p={(0,a,b)}`, where `a` and `b` can be +any number and will be ignored). Or one can provide `q` and `r` and omit +`p`. + +By changing the $y$ and $z$ components of `p`, one can achieve various +effects. + + \begin{tikzpicture}[ + 3d view, + perspective={ + p = {(5,0,1)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} + + \begin{tikzpicture}[ + 3d view, + perspective={ + p = {(5,1,0)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} + + \begin{tikzpicture}[ + 3d view, + perspective={ + p = {(5,1,1)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/perspective/p", + meta = "{x,y,z}" + }, + ["perspective/q"] = { + details = [[ +Similar to `p`, but can be turned off by setting its $y$ component to +`0`. + + \begin{tikzpicture}[ + 3d view, + perspective={ + q = {(0,5,0)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/perspective/q", + meta = "{x,y,z}" + }, + ["perspective/r"] = { + details = [[ +Similar to `p`, but can be turned off by setting its $z$ component to +`0`. + + \begin{tikzpicture}[ + 3d view, + perspective={ + r = {(0,0,5)}}] + \simplecuboid{2}{2}{2} + \simpleaxes{2}{2}{2} + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/perspective/r", + meta = "{x,y,z}" + }, + ["pic actions"] = { + details = [[ +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 ⟨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: + + \tikzset{ + my pic/.pic = { + \path [pic actions] (0,0) circle[radius=3mm]; + \draw (-3mm,-3mm) rectangle (3mm,3mm); + } + } + +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. + + (0,0) circle[radius=3mm]; + \draw (-3mm,-3mm) rectangle (3mm,3mm); + } + }}] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pic:actions" + }, + ["pic text"] = { + details = [[ +This macro stores the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pic:text", + meta = "⟨text⟩" + }, + ["pic text options"] = { + details = [[ +This macro stores the ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pic:text:options", + meta = "⟨options⟩" + }, + ["pic type"] = { + details = [[ +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.) + + (0,0) to [bend left] (3mm,0); + }, + }}] + \tikz { + \path (0,0) pic [pic type = seagull] + (1,0) pic {seagull}; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pic:type", + meta = "⟨pic type⟩" + }, + ["pics/background code"] = { + details = [[ +Like `foreground code`, only that the ⟨code⟩ is always put behind the +path, except when the `behind path` option is applied to the pic, then +the background code is drawn in front of the "behind path" code. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pics/background:code", + meta = "⟨code⟩" + }, + ["pics/code"] = { + details = [[ +This key stores the ⟨code⟩ that should be drawn in the current pic. +Normally, setting this key is done by the ⟨pic type⟩, but you can also +set it in the ⟨options⟩ and leave the ⟨pic type⟩ empty: + + \tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0) + to[bend left] (3mm,0);}] + {}; % no pic type specified +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pics/code", + meta = "⟨code⟩" + }, + ["pics/foreground code"] = { + details = [[ +This key stores ⟨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 ⟨code⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pics/foreground:code", + meta = "⟨code⟩" + }, + pin = { + details = [[ +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: + + \tikz \node [circle,fill=blue!50,minimum size=1cm,pin=60:$q_0$] {}; + +The meaning of the ⟨options⟩ and the ⟨angle⟩ and the ⟨text⟩ is exactly +the same as for the `node` option. Only, the options and styles the +influence the way pins look are different: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pin", + meta = "[⟨options⟩]⟨angle⟩:⟨text⟩" + }, + ["pin distance"] = { + details = [[ +This ⟨distance⟩ is used instead of the `label distance` for the distance +between the main node and the label node. + + \tikz[pin distance=1cm] + \node [circle,draw,pin=right:X, + pin=above right:Y, + pin=above:Z] {my circle}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pin:distance", + meta = "⟨distance⟩" + }, + ["pin edge"] = { + details = [[ +This option can be used to set the options that are to be used in the +edge created by the `pin` option. + + \tikz[pin distance=10mm] + \node [circle,draw,pin={[pin edge={blue,thick}]right:X}, + pin=above:Z] {my circle}; + + \tikz [every pin edge/.style={}, + initial/.style={pin={[pin distance=5mm, + pin edge={<-,shorten <=1pt}]left:start}}] + \node [circle,draw,initial] {my circle}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pin:edge", + meta = "⟨options⟩" + }, + ["pin position"] = { + details = [[ +The default pin position. Works like `label position`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pin:position", + meta = "⟨angle⟩" + }, + place = { + details = [[ +This style indicates that a node is a place of a Petri net. Usually, the +text of the node should be empty since places do not contain any text. +You should use the `label` option to add text outside the node like its +name or its capacity. You should use the `tokens` options, explained in +Section ??, to add tokens inside the place. + + \begin{tikzpicture} + \node[place,label=above:$p_1$,tokens=2] (p1) {}; + \node[place,label=below:$p_2\ge1$,right=of p1] (p2) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/place" + }, + ["plane origin"] = { + details = [[ +Origin of the plane. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/plane:origin", + meta = "⟨point⟩" + }, + ["plane x"] = { + details = [[ +Unit vector of the $x$-direction in the new plane. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/plane:x", + meta = "⟨point⟩" + }, + ["plane y"] = { + details = [[ +Unit vector of the $y$-direction in the new plane. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/plane:y", + meta = "⟨point⟩" + }, + ["point down"] = { + details = [[ +This is the same as `rotate=-90`. + + \tikz [circuit ee IEC] \node [diode,point down] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/point:down" + }, + ["point left"] = { + details = [[ +This is the same as `rotate=-180`. + + \tikz [circuit ee IEC] \node [diode,point left] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/point:left" + }, + ["point right"] = { + details = [[ +This key has no effect. + + \tikz [circuit ee IEC] \node [diode,point right] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/point:right" + }, + ["point up"] = { + details = [[ +This is the same as `rotate=90`. + + \tikz [circuit ee IEC] \node [diode,point up] {}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/point:up" + }, + ["polar comb"] = { + details = [[ +This option causes a line from the origin to the point to be added to +the path for each plot point. + + \tikz \draw plot[polar comb, + mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt] + coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/polar:comb" + }, + pos = { + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pos", + meta = "⟨fraction⟩" + }, + post = { + details = [[ +This style is also used with paths leading *from* a transition *to* a +place, but this time the place is in the post-set of the transition. +Again, feel free to redefine it. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/post" + }, + postaction = { + details = [[ +The postactions work in the same way as the preactions, only they are +applied *after* the main action has been taken. Like preactions, +multiple `postaction` options may be given to a `\path` command, in +which case the path is reused several times, each time with a different +set of options in force. + +If both pre- and postactions are specified, then the preactions are +taken first, then the main action, and then the post actions. + +In the first example, we use a postaction to draw the path, after it has +already been drawn: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \draw + [postaction={draw,line width=2mm,blue}] + [line width=4mm,red,fill=white] (0,0) rectangle (2,2); + \end{tikzpicture} + +In another example, we use a postaction to "colorize" a path: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw + [postaction={path fading=south,fill=white}] + [postaction={path fading=south,fading angle=45,fill=blue,opacity=.5}] + [left color=black,right color=red,draw=white,line width=2mm] + (0,0) rectangle (1,2) + (1,2) circle (5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/postaction", + meta = "⟨options⟩" + }, + pre = { + details = [[ +This style can be used with paths leading *from* a transition *to* a +place to indicate that the place is in the pre-set of the transition. By +default, this style is `<-,shorten <=1pt`, but feel free to redefine it. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pre" + }, + ["pre and post"] = { + details = [[ +This style is to be used to indicate that a place is both in the pre- +and post-set of a transition. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/pre:and:post" + }, + preaction = { + details = [[ +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 `\path` or as +part of the options of a `node`; as an option to a `{scope}` it has no +effect. + +When this option is used on a `\path`, the effect is the following: When +the path has been completely constructed and is about to be used, a +scope is created. Inside this scope, the path is used but not with the +original path options, but with ⟨options⟩ instead. Then, the path is +used in the usual manner. In other words, the path is used twice: Once +with ⟨options⟩ in force and then again with the normal path options in +force. + +Here is an example in which the path consists of a rectangle. The main +action is to draw this path in red (which is why we see a red +rectangle). However, the preaction is to draw the path in blue, which is +why we see a blue rectangle behind the red rectangle. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \draw + [preaction={draw,line width=4mm,blue}] + [line width=2mm,red] (0,0) rectangle (2,2); + \end{tikzpicture} + +Note that when the preactions are preformed, then the path is already +"finished". In particular, applying a coordinate transformation to the +path has no effect. By comparison, applying a canvas transformation does +have an effect. Let us use this to add a "shadow" to a path. For this, +we use the preaction to fill the path in gray, shifted a bit to the +right and down: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw + [preaction={fill=black,opacity=.5, + transform canvas={xshift=1mm,yshift=-1mm}}] + [fill=red] (0,0) rectangle (1,2) + (1,2) circle (5mm); + \end{tikzpicture} + +Naturally, you would normally create a style `shadow` that contains the +above code. The `shadows` library, see Section ??, contains predefined +shadows of this kind. + +It is possible to use the `preaction` option multiple times. In this +case, for each use of the `preaction` option, the path is used again +(thus, the ⟨options⟩ do not accumulate in a single usage of the path). +The path is used in the order of `preaction` options given. + +In the following example, we use one `preaction` to add a shadow and +another to provide a shading, while the main action is to use a pattern. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw [pattern=fivepointed stars] + [preaction={fill=black,opacity=.5, + transform canvas={xshift=1mm,yshift=-1mm}}] + [preaction={top color=blue,bottom color=white}] + (0,0) rectangle (1,2) + (1,2) circle (5mm); + \end{tikzpicture} + +A complicated application is shown in the following example, where the +path is used several times with different fadings and shadings to create +a special visual effect: + + \begin{tikzpicture} + [ + % Define an interesting style + button/.style={ + % First preaction: Fuzzy shadow + preaction={fill=black,path fading=circle with fuzzy edge 20 percent, + opacity=.5,transform canvas={xshift=1mm,yshift=-1mm}}, + % Second preaction: Background pattern + preaction={pattern=#1, + path fading=circle with fuzzy edge 15 percent}, + % Third preaction: Make background shiny + preaction={top color=white, + bottom color=black!50, + shading angle=45, + path fading=circle with fuzzy edge 15 percent, + opacity=0.2}, + % Fourth preaction: Make edge especially shiny + preaction={path fading=fuzzy ring 15 percent, + top color=black!5, + bottom color=black!80, + shading angle=45}, + inner sep=2ex + }, + button/.default=horizontal lines light blue, + circle + ] + + \draw [help lines] (0,0) grid (4,3); + + \node [button] at (2.2,1) {\Huge Big}; + \node [button=crosshatch dots light steel blue, + text=white] at (1,1.5) {Small}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/preaction", + meta = "⟨options⟩" + }, + prefix = { + details = [[ +The ⟨prefix⟩ is put before each plot file name. The default is +`\jobname.`, but if you have many plots, it might be better to use, say +`plots/` and have all plots placed in a directory. You have to create +the directory yourself. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/prefix", + meta = "⟨prefix⟩" + }, + ["prefix after command"] = { + details = [[ +Works like `append after command`, only the accumulation order is +inverse: The ⟨path⟩ is added before any earlier paths added using either +`append after command` or `prefix after command`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/prefix:after:command", + meta = "⟨path⟩" + }, + ["quotes mean label"] = { + details = [[ +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. + +**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 TikZ do not start with +quotation marks). When this happens, the ⟨string⟩ should not be a +key--value pair, but, rather, must have the form: + +> `"`⟨text⟩`"``’`⟨options⟩ + +(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). + +**Transformation to a label option.** When a ⟨string⟩ has the above +form, it is treated (almost) as if you had written + +> `label={[`⟨options⟩`]`⟨text⟩`}` + +instead. The "almost" refers to the following additional feature: In +reality, before the ⟨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 ⟨text⟩ relative to the main node you can just put +something like `left` or `above right` inside the ⟨options⟩: + + \tikz + \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; + +Alternatively, you can also use ⟨direction⟩`:`⟨actual text⟩ as your +⟨text⟩. This works since the `label` command allows you to specify a +direction at the beginning when it is separated by a colon: + + \tikz + \node ["90:$90^\circ$", "left:$180^\circ$", circle, draw] {circle}; + +Arguably, placing `above` or `left` behind the ⟨text⟩ seems more natural +than having it inside the ⟨text⟩. + +In addition to the above, before the ⟨options⟩ are executed, the +following style is also executed: + +**Handling commas and colons inside the text.** The ⟨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 ⟨text⟩: + + \tikz \node ["{yes, we can}", draw] {foo}; + +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: + + \tikz \node ["yes{:} we can", draw] {foo}; + +**The optional apostrophe.** Following the closing quotation marks in a +⟨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 ⟨options⟩ as another option (and, indeed, a single +apostrophe is a legal option in TikZ, it is a shorthand for `swap`): + + String has the same effect as + ---------------- -------------------------------------------------- + `"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’`) +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/quotes:mean:label" + }, + ["quotes mean pin"] = { + details = [[ +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: + + \tikz [quotes mean pin] + \node ["$90^\circ$" above, "$180^\circ$" left, circle, draw] {circle}; + +Instead of `every label quotes`, the following style is executed with +each such pin: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/quotes:mean:pin" + }, + radius = { + details = [[ +Sets the `x radius` and `y radius` simultaneously. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/radius", + meta = "⟨value⟩" + }, + range = { + details = [[ +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: + + \tikz \draw[scale=0.5,domain=-3.141:3.141, samples=100, smooth, range=-3:3] + plot[id=tan-example] function{tan(x)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/range", + meta = "⟨start⟩:⟨end⟩" + }, + ["raw gnuplot"] = { + details = [[ +This key causes the ⟨gnuplot formula⟩ to be passed on to GNUPLOT without +setting up the samples or the `plot` operation. Thus, you could write + + plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)} + +This can be useful for complicated things that need to be passed to +GNUPLOT. However, for really complicated situations you should create a +special external generating GNUPLOT file and use the `file`-syntax to +include the table "by hand". +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/raw:gnuplot" + }, + ["rdf engine"] = { + details = [[ +This key only has an effect when `rdf engine on` is called, otherwise +the argument is silently ignored. The ⟨rdf keys⟩ get executed with the +path prefix `/tikz/rdf engine` at the beginning of the current scope +(for a node, at the beginning of the node's scope). Depending on which +keys are used, semantic information gets to be added to the output. + +Note that you cannot simply the keys with path prefix `/tikz/rdf engine` +directly since they need to be executed at very specific times during +TikZ's processing of scopes. Always call those keys via this key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine", + meta = "⟨rdf keys⟩" + }, + ["rdf engine on"] = { + details = [[ +Switches "on" the generation of RDF information for the current +TeX scope. The idea is that libraries can internally use the +`rdf engine` key (explained below) a lot in order to provide good +semantic information in the output when desired, but need not worry that +this will bloat output files since users have to use this key explicitly +to include semantic information in the output. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine:on" + }, + ["rdf engine/get new resource curie"] = { + details = [[ +The ⟨macro⟩ will be set to a new unique curie that can be used anywhere +where a curie is allowed. Here is an example how we can add a state and +a transition container to an automaton, both of which have no +corresponding scope in TikZ. + + \tikz [ name = my automaton, + rdf engine = { + get new resource curie = \statecurie, + get new resource curie = \transitiocurie, + statement = { + subject = (my automaton), + predicate = automata:hasStateSet, + object = \statecurie }, + statement = { + subject = \statecurie, + hat type = automata:stateSet }, + statement = { + subject = (my automaton), + predicate = automata:hasTransitionSet, + object = \transitiocurie }, + statement = { + subject = \transitiocurie, + hat type = automata:transitionSet } } ] { ... } + +The ⟨macro⟩ will be valid for the whole scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/get:new:resource:curie", + meta = "⟨macro⟩" + }, + ["rdf engine/get scope curie"] = { + details = [[ +The ⟨macro⟩ will be set to a unique curie that represents the scope or +node. If the scope is named (using the `name` key or the special +parenthesis syntax for nodes) and this name is later referenced in +another statement, the same curie will be generated. Note how in the +following code no name is given for the automaton, which means that the +whole RDF code could be moved inside a style like `finite automaton` or +something similar. + + \tikz [ rdf engine = { + get new resource curie = \statecurie, + get new resource curie = \transitiocurie, + get scope curie = \automatoncurie, + statement = { + subject = \automatoncurie, + predicate = automata:hasStateSet, + object = \statecurie }, + statement = { + subject = \statecurie, + hat type = automata:stateSet }, + statement = { + subject = \automatoncurie, + predicate = automata:hasTransitionSet, + object = \transitiocurie }, + statement = { + subject = \transitiocurie, + hat type = automata:transitionSet } } ] { ... } + +The ⟨macro⟩ will be valid for the whole scope. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/get:scope:curie", + meta = "⟨macro⟩" + }, + ["rdf engine/prefix"] = { + details = [[ +Inside the current scope, you can use ⟨prefix⟩`:` inside curies (compact +universal resource identifier expressions, see the RDFA specification) +as an abbreviation for the ⟨iri⟩. (It has the same effect as the +`prefix` attribute in RDFa.) You can use this key several times for a +given scope. + + \scoped [rdf engine = { + prefix = {rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark}, + prefix = {automata: http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/}, + statement = { ..., predicate = rdf:type, object = automata:state }, + statement = { ..., predicate = rdf:type, object = automata:final }, + }] ... + +The above could also be written more verbosely as + + \scoped [rdf engine = { + statement = { ..., + predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type, + object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/state } + }, + statement = { ..., + predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type, + object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/final } + }] ... + +The use of the command `\tikzrdfhashmark` is necessary since TeX assigns +a special meaning to hash marks. The command simple expands to a +"normal" hash mark for use in texts. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/prefix", + meta = "⟨prefix: iri⟩" + }, + ["rdf engine/scope is new context"] = { + details = [[ +This key executes `get scope curie=\tikzrdfcontext`, thereby setting the +macro `\tikzrdfcontext` to the current scope. The idea is the key is +used with "major resources" and that keys can use this macro as the +`subject` of statements if no subject is given explicitly. For instance, +a `title` key might be defined as follows: + + title/.style = { + rdf engine = { statement = { + subject = \tikzrdfcontext, + predicate = dc:Title, + object = "#1" + } } } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/scope:is:new:context" + }, + ["rdf engine/statement"] = { + details = [[ +Each use of this key will add one RDF statement to the output file. The +⟨options⟩ will be executed with the path prefix +`/tikz/rdf engine/statements` and must use the three keys `subject`, +`predicate`, and `object` to specify the three components of the +statement (these keys can, however, be called by styles internally, so +not all statements will explicitly set these three keys). Note that *all +three must always be set*, it is *not* possible to setup, say, just a +subject for a scope and then omit the subject for statements inside the +scope. (However, using styles you can setup things in such a way that a +certain subject is used for several statements.) + + \tikz [rdf engine = { + statement = { + subject = http://www.example.org/persons/Einstein, + predicate = http://www.example.org/predicates/isA, + object = http://www.example.org/professions/physicist + }, + statement = { + subject = http://www.example.org/persons/Curie, + predicate = http://www.example.org/predicates/isA, + object = http://www.example.org/professions/physicist + }}] { ... } + +The statements are normally added at the beginning of the scope where +the `rdf enging` command is used (except when the `object` is +`scope content`, which is explained later). This means that when you use +`prefix` inside an `rdf engine` command, it will apply to all +statements, regardless of the order. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statement", + meta = "{options}" + }, + ["rdf engine/statements/has as member"] = { + details = [[ +This key may only be added to statements whose subject was previously +used as a subject in a statement containing the `is a container` key. In +this case, the internal counter will be increased and the predicate will +be set to `rdf:_ `⟨count⟩. This means that we can write the above code +as: + + \tikz { ... + + \scoped [rdf engine = { + statement = { + subject = (safe), + has type = rdf:Seq, + is a container, + }, + statement = { + subject = (safe), + has as member, + object = (coins) + }, + statement = { + subject = (safe), + has as member, + object = (gold) + } }]; + } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/has:as:member" + }, + ["rdf engine/statements/has type"] = { + details = [[ +This style is a shorthand for `predicate=rdf:type` and `object=`⟨type⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/has:type", + meta = "⟨type⟩" + }, + ["rdf engine/statements/is a bag"] = { + details = [[ +This is a shorthand for `predicate = rdf:Bag, is a container`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/is:a:bag" + }, + ["rdf engine/statements/is a container"] = { + details = [[ +Add this key to a statement in order to tell TikZ that it should setup a +special counter for the subject of the statement that keeps track of the +container's children. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/is:a:container" + }, + ["rdf engine/statements/is a sequence"] = { + details = [[ +This is a shorthand for `predicate = rdf:Seq, is a container`. In the +above example we could say: + + \tikz { ... + + \scoped [rdf engine = { + statement = { + subject = (safe), + is a sequence + }, + ... } ]; } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/is:a:sequence" + }, + ["rdf engine/statements/is an alternative"] = { + details = [[ +This is a shorthand for `predicate = rdf:Alt, is a container`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/is:an:alternative" + }, + ["rdf engine/statements/object"] = { + details = [[ +Sets the object for the statement. The syntax allowed for the ⟨object⟩ +is as follows: + +1. As for `subject` and `predicate` you can use a curie here. This is + the default unless one of the following special cases is used: + +2. As for `subject` and `predicate`, you can use the syntax `(`⟨name of + node or scope⟩`)` to create and use a curie for the node or scope. + +3. If the ⟨object⟩ starts with `"`, it must have the syntax + `"`⟨literals⟩`"`. In this case, the object of the statement is not a + curie (not a normal "resource") but the string of ⟨literals⟩ given. + +4. If the ⟨object⟩ is the text "`scope content`", the object of the + statement is actually the whole contents of the scope to which this + statement is attached. + +5. The two previous cases can be combined in the form of an object of + the form `"`⟨literals⟩`" and scope content`. In this case, the + contents of the scope is "normally" the object, but this gets + "overruled" by the ⟨literals⟩. Formally, this means that the object + is the ⟨literals⟩, but the intended semantics is that the object is + the scope content, only for further processing it should be + considered to be ⟨literals⟩. A typical example is the case where the + scope content is, say, the text "January 1st, 2000" but the + ⟨literals⟩ are set to `2000-01-01`, which is easier for software to + process: + + \node [rdf engine = { + statement = { + subject = ..., + predicate = dc:Date, + object = "2000-01-01" and scope content + } } ] { January 1st, 2000 }; + +For the last two cases, only one statement may be given per scope that +has the `scope content` as its object; if more than one is given, the +last one wins. This is the reason why several uses of `predicate` are +allowed in a `statement`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/object", + meta = "⟨object⟩" + }, + ["rdf engine/statements/predicate"] = { + details = [[ +Sets the predicate for the statement. The syntax is exactly the same as +for the subject. Unlike for subjects, you can use the predicate key +several times inside a single statement and the uses will "accumulate" +and several statements are created, namely one statement for each use of +`predicate` for the subject and object specified inside the use of +`statement`. This behavior is not very systematic (it violates the rule +"one statement per `statement`") and you should normally use the +`statement` once for each use of the `predicate` key. However, in +conjunction with the object `scope content` it is necessary to allow +this behavior. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/predicate", + meta = "⟨predicate⟩" + }, + ["rdf engine/statements/subject"] = { + details = [[ +Sets the subject of the to-be-created statement. The ⟨subject⟩ can be in +one of two possible formats: + +1. A curie (a *compact universal resource identifier expression,* see + the RDFA specification for details). Examples are standard URLs like + `http://www.example.org`, but also text like `# my_ automaton`. Note + that in order to include a hashmark in a curie you should use the + command `\tikzrdfhashmark`, which expands to a hash mark (TeX treats + hash marks in a special way, which is why this command is used + here). + +2. When the ⟨subject⟩ starts with an opening parenthesis, that is, with + "`(`", the ⟨subject⟩ must have the form `(`⟨node or scope name⟩`)`. + In this case, the ⟨node or scope name⟩ must be the name of an + already existing node (the current node or scope is considered as + "existing" here). Then, the curie `# `⟨id⟩ is used as subject, where + the ⟨id⟩ is a unique internal identifier for the node. + + As an example, suppose you wish to specify that a node has some + other node as child, you could write the following: + + \tikz [ rdf engine = { prefix = { rels: http://www.example.org/relations/} } ] { + \node (fritz) { Fritz }; + \node (heinz) at (2,0) { Heinz }; + \draw [->] (fritz) -- (heinz) + [rdf engine = { + statement = { + subject = (fritz), + predicate = rels:isSonOf, + object = (heinz) + } } ]; + } + +You can use a macro as ⟨subject⟩, it will be expanded before the above +syntax check is done. + +If you use the `subject` key several times inside a single `statement` +command, (only) the last subject is used. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rdf:engine/statements/subject", + meta = "⟨subject⟩" + }, + relationship = { + details = [[ +This style works like `entity`, only it is to be used for relationships. +Again, `relationship`s are actually relationship types. + + \begin{tikzpicture} + \node[entity] (sheep) at (0,0) {Sheep}; + \node[entity] (genome) at (2,0) {Genome}; + \node[relationship] at (1,1.5) {has} + edge (sheep) + edge (genome); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/relationship" + }, + relative = { + details = [[ +This option tells TikZ whether the `in` and `out` angles should be +considered absolute or relative. Absolute means that an `out` angle of +30$^\circ$ means that the curve leaves the start coordinate at an angle +of 30$^\circ$ relative to the paper (unless, of course, further +transformations have been installed). A *relative* angle is, by +comparison, measured relative to a straight line from the start +coordinate to the target coordinate. Thus, a relative angle of +30$^\circ$ means that the curve will bend to the left from the line +going straight from the start to the target. For the target, the +relative coordinate is measured in the same manner, namely relative to +the line going from the start to the target. Thus, an angle of +150$^\circ$ means that the curve will reach target coming slightly from +the left. + + \begin{tikzpicture}[out=45,in=135,relative] + \draw (0,0) to (1,0) + to (2,1) + to (2,2); + \end{tikzpicture} + + \begin{tikzpicture}[out=90,in=90,relative] + \node [circle,draw] (a) at (0,0) {a}; + \node [circle,draw] (b) at (1,1) {b}; + \node [circle,draw] (c) at (2,2) {c}; + + \path (a) edge (b) + edge (c); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/relative", + meta = "⟨true or false⟩" + }, + ["remember picture"] = { + details = [[ +This option tells TikZ that it should attempt to remember the position +of the current picture on the page. This attempt may fail depending on +which backend driver is used. Also, even if remembering works, the +position may only be available on a second run of TeX. + +Provided that remembering works, you may consider saying + + \tikzset{every picture/.append style={remember picture}} + +to make TikZ remember all pictures. This will add one line in the `.aux` +file for each picture in your document -- which typically is not very +much. Then, you do not have to worry about remembered pictures at all. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/remember:picture", + meta = "⟨boolean⟩" + }, + ["reset cm"] = { + details = [[ +Completely resets the coordinate transformation matrix to the identity +matrix. This will destroy not only the transformations applied in the +current scope, but also all transformations inherited from surrounding +scopes. Do not use this option, unless you really, really know what you +are doing. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/reset:cm" + }, + resistor = { + details = [[ +This key should be used with a `node` path command or with the `to` path +command. + +**Using the Key with Normal Nodes.** When used with a node, it will +cause this node to "look like" a resistor (by default, in the IEC +library, this is just a simple rectangle). + + \tikz [circuit ee IEC] + \node [resistor] {}; + +Unlike normal nodes, a resistor node generally should not take any text +(as in `node [resistor] {foo}`). Instead, the labeling of resistors +should be done using the `label`, `info` and `ohm` options. + + \tikz [circuit ee IEC] + \node [resistor,ohm=5] {}; + +The ⟨options⟩ make no real sense when the `resistor` option is used with +a normal node, you can just as well given them to the `node` itself. +Thus, the following has the same effect as the above example: + + \tikz [circuit ee IEC] + \node [resistor={ohm=5}] {}; + +In a circuit, you will often wish to rotate elements. For this, the +options `point up`, `point down`, `point left` or `point right` may be +especially useful. They are just shorthands for appropriate rotations +like `rotate=90`. + + \tikz [circuit ee IEC] { + \node (R1) [resistor,point up,ohm=5] at (3,1) {}; + \node (R2) [resistor,ohm=10k] at (0,0) {}; + \draw (R2) -| (R1); + } + +**Using the Key on a To Path.** When the `resistor` key is used on a +`to` path inside a `circuit ee IEC`, the `circuit handle symbol` key is +called internally. This has a whole bunch of effects: + +1. The path currently being constructed is cut up to make place for a + node. + +2. This node will be a `resistor node` that is rotated so that it + points "along" the path (unless an option like `shift only` or an + extra rotation is used to change this). + +3. The ⟨options⟩ passed to the `resistor` key are passed on to the + node. + +4. The ⟨options⟩ are pre-parsed to identify a `pos` key or a key like + `at start` or `midway`. These keys are used to determine where on + the `to` path the node will lie. + +Since the ⟨options⟩ of the `resistor` key are passed on to the resistor +node on the path, you can use it to add labels to the node. Here is a +simple example: + + \tikz [circuit ee IEC] + \draw (0,0) to [resistor=red] (3,0) + to [resistor={ohm=2\mu}] (3,2); + +You can add multiple labels to a resistor and you can have multiple +resistors (or other elements) on a single path. + +**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 +have four standard compass direction anchors. + +**Changing the Appearance.** To configure the appearance of all +`resistor`s, see Section ??. You can use the ⟨options⟩ to locally change +the appearance of a single resistor. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/resistor", + meta = "⟨options⟩" + }, + right = { + details = [[ +Similar to `above`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/right", + meta = "⟨offset⟩" + }, + ["right color"] = { + details = [[ +Works like `left color`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/right:color", + meta = "⟨color⟩" + }, + ["right delimiter"] = { + details = [[ +Works as above. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/right:delimiter", + meta = "⟨delimiter⟩" + }, + ["right of"] = { + details = [[ + +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/right:of", + meta = "⟨node⟩" + }, + ["root concept"] = { + details = [[ +This style is used for the roots of mindmap trees. By adding something +to this, you can change how the root of a mindmap will be rendered. + + \tikz + [root concept/.append style={concept color=blue!80,minimum size=3.5cm}, + mindmap] + \node [concept] {Root concept}; + +Note that styles like `large mindmap` redefine these styles, so you +should add something to this style only inside the picture. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/root:concept" + }, + rotate = { + details = [[ +Rotates the coordinate system by ⟨degree⟩: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[rotate=40,blue] (0,0) -- (1,1) -- (1,0); + \draw[rotate=-20,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate", + meta = "⟨degree⟩" + }, + ["rotate around"] = { + details = [[ +Rotates the coordinate system by ⟨degree⟩ around the point ⟨coordinate⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[rotate around={40:(1,1)},blue] (0,0) -- (1,1) -- (1,0); + \draw[rotate around={-20:(1,1)},red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate:around", + meta = "{⟨degree⟩:⟨coordinate⟩}" + }, + ["rotate around x"] = { + details = [[ +This key sets the $x$, $y$ and $z$ vectors of the PGF $xyz$-coordinate +system so that they are rotated by ⟨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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate:around:x", + meta = "⟨angle⟩" + }, + ["rotate around y"] = { + details = [[ +This key sets the $x$, $y$ and $z$ vectors of the PGF $xyz$-coordinate +system so that they are rotated by ⟨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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate:around:y", + meta = "⟨angle⟩" + }, + ["rotate around z"] = { + details = [[ +This key sets the $x$, $y$ and $z$ vectors of the PGF $xyz$-coordinate +system so that they are rotated by ⟨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{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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate:around:z", + meta = "⟨angle⟩" + }, + ["rotate fit"] = { + details = [[ +This key fits ⟨coordinates or nodes⟩ inside a node that is rotated by +⟨angle⟩. As a side effect, it also sets the `/tikz/rotate` key. + + \begin{tikzpicture}[inner sep=0pt,thick, + dot/.style={fill=blue,circle,minimum size=3pt}] + \draw[help lines] (0,0) grid (3,2); + \node[dot] (a) at (1,1) {}; + \node[dot] (b) at (2,2) {}; + \node[dot] (c) at (1,2) {}; + \node[dot] (d) at (1.25,0.25) {}; + \node[dot] (e) at (1.75,1.5) {}; + \node[draw, fit=(a) (b) (c) (d) (e)] {}; + \node[draw=red, rotate fit=30, fit=(a) (b) (c) (d) (e)] {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rotate:fit", + meta = "⟨angle⟩" + }, + ["rounded corners"] = { + details = [[ +When this option is in force, all corners (places where a line is +continued either via line-to or a curve-to operation) are replaced by +little arcs so that the corner becomes smooth. + + \tikz \draw [rounded corners] (0,0) -- (1,1) + -- (2,0) .. controls (3,1) .. (4,0); + +The ⟨inset⟩ describes how big the corner is. Note that the ⟨inset⟩ is +*not* scaled along if you use a scaling option like `scale=2`. + + \begin{tikzpicture} + \draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt]; + \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt); + \end{tikzpicture} + +You can switch the rounded corners on and off "in the middle of path" +and different corners in the same path can have different corner radii: + + \begin{tikzpicture} + \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1) + [sharp corners] -- (2,0) + [rounded corners=5pt] -- cycle; + \end{tikzpicture} + +Here is a rectangle with rounded corners: + + \tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex); + +You should be aware, that there are several pitfalls when using this +option. First, the rounded corner will only be an arc (part of a circle) +if the angle is $90^\circ$. In other cases, the rounded corner will +still be round, but "not as nice". + +Second, if there are very short line segments in a path, the "rounding" +may cause inadvertent effects. In such case it may be necessary to +temporarily switch off the rounding using `sharp corners`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/rounded:corners", + meta = "⟨inset⟩" + }, + ["row sep"] = { + details = [[ +This option works like `column sep`, only for rows. Here, too, you can +specify whether the space is added between the lower end of the first +row and the upper end of the second row, or whether the space is +computed between the origins of the two rows. + + \begin{tikzpicture} + \matrix [draw,row sep=1cm,nodes=draw] + { + \node (a) {123}; & \node {1}; & \node {1}; \\ + \node (b) {12}; & \node {12}; & \node {1}; \\ + \node {1}; & \node {123}; & \node {1}; \\ + }; + \draw [<->,red,thick] (a.south) -- (b.north) node [right,midway] {1cm}; + \end{tikzpicture} + + \begin{tikzpicture} + \matrix [draw,row sep={1cm,between origins},nodes=draw] + { + \node (a) {123}; & \node {1}; & \node {1}; \\ + \node (b) {12}; & \node {12}; & \node {1}; \\ + \node {1}; & \node {123}; & \node {1}; \\ + }; + \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/row:sep", + meta = "⟨spacing list⟩" + }, + ["row ⟨number⟩"] = { + details = [[ +This style is used for every cell in row ⟨number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/row:⟨number⟩" + }, + ["row ⟨row number⟩ column ⟨column number⟩"] = { + details = [[ +This style is used for the cell in row ⟨row number⟩ and column ⟨column +number⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/row:⟨row:number⟩:column:⟨column:number⟩" + }, + samples = { + details = [[ +Sets the number of samples used in the plot. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/samples", + meta = "⟨number⟩" + }, + ["samples at"] = { + details = [[ +This option specifies a list of positions for which the variable should +be evaluated. For instance, you can say `samples at={1,2,8,9,10}` to +have the variable evaluated exactly for values $1$, $2$, $8$, $9$, and +$10$. You can use the `\foreach` syntax, so you can use `...` inside the +⟨sample list⟩. + +When this option is used, the `samples` and `domain` option are +overruled. The other way round, setting either `samples` or `domain` +will overrule this option. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/samples:at", + meta = "⟨sample list⟩" + }, + ["save path"] = { + details = [[ +Save the current soft path into ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/save:path", + meta = "⟨macro⟩" + }, + scale = { + details = [[ +Multiplies all coordinates by the given ⟨factor⟩. The ⟨factor⟩ should +not be excessively large in absolute terms or very close to zero. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[scale=-1,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/scale", + meta = "⟨factor⟩" + }, + ["scale around"] = { + details = [[ +Scales the coordinate system by ⟨factor⟩, with the "origin of scaling" +centered on ⟨coordinate⟩ rather than the origin. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[scale around={2:(1,1)},red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/scale:around", + meta = "{⟨factor⟩:⟨coordinate⟩}" + }, + ["scope fading"] = { + details = [[ +In principle, this key works in exactly the same way as the +`path fading` key. The only difference is, that the effect of the fading +will persist after the current path till the end of the scope. Thus, the +⟨fading⟩ is applied to all subsequent drawings in the current scope, not +just to the current path. In this regard, the option works very much +like the `clip` option. (Note, however, that, unlike the `clip` option, +fadings to not accumulate unless a transparency group is used.) + +The keys `fit fading` and `fading transform` have the same effect as for +`path fading`. Also that, just as for `path fading`, providing the +`scope fading` option with a `{scope}` only sets the name of the fading +to be used. You have to explicitly provide the `scope fading` with a +path to actually install a fading. + + \begin{tikzpicture} + \fill [black!20] (-2,-2) rectangle (2,2); + \pattern [pattern=checkerboard,pattern color=black!30] + (-2,-2) rectangle (2,2); + + % The bounding box of the shading: + \draw [red] (-50bp,-50bp) rectangle (50bp,50bp); + + \path [scope fading=south,fit fading=false] (0,0); + % fading is centered at its natural size + + \fill[red] ( 90:1) circle (1); + \fill[green] (210:1) circle (1); + \fill[blue] (330:1) circle (1); + \end{tikzpicture} + +In the following example we resize the fading to the size of the whole +picture: + + \begin{tikzpicture} + \fill [black!20] (-2,-2) rectangle (2,2); + \pattern [pattern=checkerboard,pattern color=black!30] + (-2,-2) rectangle (2,2); + + \path [scope fading=south] (-2,-2) rectangle (2,2); + + \fill[red] ( 90:1) circle (1); + \fill[green] (210:1) circle (1); + \fill[blue] (330:1) circle (1); + \end{tikzpicture} + +Scope fadings are also needed if you wish to fade a node. + + \tikz \node [scope fading=south,fading angle=45,text width=3.5cm] + { + This is some text that will fade out as we go right + and down. It is pretty hard to achieve this effect in + other ways. + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/scope:fading", + meta = "⟨fading⟩" + }, + semithick = { + details = [[ +Sets the line width to 0.6pt. + + \tikz \draw[semithick] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/semithick" + }, + semitransparent = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/semitransparent" + }, + set = { + details = [[ +This key can be used as an option with a `node` command. The ⟨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. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/set", + meta = "⟨set name⟩" + }, + shade = { + details = [[ +Causes the path to be shaded using the currently selected shading (more +on this later). If this option is used together with the `draw` option, +then the path is first shaded, then drawn. + +It is not an error to use this option together with the `fill` option, +but it makes no sense. + + \tikz \shade (0,0) circle (1ex); + + \tikz \shadedraw (0,0) circle (1ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shade" + }, + shading = { + details = [[ +This selects a shading named ⟨name⟩. The following shadings are +predefined: `axis`, `radial`, and `ball`. + + \tikz \shadedraw [shading=axis] (0,0) rectangle (1,1); + \tikz \shadedraw [shading=radial] (0,0) rectangle (1,1); + \tikz \shadedraw [shading=ball] (0,0) circle (.5cm); + +The shadings as well as additional shadings are described in more detail +in Section ??. + +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 correct shading type, +see the following example + + \tikz \shadedraw [left color=red,right color=blue] + (0,0) rectangle (1,1); + +For a complete list of the possible options see Section ?? once more. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shading", + meta = "⟨name⟩" + }, + ["shading angle"] = { + details = [[ +This option rotates the shading (not the path!) by the given angle. For +example, we can turn a top-to-bottom axis shading into a left-to-right +shading by rotating it by $90^\circ$. + + \tikz \shadedraw [shading=axis,shading angle=90] (0,0) rectangle (1,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shading:angle", + meta = "⟨degrees⟩" + }, + ["shadow scale"] = { + details = [[ +Shadows are scaled by ⟨factor⟩. + + \tikz [even odd rule] + \draw [general shadow={fill=red,shadow scale=1.25}] + (0,0) circle (.5) (0.5,0) circle (.5); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shadow:scale", + meta = "⟨factor⟩" + }, + ["shadow xshift"] = { + details = [[ +Shadows are shifted horizontally by ⟨dimension⟩. + + \tikz [even odd rule] + \draw [general shadow={fill=red,shadow xshift=-5pt}] + (0,0) circle (.5) (0.5,0) circle (.5); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shadow:xshift", + meta = "⟨dimension⟩" + }, + ["shadow yshift"] = { + details = [[ +Shadows are shifted vertically by ⟨dimension⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shadow:yshift", + meta = "⟨dimension⟩" + }, + shape = { + details = [[ +Select the shape either of the current node or, when this option is not +given inside a node but somewhere outside, the shape of all nodes in the +current scope. + +Since this option is used often, you can leave out the `shape=`. When +TikZ encounters an option like `circle` that it does not know, it will, +after everything else has failed, check whether this option is the name +of some shape. If so, that shape is selected as if you had said +`shape=`⟨shape name⟩. + +By default, the following shapes are available: `rectangle`, `circle`, +`coordinate`. Details of these shapes, like their anchors and size +options, are discussed in Section ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shape", + meta = "⟨shape name⟩" + }, + ["sharp corners"] = { + details = [[ +This options switches off any rounding on subsequent corners of the +path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/sharp:corners" + }, + ["sharp plot"] = { + details = [[ +This is the default and causes the points to be connected by straight +lines. This option is included only so that you can "switch back" if you +"globally" install, say, `smooth`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/sharp:plot" + }, + shift = { + details = [[ +Adds the ⟨coordinate⟩ to all coordinates. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[shift={(1,1)},blue] (0,0) -- (1,1) -- (1,0); + \draw[shift={(30:1cm)},red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shift", + meta = "{⟨coordinate⟩}" + }, + ["shift only"] = { + details = [[ +This option does not take any parameter. Its effect is to cancel all +current transformations except for the shifting. This means that the +origin will remain where it is, but any rotation around the origin or +scaling relative to the origin or skewing will no longer have an effect. + +This option is useful in situations where a complicated transformation +is used to "get to a position", but you then wish to draw something +"normal" at this position. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[rotate=30,xshift=2cm,blue] (0,0) -- (1,1) -- (1,0); + \draw[rotate=30,xshift=2cm,shift only,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shift:only" + }, + ["shorten <"] = { + details = [[ +Shorten the path by ⟨length⟩ in the direction of the starting point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shorten:<", + meta = "⟨length⟩" + }, + ["shorten >"] = { + details = [[ +Shorten the path by ⟨length⟩ in the direction of the end point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/shorten:>", + meta = "⟨length⟩" + }, + ["show background bottom"] = { + details = [[ +Works like the style for the top line. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:bottom" + }, + ["show background grid"] = { + details = [[ +This style behaves similarly to the `show background rectangle` style, +but it will not use a rectangle path, but a grid. The lower left and +upper right corner of the grid is computed in the same way as for the +background rectangle: + + \begin{tikzpicture}[show background grid] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} + +You can influence the background grid by setting the following style: + +This option can be combined with the `framed` option (use the `framed` +option first): + + \tikzset{background grid/.style={thick,draw=red,step=.5cm}, + background rectangle/.style={rounded corners,fill=yellow}} + \begin{tikzpicture}[framed,gridded] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:grid" + }, + ["show background left"] = { + details = [[ +Works similarly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:left" + }, + ["show background rectangle"] = { + details = [[ +This style causes a rectangle to be drawn behind your graphic. This +style option must be given to the `{tikzpicture}` environment or to the +`\tikz` command. + + \begin{tikzpicture}[show background rectangle] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} + +The size of the background rectangle is determined as follows: We start +with the bounding box of the picture. Then, a certain separator distance +is added on the sides. This distance can be different for the $x$- and +$y$-directions and can be set using the following options: + +The following two styles make setting the inner separator a bit easier +to remember: + +You can influence how the background rectangle is rendered by setting +the following style: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:rectangle" + }, + ["show background right"] = { + details = [[ +Works similarly. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:right" + }, + ["show background top"] = { + details = [[ +This style causes a single line to be drawn at the top of the background +rectangle. Normally, the line coincides exactly with the top line of the +background rectangle: + + \begin{tikzpicture}[ + background rectangle/.style={fill=yellow}, + framed,show background top] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} + +The following option allows you to lengthen (or shorten) the line: + + \begin{tikzpicture} + [background rectangle={fill=blue!20}, + outer frame sep=1ex,% + show background top,% + show background bottom,% + show background left,% + show background right] + \draw (0,0) ellipse (10mm and 5mm); + \end{tikzpicture} + +You can influence how the line is drawn grid by setting the following +style: +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/show:background:top" + }, + ["sibling angle"] = { + details = [[ +Sets the angle between siblings in the `grow cyclic` style. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/sibling:angle", + meta = "⟨angle⟩" + }, + ["sibling distance"] = { + details = [[ +This key specifies the distance between the anchors of the children of a +parent node. + + \begin{tikzpicture} + [level distance=4mm, + level 1/.style={sibling distance=8mm}, + level 2/.style={sibling distance=4mm}, + level 3/.style={sibling distance=2mm}] + \coordinate + child { + child {child child} + child {child child} + } + child { + child {child child} + child {child child} + }; + \end{tikzpicture} + + \begin{tikzpicture} + [level distance=10mm, + every node/.style={fill=red!60,circle,inner sep=1pt}, + level 1/.style={sibling distance=20mm,nodes={fill=red!45}}, + level 2/.style={sibling distance=10mm,nodes={fill=red!30}}, + level 3/.style={sibling distance=5mm,nodes={fill=red!25}}] + \node {31} + child {node {30} + child {node {20} + child {node {5}} + child {node {4}} + } + child {node {10} + child {node {9}} + child {node {1}} + } + } + child {node {20} + child {node {19} + child {node {1}} + child[missing] + } + child {node {18}} + }; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/sibling:distance", + meta = "⟨distance⟩" + }, + size = { + details = [[ +Inside a `spy scope`, this is a shortcut for `minimum size`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/size", + meta = "⟨dimension⟩" + }, + slice = { + details = [[ +This key works exactly like `meet`, only the second rule is changed: + +1. the to-be-viewed rectangle has minimal size that it encompasses all + of the window rectangle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/slice", + meta = "⟨to-be-viewed corner⟩ rectangle ⟨to-be-viewed corner⟩ at ⟨window corner⟩ rectangle ⟨window corner⟩" + }, + sloped = { + details = [[ +This option causes the node to be rotated such that a horizontal line +becomes a tangent to the curve. The rotation is normally done in such a +way that text is never "upside down". To get upside-down text, use can +use `[rotate=180]` or `[allow upside down]`, see below. + + \tikz \draw (0,0) .. controls +(up:2cm) and +(left:2cm) .. (1,3) + node foreach \p in {0,0.25,...,1} [sloped,above,pos=\p]{\p}; + + \begin{tikzpicture}[->] + \draw (0,0) -- (2,0.5) node[midway,sloped,above] {$x$}; + \draw (2,-.5) -- (0,0) node[midway,sloped,below] {$y$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/sloped" + }, + ["small circuit symbols"] = { + details = [[ +This style sets the default circuit symbol unit to `6pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/small:circuit:symbols" + }, + ["small mindmap"] = { + details = [[ +This style includes the `mindmap` style, but additionally changes the +default size of concepts, fonts and distances so that a medium-sized +mindmap will fit on an A5 page (A5 pages are half as large as A4 pages). +Mindmaps with `small mindmap` will also fit onto a standard frame of the +`beamer` package. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/small:mindmap" + }, + smooth = { + details = [[ +This option causes the points on the path to be connected using a smooth +curve: + + \tikz\draw plot[smooth] file{plots/pgfmanual-sine.table}; + +Note that the smoothing algorithm is not very intelligent. You will get +the best results if the bending angles are small, that is, less than +about $30^\circ$ and, even more importantly, if the distances between +points are about the same all over the plotting path. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/smooth" + }, + ["smooth cycle"] = { + details = [[ +This option causes the points on the path to be connected using a closed +smooth curve. + + \tikz[scale=0.5] + \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)} + plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/smooth:cycle" + }, + solid = { + details = [[ +Shorthand for setting a solid line as "dash pattern". This is the +default. + + \tikz \draw[solid] (0pt,0pt) -- (50pt,0pt); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/solid" + }, + ["spy connection path"] = { + details = [[ +The ⟨code⟩ is executed after the spy-on and spy-in nodes have just been +created. Inside this ⟨code⟩, the two nodes can be accessed as +`tikzspyinnode` and `tikzspyonnode`. For example, the key +`connect spies` sets this command to + + \draw[thin] (tikzspyonnode) -- (tikzspyinnode); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/spy:connection:path", + meta = "⟨code⟩" + }, + ["spy scope"] = { + details = [[ +This option may be used with a `{scope}` or any environment that creates +such a scope internally (like `{tikzpicture}`). It has the following +effects: + +- It resets a number of graphic state parameters, including the color, + line style, and others. This is necessary for technical reasons. + +- It tells TikZ that the content of the scope should be saved + internally in a special box. + +- It defines the command `\spy` so that it can be used inside the + scope. + +- At the end of the scope, the nodes belonging to the `\spy` commands + used inside the scope are created. + +- The ⟨options⟩ are saved in an internal style. Each time `\spy` is + used, these ⟨options⟩ will be used. + +- Three keys are defined that provide useful shortcuts: + +It is permissible to nest `spy scopes`. In this case, all `\spy` +commands inside the inner `spy scope` only have an effect on material +inside the scope, whereas `\spy` commands outside the inner `spy scope` +but inside the outer `spy scope` allow you to "spy on the spy". + + \begin{tikzpicture} + [spy using outlines={rectangle, red, magnification=5, + size=1.5cm, connect spies}] + + \begin{scope} + [spy using outlines={circle, blue, + magnification=3, size=1.5cm, connect spies}] + \draw [help lines] (0,0) grid (3,2); + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy on (1.6,0.3) in node (zoom) [left] at (3.5,-1.25); + \end{scope} + + \spy on (zoom.north west) in node [right] at (0,-1.25); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/spy:scope", + meta = "⟨options⟩" + }, + ["spy using outlines"] = { + details = [[ +This key creates a `spy scope` in which the spy-in node is drawn, but +not filled, using a thick line; and the spy-on node is drawn, but not +filled, using a very thin line. + + \begin{tikzpicture} + [spy using outlines={circle, magnification=3, size=1cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node at (3,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/spy:using:outlines", + meta = "⟨options⟩" + }, + ["spy using overlays"] = { + details = [[ +This key creates a `spy scope` in which both the spy-in and spy-on nodes +are filled, but with the fill opacity set to 20%. + + \begin{tikzpicture} + [spy using overlays={circle, magnification=3, size=1cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [green] on (1.6,0.3) in node at (3,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/spy:using:overlays", + meta = "⟨options⟩" + }, + ["start angle"] = { + details = [[ +Sets the start angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/start:angle", + meta = "⟨degrees⟩" + }, + ["start branch"] = { + details = [[ +This key is used in the same manner as the `start chain` command, +however, the effect is slightly different: + +- This option may only be used if some chain is already active and + there is a (last) node on this chain. Let us call this node the + ⟨fork node⟩. + +- The chain is not just called ⟨branch name⟩, but ⟨current + chain⟩`/`⟨branch name⟩. For instance, if the ⟨fork node⟩ is part of + the chain called `trunk` and the ⟨branch name⟩ is set to `left`, the + complete chain name of the branch is `trunk/left`. The ⟨branch name⟩ + must be given, there is no default value. + +- The ⟨fork node⟩ is automatically "chained into" the branch chain as + its first node. Thus, for the first node on the branch that you + provide, the `join` option will cause it to be connected to the fork + node. + +  + + \begin{tikzpicture}[every on chain/.style=join,every join/.style=->, + node distance=2mm and 1cm] + { [start chain=trunk] + \node [on chain] {A}; + \node [on chain] {B}; + + { [start branch=numbers going below] + \node [on chain] {1}; + \node [on chain] {2}; + \node [on chain] {3}; + } + { [start branch=greek going above] + \node [on chain] {$\alpha$}; + \node [on chain] {$\beta$}; + \node [on chain] {$\gamma$}; + } + + \node [on chain,join=with trunk/numbers-end,join=with trunk/greek-end] {C}; + { [start branch=symbols going below] + \node [on chain] {$\star$}; + \node [on chain] {$\circ$}; + \node [on chain] {$\int$}; + } + } + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/start:branch", + meta = "⟨branch name⟩⟨direction⟩" + }, + ["start chain"] = { + details = [[ +This key should, but need not, be given as an option to a scope +enclosing all nodes of the chain. Typically, this will be a `scope` or +the whole `tikzpicture`, but it might just be a path on which all nodes +of the chain are found. If no ⟨chain name⟩ is given, the default value +`chain` will be used instead. + +The key starts a chain named ⟨chain name⟩ and makes it *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 end of the scope in which the +`start chain` command was given. + +Although chains are only locally active (that is, active inside the +scope the `start chain` command was issued), the information concerning +the chains is stored globally and it is possible to *continue* a chain +after a scope has ended. For this, the `continue chain` option can be +used, which allows you to reactivate an existing chain in another scope. + +The ⟨direction⟩ is used to determine the placement rule for nodes on the +chain. If it is omitted, the current value of the following key is used: + +The ⟨direction⟩ can have two different forms: `going `⟨options⟩ or +`placed `⟨options⟩. The effect of these rules will be explained in the +description of the `on chain` option. Right now, just remember that the +⟨direction⟩ you provide with the `chain` option applies to the whole +chain. + +Other than this, this key has no further effect. In particular, to place +nodes on the chain, you must use the `on chain` option, described next. + + \begin{tikzpicture}[start chain] + % The chain is called just "chain" + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; + \end{tikzpicture} + + \begin{tikzpicture} + % Same as above, using the scope shorthand + { [start chain] + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; + } + \end{tikzpicture} + + \begin{tikzpicture}[start chain=1 going right, + start chain=2 going below, + node distance=5mm, + every node/.style=draw] + \node [on chain=1] {A}; + \node [on chain=1] {B}; + \node [on chain=1] {C}; + + \node [on chain=2] at (0.5,-.5) {0}; + \node [on chain=2] {1}; + \node [on chain=2] {2}; + + \node [on chain=1] {D}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/start:chain", + meta = "⟨chain name⟩⟨direction⟩" + }, + state = { + details = [[ +You should redefine it to something else, if you wish to use states of a +different nature. + + \begin{tikzpicture}[state/.style=state with output] + \node[state] {$q_0$ \nodepart{lower} $11$}; + \node[state] at (2,0) {$q_1$ \nodepart{lower} $00$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/state" + }, + ["state with output"] = { + details = [[ +This node style causes nodes to be drawn as split circles, that is, +using the `circle split` shape. In the upper part of the shape you have +the name of the style, in the lower part the output is placed. To +specify the output, use the command `\nodepart{lower}` inside the node. +This style also calls `every state`. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \node[state without output] {$q_0$}; + + \node[state with output] at (2,0) {$q_1$ \nodepart{lower} $00$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/state:with:output" + }, + ["state without output"] = { + details = [[ +This node style causes nodes to be drawn as circles. Also, this style +calls `every state`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/state:without:output" + }, + step = { + details = [[ +Sets the stepping in both the $x$ and $y$-direction. If a dimension is +provided, this is used directly. If a number is provided, this number is +interpreted in the $xy$-coordinate system. For example, if you provide +the number `2`, then the $x$-step is twice the $x$-vector and the +$y$-step is twice the $y$-vector set by the `x=` and `y=` options. +Finally, if you provide a coordinate, then the $x$-part of this +coordinate will be used as the $x$-step and the $y$-part will be used as +the $y$-coordinate. + + \begin{tikzpicture}[x=.5cm] + \draw[thick] (0,0) grid [step=1] (3,2); + \draw[red] (0,0) grid [step=.75cm] (3,2); + \end{tikzpicture} + \begin{tikzpicture} + \draw (0,0) circle [radius=1]; + \draw[blue] (0,0) grid [step=(45:1)] (3,2); + \end{tikzpicture} + +A complication arises when the $x$- and/or $y$-vector do not point along +the axes. Because of this, the actual rule for computing the $x$-step +and the $y$-step is the following: As the $x$- and $y$-steps we use the +$x$- and $y$-components or the following two vectors: The first vector +is either $(⟨x-grid-step-number⟩,0)$ or +$(⟨x-grid-step-dimension⟩,0\mathrm{pt})$, the second vector is +$(0,⟨y-grid-step-number⟩)$ or $(0\mathrm{pt},⟨y-grid-step-dimension⟩)$. + +If the $x$-step or $y$-step is $0$ or negative the corresponding lines +are not drawn. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/step", + meta = "⟨number or dimension or coordinate⟩" + }, + ["structured tokens"] = { + details = [[ +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. + + \tikz \node[place,structured tokens={$x$,$y$,$z$}] {}; + + \begin{tikzpicture}[every place/.style={minimum size=9mm}] + + \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3, + 0/1/4,1/1/5,2/1/6, + 0/0/7,1/0/8,2/0/9} + \node [place,structured tokens={1,...,\tokennumber}] at (\x,\y) {}; + \end{tikzpicture} + +If you use lots of structured tokens, consider redefining the +`every token` style so that the tokens are larger. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/structured:tokens", + meta = "⟨token texts⟩" + }, + ["subgraph nodes"] = { + details = [[ +Sets the `every subgraph node` style to ⟨style⟩. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/subgraph:nodes", + meta = "⟨style⟩" + }, + ["subgraph text bottom"] = { + details = [[ +Works like `subgraph text top`, only the text placed at the bottom. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/subgraph:text:bottom", + meta = "⟨text alignment options⟩" + }, + ["subgraph text none"] = { + details = [[ +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. + + \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; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/subgraph:text:none" + }, + ["subgraph text sep"] = { + details = [[ +Some space added between the inner nodes of a subgraph node and the text +labels. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/subgraph:text:sep", + meta = "⟨dimension⟩" + }, + ["subgraph text top"] = { + details = [[ +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. + + \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; + }; + +You can pass any of the ⟨text alignment options⟩ understood by TikZ, +such as `text centered`: + + \tikz [subgraph text top=text centered] + \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + left [draw, circle] // { b, c, d }; + }; + +To place a label *outside* the subgraph node, use a label, typically +defined using the `quotes` library: + + \tikz \graph [tree layout] { + a -> { b -> {c, d}, e -> {f, g -> h} }; + + / ["left", draw] // { b, c, d } <-> + / ["right", draw] // { e, f, g, h}; + }; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/subgraph:text:top", + meta = "⟨text alignment options⟩" + }, + swap = { + details = [[ +This option exchanges the roles of `left` and `right` in automatic +placement. That is, if `left` is the current `auto` placement, `right` +is set instead and the other way round. + + \begin{tikzpicture}[auto] + \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) + 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} + + \begin{tikzpicture}[shorten >=1pt,node distance=2cm,auto] + \draw[help lines] (0,0) grid (3,2); + + \node[state] (q_0) {$q_0$}; + \node[state] (q_1) [above right of=q_0] {$q_1$}; + \node[state] (q_2) [below right of=q_0] {$q_2$}; + \node[state] (q_3) [below right of=q_1] {$q_3$}; + + \path[->] (q_0) edge node {0} (q_1) + edge node [swap] {1} (q_2) + (q_1) edge node {1} (q_3) + edge [loop above] node {0} () + (q_2) edge node [swap] {0} (q_3) + edge [loop below] node {1} (); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/swap" + }, + tension = { + details = [[ +This option influences how "tight" the smoothing is. A lower value will +result in sharper corners, a higher value in more "round" curves. A +value of $1$ results in a circle if four points at quarter-positions on +a circle are given. The default is $0.55$. The "correct" value depends +on the details of plot. + + \begin{tikzpicture}[smooth cycle] + \draw plot[tension=0.2] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; + \draw[yshift=-2.25cm] plot[tension=0.5] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; + \draw[yshift=-4.5cm] plot[tension=1] + coordinates{(0,0) (1,1) (2,0) (1,-1)}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/tension", + meta = "⟨value⟩" + }, + text = { + details = [[ +Sets the color to be used for text labels. A `color=` option will +immediately override this option. + + \begin{tikzpicture} + \draw[red] (0,0) -- +(1,1) node[above] {red}; + \draw[text=red] (1,0) -- +(1,1) node[above] {red}; + \draw (2,0) -- +(1,1) node[above,red] {red}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text", + meta = "⟨color⟩" + }, + ["text depth"] = { + details = [[ +This option works like `text height`, only for the depth of the text +box. This option is mostly useful when you need to ensure a uniform +depth of text boxes that need to be aligned. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text:depth", + meta = "⟨dimension⟩" + }, + ["text effects"] = { + details = [[ +Execute every option in `{options}` with the key path for each option +temporarily set to `/pgf/decoration/text effects/`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text:effects", + meta = "{options}" + }, + ["text height"] = { + details = [[ +Sets the height of the text boxes in shapes. Thus, when you write +something like `node {text}`, the `text` is first typeset, resulting in +some box of a certain height. This height is then replaced by the height +`text height`. The resulting box is then used to determine the size of +the shape, which will typically be larger. When you write `text height=` +without specifying anything, the "natural" size of the text box remains +unchanged. + + \tikz \node[draw] {y}; + \tikz \node[draw,text height=10pt] {y}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text:height", + meta = "⟨dimension⟩" + }, + ["text opacity"] = { + details = [[ +Sets the opacity of text labels, overriding the `fill opacity` setting. + + \begin{tikzpicture}[every node/.style={fill,draw}] + \draw[line width=2mm,blue!50,line cap=round] (0,0) grid (3,2); + + \node[opacity=0.5] at (1.5,2) {Upper node}; + \node[draw opacity=0.8,fill opacity=0.2,text opacity=1] + at (1.5,0) {Lower node}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text:opacity", + meta = "⟨value⟩" + }, + ["text width"] = { + details = [[ +This option will put the text of a node in a box of the given width +(something akin to a `{minipage}` of this width, only portable across +formats). If the node text is not as wide as ⟨dimension⟩, it will +nevertheless be put in a box of this width. If it is larger, line +breaking will be done. + +By default, when this option is given, a ragged right border will be +used (`align=left`). This is sensible since, typically, these boxes are +narrow and justifying the text looks ugly. You can, however, change the +alignment using `align` or directly using commands line `\centering`. + + \tikz \draw (0,0) node[fill=yellow!80!black,text width=3cm] + {This is a demonstration text for showing how line breaking works.}; + +Setting ⟨dimension⟩ to an empty string causes the automatic line +breaking to be disabled. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/text:width", + meta = "⟨dimension⟩" + }, + thick = { + details = [[ +Sets the line width to 0.8pt. + + \tikz \draw[thick] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/thick" + }, + thin = { + details = [[ +Sets the line width to 0.4pt. + + \tikz \draw[thin] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/thin" + }, + ["tight background"] = { + details = [[ +Sets the inner frame separator to 0pt. The background rectangle will +have the size of the bounding box. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/tight:background" + }, + ["tiny circuit symbols"] = { + details = [[ +This style sets the default circuit symbol unit to `5pt`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/tiny:circuit:symbols" + }, + ["to path"] = { + details = [[ +Whenever a `to` operation is used, the ⟨path⟩ is inserted. More +precisely, the following path is added: + +> `{[every to,`⟨options⟩`] `⟨path⟩ `}` + +The ⟨options⟩ are the options given to the `to` operation, the ⟨path⟩ is +the path set by this option `to path`. + +Inside the ⟨path⟩, different macros are used to reference the from- and +to-coordinates. In detail, these are: + +- `\tikztostart` will expand to the from-coordinate (without the + parentheses). + +- `\tikztotarget` will expand to the to-coordinate. + +- `\tikztonodes` will expand to the nodes between the `to` operation + and the coordinate. Furthermore, these nodes will have the `pos` + option set implicitly. + +Let us have a look at a simple example. The standard straight line for a +`to` is achieved by the following ⟨path⟩: + +> `– (\tikztotarget) \tikztonodes` + +Indeed, this is the default setting for the path. When we write +`(a) to (b)`, the ⟨path⟩ will expand to `(a) – (b)`, when we write + +> `(a) to[red] node {x} (b)` + +the ⟨path⟩ will expand to + +> `(a) – (b) node[red] {x}` + +It is not possible to specify the path + +> `– \tikztonodes (\tikztotarget)` + +since TikZ does not allow one to have a macro after `–` that expands to +a node. + +Now let us have a look at how we can modify the ⟨path⟩ sensibly. The +simplest way is to use a curve. + + \begin{tikzpicture}[to path={ + .. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}] + + \node (a) at (0,0) {a}; + \node (b) at (2,1) {b}; + \node (c) at (1,2) {c}; + + \draw (a) to node {x} (b) + (a) to (c); + \end{tikzpicture} + +Here is another example: + + \tikzset{ + my loop/.style={to path={ + .. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}}, + my state/.style={circle,draw}} + + \begin{tikzpicture}[shorten >=2pt] + \node [my state] (a) at (210:1) {$q_a$}; + \node [my state] (b) at (330:1) {$q_b$}; + + \draw[->] (a) to node[below] {1} (b) + to [my loop] node[above right] {0} (b); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/to:path", + meta = "⟨path⟩" + }, + token = { + details = [[ +This style indicates that a node is a token. By default, this causes the +node to be a small black circle. Unlike places and transitions, it +*does* make sense to provide text for the token node. Such text will be +typeset in a tiny font and in white on black (naturally, you can easily +change this by setting the style `every token`). + + \begin{tikzpicture} + \node[place,label=above:$p_1$] (p1) {}; + \node[token] at (p1) {}; + + \node[place,label=above:$p_2$,right=of p1] (p2) {}; + \node[token] at (p2) {$y$}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/token" + }, + ["token distance"] = { + details = [[ +This specifies the distance between the centers of the tokens in the +arrangements of the option `children are tokens`. + + \begin{tikzpicture} + \node[place,label=above:$p_3$] {} + [children are tokens,token distance=1.1ex] + child {node [token] {}} + child {node [token,red] {}} + child {node [token,blue] {}} + child {node [token] {}}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/token:distance", + meta = "⟨distance⟩" + }, + tokens = { + details = [[ +This option is given to a `place` node, not to a `token` node. The +effect of this option is to add ⟨number⟩ many child nodes to the place, +each having the style `token`. Thus, the following two pieces of codes +have the same effect: + + \tikz + \node[place] {} + [children are tokens] + child {node [token] {}} + child {node [token] {}} + child {node [token] {}}; + \tikz + \node[place,tokens=3] {}; + +It is legal to say `tokens=0`, no tokens are drawn in this case. This +option does not handle ten or more tokens correctly. If you need this +many tokens, you will have to program your own code. + + \begin{tikzpicture}[every place/.style={minimum size=9mm}] + + \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3, + 0/1/4,1/1/5,2/1/6, + 0/0/7,1/0/8,2/0/9} + \node [place,tokens=\tokennumber] at (\x,\y) {}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/tokens", + meta = "⟨number⟩" + }, + ["top color"] = { + details = [[ +This option sets the color to be used at the top in an `axis` shading. +When this option is given, several things happen: + +1. The `shade` option is selected. + +2. The `shading=axis` option is selected. + +3. The middle color of the axis shading is set to the average of the + given top color ⟨color⟩ and of whatever color is currently selected + for the bottom. + +4. The rotation angle of the shading is set to 0. + +  + + \tikz \draw[top color=red] (0,0) rectangle (2,1); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/top:color", + meta = "⟨color⟩" + }, + ["transform canvas"] = { + details = [[ +The ⟨options⟩ should contain coordinate transformations options like +`scale` or `xshift`. Multiple options can be given, their effects +accumulate in the usual manner. The effect of these ⟨options⟩ +(immediately) changes the current canvas transformation matrix. The +coordinate transformation matrix is not changed. Tracking of the picture +size is (locally) switched off and the node coordinate will no longer be +correct. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[transform canvas={scale=2},blue] (0,0) -- (1,1) -- (1,0); + \draw[transform canvas={rotate=180},red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transform:canvas", + meta = "⟨options⟩" + }, + ["transform shape"] = { + details = [[ +Causes the current "external" transformation matrix to be applied to the +shape. For example, if you said `\tikz[scale=3]` and then say +`node[transform shape] {X}`, you will get a "huge" X in your graphic. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transform:shape" + }, + ["transform shape nonlinear"] = { + details = [[ +When set to true, TikZ 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 ??. + + \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} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transform:shape:nonlinear", + meta = "⟨true or false⟩" + }, + transition = { + details = [[ +This style indicates that a node is a transition. As for places, the +text of a transition should be empty and the `label` option should be +used for adding labels. + +To connect a transition to places, you can use the `edge` command as in +the following example: + + \begin{tikzpicture} + \node[place,tokens=2,label=above:$p_1$] (p1) {}; + \node[place,label=above:$p_2\ge1$,right=of p1] (p2) {}; + + \node[transition,below right=of p1,label=below:$t_1$] {} + edge[pre] (p1) + edge[post] node[auto] {2} (p2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transition" + }, + ["transparency group"] = { + details = [[ +This option can be given to a `scope`. It will have the following +effect: The scope's contents is 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). For instance, in the forbidden sign example, the whole sign is +first painted (conceptually) like the image on the left hand side. Note +that some pixels of the sign are painted multiple times (up to three +times), but only the last color "wins". + +Then, when the scope is finished, it is painted as a whole. The *fill* +transparency settings are now applied to the resulting picture. For +instance, the pixel that has been painted three times is just red at the +end, so this red color will be blended with whatever is "behind" the +group on the page. + + \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} + +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 *inside* the group, you +need to open another scope inside it or use the `opacity` key with a +command inside the group: + + \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} + +The ⟨options⟩ are a list of comma-separated options: + +- `knockout` When this option is given inside the ⟨options⟩, the group + becomes a so-called *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 TikZ in the middle): + + \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=\fontencoding{T1}\fontfamily{ptm}\fontsize{45}{45}\bfseries] + {Ti\emph{k}Z}; + \end{scope} + \end{tikzpicture} + + 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. + +- `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 PDF + Specification, version 1.7. + +Note that when a transparency group is created, TikZ 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 ?? on how to +sidestep this problem in such cases. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transparency:group", + meta = "\\oarg{options}" + }, + transparent = { + details = [[ +Makes everything totally transparent and, hence, invisible. + + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/transparent" + }, + ["trim left"] = { + details = [[ +The `trim left` key tells PGFto discard everything which is left of the +provided ⟨dimension or coordinate⟩. Here, ⟨dimension⟩ is a single $x$ +coordinate of the picture and ⟨coordinate⟩ is a point with $x$ and $y$ +coordinates (but only its $x$ coordinate will be used). The effect is +the same as if you issue `\hspace{-s}` where `s` is the difference of +the picture's bounding box lower left $x$ coordinate and the $x$ +coordinate specified as ⟨dimension or coordinate⟩: + + Text before image.% + \begin{tikzpicture}[trim left] + \draw (-1,-1) grid (3,2); + \fill (0,0) circle (5pt); + \end{tikzpicture}% + Text after image. + +Since `trim left` uses the default `trim left=0pt`, everything left of +$x=0$ is removed from the bounding box. + +The following example has once the relative long label $-1$ and once the +shorter label $1$. Horizontal alignment is established with `trim left`: + + \begin{tikzpicture} + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$-1$}; + \end{tikzpicture} + \par + \begin{tikzpicture} + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$1$}; + \end{tikzpicture} + \par + \begin{tikzpicture}[trim left] + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$-1$}; + \end{tikzpicture} + \par + \begin{tikzpicture}[trim left] + \draw (0,1) -- (0,0) -- (1,1) -- cycle; + \fill (0,0) circle (2pt); + \node[left] at (0,0) {$1$}; + \end{tikzpicture} + +Use `trim left=default` to reset the value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/trim:left", + meta = "⟨dimension or coordinate or default⟩" + }, + ["trim right"] = { + details = [[ +This key is similar to `trim left`: it discards everything which is +right of the provided ⟨dimension or coordinate⟩. As for `trim left`, +⟨dimension⟩ denotes a single $x$ coordinate of the picture and +⟨coordinate⟩ a coordinate with $x$ and $y$ value (although only its $x$ +component will be used). + +We use the same example from above and add `trim right`: + + Text before image.% + \begin{tikzpicture}[trim left, trim right=2cm, baseline] + \draw (-1,-1) grid (3,2); + \fill (0,0) circle (5pt); + \end{tikzpicture}% + Text after image. + +In addition to `trim left=0pt`, we also discard everything which is +right of $x$`=2cm`. Furthermore, the `baseline` key supports vertical +alignment as well (using the $y$`=0cm` baseline). + +Use `trim right=default` to reset the value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/trim:right", + meta = "⟨dimension or coordinate or default⟩" + }, + turn = { + details = [[ +This key can be given as an option to a ⟨coordinate⟩ as in the following +example: + + \tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm); + +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 ⟨relative angle⟩`:`⟨distance⟩ together with the +`turn` option, you specify a point that lies at ⟨distance⟩ from the last +point in the direction of the last tangent entering the last point, but +with a rotation of ⟨relative angle⟩. + +This key also works with curves ... + + \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); + + \tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm); + +...and with plots ... + + \tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm); + +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. + + \tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1) + .. controls ([turn]0:1cm) .. ([turn]-90:1cm); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turn" + }, + turtle = { + details = [[ +This key executes the ⟨keys⟩ with the current key path set to +`/tikz/turtle`. + + \tikz[turtle/distance=2mm] + \draw [turtle={home,fd,rt,fd,lt,fd,lt,fd}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle", + meta = "⟨keys⟩" + }, + ["turtle/back"] = { + details = [[ +This has the same effect as a `turtle/forward` for the negated +⟨distance⟩ value. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/back", + meta = "⟨distance⟩" + }, + ["turtle/bk"] = { + details = [[ +An abbreviation for the `back` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/bk" + }, + ["turtle/distance"] = { + details = [[ +The default distance by which the turtle advances. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/distance", + meta = "⟨distance⟩" + }, + ["turtle/fd"] = { + details = [[ +An abbreviation for the `forward` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/fd" + }, + ["turtle/forward"] = { + details = [[ +Makes the turtle move forward by the given ⟨distance⟩. If no ⟨distance⟩ +is specified, the current value of the following key is used: + +"Moving forward the turtle" actually means that, relative to the current +last point on the path, a point at the given ⟨distance⟩ in the direction +the turtle is currently heading is computed. Then, the operation +`to[turtle/how]` is used to extend the path to this point. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/forward", + meta = "⟨distance⟩" + }, + ["turtle/home"] = { + details = [[ +Places the turtle at the origin and lets it head upward. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/home" + }, + ["turtle/how"] = { + details = [[ +This style can set up the `to path` used by turtles. By setting this +style you can change the to-path: + + \tikz \draw [turtle={how/.style={bend left},home,forward,right,forward}]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/how" + }, + ["turtle/left"] = { + details = [[ +Turns the turtle left by the given angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/left", + meta = "⟨angle⟩" + }, + ["turtle/lt"] = { + details = [[ +An abbreviation for the `left` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/lt" + }, + ["turtle/right"] = { + details = [[ +Turns the turtle right by the given angle. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/right", + meta = "⟨angle⟩" + }, + ["turtle/rt"] = { + details = [[ +An abbreviation for the `right` key. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/turtle/rt" + }, + ["ultra nearly opaque"] = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ultra:nearly:opaque" + }, + ["ultra nearly transparent"] = { + details = [[ +Makes everything, well, ultra nearly transparent. + + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ultra:nearly:transparent" + }, + ["ultra thick"] = { + details = [[ +Sets the line width to 1.6pt. + + \tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ultra:thick" + }, + ["ultra thin"] = { + details = [[ +Sets the line width to 0.1pt. + + \tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ultra:thin" + }, + ["upper left"] = { + details = [[ +Works like `lower left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/upper:left", + meta = "⟨color⟩" + }, + ["upper right"] = { + details = [[ +Works like `lower left`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/upper:right", + meta = "⟨color⟩" + }, + ["use as bounding box"] = { + details = [[ +Normally, when this option is given on a path, the bounding box of the +present path is used to determine the size of the picture and the size +of all *subsequent* paths are ignored. However, if there were previous +path operations that have already established a larger bounding box, it +will not be made smaller by this operation (consider the +`\pgfresetboundingbox` command to reset the previous bounding box). + +In a sense, `use as bounding box` has the same effect as clipping all +subsequent drawing against the current path -- without actually doing +the clipping, only making PGF treat everything as if it were clipped. + +The first application of this option is to have a `{tikzpicture}` +overlap with the main text: + + Left of picture\begin{tikzpicture} + \draw[use as bounding box] (2,0) rectangle (3,1); + \draw (1,0) -- (4,.75); + \end{tikzpicture}right of picture. + +In a second application this option can be used to get better control +over the white space around the picture: + + Left of picture + \begin{tikzpicture} + \useasboundingbox (0,0) rectangle (3,1); + \fill (.75,.25) circle (.5cm); + \end{tikzpicture} + right of picture. + +Note: If this option is used on a path inside a TeX group (scope), the +effect "lasts" only until the end of the scope. Again, this behavior is +the same as for clipping. + +Consider using `\useasboundingbox` together with `\pgfresetboundingbox` +in order to replace the bounding box with a new one. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/use:as:bounding:box" + }, + ["use path"] = { + details = [[ +Set the current path to the soft path stored in ⟨macro⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/use:path", + meta = "⟨macro⟩" + }, + variable = { + details = [[ +Sets the macro whose value is set to the different values when +⟨coordinate expression⟩ is evaluated. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/variable", + meta = "⟨macro⟩" + }, + ["very near end"] = { + details = [[ +Set to `pos=0.875`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:near:end" + }, + ["very near start"] = { + details = [[ +Set to `pos=0.125`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:near:start" + }, + ["very nearly opaque"] = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:nearly:opaque" + }, + ["very nearly transparent"] = { + details = [[ + \tikz{\fill[red] (0,0) rectangle (1,0.5); + \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); } +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:nearly:transparent" + }, + ["very thick"] = { + details = [[ +Sets the line width to 1.2pt. + + \tikz \draw[very thick] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:thick" + }, + ["very thin"] = { + details = [[ +Sets the line width to 0.2pt. + + \tikz \draw[very thin] (0,0) -- (1cm,1.5ex); +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/very:thin" + }, + view = { + details = [[ +This is an alias for `/tikz/meet`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/view" + }, + ["visualizer color"] = { + details = [[ +This key is used to set the color `visualizer color` to ⟨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. + + 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] + };}, + ] + \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}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/visualizer:color", + meta = "⟨color⟩" + }, + ["week list"] = { + details = [[ +This style creates one row for each week in the range. The value of +`day xshift` is used for the distance between days in each week row, the +value of `day yshift` is used for the distance between rows. In both +cases, "distance" refers to the distance between the anchors of the +nodes of the days (or, more generally, the distance between the origins +of the little pictures created for each day). + +The days inside each week are shifted such that Monday is always at the +first position (to change this, you need to copy and then modify the +code appropriately). If the date range does not start on a Monday, the +first line will not start in the first column, but rather in the column +appropriate for the first date in the range. + +At the beginning of each month (except for the first month in the range) +an additional vertical space of `month yshift` is added. If this is set +to `0pt` you get a continuous list of days. + + \tikz + \calendar [dates=2000-01-01 to 2000-02-last,week list]; + + \tikz + \calendar [dates=2000-01-01 to 2000-02-last,week list, + month yshift=0pt]; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/week:list" + }, + width = { + details = [[ +Inside a `spy scope`, this is a shortcut for `minimum width`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/width", + meta = "⟨dimension⟩" + }, + x = { + details = [[ +If ⟨value⟩ is a dimension, the $x$-vector of PGF's $xyz$-coordinate +system is set up to point ⟨value⟩ to the right, that is, to +$(⟨value⟩,0pt)$. + + \begin{tikzpicture} + \draw (0,0) -- +(1,0); + \draw[x=2cm,color=red] (0,0.1) -- +(1,0); + \end{tikzpicture} + + \tikz \draw[x=1.5cm] (0,0) grid (2,2); + +The last example shows that the size of steppings in grids, just like +all other dimensions, are not affected by the $x$-vector. After all, the +$x$-vector is only used to determine the coordinate of the upper right +corner of the grid. + +If ⟨value⟩ is a coordinate, the $x$-vector of PGF's $xyz$-coordinate +system is set to the specified coordinate. If ⟨value⟩ contains a comma, +it must be put in braces. + + \begin{tikzpicture} + \draw (0,0) -- (1,0); + \draw[x={(2cm,0.5cm)},color=red] (0,0) -- (1,0); + \end{tikzpicture} + +You can use this, for example, to exchange the meaning of the $x$- and +$y$-coordinate. + + \begin{tikzpicture}[smooth] + \draw plot coordinates{(1,0) (2,0.5) (3,0) (3,1)}; + \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red] + plot coordinates{(1,0) (2,0.5) (3,0) (3,1)}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/x", + meta = "⟨value⟩" + }, + ["x radius"] = { + details = [[ +Sets the horizontal radius of the circle (which, when this value is +different form the vertical radius, is actually an ellipse). The ⟨value⟩ +may either be a dimension or a dimensionless number. In the latter case, +the number is interpreted in the $xy$-coordinate system (if the $x$-unit +is set to, say, `2cm`, then `x radius=3` will have the same effect as +`x radius=6cm`). +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/x:radius", + meta = "⟨value⟩" + }, + xbar = { + details = [[ +This option works like `ybar` except that the bars are horizontal. + + \tikz \draw[pattern=north west lines] plot[xbar] + coordinates{(1,0) (0.4,1) (1.7,2) (1.6,3)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xbar" + }, + ["xbar interval"] = { + details = [[ +Works like `ybar interval`, but for horizontal bar plots. + + \begin{tikzpicture}[xbar interval,x=0.5cm,y=0.5cm] + \draw[color=red,fill=red!80] + plot coordinates {(3,0) (2,1) (4,1.5) (1,4) (2,6) (2,7)}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xbar:interval" + }, + xcomb = { + details = [[ +This option works like `ycomb` except that the bars are horizontal. + + \tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xcomb" + }, + xrange = { + details = [[ +Set the $x$-range. This makes sense only for parametric plots. + + \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)}; +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xrange", + meta = "⟨start⟩:⟨end⟩" + }, + xscale = { + details = [[ +Multiplies only the $x$-value of all coordinates by the given ⟨factor⟩. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xscale=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[xscale=-1,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xscale", + meta = "⟨factor⟩" + }, + xshift = { + details = [[ +Adds ⟨dimension⟩ to the $x$ value of all coordinates. + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xshift=2cm,blue] (0,0) -- (1,1) -- (1,0); + \draw[xshift=-10pt,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xshift", + meta = "⟨dimension⟩" + }, + xslant = { + details = [[ +Slants the coordinate horizontally by the given ⟨factor⟩: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[xslant=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[xslant=-1,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xslant", + meta = "⟨factor⟩" + }, + xstep = { + details = [[ +Sets the stepping in the $x$-direction. + + \begin{tikzpicture} + \draw (0,0) grid [xstep=.5,ystep=.75] (3,2); + \draw[ultra thick] (0,0) grid [ystep=0] (3,2); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/xstep", + meta = "⟨dimension or number⟩" + }, + y = { + details = [[ +Works like the `x=` option, only if ⟨value⟩ is a dimension, the +resulting vector points to $(0,⟨value⟩)$. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/y", + meta = "⟨value⟩" + }, + ["y radius"] = { + details = [[ +Works like the `x radius`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/y:radius", + meta = "⟨value⟩" + }, + ybar = { + details = [[ +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. + + \tikz\draw[draw=blue,fill=blue!60!black] plot[ybar] file{plots/pgfmanual-sine.table}; + + \begin{tikzpicture}[ybar] + \draw[color=red,fill=red!80,bar width=6pt] + plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)}; + \draw[color=red!50,fill=red!20,bar width=4pt,bar shift=3pt] + plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; + \end{tikzpicture} + +The use of `bar width` and `bar shift` is explained in the +`plothandlers` library documentation, section ??. Please refer to +page ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ybar" + }, + ["ybar interval"] = { + details = [[ +As `/tikz/ybar`, this options produces vertical bars. However, bars are +centered at coordinate *intervals* instead of interval edges, and the +bar's width is also determined relatively to the interval's length: + + \begin{tikzpicture}[ybar interval,x=10pt] + \draw[color=red,fill=red!80] + plot coordinates{(0,2) (2,1.2) (3,.3) (5,1.7) (8,.9) (9,.9)}; + \end{tikzpicture} + +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 widths, which is +explained in the `plothandlers` library documentation, section ??. +Please refer to page ??. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ybar:interval" + }, + ycomb = { + details = [[ +This option causes the `plot` operation to interpret the plotting points +differently. Instead of connecting them, for each point of the plot a +straight line is added to the path from the $x$-axis to the point, +resulting in a sort of "comb" or "bar diagram". + + \tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table}; + + \begin{tikzpicture}[ycomb] + \draw[color=red,line width=6pt] + plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)}; + \draw[color=red!50,line width=4pt,xshift=3pt] + plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ycomb" + }, + ["year code"] = { + details = [[ +Works like `month code`, only for years. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/year:code", + meta = "⟨code⟩" + }, + ["year text"] = { + details = [[ +Works like `month text`, only for years. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/year:text", + meta = "⟨text⟩" + }, + yrange = { + details = [[ +Same as `range`. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/yrange", + meta = "⟨start⟩:⟨end⟩" + }, + yscale = { + details = [[ +Multiplies only the $y$-value of all coordinates by ⟨factor⟩. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/yscale", + meta = "⟨factor⟩" + }, + yshift = { + details = [[ +Adds ⟨dimension⟩ to the $y$ value of all coordinates. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/yshift", + meta = "⟨dimension⟩" + }, + yslant = { + details = [[ +Slants the coordinate vertically by the given ⟨factor⟩: + + \begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \draw (0,0) -- (1,1) -- (1,0); + \draw[yslant=2,blue] (0,0) -- (1,1) -- (1,0); + \draw[yslant=-1,red] (0,0) -- (1,1) -- (1,0); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/yslant", + meta = "⟨factor⟩" + }, + ystep = { + details = [[ +Sets the stepping in the $y$-direction. +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/ystep", + meta = "⟨dimension or number⟩" + }, + z = { + details = [[ +Works like the `y=` option, but now a dimension is the point +$(⟨value⟩,⟨value⟩)$. + + \begin{tikzpicture}[z=-1cm,->,thick] + \draw[color=red] (0,0,0) -- (1,0,0); + \draw[color=blue] (0,0,0) -- (0,1,0); + \draw[color=orange] (0,0,0) -- (0,0,1); + \end{tikzpicture} +]], + documentation = "texmf:doc/generic/pgf/pgfmanual.pdf#pgf./tikz/z", + meta = "⟨value⟩" + } + } +} diff --git a/support/digestif/data/unicode-math.sty.tags b/support/digestif/data/unicode-math.sty.tags new file mode 100644 index 0000000000..ee07354621 --- /dev/null +++ b/support/digestif/data/unicode-math.sty.tags @@ -0,0 +1,10021 @@ +-- Copyright 2006-2019 Will Robertson +-- Copyright 2010-2017 Philipp Stephani +-- Copyright 2011-2017 Joseph Wright +-- Copyright 2012-2015 Khaled Hosny +-- Copyright 2022 Augusto Stoffel +-- SPDX-License-Identifier: LPPL-1.3c+ +-- +-- Adapted from the file unicode-math-table.tex, part of +-- the unicode-math package, which can be found at +-- https://github.com/wspr/unicode-math/ +ctan_package = "unicode-math" +commands = { + APLboxquestion = { + doc = "boxed question mark", + symbol = "⍰" + }, + APLboxupcaret = { + doc = "boxed up caret", + symbol = "⍓" + }, + APLnotbackslash = { + doc = "apl functional symbol backslash bar", + symbol = "⍀" + }, + APLnotslash = { + doc = "solidus, bar through (apl functional symbol slash bar)", + symbol = "⌿" + }, + Alpha = { + doc = "capital alpha, greek", + symbol = "Α" + }, + Angstrom = { + doc = "angstrom capital a, ring", + symbol = "Å" + }, + Barv = { + doc = "short down tack with overbar", + symbol = "⫧" + }, + BbbA = { + doc = "mathematical double-struck capital a", + symbol = "𝔸" + }, + BbbB = { + doc = "mathematical double-struck capital b", + symbol = "𝔹" + }, + BbbC = { + doc = "/bbb c, open face c", + symbol = "ℂ" + }, + BbbD = { + doc = "mathematical double-struck capital d", + symbol = "𝔻" + }, + BbbE = { + doc = "mathematical double-struck capital e", + symbol = "𝔼" + }, + BbbF = { + doc = "mathematical double-struck capital f", + symbol = "𝔽" + }, + BbbG = { + doc = "mathematical double-struck capital g", + symbol = "𝔾" + }, + BbbGamma = { + doc = "double-struck capital gamma", + symbol = "ℾ" + }, + BbbH = { + doc = "/bbb h, open face h", + symbol = "ℍ" + }, + BbbI = { + doc = "mathematical double-struck capital i", + symbol = "𝕀" + }, + BbbJ = { + doc = "mathematical double-struck capital j", + symbol = "𝕁" + }, + BbbK = { + doc = "mathematical double-struck capital k", + symbol = "𝕂" + }, + BbbL = { + doc = "mathematical double-struck capital l", + symbol = "𝕃" + }, + BbbM = { + doc = "mathematical double-struck capital m", + symbol = "𝕄" + }, + BbbN = { + doc = "/bbb n, open face n", + symbol = "ℕ" + }, + BbbO = { + doc = "mathematical double-struck capital o", + symbol = "𝕆" + }, + BbbP = { + doc = "/bbb p, open face p", + symbol = "ℙ" + }, + BbbPi = { + doc = "double-struck capital pi", + symbol = "ℿ" + }, + BbbQ = { + doc = "/bbb q, open face q", + symbol = "ℚ" + }, + BbbR = { + doc = "/bbb r, open face r", + symbol = "ℝ" + }, + BbbS = { + doc = "mathematical double-struck capital s", + symbol = "𝕊" + }, + BbbT = { + doc = "mathematical double-struck capital t", + symbol = "𝕋" + }, + BbbU = { + doc = "mathematical double-struck capital u", + symbol = "𝕌" + }, + BbbV = { + doc = "mathematical double-struck capital v", + symbol = "𝕍" + }, + BbbW = { + doc = "mathematical double-struck capital w", + symbol = "𝕎" + }, + BbbX = { + doc = "mathematical double-struck capital x", + symbol = "𝕏" + }, + BbbY = { + doc = "mathematical double-struck capital y", + symbol = "𝕐" + }, + BbbZ = { + doc = "/bbb z, open face z", + symbol = "ℤ" + }, + Bbba = { + doc = "mathematical double-struck small a", + symbol = "𝕒" + }, + Bbbb = { + doc = "mathematical double-struck small b", + symbol = "𝕓" + }, + Bbbc = { + doc = "mathematical double-struck small c", + symbol = "𝕔" + }, + Bbbd = { + doc = "mathematical double-struck small d", + symbol = "𝕕" + }, + Bbbe = { + doc = "mathematical double-struck small e", + symbol = "𝕖" + }, + Bbbeight = { + doc = "mathematical double-struck digit 8", + symbol = "𝟠" + }, + Bbbf = { + doc = "mathematical double-struck small f", + symbol = "𝕗" + }, + Bbbfive = { + doc = "mathematical double-struck digit 5", + symbol = "𝟝" + }, + Bbbfour = { + doc = "mathematical double-struck digit 4", + symbol = "𝟜" + }, + Bbbg = { + doc = "mathematical double-struck small g", + symbol = "𝕘" + }, + Bbbgamma = { + doc = "double-struck small gamma", + symbol = "ℽ" + }, + Bbbh = { + doc = "mathematical double-struck small h", + symbol = "𝕙" + }, + Bbbi = { + doc = "mathematical double-struck small i", + symbol = "𝕚" + }, + Bbbj = { + doc = "mathematical double-struck small j", + symbol = "𝕛" + }, + Bbbk = { + doc = "mathematical double-struck small k", + symbol = "𝕜" + }, + Bbbl = { + doc = "mathematical double-struck small l", + symbol = "𝕝" + }, + Bbbm = { + doc = "mathematical double-struck small m", + symbol = "𝕞" + }, + Bbbn = { + doc = "mathematical double-struck small n", + symbol = "𝕟" + }, + Bbbnine = { + doc = "mathematical double-struck digit 9", + symbol = "𝟡" + }, + Bbbo = { + doc = "mathematical double-struck small o", + symbol = "𝕠" + }, + Bbbone = { + doc = "mathematical double-struck digit 1", + symbol = "𝟙" + }, + Bbbp = { + doc = "mathematical double-struck small p", + symbol = "𝕡" + }, + Bbbpi = { + doc = "double-struck small pi", + symbol = "ℼ" + }, + Bbbq = { + doc = "mathematical double-struck small q", + symbol = "𝕢" + }, + Bbbr = { + doc = "mathematical double-struck small r", + symbol = "𝕣" + }, + Bbbs = { + doc = "mathematical double-struck small s", + symbol = "𝕤" + }, + Bbbseven = { + doc = "mathematical double-struck digit 7", + symbol = "𝟟" + }, + Bbbsix = { + doc = "mathematical double-struck digit 6", + symbol = "𝟞" + }, + Bbbsum = { + doc = "double-struck n-ary summation", + symbol = "⅀" + }, + Bbbt = { + doc = "mathematical double-struck small t", + symbol = "𝕥" + }, + Bbbthree = { + doc = "mathematical double-struck digit 3", + symbol = "𝟛" + }, + Bbbtwo = { + doc = "mathematical double-struck digit 2", + symbol = "𝟚" + }, + Bbbu = { + doc = "mathematical double-struck small u", + symbol = "𝕦" + }, + Bbbv = { + doc = "mathematical double-struck small v", + symbol = "𝕧" + }, + Bbbw = { + doc = "mathematical double-struck small w", + symbol = "𝕨" + }, + Bbbx = { + doc = "mathematical double-struck small x", + symbol = "𝕩" + }, + Bbby = { + doc = "mathematical double-struck small y", + symbol = "𝕪" + }, + Bbbz = { + doc = "mathematical double-struck small z", + symbol = "𝕫" + }, + Bbbzero = { + doc = "mathematical double-struck digit 0", + symbol = "𝟘" + }, + Beta = { + doc = "capital beta, greek", + symbol = "Β" + }, + Bumpeq = { + doc = "bumpy equals", + symbol = "≎" + }, + Cap = { + doc = "/cap /doublecap b: double intersection", + symbol = "⋒" + }, + Chi = { + doc = "capital chi, greek", + symbol = "Χ" + }, + Colon = { + doc = "two colons", + symbol = "∷" + }, + Coloneq = { + doc = "double colon equal", + symbol = "⩴" + }, + Cup = { + doc = "/cup /doublecup b: double union", + symbol = "⋓" + }, + DDownarrow = { + doc = "downwards quadruple arrow", + symbol = "⟱" + }, + DashV = { + doc = "double vertical bar double left turnstile", + symbol = "⫥" + }, + DashVDash = { + doc = "left and right double turnstile", + symbol = "⟚" + }, + Dashv = { + doc = "vertical bar double left turnstile", + symbol = "⫤" + }, + Ddownarrow = { + doc = "downwards triple arrow", + symbol = "⤋" + }, + Delta = { + doc = "capital delta, greek", + symbol = "Δ" + }, + Doteq = { + doc = "/doteqdot /doteq r: equals, even dots", + symbol = "≑" + }, + Downarrow = { + doc = "down double arrow", + symbol = "⇓" + }, + Epsilon = { + doc = "capital epsilon, greek", + symbol = "Ε" + }, + Equiv = { + doc = "strict equivalence (4 lines)", + symbol = "≣" + }, + Eta = { + doc = "capital eta, greek", + symbol = "Η" + }, + Eulerconst = { + doc = "euler constant", + symbol = "ℇ" + }, + Exclam = { + doc = "double exclamation mark", + symbol = "‼" + }, + Finv = { + doc = "turned capital f", + symbol = "Ⅎ" + }, + Game = { + doc = "turned sans-serif capital g", + symbol = "⅁" + }, + Gamma = { + doc = "capital gamma, greek", + symbol = "Γ" + }, + Gt = { + doc = "double nested greater-than", + symbol = "⪢" + }, + Hermaphrodite = { + doc = "male and female sign", + symbol = "⚥" + }, + Im = { + doc = "imaginary part", + symbol = "ℑ" + }, + Iota = { + doc = "capital iota, greek", + symbol = "Ι" + }, + Join = { + doc = "join", + symbol = "⨝" + }, + Kappa = { + doc = "capital kappa, greek", + symbol = "Κ" + }, + LLeftarrow = { + doc = "leftwards quadruple arrow", + symbol = "⭅" + }, + Lambda = { + doc = "capital lambda, greek", + symbol = "Λ" + }, + Lbrbrak = { + doc = "mathematical left white tortoise shell bracket", + symbol = "⟬" + }, + Ldsh = { + doc = "left down angled arrow", + symbol = "↲" + }, + Leftarrow = { + doc = "is implied by", + symbol = "⇐" + }, + Leftrightarrow = { + doc = "left and right double arrow", + symbol = "⇔" + }, + Lleftarrow = { + doc = "left triple arrow", + symbol = "⇚" + }, + Longleftarrow = { + doc = "long leftwards double arrow", + symbol = "⟸" + }, + Longleftrightarrow = { + doc = "long left right double arrow", + symbol = "⟺" + }, + Longmapsfrom = { + doc = "long leftwards double arrow from bar", + symbol = "⟽" + }, + Longmapsto = { + doc = "long rightwards double arrow from bar", + symbol = "⟾" + }, + Longrightarrow = { + doc = "long rightwards double arrow", + symbol = "⟹" + }, + Lparengtr = { + doc = "double left arc greater-than bracket", + symbol = "⦕" + }, + Lsh = { + doc = "/lsh a:", + symbol = "↰" + }, + Lt = { + doc = "double nested less-than", + symbol = "⪡" + }, + Lvzigzag = { + doc = "left double wiggly fence", + symbol = "⧚" + }, + Mapsfrom = { + doc = "leftwards double arrow from bar", + symbol = "⤆" + }, + Mapsto = { + doc = "rightwards double arrow from bar", + symbol = "⤇" + }, + Mu = { + doc = "capital mu, greek", + symbol = "Μ" + }, + Nearrow = { + doc = "ne pointing double arrow", + symbol = "⇗" + }, + Not = { + doc = "double stroke not sign", + symbol = "⫬" + }, + Nu = { + doc = "capital nu, greek", + symbol = "Ν" + }, + Nwarrow = { + doc = "nw pointing double arrow", + symbol = "⇖" + }, + Omega = { + doc = "capital omega, greek", + symbol = "Ω" + }, + Omicron = { + doc = "capital omicron, greek", + symbol = "Ο" + }, + Otimes = { + doc = "multiplication sign in double circle", + symbol = "⨷" + }, + Phi = { + doc = "capital phi, greek", + symbol = "Φ" + }, + Pi = { + doc = "capital pi, greek", + symbol = "Π" + }, + Planckconst = { + doc = "planck constant", + symbol = "ℎ" + }, + Prec = { + doc = "double precedes", + symbol = "⪻" + }, + PropertyLine = { + doc = "property line", + symbol = "⅊" + }, + Psi = { + doc = "capital psi, greek", + symbol = "Ψ" + }, + QED = { + doc = "end of proof", + symbol = "∎" + }, + Question = { + doc = "double question mark", + symbol = "⁇" + }, + RRightarrow = { + doc = "rightwards quadruple arrow", + symbol = "⭆" + }, + Rbrbrak = { + doc = "mathematical right white tortoise shell bracket", + symbol = "⟭" + }, + Rdsh = { + doc = "right down angled arrow", + symbol = "↳" + }, + Re = { + doc = "real part", + symbol = "ℜ" + }, + Rho = { + doc = "capital rho, greek", + symbol = "Ρ" + }, + Rightarrow = { + doc = "implies", + symbol = "⇒" + }, + Rparenless = { + doc = "double right arc less-than bracket", + symbol = "⦖" + }, + Rrightarrow = { + doc = "right triple arrow", + symbol = "⇛" + }, + Rsh = { + doc = "/rsh a:", + symbol = "↱" + }, + Rvzigzag = { + doc = "right double wiggly fence", + symbol = "⧛" + }, + Searrow = { + doc = "se pointing double arrow", + symbol = "⇘" + }, + Sigma = { + doc = "capital sigma, greek", + symbol = "Σ" + }, + Sqcap = { + doc = "double square intersection", + symbol = "⩎" + }, + Sqcup = { + doc = "double square union", + symbol = "⩏" + }, + Subset = { + doc = "double subset", + symbol = "⋐" + }, + Succ = { + doc = "double succeeds", + symbol = "⪼" + }, + Supset = { + doc = "double superset", + symbol = "⋑" + }, + Swarrow = { + doc = "sw pointing double arrow", + symbol = "⇙" + }, + Tau = { + doc = "capital tau, greek", + symbol = "Τ" + }, + Theta = { + doc = "capital theta, greek", + symbol = "Θ" + }, + UUparrow = { + doc = "upwards quadruple arrow", + symbol = "⟰" + }, + Uparrow = { + doc = "up double arrow", + symbol = "⇑" + }, + Updownarrow = { + doc = "up and down double arrow", + symbol = "⇕" + }, + Upsilon = { + doc = "capital upsilon, greek", + symbol = "Υ" + }, + Uuparrow = { + doc = "upwards triple arrow", + symbol = "⤊" + }, + VDash = { + doc = "double vert, double dash", + symbol = "⊫" + }, + Vbar = { + doc = "double up tack", + symbol = "⫫" + }, + Vdash = { + doc = "double vertical, dash", + symbol = "⊩" + }, + Vee = { + doc = "double logical or", + symbol = "⩔" + }, + Vert = { + doc = "double vertical bar", + symbol = "‖" + }, + Vvdash = { + doc = "triple vertical, dash", + symbol = "⊪" + }, + Vvert = { + doc = "triple vertical bar delimiter", + symbol = "⦀" + }, + Wedge = { + doc = "double logical and", + symbol = "⩓" + }, + Xi = { + doc = "capital xi, greek", + symbol = "Ξ" + }, + Yup = { + doc = "turned sans-serif capital y", + symbol = "⅄" + }, + Zbar = { + doc = "impedance (latin capital letter z with stroke)", + symbol = "Ƶ" + }, + Zeta = { + doc = "capital zeta, greek", + symbol = "Ζ" + }, + accurrent = { + doc = "ac current", + symbol = "⏦" + }, + acidfree = { + doc = "permanent paper sign", + symbol = "♾" + }, + acute = { + doc = "acute accent", + symbol = "◌́" + }, + acwcirclearrow = { + doc = "anticlockwise closed circle arrow", + symbol = "⥀" + }, + acwgapcirclearrow = { + doc = "anticlockwise gapped circle arrow", + symbol = "⟲" + }, + acwleftarcarrow = { + doc = "left-side arc anticlockwise arrow", + symbol = "⤹" + }, + acwopencirclearrow = { + doc = "anticlockwise open circle arrow", + symbol = "↺" + }, + acwoverarcarrow = { + doc = "top arc anticlockwise arrow", + symbol = "⤺" + }, + acwunderarcarrow = { + doc = "bottom arc anticlockwise arrow", + symbol = "⤻" + }, + adots = { + doc = "three dots, ascending", + symbol = "⋰" + }, + aleph = { + doc = "aleph, hebrew", + symbol = "ℵ" + }, + alpha = { + doc = "small alpha, greek", + symbol = "α" + }, + amalg = { + doc = "amalgamation or coproduct", + symbol = "⨿" + }, + angdnr = { + doc = "acute angle", + symbol = "⦟" + }, + angle = { + doc = "angle", + symbol = "∠" + }, + angles = { + doc = "angle with s inside", + symbol = "⦞" + }, + angleubar = { + doc = "angle with underbar", + symbol = "⦤" + }, + annuity = { + doc = "combining annuity symbol", + symbol = "◌⃧" + }, + approx = { + doc = "approximate", + symbol = "≈" + }, + approxeq = { + doc = "approximate, equals", + symbol = "≊" + }, + approxeqq = { + doc = "approximately equal or equal to", + symbol = "⩰" + }, + approxident = { + doc = "approximately identical to", + symbol = "≋" + }, + arabichad = { + doc = "arabic mathematical operator hah with dal", + symbol = "𞻱" + }, + arabicmaj = { + doc = "arabic mathematical operator meem with hah with tatweel", + symbol = "𞻰" + }, + arceq = { + doc = "arc, equals; corresponds to", + symbol = "≘" + }, + assert = { + doc = "assertion (vertical, short dash)", + symbol = "⊦" + }, + ast = { + doc = "centered asterisk", + symbol = "∗" + }, + asteq = { + doc = "equals with asterisk", + symbol = "⩮" + }, + asteraccent = { + doc = "combining asterisk above", + symbol = "◌⃰" + }, + astrosun = { + doc = "sun", + symbol = "☉" + }, + asymp = { + doc = "asymptotically equal to", + symbol = "≍" + }, + awint = { + doc = "anticlockwise integration", + symbol = "⨑" + }, + bNot = { + doc = "reversed double stroke not sign", + symbol = "⫭" + }, + backcong = { + doc = "all equal to", + symbol = "≌" + }, + backdprime = { + doc = "double reverse prime, not superscripted", + symbol = "‶" + }, + backprime = { + doc = "reverse prime, not superscripted", + symbol = "‵" + }, + backsim = { + doc = "reverse similar", + symbol = "∽" + }, + backsimeq = { + doc = "reverse similar, equals", + symbol = "⋍" + }, + backslash = { + doc = "reverse solidus", + symbol = "\\" + }, + backtrprime = { + doc = "triple reverse prime, not superscripted", + symbol = "‷" + }, + bagmember = { + doc = "z notation bag membership", + symbol = "⋿" + }, + bar = { + doc = "macron", + symbol = "◌̄" + }, + barV = { + doc = "double down tack", + symbol = "⫪" + }, + barcap = { + doc = "intersection with overbar", + symbol = "⩃" + }, + barcup = { + doc = "union with overbar", + symbol = "⩂" + }, + bardownharpoonleft = { + doc = "downwards harpoon with barb left from bar", + symbol = "⥡" + }, + bardownharpoonright = { + doc = "downwards harpoon with barb right from bar", + symbol = "⥝" + }, + barleftarrow = { + doc = "leftwards arrow to bar", + symbol = "⇤" + }, + barleftarrowrightarrowbar = { + doc = "leftwards arrow to bar over rightwards arrow to bar", + symbol = "↹" + }, + barleftharpoondown = { + doc = "leftwards harpoon with barb down to bar", + symbol = "⥖" + }, + barleftharpoonup = { + doc = "leftwards harpoon with barb up to bar", + symbol = "⥒" + }, + barovernorthwestarrow = { + doc = "north west arrow to long bar", + symbol = "↸" + }, + barrightarrowdiamond = { + doc = "rightwards arrow from bar to black diamond", + symbol = "⤠" + }, + barrightharpoondown = { + doc = "rightwards harpoon with barb down from bar", + symbol = "⥟" + }, + barrightharpoonup = { + doc = "rightwards harpoon with barb up from bar", + symbol = "⥛" + }, + baruparrow = { + doc = "upwards arrow to bar", + symbol = "⤒" + }, + barupharpoonleft = { + doc = "upwards harpoon with barb left to bar", + symbol = "⥘" + }, + barupharpoonright = { + doc = "upwards harpoon with barb right to bar", + symbol = "⥔" + }, + barvee = { + doc = "bar, vee (large vee)", + symbol = "⊽" + }, + barwedge = { + doc = "bar, wedge (large wedge)", + symbol = "⊼" + }, + bbrktbrk = { + doc = "bottom square bracket over top square bracket", + symbol = "⎶" + }, + bdtriplevdash = { + doc = "doubly broken vert", + symbol = "┆" + }, + because = { + doc = "because", + symbol = "∵" + }, + benzenr = { + doc = "benzene ring with circle", + symbol = "⏣" + }, + beta = { + doc = "small beta, greek", + symbol = "β" + }, + beth = { + doc = "beth, hebrew", + symbol = "ℶ" + }, + between = { + doc = "between", + symbol = "≬" + }, + bigblacktriangledown = { + doc = "big down triangle, filled", + symbol = "▼" + }, + bigblacktriangleup = { + doc = "black up-pointing triangle", + symbol = "▲" + }, + bigbot = { + doc = "large up tack", + symbol = "⟘" + }, + bigcap = { + doc = "intersection operator", + symbol = "⋂" + }, + bigcup = { + doc = "union operator", + symbol = "⋃" + }, + bigcupdot = { + doc = "n-ary union operator with dot", + symbol = "⨃" + }, + biginterleave = { + doc = "large triple vertical bar operator", + symbol = "⫼" + }, + bigodot = { + doc = "n-ary circled dot operator", + symbol = "⨀" + }, + bigoplus = { + doc = "n-ary circled plus operator", + symbol = "⨁" + }, + bigotimes = { + doc = "n-ary circled times operator", + symbol = "⨂" + }, + bigslopedvee = { + doc = "sloping large or", + symbol = "⩗" + }, + bigslopedwedge = { + doc = "sloping large and", + symbol = "⩘" + }, + bigsqcap = { + doc = "n-ary square intersection operator", + symbol = "⨅" + }, + bigsqcup = { + doc = "n-ary square union operator", + symbol = "⨆" + }, + bigstar = { + doc = "star, filled", + symbol = "★" + }, + bigtalloblong = { + doc = "n-ary white vertical bar", + symbol = "⫿" + }, + bigtimes = { + doc = "n-ary times operator", + symbol = "⨉" + }, + bigtop = { + doc = "large down tack", + symbol = "⟙" + }, + bigtriangledown = { + doc = "big down triangle, open", + symbol = "▽" + }, + bigtriangleleft = { + doc = "large left triangle operator", + symbol = "⨞" + }, + bigtriangleup = { + doc = "big up triangle, open", + symbol = "△" + }, + biguplus = { + doc = "n-ary union operator with plus", + symbol = "⨄" + }, + bigvee = { + doc = "logical or operator", + symbol = "⋁" + }, + bigwedge = { + doc = "logical and operator", + symbol = "⋀" + }, + bigwhitestar = { + doc = "star, open", + symbol = "☆" + }, + blackcircledownarrow = { + doc = "black circle with down arrow", + symbol = "⧭" + }, + blackcircledrightdot = { + doc = "black circle with white dot right", + symbol = "⚈" + }, + blackcircledtwodots = { + doc = "black circle with two white dots", + symbol = "⚉" + }, + blackcircleulquadwhite = { + doc = "circle with all but upper left quadrant black", + symbol = "◕" + }, + blackdiamonddownarrow = { + doc = "black diamond with down arrow", + symbol = "⧪" + }, + blackhourglass = { + doc = "black hourglass", + symbol = "⧗" + }, + blackinwhitediamond = { + doc = "white diamond containing black small diamond", + symbol = "◈" + }, + blackinwhitesquare = { + doc = "white square containing black small square", + symbol = "▣" + }, + blacklefthalfcircle = { + doc = "left half black circle", + symbol = "◖" + }, + blackpointerleft = { + doc = "black left-pointing pointer", + symbol = "◄" + }, + blackpointerright = { + doc = "black right-pointing pointer", + symbol = "►" + }, + blackrighthalfcircle = { + doc = "right half black circle", + symbol = "◗" + }, + blacksmiley = { + doc = "black smiling face", + symbol = "☻" + }, + blacktriangle = { + doc = "up triangle, filled", + symbol = "▴" + }, + blacktriangledown = { + doc = "down triangle, filled", + symbol = "▾" + }, + blacktriangleleft = { + doc = "(large) left triangle, filled", + symbol = "◀" + }, + blacktriangleright = { + doc = "(large) right triangle, filled", + symbol = "▶" + }, + blanksymbol = { + doc = "blank symbol", + symbol = "␢" + }, + blkhorzoval = { + doc = "black horizontal ellipse", + symbol = "⬬" + }, + blkvertoval = { + doc = "black vertical ellipse", + symbol = "⬮" + }, + blockfull = { + doc = "full block", + symbol = "█" + }, + blockhalfshaded = { + doc = "50\\% shaded block", + symbol = "▒" + }, + blocklefthalf = { + doc = "left half block", + symbol = "▌" + }, + blocklowhalf = { + doc = "lower half block", + symbol = "▄" + }, + blockqtrshaded = { + doc = "25\\% shaded block", + symbol = "░" + }, + blockrighthalf = { + doc = "right half block", + symbol = "▐" + }, + blockthreeqtrshaded = { + doc = "75\\% shaded block", + symbol = "▓" + }, + blockuphalf = { + doc = "upper half block", + symbol = "▀" + }, + bot = { + doc = "bottom", + symbol = "⊥" + }, + botsemicircle = { + doc = "lower half circle", + symbol = "◡" + }, + bowtie = { + doc = "bowtie", + symbol = "⋈" + }, + boxast = { + doc = "squared asterisk", + symbol = "⧆" + }, + boxbar = { + doc = "vertical bar in box", + symbol = "◫" + }, + boxbox = { + doc = "squared square", + symbol = "⧈" + }, + boxbslash = { + doc = "squared falling diagonal slash", + symbol = "⧅" + }, + boxcircle = { + doc = "squared small circle", + symbol = "⧇" + }, + boxdiag = { + doc = "squared rising diagonal slash", + symbol = "⧄" + }, + boxdot = { + doc = "/dotsquare /boxdot b: small dot in box", + symbol = "⊡" + }, + boxminus = { + doc = "minus sign in box", + symbol = "⊟" + }, + boxonbox = { + doc = "two joined squares", + symbol = "⧉" + }, + boxplus = { + doc = "plus sign in box", + symbol = "⊞" + }, + boxtimes = { + doc = "multiply sign in box", + symbol = "⊠" + }, + breve = { + doc = "breve", + symbol = "◌̆" + }, + bsimilarleftarrow = { + doc = "reverse tilde operator above leftwards arrow", + symbol = "⭁" + }, + bsimilarrightarrow = { + doc = "reverse tilde operator above rightwards arrow", + symbol = "⭇" + }, + bsolhsub = { + doc = "reverse solidus preceding subset", + symbol = "⟈" + }, + btimes = { + doc = "semidirect product with bottom closed", + symbol = "⨲" + }, + bullseye = { + doc = "bullseye", + symbol = "◎" + }, + bumpeq = { + doc = "bumpy equals, equals", + symbol = "≏" + }, + bumpeqq = { + doc = "equals sign with bumpy above", + symbol = "⪮" + }, + candra = { + doc = "candrabindu (non-spacing)", + symbol = "◌̐" + }, + cap = { + doc = "intersection", + symbol = "∩" + }, + capbarcup = { + doc = "intersection above bar above union", + symbol = "⩉" + }, + capdot = { + doc = "intersection with dot", + symbol = "⩀" + }, + capovercup = { + doc = "intersection above union", + symbol = "⩇" + }, + capwedge = { + doc = "intersection with logical and", + symbol = "⩄" + }, + caretinsert = { + doc = "caret (insertion mark)", + symbol = "‸" + }, + carriagereturn = { + doc = "downwards arrow with corner leftward = carriage return", + symbol = "↵" + }, + ccwundercurvearrow = { + doc = "lower left semicircular anticlockwise arrow", + symbol = "⤿" + }, + cdot = { + doc = "small middle dot", + symbol = "⋅" + }, + cdotp = { + doc = "/centerdot b: middle dot", + symbol = "·" + }, + check = { + doc = "caron", + symbol = "◌̌" + }, + checkmark = { + doc = "tick, check mark", + symbol = "✓" + }, + chi = { + doc = "small chi, greek", + symbol = "χ" + }, + cirE = { + doc = "circle with two horizontal strokes to the right", + symbol = "⧃" + }, + cirbot = { + doc = "up tack with circle above", + symbol = "⟟" + }, + circeq = { + doc = "circle, equals", + symbol = "≗" + }, + circlebottomhalfblack = { + doc = "circle, filled bottom half", + symbol = "◒" + }, + circledast = { + doc = "asterisk in circle", + symbol = "⊛" + }, + circledbullet = { + doc = "circled bullet", + symbol = "⦿" + }, + circledcirc = { + doc = "small circle in circle", + symbol = "⊚" + }, + circleddash = { + doc = "hyphen in circle", + symbol = "⊝" + }, + circledequal = { + doc = "equal in circle", + symbol = "⊜" + }, + circledownarrow = { + doc = "white circle with down arrow", + symbol = "⧬" + }, + circledparallel = { + doc = "circled parallel", + symbol = "⦷" + }, + circledrightdot = { + doc = "white circle with dot right", + symbol = "⚆" + }, + circledstar = { + doc = "circled white star", + symbol = "✪" + }, + circledtwodots = { + doc = "white circle with two dots", + symbol = "⚇" + }, + circledvert = { + doc = "circled vertical bar", + symbol = "⦶" + }, + circledwhitebullet = { + doc = "circled white bullet", + symbol = "⦾" + }, + circlehbar = { + doc = "circle with horizontal bar", + symbol = "⦵" + }, + circlelefthalfblack = { + doc = "circle, filled left half [harvey ball]", + symbol = "◐" + }, + circlellquad = { + doc = "white circle with lower left quadrant", + symbol = "◵" + }, + circlelrquad = { + doc = "white circle with lower right quadrant", + symbol = "◶" + }, + circleonleftarrow = { + doc = "left arrow with small circle", + symbol = "⬰" + }, + circleonrightarrow = { + doc = "right arrow with small circle", + symbol = "⇴" + }, + circlerighthalfblack = { + doc = "circle, filled right half", + symbol = "◑" + }, + circletophalfblack = { + doc = "circle, filled top half", + symbol = "◓" + }, + circleulquad = { + doc = "white circle with upper left quadrant", + symbol = "◴" + }, + circleurquad = { + doc = "white circle with upper right quadrant", + symbol = "◷" + }, + circleurquadblack = { + doc = "circle with upper right quadrant black", + symbol = "◔" + }, + circlevertfill = { + doc = "circle with vertical fill", + symbol = "◍" + }, + cirfnint = { + doc = "circulation function", + symbol = "⨐" + }, + cirmid = { + doc = "vertical line with circle above", + symbol = "⫯" + }, + cirscir = { + doc = "circle with small circle to the right", + symbol = "⧂" + }, + closedvarcap = { + doc = "closed intersection with serifs", + symbol = "⩍" + }, + closedvarcup = { + doc = "closed union with serifs", + symbol = "⩌" + }, + closedvarcupsmashprod = { + doc = "closed union with serifs and smash product", + symbol = "⩐" + }, + closure = { + doc = "close up", + symbol = "⁐" + }, + clubsuit = { + doc = "club suit symbol", + symbol = "♣" + }, + coloneq = { + doc = "colon, equals", + symbol = "≔" + }, + commaminus = { + doc = "minus sign with comma above", + symbol = "⨩" + }, + complement = { + doc = "complement sign", + symbol = "∁" + }, + concavediamond = { + doc = "white concave-sided diamond", + symbol = "⟡" + }, + concavediamondtickleft = { + doc = "white concave-sided diamond with leftwards tick", + symbol = "⟢" + }, + concavediamondtickright = { + doc = "white concave-sided diamond with rightwards tick", + symbol = "⟣" + }, + cong = { + doc = "congruent with", + symbol = "≅" + }, + congdot = { + doc = "congruent with dot above", + symbol = "⩭" + }, + conictaper = { + doc = "conical taper", + symbol = "⌲" + }, + conjquant = { + doc = "two logical and operator", + symbol = "⨇" + }, + coprod = { + doc = "coproduct operator", + symbol = "∐" + }, + csub = { + doc = "closed subset", + symbol = "⫏" + }, + csube = { + doc = "closed subset or equal to", + symbol = "⫑" + }, + csup = { + doc = "closed superset", + symbol = "⫐" + }, + csupe = { + doc = "closed superset or equal to", + symbol = "⫒" + }, + cuberoot = { + doc = "cube root", + symbol = "∛" + }, + cup = { + doc = "union or logical sum", + symbol = "∪" + }, + cupbarcap = { + doc = "union above bar above intersection", + symbol = "⩈" + }, + cupdot = { + doc = "union, with dot", + symbol = "⊍" + }, + cupleftarrow = { + doc = "multiset", + symbol = "⊌" + }, + cupovercap = { + doc = "union above intersection", + symbol = "⩆" + }, + cupvee = { + doc = "union with logical or", + symbol = "⩅" + }, + curlyeqprec = { + doc = "curly equals, precedes", + symbol = "⋞" + }, + curlyeqsucc = { + doc = "curly equals, succeeds", + symbol = "⋟" + }, + curlyvee = { + doc = "curly logical or", + symbol = "⋎" + }, + curlywedge = { + doc = "curly logical and", + symbol = "⋏" + }, + curvearrowleft = { + doc = "left curved arrow", + symbol = "↶" + }, + curvearrowleftplus = { + doc = "top arc anticlockwise arrow with plus", + symbol = "⤽" + }, + curvearrowright = { + doc = "right curved arrow", + symbol = "↷" + }, + curvearrowrightminus = { + doc = "top arc clockwise arrow with minus", + symbol = "⤼" + }, + cwcirclearrow = { + doc = "clockwise closed circle arrow", + symbol = "⥁" + }, + cwgapcirclearrow = { + doc = "clockwise gapped circle arrow", + symbol = "⟳" + }, + cwopencirclearrow = { + doc = "clockwise open circle arrow", + symbol = "↻" + }, + cwrightarcarrow = { + doc = "right-side arc clockwise arrow", + symbol = "⤸" + }, + cwundercurvearrow = { + doc = "lower right semicircular clockwise arrow", + symbol = "⤾" + }, + dagger = { + doc = "dagger relation", + symbol = "†" + }, + daleth = { + doc = "daleth, hebrew", + symbol = "ℸ" + }, + danger = { + doc = "dangerous bend (caution sign)", + symbol = "☡" + }, + dashV = { + doc = "double vertical bar left turnstile", + symbol = "⫣" + }, + dashVdash = { + doc = "left and right tack", + symbol = "⟛" + }, + dashcolon = { + doc = "excess (-:)", + symbol = "∹" + }, + dashleftharpoondown = { + doc = "leftwards harpoon with barb down below long dash", + symbol = "⥫" + }, + dashrightharpoondown = { + doc = "rightwards harpoon with barb down below long dash", + symbol = "⥭" + }, + dashv = { + doc = "dash, vertical", + symbol = "⊣" + }, + dbkarrow = { + doc = "rightwards triple dash arrow", + symbol = "⤏" + }, + ddagger = { + doc = "double dagger relation", + symbol = "‡" + }, + ddddot = { + doc = "combining four dots above", + symbol = "◌⃜" + }, + dddot = { + doc = "combining three dots above", + symbol = "◌⃛" + }, + ddot = { + doc = "dieresis", + symbol = "◌̈" + }, + ddots = { + doc = "three dots, descending", + symbol = "⋱" + }, + ddotseq = { + doc = "equals sign with two dots above and two dots below", + symbol = "⩷" + }, + delta = { + doc = "small delta, greek", + symbol = "δ" + }, + diameter = { + doc = "diameter sign", + symbol = "⌀" + }, + diamondbotblack = { + doc = "diamond with bottom half black", + symbol = "⬙" + }, + diamondcdot = { + doc = "white diamond with centred dot", + symbol = "⟐" + }, + diamondleftarrow = { + doc = "leftwards arrow to black diamond", + symbol = "⤝" + }, + diamondleftarrowbar = { + doc = "leftwards arrow from bar to black diamond", + symbol = "⤟" + }, + diamondleftblack = { + doc = "diamond with left half black", + symbol = "⬖" + }, + diamondrightblack = { + doc = "diamond with right half black", + symbol = "⬗" + }, + diamondsuit = { + doc = "diamond suit symbol", + symbol = "♢" + }, + diamondtopblack = { + doc = "diamond with top half black", + symbol = "⬘" + }, + dicei = { + doc = "die face-1", + symbol = "⚀" + }, + diceii = { + doc = "die face-2", + symbol = "⚁" + }, + diceiii = { + doc = "die face-3", + symbol = "⚂" + }, + diceiv = { + doc = "die face-4", + symbol = "⚃" + }, + dicev = { + doc = "die face-5", + symbol = "⚄" + }, + dicevi = { + doc = "die face-6", + symbol = "⚅" + }, + dingasterisk = { + doc = "heavy teardrop-spoked asterisk", + symbol = "✽" + }, + disin = { + doc = "element of with long horizontal stroke", + symbol = "⋲" + }, + disjquant = { + doc = "two logical or operator", + symbol = "⨈" + }, + div = { + doc = "divide sign", + symbol = "÷" + }, + divideontimes = { + doc = "division on times", + symbol = "⋇" + }, + divslash = { + doc = "division slash", + symbol = "∕" + }, + dot = { + doc = "dot above", + symbol = "◌̇" + }, + doteq = { + doc = "equals, single dot above", + symbol = "≐" + }, + dotequiv = { + doc = "identical with dot above", + symbol = "⩧" + }, + dotminus = { + doc = "minus sign, dot above", + symbol = "∸" + }, + dotplus = { + doc = "plus sign, dot above", + symbol = "∔" + }, + dotsim = { + doc = "tilde operator with dot above", + symbol = "⩪" + }, + dotsminusdots = { + doc = "minus with four dots, geometric properties", + symbol = "∺" + }, + dottedcircle = { + doc = "dotted circle", + symbol = "◌" + }, + dottedsquare = { + doc = "dotted square", + symbol = "⬚" + }, + dottimes = { + doc = "multiplication sign with dot above", + symbol = "⨰" + }, + doublebarvee = { + doc = "logical or with double overbar", + symbol = "⩢" + }, + doublebarwedge = { + doc = "logical and with double overbar", + symbol = "⩞" + }, + doubleplus = { + doc = "double plus", + symbol = "⧺" + }, + downarrow = { + doc = "downward arrow", + symbol = "↓" + }, + downarrowbar = { + doc = "downwards arrow to bar", + symbol = "⤓" + }, + downarrowbarred = { + doc = "downwards arrow with horizontal stroke", + symbol = "⤈" + }, + downdasharrow = { + doc = "downwards dashed arrow", + symbol = "⇣" + }, + downdownarrows = { + doc = "two down arrows", + symbol = "⇊" + }, + downfishtail = { + doc = "down fish tail", + symbol = "⥿" + }, + downharpoonleft = { + doc = "down harpoon-left", + symbol = "⇃" + }, + downharpoonleftbar = { + doc = "downwards harpoon with barb left to bar", + symbol = "⥙" + }, + downharpoonright = { + doc = "down harpoon-right", + symbol = "⇂" + }, + downharpoonrightbar = { + doc = "downwards harpoon with barb right to bar", + symbol = "⥕" + }, + downharpoonsleftright = { + doc = "downwards harpoon with barb left beside downwards harpoon with barb right", + symbol = "⥥" + }, + downrightcurvedarrow = { + doc = "arrow pointing rightwards then curving downwards", + symbol = "⤵" + }, + downtriangleleftblack = { + doc = "down-pointing triangle with left half black", + symbol = "⧨" + }, + downtrianglerightblack = { + doc = "down-pointing triangle with right half black", + symbol = "⧩" + }, + downuparrows = { + doc = "downwards arrow leftwards of upwards arrow", + symbol = "⇵" + }, + downupharpoonsleftright = { + doc = "downwards harpoon with barb left beside upwards harpoon with barb right", + symbol = "⥯" + }, + downwhitearrow = { + doc = "downwards white arrow", + symbol = "⇩" + }, + downzigzagarrow = { + doc = "downwards zigzag arrow", + symbol = "↯" + }, + dprime = { + doc = "double prime or second, not superscripted", + symbol = "″" + }, + draftingarrow = { + doc = "right arrow with bold head (drafting)", + symbol = "➛" + }, + drbkarrow = { + doc = "rightwards two-headed triple dash arrow", + symbol = "⤐" + }, + droang = { + doc = "left angle above (non-spacing)", + symbol = "◌̚" + }, + dsol = { + doc = "solidus with overbar", + symbol = "⧶" + }, + dsub = { + doc = "z notation domain antirestriction", + symbol = "⩤" + }, + dualmap = { + doc = "double-ended multimap", + symbol = "⧟" + }, + egsdot = { + doc = "slanted equal to or greater-than with dot inside", + symbol = "⪘" + }, + eighthnote = { + doc = "eighth note", + symbol = "♪" + }, + elinters = { + doc = "electrical intersection", + symbol = "⏧" + }, + ell = { + doc = "cursive small l", + symbol = "ℓ" + }, + elsdot = { + doc = "slanted equal to or less-than with dot inside", + symbol = "⪗" + }, + emptysetoarr = { + doc = "empty set with right arrow above", + symbol = "⦳" + }, + emptysetoarrl = { + doc = "empty set with left arrow above", + symbol = "⦴" + }, + emptysetobar = { + doc = "empty set with overbar", + symbol = "⦱" + }, + emptysetocirc = { + doc = "empty set with small circle above", + symbol = "⦲" + }, + enclosecircle = { + doc = "combining enclosing circle", + symbol = "⃝" + }, + enclosediamond = { + doc = "combining enclosing diamond", + symbol = "⃟" + }, + enclosesquare = { + doc = "combining enclosing square", + symbol = "⃞" + }, + enclosetriangle = { + doc = "combining enclosing upward pointing triangle", + symbol = "⃤" + }, + enleadertwodots = { + doc = "double baseline dot (en leader)", + symbol = "‥" + }, + eparsl = { + doc = "equals sign and slanted parallel", + symbol = "⧣" + }, + epsilon = { + doc = "greek lunate varepsilon symbol", + symbol = "ϵ" + }, + eqcirc = { + doc = "circle on equals sign", + symbol = "≖" + }, + eqcolon = { + doc = "equals, colon", + symbol = "≕" + }, + eqdef = { + doc = "equals by definition", + symbol = "≝" + }, + eqdot = { + doc = "equals sign with dot below", + symbol = "⩦" + }, + eqeq = { + doc = "two consecutive equals signs", + symbol = "⩵" + }, + eqeqeq = { + doc = "three consecutive equals signs", + symbol = "⩶" + }, + eqgtr = { + doc = "equal-or-greater", + symbol = "⋝" + }, + eqless = { + doc = "equal-or-less", + symbol = "⋜" + }, + eqqgtr = { + doc = "double-line equal to or greater-than", + symbol = "⪚" + }, + eqqless = { + doc = "double-line equal to or less-than", + symbol = "⪙" + }, + eqqplus = { + doc = "equals sign above plus sign", + symbol = "⩱" + }, + eqqsim = { + doc = "equals sign above tilde operator", + symbol = "⩳" + }, + eqqslantgtr = { + doc = "double-line slanted equal to or greater-than", + symbol = "⪜" + }, + eqqslantless = { + doc = "double-line slanted equal to or less-than", + symbol = "⪛" + }, + eqsim = { + doc = "equals, similar", + symbol = "≂" + }, + eqslantgtr = { + doc = "slanted equal to or greater-than", + symbol = "⪖" + }, + eqslantless = { + doc = "slanted equal to or less-than", + symbol = "⪕" + }, + equal = { + doc = "equals sign r:", + symbol = "=" + }, + equalleftarrow = { + doc = "equals sign above leftwards arrow", + symbol = "⭀" + }, + equalparallel = { + doc = "parallel, equal; equal or parallel", + symbol = "⋕" + }, + equalrightarrow = { + doc = "equals sign above rightwards arrow", + symbol = "⥱" + }, + equiv = { + doc = "identical with", + symbol = "≡" + }, + equivDD = { + doc = "equivalent with four dots above", + symbol = "⩸" + }, + equivVert = { + doc = "triple horizontal bar with double vertical stroke", + symbol = "⩨" + }, + equivVvert = { + doc = "triple horizontal bar with triple vertical stroke", + symbol = "⩩" + }, + eqvparsl = { + doc = "identical to and slanted parallel", + symbol = "⧥" + }, + errbarblackcircle = { + doc = "error-barred black circle", + symbol = "⧳" + }, + errbarblackdiamond = { + doc = "error-barred black diamond", + symbol = "⧱" + }, + errbarblacksquare = { + doc = "error-barred black square", + symbol = "⧯" + }, + errbarcircle = { + doc = "error-barred white circle", + symbol = "⧲" + }, + errbardiamond = { + doc = "error-barred white diamond", + symbol = "⧰" + }, + errbarsquare = { + doc = "error-barred white square", + symbol = "⧮" + }, + eta = { + doc = "small eta, greek", + symbol = "η" + }, + euro = { + doc = "euro sign", + symbol = "€" + }, + exists = { + doc = "at least one exists", + symbol = "∃" + }, + fallingdotseq = { + doc = "equals, falling dots", + symbol = "≒" + }, + fbowtie = { + doc = "black bowtie", + symbol = "⧓" + }, + fcmp = { + doc = "z notation relational composition", + symbol = "⨾" + }, + fdiagovnearrow = { + doc = "falling diagonal crossing north east arrow", + symbol = "⤯" + }, + fdiagovrdiag = { + doc = "falling diagonal crossing rising diagonal", + symbol = "⤬" + }, + female = { + doc = "venus, female", + symbol = "♀" + }, + fint = { + doc = "integral average with slash", + symbol = "⨏" + }, + fisheye = { + doc = "fisheye", + symbol = "◉" + }, + flat = { + doc = "musical flat", + symbol = "♭" + }, + fltns = { + doc = "flatness", + symbol = "⏥" + }, + forall = { + doc = "for all", + symbol = "∀" + }, + forks = { + doc = "forking", + symbol = "⫝̸" + }, + forksnot = { + doc = "nonforking", + symbol = "⫝" + }, + forkv = { + doc = "element of opening downwards", + symbol = "⫙" + }, + fourthroot = { + doc = "fourth root", + symbol = "∜" + }, + fourvdots = { + doc = "dotted fence", + symbol = "⦙" + }, + fracslash = { + doc = "fraction slash", + symbol = "⁄" + }, + frown = { + doc = "down curve", + symbol = "⌢" + }, + fullouterjoin = { + doc = "full outer join", + symbol = "⟗" + }, + gamma = { + doc = "small gamma, greek", + symbol = "γ" + }, + geq = { + doc = "/geq /ge r: greater-than-or-equal", + symbol = "≥" + }, + geqq = { + doc = "greater, double equals", + symbol = "≧" + }, + geqqslant = { + doc = "double-line slanted greater-than or equal to", + symbol = "⫺" + }, + geqslant = { + doc = "greater-than or slanted equal to", + symbol = "⩾" + }, + gescc = { + doc = "greater-than closed by curve above slanted equal", + symbol = "⪩" + }, + gesdot = { + doc = "greater-than or slanted equal to with dot inside", + symbol = "⪀" + }, + gesdoto = { + doc = "greater-than or slanted equal to with dot above", + symbol = "⪂" + }, + gesdotol = { + doc = "greater-than or slanted equal to with dot above left", + symbol = "⪄" + }, + gesles = { + doc = "greater-than above slanted equal above less-than above slanted equal", + symbol = "⪔" + }, + gg = { + doc = "much greater than, type 2", + symbol = "≫" + }, + ggg = { + doc = "/ggg /gg /gggtr r: triple greater-than", + symbol = "⋙" + }, + gggnest = { + doc = "stacked very much greater-than", + symbol = "⫸" + }, + gimel = { + doc = "gimel, hebrew", + symbol = "ℷ" + }, + glE = { + doc = "greater-than above less-than above double-line equal", + symbol = "⪒" + }, + gla = { + doc = "greater-than beside less-than", + symbol = "⪥" + }, + gleichstark = { + doc = "gleich stark", + symbol = "⧦" + }, + glj = { + doc = "greater-than overlapping less-than", + symbol = "⪤" + }, + gnapprox = { + doc = "greater-than and not approximate", + symbol = "⪊" + }, + gneq = { + doc = "greater-than and single-line not equal to", + symbol = "⪈" + }, + gneqq = { + doc = "greater, not double equals", + symbol = "≩" + }, + gnsim = { + doc = "greater, not similar", + symbol = "⋧" + }, + grave = { + doc = "grave accent", + symbol = "◌̀" + }, + greater = { + doc = "greater-than sign r:", + symbol = ">" + }, + gsime = { + doc = "greater-than above similar or equal", + symbol = "⪎" + }, + gsiml = { + doc = "greater-than above similar above less-than", + symbol = "⪐" + }, + gtcc = { + doc = "greater-than closed by curve", + symbol = "⪧" + }, + gtcir = { + doc = "greater-than with circle inside", + symbol = "⩺" + }, + gtlpar = { + doc = "spherical angle opening left", + symbol = "⦠" + }, + gtquest = { + doc = "greater-than with question mark above", + symbol = "⩼" + }, + gtrapprox = { + doc = "greater-than or approximate", + symbol = "⪆" + }, + gtrarr = { + doc = "greater-than above rightwards arrow", + symbol = "⥸" + }, + gtrdot = { + doc = "greater than, with dot", + symbol = "⋗" + }, + gtreqless = { + doc = "greater, equals, less", + symbol = "⋛" + }, + gtreqqless = { + doc = "greater-than above double-line equal above less-than", + symbol = "⪌" + }, + gtrless = { + doc = "greater, less", + symbol = "≷" + }, + gtrsim = { + doc = "greater, similar", + symbol = "≳" + }, + harrowextender = { + doc = "horizontal line extension (used to extend arrows)", + symbol = "⎯" + }, + hat = { + doc = "circumflex accent", + symbol = "◌̂" + }, + hatapprox = { + doc = "almost equal to with circumflex accent", + symbol = "⩯" + }, + heartsuit = { + doc = "heart suit symbol", + symbol = "♡" + }, + hermitmatrix = { + doc = "hermitian conjugate matrix", + symbol = "⊹" + }, + hexagon = { + doc = "horizontal benzene ring [hexagon flat open]", + symbol = "⎔" + }, + hexagonblack = { + doc = "horizontal black hexagon", + symbol = "⬣" + }, + hknearrow = { + doc = "north east arrow with hook", + symbol = "⤤" + }, + hknwarrow = { + doc = "north west arrow with hook", + symbol = "⤣" + }, + hksearrow = { + doc = "south east arrow with hook", + symbol = "⤥" + }, + hkswarrow = { + doc = "south west arrow with hook", + symbol = "⤦" + }, + hookleftarrow = { + doc = "left arrow-hooked", + symbol = "↩" + }, + hookrightarrow = { + doc = "right arrow-hooked", + symbol = "↪" + }, + horizbar = { + doc = "horizontal bar", + symbol = "―" + }, + hourglass = { + doc = "white hourglass", + symbol = "⧖" + }, + house = { + doc = "house", + symbol = "⌂" + }, + hrectangle = { + doc = "horizontal rectangle, open", + symbol = "▭" + }, + hrectangleblack = { + doc = "black rectangle", + symbol = "▬" + }, + hslash = { + doc = "/hslash - variant planck's over 2pi", + symbol = "ℏ" + }, + hyphenbullet = { + doc = "rectangle, filled (hyphen bullet)", + symbol = "⁃" + }, + hzigzag = { + doc = "zigzag", + symbol = "〰" + }, + iiiint = { + doc = "quadruple integral operator", + symbol = "⨌" + }, + iiint = { + doc = "triple integral operator", + symbol = "∭" + }, + iinfin = { + doc = "incomplete infinity", + symbol = "⧜" + }, + iint = { + doc = "double integral operator", + symbol = "∬" + }, + imageof = { + doc = "image of", + symbol = "⊷" + }, + imath = { + doc = "mathematical italic small dotless i", + symbol = "𝚤" + }, + ["in"] = { + doc = "set membership, variant", + symbol = "∈" + }, + increment = { + doc = "laplacian (delta; nabla\\string^2)", + symbol = "∆" + }, + infty = { + doc = "infinity", + symbol = "∞" + }, + int = { + doc = "integral operator", + symbol = "∫" + }, + intBar = { + doc = "integral with double stroke", + symbol = "⨎" + }, + intbar = { + doc = "finite part integral", + symbol = "⨍" + }, + intbottom = { + doc = "bottom half integral", + symbol = "⌡" + }, + intcap = { + doc = "integral with intersection", + symbol = "⨙" + }, + intclockwise = { + doc = "clockwise integral", + symbol = "∱" + }, + intcup = { + doc = "integral with union", + symbol = "⨚" + }, + intercal = { + doc = "intercal", + symbol = "⊺" + }, + interleave = { + doc = "triple vertical bar binary relation", + symbol = "⫴" + }, + intextender = { + doc = "integral extension", + symbol = "⎮" + }, + intlarhk = { + doc = "integral with leftwards arrow with hook", + symbol = "⨗" + }, + intprod = { + doc = "interior product", + symbol = "⨼" + }, + intprodr = { + doc = "righthand interior product", + symbol = "⨽" + }, + inttop = { + doc = "top half integral", + symbol = "⌠" + }, + intx = { + doc = "integral with times sign", + symbol = "⨘" + }, + inversebullet = { + doc = "inverse bullet", + symbol = "◘" + }, + inversewhitecircle = { + doc = "inverse white circle", + symbol = "◙" + }, + invlazys = { + doc = "most positive [inverted lazy s]", + symbol = "∾" + }, + invnot = { + doc = "reverse not", + symbol = "⌐" + }, + invwhitelowerhalfcircle = { + doc = "lower half inverse white circle", + symbol = "◛" + }, + invwhiteupperhalfcircle = { + doc = "upper half inverse white circle", + symbol = "◚" + }, + iota = { + doc = "small iota, greek", + symbol = "ι" + }, + isinE = { + doc = "element of with two horizontal strokes", + symbol = "⋹" + }, + isindot = { + doc = "element of with dot above", + symbol = "⋵" + }, + isinobar = { + doc = "small element of with overbar", + symbol = "⋷" + }, + isins = { + doc = "small element of with vertical bar at end of horizontal stroke", + symbol = "⋴" + }, + isinvb = { + doc = "element of with underbar", + symbol = "⋸" + }, + jmath = { + doc = "mathematical italic small dotless j", + symbol = "𝚥" + }, + kappa = { + doc = "small kappa, greek", + symbol = "κ" + }, + kernelcontraction = { + doc = "homothetic", + symbol = "∻" + }, + lAngle = { + doc = "mathematical left double angle bracket", + symbol = "⟪" + }, + lBrace = { + doc = "left white curly bracket", + symbol = "⦃" + }, + lBrack = { + doc = "mathematical left white square bracket", + symbol = "⟦" + }, + lParen = { + doc = "left white parenthesis", + symbol = "⦅" + }, + lambda = { + doc = "small lambda, greek", + symbol = "λ" + }, + langle = { + doc = "mathematical left angle bracket", + symbol = "⟨" + }, + langledot = { + doc = "left angle bracket with dot", + symbol = "⦑" + }, + laplac = { + doc = "square with contoured outline", + symbol = "⧠" + }, + lat = { + doc = "larger than", + symbol = "⪫" + }, + late = { + doc = "larger than or equal to", + symbol = "⪭" + }, + lbag = { + doc = "left s-shaped bag delimiter", + symbol = "⟅" + }, + lblkbrbrak = { + doc = "left black tortoise shell bracket", + symbol = "⦗" + }, + lbrace = { + doc = "left curly bracket", + symbol = "{" + }, + lbracelend = { + doc = "left curly bracket lower hook", + symbol = "⎩" + }, + lbracemid = { + doc = "left curly bracket middle piece", + symbol = "⎨" + }, + lbraceuend = { + doc = "left curly bracket upper hook", + symbol = "⎧" + }, + lbrack = { + doc = "left square bracket", + symbol = "[" + }, + lbrackextender = { + doc = "left square bracket extension", + symbol = "⎢" + }, + lbracklend = { + doc = "left square bracket lower corner", + symbol = "⎣" + }, + lbracklltick = { + doc = "left square bracket with tick in bottom corner", + symbol = "⦏" + }, + lbrackubar = { + doc = "left square bracket with underbar", + symbol = "⦋" + }, + lbrackuend = { + doc = "left square bracket upper corner", + symbol = "⎡" + }, + lbrackultick = { + doc = "left square bracket with tick in top corner", + symbol = "⦍" + }, + lbrbrak = { + doc = "light left tortoise shell bracket ornament", + symbol = "❲" + }, + lceil = { + doc = "left ceiling", + symbol = "⌈" + }, + lcurvyangle = { + doc = "left pointing curved angle bracket", + symbol = "⧼" + }, + leftarrow = { + doc = "/leftarrow /gets a: leftward arrow", + symbol = "←" + }, + leftarrowapprox = { + doc = "leftwards arrow above almost equal to", + symbol = "⭊" + }, + leftarrowbackapprox = { + doc = "leftwards arrow above reverse almost equal to", + symbol = "⭂" + }, + leftarrowbsimilar = { + doc = "leftwards arrow above reverse tilde operator", + symbol = "⭋" + }, + leftarrowless = { + doc = "leftwards arrow through less-than", + symbol = "⥷" + }, + leftarrowonoplus = { + doc = "left arrow with circled plus", + symbol = "⬲" + }, + leftarrowplus = { + doc = "leftwards arrow with plus below", + symbol = "⥆" + }, + leftarrowshortrightarrow = { + doc = "leftwards arrow above short rightwards arrow", + symbol = "⥃" + }, + leftarrowsimilar = { + doc = "leftwards arrow above tilde operator", + symbol = "⥳" + }, + leftarrowsubset = { + doc = "leftwards arrow through subset", + symbol = "⥺" + }, + leftarrowtail = { + doc = "left arrow-tailed", + symbol = "↢" + }, + leftarrowtriangle = { + doc = "leftwards open-headed arrow", + symbol = "⇽" + }, + leftarrowx = { + doc = "leftwards arrow through x", + symbol = "⬾" + }, + leftbkarrow = { + doc = "leftwards double dash arrow", + symbol = "⤌" + }, + leftcurvedarrow = { + doc = "wave arrow pointing directly left", + symbol = "⬿" + }, + leftdasharrow = { + doc = "leftwards dashed arrow", + symbol = "⇠" + }, + leftdbkarrow = { + doc = "leftwards triple dash arrow", + symbol = "⤎" + }, + leftdbltail = { + doc = "leftwards double arrow-tail", + symbol = "⤛" + }, + leftdotarrow = { + doc = "leftwards arrow with dotted stem", + symbol = "⬸" + }, + leftdowncurvedarrow = { + doc = "arrow pointing downwards then curving leftwards", + symbol = "⤶" + }, + leftfishtail = { + doc = "left fish tail", + symbol = "⥼" + }, + leftharpoonaccent = { + doc = "combining left harpoon above", + symbol = "◌⃐" + }, + leftharpoondown = { + doc = "left harpoon-down", + symbol = "↽" + }, + leftharpoondownbar = { + doc = "leftwards harpoon with barb down from bar", + symbol = "⥞" + }, + leftharpoonsupdown = { + doc = "leftwards harpoon with barb up above leftwards harpoon with barb down", + symbol = "⥢" + }, + leftharpoonup = { + doc = "left harpoon-up", + symbol = "↼" + }, + leftharpoonupbar = { + doc = "leftwards harpoon with barb up from bar", + symbol = "⥚" + }, + leftharpoonupdash = { + doc = "leftwards harpoon with barb up above long dash", + symbol = "⥪" + }, + leftleftarrows = { + doc = "two left arrows", + symbol = "⇇" + }, + leftmoon = { + doc = "last quarter moon", + symbol = "☾" + }, + leftouterjoin = { + doc = "left outer join", + symbol = "⟕" + }, + leftrightarrow = { + doc = "left and right arrow", + symbol = "↔" + }, + leftrightarrowcircle = { + doc = "left right arrow through small circle", + symbol = "⥈" + }, + leftrightarrows = { + doc = "left arrow over right arrow", + symbol = "⇆" + }, + leftrightarrowtriangle = { + doc = "left right open-headed arrow", + symbol = "⇿" + }, + leftrightharpoondowndown = { + doc = "left barb down right barb down harpoon", + symbol = "⥐" + }, + leftrightharpoondownup = { + doc = "left barb down right barb up harpoon", + symbol = "⥋" + }, + leftrightharpoons = { + doc = "left harpoon over right", + symbol = "⇋" + }, + leftrightharpoonsdown = { + doc = "leftwards harpoon with barb down above rightwards harpoon with barb down", + symbol = "⥧" + }, + leftrightharpoonsup = { + doc = "leftwards harpoon with barb up above rightwards harpoon with barb up", + symbol = "⥦" + }, + leftrightharpoonupdown = { + doc = "left barb up right barb down harpoon", + symbol = "⥊" + }, + leftrightharpoonupup = { + doc = "left barb up right barb up harpoon", + symbol = "⥎" + }, + leftrightsquigarrow = { + doc = "left and right arr-wavy", + symbol = "↭" + }, + leftsquigarrow = { + doc = "leftwards squiggle arrow", + symbol = "⇜" + }, + lefttail = { + doc = "leftwards arrow-tail", + symbol = "⤙" + }, + leftthreearrows = { + doc = "three leftwards arrows", + symbol = "⬱" + }, + leftthreetimes = { + doc = "left semidirect product", + symbol = "⋋" + }, + leftwavearrow = { + doc = "left arrow-wavy", + symbol = "↜" + }, + leftwhitearrow = { + doc = "leftwards white arrow", + symbol = "⇦" + }, + leq = { + doc = "/leq /le r: less-than-or-equal", + symbol = "≤" + }, + leqq = { + doc = "less, double equals", + symbol = "≦" + }, + leqqslant = { + doc = "double-line slanted less-than or equal to", + symbol = "⫹" + }, + leqslant = { + doc = "less-than or slanted equal to", + symbol = "⩽" + }, + lescc = { + doc = "less-than closed by curve above slanted equal", + symbol = "⪨" + }, + lesdot = { + doc = "less-than or slanted equal to with dot inside", + symbol = "⩿" + }, + lesdoto = { + doc = "less-than or slanted equal to with dot above", + symbol = "⪁" + }, + lesdotor = { + doc = "less-than or slanted equal to with dot above right", + symbol = "⪃" + }, + lesges = { + doc = "less-than above slanted equal above greater-than above slanted equal", + symbol = "⪓" + }, + less = { + doc = "less-than sign r:", + symbol = "<" + }, + lessapprox = { + doc = "less-than or approximate", + symbol = "⪅" + }, + lessdot = { + doc = "less than, with dot", + symbol = "⋖" + }, + lesseqgtr = { + doc = "less, equals, greater", + symbol = "⋚" + }, + lesseqqgtr = { + doc = "less-than above double-line equal above greater-than", + symbol = "⪋" + }, + lessgtr = { + doc = "less, greater", + symbol = "≶" + }, + lesssim = { + doc = "less, similar", + symbol = "≲" + }, + lfbowtie = { + doc = "left black bowtie", + symbol = "⧑" + }, + lfloor = { + doc = "left floor", + symbol = "⌊" + }, + lftimes = { + doc = "left black times", + symbol = "⧔" + }, + lgE = { + doc = "less-than above greater-than above double-line equal", + symbol = "⪑" + }, + lgblkcircle = { + doc = "black large circle", + symbol = "⬤" + }, + lgblksquare = { + doc = "black large square", + symbol = "⬛" + }, + lgroup = { + doc = "mathematical left flattened parenthesis", + symbol = "⟮" + }, + lgwhtcircle = { + doc = "large circle", + symbol = "◯" + }, + lgwhtsquare = { + doc = "white large square", + symbol = "⬜" + }, + linefeed = { + doc = "rightwards arrow with corner downwards", + symbol = "↴" + }, + ll = { + doc = "much less than, type 2", + symbol = "≪" + }, + llangle = { + doc = "z notation left binding bracket", + symbol = "⦉" + }, + llarc = { + doc = "lower left quadrant circular arc", + symbol = "◟" + }, + llblacktriangle = { + doc = "lower left triangle, filled", + symbol = "◣" + }, + llcorner = { + doc = "lower left corner", + symbol = "⌞" + }, + lll = { + doc = "/ll /lll /llless r: triple less-than", + symbol = "⋘" + }, + lllnest = { + doc = "stacked very much less-than", + symbol = "⫷" + }, + llparenthesis = { + doc = "z notation left image bracket", + symbol = "⦇" + }, + lltriangle = { + doc = "lower left triangle", + symbol = "◺" + }, + lmoustache = { + doc = "upper left or lower right curly bracket section", + symbol = "⎰" + }, + lnapprox = { + doc = "less-than and not approximate", + symbol = "⪉" + }, + lneq = { + doc = "less-than and single-line not equal to", + symbol = "⪇" + }, + lneqq = { + doc = "less, not double equals", + symbol = "≨" + }, + lnsim = { + doc = "less, not similar", + symbol = "⋦" + }, + longdashv = { + doc = "long right tack", + symbol = "⟞" + }, + longdivision = { + doc = "long division", + symbol = "⟌" + }, + longleftarrow = { + doc = "long leftwards arrow", + symbol = "⟵" + }, + longleftrightarrow = { + doc = "long left right arrow", + symbol = "⟷" + }, + longleftsquigarrow = { + doc = "long leftwards squiggle arrow", + symbol = "⬳" + }, + longmapsfrom = { + doc = "long leftwards arrow from bar", + symbol = "⟻" + }, + longmapsto = { + doc = "long rightwards arrow from bar", + symbol = "⟼" + }, + longrightarrow = { + doc = "long rightwards arrow", + symbol = "⟶" + }, + longrightsquigarrow = { + doc = "long rightwards squiggle arrow", + symbol = "⟿" + }, + looparrowleft = { + doc = "left arrow-looped", + symbol = "↫" + }, + looparrowright = { + doc = "right arrow-looped", + symbol = "↬" + }, + lowint = { + doc = "integral with underbar", + symbol = "⨜" + }, + lozengeminus = { + doc = "lozenge divided by horizontal rule", + symbol = "⟠" + }, + lparen = { + doc = "left parenthesis", + symbol = "(" + }, + lparenextender = { + doc = "left parenthesis extension", + symbol = "⎜" + }, + lparenlend = { + doc = "left parenthesis lower hook", + symbol = "⎝" + }, + lparenless = { + doc = "left arc less-than bracket", + symbol = "⦓" + }, + lparenuend = { + doc = "left parenthesis upper hook", + symbol = "⎛" + }, + lrarc = { + doc = "lower right quadrant circular arc", + symbol = "◞" + }, + lrblacktriangle = { + doc = "lower right triangle, filled", + symbol = "◢" + }, + lrcorner = { + doc = "lower right corner", + symbol = "⌟" + }, + lrtriangle = { + doc = "lower right triangle", + symbol = "◿" + }, + lrtriangleeq = { + doc = "increases as", + symbol = "⧡" + }, + lsime = { + doc = "less-than above similar or equal", + symbol = "⪍" + }, + lsimg = { + doc = "less-than above similar above greater-than", + symbol = "⪏" + }, + lsqhook = { + doc = "square left open box operator", + symbol = "⫍" + }, + ltcc = { + doc = "less-than closed by curve", + symbol = "⪦" + }, + ltcir = { + doc = "less-than with circle inside", + symbol = "⩹" + }, + ltimes = { + doc = "times sign, left closed", + symbol = "⋉" + }, + ltlarr = { + doc = "less-than above leftwards arrow", + symbol = "⥶" + }, + ltquest = { + doc = "less-than with question mark above", + symbol = "⩻" + }, + ltrivb = { + doc = "left triangle beside vertical bar", + symbol = "⧏" + }, + lvboxline = { + doc = "left vertical box line", + symbol = "⎸" + }, + lvzigzag = { + doc = "left wiggly fence", + symbol = "⧘" + }, + male = { + doc = "mars, male", + symbol = "♂" + }, + maltese = { + doc = "maltese cross", + symbol = "✠" + }, + mapsdown = { + doc = "maps to, downward", + symbol = "↧" + }, + mapsfrom = { + doc = "maps to, leftward", + symbol = "↤" + }, + mapsto = { + doc = "maps to, rightward", + symbol = "↦" + }, + mapsup = { + doc = "maps to, upward", + symbol = "↥" + }, + mathampersand = { + doc = "ampersand", + symbol = "&" + }, + mathatsign = { + doc = "commercial at", + symbol = "@" + }, + mathcolon = { + doc = "colon", + symbol = ":" + }, + mathcomma = { + doc = "comma", + symbol = "," + }, + mathdollar = { + doc = "dollar sign", + symbol = "$" + }, + matheth = { + doc = "eth", + symbol = "ð" + }, + mathexclam = { + doc = "exclamation mark", + symbol = "!" + }, + mathhyphen = { + doc = "hyphen", + symbol = "‐" + }, + mathoctothorpe = { + doc = "number sign", + symbol = "#" + }, + mathparagraph = { + doc = "paragraph symbol", + symbol = "¶" + }, + mathpercent = { + doc = "percent sign", + symbol = "%" + }, + mathperiod = { + doc = "full stop, period", + symbol = "." + }, + mathplus = { + doc = "plus sign b:", + symbol = "+" + }, + mathquestion = { + doc = "question mark", + symbol = "?" + }, + mathratio = { + doc = "ratio", + symbol = "∶" + }, + mathsection = { + doc = "section symbol", + symbol = "§" + }, + mathsemicolon = { + doc = "semicolon p:", + symbol = ";" + }, + mathslash = { + doc = "solidus", + symbol = "/" + }, + mathsterling = { + doc = "pound sign", + symbol = "£" + }, + mathunderbar = { + doc = "combining low line", + symbol = "◌̲" + }, + mathvisiblespace = { + doc = "open box", + symbol = "␣" + }, + mathyen = { + doc = "yen sign", + symbol = "¥" + }, + mbfA = { + doc = "mathematical bold capital a", + symbol = "𝐀" + }, + mbfAlpha = { + doc = "mathematical bold capital alpha", + symbol = "𝚨" + }, + mbfB = { + doc = "mathematical bold capital b", + symbol = "𝐁" + }, + mbfBeta = { + doc = "mathematical bold capital beta", + symbol = "𝚩" + }, + mbfC = { + doc = "mathematical bold capital c", + symbol = "𝐂" + }, + mbfChi = { + doc = "mathematical bold capital chi", + symbol = "𝚾" + }, + mbfD = { + doc = "mathematical bold capital d", + symbol = "𝐃" + }, + mbfDelta = { + doc = "mathematical bold capital delta", + symbol = "𝚫" + }, + mbfDigamma = { + doc = "mathematical bold capital digamma", + symbol = "𝟊" + }, + mbfE = { + doc = "mathematical bold capital e", + symbol = "𝐄" + }, + mbfEpsilon = { + doc = "mathematical bold capital epsilon", + symbol = "𝚬" + }, + mbfEta = { + doc = "mathematical bold capital eta", + symbol = "𝚮" + }, + mbfF = { + doc = "mathematical bold capital f", + symbol = "𝐅" + }, + mbfG = { + doc = "mathematical bold capital g", + symbol = "𝐆" + }, + mbfGamma = { + doc = "mathematical bold capital gamma", + symbol = "𝚪" + }, + mbfH = { + doc = "mathematical bold capital h", + symbol = "𝐇" + }, + mbfI = { + doc = "mathematical bold capital i", + symbol = "𝐈" + }, + mbfIota = { + doc = "mathematical bold capital iota", + symbol = "𝚰" + }, + mbfJ = { + doc = "mathematical bold capital j", + symbol = "𝐉" + }, + mbfK = { + doc = "mathematical bold capital k", + symbol = "𝐊" + }, + mbfKappa = { + doc = "mathematical bold capital kappa", + symbol = "𝚱" + }, + mbfL = { + doc = "mathematical bold capital l", + symbol = "𝐋" + }, + mbfLambda = { + doc = "mathematical bold capital lambda", + symbol = "𝚲" + }, + mbfM = { + doc = "mathematical bold capital m", + symbol = "𝐌" + }, + mbfMu = { + doc = "mathematical bold capital mu", + symbol = "𝚳" + }, + mbfN = { + doc = "mathematical bold capital n", + symbol = "𝐍" + }, + mbfNu = { + doc = "mathematical bold capital nu", + symbol = "𝚴" + }, + mbfO = { + doc = "mathematical bold capital o", + symbol = "𝐎" + }, + mbfOmega = { + doc = "mathematical bold capital omega", + symbol = "𝛀" + }, + mbfOmicron = { + doc = "mathematical bold capital omicron", + symbol = "𝚶" + }, + mbfP = { + doc = "mathematical bold capital p", + symbol = "𝐏" + }, + mbfPhi = { + doc = "mathematical bold capital phi", + symbol = "𝚽" + }, + mbfPi = { + doc = "mathematical bold capital pi", + symbol = "𝚷" + }, + mbfPsi = { + doc = "mathematical bold capital psi", + symbol = "𝚿" + }, + mbfQ = { + doc = "mathematical bold capital q", + symbol = "𝐐" + }, + mbfR = { + doc = "mathematical bold capital r", + symbol = "𝐑" + }, + mbfRho = { + doc = "mathematical bold capital rho", + symbol = "𝚸" + }, + mbfS = { + doc = "mathematical bold capital s", + symbol = "𝐒" + }, + mbfSigma = { + doc = "mathematical bold capital sigma", + symbol = "𝚺" + }, + mbfT = { + doc = "mathematical bold capital t", + symbol = "𝐓" + }, + mbfTau = { + doc = "mathematical bold capital tau", + symbol = "𝚻" + }, + mbfTheta = { + doc = "mathematical bold capital theta", + symbol = "𝚯" + }, + mbfU = { + doc = "mathematical bold capital u", + symbol = "𝐔" + }, + mbfUpsilon = { + doc = "mathematical bold capital upsilon", + symbol = "𝚼" + }, + mbfV = { + doc = "mathematical bold capital v", + symbol = "𝐕" + }, + mbfW = { + doc = "mathematical bold capital w", + symbol = "𝐖" + }, + mbfX = { + doc = "mathematical bold capital x", + symbol = "𝐗" + }, + mbfXi = { + doc = "mathematical bold capital xi", + symbol = "𝚵" + }, + mbfY = { + doc = "mathematical bold capital y", + symbol = "𝐘" + }, + mbfZ = { + doc = "mathematical bold capital z", + symbol = "𝐙" + }, + mbfZeta = { + doc = "mathematical bold capital zeta", + symbol = "𝚭" + }, + mbfa = { + doc = "mathematical bold small a", + symbol = "𝐚" + }, + mbfalpha = { + doc = "mathematical bold small alpha", + symbol = "𝛂" + }, + mbfb = { + doc = "mathematical bold small b", + symbol = "𝐛" + }, + mbfbeta = { + doc = "mathematical bold small beta", + symbol = "𝛃" + }, + mbfc = { + doc = "mathematical bold small c", + symbol = "𝐜" + }, + mbfchi = { + doc = "mathematical bold small chi", + symbol = "𝛘" + }, + mbfd = { + doc = "mathematical bold small d", + symbol = "𝐝" + }, + mbfdelta = { + doc = "mathematical bold small delta", + symbol = "𝛅" + }, + mbfdigamma = { + doc = "mathematical bold small digamma", + symbol = "𝟋" + }, + mbfe = { + doc = "mathematical bold small e", + symbol = "𝐞" + }, + mbfeight = { + doc = "mathematical bold digit 8", + symbol = "𝟖" + }, + mbfepsilon = { + doc = "mathematical bold varepsilon symbol", + symbol = "𝛜" + }, + mbfeta = { + doc = "mathematical bold small eta", + symbol = "𝛈" + }, + mbff = { + doc = "mathematical bold small f", + symbol = "𝐟" + }, + mbffive = { + doc = "mathematical bold digit 5", + symbol = "𝟓" + }, + mbffour = { + doc = "mathematical bold digit 4", + symbol = "𝟒" + }, + mbffrakA = { + doc = "mathematical bold fraktur capital a", + symbol = "𝕬" + }, + mbffrakB = { + doc = "mathematical bold fraktur capital b", + symbol = "𝕭" + }, + mbffrakC = { + doc = "mathematical bold fraktur capital c", + symbol = "𝕮" + }, + mbffrakD = { + doc = "mathematical bold fraktur capital d", + symbol = "𝕯" + }, + mbffrakE = { + doc = "mathematical bold fraktur capital e", + symbol = "𝕰" + }, + mbffrakF = { + doc = "mathematical bold fraktur capital f", + symbol = "𝕱" + }, + mbffrakG = { + doc = "mathematical bold fraktur capital g", + symbol = "𝕲" + }, + mbffrakH = { + doc = "mathematical bold fraktur capital h", + symbol = "𝕳" + }, + mbffrakI = { + doc = "mathematical bold fraktur capital i", + symbol = "𝕴" + }, + mbffrakJ = { + doc = "mathematical bold fraktur capital j", + symbol = "𝕵" + }, + mbffrakK = { + doc = "mathematical bold fraktur capital k", + symbol = "𝕶" + }, + mbffrakL = { + doc = "mathematical bold fraktur capital l", + symbol = "𝕷" + }, + mbffrakM = { + doc = "mathematical bold fraktur capital m", + symbol = "𝕸" + }, + mbffrakN = { + doc = "mathematical bold fraktur capital n", + symbol = "𝕹" + }, + mbffrakO = { + doc = "mathematical bold fraktur capital o", + symbol = "𝕺" + }, + mbffrakP = { + doc = "mathematical bold fraktur capital p", + symbol = "𝕻" + }, + mbffrakQ = { + doc = "mathematical bold fraktur capital q", + symbol = "𝕼" + }, + mbffrakR = { + doc = "mathematical bold fraktur capital r", + symbol = "𝕽" + }, + mbffrakS = { + doc = "mathematical bold fraktur capital s", + symbol = "𝕾" + }, + mbffrakT = { + doc = "mathematical bold fraktur capital t", + symbol = "𝕿" + }, + mbffrakU = { + doc = "mathematical bold fraktur capital u", + symbol = "𝖀" + }, + mbffrakV = { + doc = "mathematical bold fraktur capital v", + symbol = "𝖁" + }, + mbffrakW = { + doc = "mathematical bold fraktur capital w", + symbol = "𝖂" + }, + mbffrakX = { + doc = "mathematical bold fraktur capital x", + symbol = "𝖃" + }, + mbffrakY = { + doc = "mathematical bold fraktur capital y", + symbol = "𝖄" + }, + mbffrakZ = { + doc = "mathematical bold fraktur capital z", + symbol = "𝖅" + }, + mbffraka = { + doc = "mathematical bold fraktur small a", + symbol = "𝖆" + }, + mbffrakb = { + doc = "mathematical bold fraktur small b", + symbol = "𝖇" + }, + mbffrakc = { + doc = "mathematical bold fraktur small c", + symbol = "𝖈" + }, + mbffrakd = { + doc = "mathematical bold fraktur small d", + symbol = "𝖉" + }, + mbffrake = { + doc = "mathematical bold fraktur small e", + symbol = "𝖊" + }, + mbffrakf = { + doc = "mathematical bold fraktur small f", + symbol = "𝖋" + }, + mbffrakg = { + doc = "mathematical bold fraktur small g", + symbol = "𝖌" + }, + mbffrakh = { + doc = "mathematical bold fraktur small h", + symbol = "𝖍" + }, + mbffraki = { + doc = "mathematical bold fraktur small i", + symbol = "𝖎" + }, + mbffrakj = { + doc = "mathematical bold fraktur small j", + symbol = "𝖏" + }, + mbffrakk = { + doc = "mathematical bold fraktur small k", + symbol = "𝖐" + }, + mbffrakl = { + doc = "mathematical bold fraktur small l", + symbol = "𝖑" + }, + mbffrakm = { + doc = "mathematical bold fraktur small m", + symbol = "𝖒" + }, + mbffrakn = { + doc = "mathematical bold fraktur small n", + symbol = "𝖓" + }, + mbffrako = { + doc = "mathematical bold fraktur small o", + symbol = "𝖔" + }, + mbffrakp = { + doc = "mathematical bold fraktur small p", + symbol = "𝖕" + }, + mbffrakq = { + doc = "mathematical bold fraktur small q", + symbol = "𝖖" + }, + mbffrakr = { + doc = "mathematical bold fraktur small r", + symbol = "𝖗" + }, + mbffraks = { + doc = "mathematical bold fraktur small s", + symbol = "𝖘" + }, + mbffrakt = { + doc = "mathematical bold fraktur small t", + symbol = "𝖙" + }, + mbffraku = { + doc = "mathematical bold fraktur small u", + symbol = "𝖚" + }, + mbffrakv = { + doc = "mathematical bold fraktur small v", + symbol = "𝖛" + }, + mbffrakw = { + doc = "mathematical bold fraktur small w", + symbol = "𝖜" + }, + mbffrakx = { + doc = "mathematical bold fraktur small x", + symbol = "𝖝" + }, + mbffraky = { + doc = "mathematical bold fraktur small y", + symbol = "𝖞" + }, + mbffrakz = { + doc = "mathematical bold fraktur small z", + symbol = "𝖟" + }, + mbfg = { + doc = "mathematical bold small g", + symbol = "𝐠" + }, + mbfgamma = { + doc = "mathematical bold small gamma", + symbol = "𝛄" + }, + mbfh = { + doc = "mathematical bold small h", + symbol = "𝐡" + }, + mbfi = { + doc = "mathematical bold small i", + symbol = "𝐢" + }, + mbfiota = { + doc = "mathematical bold small iota", + symbol = "𝛊" + }, + mbfitA = { + doc = "mathematical bold italic capital a", + symbol = "𝑨" + }, + mbfitAlpha = { + doc = "mathematical bold italic capital alpha", + symbol = "𝜜" + }, + mbfitB = { + doc = "mathematical bold italic capital b", + symbol = "𝑩" + }, + mbfitBeta = { + doc = "mathematical bold italic capital beta", + symbol = "𝜝" + }, + mbfitC = { + doc = "mathematical bold italic capital c", + symbol = "𝑪" + }, + mbfitChi = { + doc = "mathematical bold italic capital chi", + symbol = "𝜲" + }, + mbfitD = { + doc = "mathematical bold italic capital d", + symbol = "𝑫" + }, + mbfitDelta = { + doc = "mathematical bold italic capital delta", + symbol = "𝜟" + }, + mbfitE = { + doc = "mathematical bold italic capital e", + symbol = "𝑬" + }, + mbfitEpsilon = { + doc = "mathematical bold italic capital epsilon", + symbol = "𝜠" + }, + mbfitEta = { + doc = "mathematical bold italic capital eta", + symbol = "𝜢" + }, + mbfitF = { + doc = "mathematical bold italic capital f", + symbol = "𝑭" + }, + mbfitG = { + doc = "mathematical bold italic capital g", + symbol = "𝑮" + }, + mbfitGamma = { + doc = "mathematical bold italic capital gamma", + symbol = "𝜞" + }, + mbfitH = { + doc = "mathematical bold italic capital h", + symbol = "𝑯" + }, + mbfitI = { + doc = "mathematical bold italic capital i", + symbol = "𝑰" + }, + mbfitIota = { + doc = "mathematical bold italic capital iota", + symbol = "𝜤" + }, + mbfitJ = { + doc = "mathematical bold italic capital j", + symbol = "𝑱" + }, + mbfitK = { + doc = "mathematical bold italic capital k", + symbol = "𝑲" + }, + mbfitKappa = { + doc = "mathematical bold italic capital kappa", + symbol = "𝜥" + }, + mbfitL = { + doc = "mathematical bold italic capital l", + symbol = "𝑳" + }, + mbfitLambda = { + doc = "mathematical bold italic capital lambda", + symbol = "𝜦" + }, + mbfitM = { + doc = "mathematical bold italic capital m", + symbol = "𝑴" + }, + mbfitMu = { + doc = "mathematical bold italic capital mu", + symbol = "𝜧" + }, + mbfitN = { + doc = "mathematical bold italic capital n", + symbol = "𝑵" + }, + mbfitNu = { + doc = "mathematical bold italic capital nu", + symbol = "𝜨" + }, + mbfitO = { + doc = "mathematical bold italic capital o", + symbol = "𝑶" + }, + mbfitOmega = { + doc = "mathematical bold italic capital omega", + symbol = "𝜴" + }, + mbfitOmicron = { + doc = "mathematical bold italic capital omicron", + symbol = "𝜪" + }, + mbfitP = { + doc = "mathematical bold italic capital p", + symbol = "𝑷" + }, + mbfitPhi = { + doc = "mathematical bold italic capital phi", + symbol = "𝜱" + }, + mbfitPi = { + doc = "mathematical bold italic capital pi", + symbol = "𝜫" + }, + mbfitPsi = { + doc = "mathematical bold italic capital psi", + symbol = "𝜳" + }, + mbfitQ = { + doc = "mathematical bold italic capital q", + symbol = "𝑸" + }, + mbfitR = { + doc = "mathematical bold italic capital r", + symbol = "𝑹" + }, + mbfitRho = { + doc = "mathematical bold italic capital rho", + symbol = "𝜬" + }, + mbfitS = { + doc = "mathematical bold italic capital s", + symbol = "𝑺" + }, + mbfitSigma = { + doc = "mathematical bold italic capital sigma", + symbol = "𝜮" + }, + mbfitT = { + doc = "mathematical bold italic capital t", + symbol = "𝑻" + }, + mbfitTau = { + doc = "mathematical bold italic capital tau", + symbol = "𝜯" + }, + mbfitTheta = { + doc = "mathematical bold italic capital theta", + symbol = "𝜣" + }, + mbfitU = { + doc = "mathematical bold italic capital u", + symbol = "𝑼" + }, + mbfitUpsilon = { + doc = "mathematical bold italic capital upsilon", + symbol = "𝜰" + }, + mbfitV = { + doc = "mathematical bold italic capital v", + symbol = "𝑽" + }, + mbfitW = { + doc = "mathematical bold italic capital w", + symbol = "𝑾" + }, + mbfitX = { + doc = "mathematical bold italic capital x", + symbol = "𝑿" + }, + mbfitXi = { + doc = "mathematical bold italic capital xi", + symbol = "𝜩" + }, + mbfitY = { + doc = "mathematical bold italic capital y", + symbol = "𝒀" + }, + mbfitZ = { + doc = "mathematical bold italic capital z", + symbol = "𝒁" + }, + mbfitZeta = { + doc = "mathematical bold italic capital zeta", + symbol = "𝜡" + }, + mbfita = { + doc = "mathematical bold italic small a", + symbol = "𝒂" + }, + mbfitalpha = { + doc = "mathematical bold italic small alpha", + symbol = "𝜶" + }, + mbfitb = { + doc = "mathematical bold italic small b", + symbol = "𝒃" + }, + mbfitbeta = { + doc = "mathematical bold italic small beta", + symbol = "𝜷" + }, + mbfitc = { + doc = "mathematical bold italic small c", + symbol = "𝒄" + }, + mbfitchi = { + doc = "mathematical bold italic small chi", + symbol = "𝝌" + }, + mbfitd = { + doc = "mathematical bold italic small d", + symbol = "𝒅" + }, + mbfitdelta = { + doc = "mathematical bold italic small delta", + symbol = "𝜹" + }, + mbfite = { + doc = "mathematical bold italic small e", + symbol = "𝒆" + }, + mbfitepsilon = { + doc = "mathematical bold italic varepsilon symbol", + symbol = "𝝐" + }, + mbfiteta = { + doc = "mathematical bold italic small eta", + symbol = "𝜼" + }, + mbfitf = { + doc = "mathematical bold italic small f", + symbol = "𝒇" + }, + mbfitg = { + doc = "mathematical bold italic small g", + symbol = "𝒈" + }, + mbfitgamma = { + doc = "mathematical bold italic small gamma", + symbol = "𝜸" + }, + mbfith = { + doc = "mathematical bold italic small h", + symbol = "𝒉" + }, + mbfiti = { + doc = "mathematical bold italic small i", + symbol = "𝒊" + }, + mbfitiota = { + doc = "mathematical bold italic small iota", + symbol = "𝜾" + }, + mbfitj = { + doc = "mathematical bold italic small j", + symbol = "𝒋" + }, + mbfitk = { + doc = "mathematical bold italic small k", + symbol = "𝒌" + }, + mbfitkappa = { + doc = "mathematical bold italic small kappa", + symbol = "𝜿" + }, + mbfitl = { + doc = "mathematical bold italic small l", + symbol = "𝒍" + }, + mbfitlambda = { + doc = "mathematical bold italic small lambda", + symbol = "𝝀" + }, + mbfitm = { + doc = "mathematical bold italic small m", + symbol = "𝒎" + }, + mbfitmu = { + doc = "mathematical bold italic small mu", + symbol = "𝝁" + }, + mbfitn = { + doc = "mathematical bold italic small n", + symbol = "𝒏" + }, + mbfitnabla = { + doc = "mathematical bold italic nabla", + symbol = "𝜵" + }, + mbfitnu = { + doc = "mathematical bold italic small nu", + symbol = "𝝂" + }, + mbfito = { + doc = "mathematical bold italic small o", + symbol = "𝒐" + }, + mbfitomega = { + doc = "mathematical bold italic small omega", + symbol = "𝝎" + }, + mbfitomicron = { + doc = "mathematical bold italic small omicron", + symbol = "𝝄" + }, + mbfitp = { + doc = "mathematical bold italic small p", + symbol = "𝒑" + }, + mbfitpartial = { + doc = "mathematical bold italic partial differential", + symbol = "𝝏" + }, + mbfitphi = { + doc = "mathematical bold italic phi symbol", + symbol = "𝝓" + }, + mbfitpi = { + doc = "mathematical bold italic small pi", + symbol = "𝝅" + }, + mbfitpsi = { + doc = "mathematical bold italic small psi", + symbol = "𝝍" + }, + mbfitq = { + doc = "mathematical bold italic small q", + symbol = "𝒒" + }, + mbfitr = { + doc = "mathematical bold italic small r", + symbol = "𝒓" + }, + mbfitrho = { + doc = "mathematical bold italic small rho", + symbol = "𝝆" + }, + mbfits = { + doc = "mathematical bold italic small s", + symbol = "𝒔" + }, + mbfitsansA = { + doc = "mathematical sans-serif bold italic capital a", + symbol = "𝘼" + }, + mbfitsansAlpha = { + doc = "mathematical sans-serif bold italic capital alpha", + symbol = "𝞐" + }, + mbfitsansB = { + doc = "mathematical sans-serif bold italic capital b", + symbol = "𝘽" + }, + mbfitsansBeta = { + doc = "mathematical sans-serif bold italic capital beta", + symbol = "𝞑" + }, + mbfitsansC = { + doc = "mathematical sans-serif bold italic capital c", + symbol = "𝘾" + }, + mbfitsansChi = { + doc = "mathematical sans-serif bold italic capital chi", + symbol = "𝞦" + }, + mbfitsansD = { + doc = "mathematical sans-serif bold italic capital d", + symbol = "𝘿" + }, + mbfitsansDelta = { + doc = "mathematical sans-serif bold italic capital delta", + symbol = "𝞓" + }, + mbfitsansE = { + doc = "mathematical sans-serif bold italic capital e", + symbol = "𝙀" + }, + mbfitsansEpsilon = { + doc = "mathematical sans-serif bold italic capital epsilon", + symbol = "𝞔" + }, + mbfitsansEta = { + doc = "mathematical sans-serif bold italic capital eta", + symbol = "𝞖" + }, + mbfitsansF = { + doc = "mathematical sans-serif bold italic capital f", + symbol = "𝙁" + }, + mbfitsansG = { + doc = "mathematical sans-serif bold italic capital g", + symbol = "𝙂" + }, + mbfitsansGamma = { + doc = "mathematical sans-serif bold italic capital gamma", + symbol = "𝞒" + }, + mbfitsansH = { + doc = "mathematical sans-serif bold italic capital h", + symbol = "𝙃" + }, + mbfitsansI = { + doc = "mathematical sans-serif bold italic capital i", + symbol = "𝙄" + }, + mbfitsansIota = { + doc = "mathematical sans-serif bold italic capital iota", + symbol = "𝞘" + }, + mbfitsansJ = { + doc = "mathematical sans-serif bold italic capital j", + symbol = "𝙅" + }, + mbfitsansK = { + doc = "mathematical sans-serif bold italic capital k", + symbol = "𝙆" + }, + mbfitsansKappa = { + doc = "mathematical sans-serif bold italic capital kappa", + symbol = "𝞙" + }, + mbfitsansL = { + doc = "mathematical sans-serif bold italic capital l", + symbol = "𝙇" + }, + mbfitsansLambda = { + doc = "mathematical sans-serif bold italic capital lambda", + symbol = "𝞚" + }, + mbfitsansM = { + doc = "mathematical sans-serif bold italic capital m", + symbol = "𝙈" + }, + mbfitsansMu = { + doc = "mathematical sans-serif bold italic capital mu", + symbol = "𝞛" + }, + mbfitsansN = { + doc = "mathematical sans-serif bold italic capital n", + symbol = "𝙉" + }, + mbfitsansNu = { + doc = "mathematical sans-serif bold italic capital nu", + symbol = "𝞜" + }, + mbfitsansO = { + doc = "mathematical sans-serif bold italic capital o", + symbol = "𝙊" + }, + mbfitsansOmega = { + doc = "mathematical sans-serif bold italic capital omega", + symbol = "𝞨" + }, + mbfitsansOmicron = { + doc = "mathematical sans-serif bold italic capital omicron", + symbol = "𝞞" + }, + mbfitsansP = { + doc = "mathematical sans-serif bold italic capital p", + symbol = "𝙋" + }, + mbfitsansPhi = { + doc = "mathematical sans-serif bold italic capital phi", + symbol = "𝞥" + }, + mbfitsansPi = { + doc = "mathematical sans-serif bold italic capital pi", + symbol = "𝞟" + }, + mbfitsansPsi = { + doc = "mathematical sans-serif bold italic capital psi", + symbol = "𝞧" + }, + mbfitsansQ = { + doc = "mathematical sans-serif bold italic capital q", + symbol = "𝙌" + }, + mbfitsansR = { + doc = "mathematical sans-serif bold italic capital r", + symbol = "𝙍" + }, + mbfitsansRho = { + doc = "mathematical sans-serif bold italic capital rho", + symbol = "𝞠" + }, + mbfitsansS = { + doc = "mathematical sans-serif bold italic capital s", + symbol = "𝙎" + }, + mbfitsansSigma = { + doc = "mathematical sans-serif bold italic capital sigma", + symbol = "𝞢" + }, + mbfitsansT = { + doc = "mathematical sans-serif bold italic capital t", + symbol = "𝙏" + }, + mbfitsansTau = { + doc = "mathematical sans-serif bold italic capital tau", + symbol = "𝞣" + }, + mbfitsansTheta = { + doc = "mathematical sans-serif bold italic capital theta", + symbol = "𝞗" + }, + mbfitsansU = { + doc = "mathematical sans-serif bold italic capital u", + symbol = "𝙐" + }, + mbfitsansUpsilon = { + doc = "mathematical sans-serif bold italic capital upsilon", + symbol = "𝞤" + }, + mbfitsansV = { + doc = "mathematical sans-serif bold italic capital v", + symbol = "𝙑" + }, + mbfitsansW = { + doc = "mathematical sans-serif bold italic capital w", + symbol = "𝙒" + }, + mbfitsansX = { + doc = "mathematical sans-serif bold italic capital x", + symbol = "𝙓" + }, + mbfitsansXi = { + doc = "mathematical sans-serif bold italic capital xi", + symbol = "𝞝" + }, + mbfitsansY = { + doc = "mathematical sans-serif bold italic capital y", + symbol = "𝙔" + }, + mbfitsansZ = { + doc = "mathematical sans-serif bold italic capital z", + symbol = "𝙕" + }, + mbfitsansZeta = { + doc = "mathematical sans-serif bold italic capital zeta", + symbol = "𝞕" + }, + mbfitsansa = { + doc = "mathematical sans-serif bold italic small a", + symbol = "𝙖" + }, + mbfitsansalpha = { + doc = "mathematical sans-serif bold italic small alpha", + symbol = "𝞪" + }, + mbfitsansb = { + doc = "mathematical sans-serif bold italic small b", + symbol = "𝙗" + }, + mbfitsansbeta = { + doc = "mathematical sans-serif bold italic small beta", + symbol = "𝞫" + }, + mbfitsansc = { + doc = "mathematical sans-serif bold italic small c", + symbol = "𝙘" + }, + mbfitsanschi = { + doc = "mathematical sans-serif bold italic small chi", + symbol = "𝟀" + }, + mbfitsansd = { + doc = "mathematical sans-serif bold italic small d", + symbol = "𝙙" + }, + mbfitsansdelta = { + doc = "mathematical sans-serif bold italic small delta", + symbol = "𝞭" + }, + mbfitsanse = { + doc = "mathematical sans-serif bold italic small e", + symbol = "𝙚" + }, + mbfitsansepsilon = { + doc = "mathematical sans-serif bold italic varepsilon symbol", + symbol = "𝟄" + }, + mbfitsanseta = { + doc = "mathematical sans-serif bold italic small eta", + symbol = "𝞰" + }, + mbfitsansf = { + doc = "mathematical sans-serif bold italic small f", + symbol = "𝙛" + }, + mbfitsansg = { + doc = "mathematical sans-serif bold italic small g", + symbol = "𝙜" + }, + mbfitsansgamma = { + doc = "mathematical sans-serif bold italic small gamma", + symbol = "𝞬" + }, + mbfitsansh = { + doc = "mathematical sans-serif bold italic small h", + symbol = "𝙝" + }, + mbfitsansi = { + doc = "mathematical sans-serif bold italic small i", + symbol = "𝙞" + }, + mbfitsansiota = { + doc = "mathematical sans-serif bold italic small iota", + symbol = "𝞲" + }, + mbfitsansj = { + doc = "mathematical sans-serif bold italic small j", + symbol = "𝙟" + }, + mbfitsansk = { + doc = "mathematical sans-serif bold italic small k", + symbol = "𝙠" + }, + mbfitsanskappa = { + doc = "mathematical sans-serif bold italic small kappa", + symbol = "𝞳" + }, + mbfitsansl = { + doc = "mathematical sans-serif bold italic small l", + symbol = "𝙡" + }, + mbfitsanslambda = { + doc = "mathematical sans-serif bold italic small lambda", + symbol = "𝞴" + }, + mbfitsansm = { + doc = "mathematical sans-serif bold italic small m", + symbol = "𝙢" + }, + mbfitsansmu = { + doc = "mathematical sans-serif bold italic small mu", + symbol = "𝞵" + }, + mbfitsansn = { + doc = "mathematical sans-serif bold italic small n", + symbol = "𝙣" + }, + mbfitsansnabla = { + doc = "mathematical sans-serif bold italic nabla", + symbol = "𝞩" + }, + mbfitsansnu = { + doc = "mathematical sans-serif bold italic small nu", + symbol = "𝞶" + }, + mbfitsanso = { + doc = "mathematical sans-serif bold italic small o", + symbol = "𝙤" + }, + mbfitsansomega = { + doc = "mathematical sans-serif bold italic small omega", + symbol = "𝟂" + }, + mbfitsansomicron = { + doc = "mathematical sans-serif bold italic small omicron", + symbol = "𝞸" + }, + mbfitsansp = { + doc = "mathematical sans-serif bold italic small p", + symbol = "𝙥" + }, + mbfitsanspartial = { + doc = "mathematical sans-serif bold italic partial differential", + symbol = "𝟃" + }, + mbfitsansphi = { + doc = "mathematical sans-serif bold italic phi symbol", + symbol = "𝟇" + }, + mbfitsanspi = { + doc = "mathematical sans-serif bold italic small pi", + symbol = "𝞹" + }, + mbfitsanspsi = { + doc = "mathematical sans-serif bold italic small psi", + symbol = "𝟁" + }, + mbfitsansq = { + doc = "mathematical sans-serif bold italic small q", + symbol = "𝙦" + }, + mbfitsansr = { + doc = "mathematical sans-serif bold italic small r", + symbol = "𝙧" + }, + mbfitsansrho = { + doc = "mathematical sans-serif bold italic small rho", + symbol = "𝞺" + }, + mbfitsanss = { + doc = "mathematical sans-serif bold italic small s", + symbol = "𝙨" + }, + mbfitsanssigma = { + doc = "mathematical sans-serif bold italic small sigma", + symbol = "𝞼" + }, + mbfitsanst = { + doc = "mathematical sans-serif bold italic small t", + symbol = "𝙩" + }, + mbfitsanstau = { + doc = "mathematical sans-serif bold italic small tau", + symbol = "𝞽" + }, + mbfitsanstheta = { + doc = "mathematical sans-serif bold italic small theta", + symbol = "𝞱" + }, + mbfitsansu = { + doc = "mathematical sans-serif bold italic small u", + symbol = "𝙪" + }, + mbfitsansupsilon = { + doc = "mathematical sans-serif bold italic small upsilon", + symbol = "𝞾" + }, + mbfitsansv = { + doc = "mathematical sans-serif bold italic small v", + symbol = "𝙫" + }, + mbfitsansvarTheta = { + doc = "mathematical sans-serif bold italic capital theta symbol", + symbol = "𝞡" + }, + mbfitsansvarepsilon = { + doc = "mathematical sans-serif bold italic small varepsilon", + symbol = "𝞮" + }, + mbfitsansvarkappa = { + doc = "mathematical sans-serif bold italic kappa symbol", + symbol = "𝟆" + }, + mbfitsansvarphi = { + doc = "mathematical sans-serif bold italic small phi", + symbol = "𝞿" + }, + mbfitsansvarpi = { + doc = "mathematical sans-serif bold italic pi symbol", + symbol = "𝟉" + }, + mbfitsansvarrho = { + doc = "mathematical sans-serif bold italic rho symbol", + symbol = "𝟈" + }, + mbfitsansvarsigma = { + doc = "mathematical sans-serif bold italic small final sigma", + symbol = "𝞻" + }, + mbfitsansvartheta = { + doc = "mathematical sans-serif bold italic theta symbol", + symbol = "𝟅" + }, + mbfitsansw = { + doc = "mathematical sans-serif bold italic small w", + symbol = "𝙬" + }, + mbfitsansx = { + doc = "mathematical sans-serif bold italic small x", + symbol = "𝙭" + }, + mbfitsansxi = { + doc = "mathematical sans-serif bold italic small xi", + symbol = "𝞷" + }, + mbfitsansy = { + doc = "mathematical sans-serif bold italic small y", + symbol = "𝙮" + }, + mbfitsansz = { + doc = "mathematical sans-serif bold italic small z", + symbol = "𝙯" + }, + mbfitsanszeta = { + doc = "mathematical sans-serif bold italic small zeta", + symbol = "𝞯" + }, + mbfitsigma = { + doc = "mathematical bold italic small sigma", + symbol = "𝝈" + }, + mbfitt = { + doc = "mathematical bold italic small t", + symbol = "𝒕" + }, + mbfittau = { + doc = "mathematical bold italic small tau", + symbol = "𝝉" + }, + mbfittheta = { + doc = "mathematical bold italic small theta", + symbol = "𝜽" + }, + mbfitu = { + doc = "mathematical bold italic small u", + symbol = "𝒖" + }, + mbfitupsilon = { + doc = "mathematical bold italic small upsilon", + symbol = "𝝊" + }, + mbfitv = { + doc = "mathematical bold italic small v", + symbol = "𝒗" + }, + mbfitvarTheta = { + doc = "mathematical bold italic capital theta symbol", + symbol = "𝜭" + }, + mbfitvarepsilon = { + doc = "mathematical bold italic small varepsilon", + symbol = "𝜺" + }, + mbfitvarkappa = { + doc = "mathematical bold italic kappa symbol", + symbol = "𝝒" + }, + mbfitvarphi = { + doc = "mathematical bold italic small phi", + symbol = "𝝋" + }, + mbfitvarpi = { + doc = "mathematical bold italic pi symbol", + symbol = "𝝕" + }, + mbfitvarrho = { + doc = "mathematical bold italic rho symbol", + symbol = "𝝔" + }, + mbfitvarsigma = { + doc = "mathematical bold italic small final sigma", + symbol = "𝝇" + }, + mbfitvartheta = { + doc = "mathematical bold italic theta symbol", + symbol = "𝝑" + }, + mbfitw = { + doc = "mathematical bold italic small w", + symbol = "𝒘" + }, + mbfitx = { + doc = "mathematical bold italic small x", + symbol = "𝒙" + }, + mbfitxi = { + doc = "mathematical bold italic small xi", + symbol = "𝝃" + }, + mbfity = { + doc = "mathematical bold italic small y", + symbol = "𝒚" + }, + mbfitz = { + doc = "mathematical bold italic small z", + symbol = "𝒛" + }, + mbfitzeta = { + doc = "mathematical bold italic small zeta", + symbol = "𝜻" + }, + mbfj = { + doc = "mathematical bold small j", + symbol = "𝐣" + }, + mbfk = { + doc = "mathematical bold small k", + symbol = "𝐤" + }, + mbfkappa = { + doc = "mathematical bold small kappa", + symbol = "𝛋" + }, + mbfl = { + doc = "mathematical bold small l", + symbol = "𝐥" + }, + mbflambda = { + doc = "mathematical bold small lambda", + symbol = "𝛌" + }, + mbfm = { + doc = "mathematical bold small m", + symbol = "𝐦" + }, + mbfmu = { + doc = "mathematical bold small mu", + symbol = "𝛍" + }, + mbfn = { + doc = "mathematical bold small n", + symbol = "𝐧" + }, + mbfnabla = { + doc = "mathematical bold nabla", + symbol = "𝛁" + }, + mbfnine = { + doc = "mathematical bold digit 9", + symbol = "𝟗" + }, + mbfnu = { + doc = "mathematical bold small nu", + symbol = "𝛎" + }, + mbfo = { + doc = "mathematical bold small o", + symbol = "𝐨" + }, + mbfomega = { + doc = "mathematical bold small omega", + symbol = "𝛚" + }, + mbfomicron = { + doc = "mathematical bold small omicron", + symbol = "𝛐" + }, + mbfone = { + doc = "mathematical bold digit 1", + symbol = "𝟏" + }, + mbfp = { + doc = "mathematical bold small p", + symbol = "𝐩" + }, + mbfpartial = { + doc = "mathematical bold partial differential", + symbol = "𝛛" + }, + mbfphi = { + doc = "mathematical bold phi symbol", + symbol = "𝛟" + }, + mbfpi = { + doc = "mathematical bold small pi", + symbol = "𝛑" + }, + mbfpsi = { + doc = "mathematical bold small psi", + symbol = "𝛙" + }, + mbfq = { + doc = "mathematical bold small q", + symbol = "𝐪" + }, + mbfr = { + doc = "mathematical bold small r", + symbol = "𝐫" + }, + mbfrho = { + doc = "mathematical bold small rho", + symbol = "𝛒" + }, + mbfs = { + doc = "mathematical bold small s", + symbol = "𝐬" + }, + mbfsansA = { + doc = "mathematical sans-serif bold capital a", + symbol = "𝗔" + }, + mbfsansAlpha = { + doc = "mathematical sans-serif bold capital alpha", + symbol = "𝝖" + }, + mbfsansB = { + doc = "mathematical sans-serif bold capital b", + symbol = "𝗕" + }, + mbfsansBeta = { + doc = "mathematical sans-serif bold capital beta", + symbol = "𝝗" + }, + mbfsansC = { + doc = "mathematical sans-serif bold capital c", + symbol = "𝗖" + }, + mbfsansChi = { + doc = "mathematical sans-serif bold capital chi", + symbol = "𝝬" + }, + mbfsansD = { + doc = "mathematical sans-serif bold capital d", + symbol = "𝗗" + }, + mbfsansDelta = { + doc = "mathematical sans-serif bold capital delta", + symbol = "𝝙" + }, + mbfsansE = { + doc = "mathematical sans-serif bold capital e", + symbol = "𝗘" + }, + mbfsansEpsilon = { + doc = "mathematical sans-serif bold capital epsilon", + symbol = "𝝚" + }, + mbfsansEta = { + doc = "mathematical sans-serif bold capital eta", + symbol = "𝝜" + }, + mbfsansF = { + doc = "mathematical sans-serif bold capital f", + symbol = "𝗙" + }, + mbfsansG = { + doc = "mathematical sans-serif bold capital g", + symbol = "𝗚" + }, + mbfsansGamma = { + doc = "mathematical sans-serif bold capital gamma", + symbol = "𝝘" + }, + mbfsansH = { + doc = "mathematical sans-serif bold capital h", + symbol = "𝗛" + }, + mbfsansI = { + doc = "mathematical sans-serif bold capital i", + symbol = "𝗜" + }, + mbfsansIota = { + doc = "mathematical sans-serif bold capital iota", + symbol = "𝝞" + }, + mbfsansJ = { + doc = "mathematical sans-serif bold capital j", + symbol = "𝗝" + }, + mbfsansK = { + doc = "mathematical sans-serif bold capital k", + symbol = "𝗞" + }, + mbfsansKappa = { + doc = "mathematical sans-serif bold capital kappa", + symbol = "𝝟" + }, + mbfsansL = { + doc = "mathematical sans-serif bold capital l", + symbol = "𝗟" + }, + mbfsansLambda = { + doc = "mathematical sans-serif bold capital lambda", + symbol = "𝝠" + }, + mbfsansM = { + doc = "mathematical sans-serif bold capital m", + symbol = "𝗠" + }, + mbfsansMu = { + doc = "mathematical sans-serif bold capital mu", + symbol = "𝝡" + }, + mbfsansN = { + doc = "mathematical sans-serif bold capital n", + symbol = "𝗡" + }, + mbfsansNu = { + doc = "mathematical sans-serif bold capital nu", + symbol = "𝝢" + }, + mbfsansO = { + doc = "mathematical sans-serif bold capital o", + symbol = "𝗢" + }, + mbfsansOmega = { + doc = "mathematical sans-serif bold capital omega", + symbol = "𝝮" + }, + mbfsansOmicron = { + doc = "mathematical sans-serif bold capital omicron", + symbol = "𝝤" + }, + mbfsansP = { + doc = "mathematical sans-serif bold capital p", + symbol = "𝗣" + }, + mbfsansPhi = { + doc = "mathematical sans-serif bold capital phi", + symbol = "𝝫" + }, + mbfsansPi = { + doc = "mathematical sans-serif bold capital pi", + symbol = "𝝥" + }, + mbfsansPsi = { + doc = "mathematical sans-serif bold capital psi", + symbol = "𝝭" + }, + mbfsansQ = { + doc = "mathematical sans-serif bold capital q", + symbol = "𝗤" + }, + mbfsansR = { + doc = "mathematical sans-serif bold capital r", + symbol = "𝗥" + }, + mbfsansRho = { + doc = "mathematical sans-serif bold capital rho", + symbol = "𝝦" + }, + mbfsansS = { + doc = "mathematical sans-serif bold capital s", + symbol = "𝗦" + }, + mbfsansSigma = { + doc = "mathematical sans-serif bold capital sigma", + symbol = "𝝨" + }, + mbfsansT = { + doc = "mathematical sans-serif bold capital t", + symbol = "𝗧" + }, + mbfsansTau = { + doc = "mathematical sans-serif bold capital tau", + symbol = "𝝩" + }, + mbfsansTheta = { + doc = "mathematical sans-serif bold capital theta", + symbol = "𝝝" + }, + mbfsansU = { + doc = "mathematical sans-serif bold capital u", + symbol = "𝗨" + }, + mbfsansUpsilon = { + doc = "mathematical sans-serif bold capital upsilon", + symbol = "𝝪" + }, + mbfsansV = { + doc = "mathematical sans-serif bold capital v", + symbol = "𝗩" + }, + mbfsansW = { + doc = "mathematical sans-serif bold capital w", + symbol = "𝗪" + }, + mbfsansX = { + doc = "mathematical sans-serif bold capital x", + symbol = "𝗫" + }, + mbfsansXi = { + doc = "mathematical sans-serif bold capital xi", + symbol = "𝝣" + }, + mbfsansY = { + doc = "mathematical sans-serif bold capital y", + symbol = "𝗬" + }, + mbfsansZ = { + doc = "mathematical sans-serif bold capital z", + symbol = "𝗭" + }, + mbfsansZeta = { + doc = "mathematical sans-serif bold capital zeta", + symbol = "𝝛" + }, + mbfsansa = { + doc = "mathematical sans-serif bold small a", + symbol = "𝗮" + }, + mbfsansalpha = { + doc = "mathematical sans-serif bold small alpha", + symbol = "𝝰" + }, + mbfsansb = { + doc = "mathematical sans-serif bold small b", + symbol = "𝗯" + }, + mbfsansbeta = { + doc = "mathematical sans-serif bold small beta", + symbol = "𝝱" + }, + mbfsansc = { + doc = "mathematical sans-serif bold small c", + symbol = "𝗰" + }, + mbfsanschi = { + doc = "mathematical sans-serif bold small chi", + symbol = "𝞆" + }, + mbfsansd = { + doc = "mathematical sans-serif bold small d", + symbol = "𝗱" + }, + mbfsansdelta = { + doc = "mathematical sans-serif bold small delta", + symbol = "𝝳" + }, + mbfsanse = { + doc = "mathematical sans-serif bold small e", + symbol = "𝗲" + }, + mbfsanseight = { + doc = "mathematical sans-serif bold digit 8", + symbol = "𝟴" + }, + mbfsansepsilon = { + doc = "mathematical sans-serif bold varepsilon symbol", + symbol = "𝞊" + }, + mbfsanseta = { + doc = "mathematical sans-serif bold small eta", + symbol = "𝝶" + }, + mbfsansf = { + doc = "mathematical sans-serif bold small f", + symbol = "𝗳" + }, + mbfsansfive = { + doc = "mathematical sans-serif bold digit 5", + symbol = "𝟱" + }, + mbfsansfour = { + doc = "mathematical sans-serif bold digit 4", + symbol = "𝟰" + }, + mbfsansg = { + doc = "mathematical sans-serif bold small g", + symbol = "𝗴" + }, + mbfsansgamma = { + doc = "mathematical sans-serif bold small gamma", + symbol = "𝝲" + }, + mbfsansh = { + doc = "mathematical sans-serif bold small h", + symbol = "𝗵" + }, + mbfsansi = { + doc = "mathematical sans-serif bold small i", + symbol = "𝗶" + }, + mbfsansiota = { + doc = "mathematical sans-serif bold small iota", + symbol = "𝝸" + }, + mbfsansj = { + doc = "mathematical sans-serif bold small j", + symbol = "𝗷" + }, + mbfsansk = { + doc = "mathematical sans-serif bold small k", + symbol = "𝗸" + }, + mbfsanskappa = { + doc = "mathematical sans-serif bold small kappa", + symbol = "𝝹" + }, + mbfsansl = { + doc = "mathematical sans-serif bold small l", + symbol = "𝗹" + }, + mbfsanslambda = { + doc = "mathematical sans-serif bold small lambda", + symbol = "𝝺" + }, + mbfsansm = { + doc = "mathematical sans-serif bold small m", + symbol = "𝗺" + }, + mbfsansmu = { + doc = "mathematical sans-serif bold small mu", + symbol = "𝝻" + }, + mbfsansn = { + doc = "mathematical sans-serif bold small n", + symbol = "𝗻" + }, + mbfsansnabla = { + doc = "mathematical sans-serif bold nabla", + symbol = "𝝯" + }, + mbfsansnine = { + doc = "mathematical sans-serif bold digit 9", + symbol = "𝟵" + }, + mbfsansnu = { + doc = "mathematical sans-serif bold small nu", + symbol = "𝝼" + }, + mbfsanso = { + doc = "mathematical sans-serif bold small o", + symbol = "𝗼" + }, + mbfsansomega = { + doc = "mathematical sans-serif bold small omega", + symbol = "𝞈" + }, + mbfsansomicron = { + doc = "mathematical sans-serif bold small omicron", + symbol = "𝝾" + }, + mbfsansone = { + doc = "mathematical sans-serif bold digit 1", + symbol = "𝟭" + }, + mbfsansp = { + doc = "mathematical sans-serif bold small p", + symbol = "𝗽" + }, + mbfsanspartial = { + doc = "mathematical sans-serif bold partial differential", + symbol = "𝞉" + }, + mbfsansphi = { + doc = "mathematical sans-serif bold phi symbol", + symbol = "𝞍" + }, + mbfsanspi = { + doc = "mathematical sans-serif bold small pi", + symbol = "𝝿" + }, + mbfsanspsi = { + doc = "mathematical sans-serif bold small psi", + symbol = "𝞇" + }, + mbfsansq = { + doc = "mathematical sans-serif bold small q", + symbol = "𝗾" + }, + mbfsansr = { + doc = "mathematical sans-serif bold small r", + symbol = "𝗿" + }, + mbfsansrho = { + doc = "mathematical sans-serif bold small rho", + symbol = "𝞀" + }, + mbfsanss = { + doc = "mathematical sans-serif bold small s", + symbol = "𝘀" + }, + mbfsansseven = { + doc = "mathematical sans-serif bold digit 7", + symbol = "𝟳" + }, + mbfsanssigma = { + doc = "mathematical sans-serif bold small sigma", + symbol = "𝞂" + }, + mbfsanssix = { + doc = "mathematical sans-serif bold digit 6", + symbol = "𝟲" + }, + mbfsanst = { + doc = "mathematical sans-serif bold small t", + symbol = "𝘁" + }, + mbfsanstau = { + doc = "mathematical sans-serif bold small tau", + symbol = "𝞃" + }, + mbfsanstheta = { + doc = "mathematical sans-serif bold small theta", + symbol = "𝝷" + }, + mbfsansthree = { + doc = "mathematical sans-serif bold digit 3", + symbol = "𝟯" + }, + mbfsanstwo = { + doc = "mathematical sans-serif bold digit 2", + symbol = "𝟮" + }, + mbfsansu = { + doc = "mathematical sans-serif bold small u", + symbol = "𝘂" + }, + mbfsansupsilon = { + doc = "mathematical sans-serif bold small upsilon", + symbol = "𝞄" + }, + mbfsansv = { + doc = "mathematical sans-serif bold small v", + symbol = "𝘃" + }, + mbfsansvarTheta = { + doc = "mathematical sans-serif bold capital theta symbol", + symbol = "𝝧" + }, + mbfsansvarepsilon = { + doc = "mathematical sans-serif bold small varepsilon", + symbol = "𝝴" + }, + mbfsansvarkappa = { + doc = "mathematical sans-serif bold kappa symbol", + symbol = "𝞌" + }, + mbfsansvarphi = { + doc = "mathematical sans-serif bold small phi", + symbol = "𝞅" + }, + mbfsansvarpi = { + doc = "mathematical sans-serif bold pi symbol", + symbol = "𝞏" + }, + mbfsansvarrho = { + doc = "mathematical sans-serif bold rho symbol", + symbol = "𝞎" + }, + mbfsansvarsigma = { + doc = "mathematical sans-serif bold small final sigma", + symbol = "𝞁" + }, + mbfsansvartheta = { + doc = "mathematical sans-serif bold theta symbol", + symbol = "𝞋" + }, + mbfsansw = { + doc = "mathematical sans-serif bold small w", + symbol = "𝘄" + }, + mbfsansx = { + doc = "mathematical sans-serif bold small x", + symbol = "𝘅" + }, + mbfsansxi = { + doc = "mathematical sans-serif bold small xi", + symbol = "𝝽" + }, + mbfsansy = { + doc = "mathematical sans-serif bold small y", + symbol = "𝘆" + }, + mbfsansz = { + doc = "mathematical sans-serif bold small z", + symbol = "𝘇" + }, + mbfsanszero = { + doc = "mathematical sans-serif bold digit 0", + symbol = "𝟬" + }, + mbfsanszeta = { + doc = "mathematical sans-serif bold small zeta", + symbol = "𝝵" + }, + mbfscrA = { + doc = "mathematical bold script capital a", + symbol = "𝓐" + }, + mbfscrB = { + doc = "mathematical bold script capital b", + symbol = "𝓑" + }, + mbfscrC = { + doc = "mathematical bold script capital c", + symbol = "𝓒" + }, + mbfscrD = { + doc = "mathematical bold script capital d", + symbol = "𝓓" + }, + mbfscrE = { + doc = "mathematical bold script capital e", + symbol = "𝓔" + }, + mbfscrF = { + doc = "mathematical bold script capital f", + symbol = "𝓕" + }, + mbfscrG = { + doc = "mathematical bold script capital g", + symbol = "𝓖" + }, + mbfscrH = { + doc = "mathematical bold script capital h", + symbol = "𝓗" + }, + mbfscrI = { + doc = "mathematical bold script capital i", + symbol = "𝓘" + }, + mbfscrJ = { + doc = "mathematical bold script capital j", + symbol = "𝓙" + }, + mbfscrK = { + doc = "mathematical bold script capital k", + symbol = "𝓚" + }, + mbfscrL = { + doc = "mathematical bold script capital l", + symbol = "𝓛" + }, + mbfscrM = { + doc = "mathematical bold script capital m", + symbol = "𝓜" + }, + mbfscrN = { + doc = "mathematical bold script capital n", + symbol = "𝓝" + }, + mbfscrO = { + doc = "mathematical bold script capital o", + symbol = "𝓞" + }, + mbfscrP = { + doc = "mathematical bold script capital p", + symbol = "𝓟" + }, + mbfscrQ = { + doc = "mathematical bold script capital q", + symbol = "𝓠" + }, + mbfscrR = { + doc = "mathematical bold script capital r", + symbol = "𝓡" + }, + mbfscrS = { + doc = "mathematical bold script capital s", + symbol = "𝓢" + }, + mbfscrT = { + doc = "mathematical bold script capital t", + symbol = "𝓣" + }, + mbfscrU = { + doc = "mathematical bold script capital u", + symbol = "𝓤" + }, + mbfscrV = { + doc = "mathematical bold script capital v", + symbol = "𝓥" + }, + mbfscrW = { + doc = "mathematical bold script capital w", + symbol = "𝓦" + }, + mbfscrX = { + doc = "mathematical bold script capital x", + symbol = "𝓧" + }, + mbfscrY = { + doc = "mathematical bold script capital y", + symbol = "𝓨" + }, + mbfscrZ = { + doc = "mathematical bold script capital z", + symbol = "𝓩" + }, + mbfscra = { + doc = "mathematical bold script small a", + symbol = "𝓪" + }, + mbfscrb = { + doc = "mathematical bold script small b", + symbol = "𝓫" + }, + mbfscrc = { + doc = "mathematical bold script small c", + symbol = "𝓬" + }, + mbfscrd = { + doc = "mathematical bold script small d", + symbol = "𝓭" + }, + mbfscre = { + doc = "mathematical bold script small e", + symbol = "𝓮" + }, + mbfscrf = { + doc = "mathematical bold script small f", + symbol = "𝓯" + }, + mbfscrg = { + doc = "mathematical bold script small g", + symbol = "𝓰" + }, + mbfscrh = { + doc = "mathematical bold script small h", + symbol = "𝓱" + }, + mbfscri = { + doc = "mathematical bold script small i", + symbol = "𝓲" + }, + mbfscrj = { + doc = "mathematical bold script small j", + symbol = "𝓳" + }, + mbfscrk = { + doc = "mathematical bold script small k", + symbol = "𝓴" + }, + mbfscrl = { + doc = "mathematical bold script small l", + symbol = "𝓵" + }, + mbfscrm = { + doc = "mathematical bold script small m", + symbol = "𝓶" + }, + mbfscrn = { + doc = "mathematical bold script small n", + symbol = "𝓷" + }, + mbfscro = { + doc = "mathematical bold script small o", + symbol = "𝓸" + }, + mbfscrp = { + doc = "mathematical bold script small p", + symbol = "𝓹" + }, + mbfscrq = { + doc = "mathematical bold script small q", + symbol = "𝓺" + }, + mbfscrr = { + doc = "mathematical bold script small r", + symbol = "𝓻" + }, + mbfscrs = { + doc = "mathematical bold script small s", + symbol = "𝓼" + }, + mbfscrt = { + doc = "mathematical bold script small t", + symbol = "𝓽" + }, + mbfscru = { + doc = "mathematical bold script small u", + symbol = "𝓾" + }, + mbfscrv = { + doc = "mathematical bold script small v", + symbol = "𝓿" + }, + mbfscrw = { + doc = "mathematical bold script small w", + symbol = "𝔀" + }, + mbfscrx = { + doc = "mathematical bold script small x", + symbol = "𝔁" + }, + mbfscry = { + doc = "mathematical bold script small y", + symbol = "𝔂" + }, + mbfscrz = { + doc = "mathematical bold script small z", + symbol = "𝔃" + }, + mbfseven = { + doc = "mathematical bold digit 7", + symbol = "𝟕" + }, + mbfsigma = { + doc = "mathematical bold small sigma", + symbol = "𝛔" + }, + mbfsix = { + doc = "mathematical bold digit 6", + symbol = "𝟔" + }, + mbft = { + doc = "mathematical bold small t", + symbol = "𝐭" + }, + mbftau = { + doc = "mathematical bold small tau", + symbol = "𝛕" + }, + mbftheta = { + doc = "mathematical bold small theta", + symbol = "𝛉" + }, + mbfthree = { + doc = "mathematical bold digit 3", + symbol = "𝟑" + }, + mbftwo = { + doc = "mathematical bold digit 2", + symbol = "𝟐" + }, + mbfu = { + doc = "mathematical bold small u", + symbol = "𝐮" + }, + mbfupsilon = { + doc = "mathematical bold small upsilon", + symbol = "𝛖" + }, + mbfv = { + doc = "mathematical bold small v", + symbol = "𝐯" + }, + mbfvarTheta = { + doc = "mathematical bold capital theta symbol", + symbol = "𝚹" + }, + mbfvarepsilon = { + doc = "mathematical bold small varepsilon", + symbol = "𝛆" + }, + mbfvarkappa = { + doc = "mathematical bold kappa symbol", + symbol = "𝛞" + }, + mbfvarphi = { + doc = "mathematical bold small phi", + symbol = "𝛗" + }, + mbfvarpi = { + doc = "mathematical bold pi symbol", + symbol = "𝛡" + }, + mbfvarrho = { + doc = "mathematical bold rho symbol", + symbol = "𝛠" + }, + mbfvarsigma = { + doc = "mathematical bold small final sigma", + symbol = "𝛓" + }, + mbfvartheta = { + doc = "mathematical bold theta symbol", + symbol = "𝛝" + }, + mbfw = { + doc = "mathematical bold small w", + symbol = "𝐰" + }, + mbfx = { + doc = "mathematical bold small x", + symbol = "𝐱" + }, + mbfxi = { + doc = "mathematical bold small xi", + symbol = "𝛏" + }, + mbfy = { + doc = "mathematical bold small y", + symbol = "𝐲" + }, + mbfz = { + doc = "mathematical bold small z", + symbol = "𝐳" + }, + mbfzero = { + doc = "mathematical bold digit 0", + symbol = "𝟎" + }, + mbfzeta = { + doc = "mathematical bold small zeta", + symbol = "𝛇" + }, + mdblkcircle = { + doc = "medium black circle", + symbol = "⚫" + }, + mdblkdiamond = { + doc = "black medium diamond", + symbol = "⬥" + }, + mdblklozenge = { + doc = "black medium lozenge", + symbol = "⬧" + }, + mdblksquare = { + doc = "black medium square", + symbol = "◼" + }, + mdlgblkcircle = { + doc = "circle, filled", + symbol = "●" + }, + mdlgblkdiamond = { + doc = "black diamond", + symbol = "◆" + }, + mdlgblklozenge = { + doc = "black lozenge", + symbol = "⧫" + }, + mdlgblksquare = { + doc = "square, filled", + symbol = "■" + }, + mdlgwhtcircle = { + doc = "medium large circle", + symbol = "○" + }, + mdlgwhtdiamond = { + doc = "white diamond; diamond, open", + symbol = "◇" + }, + mdlgwhtlozenge = { + doc = "lozenge or total mark", + symbol = "◊" + }, + mdlgwhtsquare = { + doc = "square, open", + symbol = "□" + }, + mdsmblkcircle = { + doc = "z notation spot", + symbol = "⦁" + }, + mdsmblksquare = { + doc = "black medium small square", + symbol = "◾" + }, + mdsmwhtcircle = { + doc = "medium small white circle", + symbol = "⚬" + }, + mdsmwhtsquare = { + doc = "white medium small square", + symbol = "◽" + }, + mdwhtcircle = { + doc = "medium white circle", + symbol = "⚪" + }, + mdwhtdiamond = { + doc = "white medium diamond", + symbol = "⬦" + }, + mdwhtlozenge = { + doc = "white medium lozenge", + symbol = "⬨" + }, + mdwhtsquare = { + doc = "white medium square", + symbol = "◻" + }, + measangledltosw = { + doc = "measured angle with open arm ending in arrow pointing left and down", + symbol = "⦯" + }, + measangledrtose = { + doc = "measured angle with open arm ending in arrow pointing right and down", + symbol = "⦮" + }, + measangleldtosw = { + doc = "measured angle with open arm ending in arrow pointing down and left", + symbol = "⦫" + }, + measanglelutonw = { + doc = "measured angle with open arm ending in arrow pointing up and left", + symbol = "⦩" + }, + measanglerdtose = { + doc = "measured angle with open arm ending in arrow pointing down and right", + symbol = "⦪" + }, + measanglerutone = { + doc = "measured angle with open arm ending in arrow pointing up and right", + symbol = "⦨" + }, + measangleultonw = { + doc = "measured angle with open arm ending in arrow pointing left and up", + symbol = "⦭" + }, + measangleurtone = { + doc = "measured angle with open arm ending in arrow pointing right and up", + symbol = "⦬" + }, + measeq = { + doc = "measured by (m over equals)", + symbol = "≞" + }, + measuredangle = { + doc = "angle-measured", + symbol = "∡" + }, + measuredangleleft = { + doc = "measured angle opening left", + symbol = "⦛" + }, + measuredrightangle = { + doc = "right angle-measured [with arc]", + symbol = "⊾" + }, + medblackstar = { + doc = "black medium star", + symbol = "⭑" + }, + medwhitestar = { + doc = "white medium star", + symbol = "⭐" + }, + mfrakA = { + doc = "mathematical fraktur capital a", + symbol = "𝔄" + }, + mfrakB = { + doc = "mathematical fraktur capital b", + symbol = "𝔅" + }, + mfrakC = { + doc = "black-letter capital c", + symbol = "ℭ" + }, + mfrakD = { + doc = "mathematical fraktur capital d", + symbol = "𝔇" + }, + mfrakE = { + doc = "mathematical fraktur capital e", + symbol = "𝔈" + }, + mfrakF = { + doc = "mathematical fraktur capital f", + symbol = "𝔉" + }, + mfrakG = { + doc = "mathematical fraktur capital g", + symbol = "𝔊" + }, + mfrakH = { + doc = "/frak h, upper case h", + symbol = "ℌ" + }, + mfrakJ = { + doc = "mathematical fraktur capital j", + symbol = "𝔍" + }, + mfrakK = { + doc = "mathematical fraktur capital k", + symbol = "𝔎" + }, + mfrakL = { + doc = "mathematical fraktur capital l", + symbol = "𝔏" + }, + mfrakM = { + doc = "mathematical fraktur capital m", + symbol = "𝔐" + }, + mfrakN = { + doc = "mathematical fraktur capital n", + symbol = "𝔑" + }, + mfrakO = { + doc = "mathematical fraktur capital o", + symbol = "𝔒" + }, + mfrakP = { + doc = "mathematical fraktur capital p", + symbol = "𝔓" + }, + mfrakQ = { + doc = "mathematical fraktur capital q", + symbol = "𝔔" + }, + mfrakS = { + doc = "mathematical fraktur capital s", + symbol = "𝔖" + }, + mfrakT = { + doc = "mathematical fraktur capital t", + symbol = "𝔗" + }, + mfrakU = { + doc = "mathematical fraktur capital u", + symbol = "𝔘" + }, + mfrakV = { + doc = "mathematical fraktur capital v", + symbol = "𝔙" + }, + mfrakW = { + doc = "mathematical fraktur capital w", + symbol = "𝔚" + }, + mfrakX = { + doc = "mathematical fraktur capital x", + symbol = "𝔛" + }, + mfrakY = { + doc = "mathematical fraktur capital y", + symbol = "𝔜" + }, + mfrakZ = { + doc = "/frak z, upper case z", + symbol = "ℨ" + }, + mfraka = { + doc = "mathematical fraktur small a", + symbol = "𝔞" + }, + mfrakb = { + doc = "mathematical fraktur small b", + symbol = "𝔟" + }, + mfrakc = { + doc = "mathematical fraktur small c", + symbol = "𝔠" + }, + mfrakd = { + doc = "mathematical fraktur small d", + symbol = "𝔡" + }, + mfrake = { + doc = "mathematical fraktur small e", + symbol = "𝔢" + }, + mfrakf = { + doc = "mathematical fraktur small f", + symbol = "𝔣" + }, + mfrakg = { + doc = "mathematical fraktur small g", + symbol = "𝔤" + }, + mfrakh = { + doc = "mathematical fraktur small h", + symbol = "𝔥" + }, + mfraki = { + doc = "mathematical fraktur small i", + symbol = "𝔦" + }, + mfrakj = { + doc = "mathematical fraktur small j", + symbol = "𝔧" + }, + mfrakk = { + doc = "mathematical fraktur small k", + symbol = "𝔨" + }, + mfrakl = { + doc = "mathematical fraktur small l", + symbol = "𝔩" + }, + mfrakm = { + doc = "mathematical fraktur small m", + symbol = "𝔪" + }, + mfrakn = { + doc = "mathematical fraktur small n", + symbol = "𝔫" + }, + mfrako = { + doc = "mathematical fraktur small o", + symbol = "𝔬" + }, + mfrakp = { + doc = "mathematical fraktur small p", + symbol = "𝔭" + }, + mfrakq = { + doc = "mathematical fraktur small q", + symbol = "𝔮" + }, + mfrakr = { + doc = "mathematical fraktur small r", + symbol = "𝔯" + }, + mfraks = { + doc = "mathematical fraktur small s", + symbol = "𝔰" + }, + mfrakt = { + doc = "mathematical fraktur small t", + symbol = "𝔱" + }, + mfraku = { + doc = "mathematical fraktur small u", + symbol = "𝔲" + }, + mfrakv = { + doc = "mathematical fraktur small v", + symbol = "𝔳" + }, + mfrakw = { + doc = "mathematical fraktur small w", + symbol = "𝔴" + }, + mfrakx = { + doc = "mathematical fraktur small x", + symbol = "𝔵" + }, + mfraky = { + doc = "mathematical fraktur small y", + symbol = "𝔶" + }, + mfrakz = { + doc = "mathematical fraktur small z", + symbol = "𝔷" + }, + mho = { + doc = "conductance", + symbol = "℧" + }, + mid = { + doc = "/mid r:", + symbol = "∣" + }, + midbarvee = { + doc = "logical or with horizontal dash", + symbol = "⩝" + }, + midbarwedge = { + doc = "ogical and with horizontal dash", + symbol = "⩜" + }, + midcir = { + doc = "vertical line with circle below", + symbol = "⫰" + }, + minus = { + doc = "minus sign", + symbol = "−" + }, + minusdot = { + doc = "minus sign with dot below", + symbol = "⨪" + }, + minusfdots = { + doc = "minus sign with falling dots", + symbol = "⨫" + }, + minusrdots = { + doc = "minus sign with rising dots", + symbol = "⨬" + }, + mitA = { + doc = "mathematical italic capital a", + symbol = "𝐴" + }, + mitAlpha = { + doc = "mathematical italic capital alpha", + symbol = "𝛢" + }, + mitB = { + doc = "mathematical italic capital b", + symbol = "𝐵" + }, + mitBbbD = { + doc = "double-struck italic capital d", + symbol = "ⅅ" + }, + mitBbbd = { + doc = "double-struck italic small d", + symbol = "ⅆ" + }, + mitBbbe = { + doc = "double-struck italic small e", + symbol = "ⅇ" + }, + mitBbbi = { + doc = "double-struck italic small i", + symbol = "ⅈ" + }, + mitBbbj = { + doc = "double-struck italic small j", + symbol = "ⅉ" + }, + mitBeta = { + doc = "mathematical italic capital beta", + symbol = "𝛣" + }, + mitC = { + doc = "mathematical italic capital c", + symbol = "𝐶" + }, + mitChi = { + doc = "mathematical italic capital chi", + symbol = "𝛸" + }, + mitD = { + doc = "mathematical italic capital d", + symbol = "𝐷" + }, + mitDelta = { + doc = "mathematical italic capital delta", + symbol = "𝛥" + }, + mitE = { + doc = "mathematical italic capital e", + symbol = "𝐸" + }, + mitEpsilon = { + doc = "mathematical italic capital epsilon", + symbol = "𝛦" + }, + mitEta = { + doc = "mathematical italic capital eta", + symbol = "𝛨" + }, + mitF = { + doc = "mathematical italic capital f", + symbol = "𝐹" + }, + mitG = { + doc = "mathematical italic capital g", + symbol = "𝐺" + }, + mitGamma = { + doc = "mathematical italic capital gamma", + symbol = "𝛤" + }, + mitH = { + doc = "mathematical italic capital h", + symbol = "𝐻" + }, + mitI = { + doc = "mathematical italic capital i", + symbol = "𝐼" + }, + mitIota = { + doc = "mathematical italic capital iota", + symbol = "𝛪" + }, + mitJ = { + doc = "mathematical italic capital j", + symbol = "𝐽" + }, + mitK = { + doc = "mathematical italic capital k", + symbol = "𝐾" + }, + mitKappa = { + doc = "mathematical italic capital kappa", + symbol = "𝛫" + }, + mitL = { + doc = "mathematical italic capital l", + symbol = "𝐿" + }, + mitLambda = { + doc = "mathematical italic capital lambda", + symbol = "𝛬" + }, + mitM = { + doc = "mathematical italic capital m", + symbol = "𝑀" + }, + mitMu = { + doc = "mathematical italic capital mu", + symbol = "𝛭" + }, + mitN = { + doc = "mathematical italic capital n", + symbol = "𝑁" + }, + mitNu = { + doc = "mathematical italic capital nu", + symbol = "𝛮" + }, + mitO = { + doc = "mathematical italic capital o", + symbol = "𝑂" + }, + mitOmega = { + doc = "mathematical italic capital omega", + symbol = "𝛺" + }, + mitOmicron = { + doc = "mathematical italic capital omicron", + symbol = "𝛰" + }, + mitP = { + doc = "mathematical italic capital p", + symbol = "𝑃" + }, + mitPhi = { + doc = "mathematical italic capital phi", + symbol = "𝛷" + }, + mitPi = { + doc = "mathematical italic capital pi", + symbol = "𝛱" + }, + mitPsi = { + doc = "mathematical italic capital psi", + symbol = "𝛹" + }, + mitQ = { + doc = "mathematical italic capital q", + symbol = "𝑄" + }, + mitR = { + doc = "mathematical italic capital r", + symbol = "𝑅" + }, + mitRho = { + doc = "mathematical italic capital rho", + symbol = "𝛲" + }, + mitS = { + doc = "mathematical italic capital s", + symbol = "𝑆" + }, + mitSigma = { + doc = "mathematical italic capital sigma", + symbol = "𝛴" + }, + mitT = { + doc = "mathematical italic capital t", + symbol = "𝑇" + }, + mitTau = { + doc = "mathematical italic capital tau", + symbol = "𝛵" + }, + mitTheta = { + doc = "mathematical italic capital theta", + symbol = "𝛩" + }, + mitU = { + doc = "mathematical italic capital u", + symbol = "𝑈" + }, + mitUpsilon = { + doc = "mathematical italic capital upsilon", + symbol = "𝛶" + }, + mitV = { + doc = "mathematical italic capital v", + symbol = "𝑉" + }, + mitW = { + doc = "mathematical italic capital w", + symbol = "𝑊" + }, + mitX = { + doc = "mathematical italic capital x", + symbol = "𝑋" + }, + mitXi = { + doc = "mathematical italic capital xi", + symbol = "𝛯" + }, + mitY = { + doc = "mathematical italic capital y", + symbol = "𝑌" + }, + mitZ = { + doc = "mathematical italic capital z", + symbol = "𝑍" + }, + mitZeta = { + doc = "mathematical italic capital zeta", + symbol = "𝛧" + }, + mita = { + doc = "mathematical italic small a", + symbol = "𝑎" + }, + mitalpha = { + doc = "mathematical italic small alpha", + symbol = "𝛼" + }, + mitb = { + doc = "mathematical italic small b", + symbol = "𝑏" + }, + mitbeta = { + doc = "mathematical italic small beta", + symbol = "𝛽" + }, + mitc = { + doc = "mathematical italic small c", + symbol = "𝑐" + }, + mitchi = { + doc = "mathematical italic small chi", + symbol = "𝜒" + }, + mitd = { + doc = "mathematical italic small d", + symbol = "𝑑" + }, + mitdelta = { + doc = "mathematical italic small delta", + symbol = "𝛿" + }, + mite = { + doc = "mathematical italic small e", + symbol = "𝑒" + }, + mitepsilon = { + doc = "mathematical italic varepsilon symbol", + symbol = "𝜖" + }, + miteta = { + doc = "mathematical italic small eta", + symbol = "𝜂" + }, + mitf = { + doc = "mathematical italic small f", + symbol = "𝑓" + }, + mitg = { + doc = "mathematical italic small g", + symbol = "𝑔" + }, + mitgamma = { + doc = "mathematical italic small gamma", + symbol = "𝛾" + }, + miti = { + doc = "mathematical italic small i", + symbol = "𝑖" + }, + mitiota = { + doc = "mathematical italic small iota", + symbol = "𝜄" + }, + mitj = { + doc = "mathematical italic small j", + symbol = "𝑗" + }, + mitk = { + doc = "mathematical italic small k", + symbol = "𝑘" + }, + mitkappa = { + doc = "mathematical italic small kappa", + symbol = "𝜅" + }, + mitl = { + doc = "mathematical italic small l", + symbol = "𝑙" + }, + mitlambda = { + doc = "mathematical italic small lambda", + symbol = "𝜆" + }, + mitm = { + doc = "mathematical italic small m", + symbol = "𝑚" + }, + mitmu = { + doc = "mathematical italic small mu", + symbol = "𝜇" + }, + mitn = { + doc = "mathematical italic small n", + symbol = "𝑛" + }, + mitnabla = { + doc = "mathematical italic nabla", + symbol = "𝛻" + }, + mitnu = { + doc = "mathematical italic small nu", + symbol = "𝜈" + }, + mito = { + doc = "mathematical italic small o", + symbol = "𝑜" + }, + mitomega = { + doc = "mathematical italic small omega", + symbol = "𝜔" + }, + mitomicron = { + doc = "mathematical italic small omicron", + symbol = "𝜊" + }, + mitp = { + doc = "mathematical italic small p", + symbol = "𝑝" + }, + mitpartial = { + doc = "mathematical italic partial differential", + symbol = "𝜕" + }, + mitphi = { + doc = "mathematical italic phi symbol", + symbol = "𝜙" + }, + mitpi = { + doc = "mathematical italic small pi", + symbol = "𝜋" + }, + mitpsi = { + doc = "mathematical italic small psi", + symbol = "𝜓" + }, + mitq = { + doc = "mathematical italic small q", + symbol = "𝑞" + }, + mitr = { + doc = "mathematical italic small r", + symbol = "𝑟" + }, + mitrho = { + doc = "mathematical italic small rho", + symbol = "𝜌" + }, + mits = { + doc = "mathematical italic small s", + symbol = "𝑠" + }, + mitsansA = { + doc = "mathematical sans-serif italic capital a", + symbol = "𝘈" + }, + mitsansB = { + doc = "mathematical sans-serif italic capital b", + symbol = "𝘉" + }, + mitsansC = { + doc = "mathematical sans-serif italic capital c", + symbol = "𝘊" + }, + mitsansD = { + doc = "mathematical sans-serif italic capital d", + symbol = "𝘋" + }, + mitsansE = { + doc = "mathematical sans-serif italic capital e", + symbol = "𝘌" + }, + mitsansF = { + doc = "mathematical sans-serif italic capital f", + symbol = "𝘍" + }, + mitsansG = { + doc = "mathematical sans-serif italic capital g", + symbol = "𝘎" + }, + mitsansH = { + doc = "mathematical sans-serif italic capital h", + symbol = "𝘏" + }, + mitsansI = { + doc = "mathematical sans-serif italic capital i", + symbol = "𝘐" + }, + mitsansJ = { + doc = "mathematical sans-serif italic capital j", + symbol = "𝘑" + }, + mitsansK = { + doc = "mathematical sans-serif italic capital k", + symbol = "𝘒" + }, + mitsansL = { + doc = "mathematical sans-serif italic capital l", + symbol = "𝘓" + }, + mitsansM = { + doc = "mathematical sans-serif italic capital m", + symbol = "𝘔" + }, + mitsansN = { + doc = "mathematical sans-serif italic capital n", + symbol = "𝘕" + }, + mitsansO = { + doc = "mathematical sans-serif italic capital o", + symbol = "𝘖" + }, + mitsansP = { + doc = "mathematical sans-serif italic capital p", + symbol = "𝘗" + }, + mitsansQ = { + doc = "mathematical sans-serif italic capital q", + symbol = "𝘘" + }, + mitsansR = { + doc = "mathematical sans-serif italic capital r", + symbol = "𝘙" + }, + mitsansS = { + doc = "mathematical sans-serif italic capital s", + symbol = "𝘚" + }, + mitsansT = { + doc = "mathematical sans-serif italic capital t", + symbol = "𝘛" + }, + mitsansU = { + doc = "mathematical sans-serif italic capital u", + symbol = "𝘜" + }, + mitsansV = { + doc = "mathematical sans-serif italic capital v", + symbol = "𝘝" + }, + mitsansW = { + doc = "mathematical sans-serif italic capital w", + symbol = "𝘞" + }, + mitsansX = { + doc = "mathematical sans-serif italic capital x", + symbol = "𝘟" + }, + mitsansY = { + doc = "mathematical sans-serif italic capital y", + symbol = "𝘠" + }, + mitsansZ = { + doc = "mathematical sans-serif italic capital z", + symbol = "𝘡" + }, + mitsansa = { + doc = "mathematical sans-serif italic small a", + symbol = "𝘢" + }, + mitsansb = { + doc = "mathematical sans-serif italic small b", + symbol = "𝘣" + }, + mitsansc = { + doc = "mathematical sans-serif italic small c", + symbol = "𝘤" + }, + mitsansd = { + doc = "mathematical sans-serif italic small d", + symbol = "𝘥" + }, + mitsanse = { + doc = "mathematical sans-serif italic small e", + symbol = "𝘦" + }, + mitsansf = { + doc = "mathematical sans-serif italic small f", + symbol = "𝘧" + }, + mitsansg = { + doc = "mathematical sans-serif italic small g", + symbol = "𝘨" + }, + mitsansh = { + doc = "mathematical sans-serif italic small h", + symbol = "𝘩" + }, + mitsansi = { + doc = "mathematical sans-serif italic small i", + symbol = "𝘪" + }, + mitsansj = { + doc = "mathematical sans-serif italic small j", + symbol = "𝘫" + }, + mitsansk = { + doc = "mathematical sans-serif italic small k", + symbol = "𝘬" + }, + mitsansl = { + doc = "mathematical sans-serif italic small l", + symbol = "𝘭" + }, + mitsansm = { + doc = "mathematical sans-serif italic small m", + symbol = "𝘮" + }, + mitsansn = { + doc = "mathematical sans-serif italic small n", + symbol = "𝘯" + }, + mitsanso = { + doc = "mathematical sans-serif italic small o", + symbol = "𝘰" + }, + mitsansp = { + doc = "mathematical sans-serif italic small p", + symbol = "𝘱" + }, + mitsansq = { + doc = "mathematical sans-serif italic small q", + symbol = "𝘲" + }, + mitsansr = { + doc = "mathematical sans-serif italic small r", + symbol = "𝘳" + }, + mitsanss = { + doc = "mathematical sans-serif italic small s", + symbol = "𝘴" + }, + mitsanst = { + doc = "mathematical sans-serif italic small t", + symbol = "𝘵" + }, + mitsansu = { + doc = "mathematical sans-serif italic small u", + symbol = "𝘶" + }, + mitsansv = { + doc = "mathematical sans-serif italic small v", + symbol = "𝘷" + }, + mitsansw = { + doc = "mathematical sans-serif italic small w", + symbol = "𝘸" + }, + mitsansx = { + doc = "mathematical sans-serif italic small x", + symbol = "𝘹" + }, + mitsansy = { + doc = "mathematical sans-serif italic small y", + symbol = "𝘺" + }, + mitsansz = { + doc = "mathematical sans-serif italic small z", + symbol = "𝘻" + }, + mitsigma = { + doc = "mathematical italic small sigma", + symbol = "𝜎" + }, + mitt = { + doc = "mathematical italic small t", + symbol = "𝑡" + }, + mittau = { + doc = "mathematical italic small tau", + symbol = "𝜏" + }, + mittheta = { + doc = "mathematical italic small theta", + symbol = "𝜃" + }, + mitu = { + doc = "mathematical italic small u", + symbol = "𝑢" + }, + mitupsilon = { + doc = "mathematical italic small upsilon", + symbol = "𝜐" + }, + mitv = { + doc = "mathematical italic small v", + symbol = "𝑣" + }, + mitvarTheta = { + doc = "mathematical italic capital theta symbol", + symbol = "𝛳" + }, + mitvarepsilon = { + doc = "mathematical italic small varepsilon", + symbol = "𝜀" + }, + mitvarkappa = { + doc = "mathematical italic kappa symbol", + symbol = "𝜘" + }, + mitvarphi = { + doc = "mathematical italic small phi", + symbol = "𝜑" + }, + mitvarpi = { + doc = "mathematical italic pi symbol", + symbol = "𝜛" + }, + mitvarrho = { + doc = "mathematical italic rho symbol", + symbol = "𝜚" + }, + mitvarsigma = { + doc = "mathematical italic small final sigma", + symbol = "𝜍" + }, + mitvartheta = { + doc = "mathematical italic theta symbol", + symbol = "𝜗" + }, + mitw = { + doc = "mathematical italic small w", + symbol = "𝑤" + }, + mitx = { + doc = "mathematical italic small x", + symbol = "𝑥" + }, + mitxi = { + doc = "mathematical italic small xi", + symbol = "𝜉" + }, + mity = { + doc = "mathematical italic small y", + symbol = "𝑦" + }, + mitz = { + doc = "mathematical italic small z", + symbol = "𝑧" + }, + mitzeta = { + doc = "mathematical italic small zeta", + symbol = "𝜁" + }, + mlcp = { + doc = "transversal intersection", + symbol = "⫛" + }, + models = { + doc = "models (vertical, short double dash)", + symbol = "⊧" + }, + modtwosum = { + doc = "modulo two sum", + symbol = "⨊" + }, + mp = { + doc = "minus-or-plus sign", + symbol = "∓" + }, + msansA = { + doc = "mathematical sans-serif capital a", + symbol = "𝖠" + }, + msansB = { + doc = "mathematical sans-serif capital b", + symbol = "𝖡" + }, + msansC = { + doc = "mathematical sans-serif capital c", + symbol = "𝖢" + }, + msansD = { + doc = "mathematical sans-serif capital d", + symbol = "𝖣" + }, + msansE = { + doc = "mathematical sans-serif capital e", + symbol = "𝖤" + }, + msansF = { + doc = "mathematical sans-serif capital f", + symbol = "𝖥" + }, + msansG = { + doc = "mathematical sans-serif capital g", + symbol = "𝖦" + }, + msansH = { + doc = "mathematical sans-serif capital h", + symbol = "𝖧" + }, + msansI = { + doc = "mathematical sans-serif capital i", + symbol = "𝖨" + }, + msansJ = { + doc = "mathematical sans-serif capital j", + symbol = "𝖩" + }, + msansK = { + doc = "mathematical sans-serif capital k", + symbol = "𝖪" + }, + msansL = { + doc = "mathematical sans-serif capital l", + symbol = "𝖫" + }, + msansM = { + doc = "mathematical sans-serif capital m", + symbol = "𝖬" + }, + msansN = { + doc = "mathematical sans-serif capital n", + symbol = "𝖭" + }, + msansO = { + doc = "mathematical sans-serif capital o", + symbol = "𝖮" + }, + msansP = { + doc = "mathematical sans-serif capital p", + symbol = "𝖯" + }, + msansQ = { + doc = "mathematical sans-serif capital q", + symbol = "𝖰" + }, + msansR = { + doc = "mathematical sans-serif capital r", + symbol = "𝖱" + }, + msansS = { + doc = "mathematical sans-serif capital s", + symbol = "𝖲" + }, + msansT = { + doc = "mathematical sans-serif capital t", + symbol = "𝖳" + }, + msansU = { + doc = "mathematical sans-serif capital u", + symbol = "𝖴" + }, + msansV = { + doc = "mathematical sans-serif capital v", + symbol = "𝖵" + }, + msansW = { + doc = "mathematical sans-serif capital w", + symbol = "𝖶" + }, + msansX = { + doc = "mathematical sans-serif capital x", + symbol = "𝖷" + }, + msansY = { + doc = "mathematical sans-serif capital y", + symbol = "𝖸" + }, + msansZ = { + doc = "mathematical sans-serif capital z", + symbol = "𝖹" + }, + msansa = { + doc = "mathematical sans-serif small a", + symbol = "𝖺" + }, + msansb = { + doc = "mathematical sans-serif small b", + symbol = "𝖻" + }, + msansc = { + doc = "mathematical sans-serif small c", + symbol = "𝖼" + }, + msansd = { + doc = "mathematical sans-serif small d", + symbol = "𝖽" + }, + msanse = { + doc = "mathematical sans-serif small e", + symbol = "𝖾" + }, + msanseight = { + doc = "mathematical sans-serif digit 8", + symbol = "𝟪" + }, + msansf = { + doc = "mathematical sans-serif small f", + symbol = "𝖿" + }, + msansfive = { + doc = "mathematical sans-serif digit 5", + symbol = "𝟧" + }, + msansfour = { + doc = "mathematical sans-serif digit 4", + symbol = "𝟦" + }, + msansg = { + doc = "mathematical sans-serif small g", + symbol = "𝗀" + }, + msansh = { + doc = "mathematical sans-serif small h", + symbol = "𝗁" + }, + msansi = { + doc = "mathematical sans-serif small i", + symbol = "𝗂" + }, + msansj = { + doc = "mathematical sans-serif small j", + symbol = "𝗃" + }, + msansk = { + doc = "mathematical sans-serif small k", + symbol = "𝗄" + }, + msansl = { + doc = "mathematical sans-serif small l", + symbol = "𝗅" + }, + msansm = { + doc = "mathematical sans-serif small m", + symbol = "𝗆" + }, + msansn = { + doc = "mathematical sans-serif small n", + symbol = "𝗇" + }, + msansnine = { + doc = "mathematical sans-serif digit 9", + symbol = "𝟫" + }, + msanso = { + doc = "mathematical sans-serif small o", + symbol = "𝗈" + }, + msansone = { + doc = "mathematical sans-serif digit 1", + symbol = "𝟣" + }, + msansp = { + doc = "mathematical sans-serif small p", + symbol = "𝗉" + }, + msansq = { + doc = "mathematical sans-serif small q", + symbol = "𝗊" + }, + msansr = { + doc = "mathematical sans-serif small r", + symbol = "𝗋" + }, + msanss = { + doc = "mathematical sans-serif small s", + symbol = "𝗌" + }, + msansseven = { + doc = "mathematical sans-serif digit 7", + symbol = "𝟩" + }, + msanssix = { + doc = "mathematical sans-serif digit 6", + symbol = "𝟨" + }, + msanst = { + doc = "mathematical sans-serif small t", + symbol = "𝗍" + }, + msansthree = { + doc = "mathematical sans-serif digit 3", + symbol = "𝟥" + }, + msanstwo = { + doc = "mathematical sans-serif digit 2", + symbol = "𝟤" + }, + msansu = { + doc = "mathematical sans-serif small u", + symbol = "𝗎" + }, + msansv = { + doc = "mathematical sans-serif small v", + symbol = "𝗏" + }, + msansw = { + doc = "mathematical sans-serif small w", + symbol = "𝗐" + }, + msansx = { + doc = "mathematical sans-serif small x", + symbol = "𝗑" + }, + msansy = { + doc = "mathematical sans-serif small y", + symbol = "𝗒" + }, + msansz = { + doc = "mathematical sans-serif small z", + symbol = "𝗓" + }, + msanszero = { + doc = "mathematical sans-serif digit 0", + symbol = "𝟢" + }, + mscrA = { + doc = "mathematical script capital a", + symbol = "𝒜" + }, + mscrB = { + doc = "bernoulli function (script capital b)", + symbol = "ℬ" + }, + mscrC = { + doc = "mathematical script capital c", + symbol = "𝒞" + }, + mscrD = { + doc = "mathematical script capital d", + symbol = "𝒟" + }, + mscrE = { + doc = "/scr e, script letter e", + symbol = "ℰ" + }, + mscrF = { + doc = "/scr f, script letter f", + symbol = "ℱ" + }, + mscrG = { + doc = "mathematical script capital g", + symbol = "𝒢" + }, + mscrH = { + doc = "hamiltonian (script capital h)", + symbol = "ℋ" + }, + mscrI = { + doc = "/scr i, script letter i", + symbol = "ℐ" + }, + mscrJ = { + doc = "mathematical script capital j", + symbol = "𝒥" + }, + mscrK = { + doc = "mathematical script capital k", + symbol = "𝒦" + }, + mscrL = { + doc = "lagrangian (script capital l)", + symbol = "ℒ" + }, + mscrM = { + doc = "physics m-matrix (script capital m)", + symbol = "ℳ" + }, + mscrN = { + doc = "mathematical script capital n", + symbol = "𝒩" + }, + mscrO = { + doc = "mathematical script capital o", + symbol = "𝒪" + }, + mscrP = { + doc = "mathematical script capital p", + symbol = "𝒫" + }, + mscrQ = { + doc = "mathematical script capital q", + symbol = "𝒬" + }, + mscrR = { + doc = "/scr r, script letter r", + symbol = "ℛ" + }, + mscrS = { + doc = "mathematical script capital s", + symbol = "𝒮" + }, + mscrT = { + doc = "mathematical script capital t", + symbol = "𝒯" + }, + mscrU = { + doc = "mathematical script capital u", + symbol = "𝒰" + }, + mscrV = { + doc = "mathematical script capital v", + symbol = "𝒱" + }, + mscrW = { + doc = "mathematical script capital w", + symbol = "𝒲" + }, + mscrX = { + doc = "mathematical script capital x", + symbol = "𝒳" + }, + mscrY = { + doc = "mathematical script capital y", + symbol = "𝒴" + }, + mscrZ = { + doc = "mathematical script capital z", + symbol = "𝒵" + }, + mscra = { + doc = "mathematical script small a", + symbol = "𝒶" + }, + mscrb = { + doc = "mathematical script small b", + symbol = "𝒷" + }, + mscrc = { + doc = "mathematical script small c", + symbol = "𝒸" + }, + mscrd = { + doc = "mathematical script small d", + symbol = "𝒹" + }, + mscre = { + doc = "/scr e, script letter e", + symbol = "ℯ" + }, + mscrf = { + doc = "mathematical script small f", + symbol = "𝒻" + }, + mscrg = { + doc = "/scr g, script letter g", + symbol = "ℊ" + }, + mscrh = { + doc = "mathematical script small h", + symbol = "𝒽" + }, + mscri = { + doc = "mathematical script small i", + symbol = "𝒾" + }, + mscrj = { + doc = "mathematical script small j", + symbol = "𝒿" + }, + mscrk = { + doc = "mathematical script small k", + symbol = "𝓀" + }, + mscrl = { + doc = "mathematical script small l", + symbol = "𝓁" + }, + mscrm = { + doc = "mathematical script small m", + symbol = "𝓂" + }, + mscrn = { + doc = "mathematical script small n", + symbol = "𝓃" + }, + mscro = { + doc = "order of (script small o)", + symbol = "ℴ" + }, + mscrp = { + doc = "mathematical script small p", + symbol = "𝓅" + }, + mscrq = { + doc = "mathematical script small q", + symbol = "𝓆" + }, + mscrr = { + doc = "mathematical script small r", + symbol = "𝓇" + }, + mscrs = { + doc = "mathematical script small s", + symbol = "𝓈" + }, + mscrt = { + doc = "mathematical script small t", + symbol = "𝓉" + }, + mscru = { + doc = "mathematical script small u", + symbol = "𝓊" + }, + mscrv = { + doc = "mathematical script small v", + symbol = "𝓋" + }, + mscrw = { + doc = "mathematical script small w", + symbol = "𝓌" + }, + mscrx = { + doc = "mathematical script small x", + symbol = "𝓍" + }, + mscry = { + doc = "mathematical script small y", + symbol = "𝓎" + }, + mscrz = { + doc = "mathematical script small z", + symbol = "𝓏" + }, + mttA = { + doc = "mathematical monospace capital a", + symbol = "𝙰" + }, + mttB = { + doc = "mathematical monospace capital b", + symbol = "𝙱" + }, + mttC = { + doc = "mathematical monospace capital c", + symbol = "𝙲" + }, + mttD = { + doc = "mathematical monospace capital d", + symbol = "𝙳" + }, + mttE = { + doc = "mathematical monospace capital e", + symbol = "𝙴" + }, + mttF = { + doc = "mathematical monospace capital f", + symbol = "𝙵" + }, + mttG = { + doc = "mathematical monospace capital g", + symbol = "𝙶" + }, + mttH = { + doc = "mathematical monospace capital h", + symbol = "𝙷" + }, + mttI = { + doc = "mathematical monospace capital i", + symbol = "𝙸" + }, + mttJ = { + doc = "mathematical monospace capital j", + symbol = "𝙹" + }, + mttK = { + doc = "mathematical monospace capital k", + symbol = "𝙺" + }, + mttL = { + doc = "mathematical monospace capital l", + symbol = "𝙻" + }, + mttM = { + doc = "mathematical monospace capital m", + symbol = "𝙼" + }, + mttN = { + doc = "mathematical monospace capital n", + symbol = "𝙽" + }, + mttO = { + doc = "mathematical monospace capital o", + symbol = "𝙾" + }, + mttP = { + doc = "mathematical monospace capital p", + symbol = "𝙿" + }, + mttQ = { + doc = "mathematical monospace capital q", + symbol = "𝚀" + }, + mttR = { + doc = "mathematical monospace capital r", + symbol = "𝚁" + }, + mttS = { + doc = "mathematical monospace capital s", + symbol = "𝚂" + }, + mttT = { + doc = "mathematical monospace capital t", + symbol = "𝚃" + }, + mttU = { + doc = "mathematical monospace capital u", + symbol = "𝚄" + }, + mttV = { + doc = "mathematical monospace capital v", + symbol = "𝚅" + }, + mttW = { + doc = "mathematical monospace capital w", + symbol = "𝚆" + }, + mttX = { + doc = "mathematical monospace capital x", + symbol = "𝚇" + }, + mttY = { + doc = "mathematical monospace capital y", + symbol = "𝚈" + }, + mttZ = { + doc = "mathematical monospace capital z", + symbol = "𝚉" + }, + mtta = { + doc = "mathematical monospace small a", + symbol = "𝚊" + }, + mttb = { + doc = "mathematical monospace small b", + symbol = "𝚋" + }, + mttc = { + doc = "mathematical monospace small c", + symbol = "𝚌" + }, + mttd = { + doc = "mathematical monospace small d", + symbol = "𝚍" + }, + mtte = { + doc = "mathematical monospace small e", + symbol = "𝚎" + }, + mtteight = { + doc = "mathematical monospace digit 8", + symbol = "𝟾" + }, + mttf = { + doc = "mathematical monospace small f", + symbol = "𝚏" + }, + mttfive = { + doc = "mathematical monospace digit 5", + symbol = "𝟻" + }, + mttfour = { + doc = "mathematical monospace digit 4", + symbol = "𝟺" + }, + mttg = { + doc = "mathematical monospace small g", + symbol = "𝚐" + }, + mtth = { + doc = "mathematical monospace small h", + symbol = "𝚑" + }, + mtti = { + doc = "mathematical monospace small i", + symbol = "𝚒" + }, + mttj = { + doc = "mathematical monospace small j", + symbol = "𝚓" + }, + mttk = { + doc = "mathematical monospace small k", + symbol = "𝚔" + }, + mttl = { + doc = "mathematical monospace small l", + symbol = "𝚕" + }, + mttm = { + doc = "mathematical monospace small m", + symbol = "𝚖" + }, + mttn = { + doc = "mathematical monospace small n", + symbol = "𝚗" + }, + mttnine = { + doc = "mathematical monospace digit 9", + symbol = "𝟿" + }, + mtto = { + doc = "mathematical monospace small o", + symbol = "𝚘" + }, + mttone = { + doc = "mathematical monospace digit 1", + symbol = "𝟷" + }, + mttp = { + doc = "mathematical monospace small p", + symbol = "𝚙" + }, + mttq = { + doc = "mathematical monospace small q", + symbol = "𝚚" + }, + mttr = { + doc = "mathematical monospace small r", + symbol = "𝚛" + }, + mtts = { + doc = "mathematical monospace small s", + symbol = "𝚜" + }, + mttseven = { + doc = "mathematical monospace digit 7", + symbol = "𝟽" + }, + mttsix = { + doc = "mathematical monospace digit 6", + symbol = "𝟼" + }, + mttt = { + doc = "mathematical monospace small t", + symbol = "𝚝" + }, + mttthree = { + doc = "mathematical monospace digit 3", + symbol = "𝟹" + }, + mtttwo = { + doc = "mathematical monospace digit 2", + symbol = "𝟸" + }, + mttu = { + doc = "mathematical monospace small u", + symbol = "𝚞" + }, + mttv = { + doc = "mathematical monospace small v", + symbol = "𝚟" + }, + mttw = { + doc = "mathematical monospace small w", + symbol = "𝚠" + }, + mttx = { + doc = "mathematical monospace small x", + symbol = "𝚡" + }, + mtty = { + doc = "mathematical monospace small y", + symbol = "𝚢" + }, + mttz = { + doc = "mathematical monospace small z", + symbol = "𝚣" + }, + mttzero = { + doc = "mathematical monospace digit 0", + symbol = "𝟶" + }, + mu = { + doc = "small mu, greek", + symbol = "μ" + }, + multimap = { + doc = "/multimap a:", + symbol = "⊸" + }, + multimapinv = { + doc = "left multimap", + symbol = "⟜" + }, + mupAlpha = { + doc = "capital alpha, greek", + symbol = "Α" + }, + mupBeta = { + doc = "capital beta, greek", + symbol = "Β" + }, + mupChi = { + doc = "capital chi, greek", + symbol = "Χ" + }, + mupDelta = { + doc = "capital delta, greek", + symbol = "Δ" + }, + mupEpsilon = { + doc = "capital epsilon, greek", + symbol = "Ε" + }, + mupEta = { + doc = "capital eta, greek", + symbol = "Η" + }, + mupGamma = { + doc = "capital gamma, greek", + symbol = "Γ" + }, + mupIota = { + doc = "capital iota, greek", + symbol = "Ι" + }, + mupKappa = { + doc = "capital kappa, greek", + symbol = "Κ" + }, + mupLambda = { + doc = "capital lambda, greek", + symbol = "Λ" + }, + mupMu = { + doc = "capital mu, greek", + symbol = "Μ" + }, + mupNu = { + doc = "capital nu, greek", + symbol = "Ν" + }, + mupOmega = { + doc = "capital omega, greek", + symbol = "Ω" + }, + mupOmicron = { + doc = "capital omicron, greek", + symbol = "Ο" + }, + mupPhi = { + doc = "capital phi, greek", + symbol = "Φ" + }, + mupPi = { + doc = "capital pi, greek", + symbol = "Π" + }, + mupPsi = { + doc = "capital psi, greek", + symbol = "Ψ" + }, + mupRho = { + doc = "capital rho, greek", + symbol = "Ρ" + }, + mupSigma = { + doc = "capital sigma, greek", + symbol = "Σ" + }, + mupTau = { + doc = "capital tau, greek", + symbol = "Τ" + }, + mupTheta = { + doc = "capital theta, greek", + symbol = "Θ" + }, + mupUpsilon = { + doc = "capital upsilon, greek", + symbol = "Υ" + }, + mupXi = { + doc = "capital xi, greek", + symbol = "Ξ" + }, + mupZeta = { + doc = "capital zeta, greek", + symbol = "Ζ" + }, + mupalpha = { + doc = "small alpha, greek", + symbol = "α" + }, + mupbeta = { + doc = "small beta, greek", + symbol = "β" + }, + mupchi = { + doc = "small chi, greek", + symbol = "χ" + }, + mupdelta = { + doc = "small delta, greek", + symbol = "δ" + }, + mupepsilon = { + doc = "greek lunate varepsilon symbol", + symbol = "ϵ" + }, + mupeta = { + doc = "small eta, greek", + symbol = "η" + }, + mupgamma = { + doc = "small gamma, greek", + symbol = "γ" + }, + mupiota = { + doc = "small iota, greek", + symbol = "ι" + }, + mupkappa = { + doc = "small kappa, greek", + symbol = "κ" + }, + muplambda = { + doc = "small lambda, greek", + symbol = "λ" + }, + mupmu = { + doc = "small mu, greek", + symbol = "μ" + }, + mupnu = { + doc = "small nu, greek", + symbol = "ν" + }, + mupomega = { + doc = "small omega, greek", + symbol = "ω" + }, + mupomicron = { + doc = "small omicron, greek", + symbol = "ο" + }, + mupphi = { + doc = "/straightphi - small phi, greek", + symbol = "ϕ" + }, + muppi = { + doc = "small pi, greek", + symbol = "π" + }, + muppsi = { + doc = "small psi, greek", + symbol = "ψ" + }, + muprho = { + doc = "small rho, greek", + symbol = "ρ" + }, + mupsigma = { + doc = "small sigma, greek", + symbol = "σ" + }, + muptau = { + doc = "small tau, greek", + symbol = "τ" + }, + muptheta = { + doc = "straight theta, small theta, greek", + symbol = "θ" + }, + mupupsilon = { + doc = "small upsilon, greek", + symbol = "υ" + }, + mupvarTheta = { + doc = "greek capital theta symbol", + symbol = "ϴ" + }, + mupvarepsilon = { + doc = "rounded small varepsilon, greek", + symbol = "ε" + }, + mupvarkappa = { + doc = "rounded small kappa, greek", + symbol = "ϰ" + }, + mupvarphi = { + doc = "curly or open small phi, greek", + symbol = "φ" + }, + mupvarpi = { + doc = "rounded small pi (pomega), greek", + symbol = "ϖ" + }, + mupvarrho = { + doc = "rounded small rho, greek", + symbol = "ϱ" + }, + mupvarsigma = { + doc = "terminal sigma, greek", + symbol = "ς" + }, + mupvartheta = { + doc = "/vartheta - curly or open theta", + symbol = "ϑ" + }, + mupxi = { + doc = "small xi, greek", + symbol = "ξ" + }, + mupzeta = { + doc = "small zeta, greek", + symbol = "ζ" + }, + nHdownarrow = { + doc = "downwards arrow with double stroke", + symbol = "⇟" + }, + nHuparrow = { + doc = "upwards arrow with double stroke", + symbol = "⇞" + }, + nLeftarrow = { + doc = "not implied by", + symbol = "⇍" + }, + nLeftrightarrow = { + doc = "not left and right double arrows", + symbol = "⇎" + }, + nRightarrow = { + doc = "not implies", + symbol = "⇏" + }, + nVDash = { + doc = "not double vert, double dash", + symbol = "⊯" + }, + nVdash = { + doc = "not double vertical, dash", + symbol = "⊮" + }, + nVleftarrow = { + doc = "leftwards arrow with double vertical stroke", + symbol = "⇺" + }, + nVleftarrowtail = { + doc = "leftwards arrow with tail with double vertical stroke", + symbol = "⬺" + }, + nVleftrightarrow = { + doc = "left right arrow with double vertical stroke", + symbol = "⇼" + }, + nVrightarrow = { + doc = "rightwards arrow with double vertical stroke", + symbol = "⇻" + }, + nVrightarrowtail = { + doc = "rightwards arrow with tail with double vertical stroke", + symbol = "⤕" + }, + nVtwoheadleftarrow = { + doc = "leftwards two-headed arrow with double vertical stroke", + symbol = "⬵" + }, + nVtwoheadleftarrowtail = { + doc = "leftwards two-headed arrow with tail with double vertical stroke", + symbol = "⬽" + }, + nVtwoheadrightarrow = { + doc = "rightwards two-headed arrow with double vertical stroke", + symbol = "⤁" + }, + nVtwoheadrightarrowtail = { + doc = "rightwards two-headed arrow with tail with double vertical stroke", + symbol = "⤘" + }, + nabla = { + doc = "nabla, del, hamilton operator", + symbol = "∇" + }, + napprox = { + doc = "not approximate", + symbol = "≉" + }, + nasymp = { + doc = "not asymptotically equal to", + symbol = "≭" + }, + natural = { + doc = "music natural", + symbol = "♮" + }, + ncong = { + doc = "not congruent with", + symbol = "≇" + }, + ne = { + doc = "/ne /neq r: not equal", + symbol = "≠" + }, + nearrow = { + doc = "ne pointing arrow", + symbol = "↗" + }, + neg = { + doc = "/neg /lnot not sign", + symbol = "¬" + }, + neovnwarrow = { + doc = "north east arrow crossing north west arrow", + symbol = "⤱" + }, + neovsearrow = { + doc = "north east arrow crossing south east arrow", + symbol = "⤮" + }, + nequiv = { + doc = "not identical with", + symbol = "≢" + }, + neswarrow = { + doc = "north east and south west arrow", + symbol = "⤢" + }, + neuter = { + doc = "neuter", + symbol = "⚲" + }, + nexists = { + doc = "negated exists", + symbol = "∄" + }, + ngeq = { + doc = "not greater-than-or-equal", + symbol = "≱" + }, + ngtr = { + doc = "not greater-than", + symbol = "≯" + }, + ngtrless = { + doc = "not greater, less", + symbol = "≹" + }, + ngtrsim = { + doc = "not greater, similar", + symbol = "≵" + }, + nhVvert = { + doc = "triple vertical bar with horizontal stroke", + symbol = "⫵" + }, + nhpar = { + doc = "parallel with horizontal stroke", + symbol = "⫲" + }, + ni = { + doc = "contains, variant", + symbol = "∋" + }, + niobar = { + doc = "small contains with overbar", + symbol = "⋾" + }, + nis = { + doc = "small contains with vertical bar at end of horizontal stroke", + symbol = "⋼" + }, + nisd = { + doc = "contains with long horizontal stroke", + symbol = "⋺" + }, + nleftarrow = { + doc = "not left arrow", + symbol = "↚" + }, + nleftrightarrow = { + doc = "not left and right arrow", + symbol = "↮" + }, + nleq = { + doc = "not less-than-or-equal", + symbol = "≰" + }, + nless = { + doc = "not less-than", + symbol = "≮" + }, + nlessgtr = { + doc = "not less, greater", + symbol = "≸" + }, + nlesssim = { + doc = "not less, similar", + symbol = "≴" + }, + nmid = { + doc = "negated mid", + symbol = "∤" + }, + nni = { + doc = "negated contains, variant", + symbol = "∌" + }, + notaccent = { + doc = "combining long solidus overlay", + symbol = "◌̸" + }, + notin = { + doc = "negated set membership", + symbol = "∉" + }, + nparallel = { + doc = "not parallel", + symbol = "∦" + }, + npolint = { + doc = "line integration not including the pole", + symbol = "⨔" + }, + nprec = { + doc = "not precedes", + symbol = "⊀" + }, + npreccurlyeq = { + doc = "not precedes, curly equals", + symbol = "⋠" + }, + nrightarrow = { + doc = "not right arrow", + symbol = "↛" + }, + nsim = { + doc = "not similar", + symbol = "≁" + }, + nsime = { + doc = "not similar, equals", + symbol = "≄" + }, + nsimeq = { + doc = "not similar, equals (alias)", + symbol = "≄" + }, + nsqsubseteq = { + doc = "not, square subset, equals", + symbol = "⋢" + }, + nsqsupseteq = { + doc = "not, square superset, equals", + symbol = "⋣" + }, + nsubset = { + doc = "not subset, variant [slash negation]", + symbol = "⊄" + }, + nsubseteq = { + doc = "not subset, equals", + symbol = "⊈" + }, + nsucc = { + doc = "not succeeds", + symbol = "⊁" + }, + nsucccurlyeq = { + doc = "not succeeds, curly equals", + symbol = "⋡" + }, + nsupset = { + doc = "not superset, variant [slash negation]", + symbol = "⊅" + }, + nsupseteq = { + doc = "not superset, equals", + symbol = "⊉" + }, + ntrianglelefteq = { + doc = "not left triangle, equals", + symbol = "⋬" + }, + ntrianglerighteq = { + doc = "not right triangle, equals", + symbol = "⋭" + }, + nu = { + doc = "small nu, greek", + symbol = "ν" + }, + nvDash = { + doc = "not vertical, double dash", + symbol = "⊭" + }, + nvLeftarrow = { + doc = "leftwards double arrow with vertical stroke", + symbol = "⤂" + }, + nvLeftrightarrow = { + doc = "left right double arrow with vertical stroke", + symbol = "⤄" + }, + nvRightarrow = { + doc = "rightwards double arrow with vertical stroke", + symbol = "⤃" + }, + nvartriangleleft = { + doc = "not left triangle", + symbol = "⋪" + }, + nvartriangleright = { + doc = "not right triangle", + symbol = "⋫" + }, + nvdash = { + doc = "not vertical, dash", + symbol = "⊬" + }, + nvinfty = { + doc = "infinity negated with vertical bar", + symbol = "⧞" + }, + nvleftarrow = { + doc = "leftwards arrow with vertical stroke", + symbol = "⇷" + }, + nvleftarrowtail = { + doc = "leftwards arrow with tail with vertical stroke", + symbol = "⬹" + }, + nvleftrightarrow = { + doc = "left right arrow with vertical stroke", + symbol = "⇹" + }, + nvrightarrow = { + doc = "rightwards arrow with vertical stroke", + symbol = "⇸" + }, + nvrightarrowtail = { + doc = "rightwards arrow with tail with vertical stroke", + symbol = "⤔" + }, + nvtwoheadleftarrow = { + doc = "leftwards two-headed arrow with vertical stroke", + symbol = "⬴" + }, + nvtwoheadleftarrowtail = { + doc = "leftwards two-headed arrow with tail with vertical stroke", + symbol = "⬼" + }, + nvtwoheadrightarrow = { + doc = "rightwards two-headed arrow with vertical stroke", + symbol = "⤀" + }, + nvtwoheadrightarrowtail = { + doc = "rightwards two-headed arrow with tail with vertical stroke", + symbol = "⤗" + }, + nwarrow = { + doc = "nw pointing arrow", + symbol = "↖" + }, + nwovnearrow = { + doc = "north west arrow crossing north east arrow", + symbol = "⤲" + }, + nwsearrow = { + doc = "north west and south east arrow", + symbol = "⤡" + }, + obar = { + doc = "circle with vertical bar", + symbol = "⌽" + }, + obot = { + doc = "circle divided by horizontal bar and top half divided by vertical bar", + symbol = "⦺" + }, + obrbrak = { + doc = "top tortoise shell bracket (mathematical use)", + symbol = "⏠" + }, + obslash = { + doc = "circled reverse solidus", + symbol = "⦸" + }, + ocirc = { + doc = "ring", + symbol = "◌̊" + }, + ocommatopright = { + doc = "combining comma above right", + symbol = "◌̕" + }, + odiv = { + doc = "circled division sign", + symbol = "⨸" + }, + odot = { + doc = "middle dot in circle", + symbol = "⊙" + }, + odotslashdot = { + doc = "circled anticlockwise-rotated division sign", + symbol = "⦼" + }, + ogreaterthan = { + doc = "circled greater-than", + symbol = "⧁" + }, + oiiint = { + doc = "triple contour integral operator", + symbol = "∰" + }, + oiint = { + doc = "double contour integral operator", + symbol = "∯" + }, + oint = { + doc = "contour integral operator", + symbol = "∮" + }, + ointctrclockwise = { + doc = "contour integral, anticlockwise", + symbol = "∳" + }, + olcross = { + doc = "circle with superimposed x", + symbol = "⦻" + }, + olessthan = { + doc = "circled less-than", + symbol = "⧀" + }, + omega = { + doc = "small omega, greek", + symbol = "ω" + }, + omicron = { + doc = "small omicron, greek", + symbol = "ο" + }, + ominus = { + doc = "minus sign in circle", + symbol = "⊖" + }, + operp = { + doc = "circled perpendicular", + symbol = "⦹" + }, + oplus = { + doc = "plus sign in circle", + symbol = "⊕" + }, + opluslhrim = { + doc = "plus sign in left half circle", + symbol = "⨭" + }, + oplusrhrim = { + doc = "plus sign in right half circle", + symbol = "⨮" + }, + origof = { + doc = "original of", + symbol = "⊶" + }, + oslash = { + doc = "solidus in circle", + symbol = "⊘" + }, + otimes = { + doc = "multiply sign in circle", + symbol = "⊗" + }, + otimeshat = { + doc = "circled multiplication sign with circumflex accent", + symbol = "⨶" + }, + otimeslhrim = { + doc = "multiplication sign in left half circle", + symbol = "⨴" + }, + otimesrhrim = { + doc = "multiplication sign in right half circle", + symbol = "⨵" + }, + oturnedcomma = { + doc = "combining turned comma above", + symbol = "◌̒" + }, + overbar = { + doc = "overbar embellishment", + symbol = "◌̅" + }, + overbrace = { + doc = "top curly bracket (mathematical use)", + symbol = "⏞" + }, + overbracket = { + doc = "top square bracket", + symbol = "⎴" + }, + overleftarrow = { + doc = "combining left arrow above", + symbol = "◌⃖" + }, + overleftharpoon = { + doc = "combining left harpoon above", + symbol = "◌⃐" + }, + overleftrightarrow = { + doc = "combining left right arrow above", + symbol = "◌⃡" + }, + overparen = { + doc = "top parenthesis (mathematical use)", + symbol = "⏜" + }, + overrightarrow = { + doc = "combining left arrow above", + symbol = "◌⃗" + }, + overrightharpoon = { + doc = "combining right harpoon above", + symbol = "◌⃑" + }, + ovhook = { + doc = "combining hook above", + symbol = "◌̉" + }, + parallel = { + doc = "parallel", + symbol = "∥" + }, + parallelogram = { + doc = "parallelogram, open", + symbol = "▱" + }, + parallelogramblack = { + doc = "black parallelogram", + symbol = "▰" + }, + parsim = { + doc = "parallel with tilde operator", + symbol = "⫳" + }, + partial = { + doc = "partial differential", + symbol = "∂" + }, + partialmeetcontraction = { + doc = "double less-than with underbar", + symbol = "⪣" + }, + pentagon = { + doc = "white pentagon", + symbol = "⬠" + }, + pentagonblack = { + doc = "black pentagon", + symbol = "⬟" + }, + perp = { + doc = "perpendicular", + symbol = "⟂" + }, + perps = { + doc = "perpendicular with s", + symbol = "⫡" + }, + phi = { + doc = "/straightphi - small phi, greek", + symbol = "ϕ" + }, + pi = { + doc = "small pi, greek", + symbol = "π" + }, + pitchfork = { + doc = "pitchfork", + symbol = "⋔" + }, + plusdot = { + doc = "plus sign with dot below", + symbol = "⨥" + }, + pluseqq = { + doc = "plus sign above equals sign", + symbol = "⩲" + }, + plushat = { + doc = "plus sign with circumflex accent above", + symbol = "⨣" + }, + plussim = { + doc = "plus sign with tilde below", + symbol = "⨦" + }, + plussubtwo = { + doc = "plus sign with subscript two", + symbol = "⨧" + }, + plustrif = { + doc = "plus sign with black triangle", + symbol = "⨨" + }, + pm = { + doc = "plus-or-minus sign", + symbol = "±" + }, + pointint = { + doc = "integral around a point operator", + symbol = "⨕" + }, + postalmark = { + doc = "postal mark", + symbol = "〒" + }, + prec = { + doc = "precedes", + symbol = "≺" + }, + precapprox = { + doc = "precedes above almost equal to", + symbol = "⪷" + }, + preccurlyeq = { + doc = "precedes, curly equals", + symbol = "≼" + }, + preceq = { + doc = "precedes above single-line equals sign", + symbol = "⪯" + }, + preceqq = { + doc = "precedes above equals sign", + symbol = "⪳" + }, + precnapprox = { + doc = "precedes above not almost equal to", + symbol = "⪹" + }, + precneq = { + doc = "precedes above single-line not equal to", + symbol = "⪱" + }, + precneqq = { + doc = "precedes above not equal to", + symbol = "⪵" + }, + precnsim = { + doc = "precedes, not similar", + symbol = "⋨" + }, + precsim = { + doc = "precedes, similar", + symbol = "≾" + }, + prime = { + doc = "prime or minute, not superscripted", + symbol = "′" + }, + prod = { + doc = "product operator", + symbol = "∏" + }, + profline = { + doc = "profile of a line", + symbol = "⌒" + }, + profsurf = { + doc = "profile of a surface", + symbol = "⌓" + }, + propto = { + doc = "is proportional to", + symbol = "∝" + }, + prurel = { + doc = "element precedes under relation", + symbol = "⊰" + }, + psi = { + doc = "small psi, greek", + symbol = "ψ" + }, + pullback = { + doc = "lower right corner with dot", + symbol = "⟓" + }, + pushout = { + doc = "upper left corner with dot", + symbol = "⟔" + }, + qprime = { + doc = "quadruple prime, not superscripted", + symbol = "⁗" + }, + quarternote = { + doc = "music note (sung text sign)", + symbol = "♩" + }, + questeq = { + doc = "equal with questionmark", + symbol = "≟" + }, + rAngle = { + doc = "mathematical right double angle bracket", + symbol = "⟫" + }, + rBrace = { + doc = "right white curly bracket", + symbol = "⦄" + }, + rBrack = { + doc = "mathematical right white square bracket", + symbol = "⟧" + }, + rParen = { + doc = "right white parenthesis", + symbol = "⦆" + }, + rangle = { + doc = "mathematical right angle bracket", + symbol = "⟩" + }, + rangledot = { + doc = "right angle bracket with dot", + symbol = "⦒" + }, + rangledownzigzagarrow = { + doc = "right angle with downwards zigzag arrow", + symbol = "⍼" + }, + rbag = { + doc = "right s-shaped bag delimiter", + symbol = "⟆" + }, + rblkbrbrak = { + doc = "right black tortoise shell bracket", + symbol = "⦘" + }, + rbrace = { + doc = "right curly bracket", + symbol = "}" + }, + rbracelend = { + doc = "right curly bracket lower hook", + symbol = "⎭" + }, + rbracemid = { + doc = "right curly bracket middle piece", + symbol = "⎬" + }, + rbraceuend = { + doc = "right curly bracket upper hook", + symbol = "⎫" + }, + rbrack = { + doc = "right square bracket", + symbol = "]" + }, + rbrackextender = { + doc = "right square bracket extension", + symbol = "⎥" + }, + rbracklend = { + doc = "right square bracket lower corner", + symbol = "⎦" + }, + rbracklrtick = { + doc = "right square bracket with tick in bottom corner", + symbol = "⦎" + }, + rbrackubar = { + doc = "right square bracket with underbar", + symbol = "⦌" + }, + rbrackuend = { + doc = "right square bracket upper corner", + symbol = "⎤" + }, + rbrackurtick = { + doc = "right square bracket with tick in top corner", + symbol = "⦐" + }, + rbrbrak = { + doc = "light right tortoise shell bracket ornament", + symbol = "❳" + }, + rceil = { + doc = "right ceiling", + symbol = "⌉" + }, + rcurvyangle = { + doc = "right pointing curved angle bracket", + symbol = "⧽" + }, + rdiagovfdiag = { + doc = "rising diagonal crossing falling diagonal", + symbol = "⤫" + }, + rdiagovsearrow = { + doc = "rising diagonal crossing south east arrow", + symbol = "⤰" + }, + revangle = { + doc = "reversed angle", + symbol = "⦣" + }, + revangleubar = { + doc = "reversed angle with underbar", + symbol = "⦥" + }, + revemptyset = { + doc = "reversed empty set", + symbol = "⦰" + }, + revnmid = { + doc = "does not divide with reversed negation slash", + symbol = "⫮" + }, + rfbowtie = { + doc = "right black bowtie", + symbol = "⧒" + }, + rfloor = { + doc = "right floor", + symbol = "⌋" + }, + rftimes = { + doc = "right black times", + symbol = "⧕" + }, + rgroup = { + doc = "mathematical right flattened parenthesis", + symbol = "⟯" + }, + rho = { + doc = "small rho, greek", + symbol = "ρ" + }, + rightangle = { + doc = "right (90 degree) angle", + symbol = "∟" + }, + rightanglemdot = { + doc = "measured right angle with dot", + symbol = "⦝" + }, + rightanglesqr = { + doc = "right angle variant with square", + symbol = "⦜" + }, + rightarrow = { + doc = "/rightarrow /to a: rightward arrow", + symbol = "→" + }, + rightarrowapprox = { + doc = "rightwards arrow above almost equal to", + symbol = "⥵" + }, + rightarrowbackapprox = { + doc = "rightwards arrow above reverse almost equal to", + symbol = "⭈" + }, + rightarrowbar = { + doc = "rightwards arrow to bar", + symbol = "⇥" + }, + rightarrowbsimilar = { + doc = "righttwards arrow above reverse tilde operator", + symbol = "⭌" + }, + rightarrowdiamond = { + doc = "rightwards arrow to black diamond", + symbol = "⤞" + }, + rightarrowgtr = { + doc = "rightwards arrow through greater-than", + symbol = "⭃" + }, + rightarrowonoplus = { + doc = "right arrow with circled plus", + symbol = "⟴" + }, + rightarrowplus = { + doc = "rightwards arrow with plus below", + symbol = "⥅" + }, + rightarrowshortleftarrow = { + doc = "rightwards arrow above short leftwards arrow", + symbol = "⥂" + }, + rightarrowsimilar = { + doc = "rightwards arrow above tilde operator", + symbol = "⥴" + }, + rightarrowsupset = { + doc = "rightwards arrow through subset", + symbol = "⭄" + }, + rightarrowtail = { + doc = "right arrow-tailed", + symbol = "↣" + }, + rightarrowtriangle = { + doc = "rightwards open-headed arrow", + symbol = "⇾" + }, + rightarrowx = { + doc = "rightwards arrow through x", + symbol = "⥇" + }, + rightbkarrow = { + doc = "rightwards double dash arrow", + symbol = "⤍" + }, + rightcurvedarrow = { + doc = "wave arrow pointing directly right", + symbol = "⤳" + }, + rightdasharrow = { + doc = "rightwards dashed arrow", + symbol = "⇢" + }, + rightdbltail = { + doc = "rightwards double arrow-tail", + symbol = "⤜" + }, + rightdotarrow = { + doc = "rightwards arrow with dotted stem", + symbol = "⤑" + }, + rightdowncurvedarrow = { + doc = "arrow pointing downwards then curving rightwards", + symbol = "⤷" + }, + rightfishtail = { + doc = "right fish tail", + symbol = "⥽" + }, + rightharpoonaccent = { + doc = "combining right harpoon above", + symbol = "◌⃑" + }, + rightharpoondown = { + doc = "right harpoon-down", + symbol = "⇁" + }, + rightharpoondownbar = { + doc = "rightwards harpoon with barb down to bar", + symbol = "⥗" + }, + rightharpoonsupdown = { + doc = "rightwards harpoon with barb up above rightwards harpoon with barb down", + symbol = "⥤" + }, + rightharpoonup = { + doc = "right harpoon-up", + symbol = "⇀" + }, + rightharpoonupbar = { + doc = "rightwards harpoon with barb up to bar", + symbol = "⥓" + }, + rightharpoonupdash = { + doc = "rightwards harpoon with barb up above long dash", + symbol = "⥬" + }, + rightimply = { + doc = "right double arrow with rounded head", + symbol = "⥰" + }, + rightleftarrows = { + doc = "right arrow over left arrow", + symbol = "⇄" + }, + rightleftharpoons = { + doc = "right harpoon over left", + symbol = "⇌" + }, + rightleftharpoonsdown = { + doc = "rightwards harpoon with barb down above leftwards harpoon with barb down", + symbol = "⥩" + }, + rightleftharpoonsup = { + doc = "rightwards harpoon with barb up above leftwards harpoon with barb up", + symbol = "⥨" + }, + rightmoon = { + doc = "first quarter moon", + symbol = "☽" + }, + rightouterjoin = { + doc = "right outer join", + symbol = "⟖" + }, + rightpentagon = { + doc = "white right-pointing pentagon", + symbol = "⭔" + }, + rightpentagonblack = { + doc = "black right-pointing pentagon", + symbol = "⭓" + }, + rightrightarrows = { + doc = "two right arrows", + symbol = "⇉" + }, + rightsquigarrow = { + doc = "rightwards squiggle arrow", + symbol = "⇝" + }, + righttail = { + doc = "rightwards arrow-tail", + symbol = "⤚" + }, + rightthreearrows = { + doc = "three rightwards arrows", + symbol = "⇶" + }, + rightthreetimes = { + doc = "right semidirect product", + symbol = "⋌" + }, + rightwavearrow = { + doc = "right arrow-wavy", + symbol = "↝" + }, + rightwhitearrow = { + doc = "rightwards white arrow", + symbol = "⇨" + }, + ringplus = { + doc = "plus sign with small circle above", + symbol = "⨢" + }, + risingdotseq = { + doc = "equals, rising dots", + symbol = "≓" + }, + rmoustache = { + doc = "upper right or lower left curly bracket section", + symbol = "⎱" + }, + rparen = { + doc = "right parenthesis", + symbol = ")" + }, + rparenextender = { + doc = "right parenthesis extension", + symbol = "⎟" + }, + rparengtr = { + doc = "right arc greater-than bracket", + symbol = "⦔" + }, + rparenlend = { + doc = "right parenthesis lower hook", + symbol = "⎠" + }, + rparenuend = { + doc = "right parenthesis upper hook", + symbol = "⎞" + }, + rppolint = { + doc = "line integration with rectangular path around pole", + symbol = "⨒" + }, + rrangle = { + doc = "z notation right binding bracket", + symbol = "⦊" + }, + rrparenthesis = { + doc = "z notation right image bracket", + symbol = "⦈" + }, + rsolbar = { + doc = "reverse solidus with horizontal stroke", + symbol = "⧷" + }, + rsqhook = { + doc = "square right open box operator", + symbol = "⫎" + }, + rsub = { + doc = "z notation range antirestriction", + symbol = "⩥" + }, + rtimes = { + doc = "times sign, right closed", + symbol = "⋊" + }, + rtriltri = { + doc = "right triangle above left triangle", + symbol = "⧎" + }, + ruledelayed = { + doc = "rule-delayed", + symbol = "⧴" + }, + rvboxline = { + doc = "right vertical box line", + symbol = "⎹" + }, + rvzigzag = { + doc = "right wiggly fence", + symbol = "⧙" + }, + sansLmirrored = { + doc = "reversed sans-serif capital l", + symbol = "⅃" + }, + sansLturned = { + doc = "turned sans-serif capital l", + symbol = "⅂" + }, + scpolint = { + doc = "line integration with semicircular path around pole", + symbol = "⨓" + }, + scurel = { + doc = "succeeds under relation", + symbol = "⊱" + }, + searrow = { + doc = "se pointing arrow", + symbol = "↘" + }, + seovnearrow = { + doc = "south east arrow crossing north east arrow", + symbol = "⤭" + }, + setminus = { + doc = "reverse solidus operator", + symbol = "⧵" + }, + sharp = { + doc = "musical sharp", + symbol = "♯" + }, + shortdowntack = { + doc = "short down tack", + symbol = "⫟" + }, + shortlefttack = { + doc = "short left tack", + symbol = "⫞" + }, + shortrightarrowleftarrow = { + doc = "short rightwards arrow above leftwards arrow", + symbol = "⥄" + }, + shortuptack = { + doc = "short up tack", + symbol = "⫠" + }, + shuffle = { + doc = "shuffle product", + symbol = "⧢" + }, + sigma = { + doc = "small sigma, greek", + symbol = "σ" + }, + sim = { + doc = "similar", + symbol = "∼" + }, + sime = { + doc = "similar, equals (alias)", + symbol = "≃" + }, + simeq = { + doc = "similar, equals", + symbol = "≃" + }, + simgE = { + doc = "similar above greater-than above equals sign", + symbol = "⪠" + }, + simgtr = { + doc = "similar or greater-than", + symbol = "⪞" + }, + similarleftarrow = { + doc = "tilde operator above leftwards arrow", + symbol = "⭉" + }, + similarrightarrow = { + doc = "tilde operator above rightwards arrow", + symbol = "⥲" + }, + simlE = { + doc = "similar above less-than above equals sign", + symbol = "⪟" + }, + simless = { + doc = "similar or less-than", + symbol = "⪝" + }, + simminussim = { + doc = "similar minus similar", + symbol = "⩬" + }, + simneqq = { + doc = "similar, not equals [vert only for 9573 entity]", + symbol = "≆" + }, + simplus = { + doc = "plus sign with tilde above", + symbol = "⨤" + }, + simrdots = { + doc = "tilde operator with rising dots", + symbol = "⩫" + }, + sinewave = { + doc = "sine wave", + symbol = "∿" + }, + smallblacktriangleleft = { + doc = "left triangle, filled", + symbol = "◂" + }, + smallblacktriangleright = { + doc = "right triangle, filled", + symbol = "▸" + }, + smallin = { + doc = "set membership (small set membership)", + symbol = "∊" + }, + smallni = { + doc = "/ni /owns r: contains (small contains as member)", + symbol = "∍" + }, + smallsetminus = { + doc = "small set minus (cf. reverse solidus)", + symbol = "∖" + }, + smalltriangleleft = { + doc = "left triangle, open", + symbol = "◃" + }, + smalltriangleright = { + doc = "right triangle, open", + symbol = "▹" + }, + smashtimes = { + doc = "smash product", + symbol = "⨳" + }, + smblkcircle = { + doc = "/bullet b: round bullet, filled", + symbol = "•" + }, + smblkdiamond = { + doc = "black small diamond", + symbol = "⬩" + }, + smblklozenge = { + doc = "black small lozenge", + symbol = "⬪" + }, + smblksquare = { + doc = "/blacksquare - sq bullet, filled", + symbol = "▪" + }, + smeparsl = { + doc = "equals sign and slanted parallel with tilde above", + symbol = "⧤" + }, + smile = { + doc = "up curve", + symbol = "⌣" + }, + smt = { + doc = "smaller than", + symbol = "⪪" + }, + smte = { + doc = "smaller than or equal to", + symbol = "⪬" + }, + smwhitestar = { + doc = "white small star", + symbol = "⭒" + }, + smwhtcircle = { + doc = "white bullet", + symbol = "◦" + }, + smwhtdiamond = { + doc = "white diamond", + symbol = "⋄" + }, + smwhtlozenge = { + doc = "white small lozenge", + symbol = "⬫" + }, + smwhtsquare = { + doc = "white small square", + symbol = "▫" + }, + spadesuit = { + doc = "spades suit symbol", + symbol = "♠" + }, + sphericalangle = { + doc = "angle-spherical", + symbol = "∢" + }, + sphericalangleup = { + doc = "spherical angle opening up", + symbol = "⦡" + }, + sqcap = { + doc = "square intersection", + symbol = "⊓" + }, + sqcup = { + doc = "square union", + symbol = "⊔" + }, + sqint = { + doc = "quaternion integral operator", + symbol = "⨖" + }, + sqlozenge = { + doc = "square lozenge", + symbol = "⌑" + }, + sqrt = { + doc = "radical", + symbol = "√" + }, + sqrtbottom = { + doc = "radical symbol bottom", + symbol = "⎷" + }, + sqsubset = { + doc = "square subset", + symbol = "⊏" + }, + sqsubseteq = { + doc = "square subset, equals", + symbol = "⊑" + }, + sqsubsetneq = { + doc = "square subset, not equals", + symbol = "⋤" + }, + sqsupset = { + doc = "square superset", + symbol = "⊐" + }, + sqsupseteq = { + doc = "square superset, equals", + symbol = "⊒" + }, + sqsupsetneq = { + doc = "square superset, not equals", + symbol = "⋥" + }, + squarebotblack = { + doc = "square with bottom half black", + symbol = "⬓" + }, + squarecrossfill = { + doc = "square with diagonal crosshatch fill", + symbol = "▩" + }, + squarehfill = { + doc = "square, horizontal rule filled", + symbol = "▤" + }, + squarehvfill = { + doc = "square with orthogonal crosshatch fill", + symbol = "▦" + }, + squareleftblack = { + doc = "square, filled left half", + symbol = "◧" + }, + squarellblack = { + doc = "square with lower left diagonal half black", + symbol = "⬕" + }, + squarellquad = { + doc = "white square with lower left quadrant", + symbol = "◱" + }, + squarelrblack = { + doc = "square, filled bottom right corner", + symbol = "◪" + }, + squarelrquad = { + doc = "white square with lower right quadrant", + symbol = "◲" + }, + squareneswfill = { + doc = "square, ne-to-sw rule filled", + symbol = "▨" + }, + squarenwsefill = { + doc = "square, nw-to-se rule filled", + symbol = "▧" + }, + squarerightblack = { + doc = "square, filled right half", + symbol = "◨" + }, + squaretopblack = { + doc = "square with top half black", + symbol = "⬒" + }, + squareulblack = { + doc = "square, filled top left corner", + symbol = "◩" + }, + squareulquad = { + doc = "white square with upper left quadrant", + symbol = "◰" + }, + squareurblack = { + doc = "square with upper right diagonal half black", + symbol = "⬔" + }, + squareurquad = { + doc = "white square with upper right quadrant", + symbol = "◳" + }, + squarevfill = { + doc = "square, vertical rule filled", + symbol = "▥" + }, + squoval = { + doc = "white square with rounded corners", + symbol = "▢" + }, + sslash = { + doc = "double solidus operator", + symbol = "⫽" + }, + star = { + doc = "small star, filled, low", + symbol = "⋆" + }, + stareq = { + doc = "star equals", + symbol = "≛" + }, + strns = { + doc = "straightness", + symbol = "⏤" + }, + subedot = { + doc = "subset of or equal to with dot above", + symbol = "⫃" + }, + submult = { + doc = "subset with multiplication sign below", + symbol = "⫁" + }, + subrarr = { + doc = "subset above rightwards arrow", + symbol = "⥹" + }, + subset = { + doc = "subset or is implied by", + symbol = "⊂" + }, + subsetapprox = { + doc = "subset of above almost equal to", + symbol = "⫉" + }, + subsetcirc = { + doc = "open subset", + symbol = "⟃" + }, + subsetdot = { + doc = "subset with dot", + symbol = "⪽" + }, + subseteq = { + doc = "subset, equals", + symbol = "⊆" + }, + subseteqq = { + doc = "subset of above equals sign", + symbol = "⫅" + }, + subsetneq = { + doc = "subset, not equals", + symbol = "⊊" + }, + subsetneqq = { + doc = "subset of above not equal to", + symbol = "⫋" + }, + subsetplus = { + doc = "subset with plus sign below", + symbol = "⪿" + }, + subsim = { + doc = "subset of above tilde operator", + symbol = "⫇" + }, + subsub = { + doc = "subset above subset", + symbol = "⫕" + }, + subsup = { + doc = "subset above superset", + symbol = "⫓" + }, + succ = { + doc = "succeeds", + symbol = "≻" + }, + succapprox = { + doc = "succeeds above almost equal to", + symbol = "⪸" + }, + succcurlyeq = { + doc = "succeeds, curly equals", + symbol = "≽" + }, + succeq = { + doc = "succeeds above single-line equals sign", + symbol = "⪰" + }, + succeqq = { + doc = "succeeds above equals sign", + symbol = "⪴" + }, + succnapprox = { + doc = "succeeds above not almost equal to", + symbol = "⪺" + }, + succneq = { + doc = "succeeds above single-line not equal to", + symbol = "⪲" + }, + succneqq = { + doc = "succeeds above not equal to", + symbol = "⪶" + }, + succnsim = { + doc = "succeeds, not similar", + symbol = "⋩" + }, + succsim = { + doc = "succeeds, similar", + symbol = "≿" + }, + sum = { + doc = "summation operator", + symbol = "∑" + }, + sumbottom = { + doc = "summation bottom", + symbol = "⎳" + }, + sumint = { + doc = "summation with integral", + symbol = "⨋" + }, + sumtop = { + doc = "summation top", + symbol = "⎲" + }, + sun = { + doc = "white sun with rays", + symbol = "☼" + }, + supdsub = { + doc = "superset beside and joined by dash with subset", + symbol = "⫘" + }, + supedot = { + doc = "superset of or equal to with dot above", + symbol = "⫄" + }, + suphsol = { + doc = "superset preceding solidus", + symbol = "⟉" + }, + suphsub = { + doc = "superset beside subset", + symbol = "⫗" + }, + suplarr = { + doc = "superset above leftwards arrow", + symbol = "⥻" + }, + supmult = { + doc = "superset with multiplication sign below", + symbol = "⫂" + }, + supset = { + doc = "superset or implies", + symbol = "⊃" + }, + supsetapprox = { + doc = "superset of above almost equal to", + symbol = "⫊" + }, + supsetcirc = { + doc = "open superset", + symbol = "⟄" + }, + supsetdot = { + doc = "superset with dot", + symbol = "⪾" + }, + supseteq = { + doc = "superset, equals", + symbol = "⊇" + }, + supseteqq = { + doc = "superset of above equals sign", + symbol = "⫆" + }, + supsetneq = { + doc = "superset, not equals", + symbol = "⊋" + }, + supsetneqq = { + doc = "superset of above not equal to", + symbol = "⫌" + }, + supsetplus = { + doc = "superset with plus sign below", + symbol = "⫀" + }, + supsim = { + doc = "superset of above tilde operator", + symbol = "⫈" + }, + supsub = { + doc = "superset above subset", + symbol = "⫔" + }, + supsup = { + doc = "superset above superset", + symbol = "⫖" + }, + surd = { + doc = "radical", + symbol = "√" + }, + swarrow = { + doc = "sw pointing arrow", + symbol = "↙" + }, + talloblong = { + doc = "white vertical bar", + symbol = "⫾" + }, + tau = { + doc = "small tau, greek", + symbol = "τ" + }, + therefore = { + doc = "therefore", + symbol = "∴" + }, + thermod = { + doc = "thermodynamic", + symbol = "⧧" + }, + theta = { + doc = "straight theta, small theta, greek", + symbol = "θ" + }, + threedangle = { + doc = "three dimensional angle", + symbol = "⟀" + }, + threedotcolon = { + doc = "triple colon operator", + symbol = "⫶" + }, + threeunderdot = { + doc = "combining triple underdot", + symbol = "◌⃨" + }, + tieconcat = { + doc = "character tie, z notation sequence concatenation", + symbol = "⁀" + }, + tieinfty = { + doc = "tie over infinity", + symbol = "⧝" + }, + tilde = { + doc = "tilde", + symbol = "◌̃" + }, + times = { + doc = "multiply sign", + symbol = "×" + }, + timesbar = { + doc = "multiplication sign with underbar", + symbol = "⨱" + }, + tminus = { + doc = "miny", + symbol = "⧿" + }, + toea = { + doc = "north east arrow and south east arrow", + symbol = "⤨" + }, + tona = { + doc = "north west arrow and north east arrow", + symbol = "⤧" + }, + top = { + doc = "top", + symbol = "⊤" + }, + topbot = { + doc = "top and bottom", + symbol = "⌶" + }, + topcir = { + doc = "down tack with circle below", + symbol = "⫱" + }, + topfork = { + doc = "pitchfork with tee top", + symbol = "⫚" + }, + topsemicircle = { + doc = "upper half circle", + symbol = "◠" + }, + tosa = { + doc = "south east arrow and south west arrow", + symbol = "⤩" + }, + towa = { + doc = "south west arrow and north west arrow", + symbol = "⤪" + }, + tplus = { + doc = "tiny", + symbol = "⧾" + }, + trapezium = { + doc = "white trapezium", + symbol = "⏢" + }, + trianglecdot = { + doc = "triangle with centered dot", + symbol = "◬" + }, + triangledown = { + doc = "down triangle, open", + symbol = "▿" + }, + triangleleft = { + doc = "(large) left triangle, open; z notation domain restriction", + symbol = "◁" + }, + triangleleftblack = { + doc = "up-pointing triangle with left half black", + symbol = "◭" + }, + trianglelefteq = { + doc = "left triangle, equals", + symbol = "⊴" + }, + triangleminus = { + doc = "minus sign in triangle", + symbol = "⨺" + }, + triangleodot = { + doc = "triangle with dot above", + symbol = "⧊" + }, + triangleplus = { + doc = "plus sign in triangle", + symbol = "⨹" + }, + triangleq = { + doc = "triangle, equals", + symbol = "≜" + }, + triangleright = { + doc = "(large) right triangle, open; z notation range restriction", + symbol = "▷" + }, + trianglerightblack = { + doc = "up-pointing triangle with right half black", + symbol = "◮" + }, + trianglerighteq = { + doc = "right triangle, equals", + symbol = "⊵" + }, + triangles = { + doc = "s in triangle", + symbol = "⧌" + }, + triangleserifs = { + doc = "triangle with serifs at bottom", + symbol = "⧍" + }, + triangletimes = { + doc = "multiplication sign in triangle", + symbol = "⨻" + }, + triangleubar = { + doc = "triangle with underbar", + symbol = "⧋" + }, + tripleplus = { + doc = "triple plus", + symbol = "⧻" + }, + trprime = { + doc = "triple prime (not superscripted)", + symbol = "‴" + }, + trslash = { + doc = "triple solidus binary relation", + symbol = "⫻" + }, + turnangle = { + doc = "turned angle", + symbol = "⦢" + }, + turnediota = { + doc = "turned iota", + symbol = "℩" + }, + turnednot = { + doc = "turned not sign", + symbol = "⌙" + }, + twocaps = { + doc = "intersection beside and joined with intersection", + symbol = "⩋" + }, + twocups = { + doc = "union beside and joined with union", + symbol = "⩊" + }, + twoheaddownarrow = { + doc = "down two-headed arrow", + symbol = "↡" + }, + twoheadleftarrow = { + doc = "left two-headed arrow", + symbol = "↞" + }, + twoheadleftarrowtail = { + doc = "leftwards two-headed arrow with tail", + symbol = "⬻" + }, + twoheadleftdbkarrow = { + doc = "leftwards two-headed triple-dash arrow", + symbol = "⬷" + }, + twoheadmapsfrom = { + doc = "leftwards two-headed arrow from bar", + symbol = "⬶" + }, + twoheadmapsto = { + doc = "rightwards two-headed arrow from bar", + symbol = "⤅" + }, + twoheadrightarrow = { + doc = "right two-headed arrow", + symbol = "↠" + }, + twoheadrightarrowtail = { + doc = "rightwards two-headed arrow with tail", + symbol = "⤖" + }, + twoheaduparrow = { + doc = "up two-headed arrow", + symbol = "↟" + }, + twoheaduparrowcircle = { + doc = "upwards two-headed arrow from small circle", + symbol = "⥉" + }, + twolowline = { + doc = "double low line (spacing)", + symbol = "‗" + }, + twonotes = { + doc = "beamed eighth notes", + symbol = "♫" + }, + typecolon = { + doc = "z notation type colon", + symbol = "⦂" + }, + ubrbrak = { + doc = "bottom tortoise shell bracket (mathematical use)", + symbol = "⏡" + }, + ularc = { + doc = "upper left quadrant circular arc", + symbol = "◜" + }, + ulblacktriangle = { + doc = "upper left triangle, filled", + symbol = "◤" + }, + ulcorner = { + doc = "upper left corner", + symbol = "⌜" + }, + ultriangle = { + doc = "upper left triangle", + symbol = "◸" + }, + uminus = { + doc = "union with minus sign", + symbol = "⩁" + }, + underbrace = { + doc = "bottom curly bracket (mathematical use)", + symbol = "⏟" + }, + underbracket = { + doc = "bottom square bracket", + symbol = "⎵" + }, + underleftarrow = { + doc = "combining left arrow below", + symbol = "◌⃮" + }, + underleftharpoondown = { + doc = "combining leftwards harpoon with barb downwards", + symbol = "◌⃭" + }, + underleftrightarrow = { + doc = "underleftrightarrow accent", + symbol = "◌͍" + }, + underparen = { + doc = "bottom parenthesis (mathematical use)", + symbol = "⏝" + }, + underrightarrow = { + doc = "combining right arrow below", + symbol = "◌⃯" + }, + underrightharpoondown = { + doc = "combining rightwards harpoon with barb downwards", + symbol = "◌⃬" + }, + unicodecdots = { + doc = "three dots, centered", + symbol = "⋯" + }, + unicodeellipsis = { + doc = "ellipsis (horizontal)", + symbol = "…" + }, + upDigamma = { + doc = "capital digamma", + symbol = "Ϝ" + }, + upand = { + doc = "turned ampersand", + symbol = "⅋" + }, + uparrow = { + doc = "upward arrow", + symbol = "↑" + }, + uparrowbarred = { + doc = "upwards arrow with horizontal stroke", + symbol = "⤉" + }, + uparrowoncircle = { + doc = "up arrow through circle", + symbol = "⦽" + }, + upbackepsilon = { + doc = "greek reversed lunate epsilon symbol", + symbol = "϶" + }, + updasharrow = { + doc = "upwards dashed arrow", + symbol = "⇡" + }, + updigamma = { + doc = "old greek small letter digamma", + symbol = "ϝ" + }, + updownarrow = { + doc = "up and down arrow", + symbol = "↕" + }, + updownarrowbar = { + doc = "up down arrow with base (perpendicular)", + symbol = "↨" + }, + updownarrows = { + doc = "up arrow, down arrow", + symbol = "⇅" + }, + updownharpoonleftleft = { + doc = "up barb left down barb left harpoon", + symbol = "⥑" + }, + updownharpoonleftright = { + doc = "up barb left down barb right harpoon", + symbol = "⥍" + }, + updownharpoonrightleft = { + doc = "up barb right down barb left harpoon", + symbol = "⥌" + }, + updownharpoonrightright = { + doc = "up barb right down barb right harpoon", + symbol = "⥏" + }, + updownharpoonsleftright = { + doc = "upwards harpoon with barb left beside downwards harpoon with barb right", + symbol = "⥮" + }, + upfishtail = { + doc = "up fish tail", + symbol = "⥾" + }, + upharpoonleft = { + doc = "up harpoon-left", + symbol = "↿" + }, + upharpoonleftbar = { + doc = "upwards harpoon with barb left from bar", + symbol = "⥠" + }, + upharpoonright = { + doc = "/upharpoonright /restriction a: up harpoon-right", + symbol = "↾" + }, + upharpoonrightbar = { + doc = "upwards harpoon with barb right from bar", + symbol = "⥜" + }, + upharpoonsleftright = { + doc = "upwards harpoon with barb left beside upwards harpoon with barb right", + symbol = "⥣" + }, + upin = { + doc = "element of opening upwards", + symbol = "⟒" + }, + upint = { + doc = "integral with overbar", + symbol = "⨛" + }, + uplus = { + doc = "plus sign in union", + symbol = "⊎" + }, + uprightcurvearrow = { + doc = "arrow pointing rightwards then curving upwards", + symbol = "⤴" + }, + upsilon = { + doc = "small upsilon, greek", + symbol = "υ" + }, + upuparrows = { + doc = "two up arrows", + symbol = "⇈" + }, + upwhitearrow = { + doc = "upwards white arrow", + symbol = "⇧" + }, + urarc = { + doc = "upper right quadrant circular arc", + symbol = "◝" + }, + urblacktriangle = { + doc = "upper right triangle, filled", + symbol = "◥" + }, + urcorner = { + doc = "upper right corner", + symbol = "⌝" + }, + urtriangle = { + doc = "upper right triangle", + symbol = "◹" + }, + vBar = { + doc = "short up tack with underbar", + symbol = "⫨" + }, + vBarv = { + doc = "short up tack above short down tack", + symbol = "⫩" + }, + vDash = { + doc = "vertical, double dash", + symbol = "⊨" + }, + vDdash = { + doc = "vertical bar triple right turnstile", + symbol = "⫢" + }, + varTheta = { + doc = "greek capital theta symbol", + symbol = "ϴ" + }, + varVdash = { + doc = "long dash from left member of double vertical", + symbol = "⫦" + }, + varbarwedge = { + doc = "/barwedge b: logical and, bar above [projective (bar over small wedge)]", + symbol = "⌅" + }, + varcarriagereturn = { + doc = "return symbol", + symbol = "⏎" + }, + varclubsuit = { + doc = "club, white (card suit)", + symbol = "♧" + }, + vardiamondsuit = { + doc = "filled diamond (card suit)", + symbol = "♦" + }, + vardoublebarwedge = { + doc = "/doublebarwedge b: logical and, double bar above [perspective (double bar over small wedge)]", + symbol = "⌆" + }, + varepsilon = { + doc = "rounded small varepsilon, greek", + symbol = "ε" + }, + varheartsuit = { + doc = "filled heart (card suit)", + symbol = "♥" + }, + varhexagon = { + doc = "white hexagon", + symbol = "⬡" + }, + varhexagonblack = { + doc = "black hexagon", + symbol = "⬢" + }, + varhexagonlrbonds = { + doc = "six carbon ring, corner down, double bonds lower right etc", + symbol = "⌬" + }, + varisinobar = { + doc = "element of with overbar", + symbol = "⋶" + }, + varisins = { + doc = "element of with vertical bar at end of horizontal stroke", + symbol = "⋳" + }, + varkappa = { + doc = "rounded small kappa, greek", + symbol = "ϰ" + }, + varlrtriangle = { + doc = "right triangle", + symbol = "⊿" + }, + varniobar = { + doc = "contains with overbar", + symbol = "⋽" + }, + varnis = { + doc = "contains with vertical bar at end of horizontal stroke", + symbol = "⋻" + }, + varnothing = { + doc = "circle, slash", + symbol = "∅" + }, + varointclockwise = { + doc = "contour integral, clockwise", + symbol = "∲" + }, + varphi = { + doc = "curly or open small phi, greek", + symbol = "φ" + }, + varpi = { + doc = "rounded small pi (pomega), greek", + symbol = "ϖ" + }, + varrho = { + doc = "rounded small rho, greek", + symbol = "ϱ" + }, + varsigma = { + doc = "terminal sigma, greek", + symbol = "ς" + }, + varspadesuit = { + doc = "spade, white (card suit)", + symbol = "♤" + }, + varstar = { + doc = "six pointed black star", + symbol = "✶" + }, + vartheta = { + doc = "/vartheta - curly or open theta", + symbol = "ϑ" + }, + vartriangle = { + doc = "/triangle - up triangle, open", + symbol = "▵" + }, + vartriangleleft = { + doc = "left triangle, open, variant", + symbol = "⊲" + }, + vartriangleright = { + doc = "right triangle, open, variant", + symbol = "⊳" + }, + varveebar = { + doc = "small vee with underbar", + symbol = "⩡" + }, + vbraceextender = { + doc = "curly bracket extension", + symbol = "⎪" + }, + vbrtri = { + doc = "vertical bar beside right triangle", + symbol = "⧐" + }, + vdash = { + doc = "vertical, dash", + symbol = "⊢" + }, + vdots = { + doc = "vertical ellipsis", + symbol = "⋮" + }, + vec = { + doc = "combining right arrow above", + symbol = "◌⃗" + }, + vectimes = { + doc = "vector or cross product", + symbol = "⨯" + }, + vee = { + doc = "/vee /lor b: logical or", + symbol = "∨" + }, + veebar = { + doc = "logical or, bar below (large vee); exclusive disjunction", + symbol = "⊻" + }, + veedot = { + doc = "or with dot inside", + symbol = "⟇" + }, + veedoublebar = { + doc = "logical or with double underbar", + symbol = "⩣" + }, + veeeq = { + doc = "logical or, equals", + symbol = "≚" + }, + veemidvert = { + doc = "logical or with middle stem", + symbol = "⩛" + }, + veeodot = { + doc = "logical or with dot above", + symbol = "⩒" + }, + veeonvee = { + doc = "two intersecting logical or", + symbol = "⩖" + }, + veeonwedge = { + doc = "logical or overlapping logical and", + symbol = "⩙" + }, + vert = { + doc = "vertical bar", + symbol = "|" + }, + vertoverlay = { + doc = "combining long vertical line overlay", + symbol = "◌⃒" + }, + viewdata = { + doc = "viewdata square", + symbol = "⌗" + }, + vlongdash = { + doc = "long left tack", + symbol = "⟝" + }, + vrectangle = { + doc = "rectangle, white (vertical)", + symbol = "▯" + }, + vrectangleblack = { + doc = "black vertical rectangle", + symbol = "▮" + }, + vysmblkcircle = { + doc = "bullet operator", + symbol = "∙" + }, + vysmblksquare = { + doc = "black very small square", + symbol = "⬝" + }, + vysmwhtcircle = { + doc = "composite function (small circle)", + symbol = "∘" + }, + vysmwhtsquare = { + doc = "white very small square", + symbol = "⬞" + }, + vzigzag = { + doc = "vertical zigzag line", + symbol = "⦚" + }, + wedge = { + doc = "/wedge /land b: logical and", + symbol = "∧" + }, + wedgebar = { + doc = "logical and with underbar", + symbol = "⩟" + }, + wedgedot = { + doc = "and with dot", + symbol = "⟑" + }, + wedgedoublebar = { + doc = "logical and with double underbar", + symbol = "⩠" + }, + wedgemidvert = { + doc = "logical and with middle stem", + symbol = "⩚" + }, + wedgeodot = { + doc = "logical and with dot above", + symbol = "⩑" + }, + wedgeonwedge = { + doc = "two intersecting logical and", + symbol = "⩕" + }, + wedgeq = { + doc = "corresponds to (wedge, equals)", + symbol = "≙" + }, + whitearrowupfrombar = { + doc = "upwards white arrow from bar", + symbol = "⇪" + }, + whiteinwhitetriangle = { + doc = "white triangle containing small white triangle", + symbol = "⟁" + }, + whitepointerleft = { + doc = "white left-pointing pointer", + symbol = "◅" + }, + whitepointerright = { + doc = "white right-pointing pointer", + symbol = "▻" + }, + whitesquaretickleft = { + doc = "white square with leftwards tick", + symbol = "⟤" + }, + whitesquaretickright = { + doc = "white square with rightwards tick", + symbol = "⟥" + }, + whthorzoval = { + doc = "white horizontal ellipse", + symbol = "⬭" + }, + whtvertoval = { + doc = "white vertical ellipse", + symbol = "⬯" + }, + wideangledown = { + doc = "oblique angle opening up", + symbol = "⦦" + }, + wideangleup = { + doc = "oblique angle opening down", + symbol = "⦧" + }, + widebreve = { + doc = "stretchy breve", + symbol = "◌̆" + }, + widebridgeabove = { + doc = "combining wide bridge above", + symbol = "◌⃩" + }, + widecheck = { + doc = "stretchy caron", + symbol = "◌̌" + }, + widehat = { + doc = "circumflex accent", + symbol = "◌̂" + }, + wideoverbar = { + doc = "stretchy overbar embellishment", + symbol = "◌̅" + }, + widetilde = { + doc = "tilde", + symbol = "◌̃" + }, + wideutilde = { + doc = "under tilde accent (multiple characters and non-spacing)", + symbol = "◌̰" + }, + wp = { + doc = "weierstrass p", + symbol = "℘" + }, + wr = { + doc = "wreath product", + symbol = "≀" + }, + xbsol = { + doc = "big reverse solidus", + symbol = "⧹" + }, + xi = { + doc = "small xi, greek", + symbol = "ξ" + }, + xsol = { + doc = "big solidus", + symbol = "⧸" + }, + zcmp = { + doc = "z notation schema composition", + symbol = "⨟" + }, + zeta = { + doc = "small zeta, greek", + symbol = "ζ" + }, + zpipe = { + doc = "z notation schema piping", + symbol = "⨠" + }, + zproject = { + doc = "z notation schema projection", + symbol = "⨡" + } +} diff --git a/support/digestif/data/xparse.sty.tags b/support/digestif/data/xparse.sty.tags new file mode 100644 index 0000000000..19fd6bb0bc --- /dev/null +++ b/support/digestif/data/xparse.sty.tags @@ -0,0 +1,86 @@ +ctan_package = "xparse" +dependencies = { + "expl3.sty" +} +commands = { + NewDocumentCommand = { + action = "NewDocumentCommand", + arguments = { + [1] = {meta = "command"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "code"} + }, + summary = "Define a new command." + }, + RenewDocumentCommand = { + action = "NewDocumentCommand", + arguments = { + [1] = {meta = "command"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "code"} + }, + summary = "Redefine an existing command." + }, + ProvideDocumentCommand = { + action = "NewDocumentCommand", + arguments = { + [1] = {meta = "command"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "code"} + }, + summary = "Define a new command, unless already defined." + }, + DeclareDocumentCommand = { + action = "NewDocumentCommand", + arguments = { + [1] = {meta = "command"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "code"} + }, + summary = "Define a new command, overriding an existing definition." + }, + NewDocumentEnvironment = { + action = "NewDocumentEnvironment", + arguments = { + [1] = {meta = "environment"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "start code"}, + [4] = {meta = "end code"} + }, + summary = "Define a new environment." + }, + RenewDocumentEnvironment = { + action = "NewDocumentEnvironment", + arguments = { + [1] = {meta = "environment"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "start code"}, + [4] = {meta = "end code"} + }, + summary = "Redefine an existing environment." + }, + ProvideDocumentEnvironment = { + action = "NewDocumentEnvironment", + arguments = { + [1] = {meta = "environment"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "start code"}, + [4] = {meta = "end code"} + }, + summary = "Define a new environment, unless already defined." + }, + DeclareDocumentEnvironment = { + action = "NewDocumentEnvironment", + arguments = { + [1] = {meta = "environment"}, + [2] = {meta = "arg spec"}, + [3] = {meta = "start code"}, + [4] = {meta = "end code"} + }, + summary = "Define a new environment, overriding an existing definition." + }, + NewExpandableDocumentCommand = "$ref:xparse.sty#/commands/NewDocumentCommand", + RenewExpandableDocumentCommand = "$ref:xparse.sty#/commands/RenewDocumentCommand", + ProvideExpandableDocumentCommand = "$ref:xparse.sty#/commands/ProvideDocumentCommand", + DeclareExpandableDocumentCommand = "$ref:xparse.sty#/commands/DeclareDocumentCommand" +} diff --git a/support/digestif/digestif/Cache.lua b/support/digestif/digestif/Cache.lua new file mode 100644 index 0000000000..d7e3e16f85 --- /dev/null +++ b/support/digestif/digestif/Cache.lua @@ -0,0 +1,129 @@ +-- A class to store transient file contents and manage the creation of +-- Manuscript objects. + +local Manuscript = require "digestif.Manuscript" +local lpeg = require "lpeg" +local util = require "digestif.util" + +local S, C = lpeg.S, lpeg.C +local sequence, gobble_until = util.sequence, util.gobble_until +local path_split, path_join = util.path_split, util.path_join +local path_normalize = util.path_normalize +local weak_values = {__mode = "v"} +local io_open = io.open + +local Cache = util.class() + +function Cache:__init(tbl) + self.store = setmetatable({}, weak_values) + self.persist = {} -- a place to keep an extra reference to things + -- that shouldn't vanish + if tbl then + for name, src in pairs(tbl) do + self:put(name, src) + end + end +end + +-- Set the contents of a file in the cache. +function Cache:put(filename, str) + local props = self.store[filename] + if not props then + props = {} + self.store[filename] = props + else + props.rootname = nil + end + props.contents = str + self.persist[filename] = props +end + +-- Return the contents of a file, as stored with the put method, or +-- attempt to read the file from disk. If neither succeeds, return +-- nil. The second return value is a cookie. Values read from disk +-- will be garbage collected when no reference to the cookie exists. +-- Values stored by the put method are not subject to garbage +-- collection until an explicit call to Cache.forget. +-- +function Cache:__call(filename) + local props = self.store[filename] + if not props then + local file, str = io_open(filename), nil + if file then + str = file:read("*all") + file:close() + end + props = {contents = str} + self.store[filename] = props + end + return props.contents, props +end + +-- Remove a file from the cache. +function Cache:forget(filename) + self.store[filename] = nil + self.persist[filename] = nil +end + +local space = S" \t\r" +local magic_comment_patt = sequence( + (space^0 * "%")^1, + space^0 * "!" * util.case_fold("tex"), + space^1 * "root", + space^0 * "=", + space^0 * C(gobble_until(space^0 * "\n"))) +local search_magic_comment_patt = util.choice( + magic_comment_patt, + util.search("\n" * magic_comment_patt)) + +-- Determine the root path of a document from magic comments. +function Cache:rootname(filename) + local _, cookie = self(filename) -- warm up + local props = assert(self.store[filename]) + local rootname = props.rootname + if rootname == nil then + local src = self(filename) + local val = search_magic_comment_patt:match(src:sub(1, 1000)) + if val then + rootname = path_normalize(path_join(path_split(filename), val)) + else + rootname = false + end + props.rootname = rootname + end + return rootname +end + +-- Produce a Manuscript object. This method ensures that the result +-- belongs to a tree of Manuscript objects representing a multi-file +-- TeX document. If the rootname argument is omitted, try to infer it +-- using magic comments. +-- +-- This method reuses as much information as possible from the cache. +-- +-- Arguments: +-- filename (string): the path of the manuscript +-- format (string): the TeX format +-- rootname (string, optional): the root path of the TeX document +-- +-- Returns: +-- a Manuscript object +-- +function Cache:manuscript(filename, format, rootname) + rootname = rootname or self:rootname(filename) or filename + local root = self.store[rootname] and self.store[rootname][format] + if not root or not root:is_current() then + root = Manuscript{ + filename = rootname, + format = format, + files = self + } + self.store[rootname][format] = root + end + local script = root:find_manuscript(filename) + or self:manuscript(filename, format, filename) -- root does not refer back + self.store[filename][format] = script + return script +end + +return Cache diff --git a/support/digestif/digestif/Manuscript.lua b/support/digestif/digestif/Manuscript.lua new file mode 100644 index 0000000000..d9101d8c07 --- /dev/null +++ b/support/digestif/digestif/Manuscript.lua @@ -0,0 +1,1523 @@ +-- Manuscript class + +local config = require "digestif.config" +local util = require "digestif.util" + +local require_data = require "digestif.data".require +local get_info = require "digestif.data".get_info +local resolve_doc_items = require "digestif.data".resolve_doc_items +local path_join, path_split = util.path_join, util.path_split +local path_normalize = util.path_normalize +local find_file = util.find_file +local format_filename_template = util.format_filename_template + +local format = string.format +local co_wrap, co_yield = coroutine.wrap, coroutine.yield +local concat, sort = table.concat, table.sort +local infty, min = math.huge, math.min +local utf8_len, utf8_offset = utf8.len, utf8.offset +local nested_get = util.nested_get +local map_keys, update, extend = util.map_keys, util.update, util.extend +local line_indices = util.line_indices +local matcher, fuzzy_matcher = util.matcher, util.fuzzy_matcher + +local Manuscript = util.class() + +--* Constructor + +-- Only descendants of this class (representing various TeX formats) +-- are ever instantiated. So we replace the constructor by a function +-- defering to the subclass indicated by the format field of the +-- argument. + +local formats = { + ["bibtex"] = "digestif.ManuscriptBibTeX", + ["context"] = "digestif.ManuscriptConTeXt", + ["latex"] = "digestif.ManuscriptLaTeX", + ["latex-prog"] = "digestif.ManuscriptLatexProg", + ["doctex"] = "digestif.ManuscriptDoctex", + ["plain"] = "digestif.ManuscriptPlainTeX", + ["texinfo"] = "digestif.ManuscriptTexinfo" +} + +local function ManuscriptFactory(_, args) + local fmt = args.format + or args.parent and args.parent.format + or error "TeX format not specified" + return require(formats[fmt])(args) +end +getmetatable(Manuscript).__call = ManuscriptFactory + +local function infer_format(path) + local ext = path:sub(-4) + if ext == ".bib" then + return "bibtex" + elseif ext == ".sty" or ext == ".cls" then + return "latex-prog" + end +end + +-- Create a new manuscript object. The argument is a table with the +-- following keys: +-- +-- filename: the manuscript's file name +-- files: a function that returns file contents +-- parent: a parent manuscript object (optional) +-- format: the TeX format ("latex", "plain", etc.). This is +-- actually only used by ManuscriptFactory +-- +function Manuscript:__init(args) + local filename, parent, files = args.filename, args.parent, args.files + self.filename = filename + self.parent = parent + self.files = files + self.root = parent and parent.root or self + local src, cache_cookie = files(filename) + self.src, self.cache_cookie = src or "", cache_cookie + self.lines = line_indices(self.src) + local super = parent or self.__index + self.packages = setmetatable({}, {__index = super.packages}) + self.commands = setmetatable({}, {__index = super.commands}) + self.environments = setmetatable({}, {__index = super.environments}) + -- We eagerly initialize most indexes here because the overhead of + -- going through the document is substantial. Only the indices used + -- by Manuscript:find_references are computed on demand. + self._children = {} + self.bib_index = {} + self.child_index = {} + self.section_index = {} + self.label_index = {} + if self.init_callbacks then + self:scan(self.init_callbacks) + end +end + +function Manuscript:is_current() + local current_src, cookie = self.files(self.filename) + return (self.src == (current_src or "")) and (cookie or true) +end + +-- Return a child manuscript, provided its name appear in the +-- child_index. It inherits this manuscript's `files` function. +-- Memoization is used to make this efficient. +function Manuscript:child(name) + local child = self._children[name] + local is_current = child and child:is_current() + if not is_current then + if not child then + local ancestor = self + while ancestor do + if ancestor.filename == name then return end + ancestor = ancestor.parent + end + end + child = Manuscript{ + filename = name, + parent = self, + format = infer_format(name), + files = self.files + } + self._children[name] = child + end + return child +end + +--* Substrings + +-- Get a substring of the manuscript. The argument can be a pair of +-- integers (inclusive indices, as in the Lua convention) or a table +-- with fields pos (inclusive) and cont (exclusive). +function Manuscript:substring(i, j) + if not i then return nil end + if type(i) == "table" then + j = i.cont - 1 + i = i.pos + end + return self.src:sub(i, j) +end + +-- Get a substring of the manuscript, trimmed. The argument follows +-- the same convention as Manuscript:substring. +function Manuscript:substring_trimmed(i, j) + return self.parser.trim(self:substring(i,j)) +end + +-- Get a substring of the manuscript, trimmed and without comments. +-- The argument follows the same convention as Manuscript:substring. +function Manuscript:substring_stripped(i, j) + local parser = self.parser + return parser.trim(parser.strip_comments(self:substring(i,j))) +end + +-- Get a substring of the manuscript, without commments and reduced to +-- one line. The argument follows the same convention as +-- Manuscript:substring. +function Manuscript:substring_clean(i, j) + local parser = self.parser + return parser.clean(parser.strip_comments(self:substring(i,j))) +end + +--* Parsing commands, lists, and key-value lists. + +-- Parse a key-value list in a given manuscript range. The argument +-- is a table with fields pos and cont. Returns a list of ranges, +-- with additional fields "key" and "value" (if present). These are +-- range tables as well. +function Manuscript:parse_kvlist(range) + local s = self:substring(1, range.cont - 1) -- TODO: avoid creating a new string + return self.parser.parse_kvlist(s, range.pos) +end + +-- Read the contents of a key-value list in the manuscript. The +-- argument is a table with fields pos and cont. Returns a nested +-- list of tables with fields "key" and "value" (if present), +-- containing the corresponding text in the source. +-- +-- TODO: add substring method as parameter +function Manuscript:read_keys(range) + local tbl = self:parse_kvlist(range) + local r = {} + for i, v in ipairs(tbl) do + r[i] = { + key = self:substring_trimmed(v.key), + value = v.value and self:substring_trimmed(v.value) + } + end + return r +end + +-- Read the contents of a list in the manuscript. Returns a list of +-- strings. +function Manuscript:read_list(i, j) + local parser = self.parser + local s = self:substring(i, j) + return parser.read_list(s) +end + +-- Parse the arguments of a command. +-- +-- Arguments: +-- pos (number): A position in the source. +-- cs (string, optional): The command name. If omitted, it is read +-- from the manuscript. +-- +-- Returns: +-- A list of ranges. +-- +function Manuscript:parse_command(pos, cs) + local parser = self.parser + if not cs then + cs = parser.csname:match(self.src, pos) or "" + end + local cmd = self.commands[cs] + local args = cmd and cmd.arguments + local cont = 1 + pos + #cs + if args then + local val = parser.parse_args(args, self.src, cont) + val.pos = pos + return val + else + return {pos = pos, cont = cont} + end +end + +--* Find line numbers, paragraphs, etc. + +-- Find the line number (and its location) of a given position. +-- Returns the line number (1-based) and that line's starting +-- position. +function Manuscript:line_number_at(pos) + local len = #self.src + local lines = self.lines + local j, l = 1, #lines -- top and bottom bounds for line search + if pos < 1 then pos = len + pos + 1 end + while pos < lines[l] do + local k = (j + l + 1) // 2 + if pos < lines[k] then + l = k - 1 + else + j = k + end + end -- now l = correct line, 1-based indexing + return l, lines[l] +end + +-- Compute the line and column number (both 1-based) at the given +-- position. +-- +-- TODO: make len function a parameter +function Manuscript:line_column_at(pos) + -- Out ranges are excluside on the right, Lua is inclusive, so we + -- may have pos == 1 + #self.src. + pos = min(pos, #self.src) + local l, line_pos = self:line_number_at(pos) + local c = utf8_len(self.src, line_pos, pos) or error("Invalid UTF-8") + return l, c +end + +-- Compute the source position at the given line an column. +-- +-- TODO: make offset function a parameter +function Manuscript:position_at(line, col) + local line_pos = self.lines[line] or error("Position out of bounds") + return utf8_offset(self.src, col, line_pos) or error("Position out of bounds") +end + + +-- Find beginning of the paragraph containing the given position. +function Manuscript:find_par(pos) + local src = self.src + local lines = self.lines + local l = self:line_number_at(pos) + for k = l, 1, -1 do + if self.parser.is_blank_line(src, lines[k]) then + return lines[k] + end + end + return 1 +end + +local preceding_command_callbacks = {} + +function preceding_command_callbacks.cs(self, pos, cs, end_pos) + if pos > end_pos then return nil end + local r = self:parse_command(pos, cs) + if r.cont <= end_pos then + local next_pos = self.parser.next_nonblank(self.src, r.cont) + if next_pos == end_pos then + return nil, pos, cs, r + end + end + return r.cont, end_pos +end + +-- Find the preceding command, if any. If there is a command whose +-- arguments end right before the given position, returns the +-- position, command name, and parse data of the preceding command. +function Manuscript:find_preceding_command(pos) + local par_pos = self:find_par(pos) + return self:scan(preceding_command_callbacks, par_pos, pos) +end + +--* Indexes and document traversal + +function Manuscript:get_index(name) + name = name .. "_index" + local idx = self[name] + if not idx then + idx = {} + self[name] = idx + end + return idx +end + +function Manuscript:index_pairs(name) + return ipairs(self:get_index(name)) +end + +local function compare_pos(x, y) + return x.pos < y.pos +end + +local function traverse_indexes(script, indexes, max_depth) + local items = {} + for i = 1, #indexes do + local idx_name = indexes[i] + local idx = script[idx_name] + for j = 1, (idx and #idx or 0) do + items[#items+1] = idx[j] + items[idx[j]] = idx_name + end + end + if max_depth > 0 then + local child_index = script.child_index + for i = 1, #child_index do + local item = child_index[i] + local child = script:child(item.name) + if child then + items[#items+1] = { + pos = item.pos, + manuscript = child + } + end + end + end + sort(items, compare_pos) + for i = 1, #items do + local item = items[i] + local kind = items[item] + if kind then + co_yield(item, kind) + else + traverse_indexes(item.manuscript, indexes, max_depth - 1) + end + end +end + +-- Iterator to transverse an index documentwise. This recursevely +-- iterates over entries of the given indexes on self and its +-- children, depth first. An index is a Manuscript field consisting a +-- list of tables containing an entry "pos". At each iteration, +-- yields one index entry and the name of the index to which it +-- belongs. +-- +-- Arguments: +-- indexes: is the name of an index, as a string, or a list of +-- such. +-- max_depth: optional, leave at the default for the recursive +-- behavior or set to 0 to disable it. +-- +function Manuscript:traverse(indexes, max_depth) + if type(indexes) == "string" then indexes = {indexes} end + return co_wrap(function () + return traverse_indexes(self, indexes, max_depth or 15) + end) +end + + +local function argument_items(script, sel, pos, cs) + local args = script.commands[cs].arguments + if not args then return end + local i + if type(sel) == "number" then + i = sel + elseif type(sel) == "string" then + for j = 1, #args do + if args[j].meta == sel then i = j; break end + end + else + i = sel(args) + end + if not i then return end + local ranges = script:parse_command(pos, cs) + local range = ranges[i] + if not range or range.omitted then return end + local arg = args[i] + if arg.list then + local items = script:parse_kvlist(range) + for j = 1, #items do + co_yield(items[j]) + end + else + co_yield(range) + end +end + +-- Iterator to look at arguments of a command. Yields the range of +-- the relevant argument (if present), or succesive ranges +-- corresponding to the argument's subitems, if the argument's `list` +-- property is true. +-- +-- Arguments: +-- sel: determines which argument to look for; it it's a string, the +-- first argument with that meta property is used; otherwise, sel +-- should be a function that takes an `arguments` table and return +-- the relevant index. +-- pos: the position of the command to analyze +-- cs: optional, the name of the command +-- +function Manuscript:argument_items(sel, pos, cs) + return co_wrap(function() return argument_items(self, sel, pos, cs) end) +end + + +--* Manuscript scanning + +-- Scan the Manuscript, executing callbacks for each document element. +-- +-- Each callback is a function taking at least two arguments (a +-- Manuscript object and a source position) and returns at least one +-- value, a position to continue scanning or nil to interrupt the +-- process. When this happens, scan function returns the remaining +-- return values of the callback. The remaining arguments and return +-- values of a callback can be used to keep track of an internal +-- state. +-- +-- The callbacks argument is a table. Its keys correspond to either +-- the "action" field of a command, or the "type" field of an item +-- found by the parser ("cs", "mathshift" or "par"). +-- +function Manuscript:scan(callbacks, pos, ...) + local patt = self.parser.scan_patt(callbacks) + local match = patt.match + local commands = self.commands + local src = self.src + local function scan(pos0, ...) + if not pos0 then return ... end + local pos1, kind, detail, pos2 = match(patt, src, pos0) + local cmd = (kind == "cs") and commands[detail] + local cb = cmd and callbacks[cmd.action] or callbacks[kind] + if cb then + return scan(cb(self, pos1, detail, ...)) + else + return scan(pos2, ...) + end + end + return scan(pos or 1, ...) +end + +-- Copy entries from t to s, but only if not already present. +local function copy_new(s, t) + for k, v in pairs(t) do + if not s[k] then s[k] = v end + end +end + +-- Adds a package to the manuscript. This entails copying the command +-- and environment definitions from the package tags to the +-- manuscript. Returns true if package is (or already was) present, +-- nil if the package tags weren't not found. +function Manuscript:add_package(name) + if self.packages[name] then return true end + local pkg = require_data(name) + if not pkg then return end + self.packages[name] = pkg + local deps = pkg.dependencies or pkg.package and pkg.package.dependencies -- TODO: use only the former case + if deps then + for _, n in ipairs(deps) do + self:add_package(n) + end + end + -- Don't overwrite stuff from generated data files + local update_fn = pkg.generated and copy_new or update + if pkg.commands then + update_fn(self.commands, pkg.commands) + end + if pkg.environments then + update_fn(self.environments, pkg.environments) + end + return true +end + +function Manuscript:find_manuscript(filename) + if self.filename == filename then return self end + local idx = self.child_index + for i = 1, #idx do + local script = self:child(idx[i].name) + local found = script and script:find_manuscript(filename) + if found then return found end + end + return nil +end + +--* Getting the local context + +-- The context at a given manuscript postion is described by a linked +-- list list of ranges, starting from the innermost, with additional +-- annotations. More specifically, the following fields are possible +-- in a context description table: +-- +-- pos: the starting position +-- cont: the ending postiion (exclusive) +-- parent: a similar table, with range including the current range +-- cs: if present, indicates that this range correspond to a command +-- and its arguments. The value of this field is the command name. +-- env: if present, indicates that this range correspond to an +-- environment beginning and its arguments. The value of this field +-- is the environment name. +-- arg: if present, indicates that this range is a command argument. +-- The value corresponds to the argument number. The parent is of +-- "cs" or "env" type. +-- key: if present, indicates this range is one item in a plain list +-- or key-value list. The value of this field is the key text. +-- value: if present, indicates this range is the value of a key in a +-- key-value list. the parent is of "key" type. +-- data: in each case above, data contains the corresponding data +-- object, for instance the command description. +-- + +-- Scan the current paragraph, returning the context around the given +-- position. +function Manuscript:get_context(pos) + return self:scan(self.context_callbacks, self:find_par(pos), nil, pos) +end + +local function local_scan_parse_keys(m, context, pos) + local items = m:parse_kvlist(context) + for _, it in ipairs(items) do -- are we inside a key/list item? + if it.pos and it.pos <= pos and pos <= it.cont then + local key = m:substring_trimmed(it.key) + context = { + key = key, + data = nested_get(context.data, "keys", key), -- or fetch context-dependent keys, say on a usepackage + pos = it.pos, + cont = it.cont, + parent = context + } + local v = it.value + if v and v.pos and v.pos <= pos and pos <= v.cont then -- are we inside the value of a key? + local value = m:substring_trimmed(v) + context = { + value = value, + data = nested_get(context.data, "values", value), -- what if "value" is command-like? + pos = v.pos, + cont = v.cont, + parent = context + } + end + break + end + end + return context +end + +local function local_scan_parse_list(m, context, pos) + local items = m:parse_kvlist(context) + for i = 1, #items do -- are we inside a key/list item? + local it = items[i] + if it.pos and it.pos <= pos and pos <= it.cont then + context = { + item = i, + pos = it.pos, + cont = it.cont, + parent = context + } + end + end + return context +end + +Manuscript.context_callbacks = {} + +function Manuscript.context_callbacks.cs(self, pos, cs, context, end_pos) + if pos > end_pos then return nil, context end -- stop parse + local r = self:parse_command(pos, cs) + if end_pos <= r.cont then + context = { + cs = cs, + data = self.commands[cs], + pos = pos, + cont = r.cont, + parent = context + } + elseif cs == "begin" then + local env_name = self:substring(r[1]) + local env = self.environments[env_name] + local args = env and env.arguments + if not args then return r.cont, context, end_pos end + local q = self.parser.parse_args(args, self.src, r.cont) + if q.cont < end_pos then + return q.cont, context, end_pos -- end_pos is after current thing + end + context = { + env = env_name, + data = self.environments[env_name], + pos = pos, + cont = q.cont, + parent = context + } + r = q + else -- pos is after current thing + return r.cont, context, end_pos + end + + for i, arg in ipairs(r) do -- are we inside an argument? + if arg.pos and arg.pos <= end_pos and end_pos <= arg.cont then + local data = nested_get(context.data, "arguments", i) + context = { + arg = i, + data = data, + pos = arg.pos, + cont = arg.cont, + parent = context + } + if data and data.keys then + context = local_scan_parse_keys(self, context, end_pos) + elseif data and data.list then + context = local_scan_parse_list(self, context, end_pos) + end + return context.pos, context, end_pos + end + end + return nil, context -- stop parse +end + +function Manuscript.context_callbacks.tikzpath(m, pos, cs, context, end_pos) + if pos > end_pos then return nil, context end -- stop parse + local r = m:parse_command(pos, cs) + if end_pos <= r.cont then + context = { + cs = cs, + data = m.commands[cs], + pos = pos, + cont = r.cont, + parent = context + } + local p = r[1].pos + while p <= end_pos do + local q = m.parser.skip_to_bracketed(m.src, p) + if q and q.pos <= end_pos and end_pos <= q.cont then + context = { + arg = true, + data = {keys = require_data"tikz".keys.tikz}, + pos = q.pos, + cont = q.cont, + parent = context + } + context = local_scan_parse_keys(m, context, end_pos) + end + p = q and q.cont or infty + end + end + return r.cont, context, end_pos +end + +function Manuscript.context_callbacks.par (_, _, _, context) + return nil, context +end + +--* Snippets and pretty-printing commands + +-- Pretty-print an argument list. +-- +-- Arguments: +-- args: A list of argument descriptors +-- before: A piece of text inserted at the beginning of the +-- formatted argument list. +-- Returns: +-- The formatted argument list (as a string) and a list of numbers +-- (of length twice that of args) indicating the positions of each +-- argument within that string. +-- +function Manuscript:signature_args(args, before) + if not args then return before or "", {} end + local t, p, pos = {before}, {}, 1 + (before and #before or 0) + for i = 1, #args do + local arg, l, r = args[i] + if arg.literal then + l, r = "", "" + elseif arg.delimiters == false then + l, r = "‹", "›" + elseif arg.delimiters then + l, r = arg.delimiters[1], arg.delimiters[2] + if r == "\n" then r = "⤶" end + if l == "" then l, r = "‹", "›" .. r end + else + l, r = "{", "}" + end + local text = arg.literal or arg.meta or "#" .. i + t[#t+1] = l; pos = pos + #l; p[#p+1] = pos + t[#t+1] = text; pos = pos + #text; p[#p+1] = pos + t[#t+1] = r; pos = pos + #r + end + return concat(t), p +end + +-- Pretty-print a command signature. +-- +-- Arguments: +-- cs: The command name. +-- args: An argument list, or nil. +-- +function Manuscript:signature_cmd(cs, args) + return self:signature_args(args, "\\" .. cs) +end + +-- This is for plain TeX. Other formats should override this +-- definition. +Manuscript.signature_env = Manuscript.signature_cmd + +-- Make a snippet fragment from an argument list. +-- +-- Arguments: +-- args: An argument list +-- i (optional, default 1): The number of the first placeholder in +-- the snippet. +-- +-- Returns: +-- The formatted snippet, as a string, without the $0 placeholder. +-- +function Manuscript:snippet_args(args, i) + if not args then return "" end + i = i or 1 + local t = {} + for _, arg in ipairs(args) do + if arg.optional then + t[#t+1] = "${" .. i .. ":" + i = i + 1 + end + if arg.literal then + t[#t+1] = arg.literal + else + local delims, l, r = arg.delimiters + local meta = arg.meta + if delims then + l, r = delims[1], delims[2] + if l == "" then meta = "‹" .. meta .. "›" end + elseif delims == false then + l, r = "", "" + meta = "‹" .. meta .. "›" + else -- delims == nil + l, r = "{", "}" + end + t[#t+1] = l .. "${" .. i .. (meta and ":" .. meta or "") .. "}" .. r + i = i + 1 + end + if arg.optional then t[#t+1] = "}" end + end + return concat(t) +end + +-- Make a snippet for a command. +function Manuscript:snippet_cmd(cs, args) + local argsnippet = args and self:snippet_args(args) or "" + return cs .. argsnippet .. "$0" +end + +-- Make a snippet for an environment. +-- +-- This is the plain TeX version. It's intended to be overwritten by +-- other classes. +-- +function Manuscript:snippet_env(cs, args) + local argsnippet = args and self:snippet_args(args) or "" + return cs .. argsnippet .. "\n\t$0\n\\end" .. cs +end + + +--* Completion + +-- Calculate completions for the manuscript at the given position. +-- Returns a a table containing a list of completion items (at +-- numerical indices) and some addition information in the following +-- fields. +-- +-- pos: position where the matched text starts +-- prefix: the matched text +-- kind: whether the completions are for a command, a key, etc. +-- +function Manuscript:complete(pos) + local ctx = self:get_context(pos - 1) + if ctx == nil then + return + elseif ctx.cs and pos == ctx.cont then + return self.completion_handlers.cs(self, ctx) + elseif ctx.arg then + local action = nested_get(ctx, "parent", "data", "action") + local handler = self.completion_handlers[action] + return handler and handler(self, ctx, pos) + elseif ctx.item then + local action = nested_get(ctx, "parent", "parent", "data", "action") + local handler = self.completion_handlers[action] + return handler and handler(self, ctx, pos) + elseif ctx.key then --and pos == ctx.pos + #ctx.key then + return self.completion_handlers.key(self, ctx, pos) + elseif ctx.value and pos == ctx.pos + #ctx.value then + return self.completion_handlers.value(self, ctx, pos) + end +end + +Manuscript.completion_handlers = {} + +function Manuscript.completion_handlers.cs(self, ctx) + local commands, environments = self.commands, self.environments + local extra_snippets = config.extra_snippets + local prefix = ctx.cs + local ret = { + pos = ctx.pos + 1, + prefix = prefix, + kind = "command" + } + for cs in pairs(map_keys(self.parser.cs_matcher(prefix), commands)) do + local cmd = commands[cs] + local args = cmd.arguments + local snippet = extra_snippets[cs] or cmd.snippet + ret[#ret+1] = { + text = cs, + summary = cmd.summary, + annotation = args and self:signature_args(args) or cmd.symbol, + snippet = snippet or args and self:snippet_cmd(cs, args) + } + end + for env in pairs(map_keys(matcher(prefix), environments)) do + local cmd = environments[env] + local args = cmd.arguments + local snippet = extra_snippets[env] or cmd.snippet + local annotation = args and self:signature_args(args) + ret[#ret+1] = { + text = env, + summary = cmd.summary, + annotation = (annotation and annotation .. " " or "") .. "(environment)", + snippet = snippet or self:snippet_env(env, args) + } + end + table.sort(ret, function(x,y) return x.text < y.text end) + return ret +end + +function Manuscript.completion_handlers.key(self, ctx, pos) + local prefix = self:substring(ctx.pos, pos - 1) + local len = #prefix + local r = { + pos = ctx.pos, + prefix = prefix, + kind = "key" + } + local keys = ctx.parent and ctx.parent.data and ctx.parent.data.keys + for text, key in pairs(keys or {}) do + if prefix == text:sub(1, len) then + r[#r+1] = { + text = text, + summary = key.summary, + annotation = key.meta and ("=" .. key.meta) + } + end + end + table.sort(r, function(x,y) return x.text < y.text end) + return r +end + +function Manuscript.completion_handlers.value(self, ctx, pos) + local prefix = self:substring(ctx.pos, pos - 1) + local len = #prefix + local r = { + pos = ctx.pos, + prefix = prefix, + kind = "value" + } + local values = ctx.parent and ctx.parent.data and ctx.parent.data.values + for text, value in pairs(values or {}) do + if prefix == text:sub(1, len) then + r[#r+1] = { + text = text, + summary = value.summary + } + end + end + return r +end + +function Manuscript.completion_handlers.begin(self, ctx, pos) + local environments = self.environments + local prefix = self:substring(ctx.pos, pos - 1) + local has_prefix = matcher(prefix) + local r = { + pos = ctx.pos, + prefix = prefix, + kind = "environment" + } + for env in pairs(map_keys(has_prefix, environments)) do + local cmd = environments[env] + r[#r+1] = { + text = env, + summary = cmd.summary, + } + end + return r +end + +Manuscript.completion_handlers["end"] = Manuscript.completion_handlers.begin + +-- Get a short piece of text around a label. If there is a recognized +-- command ending right before the label, the context starts there. +-- +-- TODO: For now, the context is 60 bytes, but it should be smart and +-- choose a lenght close to 100 characters but ending at a line end. +-- It should also be Unicode-safe. +-- +function Manuscript:label_context_short(item) + local pos, cs, _ = self:find_preceding_command(item.outer_pos) + local cmd = self.commands[cs] + if not cmd then + pos = self.parser.next_nonblank(self.src, item.outer_pos) + end + return self:substring_clean(pos, pos + 60) +end + +function Manuscript.completion_handlers.ref(self, ctx, pos) + local prefix = self:substring(ctx.pos, pos - 1) + local has_prefix = matcher(prefix) + local fuzzy_match = config.fuzzy_ref and fuzzy_matcher(prefix) + local scores = {} + local r = { + pos = ctx.pos, + prefix = prefix, + kind = "label" + } + for label in self.root:traverse "label_index" do + local short_ctx = label.manuscript:label_context_short(label) + local score = has_prefix(label.name) and infty + or fuzzy_match and fuzzy_match(short_ctx) + if score then + r[#r+1] = { + text = label.name, + annotation = short_ctx, + summary = label.manuscript:label_context_long(label), + fuzzy_score = score < infty and score or nil + } + scores[r[#r]] = score + end + end + -- sort exact matches by order in the document, fuzzy ones by score + sort(r, function(a, b) return scores[a] > scores[b] end) + return r +end + +function Manuscript.completion_handlers.cite(self, ctx, pos) + if nested_get(ctx, "data", "optional") then return end + local prefix = self:substring(ctx.pos, pos - 1) + local r = { + pos = ctx.pos, + prefix = prefix, + kind = "bibitem" + } + local scores = {} + local has_prefix = matcher(prefix) + local fuzzy_match = config.fuzzy_cite and fuzzy_matcher(prefix) + for item in self.root:traverse "bib_index" do + local score = has_prefix(item.name) and infty + or fuzzy_match and item.text and fuzzy_match(item.text) + if score then + scores[item.name] = score + r[#r+1] = { + text = item.name, + annotation = item.text, + fuzzy_score = score < infty and score or nil + } + end + end + -- sort exact matches by label, fuzzy matches by score + local cmp = function(a, b) + local na, nb = a.text, b.text + local sa, sb = scores[na], scores[nb] + if sa == sb then + return (na < nb) + else + return (sa > sb) + end + end + sort(r, cmp) + return r +end + +--* Context help + +-- Get information about the thing at the given position. +function Manuscript:describe(pos) + local ctx = self:get_context(pos) + if not ctx then return nil end + local action = ctx.arg and nested_get(ctx, "parent", "data", "action") + or ctx.item and nested_get(ctx, "parent", "parent", "data", "action") + local handlers = self.help_handlers + if handlers[action] then + return handlers[action](self, ctx) + elseif ctx.cs then + return handlers.cs(self, ctx) + elseif ctx.arg then + return handlers.arg(self, ctx) + -- elseif ctx.list then + elseif ctx.key then + return handlers.key(self, ctx) + else + return nil + end +end + +Manuscript.help_handlers = {} + +function Manuscript.help_handlers.cite(self, ctx) + local name = self:substring(ctx) + for item in self.root:traverse "bib_index" do + if name == item.name then + local script, details = item.manuscript + if script.format == "bibtex" then + details = format( + [[ +`%s`: %s + +# Bibtex definition + +```bibtex +%s +``` +]], + item.name, + item.text, + script:substring(item) + ) + end + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "bibitem", + summary = item.name .. " " .. item.text, + details = details + } + end + end +end + +function Manuscript:label_context_long(item) + local pos = self:find_preceding_command(item.outer_pos) + if not pos then pos = item.outer_pos end + local l = self:line_number_at(pos) + local lines = self.lines + local end_pos = lines[l + 10] + if end_pos then + return self:substring_trimmed(pos, end_pos - 1) + else + return self:substring_trimmed(pos, -1) + end +end + +function Manuscript.help_handlers.ref(self, ctx) + local name = self:substring(ctx) + for item in self.root:traverse "label_index" do + if name == item.name then + local script = item.manuscript + local short_context = script:label_context_short(item) + local long_context = script:label_context_long(item) + local details = format( + [[ +`%s`: Refers to “%s...” + +# Label context + +```%s +%s +[...] +``` +]], + item.name, + short_context, + script.format, + long_context + ) + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "label", + label = name, + summary = short_context, + details = details + } + end + end + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "label", + label = name, + summary = "Unknown label" + } +end + +function Manuscript.help_handlers.begin(self, ctx) + local env_name = self:substring(ctx) + local data = self.environments[env_name] + if not data then return nil end + local args = data.arguments + local sig_text, sig_pos = self:signature_env(env_name, args) + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "environment", + label = sig_text, + label_positions = sig_pos, + summary = data.summary, + details = self:make_docstring("env", env_name, data), + data = data + } +end + +Manuscript.help_handlers['end'] = function(self, ctx) + local env_name = self:substring(ctx) + local data = self.environments[env_name] + if not data then return nil end + local args = data.arguments + local sig_text, sig_pos = self:signature_env(env_name, args) + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "environment", + label = sig_text, + label_positions = sig_pos, + summary = data.summary, + details = self:make_docstring("env", env_name, data), + data = data + } +end + +function Manuscript.help_handlers.cs(self, ctx) + local data = ctx.data + if not data then return nil end + local args = data.arguments + local sig_text, sig_pos = self:signature_cmd(ctx.cs, args) + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "command", + label = sig_text, + label_positions = sig_pos, + summary = data.summary, + details = self:make_docstring("cs", ctx.cs, data), + data = data + } +end + +function Manuscript.help_handlers.arg(self, ctx) + if ctx.parent.cs then + return update( + self.help_handlers.cs(self, ctx.parent), + {pos = ctx.pos, cont = ctx.cont, arg = ctx.arg}) + end +end + +function Manuscript.help_handlers.key(self, ctx) + local key = ctx.key + local data = nested_get(ctx.parent, "data", "keys", key) + if not data then return nil end + return { + pos = ctx.pos, + cont = ctx.cont, + kind = "key", + label = key, + summary = data.summary, + details = self:make_docstring("key", key, data), + data = data + } +end + +function Manuscript:make_docstring_header(kind, name, data) + local ret = name + if kind == "cs" then + ret = self:signature_cmd(name, data.arguments) + elseif kind == "env" then + ret = self:signature_env(name, data.arguments) + elseif kind == "key" and data.meta then + ret = ret .. " = " .. data.meta + end + if data.summary then + ret = "`" .. ret .. "`: " .. data.summary + else + ret = "`" .. ret .. "`" + end + if data.symbol then + ret = ret .. " (" .. data.symbol .. ")" + end + return ret +end + +local function make_docstring_args(data) + local t = {"# Arguments\n"} + local args = data.arguments + if args then + for i = 1, #args do + local arg = args[i] + if arg.summary then + t[#t+1] = "- " .. (arg.meta or "#" .. i) + .. (arg.optional and " (optional): " or ": ") + .. arg.summary + end + end + t[#t+1] = "" + end + if #t > 2 then return concat(t, "\n") end +end + +function Manuscript:make_docstring_variants(kind, name, data) + local variants = data.variants + if not variants then return end + local t = {"# Alternative forms\n"} + local fun = (kind == "env") and self.signature_env or self.signature_cmd + for i = 1, #variants do + t[#t+1] = "- `" .. fun(self, name, variants[i].arguments) .. "`" + end + t[#t+1] = "" + return concat(t, "\n") +end + +local function make_docstring_details(data) + local details = data.details + local doc_field = data.documentation + if details then + return "# Details\n\n" .. details + elseif type(doc_field) == "string" and doc_field:match"^info:" then + local str, node, subnode = get_info(doc_field) + if str then + return format("# Info: (%s)%s\n\n```Info\n%s```", node, subnode, str) + end + else + return + end +end + +function Manuscript:make_docstring_docs(kind, name, data) + local item_doc = data.documentation + local pkg = data.package + local pkg_doc = pkg and pkg.documentation + local t = {"# Documentation\n"} + if pkg and pkg.ctan_package then + if kind == "env" then + name = "{" .. name .. "}" + elseif kind == "cs" then + name = self:signature_cmd(name) + end + t[#t+1] = format( + "`%s` is defined in the [%s](https://www.ctan.org/pkg/%s) package.\n", + name, pkg.ctan_package, pkg.ctan_package + ) + end + if item_doc then + extend(t, resolve_doc_items(item_doc)) + end + if pkg_doc then + extend(t, resolve_doc_items(pkg_doc)) + end + if #t > 1 then return concat(t, "\n") else return end +end + +function Manuscript:make_docstring(kind, name, data) + local t = {self:make_docstring_header(kind, name, data), ""} + t[#t+1] = make_docstring_args(data) + t[#t+1] = self:make_docstring_variants(kind, name, data) + t[#t+1] = make_docstring_details(data) + t[#t+1] = self:make_docstring_docs(kind, name, data) + return concat(t, "\n") +end + +--* Find definition + +-- Find the location where the thing at the given position is defined. +function Manuscript:find_definition(pos) + local ctx = self:get_context(pos) + if not ctx then return nil end + local action = ctx.arg and nested_get(ctx, "parent", "data", "action") + or ctx.item and nested_get(ctx, "parent", "parent", "data", "action") + local handlers = self.find_definition_handlers + if handlers[action] then + return handlers[action](self, ctx) + elseif ctx.cs then + return handlers.cs(self, ctx) + else + return nil + end +end + +Manuscript.find_definition_handlers = {} + +function Manuscript.find_definition_handlers.ref(self, ctx) + local name = self:substring(ctx) + for item in self.root:traverse "label_index" do + if name == item.name then + return { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "label" + } + end + end +end + +function Manuscript.find_definition_handlers.cite(self, ctx) + local name = self:substring(ctx) + for item in self.root:traverse "bib_index" do + if name == item.name then + return { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "bibitem" + } + end + end +end + +function Manuscript.find_definition_handlers.cs(self, ctx) + local name = ctx.cs + for item in self.root:traverse "newcommand_index" do + if name == item.name then + return { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "cs" + } + end + end +end + +function Manuscript.find_definition_handlers.begin(self, ctx) + local name = self:substring(ctx) + for item in self.root:traverse "newenvironment_index" do + if name == item.name then + return { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "env" + } + end + end +end + +Manuscript.find_definition_handlers["end"] + = Manuscript.find_definition_handlers.begin + +function Manuscript.find_definition_handlers.input(self, ctx) + local template + if ctx.arg then + template = nested_get(ctx, "parent", "data", "filename") or "?" + elseif ctx.item then + template = nested_get(ctx, "parent", "parent", "data", "filename") or "?" + else + return + end + local basename = format_filename_template(template, self:substring(ctx)) + local filename = find_file(path_split(self.filename), basename) + if not filename then return end + local child = self:find_manuscript(path_normalize(filename)) + if child then + return { + pos = 1, + cont = 1, + manuscript = child, + kind = "manuscript" + } + end +end + +--* Find references + +function Manuscript:scan_references() + if not self.ref_index then + self.ref_index = {} + self.cite_index = {} + self:scan(self.scan_references_callbacks) + end + local idx = self.child_index + for i = 1, #idx do + local script = self:child(idx[i].name) + if script then script:scan_references() end + end +end + +Manuscript.scan_references_callbacks = {} + +function Manuscript:scan_control_sequences() + if not self.cs_index then + self.cs_index = {} + self:scan(self.scan_cs_callbacks) + end + local idx = self.child_index + for i = 1, #idx do + local script = self:child(idx[i].name) + if script then script:scan_control_sequences() end + end +end + +Manuscript.scan_cs_callbacks = {} + +function Manuscript.scan_cs_callbacks.cs(self, pos, cs) + local idx = self.cs_index + local cont = pos + 1 + #cs + idx[#idx + 1] = { + name = cs, + pos = pos, + cont = cont, + manuscript = self, + } + return cont +end + +-- List all references to the thing at the given position. +-- +-- Returns: +-- A list of annotated ranges. +-- +function Manuscript:find_references(pos) + local ctx = self:get_context(pos) + if not ctx then return nil end + local action = ctx.arg and nested_get(ctx, "parent", "data", "action") + or ctx.item and nested_get(ctx, "parent", "parent", "data", "action") + local handlers = self.find_references_handlers + if handlers[action] then + self.root:scan_references() + return handlers[action](self, ctx) + elseif ctx.cs then + self.root:scan_control_sequences() + return handlers.cs(self, ctx) + else + return nil + end +end + +Manuscript.find_references_handlers = {} + +function Manuscript.find_references_handlers.cs(self, ctx) + local name = ctx.cs + local r = {} + for item in self.root:traverse "cs_index" do + if name == item.name then + r[#r + 1] = { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "cs" + } + end + end + return r +end + +function Manuscript.find_references_handlers.ref(self, ctx) + local name = self:substring(ctx) + local r = {} + for item in self.root:traverse "ref_index" do + if name == item.name then + r[#r + 1] = { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "label" + } + end + end + return r +end + +Manuscript.find_references_handlers.label = + Manuscript.find_references_handlers.ref + +function Manuscript.find_references_handlers.cite(self, ctx) + local name = self:substring(ctx) + local r = {} + for item in self.root:traverse "cite_index" do + if name == item.name then + r[#r + 1] = { + pos = item.pos, + cont = item.cont, + manuscript = item.manuscript, + kind = "bibitem" + } + end + end + return r +end + +--* Outline + +-- Compute a table of contents for the document. If loc is false or +-- omitted, include children of the manuscript; otherwise, restrict to +-- the current manuscript. +-- +function Manuscript:outline(loc) + local val = {} + for it in self:traverse("section_index", loc and 0) do + local lv = it.level or infty + local t = val + while t[#t] and (t[#t].level or -infty) < lv do t = t[#t] end + t[#t + 1] = { + name = it.name, + pos = it.pos, + cont = it.cont, + level = lv, + manuscript = it.manuscript, + kind = "section" + } + end + return val +end + +return Manuscript diff --git a/support/digestif/digestif/ManuscriptBibTeX.lua b/support/digestif/digestif/ManuscriptBibTeX.lua new file mode 100644 index 0000000000..219f4552b4 --- /dev/null +++ b/support/digestif/digestif/ManuscriptBibTeX.lua @@ -0,0 +1,38 @@ +local lpeg = require "lpeg" +local util = require "digestif.util" +local Manuscript = require "digestif.Manuscript" +local Parser = require "digestif.Parser" +local bibtex = require "digestif.bibtex" + +local path_join, path_split = util.path_join, util.path_split +local nested_get, nested_put = util.nested_get, util.nested_put +local map, update, merge = util.map, util.update, util.merge + +local ManuscriptBibtex = util.class(Manuscript) + +ManuscriptBibtex.parser = Parser() +ManuscriptBibtex.format = "bibtex" +ManuscriptBibtex.packages = {} +ManuscriptBibtex.commands = {} +ManuscriptBibtex.environments = {} +ManuscriptBibtex.init_callbacks = false -- Skip the normal init scan +ManuscriptBibtex:add_package("plain") -- For basic command completion + +function ManuscriptBibtex:__init(args) + Manuscript.__init(self, args) + local bibitems = bibtex.parse(self.src) + local idx = {} + self.bib_index = idx + for i, item in ipairs(bibitems) do + idx[i] = { + name = item.id, + pos = item.pos, + cont = item.cont, + manuscript = self, + text = item:pretty_print(), + bibitem = item, + } + end +end + +return ManuscriptBibtex diff --git a/support/digestif/digestif/ManuscriptConTeXt.lua b/support/digestif/digestif/ManuscriptConTeXt.lua new file mode 100644 index 0000000000..2243d3a9fc --- /dev/null +++ b/support/digestif/digestif/ManuscriptConTeXt.lua @@ -0,0 +1,604 @@ +local util = require "digestif.util" +local Manuscript = require "digestif.Manuscript" +local Parser = require "digestif.Parser" + +local co_wrap, co_yield = coroutine.wrap, coroutine.yield +local merge = util.merge +local path_join, path_split = util.path_join, util.path_split +local path_normalize = util.path_normalize +local format_filename_template = util.format_filename_template +local table_move, table_insert = table.move, table.insert + +--* Parsing ConTeXt interface files + +--** XML parser by Roberto Ierusalimschy +-- +-- Cf. http://lua-users.org/wiki/LuaXml + +local function parseargs(s) + local arg = {} + string.gsub(s, "([%w:_-]+)=([\"'])(.-)%2", function (w, _, a) + arg[w] = a + end) + return arg +end + +local function collect(s) + local stack = {} + local top = {} + table.insert(stack, top) + local ni,c,label,xarg, empty + local i, j = 1, 1 + while true do + ni,j,c,label,xarg, empty = string.find(s, "<(%/?)([%w:]+)(.-)(%/?)>", i) + if not ni then break end + local text = string.sub(s, i, ni-1) + if not string.find(text, "^%s*$") then + table.insert(top, text) + end + if empty == "/" then -- empty element tag + table.insert(top, {label=label, xarg=parseargs(xarg), empty=1}) + elseif c == "" then -- start tag + top = {label=label, xarg=parseargs(xarg)} + table.insert(stack, top) -- new level + else -- end tag + local toclose = table.remove(stack) -- remove top + top = stack[#stack] + if #stack < 1 then + error("nothing to close with "..label) + end + if toclose.label ~= label then + error("trying to close "..toclose.label.." with "..label) + end + table.insert(top, toclose) + end + i = j+1 + end + local text = string.sub(s, i) + if not string.find(text, "^%s*$") then + table.insert(stack[#stack], text) + end + if #stack > 1 then + error("unclosed "..stack[#stack].label) + end + return stack[1] +end + +local function child_with_label(node, label) + for _, n in ipairs(node) do + if n.label == label then return n end + end +end + +local function children_with_label(node, label) + local function iter(n, l) + if n.label == l then + co_yield(n) + else + for _, m in ipairs(n) do + iter(m, l) + end + end + end + return co_wrap(function() return iter(node, label) end) +end + +--** Parse ConTeXt interface (XML) files + +local braces = {"{", "}"} +local brackets = {"[", "]"} +local parenthesis = {"(", ")"} + +local function gen_tags(data) + + local inheritances = {} + local inherit_type = {} + local inherit_order = {} + + local function compute_meta(node) + local fromtag = node.label:gsub('^cd:', '') + local tbl = {} + local other = 0 + for _, child in ipairs(node) do + local attribs = child.xarg + local val = attribs.type + if val and val:match"^cd:" then + tbl[#tbl+1]=val:sub(4) + else + other = other + 1 + end + end + if other == 0 and #tbl == 1 then + return tbl[1] + else + return fromtag + end + end + + local function compute_values(node) + local tbl = {} + for _, child in ipairs(node) do + if child.label == "cd:constant" then + local val = child.xarg.type + if not val:match"^cd:" then tbl[#tbl+1] = val end + elseif child.label == "cd:inherit" then + local val = child.xarg.name + if not inheritances[tbl] then inheritances[tbl] = {} end + local inh = inheritances[tbl] + inherit_type[tbl] = "values" + inherit_order[#inherit_order+1] = tbl + inh[#inh+1] = val + end + end + return #tbl > 0 and tbl or nil + end + + local function compute_keys(node) + local tbl = {} + for _, child in ipairs(node) do + if child.label == "cd:parameter" then + local val = child.xarg.name + tbl[val] = { + values = compute_values(child), + meta = compute_meta(child) + } + elseif child.label == "cd:inherit" then + local val = child.xarg.name + if not inheritances[tbl] then inheritances[tbl] = {} end + local inh = inheritances[tbl] + inherit_type[tbl] = "keys" + inherit_order[#inherit_order+1] = tbl + inh[#inh+1] = val + end + end + return tbl + end + + local function compute_argument(node) + local ret = {delimiters=brackets} + local attrs = node.xarg + if attrs.optional == 'yes' then ret.optional = true end + if attrs.list == 'yes' then ret.list = true end + if node.label == "cd:keywords" then + ret.meta=compute_meta(node) + ret.values = compute_values(node) + elseif node.label == "cd:assignments" then + ret.meta="assignments" + ret.keys = compute_keys(node) + elseif node.label == "cd:constant" then + ret.meta = node.xarg.type:gsub('^cd:', '') + elseif node.label == "cd:content" then + ret.meta="content" + ret.delimiters = braces + elseif node.label == "cd:csname" then + ret.meta="command" + ret.type="cs" + ret.delimiters = nil + elseif node.label == "cd:dimension" then + ret.meta = "dimension" + ret.type="dimen" + end + if attrs.delimiters == 'braces' then ret.delimiters = braces end + if attrs.delimiters == 'parenthesis' then ret.delimiters = parenthesis end + if attrs.delimiters == 'none' then ret.delimiters = false end + return ret + end + + local function compute_arguments(node) + local tbl = {} + for _, child in ipairs(node) do + tbl[#tbl+1] = compute_argument(child) + end + return tbl + end + + local function compute_instances(name, node) + local tbl = {} + if node == nil then return tbl end + for _, instance in ipairs(node) do + local inst_name = instance.xarg.value + if name ~= inst_name then + tbl[#tbl+1] = inst_name + end + end + return tbl + end + + local command_list = {} + for node in children_with_label(data, "cd:command") do + local attribs = node.xarg + local arguments = child_with_label(node, "cd:arguments") + arguments = arguments and compute_arguments(arguments) + local cmd = { + cs = attribs.name, + environment = (attribs.type == "environment"), + --source = attribs.file, + --category = attribs.category, + arguments = arguments, + } + command_list[#command_list+1] = cmd + + local instances = compute_instances( + attribs.name, child_with_label(node, "cd:instances")) + for _, name in ipairs(instances) do + command_list[#command_list+1] = merge(cmd, {cs = name}) + end + end + + -- FIXME: need to distinguish when doing + local cmds_and_envs = {} + for _, cmd in ipairs(command_list) do + local cs = cmd.cs + if cmd.link or not cmds_and_envs[cs] then + cmds_and_envs[cs] = cmd + end + end + + for _, tbl in ipairs(inherit_order) do + local inh = inheritances[tbl] + --print("\n\nbefore", ser(tbl)) + for _, cs in ipairs(inh) do + for _, arg in ipairs((cmds_and_envs[cs] or {}).arguments or {}) do + util.update(tbl, arg[inherit_type[tbl]] or {}) + end + end + --print("\nafter", ser(tbl)) + end + + local tags = { + generated = true, + commands = {}, + environments = {} + + } + + for _, cmd in ipairs(command_list) do + local cs = cmd.cs + local list = cmd.environment and tags.environments or tags.commands + local wikiname = cmd.environment and "start" .. cs or cs + cmd.documentation = { + [1] = { + summary = "“" .. wikiname .. "” on ConTeXt Garden", + uri = "https://wiki.contextgarden.net/Command/" .. wikiname + } + } + cmd.environment, cmd.cs = nil, nil + if not list[cs] then + list[cs] = cmd + else + local variants = list[cs].variants + if not variants then + variants = {} + list[cs].variants = variants + end + variants[#variants+1] = cmd + end + end + + return tags +end + +-- Generate tags from a ConTeXt interface (XML) file. +-- +-- Arguments: +-- file: The file name. +-- pkg: An optional package description table. +-- +-- Returns: +-- The tags, or nil if file does not exist. +-- +local function tags_from_xml(file, pkg) + local ok, str = util.find_file(file, nil, true) + if not ok then return end + local ok, data = pcall(collect, str) + if not ok then return end + return setmetatable(gen_tags(data), {__index = pkg}) +end + +-- Monkey-patch to isolate XML dependency in this file. +(require "digestif.data").tags_from_xml = tags_from_xml + +--** Core ConTeXt tags + +local ctx_tags = (require "digestif.data".require_tags)("context-en.xml") + +if ctx_tags then + + ctx_tags.ctan_package = "context" + + ctx_tags.documentation = { + [1] = { + summary = "ConTeXt Mark IV: an excursion", + uri = "texmf:doc/context/documents/general/manuals/ma-cb-en.pdf" + }, + [2] = { + summary = "ConTeXt documentation library", + uri = "https://wiki.contextgarden.net/Documentation" + } + } + + local commands = ctx_tags.commands + local environments = ctx_tags.environments + + -- Add details to sectioning commands + for _, tbl in ipairs{commands, environments} do + for i, cs in ipairs{ + "part", "chapter", "section", "subsection", "subsubsection", + "subsubsubsection", "subsubsubsubsection" + } do + tbl[cs].section_level = i + tbl[cs].action = "section" + end + for i, cs in ipairs{ + "title", "subject", "subsubject", "subsubsubject", + "subsubsubsubject", "subsubsubsubsubject" + } do + tbl[cs].section_level = i + 1 + tbl[cs].action = "section" + end + end + + -- Add details to file-inputting commands. + for cs, filename in pairs { + environment = "?.tex", + project = "?.tex", + component = "?.tex", + usemodule = "t-?.xml" + } do + if commands[cs] then + commands[cs].action = "input" + commands[cs].filename = filename + end + end + + -- Add details to assorted commands. + for cs, action in pairs { + usebtxdataset = "input", + cite = "cite", + nocite = "cite", + define = "define", + definestartstop = "definestartstop", + defineitemgroup = "definestartstop", + definelist = "definestartstop", + citation = "cite", + nocitation = "cite", + pagereference = "label", + textreference = "label", + ["in"] = "ref", + at = "ref", + about = "ref" + } do + if commands[cs] then + commands[cs].action = action + end + end + + -- Add start/stop commands + for env, cmd in pairs(environments) do + commands["start" .. env] = cmd + commands["stop" .. env] = {} + end + +end + +--* ManuscriptContext class + +local ManuscriptContext = util.class(Manuscript) + +ManuscriptContext.parser = Parser() +ManuscriptContext.format = "context" +ManuscriptContext.packages = {} +ManuscriptContext.commands = {} +ManuscriptContext.environments = {} +ManuscriptContext.init_callbacks = {} +ManuscriptContext.scan_references_callbacks = {} +ManuscriptContext:add_package("context-en.xml") + +-- Make a snippet for an environment. +function ManuscriptContext:snippet_env(cs, args) + local argsnippet = args and self:snippet_args(args) or "" + return "start" .. cs .. argsnippet .. "\n\t$0\n\\stop" .. cs +end + +-- ConTeXt optional arguments can't always be distinguished by their +-- delimiters, for instance \citation[optional][mandatory]. Here we +-- patch Parser.parse_args to deal with this case, but just in the +-- simplest case where the optional arguments are in the beginning of +-- the argument list. +local original_parse_args = ManuscriptContext.parser.parse_args + +local function new_parse_args(arglist, str, pos) + local val = original_parse_args(arglist, str, pos) + if val.incomplete and arglist[1].optional then + arglist = table_move(arglist, 2, #arglist, 1, {}) + val = new_parse_args(arglist, str, pos) + table_insert(val, 1, {omitted = true}) + end + return val +end + +ManuscriptContext.parser.parse_args = new_parse_args + +--* Init scanning + +local to_args = {} +for i = 1, 9 do + local t = merge(to_args[i-1] or {}) + t[i] = {meta = "#" .. i} + to_args[i] = t +end + +function ManuscriptContext.init_callbacks.define(self, pos, cs) + -- ugly! this function (and others below) parses the command twice + local cont = self:parse_command(pos, cs).cont + local csname, n_args + for r in self:argument_items("command", pos, cs) do + csname = self:substring_stripped(r):sub(2) + end + for r in self:argument_items("number", pos, cs) do + n_args = tonumber(self:substring_stripped(r)) + end + if csname then + local idx = self:get_index "newcommand" + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = to_args[n_args] + } + if not self.commands[csname] then + self.commands[csname] = idx[#idx] + end + end + return cont +end + +function ManuscriptContext.init_callbacks.definestartstop(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local name + for r in self:argument_items("name", pos, cs) do + name = self:substring_stripped(r) + end + if name then + local idx = self:get_index "newenvironment" + idx[#idx+1] = { + name = name, + pos = pos, + cont = cont, + manuscript = self, + } + if not self.environments[name] then + self.environments[name] = idx[#idx] + end + end + return cont +end + +function ManuscriptContext.init_callbacks.label(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.label_index + for r in self:argument_items("reference", pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(r), + pos = r.pos, + cont = r.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +function ManuscriptContext.init_callbacks.section(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + for r in self:argument_items("assignments", pos, cs) do + local assigns = self:parse_kvlist(r) + for i = 1, #assigns do + local key = self:substring_stripped(assigns[i].key) + local val = assigns[i].value + if key == "reference" then + local idx = self.label_index + idx[#idx + 1] = { + name = self:substring_stripped(val), + pos = val.pos, + cont = val.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + elseif key == "title" then + local idx = self.section_index + idx[#idx + 1] = { + name = self:substring_stripped(val), + level = self.commands[cs].section_level, + pos = val.pos, + cont = val.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + end + end + for r in self:argument_items("reference", pos, cs) do + local idx = self.label_index + idx[#idx + 1] = { + name = self:substring_stripped(r), + pos = r.pos, + cont = r.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + for r in self:argument_items("text", pos, cs) do + local idx = self.section_index + idx[#idx + 1] = { + name = self:substring_stripped(r), + level = self.commands[cs].section_level, + pos = r.pos, + cont = r.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +function ManuscriptContext.init_callbacks.input(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.child_index + local template = self.commands[cs].filename or "?" + for r in self:argument_items("file", pos, cs) do + local f = format_filename_template(template, self:substring_stripped(r)) + local ok = self:add_package(f) + if not ok then + idx[#idx + 1] = { + name = path_normalize(path_join(path_split(self.filename), f)), + pos = r.pos, + cont = r.cont, + manuscript = self + } + end + end + return cont +end + +--* Reference scanning + +function ManuscriptContext.scan_references_callbacks.ref(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.ref_index + for s in self:argument_items("reference", pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(s), + pos = s.pos, + cont = s.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +function ManuscriptContext.scan_references_callbacks.cite(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.cite_index + for s in self:argument_items("reference", pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(s), + pos = s.pos, + cont = s.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +return ManuscriptContext diff --git a/support/digestif/digestif/ManuscriptDoctex.lua b/support/digestif/digestif/ManuscriptDoctex.lua new file mode 100644 index 0000000000..c3f0c2b0ce --- /dev/null +++ b/support/digestif/digestif/ManuscriptDoctex.lua @@ -0,0 +1,19 @@ +local ManuscriptLatex = require "digestif.ManuscriptLaTeX" +local Parser = require "digestif.Parser" +local lpeg = require "lpeg" +local util = require "digestif.util" + +local ManuscriptDoctex = util.class(ManuscriptLatex) + +-- Consider both code (no prefix) and documentation (starting with a +-- single %) as not being comments. +local comment = (lpeg.B(1) - lpeg.B("\n")) * lpeg.P("%") + +ManuscriptDoctex.format = "doctex" +ManuscriptDoctex.parser = Parser{ + comment = comment, + letter = lpeg.R("az", "@Z") +} +ManuscriptLatex:add_package("latex.ltx") + +return ManuscriptDoctex diff --git a/support/digestif/digestif/ManuscriptLaTeX.lua b/support/digestif/digestif/ManuscriptLaTeX.lua new file mode 100644 index 0000000000..1366b0e146 --- /dev/null +++ b/support/digestif/digestif/ManuscriptLaTeX.lua @@ -0,0 +1,360 @@ +local lpeg = require "lpeg" +local util = require "digestif.util" +local Manuscript = require "digestif.Manuscript" +local Parser = require "digestif.Parser" + +local path_join, path_split = util.path_join, util.path_split +local path_normalize = util.path_normalize +local nested_get, nested_put = util.nested_get, util.nested_put +local map, update, merge = util.map, util.update, util.merge +local format_filename_template = util.format_filename_template + +local ManuscriptLatex = util.class(Manuscript) + +ManuscriptLatex.parser = Parser() +ManuscriptLatex.format = "latex" +ManuscriptLatex.packages = {} +ManuscriptLatex.commands = {} +ManuscriptLatex.environments = {} +ManuscriptLatex.init_callbacks = {} +ManuscriptLatex.scan_references_callbacks = {} +ManuscriptLatex:add_package("latex") + +--* Snippets + +-- Make a snippet for an environment. +-- +-- Arguments: +-- cs: The command name +-- args: An argument list +-- +-- Returns: +-- A snippet string +-- +function ManuscriptLatex:snippet_env(cs, args) + local argsnippet = args and self:snippet_args(args) or "" + return "begin{" .. cs .. "}" .. argsnippet .. "\n\t$0\n\\end{" .. cs .. "}" +end + +-- Pretty-print an environment signature. +function ManuscriptLatex:signature_env(cs, args) + return self:signature_args(args, "\\begin{" .. cs .. "}") +end + +--* Helper functions + +local function first_mand(args) + for i, v in ipairs(args) do + if not v.optional then return i end + end +end + +local function first_opt(args) + for i, v in ipairs(args) do + if v.optional then return i end + end +end + +--* Global scanning + +--** Basic document elements + +function ManuscriptLatex.init_callbacks.input(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.child_index + local template = self.commands[cs].filename or "?" + for r in self:argument_items(first_mand, pos, cs) do + local f = format_filename_template(template, self:substring_stripped(r)) + local ok = self:add_package(f) + if not ok then + idx[#idx + 1] = { + name = path_normalize(path_join(path_split(self.filename), f)), + pos = r.pos, + cont = r.cont, + manuscript = self + } + end + end + return cont +end + +function ManuscriptLatex.init_callbacks.label (m, pos, cs) + local idx = m.label_index + local args = m.commands[cs].arguments + local r = m:parse_command(pos, cs) + local i = first_mand(args) + if r[i] then + local l = m:substring_stripped(r[i]) + idx[#idx + 1] = { + name = l, + pos = r[i].pos, + cont = r[i].cont, + outer_pos = r.pos, + outer_cont = r.cont, + manuscript = m + } + end + return r.cont +end + +function ManuscriptLatex.init_callbacks.section(self, pos, cs) + local idx = self.section_index + for r in self:argument_items(first_mand, pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(r), + level = self.commands[cs].section_level, + pos = r.pos, + cont = r.cont, + outer_pos = pos, + manuscript = self + } + end + return pos + #cs + 1 +end + +--** Bibliographic items + +function ManuscriptLatex.init_callbacks.bibitem (m, pos, cs) + local idx = m.bib_index + local args = m.commands[cs].arguments + local r = m:parse_command(pos, cs) + local i = first_mand(args) + if r[i] then + idx[#idx + 1] = { + name = m:substring_stripped(r[i]), + pos = r[i].pos, + cont = r[i].cont, + outer_pos = r.pos, + outer_cont = r.cont, + manuscript = m + } + end + return r.cont +end + +function ManuscriptLatex.init_callbacks.amsrefs_bib(self, pos, cs) + local idx = self.bib_index + local r = self:parse_command(pos, cs) + if r.incomplete then return r.cont end + local keys = self:read_keys(r[3]) + local authors, title, date = {}, "", "(n.d.)" + for i = 1, #keys do + local k, v = keys[i].key, keys[i].value + if k == "author" then + authors[#authors+1] = self.parser.clean(v:match("[^,]+", 2)) + elseif k == "title" then + title = self.parser.clean(v:sub(2, -2)) + elseif k == "date" then + date = self.parser.clean(v:match("(%d+)")) + end + end + idx[#idx + 1] = { + name = self:substring_stripped(r[1]), + text = string.format( + "%s %s; %s", + table.concat(authors, ", "), + date, + title), + pos = r[1].pos, + cont = r[1].cont, + outer_pos = r.pos, + outer_cont = r.cont, + manuscript = self + } + return r.cont +end + +--** Command definitions, TeX style + +ManuscriptLatex.init_callbacks.def = + require "digestif.ManuscriptPlainTeX".init_callbacks.def + +--** Command and environment definitions, LaTeX style + +local to_args = {} +for i = 1, 9 do + local t = merge(to_args[i-1] or {}) + t[i] = {meta = "#" .. i} + to_args[i] = t +end + +local function newcommand_args(number, default) + local args = to_args[number] + if default and args then + args = merge(args) -- make a copy + args[1] = { + meta = "#1", + optional = true, + delimiters = {"[", "]"}, + details = "Default: “" .. default .. "”." + } + end + return args +end + +function ManuscriptLatex.init_callbacks.newcommand(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local csname, nargs, optdefault + for r in self:argument_items(first_mand, pos, cs) do + csname = self:substring_stripped(r):sub(2) + end + for r in self:argument_items("number", pos, cs) do + nargs = tonumber(self:substring_stripped(r)) + end + for r in self:argument_items("default", pos, cs) do + optdefault = self:substring_stripped(r) + end + if csname then + local idx = self:get_index "newcommand" + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = newcommand_args(nargs, optdefault) + } + if not self.commands[csname] then + self.commands[csname] = idx[#idx] + end + end + return cont +end + +function ManuscriptLatex.init_callbacks.newenvironment(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local csname, nargs, optdefault + for r in self:argument_items(first_mand, pos, cs) do + csname = self:substring_stripped(r) + end + for r in self:argument_items("number", pos, cs) do + nargs = tonumber(self:substring_stripped(r)) + end + for r in self:argument_items("default", pos, cs) do + optdefault = self:substring_stripped(r) + end + if csname then + local idx = self:get_index("newenvironment") + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = newcommand_args(nargs, optdefault) + } + if not self.environments[csname] then + self.environments[csname] = idx[#idx] + end + end + return cont +end + +--** Command and environment definitions, xparse style + +local P, C, Cc, Cg, Ct = lpeg.P, lpeg.C, lpeg.Cc, lpeg.Cg, lpeg.Ct +local Pgroup = util.between_balanced("{", "}") +local Pdefault = Cg(Pgroup / "Default: “%1”", "details") + +local xparse_args = util.matcher( + Ct(util.many(Ct(util.sequence( + P" "^0, + (P"+" * Cg(Cc(true), "long"))^-1, + P"!"^-1, + util.choice( + "m", + "r" * Cg(Ct(C(1) * C(1)), "delimiters"), + "R" * Cg(Ct(C(1) * C(1)), "delimiters") * Pdefault, + "v" * Cg(Cc"verbatim", "type"), + "o" * Cg(Cc{"[", "]"}, "delimiters") * Cg(Cc(true), "optional"), + "O" * Cg(Cc{"[", "]"}, "delimiters") * Cg(Cc(true), "optional") * Pdefault, + "d" * Cg(Ct(C(1) * C(1)), "delimiters") * Cg(Cc(true), "optional"), + "D" * Cg(Ct(C(1) * C(1)), "delimiters") * Cg(Cc(true), "optional") * Pdefault, + "s" * Cg(Cc"*", "literal") * Cg(Cc"literal", "type") * Cg(Cc(true), "optional"), + "t" * Cg(C(1), "literal") * Cg(Cc"literal", "type") * Cg(Cc(true), "optional"), + "e" * Pgroup, + "E" * Pgroup * Pdefault)))))) + +function ManuscriptLatex.init_callbacks.NewDocumentCommand(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local csname, arg_spec + for r in self:argument_items("command", pos, cs) do + csname = self:substring_stripped(r):sub(2) + end + for r in self:argument_items("arg spec", pos, cs) do + arg_spec = self:substring_stripped(r) + end + if csname then + local idx = self:get_index "newcommand" + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = xparse_args(arg_spec) + } + if not self.commands[csname] then + self.commands[csname] = idx[#idx] + end + end + return cont +end + +function ManuscriptLatex.init_callbacks.NewDocumentEnvironment(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local csname, arg_spec + for r in self:argument_items("environment", pos, cs) do + csname = self:substring_stripped(r) + end + for r in self:argument_items("arg spec", pos, cs) do + arg_spec = self:substring_stripped(r) + end + if csname then + local idx = self:get_index "newenvironment" + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = xparse_args(arg_spec) + } + if not self.environments[csname] then + self.environments[csname] = idx[#idx] + end + end + return cont +end + +--* Scan references callbacks + +function ManuscriptLatex.scan_references_callbacks.ref(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.ref_index + for r in self:argument_items(first_mand, pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(r), + pos = r.pos, + cont = r.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +function ManuscriptLatex.scan_references_callbacks.cite(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local idx = self.cite_index + for r in self:argument_items(first_mand, pos, cs) do + idx[#idx + 1] = { + name = self:substring_stripped(r), + pos = r.pos, + cont = r.cont, + outer_pos = pos, + outer_cont = cont, + manuscript = self + } + end + return cont +end + +return ManuscriptLatex diff --git a/support/digestif/digestif/ManuscriptLatexProg.lua b/support/digestif/digestif/ManuscriptLatexProg.lua new file mode 100644 index 0000000000..38746afcc8 --- /dev/null +++ b/support/digestif/digestif/ManuscriptLatexProg.lua @@ -0,0 +1,12 @@ +local ManuscriptLatex = require "digestif.ManuscriptLaTeX" +local Parser = require "digestif.Parser" +local lpeg = require "lpeg" +local util = require "digestif.util" + +local ManuscriptLatexProg = util.class(ManuscriptLatex) + +ManuscriptLatexProg.format = "latex-prog" +ManuscriptLatexProg.parser = Parser{letter = lpeg.R("az", "@Z")} +ManuscriptLatex:add_package("latex.ltx") + +return ManuscriptLatexProg diff --git a/support/digestif/digestif/ManuscriptPlainTeX.lua b/support/digestif/digestif/ManuscriptPlainTeX.lua new file mode 100644 index 0000000000..1ac217985f --- /dev/null +++ b/support/digestif/digestif/ManuscriptPlainTeX.lua @@ -0,0 +1,56 @@ +local lpeg = require "lpeg" +local util = require "digestif.util" +local Manuscript = require "digestif.Manuscript" +local Parser = require "digestif.Parser" +local ManuscriptPlain = util.class(Manuscript) + +local P, R = lpeg.P, lpeg.R +local C, Ct, Cc, Cg = lpeg.C, lpeg.Ct, lpeg.Cc, lpeg.Cg + +-- In plain TeX, we can't distinguish between code and document files, +-- so we pretend @ is always a letter. +ManuscriptPlain.parser = Parser{letter = lpeg.R("az", "@Z")} +ManuscriptPlain.format = "plain" +ManuscriptPlain.packages = {} +ManuscriptPlain.commands = {} +ManuscriptPlain.environments = {} +ManuscriptPlain.init_callbacks = {} +ManuscriptPlain.scan_references_callbacks = {} +ManuscriptPlain:add_package("plain") + +-- Convert a TeX parameter text to an arguments table. +local param = P("#") * R("19") +local before_params = Ct(Cg(C((1 - param)^1), "literal")) +local one_param = Ct( + Cg(C(param), "meta") * Cg(Ct(Cc("") * C((1 - param)^1)), "delimiters")^-1 +) +local parse_params = util.matcher( + Ct(before_params^-1 * one_param^0) +) + +function ManuscriptPlain.init_callbacks.def(self, pos, cs) + local cont = self:parse_command(pos, cs).cont + local csname, params + for r in self:argument_items(1, pos, cs) do + csname = self:substring_stripped(r):sub(2) + end + for r in self:argument_items(2, pos, cs) do + params = self:substring_stripped(r) + end + if csname then + local idx = self:get_index "newcommand" + idx[#idx+1] = { + name = csname, + pos = pos, + cont = cont, + manuscript = self, + arguments = parse_params(params) + } + if not self.commands[csname] then + self.commands[csname] = idx[#idx] + end + end + return cont +end + +return ManuscriptPlain diff --git a/support/digestif/digestif/ManuscriptTexinfo.lua b/support/digestif/digestif/ManuscriptTexinfo.lua new file mode 100644 index 0000000000..0e0c71667c --- /dev/null +++ b/support/digestif/digestif/ManuscriptTexinfo.lua @@ -0,0 +1,25 @@ +local util = require "digestif.util" +local Manuscript = require "digestif.Manuscript" +local Parser = require "digestif.Parser" + +local ManuscriptTexinfo = util.class(Manuscript) + +ManuscriptTexinfo.parser = Parser({escape = "@"}) +ManuscriptTexinfo.format = "texinfo" +ManuscriptTexinfo.packages = {} +ManuscriptTexinfo.commands = {} +ManuscriptTexinfo.environments = {} +ManuscriptTexinfo.init_callbacks = {} +ManuscriptTexinfo.scan_references_callbacks = {} +ManuscriptTexinfo:add_package("texinfo") + +function ManuscriptTexinfo:snippet_env(cs, args) + local argsnippet = args and self:snippet_args(args) or "" + return cs .. argsnippet .. "\n\t$0\n@end " .. cs +end + +function Manuscript:signature_cmd(cs, args) + return self:signature_args(args, "@" .. cs) +end + +return ManuscriptTexinfo diff --git a/support/digestif/digestif/Parser.lua b/support/digestif/digestif/Parser.lua new file mode 100644 index 0000000000..e939a13c56 --- /dev/null +++ b/support/digestif/digestif/Parser.lua @@ -0,0 +1,227 @@ +-- Parser class + +local lpeg = require "lpeg" +local util = require "digestif.util" + +local C = lpeg.C +local Cc = lpeg.Cc +local Cg = lpeg.Cg +local Cs = lpeg.Cs +local Ct = lpeg.Ct +local P = lpeg.P +local R = lpeg.R +local S = lpeg.S +local V = lpeg.V +local match = lpeg.match + +local I = lpeg.Cp() +local Ipos = Cg(I, "pos") +local Icont = Cg(I, "cont") +local Iouter_pos = Cg(I, "outer_pos") +local Iouter_cont = Cg(I, "outer_cont") +local Kcs = Cc("cs") +local Kmathshift = Cc("mathshift") +local Knil = Cc(nil) +local Kpar = Cc("par") +local Pend = P(-1) +local is_incomplete = Cg(Cc(true), "incomplete") +local is_omitted = Cg(Cc(true), "omitted") + +local choice = util.choice +local gobble_until = util.gobble_until +local many = util.many +local matcher = util.matcher +local search = util.search +local sequence = util.sequence +local trim = util.trim + +local default_catcodes = { + escape = P("\\"), + bgroup = P("{"), + egroup = P("}"), + mathshift = P("$"), + eol = P("\n"), + letter = R("az", "AZ"), + comment = P("%"), + char = P(1), -- are we utf-8 agnostic? + space = S(" \t"), + listsep = P(","), + valsep = P("=") +} + +local Parser = util.class() + +function Parser:__init(catcodes) + catcodes = catcodes or default_catcodes + +--* Single characters + local escape = P(catcodes.escape or default_catcodes.escape) + local bgroup = P(catcodes.bgroup or default_catcodes.bgroup) + local egroup = P(catcodes.egroup or default_catcodes.egroup) + local mathshift = P(catcodes.mathshift or default_catcodes.mathshift) + local eol = P(catcodes.eol or default_catcodes.eol) + local letter = P(catcodes.letter or default_catcodes.letter) + local comment = P(catcodes.comment or default_catcodes.comment) + local char = P(catcodes.char or default_catcodes.char) + local space = P(catcodes.space or default_catcodes.space) + local listsep = P(catcodes.listsep or default_catcodes.listsep) + local valsep = P(catcodes.valsep or default_catcodes.valsep) + +--* Basic elements + local blank = space + eol + local cs = escape * (letter^1 + char) + local csname = escape * C(letter^1 + char) + local token = cs + char + local blank_line = eol * space^0 * eol + local single_eol = eol * space^0 * -eol + local comment_line = comment * gobble_until(eol, char) + local skip = (space + single_eol + comment_line)^0 -- simulates TeX state S + local skip_long = (space + eol + comment_line)^0 + local par = blank_line * (space + eol + comment_line)^0 + local next_par = search(blank_line, comment + char) + * (eol + space + comment_line)^0 * I * char -- need this char at the end? + + -- These patterns match text delimited by braces. They succeed on a + -- incomplete subject string (with the additional incomplete = true + -- named capture). The second variant does not cross paragraph + -- boundaries. + local group_long = sequence( + Iouter_pos, + P{sequence(bgroup, + Ipos, + many(choice(comment_line, + V(1)/0, + token - egroup)), + Icont, + egroup + is_incomplete)}, + Iouter_cont) + local group = sequence( + Iouter_pos, + P{sequence(bgroup, + Ipos, + many(choice(comment_line, + V(1)/0, + token - egroup) + - blank_line), + Icont, + egroup + is_incomplete)}, + Iouter_cont) + +--* Trimming, cleaning, and cropping + local trimmer = blank^0 * C((blank^0 * (char - blank)^1)^0) + local cleaner = blank^0 * Cs(((blank^1 / " " + true) * (char - blank)^1)^0) + local comment_block = ((eol * space^0)^-1 * comment_line)^1 -- use the one below? + -- local comment_block = (comment_line * (Pend + eol * space^0))^0 + local comment_stripper = Cs((comment_block / "" + char)^0) + +--* Parsing lists + local skim_long = comment_line + group_long/0 + token + local listsep_skip = listsep * skip_long + + local list_item = Ct(Ipos * (skim_long - listsep)^1 * Icont) + local list_parser = skip_long * Ct((listsep_skip^0 * list_item)^0) + + local list_reader = skip_long * Ct( + (listsep_skip^0 * C((skim_long - listsep)^1) + / trim(space + eol + comment_line, char))^0) + + local key = Ct(Ipos * (skim_long - listsep - valsep)^1 * Icont) + local value = Ct(valsep * skip_long * Ipos * (skim_long - listsep)^0 * Icont) + local kvlist_item = Ct(Ipos * Cg(key, "key") * Cg(value, "value")^-1 * Icont) + local kvlist_parser = skip_long * Ct((listsep_skip^0 * kvlist_item)^0) + +--* Parsing command arguments + local patt_from_arg = function(arg) + local ret = skip + if arg.delimiters == false then + -- This is different from the “plain argument” case in that only + -- a single token is allowed. + ret = ret * Ipos * token * Icont + elseif arg.delimiters then + local l, r = arg.delimiters[1], arg.delimiters[2] + ret = sequence( + ret, Iouter_pos, l, Ipos, + many( + choice(comment_line, + group/0, + token) + - blank_line - r), + Icont, + r + is_incomplete, + Iouter_cont) + elseif arg.literal then + ret = ret * Ipos * P(arg.literal) * Icont + else -- plain argument + ret = ret * (group + Ipos * token * Icont) + end + if arg.optional then + ret = ret + is_omitted + end + return Ct(ret) + end + + local patt_from_args = function(args) + local ret = Icont + for i = #args, 1, -1 do + ret = (patt_from_arg(args[i]) + is_incomplete) * ret + end + return Ct(Ipos * ret) + end + patt_from_args = util.memoize1(patt_from_args) + + local parse_args = function(args, str, pos) + return match(patt_from_args(args), str, pos) + end + +--* Public patterns + self.group = group + self.group_long = group_long + self.next_par = next_par + self.comment_line = comment_line + self.cs = cs + self.csname = csname + self.blank_line = blank_line + +--* Public functions + self.parse_args = parse_args + self.is_blank_line = matcher(space^0 * eol) + self.next_nonblank = matcher(skip * I) + self.trim = matcher(trimmer) -- replace def of trimmer directly in here? + self.clean = matcher(cleaner) + self.strip_comments = matcher(comment_stripper) + self.skip_to_bracketed = matcher( -- for tikz paths + search( + patt_from_arg{delimiters = {"[", "]"}}, + skim_long - blank_line)) -- also exclude ";"? + + -- Parse a list, return a sequence of ranges + self.parse_list = matcher(list_parser) + -- Parse a list, return the item contents as strings + self.read_list = matcher(list_reader) + -- Parse a key-value list, return their contents as strings + self.parse_kvlist = matcher(kvlist_parser) + + -- Match a normal control sequence name starting with prefix + function self.cs_matcher(prefix) + local patt = P(prefix) * letter^0 * Pend + return matcher(patt) + end + + -- Build a pattern for Manuscript.scan, which looks ahead for one of + -- the elements of the set `things`. A match produces 4 captures: a + -- position before the item, the kind of item ("cs", "mathshift" or + -- "par"), a detail (e.g., the control sequence if kind is "cs"), + -- and a position after the item. + -- + self.scan_patt = function(things) + local patt = Kcs * csname + if things.mathshift then + patt = patt + mathshift * Kmathshift * (mathshift * Cc"$$" + Cc"$") + end + if things.par then patt = patt + par * Kpar * Knil end + return search(I * patt * I, comment_line + char) + end + +end + +return Parser diff --git a/support/digestif/digestif/Schema.lua b/support/digestif/digestif/Schema.lua new file mode 100644 index 0000000000..b59a95157d --- /dev/null +++ b/support/digestif/digestif/Schema.lua @@ -0,0 +1,189 @@ +--- A simple validation library, loosely inspired by JSON Schema + +local Schema = {} +Schema.__index = Schema + +local function is_schema(tbl) + return getmetatable(tbl) == Schema +end +Schema.is_schema = is_schema + +local validators, initializers = {}, {} + +local function to_schema(tbl) + if is_schema(tbl) then return tbl end + for i = 1, #tbl do + tbl[i] = to_schema(tbl[i]) + end + -- local fields, items = tbl.fields, tbl.items + -- if fields then + -- for k, v in pairs(fields) do + -- fields[k] = to_schema(v) + -- end + -- end + -- if items then + -- tbl.items = to_schema(items) + -- end + for k, fun in pairs(initializers) do + if tbl[k] then tbl[k] = fun(tbl[k]) end + end + return setmetatable(tbl, Schema) +end +setmetatable(Schema, {__call = function(_, tbl) return to_schema(tbl) end}) + +local function msg_type(expect, got) + return ("Type: expected %q, got %q"):format(expect, got) +end + +local function msg_where(msg, loc_type, loc_name) + return ("%s in %s %q"):format(msg, loc_type, loc_name) +end + +initializers.items = to_schema +initializers.keys = to_schema +initializers.values = to_schema + +function initializers.enum(tbl) + local set = {} + for i = 1, #tbl do + set[tbl[i]] = true + end + return set +end + +function initializers.fields(fields) + for k, v in pairs(fields) do + fields[k] = to_schema(v) + end + return fields +end + +function validators.type(s, obj) + local ok = (type(obj) == s) + return ok, ok or msg_type(s, type(obj)) +end + +function validators.predicate(f, obj) + return f(obj) +end + +function validators.keys(schema, obj) + if type(obj) ~= "table" then + return false, msg_type("table", type(obj)) + end + for k in pairs(obj) do + local ok, msg = schema:validate(k) + if not ok then + return false, msg_where(msg, "key", k) + end + end + return true +end + +function validators.values(schema, obj) + if type(obj) ~= "table" then + return false, msg_type("table", type(obj)) + end + for k, v in pairs(obj) do + local ok, msg = schema:validate(v) + if not ok then + return false, msg_where(msg, "field", k) + end + end + return true +end + +function validators.fields(fields, obj) + if type(obj) ~= "table" then + return false, msg_type("table", type(obj)) + end + for k, schema in pairs(fields) do + local ok, msg = schema:validate(obj[k]) + if not ok then + return false, msg_where(msg, "field", k) + end + end + return true +end + +function validators.items(schema, obj) + if type(obj) ~= "table" then + return false, msg_type("table", type(obj)) + end + for i, item in ipairs(obj) do + local ok, msg = schema:validate(item) + if not ok then + return false, msg_where(msg, "item", i) + end + end + return true +end + +function validators.enum(set, obj) + local ok = set[obj] + return ok, ok or ('Enum: %q not allowed'):format(obj) +end + +function Schema:validate(obj) + if self.optional and obj == nil then return true end + for k, v in pairs(self) do + local fun = validators[k] + if fun then + local ok, msg = fun(v, obj) + if not ok then return false, msg end + end + end + local len = #self + if len > 0 then + for i = 1, len do + if self[i]:validate(obj) then break end + if i == len then return false, "Alternatives: no match" end + end + end + return true +end + +function Schema:assert(obj) + return assert(self:validate(obj)) +end + +function Schema:assert_fail(obj) + assert(not self:validate(obj)) +end + +local schema_of_schema = Schema { + fields = { + description = { + type = "string", + optional = true, + description = "A docstring for the schema" + }, + fields = { + type = "table", + values = {predicate = is_schema} + }, + enum = { + type = "table" + }, + items = { + predicate = is_schema + }, + optional = { + type = "boolean", + optional = true, + description = "Whether nil values are accepted" + }, + predicate = { + type = "function", + optional = true, + description = "A function to test on the object" + }, + type = { + type = "string", + optional = true, + description = "Check if the object is of a given type" + }, + } +} + +return Schema diff --git a/support/digestif/digestif/bibtex.lua b/support/digestif/digestif/bibtex.lua new file mode 100644 index 0000000000..f1430474e3 --- /dev/null +++ b/support/digestif/digestif/bibtex.lua @@ -0,0 +1,271 @@ +local lpeg = require "lpeg" +local util = require "digestif.util" + +local B, P, R, S, V + = lpeg.B, lpeg.P, lpeg.R, lpeg.S, lpeg.V +local C, Cc, Cp, Ct, Cmt, Cg + = lpeg.C, lpeg.Cc, lpeg.Cp, lpeg.Ct, lpeg.Cmt, lpeg.Cg +local concat = table.concat +local merge = util.merge +local search, gobble_until, case_fold = util.search, util.gobble_until, util.case_fold +local split, replace = util.split, util.replace + +local bibtex = {} + +local function ipairs_from(t, i) + return ipairs(t), t, i - 1 +end + +--* Parser + +local char = P(1) +local at_sign = P"@" +local newline = P"\n" +local space = S" \r\n\t" +local whitespace = space^0 +local comment = P"%" * (1 - newline)^0 * newline +local junk = (comment + 1 - at_sign)^0 +local number = C(R"09"^1) * whitespace +local name = C((R"az" + R"AZ" + R"09" + S"!$&*+-./:;<>?[]^_`|")^1) * whitespace +local lbrace = P"{" * whitespace +local rbrace = P"}" * whitespace +local lparen = P"(" * whitespace +local rparen = P")" * whitespace +local equals = P"=" * whitespace +local hash = P"#" * whitespace +local comma = P"," * whitespace +local quote = P'"' * whitespace +local lit_string = C(case_fold "string") * whitespace +local lit_comment = C(case_fold "comment") * whitespace +local lit_preamble = C(case_fold "preamble") * whitespace + +local Cstart = Cg(Cp(), "start") +local Cstop = Cg(Cp(), "stop") + +local curly_braced_string = util.between_balanced("{", "}") +local round_braced_string = util.between_balanced("(", ")") +local braced_string = (curly_braced_string + round_braced_string) * whitespace +local quoted_string = '"' * C(gobble_until('"')) * '"' * whitespace +local simple_value = quoted_string + braced_string + number + Ct(name) +local value = simple_value * (hash * simple_value)^0 +local field = Ct(name * equals * value) + whitespace +local fields = field * (comma * field)^0 + +local token = curly_braced_string/0 + char +local nonspace = token - space +local author_sep = space * "and" * space +local etal_marker = P("et al") * whitespace * P(-1) + +-- either curly or round braced +local function braced(patt) + return lbrace * patt * rbrace + lparen * patt * rparen +end + +local string_entry = at_sign * lit_string * braced(fields) +local comment_entry = at_sign * lit_comment * braced_string +local preamble_entry = at_sign * lit_preamble * braced(value) +local regular_entry = at_sign * name * braced(name * comma * fields) +local entry = string_entry + comment_entry + preamble_entry + regular_entry + +-- this pattern produces the parse tree +-- TODO: catch premature end on invalid entry +local all_entries = Ct((junk * Ct(Cstart * entry * Cstop))^0) + +--* Translate parse tree + +-- BibItem class +local BibItem = {} +local mt = {__index = BibItem} +setmetatable( + BibItem, { + __call = function(_,t) return setmetatable(t, mt) end +}) + +-- replace user-defined strings and concatenate +local function process_value(val, strings, i) + i = i or 2 + local t = {} + for _, v in ipairs_from(val, i) do + if type(v) == "table" then + t[#t+1] = strings[v[1]] or "" + else + t[#t+1] = v + end + end + return concat(t) +end + +local default_options = { + with_authors = true, + with_title = true +} + +--- Parse a bibtex file. +function bibtex.parse(src, options) + options = merge(default_options, options) + local entries = all_entries:match(src) + local strings = merge(options.strings) + local preambles = {} + local ids = {} + local items = { + strings = strings, + preambles = preambles, + ids = ids + } + for _, t in ipairs(entries) do + local entry_type = t[1]:lower() + if entry_type == "comment" then + -- pass + elseif entry_type == "preamble" then + preambles[#preambles + 1] = t[2] + elseif entry_type == "string" then + for _, u in ipairs_from(t, 2) do + local key = u[1]:lower() + local val = process_value(u, strings) + strings[key] = val + end + else + local id = t[2] + local fields = {} + for _, u in ipairs_from(t, 3) do + local key = u[1]:lower() + local val = process_value(u, strings) + fields[key] = val + end + local item = BibItem { + id = id, + type = entry_type, + fields = fields, + pos = t.start, + cont = t.stop + } + ids[id] = item + items[#items + 1] = item + end + end + return items +end + +--* Deuglify strings + +local tex_symbols = { + oe = "œ", + OE = "Œ", + ae = "ӕ", + AE = "Ӕ", + aa = "å", + AA = "Å", + ss = "ß", + o = "ø", + O = "Ø", + l = "ł", + L = "Ł", + -- corner cases + i = "{i}", -- not "ı" + j = "j", -- not "ȷ" + [" "] = " ", +} + +local tex_accents = util.map( + replace("◌", ""), + { + ['"'] = "◌̈", + ["'"] = "◌́", + ["."] = "◌̇", + ["="] = "◌̄", + ["^"] = "◌̂", + ["`"] = "◌̀", + ["~"] = "◌̃", + ["c"] = "◌̧", + ["d"] = "◌̣", + ["H"] = "◌̋", + ["u"] = "◌̆", + ["b"] = "◌̱", + ["v"] = "◌̌", + ["t"] = "◌͡" + } +) + +local tex_letter = (R"AZ" + R"az") +local tex_char_or_math = "$" * gobble_until("$") * "$" + char -- for deuglification purposes +local tex_cs_patt = "\\" * C(tex_letter^1 + char)* whitespace +local tex_accent_patt = tex_cs_patt * (curly_braced_string + C(char)) +local function repl_accents_fun(cs, arg) + local acc = tex_accents[cs] + if not acc then + return -- must return 0 values! + else + return arg .. acc + end +end + +local detexify_symbols = replace(tex_cs_patt, tex_symbols, tex_char_or_math) +local detexify_accents = replace(tex_accent_patt, repl_accents_fun, tex_char_or_math) +local debracify = replace(curly_braced_string, 1, tex_char_or_math) +local detitlify = replace(B(space) * C(tex_letter), string.lower, tex_char_or_math) +local trim = util.trim(space) +local clean = util.clean(space) + +local function deuglify_name (s) + return + clean( + debracify( + detexify_accents( + detexify_symbols(s)))) +end + +local function deuglify_title (s) + return + clean( + debracify( + detitlify( + detexify_accents( + detexify_symbols(s))))) +end + +--* Pretty-printing + +local split_authors = split(author_sep, token) +local split_name = split(comma, token) +local split_last = search(Cp() * C(nonspace^1) * whitespace * P(-1)) + +function BibItem:authors() + local t = {} + local author = self.fields.author + if not author then return {} end + for _, name in ipairs(split_authors(author)) do + local u = {} + local parts = split_name(name) + if #parts == 3 then + u.first = parts[3] + u.last = parts[1] + u.suffix = parts[2] + elseif #parts == 2 then + u.first = parts[2] + u.last = parts[1] + else + local p, l = split_last:match(name) + if p then + u.first = name:sub(1, p - 1) + u.last = l + else + u.last = name + end + end + t[#t + 1] = u + end + return t +end + +function BibItem:pretty_print() + local t, a = {}, {} + for _, name in ipairs(self:authors()) do + a[#a + 1] = deuglify_name(name.last) + end + t[#t + 1] = concat(a, ", ") + t[#t + 1] = (self.fields.year or self.fields.date or "(n.d.)") .. ";" + t[#t + 1] = deuglify_title(self.fields.title or "") + return concat(t, " ") +end + +return bibtex diff --git a/support/digestif/digestif/config.lua b/support/digestif/digestif/config.lua new file mode 100644 index 0000000000..8b901ba93d --- /dev/null +++ b/support/digestif/digestif/config.lua @@ -0,0 +1,156 @@ +local util = require "digestif.util" +local format = string.format + +local config = {} + +config.version = "0.5" +local pre_version = os.getenv("DIGESTIF_PRERELEASE") +if pre_version then + config.version = config.version .. "-" .. pre_version +end + +if util.is_command("kpsewhich") then + local pipe = io.popen("kpsewhich -var-brace-value=TEXMF") + local output = pipe:read("l") + local ok, exitt, exitc = pipe:close() + if ok and exitt == "exit" and exitc == 0 then + config.texmf_dirs = util.imap( + function (s) return s:gsub("^!!", "") end, + util.path_list_split(output) + ) + elseif config.verbose then + util.log("Error running kpsewhich (%s %d)", exitt, exitc) + end +else -- TODO: What should be the default? + config.texmf_dirs = { + "/usr/local/share/texmf", + "/usr/share/texmf", + "/usr/share/texlive/texmf-local", + "/usr/share/texlive/texmf-dist", + } +end + +config.data_dirs = {} -- TODO: What should be the default? + +-- Location of a complete texmf distribution, used for instance to +-- find documentation not installed locally. Passed to format with +-- one argument, the percent-encoded name of a file. +config.external_texmf = "https://www.tug.org/texlive/Contents/live/texmf-dist/%s" + +config.provide_snippets = false + +-- Table mapping command names to the snippet to be used, overriding +-- the default. +config.extra_snippets = {} + +-- This allows the user to assign custom actions to generated command +-- tags. +config.extra_actions = { + eqref = "ref" +} + +config.fuzzy_cite = true +config.fuzzy_ref = true +config.info_command = util.is_command("info") + +-- For candidates of these kinds, include the annotation in the +-- candidate label. The values of this table are a string which is +-- formatted with two arguments, the candidate text and annotation. +config.lsp_long_candidates = { + label = "%-12s %s", + bibitem = "%-12s %s", +} + +--* Loading user settings + +local function is_table(key_type, val_type) + return function(obj) + if type(obj) ~= "table" then return false end + for key, val in pairs(obj) do + if type(key) ~= key_type then return false end + if type(val) ~= val_type then return false end + end + return true + end +end + +local validators = { + data_dirs = is_table("number", "string"), + extra_actions = is_table("string", "string"), + extra_snippets = is_table("string", "string"), + fuzzy_cite = "boolean", + fuzzy_ref = "boolean", + info_command = "string", + lsp_long_candidates = is_table("string", "string"), + provide_snippets = "boolean", + texmf_dirs = is_table("number", "string"), + tlpdb_path = "string", + verbose = "boolean", +} + +-- Set config entries found in `tbl`. +function config.load_from_table(tbl) + -- Set verbose option before all others + local verbose = tbl.verbose or config.verbose + for key, val in pairs(tbl) do + local validator, ok = validators[key] + if type(validator) == "string" then + ok = type(val) == validator + elseif type(validator) == "function" then + ok = validator(val) + end + if ok then + config[key] = val + if verbose then + local msg = "Setting configuration option %s = %s" + util.log(msg, key, util.inspect(val)) + end + else + local msg = "Invalid configuration option: %s = %s" + error(format(msg, key, util.inspect(val))) + end + end +end + +function config.load_from_file(file) + local tbl = {} + local ok, err = loadfile(file, "t", tbl) + if ok then ok, err = pcall(ok) end + if not ok then + local msg = "Error loading configuration from %s: %s" + error(msg, file, err) + end + config.load_from_table(tbl) +end + +function config.load_from_env() + local DIGESTIF_DATA = os.getenv("DIGESTIF_DATA") + if DIGESTIF_DATA then + config.data_dirs = util.path_list_split(DIGESTIF_DATA) + end + + local DIGESTIF_TEXMF = os.getenv("DIGESTIF_TEXMF") + if DIGESTIF_TEXMF then + config.texmf_dirs = util.path_list_split(DIGESTIF_TEXMF) + end + + local DIGESTIF_TLPDB = os.getenv("DIGESTIF_TLPDB") + if DIGESTIF_TLPDB then + config.tlpdb_path = util.path_list_split(DIGESTIF_TLPDB) + end +end + +function config.check_data(dir) + if not dir then + for _, dir in ipairs(config.data_dirs) do + if config.check_data(dir) then return true end + end + end + local f = io.open(util.path_join(dir, "primitives.tags")) + if f then + f:close() + return true + end +end + +return config diff --git a/support/digestif/digestif/data.lua b/support/digestif/digestif/data.lua new file mode 100644 index 0000000000..621048f4a9 --- /dev/null +++ b/support/digestif/digestif/data.lua @@ -0,0 +1,384 @@ +local lpeg = require "lpeg" +local util = require "digestif.util" +local config = require "digestif.config" + +local format, strfind = string.format, string.find +local concat, unpack = table.concat, table.unpack +local popen = io.popen +local P, C, Cg, Ct = lpeg.P, lpeg.C, lpeg.Cg, lpeg.Ct +local match = lpeg.match +local many, sequence = util.many, util.sequence +local gobble, search = util.gobble, util.search +local nested_get, extend = util.nested_get, util.extend +local find_file = util.find_file +local parse_uri, make_uri = util.parse_uri, util.make_uri +local log = util.log +local path_split, path_join = util.path_split, util.path_join + +local data = {} +local loaded_tags = {} + +--* CTAN data + +-- function ctan_package(name) +-- +-- Return a little tags table with the package's details on CTAN +-- (package description, ctan link, documentation). No command +-- information. +-- +-- function ctan_package_of(file) +-- +-- The name of the CTAN package to which file belongs. +-- +local ctan_package, ctan_package_of -- to be defined + +local tlpdb_path = config.tlpdb_path + and find_file(config.tlpdb_path) + or find_file(config.texmf_dirs, "../tlpkg/texlive.tlpdb") + +if tlpdb_path then + + local _, tlpdb_text = find_file(tlpdb_path, nil, true) + + if config.verbose then + log("Reading TLPDB from '%s'", tlpdb_path) + end + + local Peol = P"\n" + local concat_lines = function(...) return concat({...}, "\n") end + + local within_item = 1 - Peol * Peol + local within_files = (1 - Peol) + Peol * P" " + local gobble_to_eol = gobble("\n") + + -- Pattern to turn an entry in the TLPDB file into a table with + -- entries name, summary, details, documentation, runfiles. + local tlpdb_item_patt = Ct( + sequence( + Cg( -- collect the name + P"name " * C(gobble_to_eol), + "ctan_package"), + Cg( -- find a shortdesc or give up + search( + Peol * "shortdesc " * C(gobble_to_eol), + within_item), + "summary"), + Cg( -- find a longdesc or give up + search( + (Peol * "longdesc " * C(gobble_to_eol))^1 / concat_lines, + within_item), + "details"), + Cg( -- find docfiles section + many(-1, -- or continue + sequence( + search(Peol * "docfiles " * gobble_to_eol, within_item), + Ct(many( -- collect several docfile entries in a list + search( -- looking for the interesting ones only + Ct( -- parse one docfile entry + sequence( -- collect URI, but only if details field exist + Peol * " RELOC/", + Cg(gobble(" ", 1 - Peol) / "texmf:%0", "uri"), + Cg(P" details=\"" * C(gobble"\""), "summary"))), + within_files))))), + "documentation"), + Cg( -- find runfiles section or give up + sequence( + search(Peol * "runfiles " * gobble_to_eol, within_item), + Ct(many( -- collect the runfile entries is a list + sequence( -- parse one runfile entry + Peol * " ", -- discard the file line marker + many(search("/", 1 - Peol)), -- discard folder part + C(gobble_to_eol))))), -- collect base name + "runfiles"))) + + local tlpdb_items = Ct(many(search(Peol * tlpdb_item_patt))):match(tlpdb_text) + + function ctan_package(name) + for i = 1, #tlpdb_items do + local item = tlpdb_items[i] + if item.name == name then + return item + end + end + end + ctan_package = util.memoize1(ctan_package) + + function ctan_package_of(file) + for i = 1, #tlpdb_items do + local item = tlpdb_items[i] + local runfiles = item.runfiles + for j = 1, #runfiles do + if runfiles[j] == file then + return item + end + end + end + end + ctan_package_of = util.memoize1(ctan_package_of) + +else + + ctan_package = function() end + ctan_package_of = function() end + if config.verbose then log("TLPDB not found") end + +end + +--* kpathsea emulation + +-- function kpsewhich(name) +-- +-- Like the kpsewhich command, return the full path of tex input file +-- name. We use luatex's kpse bindings if available, and parse the +-- system's ls-R files otherwise. +-- +local kpsewhich + +if kpse then -- we're on luatex + + local kpse_obj = kpse.new("luatex") + + function kpsewhich(name) + return kpse_obj:find_file(name, "tex") + end + +else -- on plain lua, we look for ls-R files + + local texmf_files = {} + local texmf_dirs = config.texmf_dirs + local dir_patt = P"./" * C(gobble(":" * P(-1))) + for i = 1, #texmf_dirs do + local texmf_dir = texmf_dirs[i] + local listing_path = find_file(texmf_dir, "ls-R") + if listing_path then + local current_dir + for line in io.lines(listing_path) do + local subdir = match(dir_patt, line) + if subdir then + current_dir = path_join(texmf_dir, subdir) + elseif current_dir and not texmf_files[line] then + texmf_files[line] = path_join(current_dir, line) + end + end + end + end + + function kpsewhich(name) + return texmf_files[name] + end + +end + +--* Generate tags from the user's TeX installation + +local function infer_format(path) + local ext = path:sub(-4) + if ext == ".bib" then + return "bibtex" + elseif ext == ".sty" or ext == ".cls" or ext == ".ltx" then + return "latex-prog" + elseif ext == ".xml" and path:match("%Acontext%A") then + return "context-xml" + elseif ext == ".tex" then + return "latex-prog" + end +end + +local function tags_from_manuscript(script, ctan_data) + local commands, environments, dependencies = {}, {}, {} + local tags = { + generated = true, + dependencies = dependencies, + commands = commands, + environments = environments + } + if ctan_data then + setmetatable(tags, {__index = ctan_data}) + end + for pkg in pairs(script.packages) do + dependencies[#dependencies+1] = pkg + end + table.sort(dependencies) + for _, it in script:index_pairs("newcommand") do + commands[it.name] = { + arguments = it.arguments, + } + end + for _, it in script:index_pairs("newenvironment") do + environments[it.name] = { + arguments = it.arguments, + } + end + return tags +end + +-- Generate tags from TeX source code (or ConTeXt interface XML file, +-- if applicable). The argument is a file name found by kpsewhich. +-- +local function generate_tags(name) + local path = kpsewhich(name) + path = path and find_file(config.texmf_dirs, path) + if not path then return end + local texformat = infer_format(path) + if not texformat then return end + if config.verbose then log("Generating tags: %s", path) end + local pkg = ctan_package_of(name) + if texformat == "context-xml" then + -- The function below is defined and monkey-patched in + -- ManuscriptConTeXt, to keep the XML dependency separated. + if not data.tags_from_xml then require "digestif.ManuscriptConTeXt" end + return data.tags_from_xml(path, pkg) + else + loaded_tags[name] = {} -- TODO: this is to avoid loops, find a better way + local cache = require "digestif.Cache"() + local script = cache:manuscript(path, texformat) + return tags_from_manuscript(script, pkg) + end +end +data.generate_tags = generate_tags + +--* Load tags + +-- function require_tags(name) +-- +-- Return tags table for input file name. Either loads from a tags +-- file in the data directory, or generate from source on the fly. +-- +local require_tags + +local parse_ref = util.matcher( + sequence( + P"$ref:", + C(gobble"#") * P"#", + Ct(many(P"/" * C(gobble"/"))))) +p=parse_ref +local function resolve_refs(tbl, seen) + seen = seen or {} + for k, v in pairs(tbl) do + if type(v) == "string" then + local loc, path = parse_ref(v) + if loc then + tbl[k] = nested_get(require_tags(loc), unpack(path)) + end + elseif type(v) == "table" and not seen[v] then + seen[v] = true + resolve_refs(v, seen) + end + end +end + +-- Load a tags file from the data directory. +local function load_tags(name) + if strfind(name, "..", 1, true) then return end -- bad file name + local path, str = find_file(config.data_dirs, name .. ".tags", true) + if not path then return end + if config.verbose then log("Loading tags: %s", path) end + local tags = {} + local ok, message = load(str, path, "t", tags) + if ok then ok, message = pcall(ok) end + if not ok and config.verbose then + log("Error loading %s.tags: %s", name, message) + return -- TODO: should throw an error? + end + local pkg = ctan_package(tags.ctan_package) or ctan_package_of(name) + setmetatable(tags, {__index = pkg}) + return tags +end + +require_tags = function(name) + local tags = loaded_tags[name] + if not tags then + tags = load_tags(name) or generate_tags(name) + if tags then + loaded_tags[name] = tags + resolve_refs(tags) + local extra_actions = config.extra_actions or {} + for _, kind in ipairs{"commands", "environments"} do + for cs, cmd in pairs(tags[kind] or {}) do + if not cmd.package then cmd.package = tags end + if extra_actions[cs] then cmd.action = extra_actions[cs] end + end + end + end + end + return tags +end +data.require = require_tags +data.require_tags = require_tags + +-- Load all data files, and return them in a table. This is intended +-- for debugging and testing only, and depends on luafilesystem. +local function load_all_tags() + local t = {} + local ok, lfs = pcall(require, "lfs") + assert(ok, "Function data.load_all() need the luafilesystem library.") + for _, data_dir in ipairs(config.data_dirs) do + for path in lfs.dir(data_dir) do + local pkg = path:match("(.*)%.tags") + if pkg then + assert(load_tags(pkg), "Error loading data file " .. path) + t[pkg] = require_tags(pkg) or error("Error processing data file " .. path) + end + end + end + return t +end +data.load_all = load_all_tags + +--* User-readable documentation + +local function resolve_uri(uri) + local scheme, _, location, _, fragment = parse_uri(uri) + if scheme == "info" then + return uri + elseif scheme == "texmf" then + local path = find_file(config.texmf_dirs, location) + if path then + return make_uri("file", "", path, nil, fragment) + else + return format( + config.external_texmf, make_uri(nil, nil, location, nil, fragment) + ) + end + else + return uri + end +end + +-- Given a list of documentation items, return a markdown-formatted +-- string of links to these documents. +local function resolve_doc_items(items) + if type(items) == "string" then items = {items} end + local t = {} + for _, item in ipairs(items) do + if type(item) == "string" then + t[#t+1] = format("- <%s>", resolve_uri(item)) + else + t[#t+1] = format("- [%s](%s)", item.summary, resolve_uri(item.uri)) + end + end + return t +end +data.resolve_doc_items = resolve_doc_items + +-- Call info, return the relevant part of the info node. +local function get_info(uri) + if config.info_command then + local scheme, _, path, _, fragment = parse_uri(uri) + if scheme ~= "info" then return end + local cmd = format("%s '(%s)%s'", config.info_command, path, fragment) + local pipe = popen(cmd) + local str = pipe:read("a") + local ok, exitt, exitc = pipe:close() + if ok and exitt == "exit" and exitc == 0 then + str = str:gsub(".-\n", "", 2) -- discard header line + str = str:gsub("\nFile: " .. path .. ".info.*", "\n") -- discard child nodes + return str, path, fragment + elseif config.verbose then + log("Error running info (%s %d)", exitt, exitc) + end + end +end +data.get_info=util.memoize(get_info) + +return data diff --git a/support/digestif/digestif/langserver.lua b/support/digestif/digestif/langserver.lua new file mode 100644 index 0000000000..55bd8c8dd7 --- /dev/null +++ b/support/digestif/digestif/langserver.lua @@ -0,0 +1,567 @@ +local config = require "digestif.config" +local util = require "digestif.util" + +local floor = math.floor +local format = string.format +local imap, nested_get, lines = util.imap, util.nested_get, util.lines +local parse_uri, make_uri = util.parse_uri, util.make_uri +local log = util.log + +-- Use cjson if available, otherwise fall back to `digestif.util` +-- implementation. +local null, json_decode, json_encode +if pcall(require, "cjson") then + local cjson = require "cjson" + cjson.encode_empty_table_as_object(false) + null = cjson.null + json_decode, json_encode = cjson.decode, cjson.encode +else + null = util.json_null + json_decode, json_encode = util.json_decode, util.json_encode +end + +--* Convert LSP API objects to/from internal representations + +-- This will be a digestif.Cache object. Its initialization is +-- deferred to `initialized` method. +local cache = setmetatable({}, { + __index = function () error "Server not initialized!" end +}) + +-- A place to store the file name and texformat of open documents. +local open_documents = setmetatable({}, { + __index = function(_, k) + error(format("Trying to access unopened document %s", k)) + end +}) + +local function from_DocumentUri(str) + local scheme, auth, path, query, fragment = parse_uri(str) + if scheme ~= "file" or (auth and auth ~= "") or query or fragment then + error("Invalid or unsupported URI: " .. str) + end + if util.os_type == "windows" and path:find("^/%a:") then + path = path:sub(2) + end + return path +end + +local function to_DocumentUri(str) + if util.os_type == "windows" then + str = str:gsub("[/\\]", "/") + if str:find("^%a:") then str = "/" .. str end + end + return make_uri("file", "", str) +end + +-- p0 is the position of a line l0, provided as a hint for the search. +-- Return a position in bytes, and a new hint p0, l0. +local function from_Position(str, position, p0, l0) + local l, c = position.line + 1, position.character + 1 + if l0 and l0 > l then p0, l0 = nil, nil end + for n, i in lines(str, p0, l0) do + if n == l then + return utf8.offset(str, c, i), i, l + end + end +end + +local function from_Range(str, range, p0, l0) + local pos, p1, l1 = from_Position(str, range.start, p0, l0) -- inclusive + local cont = from_Position(str, range['end'], p1, l1) -- exclusive + if not (pos and cont) then error("Position out of bounds") end + return pos, cont, p1, l1 +end + +local function from_TextDocumentIdentifier(arg) + local filename = from_DocumentUri(arg.uri) + local texformat = open_documents[filename] + local script = cache:manuscript(filename, texformat) + return script +end + +local function from_TextDocumentPositionParams(arg) + local filename = from_DocumentUri(arg.textDocument.uri) + local texformat = open_documents[filename] + local script = cache:manuscript(filename, texformat) + local l, c = arg.position.line + 1, arg.position.character + 1 + return script, script:position_at(l, c) +end + +local function to_Range(item) + local script = item.manuscript + local l1, c1 = script:line_column_at(item.pos) + local l2, c2 = script:line_column_at(item.cont) + return { + start = {line = l1 - 1, character = c1 - 1}, + ["end"] = {line = l2 - 1, character = c2 - 1}, + } +end + +local function to_Location(item) + return { + uri = to_DocumentUri(item.manuscript.filename), + range = to_Range(item) + } +end + +local function to_MarkupContent(str) + return {kind = "markdown", value = str} +end + +local function to_TextEdit(script, pos, old, new) + local l, c_start = script:line_column_at(pos) + local c_end = c_start + utf8.len(old) + return { + range = { + start = {line = l - 1, character = c_start - 1}, + ["end"] = {line = l - 1, character = c_end - 1}, + }, + newText = new + } +end + +-- An essentially random assignment of symbol kinds, since LSP doesn't +-- support custom kinds. +local to_SymbolKind = { + section = 5, + section_index = 5, + label_index = 7, + bib_index = 20, + newcommand_index = 12, + newenvironment_index = 12 +} + +local function to_SymbolInformation(item, index_name) + return { + name = item.name, + kind = to_SymbolKind[index_name], + location = to_Location(item) + } +end + +local function to_DocumentSymbol(outline) + return { + name = outline.name, + kind = to_SymbolKind[outline.kind], + range = to_Range(outline), + selectionRange = to_Range(outline), + children = outline[1] and imap(to_DocumentSymbol, outline) + } +end + +local languageId_translation_table = { + bibtex = "bibtex", + context = "context", + doctex = "doctex", + latex = "latex", + plain = "plain", + plaintex = "plain", + ["plain-tex"] = "plain", + tex = "latex", -- this is for vim; maybe "tex" should mean "tex file, undecided format" + texinfo = "texinfo" +} + +local function languageId_translate(id, filename) + local ext = filename:sub(-4) + local texformat = languageId_translation_table[id] + if not texformat then + error(("Invalid LSP language id %q"):format(id)) + end + if texformat == "latex" and (ext == ".sty" or ext == ".cls") then + return "latex-prog" + end + -- TODO: Handle .code.tex files from PGF, .mkiv files from ConTeXt, etc. + return texformat +end + +--* LSP methods + +local methods = {} + +methods["initialize"] = function(params) + config.provide_snippets = nested_get(params.capabilities, + "textDocument", "completion", "completionItem", "snippetSupport") + if params.initializationOptions then + config.load_from_table(params.initializationOptions) + end + return { + capabilities = { + textDocumentSync = { + openClose = true, + change = 2 + }, + completionProvider = { + triggerCharacters = {"\\", "{", "[", ",", "="}, + }, + signatureHelpProvider = { + triggerCharacters = {"{", "[", "="}, + }, + hoverProvider = true, + definitionProvider = true, + referencesProvider = true, + documentSymbolProvider = true, + workspaceSymbolProvider = true + }, + serverInfo = { + name = "Digestif", + version = config.version + } + } +end + +methods["initialized"] = function() + cache = require "digestif.Cache"() +end + +methods["shutdown"] = function() return null end +methods["exit"] = function() os.exit() end +methods["textDocument/willSave"] = function() end +methods["textDocument/didSave"] = function() end + +methods["workspace/didChangeConfiguration"] = function(params) + local settings = params.settings.digestif + if type(settings) ~= "table" then return end + config.load_from_table(settings) +end + +methods["textDocument/didOpen"] = function(params) + local filename = from_DocumentUri(params.textDocument.uri) + local texformat = languageId_translate(params.textDocument.languageId, filename) + open_documents[filename] = texformat + cache:put(filename, params.textDocument.text) +end + +methods["textDocument/didChange"] = function(params) + local filename = from_DocumentUri(params.textDocument.uri) + local p0, l0, src = 1, 1, cache(filename) + for _, change in ipairs(params.contentChanges) do + if change.range then + local pos, cont + pos, cont, p0, l0 = from_Range(src, change.range, p0, l0) + src = src:sub(1, pos - 1) .. change.text .. src:sub(cont) + else + src = change.text + end + end + cache:put(filename, src) +end + +methods["textDocument/didClose"] = function(params) + local filename = from_DocumentUri(params.textDocument.uri) + open_documents[filename] = nil + cache:forget(filename) +end + +methods["textDocument/signatureHelp"] = function(params) + local script, pos = from_TextDocumentPositionParams(params) + local help = script:describe(pos) + if not help or not help.arg then return null end + local parameters, label_positions = {}, help.label_positions or {} + for i, arg in ipairs(nested_get(help, "data", "arguments") or {}) do + parameters[i] = { + label = {label_positions[2*i-1] - 1, label_positions[2*i] - 1}, + documentation = arg.summary + } + end + return { + signatures = { + [1] = { + label = help.label, + documentation = help.summary, + parameters = parameters, + activeParameter = help.arg - 1 + } + }, + activeSignature = 0, + activeParameter = help.arg - 1 + } +end + +methods["textDocument/hover"] = function(params) + local script, pos = from_TextDocumentPositionParams(params) + local help = script:describe(pos) + if (not help) or help.arg then return null end + local contents = help.details or help.summary or "???" + return {contents = to_MarkupContent(contents)} +end + +methods["textDocument/completion"] = function(params) + local script, pos = from_TextDocumentPositionParams(params) + local candidates = script:complete(pos) + if not candidates then return null end + local long_format = config.lsp_long_candidates + and config.lsp_long_candidates[candidates.kind] + local items = {} + for i, cand in ipairs(candidates) do + local snippet = config.provide_snippets and cand.snippet + local fuzzy_score = cand.fuzzy_score or nil + local annotation = cand.annotation + local long_label = long_format and annotation + and format(long_format, cand.text, annotation) + items[i] = { + label = long_label or cand.text, + sortText = fuzzy_score and format("~%03d", floor(1000 * (1 - fuzzy_score))), + documentation = cand.summary, + detail = not long_label and cand.annotation or nil, + insertTextFormat = snippet and 2 or 1, + textEdit = to_TextEdit( + script, + candidates.pos, + candidates.prefix, + snippet or cand.text + ) + } + end + return items +end + +methods["textDocument/definition"] = function(params) + local script, pos = from_TextDocumentPositionParams(params) + local definition = script:find_definition(pos) + return definition and to_Location(definition) or null +end + +methods["textDocument/references"] = function(params) + local script, pos = from_TextDocumentPositionParams(params) + local result = {} + if params.context and params.context.includeDeclaration then + local definition = script:find_definition(pos) + if definition then + result[#result + 1] = to_Location(definition) + end + end + local references = script:find_references(pos) + if references then + for _, ref in ipairs(references) do + result[#result + 1] = to_Location(ref) + end + end + if #result > 0 then + return result + else + return null + end +end + +methods["textDocument/documentSymbol"] = function(params) + local script = from_TextDocumentIdentifier(params.textDocument) + local outline = script:outline(true) -- local only + return imap(to_DocumentSymbol, outline) +end + +methods["workspace/symbol"] = function(params) + local query, t = params.query, {} + + -- Find all root documents and sort them + local root_documents, sorted = {}, {} + for filename, texformat in pairs(open_documents) do + local script = cache:manuscript(filename, texformat) + root_documents[script.root.filename] = script.root + end + + for filename in pairs(root_documents) do + sorted[#sorted+1] = filename + end + table.sort(sorted) + + -- Gather all entries in all indexes + for _, filename in ipairs(sorted) do + local script = root_documents[filename] + for item, index_name in script:traverse { + "section_index", + "label_index", + "bib_index", + "newcommand_index", + "newenvironment_index" + } do + if item.name:find(query, 1, true) then + t[#t+1] = to_SymbolInformation(item, index_name) + end + end + end + return t +end + +--* RPC functions + +local function log_error(err) + if config.verbose then + log("Error: %s", err) + log(debug.traceback()) + end + return err +end + +local crlf = util.os_type == "windows" and "\n" or "\r\n" + +local function write_msg(msg) + io.write("Content-Length: ", #msg, crlf, crlf, msg) + io.flush() +end + +local function read_msg() + local headers, msg = {}, nil + for h in io.lines() do + if h == "" or h == "\r" then break end + local k, v = string.match(h, "^([%a%-]+): (.*)") + if k then headers[k] = v end + end + local len = tonumber(headers["Content-Length"]) + if len then msg = io.read(len) end + return msg, headers +end + +local function rpc_send(id, result, error_code) + write_msg( + json_encode({ + jsonrpc = "2.0", + id = id, + result = not error_code and result or nil, + error = error_code and {code = error_code, message = result} + })) +end + +local function rpc_receive() + local msg = read_msg() + local ok, request = xpcall(json_decode, log_error, msg) + if not ok then + rpc_send(null, request, -32700) + os.exit(false) + end + return request.id, request.method, request.params +end + +--* The main loop + +local is_optional = util.matcher("$/") + +local function process_request() + local clock = config.verbose and os.clock() + local id, method_name, params = rpc_receive() + local method = methods[method_name] + if method then + local ok, result = xpcall(method, log_error, params) + if ok then + if id then rpc_send(id, result) end + else + rpc_send(id, result, 1) + end + elseif not is_optional(method_name) then + rpc_send(id, "Unknown method " .. method_name, -32601) + end + if clock then + log("Request: %4s %-40s %6.2f ms", + id or "*", method_name, 1000 * (os.clock() - clock)) + end +end + +local function generate(path) + local generate_tags = require "digestif.data".generate_tags + local tags = generate_tags(path) + if not tags then + io.stderr:write( + format("Error: can't find '%s' or can't generate tags from it.\n", path) + ) + os.exit(false) + end + local _, basename = util.path_split(path) + local file = io.open(basename .. ".tags", "w") + for _, item in ipairs( + {"generated", "dependencies", "documentation", "commands", "environments"}) + do + if tags[item] then + file:write(item, " = ", util.inspect(tags[item]), "\n") + end + end + local i, j = 0, 0 + for _ in pairs(tags.commands) do i = i + 1 end + for _ in pairs(tags.environments) do j = j + 1 end + io.stderr:write( + format("Generated %15s.tags with %3i commands and %3i environments.\n", + basename, i, j) + ) +end + +local usage = [[ +Usage: digestif [--version] [-h] [-v] [-g FILES] +]] + +local help = [[ +Digestif is a language server for TeX + +Optional arguments: + -g, --generate FILES Generate data file stubs for FILES + -h, --help Display this message and exit + -v, --verbose Enable log output to stderr + --version Show version information + +Environment variables: + DIGESTIF_DATA Paths to look for data files + DIGESTIF_TEXMF Paths to look for TeX files + DIGESTIF_TLPDB Path to the TeXLive package database file + + If your TeX distribution or Digestif are installed in a non-standard + location, you may need to set some of the above variables. +]] + +local function main(arg) + -- Set up default config.data_dirs, if needed + config.load_from_env() + if #config.data_dirs == 0 then + for _, dir in ipairs{ + util.path_split(debug.getinfo(1).source:match("^@(.*)")), + util.path_split(arg[0]), + nil + } do + local f = io.open(util.path_join(dir, "../data/primitives.tags")) + if f then + f:close() + config.data_dirs = {util.path_join(dir, "../data")} + break + end + end + end + + -- Read CLI args + while arg[1] do + local switch = table.remove(arg, 1) + if switch == "-v" or switch == "--verbose" then + config.verbose = true + elseif switch == "-g" or switch == "--generate" then + for i = 1, #arg do generate(arg[i]) end + os.exit() + elseif switch == "-h" or switch == "--help" then + io.write(usage) + io.write(help) + os.exit() + elseif switch == "--version" then + io.write(format("Digestif %s\n", config.version)) + os.exit() + else + io.stderr:write(usage) + io.stderr:write(format("Invalid option: %s\n", switch)) + os.exit(false) + end + end + + -- Check if config.data_dirs was set up correctly + if not util.find_file(config.data_dirs, "primitives.tags") then + io.stderr:write( + "Error: could not find data files at the following locations:\n\t" + .. table.concat(config.data_dirs, "\n\t") + .. "\nSet the DIGESTIF_DATA environment variable to fix this.\n" + ) + os.exit(false) + end + + -- Main language server loop + if config.verbose then log("Digestif started!") end + while true do process_request() end +end + +return { + main = main, + methods = methods +} + diff --git a/support/digestif/digestif/util.lua b/support/digestif/digestif/util.lua new file mode 100644 index 0000000000..2e042ebd70 --- /dev/null +++ b/support/digestif/digestif/util.lua @@ -0,0 +1,789 @@ +-- Assorted utility functions + +local lpeg = require "lpeg" +local zip = pcall(require, "zip") and require "zip" + +local io, os = io, os +local co_yield, co_wrap = coroutine.yield, coroutine.wrap +local strupper, strfind, strsub, strrep = string.upper, string.find, string.sub, string.rep +local strchar, strbyte, utf8_char = string.char, string.byte, utf8.char +local format, gsub = string.format, string.gsub +local pack, unpack, concat = table.pack, table.unpack, table.concat +local move, sort = table.move, table.sort +local pairs, getmetatable, setmetatable = pairs, getmetatable, setmetatable +local P, V, R, S, I, B = lpeg.P, lpeg.V, lpeg.R, lpeg.S, lpeg.Cp(), lpeg.B +local C, Cs, Cf, Ct, Cc, Cg = lpeg.C, lpeg.Cs, lpeg.Cf, lpeg.Ct, lpeg.Cc, lpeg.Cg +local match, locale_table = lpeg.match, lpeg.locale() + +local util = {} + +--* Table manipulation + +local function map(f, t) + local r = {} + for k, v in pairs(t) do + r[k] = f(v) + end + return r +end +util.map = map + +local function imap(f, t) + local r = {} + for i = 1, #t do + r[i] = f(t[i]) + end + return r +end +util.imap = imap + +-- Return a table with entries (k, f(k)), where k ranges over the keys +-- of t and all its __index parents. +local function map_keys(f, t) + local mt = getmetatable(t) + local p = mt and mt.__index + local r = p and map_keys(f, p) or {} + for k in pairs(t) do + r[k] = f(k) + end + return r +end +util.map_keys = map_keys + +local function foldl1(f, t) + local v = t[1] + for i = 2, t.n or #t do + v = f(v, t[i]) + end + return v +end +util.foldl1 = foldl1 + +local function nested_get(t, ...) + local arg = pack(...) + for i = 1, #arg do + if t then t = t[arg[i]] else return nil end + end + return t +end +util.nested_get = nested_get + +local function nested_put(v, t, ...) + local arg = pack(...) + local k = arg[1] + for i = 2, arg.n do + local u = t[k] + if u == nil then u = {}; t[k] = u end + t, k = u, arg[i] + end + t[k] = v + return v +end +util.nested_put = nested_put + +-- Copy all entries of s onto t +local function update(t, s) + if s then + for k, v in pairs(s) do + t[k] = v + end + end + return t +end +util.update = update + +-- Return a new table containing all entries of the given tables, +-- priority given to the latter ones. +local function merge(...) + return foldl1(update, pack({}, ...)) +end +util.merge = merge + +-- Copy entries of the second list to the end of the first. +local function extend(s, t) + return move(t, 1, #t, #s+1, s) +end +util.extend = extend + +-- Iterate over a table of tables. +local function triples(t) + return co_wrap( + function() + for i, u in pairs(t) do + for j, v in pairs(u) do + co_yield(i, j, v) + end + end + end + ) +end +util.triples = triples + +--* Cool combinators and friendly functions for LPeg + +--** Simple things for better legibility of complicated constructions + +local lpeg_add = getmetatable(P(true)).__add +local lpeg_mul = getmetatable(P(true)).__mul +local lpeg_pow = getmetatable(P(true)).__pow + +local char = P(1) -- in most cases, this works with utf8 too +local uchar = R("\0\127") + R("\194\244") * R("\128\191")^-3 +local hex = R("09", "AF", "af") +local alnum = R("09", "AZ", "az") +local alpha = R("AZ", "az") +local eol = P("\n") + +local function choice(...) + return foldl1(lpeg_add, pack(...)) +end +util.choice = choice + +local function sequence(...) + return foldl1(lpeg_mul, pack(...)) +end +util.sequence = sequence + +local function many(times, patt) + if patt then + return lpeg_pow(patt, times) + else + return lpeg_pow(times, 0) + end +end +util.many = many + +-- Return a function to match against a pattern +local function matcher(patt) + patt = P(patt) + return function(s, i) return match(patt, s, i) end +end +util.matcher = matcher + +-- Return a function to perfom replacement. Like string.gsub, but +-- partially evaluated +local function replace(patt, repl, token) + token = token and P(token) or char + patt = Cs((P(patt) / repl + token)^0) + return function(s, i) return match(patt, s, i) end +end +util.replace = replace + +util.lpeg_escape = replace("%", "%%%%") + +--** General purpose combinators + +local function search(patt, token) + token = token and P(token) or char + return P{P(patt) + token * V(1)} +end +util.search = search + +local function gobble(patt, token) + token = token and P(token) or char + return (token - P(patt))^0 +end +util.gobble = gobble +util.gobble_until = gobble + +local function between_balanced(l, r, token) --nicer name? + l, r = P(l), P(r) + token = token and P(token) or char + return P{l * C(((token - l - r) + V(1)/0)^0) * r} +end +util.between_balanced = between_balanced + +-- function case_fold(str) +-- +-- Return a pattern that matches the given string, ignoring case. +-- Uppercase characters in the input still match only uppercase. +-- Indexing case_fold as a table does the same, but for individual +-- characters only. +local case_fold = {} +for i = strbyte"a", strbyte"z" do + local c = strchar(i) + case_fold[c] = S(c .. strupper(c)) +end +local cf_patt = Cf((C(char) / case_fold)^1, lpeg_mul) +setmetatable(case_fold, { + __index = function(_, c) return P(c) end, + __call = function(_, s) return match(cf_patt, s) end +}) +util.case_fold = case_fold + +--** String functions, with a tendency towards currying + +-- Split a string at the given separators. `nulls` determines wheter +-- empty sequences are returned. +local function split(sep, token, nulls) + sep = sep and P(sep) or locale_table.space + token = token and P(token) or char + local patt + if nulls then + local item = C((token - sep)^0) + patt = Ct(item * (sep * item)^0) + else + patt = Ct((sep^0 * C((token - sep)^1))^0) + end + return function (s, i) return match(patt, s, i) end +end +util.split = split + +-- Remove spaces from the ends of subject. +local function trim(space, token) + space = space and P(space) or locale_table.space + token = token and P(token) or char + local patt = space^0 * C((space^0 * (token - space)^1)^0) + return function(s, i) return match(patt, s, i) end +end +util.trim = trim + +-- Trim and remove repeated spaces inside subject. +local function clean(space, token) + space = space and P(space) or locale_table.space + token = token and P(token) or char + local patt = space^0 * Cs(((space^1 / " " + true) * (token - space)^1)^0) + return function(s, i) return match(patt, s, i) end +end +util.clean = clean + +-- Return a list of new lines in the subject string. +util.line_indices = matcher(Ct(I * search(eol * I)^0)) + +local utf8_sync_patt = R("\128\191")^-3 * I + I + +-- Like string.sub, but don't break up UTF-8 codepoints. May return +-- a string slightly longer or shorter than j - i + 1 bytes. +local function strsub8(s, i, j) + i = match(utf8_sync_patt, s, i) + j = j and match(utf8_sync_patt, s, j + 1) - 1 + return strsub(s, i, j) +end +util.strsub8 = strsub8 + +--** Fuzzy matching + +local fuzzy_build_patt = Cf( + (C(uchar) / function(c) return search(I * case_fold[c]) end)^1, + lpeg_mul) + +-- Return a function that fuzzy-matches against a string. +-- Higher values of the "penalty parameter" p0 reduce the relative +-- penalty for long gaps. This is a made-up scoring algorithm, there +-- must be better ones. +-- +-- Arguments: +-- +-- - str: the string to match against +-- - p0: penalty parameter for computing scores, default is 2 +-- +local function fuzzy_matcher(str, p0) + if str == "" then return function() return 1 end end + p0 = p0 or 2 + local best_score = #str / (p0 + 1) -- Score of a prefix match + local search_patt = Ct(match(fuzzy_build_patt, str)) + return function(s, i) + local score, old_pos, matches = 0, 0, match(search_patt, s, i) + if not matches then return end + for j = 1, #matches do + local pos = matches[j] + score = score + 1 / (p0 + pos - old_pos) + old_pos = pos + end + return score / best_score + end +end +util.fuzzy_matcher = fuzzy_matcher + +--** Iterators + +local line_patt = I * (search(I * eol) * I + P(true)) + +local function lines(s, i, n) + return co_wrap(function() + local n, i, j, k = n or 1, match(line_patt, s, i) + while k do + co_yield(n, i, j - 1) + n, i, j, k = n + 1, match(line_patt, s, k) + end + co_yield(n, i or 1, #s) + end) +end +util.lines = lines + +--* Classes + +local function create_object (c, ...) + local obj = setmetatable({}, c) + c.__init(obj, ...) + return obj +end + +local function class(parent) + local c = {} + local mt = { + __call = create_object, + __index = parent + } + c.__index = c + return setmetatable(c, mt) +end +util.class = class + +--* Memoization + +local weak_keys, nil_marker, value_marker = {__mode = "k"}, {}, {} + +-- Memoize a function of one argument with one return value. Nil as +-- an argument is equivalent to false, and nil as return value is not +-- memoized. +local function memoize1(fun) + local values = setmetatable({}, weak_keys) + return function(arg) + arg = arg or false + local val = values[arg] + if val == nil then + val = fun(arg) + values[arg] = val + end + return val + end +end +util.memoize1 = memoize1 + +-- Return a memoizing version of a function. +local function memoize(fun) + local values = setmetatable({}, weak_keys) + return function(...) + local arg, val = pack(...), values + for i = 1, arg.n do + local a = arg[i] + if a == nil then a = nil_marker end + local v = val[a] + if v == nil then + v = setmetatable({}, weak_keys) + val[a] = v + end + val = v + end + local v = val[value_marker] + if v == nil then + v = pack(fun(...)) + val[value_marker] = v + end + return unpack(v, 1, v.n) + end +end +util.memoize = memoize + +--* OS utilities + +if package.config:sub(1, 1) == "\\" then + util.os_type = "windows" +else + util.os_type = "posix" +end + +local is_command_cmd = util.os_type == "windows" + and "WHERE /Q %q" + or ">/dev/null command -v %q" + +-- Return `name` if an executable with that name exists, nil +-- otherwise. +local function is_command(name) + local ok = os.execute(format(is_command_cmd, name)) + return ok and name or nil +end +util.is_command = is_command + +--* Path and file manipulation + +local dir_sep, dir_sep_patt, path_is_abs_patt + +if util.os_type == "windows" then + dir_sep = "/" + dir_sep_patt = S"/\\" + path_is_abs_patt = (alpha * P":")^-1 * dir_sep_patt +else + dir_sep = "/" + dir_sep_patt = P"/" + path_is_abs_patt = dir_sep_patt +end + +-- Concatenate two paths. If the second is absolute, the first one is +-- ignored. +local function path_join(p, q) + if match(path_is_abs_patt, q) or p == "" then + return q + else + local sep = match(dir_sep_patt, p, #p) and "" or dir_sep + return p .. sep .. q + end +end +util.path_join = path_join + +-- Split a path into directory and file parts. +local path_split_patt = sequence( + C(sequence( + many(dir_sep_patt), + gobble( + sequence( + dir_sep_patt^0, + many(1 - dir_sep_patt), + P(-1))))), + dir_sep_patt^0, + C(many(char)) +) + +local function path_split(p) + return match(path_split_patt, p) +end +util.path_split = path_split + +local path_norm_double_sep = Cs(search((dir_sep_patt ^ 2) / dir_sep) * P(1)^0) +local path_norm_dot_patt = Cs( + search(((B(dir_sep_patt) + B(-1)) * P"." * dir_sep_patt) / "") * P(1)^0) +local path_norm_dotdot_patt = Cs( + search(((1 - dir_sep_patt)^1 * dir_sep_patt * P".." * dir_sep_patt) / "") * P(1)^0) + +-- Normalize a path name, removing repeated separators and "./" and "../" +local function path_normalize(p) + local q = match(path_norm_double_sep, p) + or match(path_norm_dot_patt, p) + or match(path_norm_dotdot_patt, p) + if q then + return path_normalize(q) + elseif util.os_type == "windows" then + return p:gsub("\\", "/") + else + return p + end +end +util.path_normalize = path_normalize + +if util.os_type == "windows" then + util.path_list_split = split";" +else + util.path_list_split = split":" +end + +local function format_filename_template(template, name) + name = gsub(name, "%%", "%%%%") + return gsub(template, "?", name) +end +util.format_filename_template = format_filename_template + +-- Look for a file in several locations. `path` is a string or a list +-- of strings. The optional `name` is joined to each element. +-- Returns the first file name that exists on disk. If `read` is +-- true, give the file contents as second return value. +local function find_file(path, name, read) + if type(path) == "table" then + for i = 1, #path do + local p, s = find_file(path[i], name, read) + if p then return p, s end + end + return + end + local file + local zipfile = zip and name and zip.open(path) + if zipfile then + path = path .. "#" .. name + file = zipfile:open(name) + zipfile:close() + else + if name then path = path_join(path, name) end + file = io.open(path) + end + if file then + local str = read and file:read("*a") + file:close() + return path, str + end +end +util.find_file = find_file + +--* URI manipulation + +local percent_decode = replace( + P"%" * C(hex * hex), + function(s) return strchar(tonumber(s, 16)) end +) + +local percent_encode = replace( + char - (alnum + S"-./:=_~"), + function(s) return format("%%%X", strbyte(s)) end +) + +local uri_patt = sequence( + C(alpha^1) * P":", + (P"//" * C(gobble("/"))) + Cc(nil), + C(gobble(S"?#")) / percent_decode, + (P"?" * C(gobble("#")) / percent_decode) + Cc(nil), + (P"#" * C(char^0) / percent_decode) + Cc(nil) +) +util.parse_uri = matcher(uri_patt) + +local function make_uri(scheme, authority, path, query, fragment) + local t = {} + if scheme then t[#t+1] = scheme; t[#t+1] = ":" end + if authority then t[#t+1] = "//"; t[#t+1] = authority end + if path then t[#t+1] = percent_encode(path) end + if query then t[#t+1] = "?"; t[#t+1] = percent_encode(query) end + if fragment then t[#t+1] = "#"; t[#t+1] = percent_encode(fragment) end + return concat(t) +end +util.make_uri = make_uri + +--* JSON + +util.json_null = setmetatable({}, {__json = "null"}) + +--** Decoding + +do + local ws = S" \n\t\r"^0 + local quote = P"\"" + + local function decode_number(s) + return tonumber(s) or error("Error parsing “" .. s .. "” as a number") + end + + local char_or_escape = choice( + P(1) - P"\\", + P"\\n" / "\n", + P"\\\"" / "\"", + P"\\\\" / "\\", + P"\\/" / "/", + P"\\r" / "\r", + P"\\t" / "\t", + P"\\b" / "\b", + P"\\f" / "\f", + P"\\u" * C(S"Dd" * S"89ABab" * hex * hex) + * P"\\u" * C(S"Dd" * R("CF","cf") * hex * hex) + / function(high, low) + high = tonumber(high, 16) + low = tonumber(low, 16) + return utf8_char( + (high - 0xD800) * 2^10 + low - 0xDC00 + 0x10000) + end, + P"\\u" * C(hex * hex * hex * hex) + / function(s) return utf8_char(tonumber(s, 16)) end + ) + + local json_patt = P{ + [1] = ws * V"element" * P(-1), + ["true"] = P"true" * Cc(true) * ws, + ["false"] = P"false" * Cc(false) * ws, + null = P"null" * Cc(util.json_null) * ws, + number = (R"09" + S"-+.") * (1 - S",]}")^0 / decode_number, + string = quote * Cs(gobble(quote, char_or_escape)) * quote * ws, + element = V"string" + V"number" + V"true" + V"false" + V"null" + V"array" + V"object", + elements = V"element" * (P"," * ws * V"element")^0, + array = P"[" * ws * Ct(V"elements"^-1) * P"]" * ws, + member = Cg(V"string" * P":" * ws * V"element"), + members = V"member" * (P"," * ws * V"member")^0, + object = P"{" * ws * Cf(Ct(true) * V"members"^-1, rawset) * P"}" * ws + } + + function util.json_decode(str) + return match(json_patt, str) or error "Error decoding json" + end +end + +--** Encoding + +do + local control_chars = {} + for i = 0, 31 do + control_chars[strchar(i)] = format("\\u%04x", i) + end + + local encode_string = matcher( + Cs(many(choice( + P(1) - R"\0\31" - S"\"\\", + P"\n" / "\\n", + P"\"" / "\\\"", + P"\\" / "\\\\", + P"\r" / "\\r", + P"\t" / "\\t", + P"\b" / "\\b", + P"\f" / "\\f", + R"\0\31" / control_chars + )))) + + local fix_decimal + local decimal_sep = tostring(5.5):gsub("5", "") + if decimal_sep == "." then + fix_decimal = function(x) return x end + else + fix_decimal = replace(decimal_sep, ".") + end + + local inf = math.huge + + local function encode_number(v) + if -inf < v and v < inf then + return fix_decimal(tostring(v)) + else + return "null" + end + end + + local function do_encode(obj, t, n) + local obj_type = type(obj) + if obj_type == "string" then + t[n] = "\"" + t[n + 1] = encode_string(obj) + t[n + 2] = "\"" + return n + 3 + elseif obj_type == "number" then + t[n] = encode_number(obj) + return n + 1 + elseif obj_type == "table" then + local v = obj[1] + if v ~= nil then + t[n] = "[" + n = do_encode(v, t, n + 1) + for i = 2, #obj do + t[n] = "," + n = do_encode(obj[i], t, n + 1) + end + t[n] = "]" + return n + 1 + end + local k, v = next(obj) + if k ~= nil then + t[n] = "{\"" + t[n + 1] = encode_string(k) + t[n + 2] = "\":" + n = do_encode(v, t, n + 3) + for k, v in next, obj, k do + t[n] = ",\"" + t[n + 1] = encode_string(k) + t[n + 2] = "\":" + n = do_encode(v, t, n + 3) + end + t[n] = "}" + return n + 1 + else + local mt = getmetatable(obj) + t[n] = mt and mt.__json or "[]" + return n + 1 + end + elseif obj_type == "boolean" then + t[n] = obj and "true" or "false" + return n + 1 + else + error("Error encoding json, found object of type " .. type) + end + end + + function util.json_encode(obj) + local t = {} + do_encode(obj, t, 1) + return concat(t) + end +end + +--* Inspect and serialize Lua values + +-- function inspect(obj, depth) +-- +-- Return a string representation of `obj`, with at most `depth` +-- layers of nested tables. If `obj` consists solely of scalars, +-- strings and tables and does not exceed the maximum nesting, the +-- return value is valid Lua code. +-- +local inspect + +local is_lua_identifier = util.matcher( + C(R("AZ", "az", "__") * R("09", "AZ", "az", "__")^0) * P(-1) + / function(s) return load("local " .. s) and s end +) + +local function lua_encode_key(obj) + if type(obj) == "string" then + if is_lua_identifier(obj) then + return obj + else + return "[" .. format("%q", obj) .. "]" + end + else + return "[" .. tostring(obj) .. "]" + end +end + +local function lua_encode_string(obj) + if strfind(obj, "\n", 1, true) then + local delim = "" + while strfind(obj, "]" .. delim .. "]", 1, true) do + delim = delim .. "=" + end + return "[" .. delim .. "[\n" .. obj .. "]" .. delim .. "]" + else + return format("%q", obj) + end +end + +local function lua_encode_table(obj, depth, d) + local t = {} + local array_keys, hash_keys = {}, {} + for i = 1, #obj do + array_keys[i] = true + t[#t+1] = inspect(obj[i], depth, d+1) + end + for k in pairs(obj) do + if not array_keys[k] then + hash_keys[#hash_keys+1] = k + end + end + sort( + hash_keys, + function(v, w) return tostring(v) < tostring(w) end + ) + for i = 1, #hash_keys do + local k = hash_keys[i] + local v = obj[k] + t[#t+1] = lua_encode_key(k) .. " = " .. inspect(v, depth, d+1) + end + local short = concat(t, ", ") + if 2*d + #short > 70 or strfind(short, "\n", 1, true) then + local sep = strrep(" ", d) + return "{\n " .. sep .. concat(t, ",\n " .. sep) .. "\n" .. sep .. "}" + else + return "{" .. short .. "}" + end +end + +inspect = function(obj, depth, d) + depth, d = depth or 10, d or 0 + if type(obj) == "table" and d < depth then + return lua_encode_table(obj, depth, d) + elseif type(obj) == "string" then + if d < depth or #obj < 20 then + return lua_encode_string(obj) + else + return format("string: \"%s...\"", strsub(obj, 1, 9)) + end + else + return tostring(obj) + end +end +util.inspect = inspect + +--* Logging + +local function log(msg, ...) + if select("#", ...) > 0 then msg = format(msg, ...) end + io.stderr:write(os.date("%H:%M:%S "), msg, "\n") + io.stderr:flush() +end +util.log = log + +local function log_objects(...) + return log(concat(map(inspect, {...}), "\n")) +end +util.log_objects = log_objects + +return util -- cgit v1.2.3