summaryrefslogtreecommitdiff
path: root/info/latex2e-help-texinfo/latex2e.dbk
diff options
context:
space:
mode:
Diffstat (limited to 'info/latex2e-help-texinfo/latex2e.dbk')
-rw-r--r--info/latex2e-help-texinfo/latex2e.dbk4875
1 files changed, 3585 insertions, 1290 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.dbk b/info/latex2e-help-texinfo/latex2e.dbk
index 5c203240fa..b1a75624cb 100644
--- a/info/latex2e-help-texinfo/latex2e.dbk
+++ b/info/latex2e-help-texinfo/latex2e.dbk
@@ -4,44 +4,41 @@
<!ENTITY latex "LaTeX">
]>
<book id="latex2e.dbk" lang="en">
-<!-- $Id: common.texi 701 2018-10-08 14:32:37Z jimhefferon $ -->
+<!-- $Id: common.texi 729 2018-11-13 23:22:27Z karl $ -->
<!-- Public domain. -->
-
-<title>&latex;2e unofficial reference manual (October 2018)</title>
+<title>&latex;2e unofficial reference manual (July 2021)</title>
<!-- %**end of header (This is for running Texinfo on a region.) -->
<!-- latex 2.09 commands should all be present now, -->
<!-- xx but latex2e stuff is missing. -->
<!-- xx random list of a few of the missing items is at the end of this file -->
+<!-- xx read through latex2e news for things to update. -->
<!-- -->
<!-- xx ctan, distributions, components of TeX -->
-<!-- xx classes and packages - required, additional, useful; oberdiek; fonts -->
-<!-- -->
+<!-- xx classes and packages: required, additional, useful; oberdiek; fonts -->
<!-- xx merge permuted-index -->
<!-- xx merge latex-manual from savannah -->
<!-- xx merge display style math -->
+<!-- xx check recent ltnews for (lots of) changes -->
+<!-- xx \write of non-ASCII chars (vincent mail of 14 Mar 2020 21:39:41) -->
+<!-- xx \nonstopmode etc., if they are officially supported by LaTeX? -->
<!-- xx JH explain nfss somewhere -->
<!-- xx JH expand BiBTeX -->
<!-- xx JH expand theorem, AMS math -->
<!-- xx JH something on code listings -->
<!-- xx JH ligatures -->
-<!-- xx JH \xspace -->
-<!-- xx JH \stretch -->
-<!-- xx JH \mathstrut -->
-<!-- xx JH \phantom https://tex.stackexchange.com/questions/4519/how-do-i-create-an-invisible-character -->
-<!-- xx JH \baselineskip https://texfaq.org/FAQ-baselinepar -->
-<!-- xx JH \contentsline, \@@dottedtocline? -->
-<!-- xx JH more on \write18, beyond what's mentioned in Command line. -->
-<!-- xx JH \numexpr, \dimexpr, \glueexpr, \muexpr -->
+<!-- xx JH \caption -->
<!-- -->
<!-- xx The typeset source2e has an index with all kernel -->
<!-- xx commands, though some are internal and shouldn't be included. -->
<!-- xx classes.dtx et al. define additional commands. -->
<!-- xx See also http://ctan.org/pkg/macros2e. -->
+<!-- -->
+<!-- xx All the special characters should be definitively described. -->
<bookinfo><legalnotice><para>This document is an unofficial reference manual for &latex;, a
-document preparation system, version of October 2018.
+document preparation system, version of July 2021.
</para>
<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the
VMS Help Library. The pre-translation version was written by
@@ -58,7 +55,7 @@ latex2e-reference by Martin Herbert Dietze. (From these references no
text was directly copied.)
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
-2014, 2015, 2016, 2017, 2018 Karl Berry.
+2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
@@ -83,8 +80,9 @@ into another language, under the above conditions for modified versions.
+
<para>This document is an unofficial reference manual for &latex;, a
-document preparation system, version of October 2018.
+document preparation system, version of July 2021.
</para>
<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the
VMS Help Library. The pre-translation version was written by
@@ -101,7 +99,7 @@ latex2e-reference by Martin Herbert Dietze. (From these references no
text was directly copied.)
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
-2014, 2015, 2016, 2017, 2018 Karl Berry.
+2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
@@ -123,7 +121,6 @@ into another language, under the above conditions for modified versions.
<!-- end of License -->
</para>
-
<!-- Best Effort Symbol -->
@@ -131,10 +128,9 @@ into another language, under the above conditions for modified versions.
<title>&latex;2e: An unofficial reference manual</title>
<para>This document is an unofficial reference manual (version of
-October 2018) for &latex;2e, a document preparation system.
+July 2021) for &latex;2e, a document preparation system.
</para>
-
</chapter>
<chapter label="1" id="About-this-document">
<title>About this document</title>
@@ -144,15 +140,11 @@ October 2018) for &latex;2e, a document preparation system.
preparation system, which is a macro package for the &tex;
typesetting program (see <link linkend="Overview">Overview</link>).
</para>
-<para>This document&#8217;s home page is <ulink url="https://puszcza.gnu.org.ua/software/latexrefman">https://puszcza.gnu.org.ua/software/latexrefman</ulink>. There
-you can get the sources, subscribe to the mailing list or read its
-archives, see other infrastructure, and get the current output in
-various formats. In particular, the output comes in two web formats.
-Probably the most convenient one, shown at <ulink url="http://latexref.xyz/">http://latexref.xyz/</ulink>,
-has pages for each topic and so is good for a quick lookup; see also the
-note there about easy-to-remember links. The other, shown at
-<ulink url="http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co">http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co</ulink>,
-has all the information on single page.
+<para>This document&#8217;s home page is <ulink url="https://latexref.xyz">https://latexref.xyz</ulink>; it has
+separate web pages for each topic. Alternatively.
+<ulink url="https://latexref.xyz/dev/latex2e.html">https://latexref.xyz/dev/latex2e.html</ulink> has the entire document on
+a single page. For other output formats, the sources, and plenty more
+information, see <ulink url="https://latexref.xyz/dev/">https://latexref.xyz/dev/</ulink>.
</para>
<indexterm role="cp"><primary>&latex; vs. &latex;2e</primary></indexterm>
<para>In this document, we will mostly just use &#8216;&latex;&#8217; rather than
@@ -162,39 +154,33 @@ frozen decades ago.
<indexterm role="cp"><primary>unofficial nature of this manual</primary></indexterm>
<indexterm role="cp"><primary>&latex; Project team</primary></indexterm>
<indexterm role="fn"><primary><email>latexrefman@tug.org</email> email address</primary></indexterm>
-<para>&latex; is currently maintained by a group of volunteers
-(<ulink url="http://latex-project.org">http://latex-project.org</ulink>). The official documentation written by
-the &latex; project is available from their web site. This document is
-completely unofficial and has not been reviewed by the &latex;
-maintainers.
+<para>&latex; is maintained by a group of volunteers
+(<ulink url="https://latex-project.org">https://latex-project.org</ulink>). The official documentation written
+by the &latex; project is available from their web site. The present
+document is completely unofficial and has not been written or reviewed
+by the &latex; maintainers.
<indexterm role="cp"><primary>bug reporting</primary></indexterm>
<indexterm role="cp"><primary>reporting bugs</primary></indexterm>
Do not send bug reports or anything else about this document to them.
Instead, please send all comments to <email>latexrefman@tug.org</email>.
</para>
-<para>This document is a reference. There is a vast array of other sources
-of information about &latex;, at all levels. Here are a few
-introductions.
+<para>This document is a reference, not a tutorial. There is a vast array
+of other information available about &latex;, at all levels. Here
+are a few introductions.
</para>
-<variablelist><varlistentry><term><ulink url="http://ctan.org/pkg/latex-doc-ptr">http://ctan.org/pkg/latex-doc-ptr</ulink>
+<variablelist><varlistentry><term><ulink url="https://ctan.org/pkg/latex-doc-ptr">https://ctan.org/pkg/latex-doc-ptr</ulink>
</term><listitem><indexterm role="fn"><primary>latex-doc-ptr document</primary></indexterm>
<para>Two pages of recommended references to &latex; documentation.
</para>
-</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/first-latex-doc">http://ctan.org/pkg/first-latex-doc</ulink>
+</listitem></varlistentry><varlistentry><term><ulink url="https://ctan.org/pkg/first-latex-doc">https://ctan.org/pkg/first-latex-doc</ulink>
</term><listitem><indexterm role="fn"><primary>first-latex-doc document</primary></indexterm>
<para>Writing your first document, with a bit of both text and math.
</para>
-</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/usrguide">http://ctan.org/pkg/usrguide</ulink>
-</term><listitem><indexterm role="fn"><primary>usrguide official documentation</primary></indexterm>
-<para>The guide for document authors that is maintained as part of &latex;.
-Many other guides by many other people are also available, independent
-of &latex; itself; one such is the next item:
-</para>
-</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/lshort">http://ctan.org/pkg/lshort</ulink>
+</listitem></varlistentry><varlistentry><term><ulink url="https://ctan.org/pkg/lshort">https://ctan.org/pkg/lshort</ulink>
</term><listitem><indexterm role="fn"><primary>lshort document</primary></indexterm>
-<para>A short introduction to &latex;, translated to many languages.
+<para>A longer introduction to &latex;, translated to many languages.
</para>
-</listitem></varlistentry><varlistentry><term><ulink url="http://tug.org/begin.html">http://tug.org/begin.html</ulink>
+</listitem></varlistentry><varlistentry><term><ulink url="https://tug.org/begin.html">https://tug.org/begin.html</ulink>
</term><listitem><para>Introduction to the &tex; system, including &latex;, with further
references.
</para>
@@ -211,21 +197,25 @@ references.
<indexterm role="cp"><primary>&latex; overview</primary></indexterm>
<para>&latex; is a system for typesetting documents. It was originally
-created by Leslie Lamport and is now maintained by a group of volunteers
-(<ulink url="http://latex-project.org">http://latex-project.org</ulink>). It is widely used, particularly for
-complex and technical documents, such as those involving mathematics.
-</para>
-<indexterm role="cp"><primary>macro package, &latex; as</primary></indexterm>
-<para>A &latex; user writes an input file containing text along with
-interspersed commands, for instance commands describing how the text
-should be formatted. It is implemented as a set of related commands
-that interface with Donald&#160;E. Knuth&#8217;s &tex; typesetting program
-(the technical term is that &latex; is a <firstterm>macro package</firstterm> for the
-&tex; engine). The user produces the output document by giving that
-input file to the &tex; engine.
+created by Leslie Lamport in 1984, but has been maintained by a group
+of volunteers for many years now (<ulink url="https://latex-project.org">https://latex-project.org</ulink>).
+It is widely used, particularly but not exclusively for mathematical
+and technical documents.
+</para>
+<indexterm role="cp"><primary>UTF-8, default &latex; input encoding</primary></indexterm>
+<para>A &latex; user writes an input file containing text to be typeset
+along with interspersed commands. The default encoding for the text is
+UTF-8 (as of 2018). The commands specify, for example, how the text
+should be formatted.
+</para>
+<para>&latex; is implemented as a set of related so-called &#8220;macros&#8221; which
+use Donald&#160;E. Knuth&#8217;s &tex; typesetting program or one of its
+derivatives, collectively known as &#8220;engines&#8221;. Thus, the user
+produces output, typically PDF, by giving the input file to a &tex;
+engine. (The following sections describe all this in more detail.)
</para>
<para>The term &latex; is also sometimes used to mean the language in which
-the document is marked up, that is, to mean the set of commands
+the input document is marked up, that is, to mean the set of commands
available to a &latex; user.
</para>
<indexterm role="cp"><primary>Lamport &tex;</primary></indexterm>
@@ -300,7 +290,7 @@ it to a PostScript <literal>.ps</literal> file with <command>dvips</command> or
Portable Document Format <literal>.pdf</literal> file with <command>dvipdfmx</command>.
The contents of the file can be dumped in human-readable form with
<command>dvitype</command>. A vast array of other DVI utility programs are
-available (<ulink url="http://mirror.ctan.org/dviware">http://mirror.ctan.org/dviware</ulink>).
+available (<ulink url="https://mirror.ctan.org/dviware">https://mirror.ctan.org/dviware</ulink>).
</para>
</listitem></varlistentry><varlistentry><term><literal>.pdf</literal>
</term><listitem><indexterm role="fn"><primary>.pdf file</primary></indexterm>
@@ -312,7 +302,7 @@ a Portable Document Format (PDF) file. Typically this is a
self-contained file, with all fonts and images included.
</para>
</listitem></varlistentry></variablelist>
-<para>&latex; also produces at least two additional files.
+<para>&latex; always produces at least two additional files.
</para>
<variablelist><varlistentry><term><literal>.log</literal>
</term><listitem><indexterm role="cp"><primary>transcript file</primary></indexterm>
@@ -361,28 +351,36 @@ open-ended.
<indexterm role="cp"><primary>engines, &tex;</primary></indexterm>
<indexterm role="cp"><primary>implementations of &tex;</primary></indexterm>
-<indexterm role="cp"><primary>UTF-8</primary></indexterm>
+<indexterm role="cp"><primary>UTF-8, engine support for</primary></indexterm>
<indexterm role="cp"><primary>Unicode input, native</primary></indexterm>
<indexterm role="cp"><primary>TrueType fonts</primary></indexterm>
<indexterm role="cp"><primary>OpenType fonts</primary></indexterm>
-<para>&latex; is defined to be a set of commands that are run by a &tex;
-implementation (see <link linkend="Overview">Overview</link>). This section gives a terse
-overview of the main programs (see also&#160;<link linkend="Command-line">Command line</link>).
-</para>
-<variablelist><varlistentry><term><literal>latex</literal>
-</term><term><literal>pdflatex</literal>
-</term><listitem><indexterm role="cp"><primary>pdf&tex; engine</primary></indexterm>
-<indexterm role="fn"><primary>etex command</primary></indexterm>
+<indexterm role="cp"><primary>&tex; format (<literal>.fmt</literal>) files</primary></indexterm>
+<indexterm role="cp"><primary>&latex; format (<literal>.fmt</literal>) files</primary></indexterm>
+<indexterm role="cp"><primary>format files, &tex;</primary></indexterm>
+<indexterm role="fn"><primary>.fmt file</primary></indexterm>
+<para>&latex; is a large set of commands that is executed by a &tex;
+program (see <link linkend="Overview">Overview</link>). Such a set of commands is called a
+<firstterm>format</firstterm>, and is embodied in a binary <literal>.fmt</literal> file, which can
+be read much more quickly than the corresponding &tex; source.
+</para>
+<para>This section gives a terse overview of the &tex; programs that are
+commonly available (see also <link linkend="Command-line-interface">Command line interface</link>).
+</para>
+<variablelist><varlistentry><term><indexterm role="fn"><primary>latex</primary></indexterm><literal>latex</literal>
+</term><term><indexterm role="fn"><primary>pdflatex</primary></indexterm><literal>pdflatex</literal>
+</term><listitem><indexterm role="fn"><primary>etex command</primary></indexterm>
+<indexterm role="cp"><primary>pdf&tex; engine</primary></indexterm>
<indexterm role="cp"><primary>e-&tex;</primary></indexterm>
-<anchor id="tex-engines-latex"/><para>In &tex; Live (<ulink url="http://tug.org/texlive">http://tug.org/texlive</ulink>), if &latex; is invoked
+<anchor id="tex-engines-latex"/><para>In &tex; Live (<ulink url="https://tug.org/texlive">https://tug.org/texlive</ulink>), if &latex; is invoked
via either the system command <command>latex</command> or <command>pdflatex</command>,
-then the pdf&tex; engine is run (<ulink url="http://ctan.org/pkg/pdftex">http://ctan.org/pkg/pdftex</ulink>).
+then the pdf&tex; engine is run (<ulink url="https://ctan.org/pkg/pdftex">https://ctan.org/pkg/pdftex</ulink>).
When invoked as <command>latex</command>, the main output is a <filename>.dvi</filename>
file; as <command>pdflatex</command>, the main output is a <filename>.pdf</filename> file.
</para>
<para>pdf&tex; incorporates the e-&tex; extensions to Knuth&#8217;s original
-program (<ulink url="http://ctan.org/pkg/etex">http://ctan.org/pkg/etex</ulink>), including additional
+program (<ulink url="https://ctan.org/pkg/etex">https://ctan.org/pkg/etex</ulink>), including additional
programming features and bi-directional typesetting, and has plenty of
extensions of its own. e-&tex; is available on its own as the system
command <command>etex</command>, but this is plain &tex; (and produces
@@ -392,25 +390,22 @@ command <command>etex</command>, but this is plain &tex; (and produces
rather than pdf&tex;. In any case, the e-&tex; extensions can be
assumed to be available in &latex;.
</para>
-</listitem></varlistentry><varlistentry><term><literal>lualatex</literal>
-</term><listitem><indexterm role="fn"><primary>lualatex command</primary></indexterm>
-<indexterm role="cp"><primary>Lua&tex;</primary></indexterm>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lualatex</primary></indexterm><literal>lualatex</literal>
+</term><listitem><indexterm role="cp"><primary>Lua&tex;</primary></indexterm>
<anchor id="tex-engines-lualatex"/><para>If &latex; is invoked via the system command <command>lualatex</command>, the
-Lua&tex; engine is run (<ulink url="http://ctan.org/pkg/luatex">http://ctan.org/pkg/luatex</ulink>). This
+Lua&tex; engine is run (<ulink url="https://ctan.org/pkg/luatex">https://ctan.org/pkg/luatex</ulink>). This
program allows code written in the scripting language Lua
(<ulink url="http://luatex.org">http://luatex.org</ulink>) to interact with &tex;&#8217;s typesetting.
Lua&tex; handles UTF-8 Unicode input natively, can handle OpenType
and TrueType fonts, and produces a <filename>.pdf</filename> file by default.
-There is also <command>dvilualatex</command> to produce a <filename>.dvi</filename> file,
-but this is rarely used.
+There is also <command>dvilualatex</command> to produce a <filename>.dvi</filename> file.
</para>
-</listitem></varlistentry><varlistentry><term><literal>xelatex</literal>
-</term><listitem><indexterm role="fn"><primary>xelatex command</primary></indexterm>
-<indexterm role="cp"><primary>Xe&tex;</primary></indexterm>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>xelatex</primary></indexterm><literal>xelatex</literal>
+</term><listitem><indexterm role="cp"><primary>Xe&tex;</primary></indexterm>
<indexterm role="fn"><primary>.xdv file</primary></indexterm>
<indexterm role="fn"><primary>xdvipdfmx</primary></indexterm>
<anchor id="tex-engines-xelatex"/><para>If &latex; is invoked with the system command <command>xelatex</command>, the
-Xe&tex; engine is run (<ulink url="http://tug.org/xetex">http://tug.org/xetex</ulink>). Like Lua&tex;,
+Xe&tex; engine is run (<ulink url="https://tug.org/xetex">https://tug.org/xetex</ulink>). Like Lua&tex;,
Xe&tex; natively supports UTF-8 Unicode and TrueType and OpenType
fonts, though the implementation is completely different, mainly using
external libraries instead of internal code. Xe&tex; produces a
@@ -421,12 +416,44 @@ and translates that to PDF using the (<literal>x</literal>)<literal>dvipdfmx</li
program, but this process is automatic. The <literal>.xdv</literal> file is only
useful for debugging.
</para>
-</listitem></varlistentry></variablelist>
-<para>Other variants of &latex; and &tex; exist, e.g., to provide
-additional support for Japanese and other languages ([u]p&tex;,
-<ulink url="http://ctan.org/pkg/ptex">http://ctan.org/pkg/ptex</ulink>, <ulink url="http://ctan.org/pkg/uptex">http://ctan.org/pkg/uptex</ulink>).
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>platex</primary></indexterm><literal>platex</literal>
+</term><term><indexterm role="fn"><primary>uplatex</primary></indexterm><literal>uplatex</literal>
+</term><listitem><para>These commands provide significant additional support for Japanese and
+other languages; the <literal>u</literal> variant supports Unicode. See
+<ulink url="https://ctan.org/pkg/ptex">https://ctan.org/pkg/ptex</ulink> and <ulink url="https://ctan.org/pkg/uptex">https://ctan.org/pkg/uptex</ulink>.
+</para></listitem></varlistentry></variablelist>
+<para>As of 2019, there is a companion <literal>-dev</literal> command and format for
+all of the above:
+</para>
+<variablelist><varlistentry><term><indexterm role="fn"><primary>dvilualatex-dev</primary></indexterm><literal>dvilualatex-dev</literal>
+</term><term><indexterm role="fn"><primary>latex-dev</primary></indexterm><literal>latex-dev</literal>
+</term><term><indexterm role="fn"><primary>lualatex-dev</primary></indexterm><literal>lualatex-dev</literal>
+</term><term><indexterm role="fn"><primary>pdflatex-dev</primary></indexterm><literal>pdflatex-dev</literal>
+</term><term><indexterm role="fn"><primary>platex-dev</primary></indexterm><literal>platex-dev</literal>
+</term><term><indexterm role="fn"><primary>uplatex-dev</primary></indexterm><literal>uplatex-dev</literal>
+</term><term><indexterm role="fn"><primary>xelatex-dev</primary></indexterm><literal>xelatex-dev</literal>
+</term><listitem><indexterm role="cp"><primary>release candidates</primary></indexterm>
+<indexterm role="cp"><primary>prerelease testing</primary></indexterm>
+<para>These are candidates for an upcoming &latex; release. The main
+purpose is to find and address compatibility problems before an
+official release.
+</para>
+<para>These <literal>-dev</literal> formats make it easy for anyone to help test
+documents and code: you can run, say, <literal>pdflatex-dev</literal> instead of
+<literal>pdflatex</literal>, without changing anything else in your environment.
+Indeed, it is easiest and most helpful to always run the <literal>-dev</literal>
+versions instead of bothering to switch back and forth. During quiet
+times after a release, the commands will be equivalent.
+</para>
+<para>These are not daily snapshots or untested development code. They
+undergo the same extensive regression testing by the &latex; team
+before being released.
+</para>
+<para>For more information, see &#8220;The &latex; release workflow and the
+&latex; <literal>dev</literal> formats&#8221; by Frank Mittelbach, <citetitle>TUGboat</citetitle> 40:2,
+<ulink url="https://tug.org/TUGboat/tb40-2/tb125mitt-dev.pdf">https://tug.org/TUGboat/tb40-2/tb125mitt-dev.pdf</ulink>.
</para>
-
+</listitem></varlistentry></variablelist>
</sect1>
<sect1 label="2.4" id="LaTeX-command-syntax">
<title>&latex; command syntax</title>
@@ -441,7 +468,7 @@ character, <literal>\</literal>. The name itself then consists of either
</para>
<para>&latex; commands names are case sensitive so that <literal>\pagebreak</literal>
differs from <literal>\Pagebreak</literal> (the latter is not a standard command).
-Most commands are lowercase, but in any event you must enter all
+Most command names are lowercase, but in any event you must enter all
commands in the same case as they are defined.
</para>
<para>A command may be followed by zero, one, or more arguments. These
@@ -458,12 +485,6 @@ argument comes last, with no required argument after it, then to make
the first character of the following text be an open square bracket,
hide it inside curly braces.
</para>
-<para>Some of &latex;&#8217;s commands are a <firstterm>declaration</firstterm>. Such a command
-changes the value the meaning of some other command or parameter. For
-instance, the <literal>\mainmatter</literal> declaration changes the typesetting of
-page numbers from roman numerals to arabic (see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp;
-\mainmatter &amp; \backmatter</link>).
-</para>
<para>&latex; has the convention that some commands have a <literal>*</literal> form that
is related to the form without a <literal>*</literal>, such as <literal>\chapter</literal> and
<literal>\chapter*</literal>. The exact difference in behavior varies from command
@@ -472,32 +493,44 @@ to command.
<para>This manual describes all accepted options and <literal>*</literal>-forms for the
commands it covers (barring unintentional omissions, a.k.a. bugs).
</para>
+<indexterm role="cp"><primary>package, <literal>expl3</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>expl3</literal> package</primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>xparse</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>xparse</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>&latex;3 syntax</primary></indexterm>
+<para>As of the 2020-10-01 release of &latex;, the <literal>expl3</literal> and
+<literal>xparse</literal> packages are part of the &latex;2e format. They
+provide a completely different underlying programming language
+syntax. We won&#8217;t try to cover them in this document; see the related
+package documentation and other &latex; manuals.
+</para>
</sect1>
<sect1 label="2.5" id="Environment">
<title>Environment</title>
<para>Synopsis:
</para>
-<screen>\begin{<replaceable>environment name</replaceable>}
+<screen>\begin{<replaceable>environment-name</replaceable>}
...
-\end{<replaceable>environment name</replaceable>}
+\end{<replaceable>environment-name</replaceable>}
</screen>
-<para>An area of &latex; source, inside of which there is a distinct
-behavior. For instance, for poetry in &latex; put the lines between
-<literal>\begin{verse}</literal> and <literal>\end{verse}</literal>.
+<para>An <firstterm>environment</firstterm> is an area of &latex; source, inside of which
+there is a distinct behavior. For instance, for poetry in &latex;
+put the lines between <literal>\begin{verse}</literal> and <literal>\end{verse}</literal>.
</para>
<screen>\begin{verse}
There once was a man from Nantucket \\
...
\end{verse}
</screen>
-<para>See <link linkend="Environments">Environments</link> for a list of environments. Particularly notable is
+<para>See <link linkend="Environments">Environments</link>, for a list of environments. Particularly notable is
that every &latex; document must have a <literal>document</literal> environment,
a <literal>\begin{document} ... \end{document}</literal> pair.
</para>
-<para>The <replaceable>environment name</replaceable> at the beginning must exactly match that at
-the end. This includes the case where <replaceable>environment name</replaceable> ends in a
+<para>The <replaceable>environment-name</replaceable> at the beginning must exactly match that at
+the end. This includes the case where <replaceable>environment-name</replaceable> ends in a
star&#160;(<literal>*</literal>); both the <literal>\begin</literal> and <literal>\end</literal> texts must
include the star.
</para>
@@ -513,7 +546,7 @@ required (it specifies the formatting of columns).
</sect1>
<sect1 label="2.6" id="CTAN">
-<title>CTAN: the Comprehensive &tex; Archive Network</title>
+<title>CTAN: The Comprehensive &tex; Archive Network</title>
<indexterm role="cp"><primary>CTAN</primary></indexterm>
@@ -528,20 +561,22 @@ person or a small number of people. For instance, many publishers have
a package that allows authors to format papers to that publisher&#8217;s
specifications.
</para>
-<para>In addition to the massive holdings, the web site offers features such
-as search by name or by functionality.
+<para>In addition to the massive holdings, the <literal>ctan.org</literal> web site
+offers features such as search by name or by functionality.
</para>
<indexterm role="cp"><primary>DANTE e.V.</primary></indexterm>
+<para>CTAN is not a single host, but instead is a set of hosts, one of which
+is the so-called &#8220;master&#8221;. The master host actively manages the
+material, for instance, by accepting uploads of new or updated
+packages. For many years, it has been hosted by the German &tex;
+group, DANTE e.V.
+</para>
<indexterm role="cp"><primary>mirrors of CTAN</primary></indexterm>
-<para>CTAN is not a single site, but instead is a set of sites. One of the
-sites is the core. This site actively manages the material, for
-instance, by accepting uploads of new or updated packages. It is
-hosted by the German &tex; group DANTE e.V. Other sites around the
-world help out by mirroring, that is, automatically syncing their
-collections with the core site and then in turn making their copies
-publicly available. This gives users close to their location better
-access and relieves the load on the core site. The list of mirrors is
-at <ulink url="https://ctan.org/mirrors">https://ctan.org/mirrors</ulink>.
+<para>Other sites around the world help out by mirroring, that is,
+automatically syncing their collections with the master site and then
+in turn making their copies publicly available. This gives users close
+to their location better access and relieves the load on the master
+site. The list of mirrors is at <ulink url="https://ctan.org/mirrors">https://ctan.org/mirrors</ulink>.
</para>
</sect1>
@@ -584,9 +619,10 @@ matter, such as a preface, and back matter, such as an appendix
such as technical reports or theses, which may contain several chapters.
</para>
</listitem></varlistentry><varlistentry><term><literal>slides</literal>
-</term><listitem><anchor id="document-classes-slides"/><para>For slide presentations&#8212;rarely used today. In its place the
-<literal>beamer</literal> package is perhaps the most prevalent (see <link linkend="beamer-template">beamer
-template</link>).
+</term><listitem><anchor id="document-classes-slides"/><para>For slide presentations&#8212;rarely used nowadays. The
+<literal>beamer</literal> package is perhaps the most prevalent
+(<ulink url="https://ctan.org/pkg/beamer">https://ctan.org/pkg/beamer</ulink>). See <link linkend="beamer-template">beamer template</link>, for a
+small template for a beamer document.
</para>
</listitem></varlistentry></variablelist>
<para>Standard <replaceable>options</replaceable> are described in the next section.
@@ -721,6 +757,7 @@ for the abstract also, if there is one. The default for the
</term><term><literal>twoside</literal>
</term><listitem><indexterm role="fn"><primary>\evensidemargin</primary></indexterm>
<indexterm role="fn"><primary>\oddsidemargin</primary></indexterm>
+<!-- xx TODO re-align on the French version which is more accurate. -->
<para>Selects one- or two-sided layout; default is <literal>oneside</literal>, except
that in the <literal>book</literal> class the default is <literal>twoside</literal>.
</para>
@@ -832,9 +869,9 @@ name</replaceable>}</literal>, to modify the behavior of the class. An example
declare <literal>\documentclass[11pt]{article}</literal> to set the default
document font size.
</para>
-</listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package usually does
-most of its work: declaring new variables, commands and fonts, and
-loading other files.
+</listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package
+usually does most of its work: declaring new variables, commands and
+fonts, and loading other files.
</para></listitem></orderedlist>
<para>Here is a starting class file, which should be saved as <filename>stub.cls</filename>
where &latex; can find it, for example in the same directory as the
@@ -853,7 +890,7 @@ passing them all to the <literal>article</literal> class, and then loads the
</para>
<para>For more, see the official guide for class and package writers, the
Class Guide, at
-<ulink url="http://www.latex-project.org/help/documentation/clsguide.pdf">http://www.latex-project.org/help/documentation/clsguide.pdf</ulink> (much
+<ulink url="https://www.latex-project.org/help/documentation/clsguide.pdf">https://www.latex-project.org/help/documentation/clsguide.pdf</ulink> (much
of the descriptions here derive from this document), or the tutorial
<ulink url="https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf">https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf</ulink>.
</para>
@@ -957,10 +994,10 @@ must contain <literal>\DeclareOption{logo}{<replaceable>code</replaceable>}</lit
<literal>\ProcessOptions</literal>).
</para>
<para>If you request an option that has not been declared, by default this
-will produce a warning like <literal>Unused global option(s): [badoption].</literal>
-Change this behaviour with the starred version
-<literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>. For example, many classes extend
-an existing class, using a declaration such as
+will produce a warning like <literal>Unused global option(s):
+[badoption].</literal> Change this behavior with the starred version
+<literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>. For example, many classes
+extend an existing class, using a command such as
<literal>\LoadClass{article}</literal>, and for passing extra options to the
underlying class use code such as this.
</para>
@@ -1015,8 +1052,8 @@ commands, so they do not just make a log message when you redefine
<literal>\renew&#8230;</literal> or <literal>\provide&#8230;</literal> or you get an error.
</para></listitem></orderedlist>
-</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
-</term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
+</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>filename</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
+</term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>filename</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\IfFileExists</primary></indexterm>
<indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm>
<para>Execute <replaceable>true code</replaceable> if &latex; finds the file <filename><replaceable>file
@@ -1223,12 +1260,12 @@ with certain features by specifying that it must be released no earlier
than the given date. (Although, in practice package users only rarely
include a date, and class users almost never do.)
</para>
-</listitem></varlistentry><varlistentry><term><literal>\ProvidesFile{<replaceable>file name</replaceable>}[<replaceable>additional information</replaceable>]</literal>
+</listitem></varlistentry><varlistentry><term><literal>\ProvidesFile{<replaceable>filename</replaceable>}[<replaceable>additional information</replaceable>]</literal>
</term><listitem><indexterm role="fn"><primary>\ProvidesFile</primary></indexterm>
<para>Declare a file other than the main class and package files, such as
configuration files or font definition files. Put this command in that
file and you get in the log a string like <literal>File: test.config
-2017/10/12 config file for test.cls</literal> for <replaceable>file name</replaceable> equal to
+2017/10/12 config file for test.cls</literal> for <replaceable>filename</replaceable> equal to
&#8216;<literal>test.config</literal>&#8217; and <replaceable>additional information</replaceable> equal to
&#8216;<literal>2017/10/12 config file for test.cls</literal>&#8217;.
</para>
@@ -1273,12 +1310,530 @@ causes &latex; to give error like <literal>\usepackage before
<indexterm role="cp"><primary>typefaces</primary></indexterm>
<indexterm role="cp"><primary>fonts</primary></indexterm>
-<para>Two important aspects of selecting a <firstterm>font</firstterm> are specifying a size
-and a style. The &latex; commands for doing this are described here.
+<para>&latex; comes with powerful font capacities. For one thing, its New
+Font Selection Scheme allows you to work easily with the font families
+in your document (for instance, see&#160;<link linkend="Font-styles">Font styles</link>). And,
+&latex; documents can use most fonts that are available today,
+including versions of Times Roman, Helvetica, Courier, etc. (Note,
+though, that many fonts do not have support for mathematics.)
+</para>
+<para>The first typeface in the &tex; world was the Computer Modern family,
+developed by Donald Knuth. It is the default for &latex; documents and
+is still the most widely used. But changing to another font often only
+involves a few commands. For instance, putting the following in your
+preamble gives you a Palatino-like font, which is handsome and more
+readable online than many other fonts, while still allowing you to
+typeset mathematics. (This example is from Michael Sharpe,
+<ulink url="https://math.ucsd.edu/~msharpe/RcntFnts.pdf">https://math.ucsd.edu/~msharpe/RcntFnts.pdf</ulink>.)
+</para>
+<screen>\usepackage[osf]{newpxtext} % osf for text, not math
+\usepackage{cabin} % sans serif
+\usepackage[varqu,varl]{inconsolata} % sans serif typewriter
+\usepackage[bigdelims,vvarbb]{newpxmath} % bb from STIX
+\usepackage[cal=boondoxo]{mathalfa} % mathcal
+</screen>
+<para>In addition, the <command>xelatex</command> or <command>lualatex</command> engines allow
+you to use any fonts on your system that are in OpenType or TrueType
+format (see <link linkend="TeX-engines">&tex; engines</link>).
+</para>
+<para>The &latex; Font Catalogue (<ulink url="https://tug.org/FontCatalogue">https://tug.org/FontCatalogue</ulink>) shows
+font sample graphics and copy-and-pasteable source to use many fonts,
+including many with support for mathematics. It aims to cover all Latin
+alphabet free fonts available for easy use with &latex;.
+</para>
+<para>More information is also available from the &tex; Users Group, at
+<ulink url="https://www.tug.org/fonts/">https://www.tug.org/fonts/</ulink>.
+</para>
+
+
+<sect1 label="4.1" id="fontenc-package">
+<title><literal>fontenc</literal> package</title>
+
+<indexterm role="cp"><primary>font encoding</primary></indexterm>
+<indexterm role="cp"><primary>UTF-8, font support for</primary></indexterm>
+<indexterm role="cp"><primary>T1</primary></indexterm>
+<indexterm role="cp"><primary>OT1</primary></indexterm>
+<indexterm role="fn"><primary>fontenc</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\usepackage[<replaceable>font_encoding</replaceable>]{fontenc}
+</screen>
+<para>or
+</para>
+<screen>\usepackage[<replaceable>font_encoding1</replaceable>, <replaceable>font_encoding2</replaceable>, ...]{fontenc}
+</screen>
+<para>Specify the font encodings. A font encoding is a mapping of the
+character codes to the font glyphs that are used to typeset your output.
+</para>
+<para>This package only applies if you use the <literal>pdflatex</literal> engine
+(see <link linkend="TeX-engines">&tex; engines</link>). If you use the <command>xelatex</command> or
+<command>lualatex</command> engine then instead use the <filename>fontspec</filename> package.
+</para>
+<para>&tex;&#8217;s original font family, Computer Modern, has a limited character
+set. For instance, to make common accented characters you must use
+<literal>\accent</literal> (see <link linkend="_005caccent">\accent</link>) but this disables hyphenation. &tex;
+users have agreed on a number of standards to access the larger sets of
+characters provided by modern fonts. If you are using
+<command>pdflatex</command> then this in the preamble
+</para>
+<screen>\usepackage[T1]{fontenc}
+</screen>
+<para>gives you support for the most widespread European languages, including
+French, German, Italian, Polish, and others. In particular, if you have
+words with accented letters then &latex; will hyphenate them and your
+output can be copied and pasted. (The optional second line allows you
+to directly enter accented characters into your source file.)
+</para>
+<indexterm role="cp"><primary>package, <literal>lmodern</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>lmodern</literal> package</primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>cm-super</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>cm-super</literal> package</primary></indexterm>
+
+<para>If you are using an encoding such as <literal>T1</literal> and the characters appear
+blurry or do not magnify well then your fonts may be bitmapped,
+sometimes called raster or Type&#160;3. You want vector fonts. Use a
+package such as <filename>lmodern</filename> or <filename>cm-super</filename> to get a font that
+extends &latex;&#8217;s default using vector fonts.
+</para>
+<para>For each <replaceable>font_encoding</replaceable> given as an option but not already
+declared, this package loads the encoding definition files, named
+<filename><replaceable>font_encoding</replaceable>enc.def</filename>. It also sets <literal>\encodingdefault</literal>
+to be the last encoding in the option list.
+</para>
+<para>These are the common values for <replaceable>font_encoding</replaceable>.
+</para>
+<variablelist><varlistentry><term><literal>OT1</literal>
+</term><listitem><para>The original encoding for &tex;. Limited to mostly English characters.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>OMS, OML</literal>
+</term><listitem><para>Math symbols and math letters encoding.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>T1</literal>
+</term><listitem><para>&tex; text extended. Sometimes called the Cork encoding for the Users
+Group meeting where it was developed. Gives access to most European
+accented characters. The most common option for this package.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>TS1</literal>
+</term><listitem><para>Text Companion encoding.
+</para></listitem></varlistentry></variablelist>
+<para>&latex;&#8217;s default is to load <literal>OML</literal>, <literal>T1</literal>, <literal>OT1</literal>, and
+then <literal>OMS</literal>, and set the default to <literal>OT1</literal>.
+</para>
+<para>Even if you do not use accented letters, you may need to specify a font
+encoding if your font requires it.
+</para>
+<para>If you use <literal>T1</literal>&#160;encoded fonts other than the default Computer
+Modern family then you may need to load the package that selects your
+fonts before loading <filename>fontenc</filename>, to prevent the system from loading
+any <literal>T1</literal>&#160;encoded fonts from the default.
+</para>
+<para>The &latex; team reserve encoding names starting with: &#8216;<literal>T</literal>&#8217; for the
+standard text encodings with 256 characters, &#8216;<literal>TS</literal>&#8217; for symbols that
+extend the corresponding T encodings, &#8216;<literal>X</literal>&#8217; for test encodings,
+&#8216;<literal>M</literal>&#8217; for standard math encodings with 256 characters, &#8216;<literal>A</literal>&#8217; for
+special applications, &#8216;<literal>OT</literal>&#8217; for standard text encodings with 128
+characters, and &#8216;<literal>OM</literal>&#8217; for standard math encodings with 128
+characters (&#8216;<literal>O</literal>&#8217; stands for &#8216;<literal>obsolete</literal>&#8217;).
+</para>
+<para>This package provides a number of commands, detailed below. Many of
+them are encoding-specific, so if you have defined a command that works
+for one encoding but the current encoding is different then the command
+is not in effect.
+</para>
+
+
+<sect2 label="4.1.1" id="_005cDeclareFontEncoding">
+<title><literal>\DeclareFontEncoding</literal></title>
+
+<indexterm role="cp"><primary>font encoding, declaring</primary></indexterm>
+<indexterm role="cp"><primary>encoding, font</primary></indexterm>
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareFontEncoding</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareFontEncoding{<replaceable>encoding</replaceable>}{<replaceable>text-settings</replaceable>}{<replaceable>math-settings</replaceable>}
+</screen>
+<para>Declare the font encoding <replaceable>encoding</replaceable>. It also saves the value of
+<replaceable>encoding</replaceable> in <literal>\LastDeclaredEncoding</literal>
+(see <link linkend="_005cLastDeclaredEncoding">\LastDeclaredEncoding</link>).
+</para>
+<para>The file <filename>t1enc.def</filename> contains this line (followed by many others).
+</para>
+<screen>\DeclareFontEncoding{T1}{}{}
+</screen>
+<para>The <replaceable>text-settings</replaceable> are the commands that &latex; will run every
+time it switches from one encoding to another with the
+<literal>\selectfont</literal> or <literal>\fontencoding</literal> command. The
+<replaceable>math-settings</replaceable> are the commands that &latex; will use whenever the
+font is accessed as a math alphabet.
+</para>
+<para>&latex; ignores any space characters inside <replaceable>text-settings</replaceable> and
+<replaceable>math-settings</replaceable>, to prevent unintended spaces in the output.
+</para>
+<para>If you invent an encoding you should pick a two or three letter name
+starting with &#8216;<literal>L</literal>&#8217; for &#8216;<literal>local</literal>&#8217;, or &#8216;<literal>E</literal>&#8217; for
+&#8216;<literal>experimental</literal>&#8217;.
+</para>
+<para>Note that output encoding files may be read several times by &latex; so
+using, e.g., <literal>\newcommand</literal> may cause an error. In addition, such
+files should contain <literal>\ProvidesFile</literal> line (see <link linkend="Class-and-package-commands">Class and package
+commands</link>).
+</para>
+<para>Note also that you should use the <literal>\...Default</literal> commands only in a
+package, not in the encoding definition files, since those files
+should only contain declarations specific to that encoding.
+</para>
+
+</sect2>
+<sect2 label="4.1.2" id="_005cDeclareTextAccent">
+<title><literal>\DeclareTextAccent</literal></title>
+
+<indexterm role="cp"><primary>font encoding</primary></indexterm>
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextAccent</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareTextAccent{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>slot</replaceable>}
+</screen>
+<para>Define an accent, to be put on top of other glyphs, in the encoding
+<replaceable>encoding</replaceable> at the location <replaceable>slot</replaceable>.
+</para>
+<para>This line from <filename>t1enc.def</filename> declares that to make a circumflex
+accent as in <literal>\^A</literal>, the system will put the accent in slot&#160;2
+over the &#8216;<literal>A</literal>&#8217; character, which is represented in ASCII as&#160;65.
+(This holds unless there is a relevant <literal>DeclareTextComposite</literal> or
+<literal>\DeclareTextCompositeCommand</literal> declaration;
+see <link linkend="_005cDeclareTextComposite">\DeclareTextComposite</link>.)
+</para>
+<screen>\DeclareTextAccent{\^}{T1}{2}
+</screen>
+<para>If <replaceable>cmd</replaceable> has already been defined then <literal>\DeclareTextAccent</literal>
+does not give an error but it does log the redefinition in the
+transcript file.
+</para>
+
+</sect2>
+<sect2 label="4.1.3" id="_005cDeclareTextAccentDefault">
+<title><literal>\DeclareTextAccentDefault</literal></title>
+
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextAccent</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextAccentDefault</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareTextAccentDefault{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}
+</screen>
+<para>If there is an encoding-specific accent command <replaceable>cmd</replaceable> but there is
+no associated <literal>\DeclareTextAccent</literal> for that encoding then this
+command will pick up the slack, by saying to use it as described for
+<replaceable>encoding</replaceable>.
+</para>
+<para>For example, to make the encoding <literal>OT1</literal> be the default encoding for
+the accent <literal>\&quot;</literal>, declare this.
+</para>
+<screen>\DeclareTextAccentDefault{\&quot;}{OT1}
+</screen>
+<para>If you issue a <literal>\&quot;</literal> when the current encoding does not have a
+definition for that accent then &latex; will use the definition from
+<literal>OT1</literal>
+</para>
+<para>That is, this command is equivalent to this call (see <link linkend="_005cUseTextSymbol-_0026-_005cUseTextAccent">\UseTextSymbol
+&amp; \UseTextAccent</link>).
+</para>
+<screen>\DeclareTextCommandDefault[1]{<replaceable>cmd</replaceable>}
+ {\UseTextAccent{<replaceable>encoding</replaceable>}{<replaceable>cmd</replaceable>}{#1}}
+</screen>
+<para>Note that <literal>\DeclareTextAccentDefault</literal> works for any one-argument
+<filename>fontenc</filename> command, not just the accent command.
+</para>
+
+</sect2>
+<sect2 label="4.1.4" id="_005cDeclareTextCommand-_0026-_005cProvideTextCommand">
+<title><literal>\DeclareTextCommand</literal> &amp; <literal>\ProvideTextCommand</literal></title>
+
+<indexterm role="fn"><primary>\DeclareTextCommand</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextCommandDefault</primary></indexterm>
+<indexterm role="fn"><primary>\ProvideTextCommand</primary></indexterm>
+
+<para>Synopsis, one of:
+</para>
+<screen>\DeclareTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>defn</replaceable>}
+\DeclareTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn}</replaceable>
+\DeclareTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>}
+</screen>
+<para>or one of:
+</para>
+<screen>\ProvideTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>defn</replaceable>}
+\ProvideTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>}
+\ProvideTextCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>}
+</screen>
+<para>Define the command <replaceable>cmd</replaceable>, which will be specific to one encoding.
+The command name <replaceable>cmd</replaceable> must begin with a backslash, \. These
+commands can only appear in the preamble. Redefining <literal>cmd</literal> does
+not cause an error. The defined command will be robust even if the code
+in <replaceable>defn</replaceable> is fragile (see <link linkend="_005cprotect">\protect</link>).
+</para>
+<para>For example, the file <filename>t1enc.def</filename> contains this line.
+</para>
+<screen>\DeclareTextCommand{\textperthousand}{T1}{\%\char 24 }
+</screen>
+<para>With that, you can express parts per thousand.
+</para>
+<screen>\usepackage[T1]{fontenc} % in preamble
+ ...
+Legal limit is \( 0.8 \)\textperthousand.
+</screen>
+<para>If you change the font encoding to <literal>OT1</literal> then you get an error like
+&#8216;<literal>LaTeX Error: Command \textperthousand unavailable in encoding
+OT1</literal>&#8217;.
+</para>
+<para>The <literal>\ProvideTextCommand</literal> variant does the same, except that it
+does nothing if <replaceable>cmd</replaceable> is already defined. The
+<literal>\DeclareTextSymbol</literal> command is faster than this one for simple
+slot-to-glyph association (see <link linkend="_005cDeclareTextSymbol">\DeclareTextSymbol</link>)
+</para>
+<para>The optional <replaceable>nargs</replaceable> and <replaceable>optargsdefault</replaceable> arguments play the
+same role here as in <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
+\renewcommand</link>). Briefly, <replaceable>nargs</replaceable> is an integer from 0 to 9
+specifying the number of arguments that the defined command <literal>cmd</literal>
+takes. This number includes any optional argument. Omitting this
+argument is the same as specifying 0, meaning that <replaceable>cmd</replaceable> will have
+no arguments. And, if <replaceable>optargsdefault</replaceable> is present then the first
+argument of <literal>\<replaceable>cmd</replaceable></literal> is optional, with default value
+<replaceable>optargdefault</replaceable> (which may be the empty string). If
+<replaceable>optargsdefault</replaceable> is not present then <literal>\<replaceable>cmd</replaceable></literal> does not take
+an optional argument.
+</para>
+
+</sect2>
+<sect2 label="4.1.5" id="_005cDeclareTextCommandDefault-_0026-_005cProvideTextCommandDefault">
+<title><literal>\DeclareTextCommandDefault</literal> &amp; <literal>\ProvideTextCommandDefault </literal></title>
+
+<indexterm role="fn"><primary>\DeclareTextCommand</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextCommandDefault</primary></indexterm>
+<indexterm role="fn"><primary>\ProvideTextCommand</primary></indexterm>
+<indexterm role="fn"><primary>\ProvideTextCommandDefault</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareTextCommandDefault{<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>}
+</screen>
+<para>or:
+</para>
+<screen>\ProvideTextCommandDefault{<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>}
+</screen>
+<para>Give a default definition for <replaceable>cmd</replaceable>, for when that command is not
+defined in the encoding currently in force. This default should only use
+encodings known to be available.
+</para>
+<para>This makes <literal>\copyright</literal> available.
+</para>
+<screen>\DeclareTextCommandDefault{\copyright}{\textcircled{c}}
+</screen>
+<para>It uses only an encoding (OMS) that is always available.
+</para>
+<para>The <literal>\DeclareTextCommandDefault</literal> should not occur in the encoding
+definition files since those files should declare only commands for use
+when you select that encoding. It should instead be in a package.
+</para>
+<para>As with the related non-default commands, the
+<literal>\ProvideTextCommandDefault</literal> has exactly the same behavior as
+<literal>\DeclareTextCommandDefault</literal> except that it does nothing if
+<replaceable>cmd</replaceable> is already defined (see <link linkend="_005cDeclareTextCommand-_0026-_005cProvideTextCommand">\DeclareTextCommand &amp;
+\ProvideTextCommand</link>). So, packages can use it to provide fallbacks
+that other packages can improve upon.
+</para>
+
+</sect2>
+<sect2 label="4.1.6" id="_005cDeclareTextComposite">
+<title><literal>\DeclareTextComposite</literal></title>
+
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextComposite</primary></indexterm>
+
+<para>Synopsis:
</para>
+<screen>\DeclareTextComposite{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>simple_object</replaceable>}{<replaceable>slot</replaceable>}
+</screen>
+<para>Access an accented glyph directly, that is, without having to put an
+accent over a separate character.
+</para>
+<para>This line from <filename>t1enc.def</filename> means that <literal>\^o</literal> will cause
+&latex; to typeset lowercase&#160;&#8216;<literal>o</literal>&#8217; by taking the character
+directly from location 224 in the font.
+</para>
+<screen>\DeclareTextComposite{\^}{T1}{o}{244}
+</screen>
+<para>See <link linkend="fontenc-package">fontenc package</link>, for a list of common encodings. The
+<replaceable>simple_object</replaceable> should be a single character or a single command.
+The <replaceable>slot</replaceable> argument is usually a positive integer represented in
+decimal (although octal or hexadecimal are possible). Normally
+<replaceable>cmd</replaceable> has already been declared for this encoding, either with
+<literal>\DeclareTextAccent</literal> or with a one-argument
+<literal>\DeclareTextCommand</literal>. In <filename>t1enc.def</filename>, the above line follows
+the <literal>\DeclareTextAccent{\^}{T1}{2}</literal> command.
+</para>
+
+</sect2>
+<sect2 label="4.1.7" id="_005cDeclareTextCompositeCommand">
+<title><literal>\DeclareTextCompositeCommand</literal></title>
+
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextCompositeCommand</primary></indexterm>
+<para>Synopsis:
+</para>
+<screen>\DeclareTextCompositeCommand{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>arg</replaceable>}{<replaceable>code</replaceable>}
+</screen>
+<para>A more general version of <literal>\DeclareTextComposite</literal> that runs
+arbitrary code with <replaceable>cmd</replaceable>.
+</para>
+<para>This allows accents on &#8216;<literal>i</literal>&#8217; to act like accents on dotless&#160;i,
+<literal>\i</literal>.
+</para>
+<screen>\DeclareTextCompositeCommand{\'}{OT1}{i}{\'\i}
+</screen>
+<para>See <link linkend="fontenc-package">fontenc package</link>, for a list of common encodings. Normally
+<replaceable>cmd</replaceable> will have already been declared with <literal>\DeclareTextAccent</literal>
+or as a one argument <literal>\DeclareTextCommand</literal>.
+</para>
+
+</sect2>
+<sect2 label="4.1.8" id="_005cDeclareTextSymbol">
+<title><literal>\DeclareTextSymbol</literal></title>
+
+<indexterm role="cp"><primary>symbol, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextSymbol</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareTextSymbol{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}{<replaceable>slot</replaceable>}
+</screen>
+<para>Define a symbol in the encoding <replaceable>encoding</replaceable> at the location
+<replaceable>slot</replaceable>. Symbols defined in this way are for use in text, not
+mathematics.
+</para>
+<para>For example, this line from <filename>t1enc.def</filename> declares the number of the
+glyph to use for &#x00AB;, the left guillemet.
+</para>
+<screen>\DeclareTextSymbol{\guillemotleft}{T1}{19}
+</screen>
+<para>The command <literal>\DeclareTextCommand{\guillemotleft}{T1}{\char
+19}</literal> has the same effect but is slower (see <link linkend="_005cDeclareTextCommand-_0026-_005cProvideTextCommand">\DeclareTextCommand &amp;
+\ProvideTextCommand</link>).
+</para>
+<para>See <link linkend="fontenc-package">fontenc package</link>, for a list of common encodings. The <replaceable>slot</replaceable>
+can be specified in decimal, or octal (as in <literal>'023</literal>), or
+hexadecimal (as in <literal>&quot;13</literal>), although decimal has the advantage that
+single quote or double quote could be redefined by another package.
+</para>
+<para>If <replaceable>cmd</replaceable> has already been defined then <literal>\DeclareTextSymbol</literal>
+does not give an error but it does log the redefinition in the
+transcript file.
+</para>
+
+</sect2>
+<sect2 label="4.1.9" id="_005cDeclareTextSymbolDefault">
+<title><literal>\DeclareTextSymbolDefault</literal></title>
+
+<indexterm role="cp"><primary>accents, defining</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextSymbol</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareTextSymbolDefault</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareTextSymbolDefault{<replaceable>cmd</replaceable>}{<replaceable>encoding</replaceable>}
+</screen>
+<para>If there is an encoding-specific symbol command <replaceable>cmd</replaceable> but there is no
+associated <literal>\DeclareTextSymbol</literal> for that encoding, then this command
+will pick up the slack, by saying to get the symbol as described for
+<replaceable>encoding</replaceable>.
+</para>
+<para>For example, to declare that if the current encoding has no meaning for
+<literal>\textdollar</literal> then use the one from <literal>OT1</literal>, declare this.
+</para>
+<screen>\DeclareTextSymbolDefault{\textdollar}{OT1}
+</screen>
+<para>That is, this command is equivalent to this call (see <link linkend="_005cUseTextSymbol-_0026-_005cUseTextAccent">\UseTextSymbol
+&amp; \UseTextAccent</link>).
+</para>
+<screen>\DeclareTextCommandDefault{<replaceable>cmd</replaceable>}
+ {\UseTextSymbol{<replaceable>encoding</replaceable>}{<replaceable>cmd</replaceable>}}
+</screen>
+<para>Note that <literal>\DeclareTextSymbolDefault</literal> can be used to define a
+default for any zero-argument <filename>fontenc</filename> command.
+</para>
+
+</sect2>
+<sect2 label="4.1.10" id="_005cLastDeclaredEncoding">
+<title><literal>\LastDeclaredEncoding</literal></title>
+
+<indexterm role="fn"><primary>\LastDeclaredEncoding</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\LastDeclaredEncoding
+</screen>
+<para>Get the name of the most recently declared encoding. The
+<literal>\DeclareFontEncoding</literal> command stores the name so that it can be
+retrieved with this command (see <link linkend="_005cDeclareFontEncoding">\DeclareFontEncoding</link>).
+</para>
+<para>This relies on <literal>\LastDeclaredEncoding</literal> rather than give the
+name of the encoding explicitly.
+</para>
+<screen>\DeclareFontEncoding{JH1}{}{}
+\DeclareTextAccent{\'}{\LastDeclaredEncoding}{0}
+</screen>
+
+</sect2>
+<sect2 label="4.1.11" id="_005cUseTextSymbol-_0026-_005cUseTextAccent">
+<title><literal>\UseTextSymbol</literal> &amp; <literal>\UseTextAccent</literal></title>
-<sect1 label="4.1" id="Font-styles">
+<indexterm role="fn"><primary>\UseTextSymbol</primary></indexterm>
+<indexterm role="fn"><primary>\UseTextAccent</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\UseTextSymbol{<replaceable>encoding</replaceable>}{<replaceable>cmd</replaceable>}
+</screen>
+<para>or:
+</para>
+<screen>\UseTextAccent{<replaceable>encoding</replaceable>}{<replaceable>cmd</replaceable>}{<replaceable>text</replaceable>}
+</screen>
+<para>Use a symbol or accent not from the current encoding.
+</para>
+<para>In general, to use a <filename>fontenc</filename> command in an encoding where it is
+not defined, and if the command has no arguments, then you can use it
+like this:
+</para>
+<screen>\UseTextSymbol{OT1}{\ss}
+</screen>
+<para>which is equivalent to this (note the outer braces form a group, so &latex;
+reverts back to the prior encoding after the <literal>\ss</literal>):
+</para>
+<screen>{\fontencoding{OT1}\selectfont\ss}
+</screen>
+<para>Similarly, to use a <filename>fontenc</filename> command in an encoding where it is
+not defined, and if the command has one argument, you can use it like this:
+</para>
+<screen>\UseTextAccent{OT1}{\'}{a}
+</screen>
+<para>which is equivalent to this (again note the outer braces forming a group):
+</para>
+<screen>{fontencoding{OT1}\selectfont\'{\fontencoding{<replaceable>enc_in_use</replaceable>}\selectfont a}}
+</screen>
+<para>Here, <replaceable>enc_in_use</replaceable> is the encoding in force before this sequence
+of commands, so that &#8216;<literal>a</literal>&#8217; is typeset using the current encoding
+and only the accent is taken from <literal>OT1</literal>.
+</para>
+
+</sect2>
+</sect1>
+<sect1 label="4.2" id="Font-styles">
<title>Font styles</title>
<indexterm role="cp"><primary>font styles</primary></indexterm>
@@ -1287,17 +1842,19 @@ and a style. The &latex; commands for doing this are described here.
<para>The following type style commands are supported by &latex;.
</para>
+<indexterm role="cp"><primary>declaration form of font style commands</primary></indexterm>
<para>In the table below the listed commands, the <literal>\text...</literal> commands,
-is used with an argument, as in <literal>\textit{<replaceable>text</replaceable>}</literal>. This is
-the preferred form. But shown after it, in parenthesis, is the
-corresponding declaration form, which is sometimes useful. This form
-takes no arguments, as in <literal>{\itshape <replaceable>text</replaceable>}</literal>. The scope of
-the declaration form lasts until the next type style command or the end
-of the current group. In addition, each has an environment form such as
-<literal>\begin{itshape}...\end{itshape}</literal>.
-</para>
-<para>These commands, in both the argument form and the declaration form, are
-cumulative; for instance you can get bold sans serif by saying either of
+are used with an argument as in <literal>\textit{<replaceable>text</replaceable>}</literal>. This is
+the preferred form. But shown after it in parenthesis is the
+corresponding <firstterm>declaration form</firstterm>, which is often useful. This
+form takes no arguments, as in <literal>{\itshape <replaceable>text</replaceable>}</literal>. The
+scope of the declaration form lasts until the next type style command
+or the end of the current group. In addition, each has an environment
+form such as <literal>\begin{itshape}...\end{itshape}</literal>, which we&#8217;ll
+describe further at the end of the section.
+</para>
+<para>These commands, in any of the three forms, are cumulative; for instance
+you can get bold sans serif by saying either of
<literal>\sffamily\bfseries</literal> or <literal>\bfseries\sffamily</literal>.
</para>
<indexterm role="fn"><primary>\nocorrlist</primary></indexterm>
@@ -1305,7 +1862,7 @@ cumulative; for instance you can get bold sans serif by saying either of
<para>One advantage of these commands is that they automatically insert italic
corrections if needed (see <link linkend="_005c_002f">\/</link>). Specifically, they insert the
italic correction unless the following character is in the list
-<literal>\nocorrlist</literal>, which by default consists of a period and a comma.
+<literal>\nocorrlist</literal>, which by default consists of period and comma.
To suppress the automatic insertion of italic correction, use
<literal>\nocorr</literal> at the start or end of the command argument, such as
<literal>\textit{\nocorr text}</literal> or <literal>\textsc{text \nocorr}</literal>.
@@ -1377,8 +1934,8 @@ used as declarations: <literal>{\<replaceable>cmd</replaceable>...}</literal> in
</para>
<para>(The unconditional commands below are an older version of font
switching. The earlier commands are an improvement in most
-circumstances. But sometimes an unconditional font switch is precisely
-what you want.)
+circumstances. But sometimes an unconditional font switch is what is
+needed.)
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\bf</primary></indexterm><literal>\bf</literal>
</term><listitem><indexterm role="cp"><primary>bold font</primary></indexterm>
@@ -1465,23 +2022,19 @@ formulas. <literal>\mathversion{normal}</literal> restores the default.
<indexterm role="cp"><primary>numerals, old-style</primary></indexterm>
<indexterm role="cp"><primary>old-style numerals</primary></indexterm>
<indexterm role="cp"><primary>lining numerals</primary></indexterm>
-<indexterm role="cp"><primary>package, <literal>textcomp</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm>
-
-<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset
-so-called &#8220;old-style&#8221; numerals, which have differing heights and
-depths (and sometimes widths) from the standard &#8220;lining&#8221; numerals,
-which all have the same height as uppercase letters. &latex;&#8217;s
-default fonts support this, and will respect <literal>\textbf</literal> (but not
-other styles; there are no italic old-style numerals in Computer
-Modern). Many other fonts have old-style numerals also; sometimes the
-<literal>textcomp</literal> package must be loaded, and sometimes package options
-are provided to make them the default. FAQ entry:
-<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf</ulink>.
+<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will
+typeset so-called &#8220;old-style&#8221; numerals, which have differing heights
+and depths (and sometimes widths) from the standard &#8220;lining&#8221;
+numerals, which all have the same height as uppercase letters.
+&latex;&#8217;s default fonts support this, and will respect <literal>\textbf</literal>
+(but not other styles; there are no italic old-style numerals in
+Computer Modern). Many other fonts have old-style numerals also;
+sometimes package options are provided to make them the default. FAQ
+entry: <ulink url="https://www.texfaq.org/FAQ-osf">https://www.texfaq.org/FAQ-osf</ulink>.
</para>
</sect1>
-<sect1 label="4.2" id="Font-sizes">
+<sect1 label="4.3" id="Font-sizes">
<title>Font sizes</title>
<indexterm role="cp"><primary>font sizes</primary></indexterm>
@@ -1527,23 +2080,36 @@ options</link>).
</para></entry></row><row><entry><para><literal>\Huge</literal>
</para></entry><entry><para>24.88 </para></entry><entry><para>24.88 </para></entry><entry><para>24.88
</para></entry></row></tbody></tgroup></informaltable>
-<para>The commands are listed here in declaration forms. You use them by
-declaring them, as with this example.
+<indexterm role="cp"><primary>declaration form of font size commands</primary></indexterm>
+<para>The commands are listed here in declaration (not environment) form,
+since that is how they are typically used. For example.
</para>
<screen>\begin{quotation} \small
The Tao that can be named is not the eternal Tao.
\end{quotation}
</screen>
-<para>The scope of the <literal>\small</literal> lasts until the end of the
-<literal>quotation</literal> environment. It would also end at the next type style
-command or the end of the current group, so you could enclose it in
-extra curly braces <literal>{\small We are here, we are here, we are
-here!}</literal>. You can instead use the environment form of these commands;
-for instance, <literal>\begin{tiny}...\end{tiny}</literal>.
+<para>Here, the scope of the <literal>\small</literal> lasts until the end of the
+<literal>quotation</literal> environment. It would also end at the next type
+style command or the end of the current group, so you could enclose it
+in curly braces <literal>{\small This text is typeset in the small font.}</literal>.
+</para>
+<indexterm role="cp"><primary>environment form of font size commands</primary></indexterm>
+<para>An <firstterm>environment form</firstterm> of each of these commands is also defined; for
+instance, <literal>\begin{tiny}...\end{tiny}</literal>. However, in practice
+this form can easily lead to unwanted spaces at the beginning and/or
+end of the environment without careful consideration, so it&#8217;s
+generally less error-prone to stick to the declaration form.
+</para>
+<para>(Aside: Technically, due to the way &latex; defines <literal>\begin</literal> and
+<literal>\end</literal>, nearly every command that does not take an argument
+technically has an environment form. But in almost all cases, it would
+only cause confusion to use it. The reason for mentioning the
+environment form of the font size declarations specifically is that
+this particular use is not rare.)
</para>
</sect1>
-<sect1 label="4.3" id="Low_002dlevel-font-commands">
+<sect1 label="4.4" id="Low_002dlevel-font-commands">
<title>Low-level font commands</title>
<indexterm role="cp"><primary>low-level font commands</primary></indexterm>
@@ -1571,7 +2137,7 @@ hyphenate words containing accented letters. For more, see
<indexterm role="cp"><primary>families, of fonts</primary></indexterm>
<indexterm role="cp"><primary>font catalogue</primary></indexterm>
<para>Select the font family. The web page
-<ulink url="http://www.tug.dk/FontCatalogue/">http://www.tug.dk/FontCatalogue/</ulink> provides one way to browse
+<ulink url="https://tug.org/FontCatalogue/">https://tug.org/FontCatalogue/</ulink> provides one way to browse
through many of the fonts easily used with &latex;. Here are
examples of some common families.
</para>
@@ -1716,26 +2282,8 @@ vertical space between lines, baseline to baseline. It is stored in the
parameter <literal>\baselineskip</literal>. The default <literal>\baselineskip</literal> for
the Computer Modern typeface is 1.2 times the <literal>\fontsize</literal>.
Changing <literal>\baselineskip</literal> directly is inadvisable since its value is
-reset every time a size change happens; see <literal>\baselinestretch</literal>, next.
-</para>
-<anchor id="low-level-font-commands-baselinestretch"/></listitem></varlistentry><varlistentry><term><literal>\baselinestretch</literal>
-</term><listitem><indexterm role="fn"><primary>\baselinestretch</primary></indexterm>
-<para>&latex; multiplies the line spacing by the value of the
-<literal>\baselinestretch</literal> parameter; the default factor is 1. A change
-takes effect when <literal>\selectfont</literal> (see below) is called. You can
-make a line skip change happen for the entire document, for instance
-doubling it, by doing <literal>\renewcommand{\baselinestretch}{2.0}</literal> in
-the preamble.
-</para>
-<indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm>
-
-<indexterm role="cp"><primary>double spacing</primary></indexterm>
-<para>However, the best way to double-space a document is to use the
-<filename>setspace</filename> package. In addition to offering a number of spacing
-options, this package keeps the line spacing single-spaced in places
-where that is typically desirable, such as footnotes and figure
-captions. See the package documentation.
+reset every time a size change happens; instead use
+<literal>\baselinestretch</literal>. (see <link linkend="_005cbaselineskip-_0026-_005cbaselinestretch">\baselineskip &amp; \baselinestretch</link>).
</para>
<anchor id="low-level-font-commands-linespread"/></listitem></varlistentry><varlistentry><term><literal>\linespread{<replaceable>factor</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\linespread</primary></indexterm>
@@ -1819,22 +2367,22 @@ typesetting starts.
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\columnsep</primary></indexterm><literal>\columnsep</literal>
</term><listitem><anchor id="twocolumn-columnsep"/><para>The distance between columns. The default is 35pt. Change it with a
-command such as <literal>\setlength{\columnsep}{40pt}</literal> You must change
-it before the two column environment starts; in the preamble is a good
+command such as <literal>\setlength{\columnsep}{40pt}</literal>. You must change
+it before the two column mode starts; in the preamble is a good
place.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\columnseprule</primary></indexterm><literal>\columnseprule</literal>
-</term><listitem><anchor id="twocolumn-columnseprule"/><para>The width of the rule between columns. The rule appears halfway between
-the two columns. The default is 0pt, meaning that there is no rule.
-Change it with a command such as
+</term><listitem><anchor id="twocolumn-columnseprule"/><para>The width of the rule between columns. The default is 0pt, meaning that
+there is no rule. Otherwise, the rule appears halfway between the two
+columns. Change it with a command such as
<literal>\setlength{\columnseprule}{0.4pt}</literal>, before the two-column
-environment starts.
+mode starts.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\columnwidth</primary></indexterm><literal>\columnwidth</literal>
</term><listitem><anchor id="twocolumn-columnwidth"/><para>The width of a single column. In one-column mode this is equal to
<literal>\textwidth</literal>. In two-column mode by default &latex; sets the
-width of each of the two columns to be half of <literal>\textwidth</literal> minus
-<literal>\columnsep</literal>.
+width of each of the two columns, <literal>\columnwidth</literal>, to be half of
+<literal>\textwidth</literal> minus <literal>\columnsep</literal>.
</para>
</listitem></varlistentry></variablelist>
<para>In a two-column document, the starred environments <literal>table*</literal> and
@@ -1847,11 +2395,11 @@ The following parameters control float behavior of two-column output.
</term><listitem><para>The maximum fraction at the top of a two-column page that may be
occupied by two-column wide floats. The default is 0.7, meaning that
the height of a <literal>table*</literal> or <literal>figure*</literal> environment must not
-exceed <literal>0.7\textheight</literal> . If the height of your starred float
+exceed <literal>0.7\textheight</literal>. If the height of your starred float
environment exceeds this then you can take one of the following actions
to prevent it from floating all the way to the back of the document:
</para>
-<itemizedlist><listitem><para>Use the <literal>[tp]</literal> location specifier to tell LaTeX to try to put
+<itemizedlist><listitem><para>Use the <literal>[tp]</literal> location specifier to tell &latex; to try to put
the bulky float on a page by itself, as well as at the top of a page.
</para>
</listitem><listitem><para>Use the <literal>[t!]</literal> location specifier to override the effect of
@@ -1863,25 +2411,25 @@ to avoid going to float pages so soon.
<para>You can redefine it, as with
<literal>\renewcommand{\dbltopfraction}{0.9}</literal>.
</para>
-<anchor id="twocolumn-dblfloatpagefraction"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatpagefraction</primary></indexterm><literal>\dblfloatpagefraction</literal>
-</term><listitem><para>For a float page of two-column wide floats, this is the minimum fraction
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatpagefraction</primary></indexterm><literal>\dblfloatpagefraction</literal>
+</term><listitem><anchor id="twocolumn-dblfloatpagefraction"/><para>For a float page of two-column wide floats, this is the minimum fraction
that must be occupied by floats, limiting the amount of blank space.
&latex;&#8217;s default is <literal>0.5</literal>. Change it with <literal>\renewcommand</literal>.
</para>
-<anchor id="twocolumn-dblfloatsep"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatsep</primary></indexterm><literal>\dblfloatsep</literal>
-</term><listitem><para>On a float page of two-column wide floats, this length is the distance
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatsep</primary></indexterm><literal>\dblfloatsep</literal>
+</term><listitem><anchor id="twocolumn-dblfloatsep"/><para>On a float page of two-column wide floats, this length is the distance
between floats, at both the top and bottom of the page. The default is
<literal>12pt plus2pt minus2pt</literal> for a document set at <literal>10pt</literal> or
<literal>11pt</literal>, and <literal>14pt plus2pt minus4pt</literal> for a document set at
<literal>12pt</literal>.
</para>
-<anchor id="twocolumn-dbltextfloatsep"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltextfloatsep</primary></indexterm><literal>\dbltextfloatsep</literal>
-</term><listitem><para>This length is the distance between a multi-column float at the top or
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltextfloatsep</primary></indexterm><literal>\dbltextfloatsep</literal>
+</term><listitem><anchor id="twocolumn-dbltextfloatsep"/><para>This length is the distance between a multi-column float at the top or
bottom of a page and the main text. The default is <literal>20pt plus2pt
minus4pt</literal>.
</para>
-<anchor id="twocolumn-dbltopnumber"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltopnumber</primary></indexterm><literal>\dbltopnumber</literal>
-</term><listitem><para>On a float page of two-column wide floats, this counter gives the
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltopnumber</primary></indexterm><literal>\dbltopnumber</literal>
+</term><listitem><anchor id="twocolumn-dbltopnumber"/><para>On a float page of two-column wide floats, this counter gives the
maximum number of floats allowed at the top of the page. The &latex;
default is <literal>2</literal>.
</para>
@@ -1983,7 +2531,7 @@ at all type sizes.
<anchor id="page-layout-parameters-headsep"/><para>Vertical distance between the bottom of the header line and the top of
the main text. The default in the <literal>article</literal> and <literal>report</literal>
classes is &#8216;<literal>25pt</literal>&#8217;. In the <literal>book</literal> class the default is: if the
-document is set at 10pt then it is &#8216;<literal>0.25in</literal>&#8217;, and at 11pt and 12pt
+document is set at 10pt then it is &#8216;<literal>0.25in</literal>&#8217;, and at 11pt or 12pt
it is &#8216;<literal>0.275in</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\footskip</primary></indexterm><literal>\footskip</literal>
@@ -2039,12 +2587,13 @@ distance.
</term><term><indexterm role="fn"><primary>\evensidemargin</primary></indexterm><literal>\evensidemargin</literal>
</term><listitem><indexterm role="fn"><primary>\oddsidemargin</primary></indexterm>
<indexterm role="fn"><primary>\evensidemargin</primary></indexterm>
-<anchor id="page-layout-parameters-oddsidemargin"/><anchor id="page-layout-parameters-evensidemargin"/><para>The <literal>\oddsidemargin</literal> is the extra distance between the left side of
+<anchor id="page-layout-parameters-oddsidemargin"/><anchor id="page-layout-parameters-evensidemargin"/><!-- xx TODO re-align on French version that is more complete/accurate. -->
+<para>The <literal>\oddsidemargin</literal> length is the extra distance between the left side of
the page and the text&#8217;s left margin, on odd-numbered pages when the
document class option <literal>twoside</literal> is chosen and on all pages when
<literal>oneside</literal> is in effect. When <literal>twoside</literal> is in effect, on
even-numbered pages the extra distance on the left is
-<literal>evensidemargin</literal>.
+<literal>\evensidemargin</literal>.
</para>
<para>&latex;&#8217;s default is that <literal>\oddsidemargin</literal> is 40% of the
difference between <literal>\paperwidth</literal> and <literal>\textwidth</literal>, and
@@ -2094,15 +2643,16 @@ column), while <literal>\linewidth</literal> may decrease for nested lists.
specified width, and revert to their normal values at the end of the
<literal>minipage</literal> or <literal>\parbox</literal>.
</para>
-<indexterm role="fn"><primary>\hsize</primary></indexterm>
-<anchor id="page-layout-parameters-hsize"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hsize</primary></indexterm><literal>\hsize</literal>
-</term><listitem><para>This entry is included for completeness: <literal>\hsize</literal> is the &tex;
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hsize</primary></indexterm><literal>\hsize</literal>
+</term><listitem><indexterm role="fn"><primary>\hsize</primary></indexterm>
+<anchor id="page-layout-parameters-hsize"/><para>This entry is included for completeness: <literal>\hsize</literal> is the &tex;
primitive parameter used when text is broken into lines. It should not
be used in normal &latex; documents.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topmargin</primary></indexterm><literal>\topmargin</literal>
</term><listitem><indexterm role="fn"><primary>topmargin</primary></indexterm>
-<anchor id="page-layout-parameters-topmargin"/><para>Space between the top of the &tex; page (one inch from the top of the
+<anchor id="page-layout-parameters-topmargin"/><!-- xxx TODO re-align on French version that is more accurate. -->
+<para>Space between the top of the &tex; page (one inch from the top of the
paper, by default) and the top of the header. The value is computed
based on many other parameters: <literal>\paperheight &#8722; 2in &#8722;
\headheight &#8722; \headsep &#8722; \textheight &#8722; \footskip</literal>,
@@ -2117,7 +2667,119 @@ same as the font size, e.g., &#8216;<literal>10pt</literal>&#8217; at a type siz
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="5.6" id="Floats">
+<sect1 label="5.6" id="_005cbaselineskip-_0026-_005cbaselinestretch">
+<title><literal>\baselineskip</literal> &amp; <literal>\baselinestretch</literal></title>
+
+<indexterm role="fn"><primary>\baselineskip</primary></indexterm>
+<indexterm role="fn"><primary>\baselinestretch</primary></indexterm>
+<indexterm role="fn"><primary>\linespread</primary></indexterm>
+<indexterm role="cp"><primary>space between lines</primary></indexterm>
+<indexterm role="cp"><primary>interline space</primary></indexterm>
+<indexterm role="cp"><primary>leading</primary></indexterm>
+<indexterm role="cp"><primary>double spacing</primary></indexterm>
+
+<para>The <literal>\baselineskip</literal> is a rubber length (see <link linkend="Lengths">Lengths</link>). It gives
+the leading, the normal distance between lines in a paragraph, from
+baseline to baseline.
+</para>
+<para>Ordinarily document authors do not directly change <literal>\baselineskip</literal>
+while writing. Instead, it is set by the low level font selection
+command <literal>\fontsize</literal> (see <link linkend="low-level-font-commands-fontsize">low level font commands fontsize</link>).
+The <literal>\baselineskip</literal>&#8217;s value is reset every time a font change
+happens and so any direct change to <literal>\baselineskip</literal> would vanish
+the next time there was a font switch. For how to influence line
+spacing, see the discussion of <literal>\baselinestretch</literal> below.
+</para>
+<para>Usually, a font&#8217;s size and baseline skip is assigned by the font
+designer. These numbers are nominal in the sense that if, for instance,
+a font&#8217;s style file has the command <literal>\fontsize{10pt}{12pt}</literal>
+then that does not mean that the characters in the font are 10pt tall;
+for instance, parentheses and accented capitals may be taller. Nor does
+it mean that if the lines are spaced less than 12pt apart then they risk
+touching. Rather these numbers are typographic judgements. (Often, the
+<literal>\baselineskip</literal> is about twenty percent larger than the font size.)
+</para>
+<!-- adapted from FAQ -->
+<para>The <literal>\baselineskip</literal> is not a property of each line but of the
+entire paragraph. As a result, large text in the middle of a paragraph,
+such as a single <literal>{\Huge Q}</literal>, will be squashed into its line.
+&tex; will make sure it doesn&#8217;t scrape up against the line above but
+won&#8217;t change the <literal>\baselineskip</literal> for that one line to make extra
+room above. For the fix, use a <literal>\strut</literal> (see <link linkend="_005cstrut">\strut</link>).
+</para>
+<para>The value of <literal>\baselineskip</literal> that &tex; uses for the paragraph is
+the value in effect at the blank line or command that ends the paragraph
+unit. So if a document contains this paragraph then its lines will be
+scrunched together, compared to lines in surrounding paragraphs.
+</para>
+<!-- Adapted from B Beeton's "Lapses in TeX" TB 42:1 p 13. -->
+<screen>Many people see a page break between text and a displayed equation as
+bad style, so in effect the display is part of the paragraph.
+Because this display is in footnotesize, the entire paragraph has the
+baseline spacing matching that size.
+{\footnotesize $$a+b = c$$}
+</screen>
+<indexterm role="fn"><primary>\lineskip</primary></indexterm>
+<indexterm role="fn"><primary>\lineskiplimit</primary></indexterm>
+<indexterm role="fn"><primary>\prevdepth</primary></indexterm>
+<para>The process for making paragraphs is that when a new line is added, if
+the depth of the previous line plus the height of the new line is less
+than <literal>\baselineskip</literal> then &tex; inserts vertical glue to make up
+the difference. There are two fine points. The first is that if the
+lines would be too close together, closer than <literal>\lineskiplimit</literal>,
+then &tex; instead uses <literal>\lineskip</literal> as the interline glue. The
+second is that &tex; doesn&#8217;t actually use the depth of the previous
+line. Instead it uses <literal>\prevdepth</literal>, which usually contains that
+depth. But at the beginning of the paragraph (or any vertical list)
+or just after a rule, <literal>\prevdepth</literal> has the value -1000pt and this
+special value tells &tex; not to insert any interline glue at the
+paragraph start.
+</para>
+<para>In the standard classes <literal>\lineskiplimit</literal> is 0pt and
+<literal>\lineskip</literal> is 1pt. By the prior paragraph then, the distance
+between lines can approach zero but if it becomes zero (or less than
+zero) then the lines jump to 1pt apart.
+</para>
+<para>Sometimes authors must, for editing purposes, put the document in double
+space or one-and-a-half space. The right way to influence the interline
+distance is via <literal>\baselinestretch</literal>. It scales
+<literal>\baselineskip</literal>, and has a default value of 1.0. It is a command,
+not a length, so change the scale factor as in
+<literal>\renewcommand{\baselinestretch}{1.5}\selectfont</literal>.
+</para>
+<para>The most straightforward way to change the line spacing for an entire
+document is to put <literal>\linespread{<replaceable>factor</replaceable>}</literal> in the preamble.
+For double spacing, take <replaceable>factor</replaceable> to be 1.6 and for one-and-a-half
+spacing use 1.3. These number are rough: for instance, since the
+<literal>\baselineskip</literal> is about 1.2 times the font size, multiplying by
+1.6 gives a font size to baseline ratio of about 2. (The
+<literal>\linespread</literal> command is defined as
+<literal>\renewcommand{\baselinestretch}{<replaceable>factor</replaceable>}</literal> so it won&#8217;t
+take effect until a font setting happens. But that always takes place at
+the start of a document, so there you don&#8217;t need to follow it with
+<literal>\selectfont</literal>.)
+</para>
+<indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm>
+
+<para>A simpler approach is the <filename>setspace</filename> package. The basic example:
+</para>
+<screen>\usepackage{setspace}
+\doublespacing % or \onehalfspacing for 1.5
+</screen>
+<para>In the preamble these will start the document off with that sizing.
+But you can also use these declarations in the document body to change
+the spacing from that point forward, and consequently there is
+<literal>\singlespacing</literal> to return the spacing to normal. In the
+document body, a better practice than using the declarations is to use
+environments, such as <literal>\begin{doublespace}
+... \end{doublespace}</literal>. The package also has commands to do
+arbitrary spacing: <literal>\setstretch{<replaceable>factor</replaceable>}</literal> and
+<literal>\begin{spacing}{<replaceable>factor</replaceable>} ... \end{spacing}</literal>.
+</para>
+
+</sect1>
+<sect1 label="5.7" id="Floats">
<title>Floats</title>
<para>Some typographic elements, such as figures and tables, cannot be broken
@@ -2161,7 +2823,7 @@ both <literal>article</literal> and <literal>book</literal> classes, is <literal
allowed for full-width floats (<literal>figure*</literal>) with double-column
output. To ameliorate this, use the <filename>stfloats</filename> or
<filename>dblfloatfix</filename> package, but see the discussion at caveats in the
-FAQ: <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat</ulink>.
+FAQ: <ulink url="https://www.texfaq.org/FAQ-2colfloat">https://www.texfaq.org/FAQ-2colfloat</ulink>.
</para>
</listitem></varlistentry><varlistentry><term><literal>h</literal>
</term><listitem><para>(Here)&#8212;at the position in the text where the <literal>figure</literal> environment
@@ -2175,7 +2837,7 @@ automatically added.
<para>To absolutely force a float to appear &#8220;here&#8221;, you can
<literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it
defines. For further discussion, see the FAQ entry at
-<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere</ulink>.
+<ulink url="https://www.texfaq.org/FAQ-figurehere">https://www.texfaq.org/FAQ-figurehere</ulink>.
</para>
</listitem></varlistentry><varlistentry><term><literal>p</literal>
</term><listitem><indexterm role="cp"><primary>float page</primary></indexterm>
@@ -2287,13 +2949,13 @@ default 2.
<anchor id="floats-totalnumber"/><para>Maximum number of floats that can appear on a text page; default 3.
</para></listitem></varlistentry></variablelist>
<para>The principal &tex;&#160;FAQ entry relating to floats
-<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats</ulink> contains
+<ulink url="https://www.texfaq.org/FAQ-floats">https://www.texfaq.org/FAQ-floats</ulink> contains
suggestions for relaxing &latex;&#8217;s default parameters to reduce the
problem of floats being pushed to the end. A full explanation of the
float placement algorithm is in Frank Mittelbach&#8217;s article &#8220;How to
influence the position of float environments like figure and table in
&latex;?&#8221;
-(<ulink url="http://latex-project.org/papers/tb111mitt-float.pdf">http://latex-project.org/papers/tb111mitt-float.pdf</ulink>).
+(<ulink url="https://www.latex-project.org/publications/2014-FMi-TUB-tb111mitt-float-placement.pdf">https://www.latex-project.org/publications/2014-FMi-TUB-tb111mitt-float-placement.pdf</ulink>).
</para>
</sect1>
@@ -2306,12 +2968,14 @@ influence the position of float environments like figure and table in
<indexterm role="cp"><primary>chapter</primary></indexterm>
<indexterm role="cp"><primary>section</primary></indexterm>
<indexterm role="cp"><primary>subsection</primary></indexterm>
+<indexterm role="cp"><primary>subsubsection</primary></indexterm>
<indexterm role="cp"><primary>paragraph</primary></indexterm>
<indexterm role="cp"><primary>subparagraph</primary></indexterm>
<indexterm role="fn"><primary>\part</primary></indexterm>
<indexterm role="fn"><primary>\chapter</primary></indexterm>
<indexterm role="fn"><primary>\section</primary></indexterm>
<indexterm role="fn"><primary>\subsection</primary></indexterm>
+<indexterm role="fn"><primary>\subsubsection</primary></indexterm>
<indexterm role="fn"><primary>\paragraph</primary></indexterm>
<indexterm role="fn"><primary>\subparagraph</primary></indexterm>
@@ -2348,8 +3012,8 @@ not available in <literal>article</literal>.
</para></entry></row></tbody></tgroup></informaltable>
<indexterm role="cp"><primary><literal>*</literal>-form of sectioning commands</primary></indexterm>
<para>All these commands have a <literal>*</literal>-form that prints <replaceable>title</replaceable> as usual
-but is not numbered and does not make an entry in the table of contents.
-An example of using this is for an appendix in an <literal>article</literal> . The
+but does not number it and does not make an entry in the table of contents.
+An example of using this is for an appendix in an <literal>article</literal>. The
input <literal>\appendix\section{Appendix}</literal> gives the output &#8216;<literal>A
Appendix</literal>&#8217; (see <link linkend="_005cappendix">\appendix</link>). You can lose the numbering&#160;&#8216;<literal>A</literal>&#8217;
by instead entering <literal>\section*{Appendix}</literal> (articles often omit a
@@ -2372,25 +3036,35 @@ of contents will have an entry for this sectioning unit
(see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>).
</para>
<para>&latex; expects that before you have a <literal>\subsection</literal> you will have
-a <literal>\section</literal> and, in a book, that before a <literal>\section</literal> you will
-have a <literal>\chapter</literal>. Otherwise you can get a something like a
-subsection numbered &#8216;<literal>3.0.1</literal>&#8217;.
+a <literal>\section</literal> and, in a <literal>book</literal> class document, that before a
+<literal>\section</literal> you will have a <literal>\chapter</literal>. Otherwise you can get
+something like a subsection numbered &#8216;<literal>3.0.1</literal>&#8217;.
</para>
-<para>Two counters relate to the appearance of sectioning commands.
+<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm>
+
+<para>&latex; lets you change the appearance of the sectional units. As a
+simple example, you can change the section numbering to upper-case
+letters with <literal>\renewcommand\thesection{\Alph{section}}</literal> in the
+preamble (see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>). CTAN
+has many packages that make this adjustment easier, notably
+<filename>titlesec</filename>.
+</para>
+<para>Two counters relate to the appearance of headings made by sectioning commands.
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>secnumdepth</primary></indexterm><literal>secnumdepth</literal>
</term><listitem><indexterm role="fn"><primary>secnumdepth counter</primary></indexterm>
<indexterm role="cp"><primary>section numbers, printing</primary></indexterm>
-<anchor id="sectioning-secnumdepth"/><anchor id="Sectioning_002fsecnumdepth"/><para>Controls which sectioning commands are
-numbered. Suppress numbering of sectioning at any depth greater than
-<replaceable>level</replaceable> <literal>\setcounter{secnumdepth}{<replaceable>level</replaceable>}</literal>
-(see <link linkend="_005csetcounter">\setcounter</link>). See the above table for the level numbers. For
-instance, if the <literal>secnumdepth</literal> is 1 in an <literal>article</literal> then a
-<literal>\section{Introduction}</literal> command will produce output like &#8216;<literal>1
-Introduction</literal>&#8217; while <literal>\subsection{Discussion}</literal> will produce output
-like &#8216;<literal>Discussion</literal>&#8217;, without the number. &latex;&#8217;s default
-<literal>secnumdepth</literal> is&#160;3 in <filename>article</filename> class and &#160;2 in the
-<filename>book</filename> and <filename>report</filename> classes.
+<anchor id="sectioning-secnumdepth"/><anchor id="Sectioning_002fsecnumdepth"/><para>Controls which sectioning unit are numbered. Setting the counter with
+<literal>\setcounter{secnumdepth}{<replaceable>level</replaceable>}</literal> will suppress
+numbering of sectioning at any depth greater than <replaceable>level</replaceable>
+(see <link linkend="_005csetcounter">\setcounter</link>). See the above table for the level numbers.
+For instance, if the <literal>secnumdepth</literal> is 1 in an <literal>article</literal> then
+a <literal>\section{Introduction}</literal> command will produce output like
+&#8216;<literal>1 Introduction</literal>&#8217; while <literal>\subsection{Discussion}</literal> will
+produce output like &#8216;<literal>Discussion</literal>&#8217;, without the number. &latex;&#8217;s
+default <literal>secnumdepth</literal> is&#160;3 in <filename>article</filename> class and
+&#160;2 in the <filename>book</filename> and <filename>report</filename> classes.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>tocdepth</primary></indexterm><literal>tocdepth</literal>
</term><listitem><indexterm role="fn"><primary>tocdepth counter</primary></indexterm>
@@ -2401,7 +3075,7 @@ sectioning units at <replaceable>level</replaceable> be the smallest ones listed
(see <link linkend="_005csetcounter">\setcounter</link>). See the above table for the level numbers. For
instance, if <literal>tocdepth</literal> is&#160;1 then the table of contents will
list sections but not subsections. &latex;&#8217;s default
-<literal>secnumdepth</literal> is&#160;3 in <filename>article</filename> class and &#160;2 in the
+<literal>tocdepth</literal> is&#160;3 in <filename>article</filename> class and &#160;2 in the
<filename>book</filename> and <filename>report</filename> classes.
</para>
</listitem></varlistentry></variablelist>
@@ -2456,7 +3130,7 @@ out the break in the table of contents.
</screen>
<para>For determining which sectional units are numbered and which appear in
the table of contents, the level number of a part is&#160;-1
-(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>).
+(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link>, and <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>).
</para>
<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm>
@@ -2527,7 +3201,7 @@ title,
the title but that doesn&#8217;t work well with running headers so it omits
the break in the contents
</para>
-<screen>\chapter[Given it all\\ my story]{Given it all\\ my story}
+<screen>\chapter[Given it all; my story]{Given it all\\ my story}
</screen>
<para>For determining which sectional units are numbered and which appear in
the table of contents, the level number of a chapter is&#160;0
@@ -2707,13 +3381,13 @@ holds in <literal>article</literal> except that there are no chapters in that cl
so it looks like &#8216;<literal>2.3 <replaceable>title</replaceable></literal>&#8217;.
</para>
<para>The <literal>*</literal>&#160;form shows <replaceable>title</replaceable>.
-But it does not show the section number, does not increment the
-<literal>section</literal> counter, and produces no table of contents entry.
+But it does not show the subsection number, does not increment the
+<literal>subsection</literal> counter, and produces no table of contents entry.
</para>
-<para>The optional argument <replaceable>toc-title</replaceable> will appear as the section title
+<para>The optional argument <replaceable>toc-title</replaceable> will appear as the subsection title
in the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>). If it is
-not present then <replaceable>title</replaceable> will be there. This shows the full name in
-the title of the section,
+not present then <replaceable>title</replaceable> will be there. This shows the full text in
+the title of the subsection,
</para>
<screen>\subsection[$\alpha,\beta,\gamma$ paper]{\textit{The Origin of
Chemical Elements} by R.A.~Alpher, H.~Bethe, and G.~Gamow}
@@ -2865,38 +3539,45 @@ book or report, and in an article resets the <literal>section</literal> and
</screen>
<para>the first two will generate output numbered &#8216;<literal>Chapter 1</literal>&#8217; and
&#8216;<literal>Chapter 2</literal>&#8217;. After the <literal>\appendix</literal> the numbering will be
-&#8216;<literal>Appendix A</literal>&#8217; and &#8216;<literal>Appendix B</literal>&#8217;. See <link linkend="Larger-book-template">Larger book template</link>
+&#8216;<literal>Appendix A</literal>&#8217; and &#8216;<literal>Appendix B</literal>&#8217;. See <link linkend="Larger-book-template">Larger book template</link>,
for another example.
</para>
<indexterm role="cp"><primary>package, <literal>appendix</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>appendix</literal> package</primary></indexterm>
+
<para>The <filename>appendix</filename> package adds the command
<literal>\appendixpage</literal> to put a separate &#8216;<literal>Appendices</literal>&#8217; in the document
body before the first appendix, and the command <literal>\addappheadtotoc</literal>
to do the same in the table of contents. You can reset the name
-&#8216;<literal>Appendix</literal>&#8217; with a command like
+&#8216;<literal>Appendices</literal>&#8217; with a command like
<literal>\renewcommand{\appendixname}{Specification}</literal>, as well as a
number of other features. See the documentation on CTAN.
</para>
</sect1>
-
<sect1 label="6.7" id="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">
<title><literal>\frontmatter</literal>, <literal>\mainmatter</literal>, <literal>\backmatter</literal></title>
<indexterm role="fn"><primary>\frontmatter</primary></indexterm>
<indexterm role="cp"><primary>book, front matter</primary></indexterm>
+<indexterm role="cp"><primary>front matter of a book</primary></indexterm>
<indexterm role="fn"><primary>\mainmatter</primary></indexterm>
<indexterm role="cp"><primary>book, main matter</primary></indexterm>
+<indexterm role="cp"><primary>main matter of a book</primary></indexterm>
<indexterm role="fn"><primary>\backmatter</primary></indexterm>
<indexterm role="cp"><primary>book, back matter</primary></indexterm>
<indexterm role="cp"><primary>book, end matter</primary></indexterm>
+<indexterm role="cp"><primary>back matter of a book</primary></indexterm>
+<indexterm role="cp"><primary>end matter of a book</primary></indexterm>
-<para>Synopsis, one of:
+<para>Synopsis, one or more of:
</para>
<screen>\frontmatter
+...
\mainmatter
+...
\backmatter
+...
</screen>
<para>Format a <literal>book</literal> class document differently according to which part
of the document is being produced. All three commands are optional.
@@ -2908,19 +3589,23 @@ pages, such as the title page, are traditionally not numbered.) The
back matter may contain such things as a glossary, notes, a
bibliography, and an index.
</para>
-<para>The <literal>\frontmatter</literal> declaration makes the pages numbered in
-lowercase roman, and makes chapters not numbered, although each
-chapter&#8217;s title appears in the table of contents; if you use other
-sectioning commands here, use the <literal>*</literal>-version (see <link linkend="Sectioning">Sectioning</link>).
-The <literal>\mainmatter</literal> changes the behavior back to the expected
-version, and resets the page number. The <literal>\backmatter</literal> leaves the
-page numbering alone but switches the chapters back to being not
-numbered. See <link linkend="Larger-book-template">Larger book template</link> for an example using the three.
+<para>The <literal>\frontmatter</literal> command makes the pages numbered in lowercase
+roman, and makes chapters not numbered, although each chapter&#8217;s title
+appears in the table of contents; if you use other sectioning commands
+here, use the <literal>*</literal>-version (see <link linkend="Sectioning">Sectioning</link>).
+</para>
+<para>The <literal>\mainmatter</literal> command changes the behavior back to the expected
+version, and resets the page number.
+</para>
+<para>The <literal>\backmatter</literal> command leaves the page numbering alone but
+switches the chapters back to being not numbered.
+</para>
+<para>See <link linkend="Larger-book-template">Larger book template</link>, for an example using these three commands.
</para>
</sect1>
<sect1 label="6.8" id="_005c_0040startsection">
-<title><literal>\@startsection</literal></title>
+<title><literal>\@startsection</literal>, typesetting sectional unit headings</title>
<indexterm role="fn"><primary>\@startsection</primary></indexterm>
<indexterm role="cp"><primary>section, redefining</primary></indexterm>
@@ -2958,12 +3643,13 @@ make such a command you may want to use the <literal>\secdef</literal> command.
{<replaceable>afterskip</replaceable>}
{<replaceable>style</replaceable>}}
</screen>
-<para>redefines <literal>\section</literal> to have the form
-<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (here too, the
-star&#160;<literal>*</literal> is optional). See <link linkend="Sectioning">Sectioning</link>. This implies that
-when you write a command like <literal>\renewcommand{section}{...}</literal>,
-the <literal>\@startsection{...}</literal> must come last in the definition. See
-the examples below.
+<para>redefines <literal>\section</literal> while keeping its standard calling form
+<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (in which, for reminder,
+the star&#160;<literal>*</literal> is optional). See <link linkend="Sectioning">Sectioning</link>. This implies
+that when you write a command like
+<literal>\renewcommand{\section}{...}</literal>, the
+<literal>\@startsection{...}</literal> must come last in the definition. See the
+examples below.
</para>
<variablelist>
<varlistentry><term><replaceable>name</replaceable>
@@ -2979,7 +3665,7 @@ example below.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>level</replaceable>
</term><listitem><anchor id="startsection-level"/><anchor id="_005c_0040startsection_002flevel"/><para>An integer giving the depth of the sectioning command.
-See <link linkend="Sectioning">Sectioning</link> for the list of standard level numbers.
+See <link linkend="Sectioning">Sectioning</link>, for the list of standard level numbers.
</para>
<para>If <replaceable>level</replaceable> is less than or equal to the value of the counter
<literal>secnumdepth</literal> then titles for this sectioning command will be
@@ -3004,7 +3690,7 @@ the title into the left margin.
</listitem></varlistentry><varlistentry><term><replaceable>beforeskip</replaceable>
</term><listitem><anchor id="startsection-beforeskip"/><anchor id="_005c_0040startsection_002fbeforeskip"/><para>The absolute value of this length is the amount of vertical space that
is inserted before this sectioning unit&#8217;s title. This space will be
-discarded if the sectioning unit happens to start at the top of a fresh
+discarded if the sectioning unit happens to start at the beginning of a
page. If this number is negative then the first paragraph following the
header is not indented, if it is non-negative then the first paragraph
is indented. (Note that the negative of <literal>1pt plus 2pt minus 3pt</literal>
@@ -3062,20 +3748,24 @@ produce titles that are bold and uppercase.
</para></listitem></varlistentry></variablelist>
<para>These are &latex;&#8217;s defaults for the first three sectioning units that
are defined with <literal>\@startsection</literal>, for the <filename>article</filename>,
-<filename>book</filename>, and <filename>report</filename> classes. For section, the <replaceable>level</replaceable> is
-1, the <replaceable>indent</replaceable> is 0pt, the <replaceable>beforeskip</replaceable> is <literal>-3.5ex
-plus -1ex minus -0.2ex</literal>, the <replaceable>afterskip</replaceable> is <literal>2.3ex plus 0.2ex</literal>,
-and the <replaceable>style</replaceable> is <literal>\normalfont\Large\bfseries</literal>. For
-subsection, the <replaceable>level</replaceable> is 2, the <replaceable>indent</replaceable> is 0pt, the
-<replaceable>beforeskip</replaceable> is <literal>-3.25ex plus -1ex minus -0.2ex</literal>, the
-<replaceable>afterskip</replaceable> is <literal>1.5ex plus 0.2ex</literal>, and the <replaceable>style</replaceable> is
-<literal>\normalfont\large\bfseries</literal>. For subsubsection, the <replaceable>level</replaceable>
-is 3, the <replaceable>indent</replaceable> is 0pt, the <replaceable>beforeskip</replaceable> is
-<literal>-3.25ex plus -1ex minus -0.2ex</literal>, the <replaceable>afterskip</replaceable> is
-<literal>1.5ex plus 0.2ex</literal>, and the <replaceable>style</replaceable> is
-<literal>\normalfont\normalsize\bfseries</literal>.
+<filename>book</filename>, and <filename>report</filename> classes.
</para>
-<para>Here are examples. They go either in a package or class file or in the
+<itemizedlist><listitem><para>For <literal>section</literal>: <replaceable>level</replaceable> is 1, <replaceable>indent</replaceable> is 0pt,
+<replaceable>beforeskip</replaceable> is <literal>-3.5ex plus -1ex minus -0.2ex</literal>,
+<replaceable>afterskip</replaceable> is <literal>2.3ex plus 0.2ex</literal>, and <replaceable>style</replaceable> is
+<literal>\normalfont\Large\bfseries</literal>.
+</para>
+</listitem><listitem><para>For <literal>subsection</literal>: <replaceable>level</replaceable> is 2, <replaceable>indent</replaceable> is 0pt,
+<replaceable>beforeskip</replaceable> is <literal>-3.25ex plus -1ex minus -0.2ex<!-- /@w --></literal>,
+<replaceable>afterskip</replaceable> is <literal>1.5ex plus 0.2ex</literal>, and <replaceable>style</replaceable> is
+<literal>\normalfont\large\bfseries</literal>.
+</para>
+</listitem><listitem><para>For <literal>subsubsection</literal>: <replaceable>level</replaceable> is 3, <replaceable>indent</replaceable> is 0pt,
+<replaceable>beforeskip</replaceable> is <literal>-3.25ex plus -1ex minus -0.2ex</literal>,
+<replaceable>afterskip</replaceable> is <literal>1.5ex plus 0.2ex</literal>, and <replaceable>style</replaceable> is
+<literal>\normalfont\normalsize\bfseries</literal>.
+</para></listitem></itemizedlist>
+<para>Some examples follow. These go either in a package or class file or in the
preamble of a &latex; document. If you put them in the preamble they
must go between a <literal>\makeatletter</literal> command and a
<literal>\makeatother</literal>. (Probably the error message <literal>You can't use
@@ -3319,6 +4009,68 @@ reference. See the documentation on CTAN.
</para>
</sect1>
+<sect1 label="7.4" id="xr-package">
+<title><literal>xr</literal> package</title>
+
+<indexterm role="fn"><primary><literal>xr</literal> package</primary></indexterm>
+<indexterm role="fn"><primary><literal>xr-hyper</literal> package</primary></indexterm>
+<indexterm role="fn"><primary>\externaldocument</primary></indexterm>
+<indexterm role="cp"><primary>cross referencing, across documents</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\usepackage{xr}
+ \externaldocument{<replaceable>document-basename</replaceable>}
+</screen>
+<para>or
+</para>
+<screen>\usepackage{xr}
+ \externaldocument[<replaceable>reference-prefix</replaceable>]{<replaceable>document-basename</replaceable>}
+</screen>
+<para>Make cross references to the external document
+<literal><replaceable>document-basename</replaceable>.tex</literal>.
+</para>
+<para>Here is an example. If <literal>lectures.tex</literal> has this in the preamble
+</para>
+<screen>\usepackage{xr}
+ \externaldocument{exercises}
+ \externaldocument[H-]{hints}
+ \externaldocument{answers}
+</screen>
+<para>then it can use cross reference labels from the other three documents.
+Suppose that <literal>exercises.tex</literal> has an enumerated list containing
+this,
+</para>
+<screen>\item \label{exer:EulersThm} What if every vertex has odd degree?
+</screen>
+<para>and <literal>hints.tex</literal> has an enumerated list with this,
+</para>
+<screen>\item \label{exer:EulersThm} Distinguish the case of two vertices.
+</screen>
+<para>and <literal>answers.tex</literal> has an enumerated list with this.
+</para>
+<screen>\item \label{ans:EulersThm} There is no Euler path, except if there
+ are exactly two vertices.
+</screen>
+<para>After compiling the exercises, hints, and answers documents, entering
+this in the body of <literal>lectures.tex</literal> will result in the lectures
+getting the reference numbers used in the other documents.
+</para>
+<screen>See Exercise~\ref{exer:EulersThm}, with Hint~\ref{H-exer:EulersThm}.
+The solution is Answer~\ref{ans:EulersThm}.
+</screen>
+<para>The prefix <literal>H-</literal> for the reference from the hints file is needed
+because the label in the hints file is the same as the label in the
+exercises file. Without that prefix, both references would get the
+number from the later file.
+</para>
+<para>Note: if the document uses the <literal>hyperref</literal> package then in place of
+<literal>xr</literal>, put <literal>\usepackage{xr-hyper}</literal> before the
+<literal>\usepackage{hyperref}</literal>. Also, if any of the multiple documents
+uses <literal>hyperref</literal> then they all must use it.
+</para>
+
+</sect1>
</chapter>
<chapter label="8" id="Environments">
<title>Environments</title>
@@ -3375,6 +4127,9 @@ default only in the <literal>report</literal> class.
in a guerrilla war, which Lee refused.
\end{abstract}
</screen>
+<indexterm role="cp"><primary>package, <literal>abstract</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>abstract</literal> package</primary></indexterm>
+
<para>The next example produces a one column abstract in a two column document (for
a more flexible solution, use the package <filename>abstract</filename>).
</para>
@@ -3546,7 +4301,7 @@ ending.
<screen>\begin{center}
My father considered that anyone who went to chapel and didn't drink
alcohol was not to be tolerated.\\
- I grew up in that belief. --Richard Burton
+ I grew up in that belief. ---Richard Burton
\end{center}
</screen>
<para>A double backslash after the final line is optional. If present it
@@ -3632,10 +4387,10 @@ missing \item</literal>&#8217;.
</para>
<para>This example shows the environment used for a sequence of definitions.
</para>
-<screen>\begin{definition}
+<screen>\begin{description}
\item[lama] A priest.
\item[llama] A beast.
-\end{definition}
+\end{description}
</screen>
<para>The labels &#8216;<literal>lama</literal>&#8217; and &#8216;<literal>llama</literal>&#8217; are output in boldface, with the
left edge on the left margin.
@@ -3688,9 +4443,9 @@ lists.
<replaceable>mathematical text</replaceable>
\end{displaymath}
</screen>
-<para>Environment to typeset the math text on its own line, in display style
-and centered. To make the text be flush-left use the global option
-<literal>fleqn</literal>; see <link linkend="Document-class-options">Document class options</link>.
+<para>Environment to typeset the <replaceable>mathematical text</replaceable> on its own line, in
+display style and centered. To make the text be flush-left use the
+global option <literal>fleqn</literal>; see <link linkend="Document-class-options">Document class options</link>.
</para>
<para>In the <literal>displaymath</literal> environment no equation number is added to the
math text. One way to get an equation number is to use the
@@ -3705,18 +4460,20 @@ math text. One way to get an equation number is to use the
displayed equation facilities. For example, there are a number of
ways in that package for having math text broken across lines.
</para>
-<para>The construct <literal>\[<replaceable>math text</replaceable>\]</literal> is essentially a synonym for
-<literal>\begin{displaymath}<replaceable>math text</replaceable>\end{displaymath}</literal> but the
-latter is easier to work with in the source file; for instance,
+<indexterm role="fn"><primary>\[...\] display math</primary></indexterm>
+<para>The construct <literal>\[<replaceable>math</replaceable>\]</literal> is a synonym for the environment
+<literal>\begin{displaymath} <replaceable>math</replaceable> \end{displaymath}</literal> but the
+latter is easier to work with in the source; for instance,
searching for a square bracket may get false positives but the word
-<literal>displaymath</literal> will likely be unique. (The construct
-<literal>$$<replaceable>math text</replaceable>$$</literal> from Plain&#160;&tex; is sometimes
-mistakenly used as a synonym for <literal>displaymath</literal>. It is not a
-synonym, because the <literal>displaymath</literal> environment checks that it isn&#8217;t
-started in math mode and that it ends in math mode begun by the matching
-environment start, because the <literal>displaymath</literal> environment has
-different vertical spacing, and because the <literal>displaymath</literal>
-environment honors the <literal>fleqn</literal> option.)
+<literal>displaymath</literal> will likely be unique.
+</para>
+<indexterm role="fn"><primary>$$...$$ plain &tex; display math</primary></indexterm>
+<para>(Aside: The construct <literal>$$<replaceable>math</replaceable>$$</literal> from Plain&#160;&tex; is
+sometimes mistakenly used as a synonym for <literal>displaymath</literal>. It is
+not a synonym, and is not officially supported in &latex; at all;
+<literal>$$</literal> doesn&#8217;t support the <literal>fleqn</literal> option (see <link linkend="Document-class-options">Document
+class options</link>), has different vertical spacing, and doesn&#8217;t perform
+consistency checks.)
</para>
<para>The output from this example is centered and alone on its line.
</para>
@@ -3887,7 +4644,7 @@ period.
<para>The <literal>eqnarray</literal> environment is obsolete. It has infelicities,
including spacing that is inconsistent with other mathematics elements.
(See &#8220;Avoid eqnarray!&#8221; by Lars Madsen
-<ulink url="http://tug.org/TUGboat/tb33-1/tb103madsen.pdf">http://tug.org/TUGboat/tb33-1/tb103madsen.pdf</ulink>). New documents
+<ulink url="https://tug.org/TUGboat/tb33-1/tb103madsen.pdf">https://tug.org/TUGboat/tb33-1/tb103madsen.pdf</ulink>). New documents
should include the <filename>amsmath</filename> package and use the displayed
mathematics environments provided there, such as the <literal>align</literal>
environment. We include a description only for completeness and for
@@ -4042,7 +4799,7 @@ end of the document, on a page of floats.
</sect1>
<sect1 label="8.11" id="filecontents">
-<title><literal>filecontents</literal>: Write an external file</title>
+<title><literal>filecontents</literal></title>
<indexterm role="fn"><primary>environment, <literal>filecontents</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>filecontents</literal> environment</primary></indexterm>
@@ -4055,34 +4812,55 @@ end of the document, on a page of floats.
<para>Synopsis:
</para>
-<screen>\begin{filecontents}{<replaceable>filename</replaceable>}
+<screen>\begin{filecontents}[<replaceable>option</replaceable>]{<replaceable>filename</replaceable>}
<replaceable>text</replaceable>
\end{filecontents}
</screen>
<para>or
</para>
-<screen>\begin{filecontents*}{<replaceable>filename</replaceable>}
+<screen>\begin{filecontents*}[<replaceable>option</replaceable>]{<replaceable>filename</replaceable>}
<replaceable>text</replaceable>
\end{filecontents*}
</screen>
-<para>Create a file named <replaceable>filename</replaceable> and fill it with <replaceable>text</replaceable>. The
-unstarred version of the environment <literal>filecontents</literal> prefixes the
-content of the created file with a header; see the example below. The
-starred version <literal>filecontents*</literal> does not include the header.
+<para>Create a file named <replaceable>filename</replaceable> in the current directory (or the
+output directory, if specified; see <link linkend="output-directory">output directory</link>) and write
+<replaceable>text</replaceable> to it. By default, an existing file is not overwritten.
</para>
-<para>This environment can be used anywhere in the preamble, although it often
-appears before the <literal>\documentclass</literal> command. It is typically used
-when a source file requires a nonstandard style or class file. The
-environment will write that file to the directory containing the source
-and thus make the source file self-contained. Another use is to include
-<literal>bib</literal> references in the file, again to make it self-contained.
+<para>The unstarred version of the environment
+<literal>filecontents</literal> prefixes the content of the created file with a
+header of &tex; comments; see the example below. The starred
+version <literal>filecontents*</literal> does not include the header.
</para>
-<para>The environment checks whether a file of that name already exists and if
-so, does not do anything. There is a <filename>filecontents</filename> package that
-redefines the <literal>filecontents</literal> environment so that instead of doing
-nothing in that case, it will overwrite the existing file.
+<para>The possible options are:
</para>
-<para>For example, this document
+<variablelist><varlistentry><term><literal>force</literal>
+</term><term><literal>overwrite</literal>
+</term><listitem><indexterm role="cp"><primary><literal>force</literal> option for <literal>filecontents</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>overwrite</literal> option for <literal>filecontents</literal></primary></indexterm>
+<para>Overwrite an existing file.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>noheader</literal>
+</term><listitem><indexterm role="cp"><primary><literal>noheader</literal> option for <literal>filecontents</literal></primary></indexterm>
+<para>Omit the header. Equivalent to using <literal>filecontents*</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>nosearch</literal>
+</term><listitem><indexterm role="cp"><primary><literal>nosearch</literal> option for <literal>filecontents</literal></primary></indexterm>
+<para>Only check the current directory (and the output directory, if
+specified) for an existing file, not the entire search path.
+</para>
+</listitem></varlistentry></variablelist>
+<para>These options were added in a 2019 release of &latex;.
+</para>
+<indexterm role="cp"><primary>self-contained sources</primary></indexterm>
+<indexterm role="cp"><primary>source files, making self-contained</primary></indexterm>
+<para>This environment can be used anywhere in the preamble, although it
+often appears before the <literal>\documentclass</literal> command. It is
+commonly used to create a <literal>.bib</literal> or other such data file from the
+main document source, to make the source file self-contained.
+Similarly, it can be used to create a custom style or class file,
+again making the source self-contained.
+</para>
+<para>For example, this document:
</para>
<screen>\documentclass{article}
\begin{filecontents}{JH.sty}
@@ -4093,7 +4871,7 @@ nothing in that case, it will overwrite the existing file.
Article by \myname.
\end{document}
</screen>
-<para>produces this file <filename>JH.sty</filename>.
+<para>produces this file <filename>JH.sty</filename>:
</para>
<screen>%% LaTeX2e file `JH.sty'
%% generated by the `filecontents' environment
@@ -4124,7 +4902,7 @@ Article by \myname.
<para>An environment that creates a paragraph whose lines are flush to the
left-hand margin, and ragged right. If you have lines that are too long
then &latex; will linebreak them in a way that avoids hyphenation and
-stretching or shrinking spaces. To force a new line use a double
+stretching or shrinking interword spaces. To force a new line use a double
backslash, <literal>\\</literal>. For the declaration form
see&#160;<link linkend="_005craggedright">\raggedright</link>.
</para>
@@ -4161,7 +4939,7 @@ flush left and ragged right.
\end{<replaceable>environment</replaceable>}
</screen>
<para>A declaration which causes lines to be flush to the left margin and
-ragged right. It can be used inside an environment such as <literal>quote</literal>
+ragged right. It can be used inside an <replaceable>environment</replaceable> such as <literal>quote</literal>
or in a <literal>parbox</literal>. For the environment form
see&#160;<link linkend="flushleft">flushleft</link>.
</para>
@@ -4204,11 +4982,13 @@ delimit its effect.
<para>An environment that creates a paragraph whose lines are flush to the
right-hand margin and ragged left. If you have lines that are too long
to fit the margins then &latex; will linebreak them in a way that
-avoids hyphenation and stretching or shrinking spaces. To force a new
+avoids hyphenation and stretching or shrinking inter-word spaces. To force a new
line use a double backslash, <literal>\\</literal>. For the declaration form
see&#160;<link linkend="_005craggedleft">\raggedleft</link>.
</para>
-<para>For an example related to this environment, see&#160;<link linkend="flushleft">flushleft</link>.
+<para>For an example related to this environment, see&#160;<link linkend="flushleft">flushleft</link>,
+where one just have mutatis mutandis to replace <literal>flushleft</literal> by
+<literal>flushright</literal>.
</para>
@@ -4231,7 +5011,7 @@ see&#160;<link linkend="_005craggedleft">\raggedleft</link>.
\end{<replaceable>environment</replaceable>}
</screen>
<para>A declaration which causes lines to be flush to the right margin and
-ragged left. It can be used inside an environment such as <literal>quote</literal>
+ragged left. It can be used inside an <replaceable>environment</replaceable> such as <literal>quote</literal>
or in a <literal>parbox</literal>. For the environment form
see&#160;<link linkend="flushright">flushright</link>.
</para>
@@ -4241,7 +5021,9 @@ formats paragraph units. To affect a paragraph unit&#8217;s format, the
scope of the declaration must contain the blank line or <literal>\end</literal>
command that ends the paragraph unit.
</para>
-<para>For an example related to this environment, see&#160;<link linkend="_005craggedright">\raggedright</link>.
+<para>For an example related to this environment, see&#160;<link linkend="_005craggedright">\raggedright</link>,
+where one just have mutatis mutandis to replace <literal>\raggedright</literal> by
+<literal>\raggedleft</literal>.
</para>
</sect2>
@@ -4266,8 +5048,8 @@ command that ends the paragraph unit.
...
\end{itemize}
</screen>
-<para>Produce a list that is unordered, sometimes called a bullet list. The
-environment must have at least one <literal>\item</literal>; having none causes the
+<para>Produce an <firstterm>unordered list</firstterm>, sometimes called a bullet list. There
+must be at least one <literal>\item</literal> within the environment; having none causes the
&latex; error &#8216;<literal>Something's wrong--perhaps a missing \item</literal>&#8217;.
</para>
<para>This gives a two-item list.
@@ -4277,34 +5059,38 @@ environment must have at least one <literal>\item</literal>; having none causes
\item Rice portrait
\end{itemize}
</screen>
-<para>As a top-level list each label would come out as a bullet, &#8226;.
-The format of the labeling depends on the nesting level; see below.
+<para>With the default locale&#8212;without loading e.g. <filename>babel</filename> package
+with another language than USenglish&#8212;as a top-level list each label
+would come out as a bullet, &#8226;. The format of the labeling
+depends on the nesting level; see below.
</para>
<indexterm role="fn"><primary>\item</primary></indexterm>
<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you
give <literal>\item</literal> an optional argument by following it with square
-brackets, as in <literal>\item[Optional label]</literal>, then by default it will
-appear in bold and be flush right, so it could extend into the left
-margin. For labels that are flush left see the <link linkend="description">description</link>
-environment. Following the <literal>\item</literal> is optional text, which may
-contain multiple paragraphs.
+brackets, as in <literal>\item[<replaceable>Optional label</replaceable>]</literal>, then by default
+<replaceable>Optional label</replaceable> will appear in bold and be flush right, so it could
+extend into the left margin. For labels that are flush left see the
+<link linkend="description">description</link> environment. Following the <literal>\item</literal> is the text of
+the item, which may be empty or contain multiple paragraphs.
+</para>
+<para>Unordered lists can be nested within one another, up to four levels deep.
+They can also be nested within other paragraph-making environments, such
+as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>).
</para>
<indexterm role="fn"><primary>\labelitemi</primary></indexterm>
<indexterm role="fn"><primary>\labelitemii</primary></indexterm>
<indexterm role="fn"><primary>\labelitemiii</primary></indexterm>
<indexterm role="fn"><primary>\labelitemiv</primary></indexterm>
-<anchor id="itemize-labelitemi"/><anchor id="itemize-labelitemii"/><anchor id="itemize-labelitemiii"/><anchor id="itemize-labelitemiv"/><para>Itemized lists can be nested within one another, up to four levels deep.
-They can also be nested within other paragraph-making environments, such
-as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). The <literal>itemize</literal> environment
-uses the commands <literal>\labelitemi</literal> through <literal>\labelitemiv</literal> to
-produce the default label (this also uses the convention of lowercase
-roman numerals at the end of the command names that signify the nesting
-level). These are the default marks at each level.
+<anchor id="itemize-labelitemi"/><anchor id="itemize-labelitemii"/><anchor id="itemize-labelitemiii"/><anchor id="itemize-labelitemiv"/><para>The <literal>itemize</literal> environment uses the commands <literal>\labelitemi</literal>
+through <literal>\labelitemiv</literal> to produce the default label (note the
+convention of lowercase roman numerals at the end of the command names
+that signify the nesting level). These are the default marks at each
+level.
</para>
<orderedlist numeration="arabic"><listitem><para>&#8226; (bullet, from <literal>\textbullet</literal>)
</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash, from <literal>\normalfont\bfseries\textendash</literal>)
</para></listitem><listitem><para>* (asterisk, from <literal>\textasteriskcentered</literal>)
-</para></listitem><listitem><para>. (centered dot, rendered here as a period, from <literal>\textperiodcentered</literal>)
+</para></listitem><listitem><para>. (vertically centered dot, rendered here as a period, from <literal>\textperiodcentered</literal>)
</para></listitem></orderedlist>
<para>Change the labels with <literal>\renewcommand</literal>. For instance, this makes
the first level use diamonds.
@@ -4320,18 +5106,22 @@ the first level use diamonds.
<indexterm role="fn"><primary>\leftmarginvi</primary></indexterm>
<anchor id="itemize-leftmargin"/><anchor id="itemize-leftmargini"/><anchor id="itemize-leftmarginii"/><anchor id="itemize-leftmarginiii"/><anchor id="itemize-leftmarginiv"/><anchor id="itemize-leftmarginv"/><anchor id="itemize-leftmarginvi"/><para>The distance between the left margin of the enclosing environment and
the left margin of the <literal>itemize</literal> list is determined by the
-parameters <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal>. (Note the
-convention of using lowercase roman numerals a the end of the command
-name to denote the nesting level.) The defaults are: <literal>2.5em</literal> in
-level 1 (<literal>2em</literal> in two-column mode), <literal>2.2em</literal> in level 2,
-<literal>1.87em</literal> in level 3, and <literal>1.7em</literal> in level 4, with smaller
-values for more deeply nested levels.
+parameters <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal>. (This also
+uses the convention of using lowercase roman numerals a the end of the
+command name to denote the nesting level.) The defaults are:
+<literal>2.5em</literal> in level 1 (<literal>2em</literal> in two-column mode), <literal>2.2em</literal> in
+level 2, <literal>1.87em</literal> in level 3, and <literal>1.7em</literal> in level 4, with
+smaller values for more deeply nested levels.
</para>
+<indexterm role="cp"><primary>package, <literal>enumitem</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>enumitem</literal> package</primary></indexterm>
+
<para>For other major &latex; labeled list environments, see
-<link linkend="description">description</link> and <link linkend="enumerate">enumerate</link>. For information about list
-layout parameters, including the default values, and for information
-about customizing list layout, see <link linkend="list">list</link>. The package
-<filename>enumitem</filename> is useful for customizing lists.
+<link linkend="description">description</link> and <link linkend="enumerate">enumerate</link>. The <literal>itemize</literal>,
+<literal>enumerate</literal> and <literal>description</literal> environment use the same list
+layout parameters. For a description, including the default values, and
+for information about customizing list layout, see <link linkend="list">list</link>. The
+package <filename>enumitem</filename> is useful for customizing lists.
</para>
<para>This example greatly reduces the margin space for outermost itemized
lists.
@@ -4414,11 +5204,11 @@ environment.
</screen>
<para>The mandatory first argument <replaceable>labeling</replaceable> specifies the default
labeling of list items. It can contain text and &latex; commands, as
-above where it contains both &#8216;<literal>Item</literal>&#8217; and &#8216;<literal>\Roman{...}</literal>&#8217;.
+above where it contains both &#8216;<literal>Item</literal>&#8217; and &#8216;<literal>\Roman{&#8230;}</literal>&#8217;.
&latex; forms the label by putting the <replaceable>labeling</replaceable> argument in a box
of width <literal>\labelwidth</literal>. If the label is wider than that, the
additional material extends to the right. When making an instance of a
-list you can override the default labeling by giving <literal>\item</literal> an
+<literal>list</literal> you can override the default labeling by giving <literal>\item</literal> an
optional argument by including square braces and the text, as in the
above <literal>\item[Special label.]</literal>; see <link linkend="_005citem">\item</link>.
</para>
@@ -4440,7 +5230,7 @@ definition of the environment add
<literal>\newcommand{\namedmakelabel}[1]{\textsc{#1}}</literal>, and between
the <literal>\setlength</literal> command and the parenthesis that closes the
<replaceable>spacing</replaceable> argument also add <literal>\let\makelabel\namedmakelabel</literal>.
-Then the items will be typeset in small caps. Similarly, changing the
+Then the labels will be typeset in small caps. Similarly, changing the
second code line to <literal>\let\makelabel\fbox</literal> puts the labels inside a
framed box. Another example of the <literal>\makelabel</literal> command is below,
in the definition of the <literal>redlabel</literal> environment.
@@ -4466,7 +5256,7 @@ and &#8216;<literal>report</literal>&#8217; classes at 10 point size are: <liter
minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>), and
<literal>\topsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>). The defaults at
11 point are: <literal>4.5pt plus2pt minus1pt</literal>, <literal>\parsep</literal> (that is,
-<literal>2pt plus1pt minus1pt</literal>), and <literal>topsep</literal> (that is, <literal>2pt
+<literal>2pt plus1pt minus1pt</literal>), and <literal>\topsep</literal> (that is, <literal>2pt
plus1pt minus1pt</literal>). The defaults at 12 point are: <literal>5pt plus2.5pt
minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>), and
<literal>\topsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>).
@@ -4521,14 +5311,14 @@ item. A negative value makes this an &#8220;outdent&#8221;. Its default value
is <literal>0pt</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal>
-</term><listitem><anchor id="list-parsep"/><para>Vertical space between paragraphs within an item. In the &#8216;<literal>book</literal>&#8217;
-and &#8216;<literal>article</literal>&#8217; classes The defaults for the first three levels in
-&latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217; classes at 10
-point size are: <literal>4pt plus2pt minus1pt</literal>, <literal>2pt plus1pt
-minus1pt</literal>, and <literal>0pt</literal>. The defaults at 11 point size are:
-<literal>4.5pt plus2pt minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and
-<literal>0pt</literal>. The defaults at 12 point size are: <literal>5pt plus2.5pt
-minus1pt</literal>, <literal>2.5pt plus1pt minus1pt</literal>, and <literal>0pt</literal>.
+</term><listitem><anchor id="list-parsep"/><para>Vertical space between paragraphs within an item.
+The defaults for the first three levels in &latex;&#8217;s &#8216;<literal>article</literal>&#8217;,
+&#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217; classes at 10 point size are: <literal>4pt
+plus2pt minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and <literal>0pt</literal>. The
+defaults at 11 point size are: <literal>4.5pt plus2pt minus1pt</literal>,
+<literal>2pt plus1pt minus1pt</literal>, and <literal>0pt</literal>. The defaults at 12 point
+size are: <literal>5pt plus2.5pt minus1pt</literal>, <literal>2.5pt plus1pt
+minus1pt</literal>, and <literal>0pt</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal>
</term><listitem><anchor id="list-partopsep"/><para>Vertical space added, beyond <literal>\topsep</literal>+<literal>\parskip</literal>, to the top
@@ -4672,7 +5462,7 @@ See <link linkend="_005cusecounter">\usecounter</link>.
\let\makelabel=\makeredlabel
}
}
-{\end{list} }
+{\end{list}}
</screen>
@@ -4691,7 +5481,7 @@ See <link linkend="_005cusecounter">\usecounter</link>.
depends on the list type.
</para>
<para>Because the optional label is surrounded by square brackets
-&#8216;<literal>[...]</literal>&#8217;, if you have an item whose text starts with &#8216;<literal>[</literal>&#8217;, you
+&#8216;<literal>[...]</literal>&#8217;, if you have an item whose text starts with [, you
have to hide the bracket inside curly braces, as in: <literal>\item
{[} is an open square bracket</literal>; otherwise, &latex; will think it
marks the start of an optional label.
@@ -4729,7 +5519,7 @@ labelled&#160;&#8216;<literal>3.</literal>&#8217;.
<para>A restricted version of the list environment, in which margins are not
indented and an <literal>\item</literal> without an optional argument produces no
text. It is most often used in macros, to define an environment where
-the <literal>\item</literal> command as part of the environment&#8217;s definition. For
+the <literal>\item</literal> command is part of the environment&#8217;s definition. For
instance, the <literal>center</literal> environment is defined essentially like
this:
</para>
@@ -4766,7 +5556,7 @@ default) they have no paragraph indent and are vertically separated.
<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm>
-<indexterm role="cp"><primary>in-line formulas</primary></indexterm>
+<indexterm role="cp"><primary>inline formulas</primary></indexterm>
<para>Synopsis:
</para>
@@ -4774,6 +5564,8 @@ default) they have no paragraph indent and are vertically separated.
<replaceable>math</replaceable>
\end{math}
</screen>
+<indexterm role="fn"><primary>$ inline math</primary></indexterm>
+<indexterm role="fn"><primary>\(...\) inline math</primary></indexterm>
<para>The <literal>math</literal> environment inserts given <replaceable>math</replaceable> material within
the running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms.
See <link linkend="Math-formulas">Math formulas</link>.
@@ -4826,24 +5618,30 @@ It gives the width of the box into which <replaceable>contents</replaceable> are
<para>There are three optional arguments, <replaceable>position</replaceable>, <replaceable>height</replaceable>, and
<replaceable>inner-pos</replaceable>. You need not include all three. For example, get the
default <replaceable>position</replaceable> and set the <replaceable>height</replaceable> with
-<literal>\begin{minipage}[c][2.54cm] <replaceable>contents</replaceable> \end{minipage}</literal>.
-(Get the natural height with an empty argument, <literal>[]</literal>.)
+<literal>\begin{minipage}[c][2.54cm]{\columnwidth} <replaceable>contents</replaceable>
+\end{minipage}</literal>. (Get the natural height with an empty argument,
+<literal>[]</literal>.)
</para>
<para>The optional argument <replaceable>position</replaceable> governs how the <literal>minipage</literal>
vertically aligns with the surrounding material.
</para>
<variablelist><varlistentry><term><literal>c</literal>
-</term><listitem><para>(synonym <literal>m</literal>) Default. Positions the <literal>minipage</literal> so its
-vertical center lines up with the center of the adjacent text line (what
-Plain &tex; calls <literal>\vcenter</literal>).
+</term><listitem><!-- xx Clarify what it means when adjacent text lines do not have aligned -->
+<!-- vertical center with each other -->
+<para>(synonym <literal>m</literal>) Default. Positions the <literal>minipage</literal> so its
+vertical center lines up with the center of the adjacent text line.
</para>
</listitem></varlistentry><varlistentry><term><literal>t</literal>
-</term><listitem><para>Match the top line in the <literal>minipage</literal> with the baseline of the
-surrounding text (Plain &tex;&#8217;s <literal>\vtop</literal>.
+</term><listitem><indexterm role="fn"><primary>\vtop plain &tex;</primary></indexterm>
+<!-- xx Is there any reason why the word ``match'' is used instead of word -->
+<!-- ``align''. Do we mean some more permissive alignment? -->
+<para>Match the top line in the <literal>minipage</literal> with the baseline of the
+surrounding text (plain &tex;&#8217;s <literal>\vtop</literal>).
</para>
</listitem></varlistentry><varlistentry><term><literal>b</literal>
-</term><listitem><para>Match the bottom line in the <literal>minipage</literal> with the baseline of the
-surrounding text (Plain &tex;&#8217;s <literal>\vbox</literal>.
+</term><listitem><indexterm role="fn"><primary>\vbox plain &tex;</primary></indexterm>
+<para>Match the bottom line in the <literal>minipage</literal> with the baseline of the
+surrounding text (plain &tex;&#8217;s <literal>\vbox</literal>).
</para></listitem></varlistentry></variablelist>
<para>To see the effects of these, contrast running this
</para>
@@ -4853,6 +5651,8 @@ surrounding text (Plain &tex;&#8217;s <literal>\vbox</literal>.
</screen>
<para>with the results of changing <literal>c</literal> to <literal>b</literal> or&#160;<literal>t</literal>.
</para>
+<!-- xx Clarify what happens if user enter a rubber length instead of a -->
+<!-- rigid length. -->
<para>The optional argument <replaceable>height</replaceable> is a rigid length (see <link linkend="Lengths">Lengths</link>).
It sets the height of the <literal>minipage</literal>. You can enter any value
larger than, or equal to, or smaller than the <literal>minipage</literal>&#8217;s natural
@@ -4860,11 +5660,11 @@ height and &latex; will not give an error or warning. You can also set
it to a height of zero or a negative value.
</para>
<para>The final optional argument <replaceable>inner-pos</replaceable> controls the placement of
-<replaceable>content</replaceable> inside the box. These are the possible values are (the
+<replaceable>contents</replaceable> inside the box. These are the possible values are (the
default is the value of <replaceable>position</replaceable>).
</para>
<variablelist><varlistentry><term><literal>t</literal>
-</term><listitem><para>Place <replaceable>content</replaceable> at the top of the box.
+</term><listitem><para>Place <replaceable>contents</replaceable> at the top of the box.
</para>
</listitem></varlistentry><varlistentry><term><literal>c</literal>
</term><listitem><para>Place it in the vertical center.
@@ -4929,19 +5729,29 @@ Footnotes appear at the bottom of the text ended by the next
<para>This puts a table containing data side by side with a map graphic. They
are vertically centered.
</para>
-<screen>\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}}
+<indexterm role="cp"><primary>package, <literal>siunitx</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>siunitx</literal> package</primary></indexterm>
+
+<screen>% siunitx to have the S column specifier,
+% which aligns numbers on their decimal point.
+\usepackage{siunitx}
+\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}}
...
\begin{center}
\vcenteredhbox{\includegraphics[width=0.3\textwidth]{nyc.png}}
\hspace{0.1\textwidth}
\begin{minipage}{0.5\textwidth}
- \begin{tabular}{r|l}
- \multicolumn{1}{r}{Borough} &amp;Pop (million) \\ \hline
- The Bronx &amp;$1.5$ \\
- Brooklyn &amp;$2.6$ \\
- Manhattan &amp;$1.6$ \\
- Queens &amp;$2.3$ \\
- Staten Island &amp;$0.5$
+ \begin{tabular}{r|S}
+ % \multicolumn to remove vertical bar between column headers
+ \multicolumn{1}{r}{Borough} &amp;
+ % braces to prevent siunitx from misinterpreting the
+ % period as a decimal separator
+ {Pop. (million)} \\ \hline
+ The Bronx &amp;1.5 \\
+ Brooklyn &amp;2.6 \\
+ Manhattan &amp;1.6 \\
+ Queens &amp;2.3 \\
+ Staten Island &amp;0.5
\end{tabular}
\end{minipage}
\end{center}
@@ -4959,22 +5769,24 @@ are vertically centered.
<para>Synopses:
</para><screen>\begin{picture}(<replaceable>width</replaceable>,<replaceable>height</replaceable>)
- <replaceable>picture commands</replaceable>
+ <replaceable>picture command</replaceable>
\end{picture}
</screen>
<para>or
</para>
<screen>\begin{picture}(<replaceable>width</replaceable>,<replaceable>height</replaceable>)(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>)
- <replaceable>picture commands</replaceable>
+ <replaceable>picture command</replaceable>
\end{picture}
</screen>
+<para>Where there may be any number of <replaceable>picture command</replaceable>&#8217;s.
+</para>
<para>An environment to create simple pictures containing lines, arrows,
-boxes, circles, and text. Note that while this environment is not
-obsolete, new documents typically use much more powerful graphics
-creation systems, such as <literal>TikZ</literal>, <literal>PSTricks</literal>, <literal>MetaPost</literal>,
-or <literal>Asymptote</literal>. These are not covered in this document; see CTAN.
+boxes, circles, and text. This environment is not obsolete, but new
+documents typically use much more powerful graphics creation systems,
+such as TikZ, PSTricks, MetaPost, or Asymptote. None of these are
+covered in this document; see CTAN.
</para>
-<para>This shows the parallelogram law for adding vectors.
+<para>To start, here&#8217;s an example showing the parallelogram law for adding vectors.
</para>
<indexterm role="fn"><primary>\unitlength</primary></indexterm>
<screen>\setlength{\unitlength}{1cm}
@@ -4983,41 +5795,24 @@ or <literal>Asymptote</literal>. These are not covered in this document; see CT
\put(2,1){\makebox(0,0)[l]{\ first leg}}
\put(4,2){\vector(1,2){2}}
\put(5,4){\makebox(0,0)[l]{\ second leg}}
- \put(0,0){\line(1,1){6}}
+ \put(0,0){\vector(1,1){6}}
\put(3,3){\makebox(0,0)[r]{sum\ }}
\end{picture}
</screen>
-<para>You can also use this environment to place arbitrary material at an
-exact location.
-</para>
-<screen>\usepackage{color,graphicx} % in preamble
- ...
-\begin{center}
-\setlength{\unitlength}{\textwidth}
-\begin{picture}(1,1) % leave space, \textwidth wide and tall
- \put(0,0){\includegraphics[width=\textwidth]{desertedisland.jpg}}
- \put(0.25,0.35){\textcolor{red}{X Treasure here}}
-\end{picture}
-\end{center}
-</screen>
-<para>The red&#160;X will be precisely a quarter of the <literal>\linewidth</literal> from
-the left margin, and <literal>0.35\linewidth</literal> up from the bottom. Another
-example of this usage is to put similar code in the page header to get
-repeat material on each of a document&#8217;s pages.
-</para>
<para>The <literal>picture</literal> environment has one required argument, a pair of
-numbers (<replaceable>width</replaceable>,<replaceable>height</replaceable>). Multiply these by the value
-<literal>\unitlength</literal> to get the nominal size of the output, the space that
-&latex; reserves on the output page. This nominal size need not be how
-large the picture really is; &latex; will draw things from the picture
-outside the picture&#8217;s box.
+positive real numbers (<replaceable>width</replaceable>,<replaceable>height</replaceable>). Multiply these by the
+value <literal>\unitlength</literal> to get the nominal size of the output, i.e.
+the space that &latex; reserves on the output page. This nominal size
+need not be how large the picture really is; &latex; will draw things
+from the picture outside the picture&#8217;s box.
</para>
<para>This environment also has an optional argument
(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>). It is used to shift the origin. Unlike
most optional arguments, this one is not contained in square brackets.
-As with the required argument, it consists of two real numbers.
-Multiply these by <literal>\unitlength</literal> to get the point at the lower-left
-corner of the picture.
+As with the required argument, it consists of a pair of two real
+numbers, but these may also be negative or null. Multiply these
+by <literal>\unitlength</literal> to get the coordinates of the point at the
+lower-left corner of the picture.
</para>
<para>For example, if <literal>\unitlength</literal> has been set to <literal>1mm</literal>, the
command
@@ -5034,24 +5829,27 @@ optional argument.
</para>
<indexterm role="cp"><primary>position, in picture</primary></indexterm>
<para>Each <replaceable>picture command</replaceable> tells &latex; where to put something by
-naming its position. A <firstterm>position</firstterm> is a pair such as <literal>(2.4,-5)</literal>
+providing its position. A <firstterm>position</firstterm> is a pair such as <literal>(2.4,-5)</literal>
giving the x- and y-coordinates. A <firstterm>coordinate</firstterm> is a not a length,
it is a real number (it may have a decimal point or a minus sign). It
specifies a length in multiples of the unit length <literal>\unitlength</literal>,
so if <literal>\unitlength</literal> has been set to <literal>1cm</literal>, then the coordinate
-2.54 specifies a length of 2.54 centimeters.
+<literal>2.54</literal> specifies a length of 2.54 centimeters.
</para>
-<para>&latex;&#8217;s default for <literal>\unitlength</literal> is <literal>1pt</literal>. it is a rigid
+<para>&latex;&#8217;s default for <literal>\unitlength</literal> is <literal>1pt</literal>. It is a rigid
length (see <link linkend="Lengths">Lengths</link>). Change it with the <literal>\setlength</literal> command
(see <link linkend="_005csetlength">\setlength</link>). Make this change only outside of a <literal>picture</literal>
environment.
</para>
-<para>Coordinates are given with respect to an origin, which is normally at
+<para>The <literal>picture</literal> environment supports using standard arithmetic
+expressions as well as numbers.
+</para>
+<para>Coordinates are given with respect to an origin, which is by default at
the lower-left corner of the picture. Note that when a position appears
as an argument, as with <literal>\put(1,2){...}</literal>, it is not enclosed in
braces since the parentheses serve to delimit the argument. Also,
unlike in some computer graphics systems, larger y-coordinates are
-further up the page.
+further up the page, for example, <inlineequation><mathphrase>y = 1</mathphrase></inlineequation> is <emphasis>above</emphasis> <inlineequation><mathphrase>y = 0</mathphrase></inlineequation>.
</para>
<para>There are four ways to put things in a picture: <literal>\put</literal>,
<literal>\multiput</literal>, <literal>\qbezier</literal>, and <literal>\graphpaper</literal>. The most
@@ -5082,21 +5880,24 @@ line of length one; rather the line has a change in the x coordinate of
<para>The <literal>\multiput</literal>, <literal>qbezier</literal>, and <literal>graphpaper</literal> commands are
described below.
</para>
-<para>This draws a rectangle with a wavy top, using <literal>\qbezier</literal> for
-that curve.
+<para>You can also use this environment to place arbitrary material at an
+exact location. For example:
</para>
-<screen>\begin{picture}(3,1.5)
- \put(0,0){\vector(1,0){8}} % x axis
- \put(0,0){\vector(0,1){4}} % y axis
- \put(2,0){\line(0,1){3}} % left side rectangle
- \put(4,0){\line(0,1){3.5}} % right side
- \qbezier(2,3)(2.5,2.9)(3,3.25)
- \qbezier(3,3.25)(3.5,3.6)(4,3.5)
- \thicklines % below here, lines are twice as thick
- \put(2,3){\line(4,1){2}}
- \put(4.5,2.5){\framebox{Trapezoidal Rule}}
+<screen>\usepackage{color,graphicx} % in preamble
+ ...
+\begin{center}
+\setlength{\unitlength}{\textwidth}
+\begin{picture}(1,1) % leave space, \textwidth wide and tall
+ \put(0,0){\includegraphics[width=\textwidth]{desertedisland.jpg}}
+ \put(0.25,0.35){\textcolor{red}{X Treasure here}}
\end{picture}
+\end{center}
</screen>
+<para>The red&#160;X will be precisely a quarter of the <literal>\textwidth</literal> from
+the left margin, and <literal>0.35\textwidth</literal> up from the bottom of the
+picture. Another example of this usage is to put similar code in the
+page header to get repeat material on each of a document&#8217;s pages.
+</para>
<sect2 label="8.19.1" id="_005cput">
@@ -5178,7 +5979,21 @@ intermediate points. The default is to draw a smooth curve whose
maximum number of points is <literal>\qbeziermax</literal> (change this value with
<literal>\renewcommand</literal>).
</para>
-
+<para>This draws a rectangle with a wavy top, using <literal>\qbezier</literal> for
+that curve.
+</para>
+<screen>\begin{picture}(8,4)
+ \put(0,0){\vector(1,0){8}} % x axis
+ \put(0,0){\vector(0,1){4}} % y axis
+ \put(2,0){\line(0,1){3}} % left side
+ \put(4,0){\line(0,1){3.5}} % right side
+ \qbezier(2,3)(2.5,2.9)(3,3.25)
+ \qbezier(3,3.25)(3.5,3.6)(4,3.5)
+ \thicklines % below here, lines are twice as thick
+ \put(2,3){\line(4,1){2}}
+ \put(4.5,2.5){\framebox{Trapezoidal Rule}}
+\end{picture}
+</screen>
</sect2>
<sect2 label="8.19.4" id="_005cgraphpaper">
<title><literal>\graphpaper</literal></title>
@@ -5189,7 +6004,10 @@ maximum number of points is <literal>\qbeziermax</literal> (change this value wi
<screen>\graphpaper(<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)(<replaceable>x_dimen</replaceable>,<replaceable>y_dimen</replaceable>)
\graphpaper[<replaceable>spacing</replaceable>](<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)(<replaceable>x_dimen</replaceable>,<replaceable>y_dimen</replaceable>)
</screen>
-<para>Draw a coordinate grid. Requires the <literal>graphpap</literal> package.
+<indexterm role="cp"><primary>package, <literal>graphpap</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>graphpap</literal> package</primary></indexterm>
+
+<para>Draw a coordinate grid. Requires the <filename>graphpap</filename> package.
The grid&#8217;s origin is <literal>(<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)</literal>.
Grid lines come every <replaceable>spacing</replaceable> units (the default is 10).
The grid extends <replaceable>x_dimen</replaceable> units to the right and <replaceable>y_dimen</replaceable> units up.
@@ -5218,7 +6036,7 @@ All arguments must be positive integers.
</screen>
<para>Draw a line. It slopes such that it vertically rises <replaceable>y_rise</replaceable> for
every horizontal <replaceable>x_run</replaceable>. The <replaceable>travel</replaceable> is the total horizontal
-change&#160;&#8212; it is not the length of the vector, it is the change in
+change&#8212;it is not the length of the vector, it is the change in
<inlineequation><mathphrase>x</mathphrase></inlineequation>. In the special case of vertical lines, where
(<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>)=(0,1), the <replaceable>travel</replaceable> gives the change in
<inlineequation><mathphrase>y</mathphrase></inlineequation>.
@@ -5270,9 +6088,10 @@ relatively prime, so that <replaceable>(x_run,y_rise)</replaceable> can be (2,1)
(4,2) (if you choose the latter then instead of lines you get sequences
of arrowheads; the solution is to switch to the former). To get lines
of arbitrary slope and plenty of other shapes in a system like
-<literal>picture</literal>, see the package <filename>pict2e</filename> on CTAN. Another solution
-is to use a full-featured graphics system such as <filename>TikZ</filename>, or
-<filename>PSTricks</filename>, or <filename>MetaPost</filename>, or <filename>Asymptote</filename>
+<literal>picture</literal>, see the package <filename>pict2e</filename>
+(<ulink url="https://ctan.org/pkg/pict2e">https://ctan.org/pkg/pict2e</ulink>). Another solution
+is to use a full-featured graphics system such as TikZ, PSTricks,
+MetaPost, or Asymptote.
</para>
</sect2>
@@ -5334,8 +6153,8 @@ one. The <literal>*</literal>&#160;form produces a filled-in circle.
</para>
<screen>\put(5,7){\circle{6}}
</screen>
-<para>The available radii for <literal>circle</literal> are, in points, the even
-numbers from 2 to 20, inclusive. For <literal>circle*</literal> they are all the
+<para>The available radii for <literal>\circle</literal> are, in points, the even
+numbers from 2 to 20, inclusive. For <literal>\circle*</literal> they are all the
integers from 1 to 15.
</para>
@@ -5438,7 +6257,7 @@ argument <literal>\shortstack{X\\[2pt] o\\o\\X}</literal>.
</screen>
<para>Draw a line ending in an arrow. The slope of that line is: it
vertically rises <replaceable>y_rise</replaceable> for every horizontal <replaceable>x_run</replaceable>. The
-<replaceable>travel</replaceable> is the total horizontal change&#160;&#8212; it is not the
+<replaceable>travel</replaceable> is the total horizontal change&#8212;it is not the
length of the vector, it is the change in <inlineequation><mathphrase>x</mathphrase></inlineequation>. In the special case
of vertical vectors, if (<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>)=(0,1), then
<replaceable>travel</replaceable> gives the change in <inlineequation><mathphrase>y</mathphrase></inlineequation>.
@@ -5640,6 +6459,8 @@ between paragraphs (it is the rubber length <literal>\parsep</literal>).
<sect1 label="8.21" id="tabbing">
<title><literal>tabbing</literal></title>
+<!-- xx TODO align on the French which is more precise and has more illustrative examples. -->
+
<indexterm role="fn"><primary>environment, <literal>tabbing</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>tabbing</literal> environment</primary></indexterm>
@@ -5665,12 +6486,12 @@ known in advance.
widths, ended by a <literal>\kill</literal> command (which is described below):
</para>
<screen>\begin{tabbing}
-\hspace{0.75in} \= \hspace{0.40in} \= \hspace{0.40in} \kill
-Ship \&gt; Guns \&gt; Year \\
-\textit{Sophie} \&gt; 14 \&gt; 1800 \\
-\textit{Polychrest} \&gt; 24 \&gt; 1803 \\
-\textit{Lively} \&gt; 38 \&gt; 1804 \\
-\textit{Surprise} \&gt; 28 \&gt; 1805 \\
+\hspace{1.2in}\=\hspace{1in}\=\kill
+Ship \&gt;Guns \&gt;Year \\
+\textit{Sophie} \&gt;14 \&gt;1800 \\
+\textit{Polychrest} \&gt;24 \&gt;1803 \\
+\textit{Lively} \&gt;38 \&gt;1804 \\
+\textit{Surprise} \&gt;28 \&gt;1805 \\
\end{tabbing}
</screen>
<para>Both the <literal>tabbing</literal> environment and the more widely-used
@@ -5680,10 +6501,10 @@ determined automatically by &latex;, while in <literal>tabbing</literal> the use
sets the tab stops. Another distinction is that <literal>tabular</literal>
generates a box, but <literal>tabbing</literal> can be broken across pages.
Finally, while <literal>tabular</literal> can be used in any mode, <literal>tabbing</literal>
-can be used only in paragraph mode and it starts a new paragraph.
+can be used only in paragraph mode and it always starts a new paragraph,
+without indentation.
</para>
-<para>A <literal>tabbing</literal> environment always starts a new paragraph, without
-indentation. Moreover, as shown in the example above, there is no need
+<para>Moreover, as shown in the example above, there is no need
to use the starred form of the <literal>\hspace</literal> command at the beginning
of a tabbed row. The right margin of the <literal>tabbing</literal> environment is
the end of line, so that the width of the environment is
@@ -5696,8 +6517,9 @@ rows</firstterm>. The first tabbed row begins immediately after
<literal>\kill</literal>. The last row may omit the <literal>\\</literal> and end with just
<literal>\end{tabbing}</literal>.
</para>
-<para>At any point the <literal>tabbing</literal> environment has a current tab stop
-pattern, a sequence of <inlineequation><mathphrase><replaceable>n</replaceable> &gt; 0</mathphrase></inlineequation> tab stops, numbered 0, 1,
+<indexterm role="cp"><primary>pattern, current tab stops, tabbing</primary></indexterm>
+<para>At any point the <literal>tabbing</literal> environment has a <firstterm>current tab stop
+pattern</firstterm>, a sequence of <inlineequation><mathphrase><replaceable>n</replaceable> &gt; 0</mathphrase></inlineequation> tab stops, numbered 0, 1,
etc. These create <replaceable>n</replaceable> corresponding columns. Tab stop&#160;0 is
always the left margin, defined by the enclosing environment. Tab
stop number&#160;<replaceable>i</replaceable> is set if it is assigned a horizontal
@@ -5854,20 +6676,18 @@ are floated to a convenient place, such as the top of a following page.
\label{tab:cello}
\end{table}
</screen>
-<para>but you can put many different kinds of content in a <literal>table</literal>,
-including text, &latex; commands, etc.
+<para>but you can put many different kinds of content in a <literal>table</literal>:
+the <replaceable>table body</replaceable> may contain text, &latex; commands, graphics, etc. It is
+typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal>.
</para>
<para>For the possible values of <replaceable>placement</replaceable> and their effect on the
float placement algorithm, see <link linkend="Floats">Floats</link>.
</para>
-<para>The table body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal>.
-It can contain text, commands, graphics, etc.
-</para>
<para>The label is optional; it is used for cross references (see <link linkend="Cross-references">Cross
references</link>).
<indexterm role="fn"><primary>\caption</primary></indexterm>
The <literal>\caption</literal> command is also optional. It specifies caption text
-for the table. By default it is numbered. If its optional
+<replaceable>title</replaceable> for the table. By default it is numbered. If its optional
<replaceable>lottitle</replaceable> is present then that text is used in the list of tables
instead of <replaceable>title</replaceable> (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>).
</para>
@@ -5924,7 +6744,7 @@ illustrates many of the features.
<para>The output will have two left-aligned columns with a vertical bar
between them. This is specified in <literal>tabular</literal>&#8217;s argument
<literal>{l|l}</literal>.
-<indexterm role="fn"><primary>&amp;</primary></indexterm>
+<indexterm role="fn"><primary>&amp; for table cells</primary></indexterm>
Put the entries into different columns by separating them with an
ampersand, <literal>&amp;</literal>. The end of each row is marked with a double
backslash, <literal>\\</literal>. Put a horizontal rule below a row, after a double
@@ -6032,7 +6852,7 @@ a <literal>\centering</literal>, <literal>\raggedright</literal>, or <literal>\r
declaration (when used in a <literal>p</literal>-column element these declarations
must appear inside braces, as with <literal>{\centering .. \\
..}</literal>). Otherwise &latex; will misinterpret the double backslash as
-ending the row. Instead, to get a line break in there use
+ending the tabular row. Instead, to get a line break in there use
<literal>\newline</literal> (see <link linkend="_005cnewline">\newline</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>*{<replaceable>num</replaceable>}{<replaceable>cols</replaceable>}</literal>
@@ -6268,7 +7088,7 @@ is required.
</screen>
<para>Produce a bibliography or reference list. There are two ways to produce
bibliographic lists. This environment is suitable when you have only a
-few references and can maintain the list by hand. See <link linkend="Using-BibTeX">Using BibTeX</link>
+few references and can maintain the list by hand. See <link linkend="Using-BibTeX">Using BibTeX</link>,
for a more sophisticated approach.
</para>
<para>This shows the environment with two entries.
@@ -6288,15 +7108,17 @@ Together they are \cite{latexdps, texbook}.
\end{thebibliography}
</screen>
<para>This styles the first reference as &#8216;<literal>[1] Leslie ...</literal>&#8217;, and so that
-<literal>\cite{latexdps}</literal> produces the matching &#8216;<literal>... based on [1]</literal>&#8217;.
-The second <literal>\cite</literal> produces &#8216;<literal>[1, 2]</literal>&#8217;. You must compile the
-document twice to resolve these references.
+<literal>... based on \cite{latexdps}</literal> produces the matching
+&#8216;<literal>... based on [1]</literal>&#8217;. The second <literal>\cite</literal> produces &#8216;<literal>[1,
+2]</literal>&#8217;. You must compile the document twice to resolve these references.
</para>
<para>The mandatory argument <replaceable>widest-label</replaceable> is text that, when typeset, is
as wide as the widest item label produced by the <literal>\bibitem</literal>
commands. The tradition is to use <literal>9</literal> for bibliographies with less
than 10 references, <literal>99</literal> for ones with less than 100, etc.
</para>
+<indexterm role="fn"><primary>\bibname</primary></indexterm>
+<indexterm role="fn"><primary>\refname</primary></indexterm>
<para>The bibliographic list is headed by a title such as &#8216;<literal>Bibliography</literal>&#8217;.
To change it there are two cases. In the <filename>book</filename> and <filename>report</filename>
classes, where the top level sectioning is <literal>\chapter</literal> and the
@@ -6304,7 +7126,7 @@ default title is &#8216;<literal>Bibliography</literal>&#8217;, that title is in
<literal>\bibname</literal>. For <filename>article</filename>, where the class&#8217;s top level
sectioning is <literal>\section</literal> and the default is &#8216;<literal>References</literal>&#8217;, the
title is in macro <literal>\refname</literal>. Change it by redefining the command,
-as with <literal>\renewcommand{\refname}{Cited references}</literal> after
+as with <literal>\renewcommand{\refname}{Cited references}</literal>, after
<literal>\begin{document}</literal>.
</para>
<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm>
@@ -6314,6 +7136,8 @@ as with <literal>\renewcommand{\refname}{Cited references}</literal> after
redefine <literal>\refname</literal> or <literal>\bibname</literal> to fit the selected
language.
</para>
+<para>See <link linkend="list">list</link>, for the list layout control parameters.
+</para>
<sect2 label="8.24.1" id="_005cbibitem">
@@ -6329,16 +7153,16 @@ language.
</para>
<screen>\bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key</replaceable>}
</screen>
-<para>Generate an entry labeled by <replaceable>label</replaceable>. The default is for &latex; to
-generates a number using the <literal>enumi</literal> counter. The <firstterm>citation key</firstterm>
+<para>Generate an entry labeled by default by a number generated using the
+<literal>enumi</literal> counter. The <firstterm>citation key</firstterm>
<indexterm role="cp"><primary>citation key</primary></indexterm>
-<replaceable>cite_key</replaceable> is a string of
+<replaceable>cite_key</replaceable> can be any string of
letters, numbers, and punctuation symbols (but not comma).
</para>
-<para>See <link linkend="thebibliography">thebibliography</link> for an example.
+<para>See <link linkend="thebibliography">thebibliography</link>, for an example.
</para>
-<para>The optional <replaceable>label</replaceable> changes the default label from an integer to the
-given string. With this
+<para>When provided, the optional <replaceable>label</replaceable> becomes the entry label and the
+<literal>enumi</literal> counter is not incremented. With this
</para>
<screen>\begin{thebibliography}
\bibitem[Lamport 1993]{latexdps}
@@ -6367,8 +7191,8 @@ Warning: There were multiply-defined labels</literal>&#8217;.
</para>
<para>Under the hood, &latex; remembers the <replaceable>cite_key</replaceable> and <replaceable>label</replaceable>
information because <literal>\bibitem</literal> writes it to the auxiliary file
-<filename><replaceable>filename</replaceable>.aux</filename>. For instance, the above example causes
-<literal>\bibcite{latexdps}{Lamport, 1993}</literal> and
+<filename><replaceable>jobname</replaceable>.aux</filename> (see <link linkend="Jobname">Jobname</link>). For instance, the above
+example causes the two <literal>\bibcite{latexdps}{Lamport, 1993}</literal> and
<literal>\bibcite{texbook}{1}</literal> to appear in that file. The <filename>.aux</filename>
file is read by the <literal>\begin{document}</literal> command and then the
information is available for <literal>\cite</literal> commands. This explains why
@@ -6410,20 +7234,21 @@ comma-separated list of citation keys (see <link linkend="_005cbibitem">\bibitem
Addison-Wesley, Reading, Massachusetts, 1983.
\end{thebibliography}
</screen>
-<para>produces output like &#8216;<literal>... source is [1]</literal>&#8217;. (You can change the
-appearance of the citation with bibliography styles. More is in
-<link linkend="Using-BibTeX">Using BibTeX</link>.)
+<para>produces output like &#8216;<literal>... source is [1]</literal>&#8217;. You can change the
+appearance of the citation and of the reference by using bibliography
+styles if you generate automatically the <literal>thebibliography</literal>
+environment. More information in <link linkend="Using-BibTeX">Using BibTeX</link>.
</para>
<para>The optional argument <replaceable>subcite</replaceable> is appended to the citation. For
example, <literal>See 14.3 in \cite[p.~314]{texbook}</literal> might produce
&#8216;<literal>See 14.3 in [1, p.&#160;314]</literal>&#8217;.
</para>
<para>In addition to what appears in the output, <literal>\cite</literal> writes
-information to the auxiliary file <filename><replaceable>filename</replaceable>.aux</filename>. For
-instance, <literal>\cite{latexdps}</literal> writes &#8216;<literal>\citation{latexdps}</literal>&#8217;
-to that file. This information is used by Bib&tex; to include in your
-reference list only those works that you have actually cited; see
-<link linkend="_005cnocite">\nocite</link> also.
+information to the auxiliary file <filename><replaceable>jobname</replaceable>.aux</filename>
+(see <link linkend="Jobname">Jobname</link>). For instance, <literal>\cite{latexdps}</literal> writes
+&#8216;<literal>\citation{latexdps}</literal>&#8217; to that file. This information is used by
+Bib&tex; to include in your reference list only those works that you
+have actually cited; see <link linkend="_005cnocite">\nocite</link> also.
</para>
<para>If <replaceable>keys</replaceable> is not in your bibliography information then you get
&#8216;<literal>LaTeX Warning: There were undefined references</literal>&#8217;, and in the output
@@ -6446,12 +7271,12 @@ the fix may be to run &latex; again.
<screen><literal>\nocite{<replaceable>keys</replaceable>}</literal>
</screen>
<para>Produces no output but writes <replaceable>keys</replaceable> to the auxiliary file
-<filename><replaceable>doc-filename</replaceable>.aux</filename>.
+<filename><replaceable>jobname</replaceable>.aux</filename> (see <link linkend="Jobname">Jobname</link>).
</para>
<para>The mandatory argument <replaceable>keys</replaceable> is a comma-separated list of one or
more citation keys (see <link linkend="_005cbibitem">\bibitem</link>). This information is used by
Bib&tex; to include these works in your reference list even though you
-have not cited them (see <link linkend="_005ccite">\cite</link>).
+have not explicitly cited them (see <link linkend="_005ccite">\cite</link>).
</para>
</sect2>
@@ -6467,7 +7292,7 @@ have not cited them (see <link linkend="_005ccite">\cite</link>).
<para>As described in <literal>thebibliography</literal> (see <link linkend="thebibliography">thebibliography</link>), a
sophisticated approach to managing bibliographies is provided by the
Bib&tex; program. This is only an introduction; see the full
-documentation on CTAN.
+documentation on CTAN (see <link linkend="CTAN">CTAN</link>).
</para>
<para>With Bib&tex;, you don&#8217;t use <literal>thebibliography</literal>
(see <link linkend="thebibliography">thebibliography</link>). Instead, include these lines.
@@ -6492,7 +7317,7 @@ Sort the bibliographic items alphabetically.
</para></listitem></varlistentry></variablelist>
<para>Many, many other Bib&tex; style files exist,
tailored to the demands of various publications. See CTAN&#8217;s listing
-<ulink url="http://mirror.ctan.org/biblio/bibtex/contrib">http://mirror.ctan.org/biblio/bibtex/contrib</ulink>.
+<ulink url="https://mirror.ctan.org/biblio/bibtex/contrib">https://mirror.ctan.org/biblio/bibtex/contrib</ulink>.
</para>
<para>The <literal>\bibliography</literal> command is what actually produces the
bibliography. Its argument is a comma-separated list, referring to
@@ -6651,8 +7476,13 @@ the string <literal>\end{verbatim}</literal>.
<para>You cannot use the verbatim environment in the argument to macros, for
instance in the argument to a <literal>\section</literal>. This is not the same as
-commands being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot appear
-there. (But the <literal>cprotect</literal> package can help with this.)
+commands being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot work,
+as the <literal>verbatim</literal> environment changes the catcode regime before
+processing its contents, and restore it immediately afterward,
+nevertheless with a macro argument the content of the argument has
+already be converted to a token list along the catcode regime in effect
+when the macro was called. However, the <literal>cprotect</literal> package can
+help with this.
</para>
<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm>
@@ -6675,7 +7505,7 @@ and <literal>minted</literal>.
<para>A package that provides many more options for verbatim environments is
<literal>fancyvrb</literal>. Another is <literal>verbatimbox</literal>.
</para>
-<para>For a list of all the relevant packages, see CTAN.
+<para>For a list of all the relevant packages, see CTAN (see <link linkend="CTAN">CTAN</link>).
</para>
@@ -6703,27 +7533,28 @@ exclamation point, <literal>!</literal>. The second instead uses plus, <literal
because the exclamation point is part of <literal>literal-text</literal>.
</para>
<para>The single-character delimiter <replaceable>char</replaceable> surrounds
-<replaceable>literal-text</replaceable>&#160;&#8212; it must be the same character before and
-after. No spaces come between <literal>\verb</literal> or <literal>\verb*</literal> and
-<replaceable>char</replaceable>, or between <replaceable>char</replaceable> and <replaceable>literal-text</replaceable>, or between
-<replaceable>literal-text</replaceable> and the second occurrence of <replaceable>char</replaceable> (the synopsis
-shows a space only to distinguish one component from the other). The
-delimiter must not appear in <replaceable>literal-text</replaceable>. The <replaceable>literal-text</replaceable>
-cannot include a line break.
+<replaceable>literal-text</replaceable>&#8212;it must be the same character before and after.
+No spaces come between <literal>\verb</literal> or <literal>\verb*</literal> and <replaceable>char</replaceable>,
+or between <replaceable>char</replaceable> and <replaceable>literal-text</replaceable>, or between
+<replaceable>literal-text</replaceable> and the second occurrence of <replaceable>char</replaceable> (the
+synopsis shows a space only to distinguish one component from the
+other). The delimiter must not appear in <replaceable>literal-text</replaceable>. The
+<replaceable>literal-text</replaceable> cannot include a line break.
</para>
<indexterm role="cp"><primary>visible space</primary></indexterm>
<para>The <literal>*</literal>-form differs only in that spaces are printed with a visible
space character.
</para>
-<para>The output from this will include a character showing the spaces.
+<para>The output from this will include a visible space on both side of word
+&#8216;<literal>with</literal>&#8217;:
</para>
-<screen>The commands's first argument is \verb*!filename with extension! and ...
+<screen>The command's first argument is \verb*!filename with extension! and ...
</screen>
<indexterm role="cp"><primary>package, <literal>url</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>url</literal> package</primary></indexterm>
<para>For typesetting Internet addresses, urls, the package <literal>url</literal>
-provides an option that is better than the <literal>\verb</literal> command, since
+is a better option than the <literal>\verb</literal> command, since
it allows line breaks.
</para>
<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm>
@@ -6740,8 +7571,12 @@ it allows line breaks.
<para>You cannot use <literal>\verb</literal> in the argument to a macro, for instance in
the argument to a <literal>\section</literal>. It is not a question of <literal>\verb</literal>
-being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot appear there.
-(But the <literal>cprotect</literal> package can help with this.)
+being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot work, as the
+<literal>\verb</literal> command changes the catcode regime before reading its
+argument, and restore it immediately afterward, nevertheless with a
+macro argument the content of the argument has already be converted to a
+token list along the catcode regime in effect when the macro was called.
+However, the <literal>cprotect</literal> package can help with this.
</para>
</sect2>
@@ -6899,8 +7734,8 @@ internally) the same as <literal>\\</literal>, followed by <literal>\relax</lite
new line in the input will also be a new line in the output. The
<literal>\restorecr</literal> command restores normal line-breaking behavior.
</para>
-<para>This is not the way to show verbatim text or computer code.
-See <link linkend="verbatim">verbatim</link> instead.
+<para>This is not the way to show verbatim text or computer code. Use
+<literal>verbatim</literal> (see <link linkend="verbatim">verbatim</link>) instead.
</para>
<para>With &latex;&#8217;s usual defaults, this
</para>
@@ -7143,7 +7978,7 @@ underrepresented groups.
</screen>
<para>When you issue <literal>\linebreak</literal>, the spaces in the line are stretched
out so that it extends to the right margin. See <link linkend="_005c_005c">\\</link>
-and&#160;<link linkend="_005cnewline">\newline</link> to have the spaces not stretched out.
+and&#160;<link linkend="_005cnewline">\newline</link>, to have the spaces not stretched out.
</para>
@@ -7183,7 +8018,7 @@ second one is lousy; to break the current page &latex; doesn&#8217;t look as
far ahead as the next page break. So occasionally you may want to
influence page breaks while preparing a final version of a document.
</para>
-<para>See <link linkend="Layout">Layout</link> for more material that is relevant to page breaking.
+<para>See <link linkend="Layout">Layout</link>, for more material that is relevant to page breaking.
</para>
@@ -7272,7 +8107,7 @@ continent,
\noindent a new nation, conceived in Liberty, and dedicated to the
proposition that all men are created equal.
</screen>
-<para>makes a new page start after &#8216;<literal>continent,</literal>&#8217; and the cut-off line is
+<para>makes a new page start after &#8216;<literal>continent</literal>&#8217;, and the cut-off line is
not right justified. In addition, <literal>\newpage</literal> does not vertically
stretch out the page, as <literal>\pagebreak</literal> does.
</para>
@@ -7347,13 +8182,13 @@ continent,
a new nation, conceived in Liberty, and dedicated to the proposition
that all men are created equal.
</screen>
-<para>does not give a page break at &#8216;<literal>continent,</literal>&#8217; but instead at
-&#8216;<literal>nation,</literal>&#8217; since that is where &latex; breaks that line. In
+<para>does not give a page break at &#8216;<literal>continent</literal>&#8217;, but instead at
+&#8216;<literal>nation</literal>&#8217;, since that is where &latex; breaks that line. In
addition, with <literal>\pagebreak</literal> the vertical space on the page is
stretched out where possible so that it extends to the normal bottom
margin. This can look strange, and if <literal>\flushbottom</literal> is in effect
this can cause you to get &#8216;<literal>Underfull \vbox (badness 10000) has
-occurred while \output is active</literal>&#8217;. See <link linkend="_005cnewpage">\newpage</link> for a command that
+occurred while \output is active</literal>&#8217;. See <link linkend="_005cnewpage">\newpage</link>, for a command that
does not have these effects.
</para>
@@ -7452,7 +8287,7 @@ sectioning command such as <literal>\chapter</literal> (it can only be used in o
paragraph mode; see <link linkend="Modes">Modes</link>). There are some workarounds; see
following sections.
</para>
-<indexterm role="cp"><primary>Footnotes, in a minipage</primary></indexterm>
+<indexterm role="cp"><primary>footnotes, in a minipage</primary></indexterm>
<indexterm role="cp"><primary>mpfootnote counter</primary></indexterm>
<para>In a <literal>minipage</literal> environment the <literal>\footnote</literal> command uses the
<literal>mpfootnote</literal> counter instead of the <literal>footnote</literal> counter, so
@@ -7549,7 +8384,7 @@ that command, but must appear in outer paragraph mode (see <link linkend="Modes"
The optional argument <replaceable>number</replaceable> changes the number of the footnote
mark.
</para>
-<para>See <link linkend="_005cfootnotemark">\footnotemark</link> and&#160;<link linkend="Footnotes-in-a-table">Footnotes in a table</link> for usage
+<para>See <link linkend="_005cfootnotemark">\footnotemark</link> and&#160;<link linkend="Footnotes-in-a-table">Footnotes in a table</link>, for usage
examples.
</para>
@@ -7712,13 +8547,16 @@ second.\footnotefrom{%
\renewcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>}
\renewcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>}
</screen>
-<para>Define or redefine a command. See also the discussion of
-<literal>\DeclareRobustCommand</literal> in <link linkend="Class-and-package-commands">Class and package commands</link>.
+<para>Define or redefine a command (see also the discussion of
+<literal>\DeclareRobustCommand</literal> in <link linkend="Class-and-package-commands">Class and package commands</link>).
+</para>
<indexterm role="cp"><primary>starred form, defining new commands</primary></indexterm>
<indexterm role="cp"><primary>*-form, defining new commands</primary></indexterm>
-The starred form of these two requires that the arguments not contain
-multiple paragraphs of text (in plain &tex; terms that it not be
-<literal>\long</literal>).
+<indexterm role="fn"><primary>\long</primary></indexterm>
+<para>The starred form of these two forbids the arguments from containing
+multiple paragraphs of text (in plain &tex; terms, the commands
+are not <literal>\long</literal>). With the default form, arguments can be
+multiple paragraphs.
</para>
<para>These are the parameters:
</para>
@@ -7739,8 +8577,8 @@ different number of arguments than the old version.
</listitem></varlistentry><varlistentry><term><replaceable>optargdefault</replaceable>
</term><listitem><para>Optional; if this argument is present then the first argument of
<literal>\<replaceable>cmd</replaceable></literal> is optional, with default value <replaceable>optargdefault</replaceable>
-(which may be the empty string). If this argument is not present then
-<literal>\<replaceable>cmd</replaceable></literal> does not take an optional argument.
+(which may be the empty string). If <replaceable>optargsdefault</replaceable> is not present
+then <literal>\<replaceable>cmd</replaceable></literal> does not take an optional argument.
</para>
<indexterm role="cp"><primary>positional parameter</primary></indexterm>
<para>That is, if <literal>\<replaceable>cmd</replaceable></literal> is used with square brackets, as in
@@ -7849,13 +8687,13 @@ If no command of this name already exists then this has the same effect
as <literal>\newcommand</literal>. If a command of this name already exists then
this definition does nothing. This is particularly useful in a file
that may be loaded more than once, such as a style file.
-See <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link> for the description of the arguments.
+See <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>, for the description of the arguments.
</para>
<para>This example
</para>
<screen>\providecommand{\myaffiliation}{Saint Michael's College}
\providecommand{\myaffiliation}{Saint Michael's College}
-From \myaffiliation.
+&gt;From \myaffiliation.
</screen>
<para>outputs &#8216;<literal>From Saint Michael's College</literal>&#8217;. Unlike <literal>\newcommand</literal>,
the repeated use of <literal>\providecommand</literal> does not give an error.
@@ -7894,19 +8732,19 @@ or class writers. The convention prevents authors who are just using a
package or class from accidentally replacing such a command with one of
their own, because by default the at-sign has catcode&#160;12.
</para>
-<para>The pair <literal>\makeatletter</literal> and <literal>\makeatother</literal> changes the
-default code and then changes it back. Use them inside a <filename>.tex</filename>
-file, in the preamble, when you are defining or redefining commands
-named with <literal>@</literal>, by having them surround your definition. Don&#8217;t
-use these inside <filename>.sty</filename> or <filename>.cls</filename> files since the
-<literal>\usepackage</literal> and <literal>\documentclass</literal> commands already arrange
-that the at-sign has the character code of a letter, catcode&#160;11.
+<para>Use the pair <literal>\makeatletter</literal> and <literal>\makeatother</literal> inside a
+<filename>.tex</filename> file, typically in the preamble, when you are defining or
+redefining commands named with <literal>@</literal>, by having them surround your
+definition. Don&#8217;t use these inside <filename>.sty</filename> or <filename>.cls</filename> files
+since the <literal>\usepackage</literal> and <literal>\documentclass</literal> commands already
+arrange that the at-sign has the character code of a letter,
+catcode&#160;11.
</para>
<indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>macros2e</literal> package</primary></indexterm>
<para>For a comprehensive list of macros with an at-sign in their names see
-<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>.
+<ulink url="https://ctan.org/pkg/macros2e">https://ctan.org/pkg/macros2e</ulink>.
</para>
<para>In this example the class file has a command
<literal>\thesis@universityname</literal> that the user wants to change. These
@@ -7939,27 +8777,33 @@ Examples are the <literal>table</literal> and <literal>table*</literal> environm
</para>
<para>When defining environments, following this pattern is straightforward
because <literal>\newenvironment</literal> and <literal>\renewenvironment</literal> allow the
-environment name to contain a star. For commands the situation is more
-complex. As in the synopsis above, there will be a user-called command,
-given above as <literal>\mycmd</literal>, which peeks ahead to see if it is followed
-by a star. For instance, &latex; does not really have a
-<literal>\section*</literal> command; instead, the <literal>\section</literal> command peeks
-ahead. This command does not accept arguments but instead expands to
-one of two commands that do accept arguments. In the synopsis these two
-are <literal>\mycmd@nostar</literal> and <literal>\mycmd@star</literal>. They could take the
-same number of arguments or a different number, or no arguments at all.
-As always, in a &latex; document a command using at-sign&#160;<literal>@</literal>
-must be enclosed inside a <literal>\makeatletter ... \makeatother</literal> block
+environment name to contain a star. So you just have to write
+<literal>\newenvironment{<replaceable>myenv</replaceable>}</literal> or
+<literal>\newenvironment{<replaceable>myenv</replaceable>*}</literal> and continue the definition as
+usual. For commands the situation is more complex as the star not being
+a letter cannot be part of the command name. As in the synopsis above,
+there will be a user-called command, given above as <literal>\mycmd</literal>, which
+peeks ahead to see if it is followed by a star. For instance, &latex;
+does not really have a <literal>\section*</literal> command; instead, the
+<literal>\section</literal> command peeks ahead. This command does not accept
+arguments but instead expands to one of two commands that do accept
+arguments. In the synopsis these two are <literal>\mycmd@nostar</literal> and
+<literal>\mycmd@star</literal>. They could take the same number of arguments or a
+different number, or no arguments at all. As always, in a &latex;
+document a command using an at-sign&#160;<literal>@</literal> in its name must be
+enclosed inside a <literal>\makeatletter ... \makeatother</literal> block
(see <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>).
</para>
<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a
variant <literal>\ciel*</literal>. Both have one required argument. A call to
-<literal>\ciel{night}</literal> will return &quot;starry night sky&quot; while
-<literal>\ciel*{blue}</literal> will return &quot;starry not blue sky&quot;.
+<literal>\ciel{blue}</literal> will return &quot;not starry blue sky&quot; while
+<literal>\ciel*{night}</literal> will return &quot;starry night sky&quot;.
</para>
-<screen>\newcommand*{\ciel@unstarred}[1]{starry #1 sky}
-\newcommand*{\ciel@starred}[1]{starry not #1 sky}
+<screen>\makeatletter
+\newcommand*{\ciel@unstarred}[1]{not starry #1 sky}
+\newcommand*{\ciel@starred}[1]{starry #1 sky}
\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}
+\makeatother
</screen>
<para>In the next example, the starred variant takes a different number of
arguments than the unstarred one. With this definition, Agent 007&#8217;s
@@ -7972,15 +8816,31 @@ arguments than the unstarred one. With this definition, Agent 007&#8217;s
\newcommand*{\agentsecret}{%
\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
</screen>
-<para>There are two sometimes more convenient ways to accomplish the work of
-<literal>\@ifstar</literal>. The <filename>suffix</filename> package allows the construct
-<literal>\newcommand\mycommand{<replaceable>unstarred version</replaceable>}</literal> followed by
-<literal>\WithSuffix\newcommand\mycommand*{<replaceable>starred version</replaceable>}</literal>. And
-&latex;3 has the <filename>xparse</filename> package that allows this code.
+<para>After a command name, a star is handled similarly to an optional
+argument. (This differs from environment names in which the star is
+part of the name itself and as such could be in any position.) Thus,
+it is technically possible to put any number of spaces between the
+command and the star. Thus <literal>\agentsecret*{Bond}</literal> and
+<literal>\agentsecret *<!-- /@w -->{Bond}</literal> are equivalent. However, the
+standard practice is not to insert any such spaces.
+</para>
+<indexterm role="cp"><primary>package, <literal>suffix</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>suffix</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>xparse</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>xparse</literal> package</primary></indexterm>
+
+<para>There are two alternative ways to accomplish the work of
+<literal>\@ifstar</literal>. (1)&#160;The <filename>suffix</filename> package allows the
+construct <literal>\newcommand\mycommand{<replaceable>unstarred-variant</replaceable>}</literal>
+followed by
+<literal>\WithSuffix\newcommand\mycommand*{<replaceable>starred-variant</replaceable>}</literal>.
+(2)&#160;&latex; provides the <filename>xparse</filename> package, which allows
+this code:
</para>
<screen>\NewDocumentCommand\foo{s}{\IfBooleanTF#1
- {<replaceable>starred version</replaceable>}%
- {<replaceable>unstarred version</replaceable>}%
+ {<replaceable>starred-variant</replaceable>}%
+ {<replaceable>unstarred-variant</replaceable>}%
}
</screen>
@@ -8493,7 +9353,7 @@ to <literal>\protect\(..\protect\)</literal>.
</screen>
<para>Both commands cause &latex; to ignore spaces after the end of the
command up until the first non-space character. The first is a command
-from Plain &tex;, and the second is &latex;-specific.
+from plain &tex;, and the second is &latex;-specific.
</para>
<para>The <literal>ignorespaces</literal> is often used when defining commands via
<literal>\newcommand</literal>, or <literal>\newenvironment</literal>, or <literal>\def</literal>. The
@@ -8518,21 +9378,20 @@ commands below allow a user to uniformly attach a title to names. But,
as given, if a title accidentally starts with a space then
<literal>\fullname</literal> will reproduce that.
</para>
-<screen>\makeatletter
-\newcommand{\honorific}[1]{\def\@honorific{#1}} % remember title
-\newcommand{\fullname}[1]{\@honorific~#1} % put title before name
-\makeatother
+<screen>\newcommand{\honorific}[1]{\def\honorific{#1}} % remember title
+\newcommand{\fullname}[1]{\honorific~#1} % put title before name
+
\begin{tabular}{|l|}
\honorific{Mr/Ms} \fullname{Jones} \\ % no extra space here
\honorific{ Mr/Ms} \fullname{Jones} % extra space before title
\end{tabular}
</screen>
<para>To fix this, change to
-<literal>\newcommand{\fullname}[1]{\ignorespaces\@honorific~#1}</literal>.
+<literal>\newcommand{\fullname}[1]{\ignorespaces\honorific~#1}</literal>.
</para>
<para>The <literal>\ignorespaces</literal> is also often used in a <literal>\newenvironment</literal>
-at the end of the <replaceable>begin</replaceable> clause, that is, as part of the second
-argument, as in <literal>\begin{newenvironment}{<replaceable>env
+at the end of the <replaceable>begin</replaceable> clause, as in
+<literal>\begin{newenvironment}{<replaceable>env
name</replaceable>}{... \ignorespaces}{...}</literal>.
</para>
<para>To strip spaces off the end of an environment use
@@ -8558,6 +9417,61 @@ inconvenient. The solution is to change to
</para>
</sect1>
+<sect1 label="12.13" id="xspace-package">
+<title>xspace package</title>
+
+<indexterm role="fn"><primary>\xspace</primary></indexterm>
+<indexterm role="cp"><primary>spaces, ignore around commands</primary></indexterm>
+<indexterm role="cp"><primary>commands, ignore spaces</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\usepackage{xspace}
+ ...
+\newcommand{...}{...\xspace}
+</screen>
+<para>The <literal>\xspace</literal> macro, when used at the end of a command, adds a
+space unless the command is followed by certain punctuation characters.
+</para>
+<para>After a command name that uses letters (as opposed to single character
+command names using non-letters such as <literal>\$</literal>), &tex; gobbles white
+space. Thus, in the first sentence below, the output has &#8216;<literal>Vermont</literal>&#8217;
+placed snugly against the period, without any intervening space.
+</para>
+<screen>\newcommand{\VT}{Vermont}
+Our college is in \VT .
+The \VT{} summers are nice.
+</screen>
+<para>But because of the gobbling, the second sentence needs the dummy curly
+braces or else there would be no space separating &#8216;<literal>Vermont</literal>&#8217; from
+&#8216;<literal>summers</literal>&#8217;. (Many authors instead instead use a backslash-space
+<literal>\ </literal> for this. See <link linkend="_005c_0028SPACE_0029">\(SPACE)</link>.)
+</para>
+<para>The <filename>xspace</filename> package provides <literal>\xspace</literal>. It is for writing
+commands which are designed to be used mainly in text. It inserts a
+space after that command unless what immediately follows is in a list of
+exceptions. In this example, the dummy braces are not needed.
+</para>
+<screen>\newcommand{\VT}{Vermont\xspace}
+Our college is in \VT .
+\VT summers are nice.
+</screen>
+<para>The default exception list contains the characters <literal>,.'/?;:!~-)</literal>,
+the open curly brace and the backslash-space command discussed above,
+and the commands <literal>\footnote</literal> or <literal>\footnotemark</literal>. Add to that
+list as with <literal>\xspaceaddexceptions{\myfni \myfnii}</literal> and remove
+from that list as with <literal>\xspaceremoveexception{!}</literal>.
+</para>
+<!-- David Carlisle https://tex.stackexchange.com/a/86620/339 -->
+<para>A comment: many experts prefer not to use <literal>\xspace</literal>. Putting it in
+a definition means that the command will usually get the spacing right.
+But it isn&#8217;t easy to predict when to enter dummy braces because
+<literal>\xspace</literal> will get it wrong, such as when it is followed by another
+command, and so <literal>\xspace</literal> can make editing material harder and more
+error-prone than instead always remembering the dummy braces.
+</para>
+
+</sect1>
</chapter>
<chapter label="13" id="Counters">
<title>Counters</title>
@@ -8756,7 +9670,8 @@ Here it is in Roman: \Roman{exercise}.
<para>Synopsis:
</para>
-<screen>\addtocounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>&#160;</screen>
+<screen>\addtocounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>}
+</screen>
<para>Globally increment <replaceable>counter</replaceable> by the amount specified by the
<replaceable>value</replaceable> argument, which may be negative.
</para>
@@ -8804,7 +9719,7 @@ within it. (For the definition of &#8220;counters numbered within&#8221;,
see <link linkend="_005cnewcounter">\newcounter</link>.)
</para>
<para>This command differs from <literal>\refstepcounter</literal> in that this one does
-not influence references&#160;&#8212; it does not define the current
+not influence references; that is, it does not define the current
<literal>\ref</literal> value to be the result of <literal>\thecounter</literal>
(see <link linkend="_005crefstepcounter">\refstepcounter</link>).
</para>
@@ -8844,14 +9759,20 @@ bogus month value produces no output).
<para>A <firstterm>length</firstterm> is a measure of distance. Many &latex; commands take a
length as an argument.
</para>
+<indexterm role="cp"><primary>rigid lengths</primary></indexterm>
+<indexterm role="cp"><primary>rubber lengths</primary></indexterm>
+<indexterm role="cp"><primary>dimen plain &tex;</primary></indexterm>
+<indexterm role="cp"><primary>skip plain &tex;</primary></indexterm>
+<indexterm role="cp"><primary>glue plain &tex;</primary></indexterm>
<para>Lengths come in two types. A <firstterm>rigid length</firstterm> such as <literal>10pt</literal>
-does not contain a <literal>plus</literal> or <literal>minus</literal> component. (Plain &tex;
-calls this a <firstterm>dimen</firstterm>.) A <firstterm>rubber length</firstterm> (what Plain &tex;
-calls a <firstterm>skip</firstterm>) such as as with <literal>1cm plus0.05cm minus0.01cm</literal>
-can contain either or both of those components. In that rubber length,
-the <literal>1cm</literal> is the <firstterm>natural length</firstterm> while the other two, the
-<literal>plus</literal> and <literal>minus</literal> components, allow &tex; to stretch or
-shrink the length to optimize placement.
+does not contain a <literal>plus</literal> or <literal>minus</literal> component. (Plain
+&tex; calls this a <firstterm>dimen</firstterm>.) A <firstterm>rubber length</firstterm> (what plain
+&tex; calls a <firstterm>skip</firstterm> or <firstterm>glue</firstterm>) such as with <literal>1cm
+plus0.05cm minus0.01cm</literal> can contain either or both of those
+components. In that rubber length, the <literal>1cm</literal> is the <firstterm>natural
+length</firstterm> while the other two, the <literal>plus</literal> and <literal>minus</literal>
+components, allow &tex; to stretch or shrink the length to optimize
+placement.
</para>
<para>The illustrations below use these two commands.
</para>
@@ -8951,9 +9872,9 @@ math mode.
</para>
<variablelist><varlistentry><term><literal>pt</literal>
</term><listitem><indexterm role="fn"><primary>pt</primary></indexterm>
-<indexterm role="cp"><primary>Point</primary></indexterm>
-<anchor id="units-of-length-pt"/><para>Point, 1/72.27 inch. The conversion to metric units, to two decimal
-places, is 1point = 2.85mm = 28.45cm.
+<indexterm role="cp"><primary>point</primary></indexterm>
+<anchor id="units-of-length-pt"/><para>Point, 1/72.27 inch. The conversion to metric units
+is 1point = 2.845mm = .2845cm.
</para>
</listitem></varlistentry><varlistentry><term><literal>pc</literal>
</term><listitem><indexterm role="cp"><primary>pica</primary></indexterm>
@@ -8967,32 +9888,32 @@ places, is 1point = 2.85mm = 28.45cm.
</para>
</listitem></varlistentry><varlistentry><term><literal>bp</literal>
</term><listitem><indexterm role="fn"><primary>bp</primary></indexterm>
-<indexterm role="cp"><primary>Big point</primary></indexterm>
+<indexterm role="cp"><primary>big point</primary></indexterm>
<anchor id="units-of-length-bp"/><para>Big point, 1/72 inch. This length is the definition of a point in
PostScript and many desktop publishing systems.
</para>
</listitem></varlistentry><varlistentry><term><literal>cm</literal>
-</term><listitem><indexterm role="cp"><primary>Centimeter</primary></indexterm>
+</term><listitem><indexterm role="cp"><primary>centimeter</primary></indexterm>
<indexterm role="fn"><primary>cm</primary></indexterm>
<anchor id="units-of-length-cm"/><para>Centimeter
</para>
</listitem></varlistentry><varlistentry><term><literal>mm</literal>
-</term><listitem><indexterm role="cp"><primary>Millimeter</primary></indexterm>
+</term><listitem><indexterm role="cp"><primary>millimeter</primary></indexterm>
<indexterm role="fn"><primary>mm</primary></indexterm>
<anchor id="units-of-length-mm"/><para>Millimeter
</para>
</listitem></varlistentry><varlistentry><term><literal>dd</literal>
-</term><listitem><indexterm role="cp"><primary>Didot point</primary></indexterm>
+</term><listitem><indexterm role="cp"><primary>didot point</primary></indexterm>
<indexterm role="fn"><primary>dd</primary></indexterm>
<anchor id="units-of-length-dd"/><para>Didot point, 1.07 pt
</para>
</listitem></varlistentry><varlistentry><term><literal>cc</literal>
-</term><listitem><indexterm role="cp"><primary>Cicero</primary></indexterm>
+</term><listitem><indexterm role="cp"><primary>cicero</primary></indexterm>
<indexterm role="fn"><primary>cc</primary></indexterm>
<anchor id="units-of-length-cc"/><para>Cicero, 12 dd
</para>
</listitem></varlistentry><varlistentry><term><literal>sp</literal>
-</term><listitem><indexterm role="cp"><primary>Scaled point</primary></indexterm>
+</term><listitem><indexterm role="cp"><primary>scaled point</primary></indexterm>
<indexterm role="fn"><primary>sp</primary></indexterm>
<anchor id="units-of-length-sp"/><para>Scaled point, 1/65536 pt
</para>
@@ -9177,6 +10098,153 @@ then you get something like &#8216;<literal>Undefined control sequence. &lt;argu
</para>
</sect1>
+<sect1 label="14.7" id="_005cstretch">
+<title><literal>\stretch</literal></title>
+
+<indexterm role="fn"><primary>\stretch</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\stretch{<replaceable>number</replaceable>}
+</screen>
+<para>Produces a rubber length with zero natural length and <replaceable>number</replaceable> times
+<literal>\fill</literal> units of stretchability (see <link linkend="Lengths">Lengths</link>). The
+<replaceable>number</replaceable> can be positive or negative. This command is robust
+(see <link linkend="_005cprotect">\protect</link>).
+</para>
+<para>It works for both vertical and horizontal spacing. In this horizontal
+example, &latex; produces three tick marks, and the distance between
+the first and second is half again as long as the distance between the
+second and third.
+</para>
+<screen>\rule{0.4pt}{1ex}\hspace{\stretch{1.5}}%
+ \rule{0.4pt}{1ex}\hspace{\stretch{1}}%
+ \rule{0.4pt}{1ex}
+</screen>
+<para>In this vertical example, the &#8216;<literal>We dedicate &#8230;</literal>&#8217; will have three
+times as much space under it as above it.
+</para>
+<screen>\newenvironment{dedication}{% in document preamble
+ \clearpage\thispagestyle{empty}%
+ \vspace*{\stretch{1}} % stretchable space at top
+ \it
+}{%
+ \vspace{\stretch{3}} % space at bot is 3x as at top
+ \clearpage
+}
+ ...
+\begin{dedication} % in document body
+We dedicate this book to our wives.
+\end{dedication}
+</screen>
+
+</sect1>
+<sect1 label="14.8" id="Expressions">
+<title>Expressions</title>
+
+<indexterm role="fn"><primary>expressions</primary></indexterm>
+
+<!-- Much from Joseph Wright's https://tex.stackexchange.com/a/245663/339 -->
+<para>Synopsis, one of:
+</para>
+<screen>\numexpr <replaceable>expression</replaceable>
+\dimexpr <replaceable>expression</replaceable>
+\glueexpr <replaceable>expression</replaceable>
+\muglue <replaceable>expression</replaceable>
+</screen>
+<para>Any place where you may write an integer, or a &tex; dimen, or &tex;
+glue, or muglue, you can instead write an expression to compute that
+type of quantity.
+</para>
+<para>An example is that <literal>\the\dimexpr\linewidth-4pt\relax</literal> will
+produce as output the length that is four points less than width of a
+line (the only purpose of <literal>\the</literal> is to show the result in the
+document). Analogously, <literal>\romannumeral\numexpr6+3\relax</literal> will
+produce &#8216;<literal>ix</literal>&#8217;, and <literal>\the\glueexpr 5pt plus 1pt * 2 \relax</literal>
+will produce &#8216;<literal>10.0pt plus 2.0pt</literal>&#8217;.
+</para>
+<para>A convenience here over doing calculations by allocating registers and
+then using <literal>\advance</literal>, etc., is that the evaluation of expressions
+does not involve assignments and can therefore be performed in places
+where assignments are not allowed. The next example computes the width
+of the <literal>\parbox</literal>.
+</para>
+<screen>\newlength{\offset}\setlength{\offset}{2em}
+\begin{center}
+\parbox{\dimexpr\linewidth-\offset*3}{With malice toward none
+with charity for all with firmness in the right as God gives us to see
+the right let us strive on to finish the work we are in to bind up the
+nation's wounds, to care for him who shall have borne the battle and
+for his widow and his orphan \textasciitilde\ to do all which may
+achieve and cherish a just and lasting peace among ourselves and with
+all nations. ---Abraham Lincoln, Second Inaugural Address, from the
+memorial}
+\end{center}
+</screen>
+<para>The <replaceable>expression</replaceable> consists of one or more terms of the same type
+(integer, dimension, etc.) that are added or subtracted. A term that is
+a type of number, dimension, etc., consists of a factor of that type,
+optionally multiplied or divided by factors. A factor of a type is
+either a quantity of that type or a parenthesized subexpression. The
+expression produces a result of the given type, so that <literal>\numexpr</literal>
+produces an integer, <literal>\dimexpr</literal> produces a dimension, etc.
+</para>
+<para>In the quotation example above, changing to
+<literal>\dimexpr\linewidth-3*\offset</literal> gives the error <literal>Illegal unit
+of measure (pt inserted)</literal>. This is because for <literal>\dimexpr</literal> and
+<literal>\glueexpr</literal>, the input consists of a dimension or glue value
+followed by an optional multiplication factor, and not the other way
+around. Thus <literal>\the\dimexpr 1pt*10\relax</literal> is valid and produces
+&#8216;<literal>10.0pt</literal>&#8217;, but <literal>\the\dimexpr 10*1pt\relax</literal> gives the
+<literal>Illegal unit</literal> error.
+</para>
+<para>The expressions absorb tokens and carry out appropriate mathematics up
+to a <literal>\relax</literal> (which will be absorbed), or up to the first
+non-valid token. Thus, <literal>\the\numexpr2+3px</literal> will print
+&#8216;<literal>5px</literal>&#8217;, because &latex; reads the <literal>\numexpr2+3</literal>, which is
+made up of numbers, and then finds the letter <literal>p</literal>, which cannot
+be part of a number. It therefore terminates the expression and
+produces the &#8216;<literal>5</literal>&#8217;, followed by the regular text &#8216;<literal>px</literal>&#8217;.
+</para>
+<para>This termination behavior is useful in comparisons. In
+<literal>\ifnum\numexpr\parindent*2 &lt; 10pt Yes\else No\fi</literal>, the less than
+sign terminates the expression and the result is &#8216;<literal>No</literal>&#8217; (in a
+standard &latex; article).
+</para>
+<para>Expressions may use the operators <literal>+</literal>, <literal>-</literal>, <literal>*</literal> and
+<literal>/</literal> along with parentheses for subexpressions, <literal>(...)</literal>. In
+glue expressions the <literal>plus</literal> and <literal>minus</literal> parts do not need
+parentheses to be affected by a factor. So <literal>\the\glueexpr 5pt plus
+1pt * 2 \relax</literal> results in &#8216;<literal>10pt plus 2pt</literal>&#8217;.
+</para>
+<para>&tex; will coerce other numerical types in the same way as it does when
+doing register assignment. Thus <literal>\the\numexpr\dimexpr
+1pt\relax\relax</literal> will result in &#8216;<literal>65536</literal>&#8217;, which is <literal>1pt</literal>
+converted to scaled points (&tex;&#8217;s internal unit) and then coerced
+into an integer. With a <literal>\glueexpr</literal> here, the stretch and shrink
+would be dropped. Going the other way, a <literal>\numexpr</literal> inside a
+<literal>\dimexpr</literal> or <literal>\glueexpr</literal> will need appropriate units, as in
+<literal>\the\dimexpr\numexpr 1 + 2\relax pt\relax</literal>, which produces
+&#8216;<literal>3.0pt</literal>&#8217;.
+</para>
+<para>The details of the arithmetic: each factor is checked to be in the
+allowed range, numbers must be less than <inlineequation><mathphrase>2^{31}</mathphrase></inlineequation> in absolute
+value, and dimensions or glue components must be less than
+<inlineequation><mathphrase>2^{14}</mathphrase></inlineequation> points, or <literal>mu</literal>, or <literal>fil</literal>, etc. The
+arithmetic operations are performed individually, except for a scaling
+operation (a multiplication immediately followed by a division) which
+is done as one combined operation with a 64-bit product as
+intermediate value. The result of each operation is again checked to
+be in the allowed range.
+</para>
+<para>Finally, division and scaling take place with rounding (unlike &tex;&#8217;s
+<literal>\divide</literal>, which truncates). Thus
+<literal>\the\dimexpr 5pt*(3/2)\relax</literal> puts &#8216;<literal>10.0pt</literal>&#8217; in the document,
+because it rounds <literal>3/2</literal> to <literal>2</literal>, while
+<literal>\the\dimexpr 5pt*(4/3)\relax</literal> produces &#8216;<literal>5.0pt</literal>&#8217;.
+</para>
+
+</sect1>
</chapter>
<chapter label="15" id="Making-paragraphs">
<title>Making paragraphs</title>
@@ -9307,7 +10375,7 @@ first outputs an empty box whose width is <literal>\parindent</literal>. These
commands are robust (see <link linkend="_005cprotect">\protect</link>).
</para>
<para>Ordinarily you create a new paragraph by putting in a blank line.
-See <link linkend="_005cpar">\par</link> for the difference between this command and <literal>\par</literal>. To
+See <link linkend="_005cpar">\par</link>, for the difference between this command and <literal>\par</literal>. To
start a paragraph without an indent, or to continue an interrupted
paragraph, use <literal>\noindent</literal>.
</para>
@@ -9351,32 +10419,38 @@ look on CTAN for the package <literal>indentfirst</literal>.
<indexterm role="fn"><primary>\parindent</primary></indexterm>
<indexterm role="fn"><primary>\parskip</primary></indexterm>
<indexterm role="cp"><primary>paragraph indentation</primary></indexterm>
+<indexterm role="cp"><primary>horizontal paragraph indentation</primary></indexterm>
<indexterm role="cp"><primary>vertical space before paragraphs</primary></indexterm>
<para>Synopsis:
</para>
-<screen>\setlength{\parskip}{<replaceable>horizontal len</replaceable>}
-\setlength{\parinden}{<replaceable>vertical len</replaceable>}
+<screen>\setlength{\parindent}{<replaceable>horizontal len</replaceable>}
+\setlength{\parskip}{<replaceable>vertical len</replaceable>}
</screen>
-<para>Both are a rubber lengths (see <link linkend="Lengths">Lengths</link>). They give the indentation
-of ordinary paragraphs, not paragraphs inside minipages
-(see <link linkend="minipage">minipage</link>), and the vertical space between paragraphs.
+<para>Both are rubber lengths (see <link linkend="Lengths">Lengths</link>). They affect the
+indentation of ordinary paragraphs, not paragraphs inside
+minipages (see <link linkend="minipage">minipage</link>), and the vertical space between
+paragraphs, respectively.
</para>
-<para>This, put in the preamble,
+<para>For example, if this is put in the preamble:
</para>
<screen>\setlength{\parindent}{0em}
\setlength{\parskip}{1ex}
</screen>
-<para>arranges that the document will have paragraphs that are not indented,
-but instead are vertically separated by about the height of a lowercase
-&#8216;<literal>x</literal>&#8217;.
+<para>The document will have paragraphs that are not indented, but instead
+are vertically separated by about the height of a lowercase &#8216;<literal>x</literal>&#8217;.
</para>
<para>In standard &latex; documents, the default value for <literal>\parindent</literal>
in one-column documents is <literal>15pt</literal> when the default text size is
-<literal>10pt</literal> , <literal>17pt</literal> for <literal>11pt</literal>, and <literal>1.5em</literal> for
-<literal>12pt</literal>. In two-column documents it is <literal>1em</literal>. The default
-value for <literal>\parskip</literal> in &latex;&#8217;s standard document styles is
-<literal>0pt plus1pt</literal>.
+<literal>10pt</literal>, <literal>17pt</literal> for <literal>11pt</literal>, and <literal>1.5em</literal> for
+<literal>12pt</literal>. In two-column documents it is <literal>1em</literal>. (These values
+are set before &latex; calls <literal>\normalfont</literal> so <literal>em</literal> is derived
+from the default font, Computer Modern. If you use a different font
+then to set <literal>\parindent</literal> in units matching that font, do
+<literal>\AtBeginDocument{\setlength{\parindent}{1em}}</literal>.)
+</para>
+<para>The default value for <literal>\parskip</literal> in &latex;&#8217;s standard document
+styles is <literal>0pt plus1pt</literal>.
</para>
</sect1>
@@ -9423,8 +10497,9 @@ hyphenation there by beginning <replaceable>left</replaceable> or <replaceable>r
<para>These parameters affect the formatting of the note:
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\marginparpush</primary></indexterm><literal>\marginparpush</literal>
-</term><listitem><anchor id="marginal-notes-marginparpush"/><para>Minimum vertical space between notes; default &#8216;<literal>7pt</literal>&#8217; for
-&#8216;<literal>12pt</literal>&#8217; documents, &#8216;<literal>5pt</literal>&#8217; else.
+</term><listitem><anchor id="marginal-notes-marginparpush"/><para>Minimum vertical space between notes; default &#8216;<literal>7pt</literal>&#8217; for &#8216;<literal>12pt</literal>&#8217;
+documents, &#8216;<literal>5pt</literal>&#8217; else. See also&#160;<link linkend="page-layout-parameters-marginparpush">page layout parameters
+marginparpush</link>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\marginparsep</primary></indexterm><literal>\marginparsep</literal>
</term><listitem><anchor id="marginal-notes-marginparsep"/><para>Horizontal space between the main text and the note; default
@@ -9568,9 +10643,9 @@ see their documentation on CTAN.
<indexterm role="cp"><primary>superscript</primary></indexterm>
<indexterm role="cp"><primary>subscript</primary></indexterm>
+<indexterm role="fn"><primary>^ superscript</primary></indexterm>
+<indexterm role="fn"><primary>_ subscript</primary></indexterm>
<indexterm role="cp"><primary>exponent</primary></indexterm>
-<indexterm role="fn"><primary>_</primary></indexterm>
-<indexterm role="fn"><primary>^</primary></indexterm>
<para>Synopsis (in math mode or display math mode), one of:
</para>
@@ -9625,7 +10700,7 @@ subscript.
subscript something to attach to and keeps it from accidentally
attaching to a prior symbols.
</para>
-<para>Using the subscript or superscript command outside of math mode or
+<para>Using the subscript or superscript character outside of math mode or
display math mode, as in <literal>the expression x^2</literal>, will get you
the error &#8216;<literal>Missing $ inserted</literal>&#8217;.
</para>
@@ -9633,7 +10708,7 @@ the error &#8216;<literal>Missing $ inserted</literal>&#8217;.
<indexterm role="cp"><primary><literal>mhchem</literal> package</primary></indexterm>
<para>A common reason to want subscripts outside of a mathematics mode is to
-typeset chemical formulas. There are packages for that such as
+typeset chemical formulas. There are packages for that, such as
<filename>mhchem</filename>; see CTAN.
</para>
@@ -9645,15 +10720,15 @@ typeset chemical formulas. There are packages for that such as
<indexterm role="cp"><primary>symbols, math</primary></indexterm>
<indexterm role="cp"><primary>greek letters</primary></indexterm>
-<indexterm role="cp"><primary>package, <literal>symbols</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>symbols</literal> package</primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>comprehensive</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>comprehensive</literal> package</primary></indexterm>
<para>&latex; provides almost any mathematical or technical symbol that
-anyone uses. For example, if you include <literal>$\pi$</literal> in your source,
-you will get the pi symbol &#x03C0;. See the <filename>Comprehensive
-&latex; Symbol List</filename> at
-<ulink url="https://ctan.org/tex-archive/info/symbols/comprehensive/">https://ctan.org/tex-archive/info/symbols/comprehensive/</ulink>.
+anyone uses. For example, if you include <literal>$\pi$</literal> in your source,
+you will get the pi symbol &#x03C0;. See the &#8220;Comprehensive
+&latex; Symbol List&#8221; package at
+<ulink url="https://ctan.org/pkg/comprehensive">https://ctan.org/pkg/comprehensive</ulink>.
</para>
<para>Here is a list of commonly-used symbols. It is by no means exhaustive.
Each symbol is described with a short phrase, and its symbol class,
@@ -9738,13 +10813,13 @@ union&#160;<literal>\cup</literal>.
(operator). (Note that the name has only one p.)
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigvee</primary></indexterm><literal>\bigvee</literal>
-</term><listitem><para>&#x22C1; Variable-sized, or n-ary, logical-and (operator).
+</term><listitem><para>&#x22C1; Variable-sized, or n-ary, logical-or (operator).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigwedge</primary></indexterm><literal>\bigwedge</literal>
-</term><listitem><para>&#x22C0; Variable-sized, or n-ary, logical-or (operator).
+</term><listitem><para>&#x22C0; Variable-sized, or n-ary, logical-and (operator).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bot</primary></indexterm><literal>\bot</literal>
-</term><listitem><para>&#x22A5; Up tack, bottom, least element of a partially ordered
+</term><listitem><para>&#x22A5;, Up tack, bottom, least element of a partially ordered
set, or a contradiction (ordinary). See also&#160;<literal>\top</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bowtie</primary></indexterm><literal>\bowtie</literal>
@@ -9779,7 +10854,7 @@ variable-sized operator&#160;<literal>\bigcirc</literal>.
</term><listitem><para>&#x2663; Club card suit (ordinary).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\complement</primary></indexterm><literal>\complement</literal>
-</term><listitem><para>&#x2201; Set complement, used as a superscript as in
+</term><listitem><para>&#x2201;, Set complement, used as a superscript as in
<literal>$S^\complement$</literal> (ordinary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. Also used:
<literal>$S^{\mathsf{c}}$</literal> or&#160;<literal>$\bar{S}$</literal>.
</para>
@@ -9947,8 +11022,8 @@ accents</link>).
</term><listitem><para>&#x03BB; Lowercase Greek letter (ordinary).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\land</primary></indexterm><literal>\land</literal>
-</term><listitem><para>&#x2227; Logical and (binary). This is a synonym for <literal>\wedge</literal>.
-See also logical or&#160;<literal>\lor</literal>.
+</term><listitem><para>&#x2227; Logical and (binary). Synonym:&#160;<literal>\wedge</literal>.
+See also logical&#160;or&#160;<literal>\lor</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\langle</primary></indexterm><literal>\langle</literal>
</term><listitem><para>&#x27E8; Left angle, or sequence, bracket (opening). Similar:
@@ -9971,7 +11046,7 @@ shaved off (opening). Matches&#160;<literal>\rceil</literal>.
for&#160;<literal>\leq</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leadsto</primary></indexterm><literal>\leadsto</literal>
-</term><listitem><para>&#x21DD; Squiggly right arrow (relation). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
+</term><listitem><para>&#x21DD; Squiggly right arrow (relation).
To get this symbol outside of math mode you can put
<literal>\newcommand*{\Leadsto}{\ensuremath{\leadsto}}</literal> in the
preamble and then use <literal>\Leadsto</literal> instead.
@@ -10009,7 +11084,7 @@ for&#160;<literal>\le</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lhd</primary></indexterm><literal>\lhd</literal>
</term><listitem><para>&#x25C1; Arrowhead, that is, triangle, pointing left (binary).
-Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the normal subgroup symbol you should load
+For the normal subgroup symbol you should load
<filename>amssymb</filename> and use&#160;<literal>\vartriangleleft</literal> (which is a relation
and so gives better spacing).
</para>
@@ -10037,15 +11112,16 @@ double-line double-headed arrow&#160;<literal>\Longleftrightarrow</literal>.
double-line right arrow&#160;<literal>\Longrightarrow</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lor</primary></indexterm><literal>\lor</literal>
-</term><listitem><para>&#x2228; Logical or (binary). Synonym: wedge&#160;<literal>\wedge</literal>.
+</term><listitem><para>&#x2228; Logical or (binary). Synonym:&#160;<literal>\vee</literal>.
+See also logical&#160;and&#160;<literal>\land</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mapsto</primary></indexterm><literal>\mapsto</literal>
-</term><listitem><para>&#x21A6; Single-line left arrow starting with vertical bar (relation).
+</term><listitem><para>&#x21A6; Single-line left arrow starting with vertical bar
+(relation).
Similar: longer version&#160;<literal>\longmapsto</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mho</primary></indexterm><literal>\mho</literal>
</term><listitem><para>&#x2127; Conductance, half-circle rotated capital omega (ordinary).
-Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mid</primary></indexterm><literal>\mid</literal>
</term><listitem><para>&#x2223; Single-line vertical bar (relation). A typical use of
@@ -10155,6 +11231,9 @@ of&#160;<literal>\in</literal>.
same glyph but the spacing is different because it is in the class
ordinary.
</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Phi</primary></indexterm><literal>\Phi</literal>
+</term><listitem><para>&#x03A6; Uppercase Greek letter (ordinary).
+</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\phi</primary></indexterm><literal>\phi</literal>
</term><listitem><para>&#x03D5; Lowercase Greek letter (ordinary). The variant form is
<literal>\varphi</literal>&#160;&#x03C6;.
@@ -10219,11 +11298,11 @@ double-line, or blackboard bold, R&#160;<literal>\mathbb{R}</literal>; to access
this, load the <filename>amsfonts</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\restriction</primary></indexterm><literal>\restriction</literal>
-</term><listitem><para>&#x21BE; Restriction of a function (relation). Synonym:
+</term><listitem><para>&#x21BE;, Restriction of a function (relation). Synonym:
<literal>\upharpoonright</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\revemptyset</primary></indexterm><literal>\revemptyset</literal>
-</term><listitem><para>&#x29B0; Reversed empty set symbol (ordinary). Related:
+</term><listitem><para>&#x29B0;, Reversed empty set symbol (ordinary). Related:
<literal>\varnothing</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>stix</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rfloor</primary></indexterm><literal>\rfloor</literal>
@@ -10232,7 +11311,7 @@ off (closing). Matches&#160;<literal>\lfloor</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rhd</primary></indexterm><literal>\rhd</literal>
</term><listitem><para>&#x25C1; Arrowhead, that is, triangle, pointing right (binary).
-Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the normal subgroup symbol you should instead
+For the normal subgroup symbol you should instead
load <filename>amssymb</filename> and use&#160;<literal>\vartriangleright</literal> (which is a
relation and so gives better spacing).
</para>
@@ -10305,7 +11384,7 @@ union&#160;<literal>cup</literal>. Related: variable-sized
operator&#160;<literal>\bigsqcup</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubset</primary></indexterm><literal>\sqsubset</literal>
-</term><listitem><para>&#x228F; Square subset symbol (relation). Similar:
+</term><listitem><para>&#x228F;, Square subset symbol (relation). Similar:
subset&#160;<literal>\subset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubseteq</primary></indexterm><literal>\sqsubseteq</literal>
@@ -10313,7 +11392,7 @@ subset&#160;<literal>\subset</literal>. Not available in plain &tex;. In &latex;
equal to&#160;<literal>\subseteq</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupset</primary></indexterm><literal>\sqsupset</literal>
-</term><listitem><para>&#x2290; Square superset symbol (relation). Similar:
+</term><listitem><para>&#x2290;, Square superset symbol (relation). Similar:
superset&#160;<literal>\supset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupseteq</primary></indexterm><literal>\sqsupseteq</literal>
@@ -10395,14 +11474,14 @@ relation and so gives better spacing).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unlhd</primary></indexterm><literal>\unlhd</literal>
</term><listitem><para>&#x22B4; Left-pointing not-filled underlined arrowhead, that is,
-triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the
+triangle, with a line under (binary). For the
normal subgroup symbol load <filename>amssymb</filename> and
use&#160;<literal>\vartrianglelefteq</literal> (which is a relation and so gives
better spacing).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unrhd</primary></indexterm><literal>\unrhd</literal>
</term><listitem><para>&#x22B5; Right-pointing not-filled underlined arrowhead, that is,
-triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the
+triangle, with a line under (binary). For the
normal subgroup symbol load <filename>amssymb</filename> and
use&#160;<literal>\vartrianglerighteq</literal> (which is a relation and so gives
better spacing).
@@ -10428,7 +11507,7 @@ arrow&#160;<literal>\updownarrow</literal>.
arrow&#160;<literal>\Updownarrow</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\upharpoonright</primary></indexterm><literal>\upharpoonright</literal>
-</term><listitem><para>&#x21BE; Up harpoon, with barb on right side
+</term><listitem><para>&#x21BE;, Up harpoon, with barb on right side
(relation). Synonym:&#160;<literal>&#92;restriction</literal>.
Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
@@ -10450,7 +11529,7 @@ more widely used in mathematics than the non-variant lunate epsilon form
membership&#160;<literal>\in</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vanothing</primary></indexterm><literal>\vanothing</literal>
-</term><listitem><para>&#x2205; Empty set symbol. Similar: <literal>\emptyset</literal>. Related:
+</term><listitem><para>&#x2205;, Empty set symbol. Similar: <literal>\emptyset</literal>. Related:
<literal>\revemptyset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varphi</primary></indexterm><literal>\varphi</literal>
@@ -10486,38 +11565,15 @@ logical and&#160;<literal>\wedge</literal>. Similar: variable-sized
operator&#160;<literal>\bigvee</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Vert</primary></indexterm><literal>\Vert</literal>
-</term><listitem><para>&#x2016; Vertical double bar (ordinary). Similar: vertical single
-bar&#160;<literal>\vert</literal>.
-</para>
-<para>For a norm symbol, you can use the <filename>mathtools</filename> package and put in
-your preamble
-<literal>\DeclarePairedDelimiter\norm{\lVert}{\rVert}</literal>. This gives you
-three command variants for double-line vertical bars that are correctly
-horizontally spaced: if in the document body you write the starred
-version <literal>$\norm*{M^\perp}$</literal> then the height of the vertical bars
-will match the height of the argument, whereas with
-<literal>\norm{M^\perp}</literal> the bars do not grow with the height of the
-argument but instead are the default height, and <literal>\norm[<replaceable>size
-command</replaceable>]{M^\perp}</literal> also gives bars that do not grow but are set to
-the size given in the <replaceable>size command</replaceable>, e.g., <literal>\Bigg</literal>.
+</term><listitem><para>&#x2016; Vertical double bar (ordinary). See <link linkend="Delimiters">Delimiters</link>,
+for how to use the <filename>mathtools</filename> package to create flexibly-sized
+norm symbols.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vert</primary></indexterm><literal>\vert</literal>
-</term><listitem><para>&#x007C; Single line vertical bar (ordinary). Similar: double-line
-vertical bar&#160;<literal>\Vert</literal>. For such that, as in the definition of a
-set, use&#160;<literal>\mid</literal> because it is a relation.
-</para>
-<para>For absolute value you can use the <filename>mathtools</filename> package and in your
-preamble put
-<literal>\DeclarePairedDelimiter\abs{\lvert}{\rvert}</literal>. This gives you
-three command variants for single-line vertical bars that are correctly
-horizontally spaced: if in the document body you write the starred
-version <literal>$\abs*{\frac{22}{7}}$</literal> then the height of the
-vertical bars will match the height of the argument, whereas with
-<literal>\abs{\frac{22}{7}}</literal> the bars do not grow with the height of
-the argument but instead are the default height, and
-<literal>\abs[<replaceable>size command</replaceable>]{\frac{22}{7}}</literal> also gives bars that
-do not grow but are set to the size given in the <replaceable>size command</replaceable>,
-e.g., <literal>\Bigg</literal>.
+</term><listitem><para>&#x007C; Single line vertical bar (ordinary). For &#8220;such
+that&#8221;, as in the definition of a set, use&#160;<literal>\mid</literal> because it
+is a relation. See <link linkend="Delimiters">Delimiters</link>, for how to use the <filename>mathtools</filename>
+package to create flexibly-sized absolute-value symbols.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\wedge</primary></indexterm><literal>\wedge</literal>
</term><listitem><para>&#x2227; Logical and (binary). Synonym:&#160;<literal>\land</literal>. See also
@@ -10561,7 +11617,93 @@ provides versions to use in mathematical text.
</listitem></varlistentry></variablelist>
-<sect2 label="16.2.1" id="Blackboard-bold">
+<sect2 label="16.2.1" id="Arrows">
+<title>Arrows</title>
+
+<indexterm role="cp"><primary>arrows</primary></indexterm>
+<indexterm role="cp"><primary>symbols, arrows</primary></indexterm>
+<indexterm role="fn"><primary>math, arrows</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>amsfonts</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsfonts</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>latexsym</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>latexsym</literal> package</primary></indexterm>
+
+<para>These are the arrows that come with standard &latex;. The
+<filename>latexsym</filename> and <filename>amsfonts</filename> packages contain many more.
+</para>
+<informaltable><tgroup cols="3"><colspec colwidth="10*"></colspec><colspec colwidth="40*"></colspec><colspec colwidth="50*"></colspec><thead><row><entry><para>Symbol</para></entry><entry><para>Command</para></entry><entry></entry></row></thead><tbody><row><entry><para>&#x021D3; </para></entry><entry><para><literal>\Downarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02193; </para></entry><entry><para><literal>\downarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021A9; </para></entry><entry><para><literal>\hookleftarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021AA; </para></entry><entry><para><literal>\hookrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x2190; </para></entry><entry><para><literal>\leftarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021D0; </para></entry><entry><para><literal>\Leftarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021D4; </para></entry><entry><para><literal>\Leftrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02194; </para></entry><entry><para><literal>\leftrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027F5; </para></entry><entry><para><literal>\longleftarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027F8; </para></entry><entry><para><literal>\Longleftarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027F7; </para></entry><entry><para><literal>\longleftrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027FA; </para></entry><entry><para><literal>\Longleftrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027FC; </para></entry><entry><para><literal>\longmapsto</literal> </para></entry><entry></entry></row><row><entry><para>&#x027F9; </para></entry><entry><para><literal>\Longrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x027F6; </para></entry><entry><para><literal>\longrightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021A6; </para></entry><entry><para><literal>\mapsto</literal> </para></entry><entry></entry></row><row><entry><para>&#x02197; </para></entry><entry><para><literal>\nearrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02196; </para></entry><entry><para><literal>\nwarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021D2; </para></entry><entry><para><literal>\Rightarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02192; </para></entry><entry><para><literal>\rightarrow</literal>, or <literal>\to</literal> </para></entry><entry></entry></row><row><entry><para>&#x02198; </para></entry><entry><para><literal>\searrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02199; </para></entry><entry><para><literal>\swarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02191; </para></entry><entry><para><literal>\uparrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021D1; </para></entry><entry><para><literal>\Uparrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x02195; </para></entry><entry><para><literal>\updownarrow</literal> </para></entry><entry></entry></row><row><entry><para>&#x021D5; </para></entry><entry><para><literal>\Updownarrow</literal> </para></entry><entry></entry></row></tbody></tgroup></informaltable>
+<para>An example of the difference between <literal>\to</literal> and <literal>\mapsto</literal>
+is: <literal>\( f\colon D\to C \) given by \( n\mapsto n^2 \)</literal>.
+</para>
+<indexterm role="cp"><primary>package, <literal>amscd</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amscd</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>tikz-cd</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>tikz-cd</literal> package</primary></indexterm>
+
+<para>For commutative diagrams there are a number of packages, including
+<filename>tikz-cd</filename> and <filename>amscd</filename>.
+</para>
+
+</sect2>
+<sect2 label="16.2.2" id="_005cboldmath-_0026-_005cunboldmath">
+<title><literal>\boldmath</literal> &amp; <literal>\unboldmath</literal></title>
+
+<indexterm role="cp"><primary>boldface mathematics</primary></indexterm>
+<indexterm role="cp"><primary>symbols, boldface</primary></indexterm>
+<indexterm role="fn"><primary>\boldmath</primary></indexterm>
+<indexterm role="fn"><primary>\unboldmath</primary></indexterm>
+
+<para>Synopsis (used in paragraph mode or LR mode):
+</para>
+<screen>\boldmath \( <replaceable>math</replaceable> \)
+</screen>
+<para>or
+</para>
+<screen>\unboldmath \( <replaceable>math</replaceable> \)
+</screen>
+<indexterm role="fn"><primary>\boldmath</primary></indexterm>
+<indexterm role="fn"><primary>\unboldmath</primary></indexterm>
+<para>Declarations to change the letters and symbols in <replaceable>math</replaceable> to be in
+a bold font, or to countermand that and bring back the regular
+(non-bold) default. They must be used when not in math mode or display
+math mode (see <link linkend="Modes">Modes</link>). Both commands are fragile
+(see <link linkend="_005cprotect">\protect</link>).
+</para>
+<para>In this example each <literal>\boldmath</literal> command takes place inside an
+<literal>\mbox</literal>,
+</para>
+<screen>we have $\mbox{\boldmath \( v \)} = 5\cdot\mbox{\boldmath \( u \)$}$
+</screen>
+<para>which means <literal>\boldmath</literal> is only called in a text mode, here LR
+mode, and explains why &latex; must switch to math mode to set <literal>v</literal>
+and <literal>u</literal>.
+</para>
+<para>If you use either command inside math mode, as with <literal>Trouble: \(
+\boldmath x \)</literal>, then you get something like &#8216;<literal>LaTeX Font Warning:
+Command \boldmath invalid in math mode on input line 11</literal>&#8217; and &#8216;<literal>LaTeX
+Font Warning: Command \mathversion invalid in math mode on input line
+11</literal>&#8217;.
+</para>
+<indexterm role="cp"><primary>package, <literal>bm</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>bm</literal> package</primary></indexterm>
+
+<para>There are many issues with <literal>\boldmath</literal>. New documents should use
+the <filename>bm</filename> package provided by the &latex; Project team. A complete
+description is outside the scope of this document (see the full
+documentation on CTAN) but even this small example
+</para>
+<screen>\usepackage{bm} % in preamble
+...
+we have $\bm{v} = 5\cdot\bm{u}$
+</screen>
+<para>shows that it is an improvement over <literal>\boldmath</literal>.
+</para>
+
+</sect2>
+<sect2 label="16.2.3" id="Blackboard-bold">
<title>Blackboard bold</title>
<indexterm role="cp"><primary>blackboard bold</primary></indexterm>
@@ -10581,7 +11723,7 @@ integers, etc.
</para>
<screen>\( \forall n \in \mathbb{N}, n^2 \geq 0 \)
</screen>
-<para>the <literal>\mathbb{N}</literal> gives blackboard bold symbol &#x2115;
+<para>the <literal>\mathbb{N}</literal> gives blackboard bold symbol &#x2115;,
representing the natural numbers.
</para>
<para>If you use other than an uppercase letter then you do not get an error
@@ -10592,7 +11734,7 @@ capital letters; look on CTAN.
</para>
</sect2>
-<sect2 label="16.2.2" id="Calligraphic">
+<sect2 label="16.2.4" id="Calligraphic">
<title>Calligraphic</title>
<indexterm role="cp"><primary>calligraphic fonts</primary></indexterm>
@@ -10610,68 +11752,295 @@ capital letters; look on CTAN.
<screen>Let the graph be \( \mathcal{G} \).
</screen>
<para>If you use something other than an uppercase letter then you do not get
-an error. Instead you get unexpected output. For instance,
-<literal>\mathcal{g}</literal> outputs a close curly brace symbol, while
-<literal>\mathcal{+}</literal> outputs a plus sign.
+an error but you also do not get math calligraphic output. For instance,
+<literal>\mathcal{g}</literal> outputs a close curly brace symbol.
</para>
</sect2>
-<sect2 label="16.2.3" id="_005cboldmath-_0026-_005cunboldmath">
-<title><literal>\boldmath</literal> &amp; <literal>\unboldmath</literal></title>
+<sect2 label="16.2.5" id="Delimiters">
+<title>Delimiters</title>
+
+<indexterm role="cp"><primary>delimiters</primary></indexterm>
+<indexterm role="cp"><primary>parentheses</primary></indexterm>
+<indexterm role="cp"><primary>braces</primary></indexterm>
+<indexterm role="cp"><primary>curly braces</primary></indexterm>
+<indexterm role="cp"><primary>brackets</primary></indexterm>
+
+<para>Delimiters are parentheses, braces, or other characters used to mark
+the start and end of subformulas. This formula has three sets of
+parentheses delimiting the three subformulas.
+</para>
+<screen>(z-z_0)^2 = (x-x_0)^2 + (y-y_0)^2
+</screen>
+<para>The delimiters do not need to match, so you can enter <literal>\( [0,1) \)</literal>.
+</para>
+<para>Here are the common delimiters:
+</para>
+<informaltable><tgroup cols="4"><colspec colwidth="11*"></colspec><colspec colwidth="20*"></colspec><colspec colwidth="40*"></colspec><colspec colwidth="29*"></colspec><thead><row><entry><para>Delimiter</para></entry><entry><para>Command</para></entry><entry><para>Name
+</para></entry></row></thead><tbody><row><entry><para>( </para></entry><entry><para><literal>(</literal> </para></entry><entry><para>Left parenthesis
+</para></entry></row><row><entry><para>) </para></entry><entry><para><literal>)</literal> </para></entry><entry><para>Right parenthesis
+</para></entry></row><row><entry><para>\} </para></entry><entry><para><literal>{</literal> or <literal>\lbrace</literal> </para></entry><entry><para>Left brace
+</para></entry></row><row><entry><para>\{ </para></entry><entry><para><literal>}</literal> or <literal>\rbrace</literal> </para></entry><entry><para>Right brace
+</para></entry></row><row><entry><para>[ </para></entry><entry><para><literal>[</literal> or <literal>\lbrack</literal> </para></entry><entry><para>Left bracket
+</para></entry></row><row><entry><para>] </para></entry><entry><para><literal>]</literal> or <literal>\rbrack</literal> </para></entry><entry><para>Right bracket
+</para></entry></row><row><entry><para>&#x230A; </para></entry><entry><para><literal>\lfloor</literal> </para></entry><entry><para>Left floor bracket
+</para></entry></row><row><entry><para>&#x230B; </para></entry><entry><para><literal>\rfloor</literal> </para></entry><entry><para>Right floor bracket
+</para></entry></row><row><entry><para>&#x2308; </para></entry><entry><para><literal>\lceil</literal> </para></entry><entry><para>Left ceiling bracket
+</para></entry></row><row><entry><para>&#x2309; </para></entry><entry><para><literal>\rceil</literal> </para></entry><entry><para>Right ceiling bracket
+</para></entry></row><row><entry><para>&#x27E8; </para></entry><entry><para><literal>\langle</literal> </para></entry><entry><para>Left angle bracket
+</para></entry></row><row><entry><para>&#x27E9; </para></entry><entry><para><literal>\rangle</literal> </para></entry><entry><para>Right angle bracket
+</para></entry></row><row><entry><para>/ </para></entry><entry><para><literal>/</literal> </para></entry><entry><para>Slash, or forward slash
+</para></entry></row><row><entry><para>\ </para></entry><entry><para><literal>\backslash</literal> </para></entry><entry><para>Reverse slash, or backslash
+</para></entry></row><row><entry><para>| </para></entry><entry><para><literal>|</literal> or <literal>\vert</literal> </para></entry><entry><para>Vertical bar
+</para></entry></row><row><entry><para>&#x2016; </para></entry><entry><para><literal>\|</literal> or <literal>\Vert</literal> </para></entry><entry><para>Double vertical bar
+</para></entry></row></tbody></tgroup></informaltable>
+<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
-<indexterm role="cp"><primary>boldface mathematics</primary></indexterm>
-<indexterm role="cp"><primary>symbols, boldface</primary></indexterm>
-<indexterm role="fn"><primary>\boldmath</primary></indexterm>
-<indexterm role="fn"><primary>\unboldmath</primary></indexterm>
+<para>The <filename>mathtools</filename> package allows you to create commands for paired
+delimiters. For instance, if you put
+<literal>\DeclarePairedDelimiter\abs{\lvert}{\rvert}</literal> in your preamble
+then you get two commands for single-line vertical bars (they only work
+in math mode). The starred version, such as
+<literal>\abs*{\frac{22}{7}}</literal>, has the height of the vertical bars
+match the height of the argument. The unstarred version, such as
+<literal>\abs{\frac{22}{7}}</literal>, has the bars fixed at a default height.
+This version accepts an optional argument, as in <literal>\abs[<replaceable>size
+command</replaceable>]{\frac{22}{7}}</literal>, where the height of the bars is given in
+<replaceable>size command</replaceable>, such as <literal>\Bigg</literal>. Using <literal>\lVert</literal> and
+<literal>\rVert</literal> as the symbols will give you a norm symbol with the same
+behavior.
+</para>
-<para>Synopsis (used in paragraph mode or LR mode):
+
+<sect3 label="16.2.5.1" id="_005cleft-_0026-_005cright">
+<title><literal>\left</literal> &amp; <literal>\right</literal></title>
+
+<indexterm role="cp"><primary>delimiters, paired</primary></indexterm>
+<indexterm role="cp"><primary>paired delimiters</primary></indexterm>
+<indexterm role="cp"><primary>matching parentheses</primary></indexterm>
+<indexterm role="cp"><primary>matching brackets</primary></indexterm>
+<indexterm role="cp"><primary>null delimiter</primary></indexterm>
+<indexterm role="fn"><primary>\left</primary></indexterm>
+<indexterm role="fn"><primary>\right</primary></indexterm>
+
+<!-- Credit: SE userPhilipp https://tex.stackexchange.com/a/12793 -->
+
+<para>Synopsis:
</para>
-<screen>\boldmath \( <replaceable>math</replaceable> \)
+<screen>\left <replaceable>delimiter1</replaceable> ... \right <replaceable>delimiter2</replaceable>
</screen>
-<para>or
+<para>Make matching parentheses, braces, or other delimiters. &latex; makes
+the delimiters tall enough to just cover the size of the formula that
+they enclose.
</para>
-<screen>\unboldmath \( <replaceable>math</replaceable> \)
+<para>This makes a unit vector surrounded by parentheses tall enough to cover
+the entries.
+</para>
+<screen>\begin{equation}
+ \left(\begin{array}{c}
+ 1 \\
+ 0 \\
+ \end{array}\right)
+\end{equation}
</screen>
-<indexterm role="fn"><primary>\boldmath</primary></indexterm>
-<indexterm role="fn"><primary>\unboldmath</primary></indexterm>
-<para>Declarations to change the letters and symbols in <replaceable>math</replaceable> to be in
-a bold font, or to countermand that and bring back the regular
-(non-bold) default. They must be used when not in math mode or display
-math mode (see <link linkend="Modes">Modes</link>). Both commands are fragile
-(see <link linkend="_005cprotect">\protect</link>).
+<para>See <link linkend="Delimiters">Delimiters</link>, for a list of the common delimiters.
</para>
-<para>In this example each <literal>\boldmath</literal> command takes place inside an
-<literal>\mbox</literal>,
+<para>Every <literal>\left</literal> must have a matching <literal>\right</literal>. In the above
+example, leaving out the <literal>\left(</literal> gets the error message
+&#8216;<literal>Extra \right</literal>&#8217;. Leaving out the <literal>\right)</literal> gets &#8216;<literal>You
+can't use `\eqno' in math mode</literal>&#8217;.
</para>
-<screen>we have $\mbox{\boldmath \( v \)} = 5\cdot\mbox{\boldmath \( u \)$}$
+<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
+
+<para>However, <replaceable>delimiter1</replaceable> and <replaceable>delimiter2</replaceable> need not match. A common
+case is that you want an unmatched brace, as below. Use a period,
+&#8216;<literal>.</literal>&#8217;, as a null delimiter.
+</para>
+<screen>\begin{equation}
+ f(n)=\left\{\begin{array}{ll}
+ 1 &amp;\mbox{--if \(n=0\)} \\
+ f(n-1)+3n^2 &amp;\mbox{--else}
+ \end{array}\right.
+\end{equation}
</screen>
-<para>which means <literal>\boldmath</literal> is only called in a text mode, here LR
-mode, and explains why &latex; must switch to math mode to set <literal>v</literal>
-and <literal>u</literal>.
+<para>Note that to get a curly brace as a delimiter you must prefix it with a
+backslash, <literal>\{</literal>. (The packages <filename>amsmath</filename> and
+<filename>mathtools</filename> allow you to get the above construct through in a
+<literal>cases</literal> environment.)
</para>
-<para>If you use either command inside math mode, as with <literal>Trouble: \(
-\boldmath x \)</literal>, then you get something like &#8216;<literal>LaTeX Font Warning:
-Command \boldmath invalid in math mode on input line 11</literal>&#8217; and &#8216;<literal>LaTeX
-Font Warning: Command \mathversion invalid in math mode on input line
-11</literal>&#8217;.
+<para>The <literal>\left ... \right</literal> pair make a group. One consequence is that
+the formula enclosed in the <literal>\left ... \right</literal> pair cannot have
+line breaks in the output. This includes both manual line breaks and
+&latex;-generated automatic ones. In this example, &latex; breaks the
+equation to make the formula fit the margins.
+</para>
+<screen>Lorem ipsum dolor sit amet
+\( (a+b+c+d+e+f+g+h+i+j+k+l+m+n+o+p+q+r+s+t+u+v+w+x+y+z) \)
+</screen>
+<para>But with <literal>\left</literal> and <literal>\right</literal>
+</para>
+<screen>Lorem ipsum dolor sit amet
+\( \left(a+b+c+d+e+f+g+h+i+j+k+l+m+n+o+p+q+r+s+t+u+v+w+x+y+z\right) \)
+</screen>
+<para>&latex; won&#8217;t break the line, causing the formula to extend into the
+margin.
+</para>
+<para>Because <literal>\left ... \right</literal> make a group, all the usual grouping
+rules hold. Here, the value of <literal>\testlength</literal> set inside the
+equation will be forgotten, and the output is &#8216;<literal>1.2pt</literal>&#8217;.
+</para>
+<screen>\newlength{\testlength} \setlength{\testlength}{1.2pt}
+\begin{equation}
+ \left( a+b=c \setlength{\testlength}{3.4pt} \right)
+ \the\testlength
+\end{equation}
+</screen>
+<para>The <literal>\left ... \right</literal> pair affect the horizontal spacing of the
+enclosed formula, in two ways. The first is that in <literal>\( \sin(x) =
+\sin\left(x\right) \)</literal> the one after the equals sign has more space
+around the <literal>x</literal>. That&#8217;s because <literal>\left( ... \right)</literal> inserts
+an inner node while <literal>( ... )</literal> inserts an opening node. The second
+way that the pair affect the horizontal spacing is that because they
+form a group, the enclosed subformula will be typeset at its natural
+width, with no stretching or shrinking to make the line fit better.
+</para>
+<para>&tex; scales the delimiters according to the height and depth of the
+contained formula. Here &latex; grows the brackets to extend the full
+height of the integral.
+</para>
+<screen>\begin{equation}
+ \left[ \int_{x=r_0}^{\infty} -G\frac{Mm}{r^2}\, dr \right]
+\end{equation}
+</screen>
+<para>Manual sizing is often better. For instance, although below the rule
+has no depth, &tex; will create delimiters that extend far below the
+rule.
+</para>
+<screen>\begin{equation}
+ \left( \rule{1pt}{1cm} \right)
+\end{equation}
+</screen>
+<para>&tex; can choose delimiters that are too small, as in <literal>\( \left|
+|x|+|y| \right| \)</literal>. It can also choose delimiters that are too large,
+as here.
+</para>
+<screen>\begin{equation}
+ \left( \sum_{0\leq i&lt;n} i^k \right)
+\end{equation}
+</screen>
+<para>A third awkward case is when a long displayed formula is on more than
+one line and you must match the sizes of the opening and closing
+delimiter; you can&#8217;t use <literal>\left</literal> on the first line and
+<literal>\right</literal> on the last because they must be paired.
+</para>
+<para>To size the delimiters manually, see&#160;<link linkend="_005cbigl-_0026-_005cbigr-etc_002e">\bigl &amp; \bigr etc.</link>.
</para>
-<indexterm role="cp"><primary>package, <literal>bm</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>bm</literal> package</primary></indexterm>
-<para>There are many issues with <literal>\boldmath</literal>. New documents should use
-the <filename>bm</filename> package provided by the &latex; Project team. A complete
-description is outside the scope of this document (see the full
-documentation on CTAN) but even this small example
+</sect3>
+<sect3 label="16.2.5.2" id="_005cbigl-_0026-_005cbigr-etc_002e">
+<title><literal>\bigl</literal>, <literal>\bigr</literal>, etc.</title>
+
+<para>Synopsis, one of:
</para>
-<screen>\usepackage{bm} % in preamble
-...
-we have $\bm{v} = 5\cdot\bm{u}$
+<screen>\bigl<replaceable>delimiter1</replaceable> ... \bigr<replaceable>delimiter2</replaceable>
+\Bigl<replaceable>delimiter1</replaceable> ... \bigr<replaceable>delimiter2</replaceable>
+\biggl<replaceable>delimiter1</replaceable> ... \biggr<replaceable>delimiter2</replaceable>
+\Biggl<replaceable>delimiter1</replaceable> ... \Biggr<replaceable>delimiter2</replaceable>
</screen>
-<para>shows that it is an improvement over <literal>\boldmath</literal>.
+<para>(as with <literal>\bigl[...\bigr]</literal>; strictly speaking they need not be
+paired, see below), or one of:
+</para>
+<screen>\bigm<replaceable>delimiter</replaceable>
+\Bigm<replaceable>delimiter</replaceable>
+\biggm<replaceable>delimiter</replaceable>
+\Biggm<replaceable>delimiter</replaceable>
+</screen>
+<para>(as with <literal>\bigm|</literal>), or one of:
+</para>
+<screen>\big<replaceable>delimiter</replaceable>
+\Big<replaceable>delimiter</replaceable>
+\bigg<replaceable>delimiter</replaceable>
+\Bigg<replaceable>delimiter</replaceable>
+</screen>
+<para>(as with <literal>\big[</literal>).
+</para>
+<para>Produce manually-sized delimiters. For delimiters that are
+automatically sized see&#160;<link linkend="_005cleft-_0026-_005cright">\left &amp; \right</link>).
+</para>
+<para>This produces slightly larger outer vertical bars.
+</para>
+<screen> \bigl| |x|+|y| \bigr|
+</screen>
+<para>The commands above are listed in order of increasing size. You can use
+the smallest size such as <literal>\bigl...\bigr</literal> in a paragraph without
+causing &latex; to spread the lines apart. The larger sizes are meant
+for displayed equations.
+</para>
+<para>See <link linkend="Delimiters">Delimiters</link>, for a list of the common delimiters. In the family of
+commands with &#8216;<literal>l</literal>&#8217; and &#8216;<literal>r</literal>&#8217;, <replaceable>delimiter1</replaceable> and
+<replaceable>delimiter2</replaceable> need not be the same.
+</para>
+<para>The &#8216;<literal>l</literal>&#8217; and &#8216;<literal>r</literal>&#8217; commands produce open and close delimiters
+that insert no horizontal space between a preceding atom and the
+delimiter, while the commands without &#8216;<literal>l</literal>&#8217; and &#8216;<literal>r</literal>&#8217; insert some
+space (because each delimiter is set as an ordinary variable). Compare
+these two.
+</para>
+<!-- credit: Martin Heller https://tex.stackexchange.com/a/1234 -->
+<screen>\begin{tabular}{l}
+ \(\displaystyle \sin\biggl(\frac{1}{2}\biggr) \) \\ % good
+ \(\displaystyle \sin\bigg(\frac{1}{2}\bigg) \) \\ % bad
+\end{tabular}
+</screen>
+<para>The traditional typographic treatment is on the first line. On the
+second line the output will have some extra space between the
+<literal>\sin</literal> and the open parenthesis.
+</para>
+<para>Commands without &#8216;<literal>l</literal>&#8217; or&#160;&#8216;<literal>r</literal>&#8217; do give correct spacing in
+some circumstances, as with this large vertical line
+</para>
+<screen>\begin{equation}
+ \int_{x=a}^b x^2\,dx = \frac{1}{3} x^3 \Big|_{x=a}^b
+\end{equation}
+</screen>
+<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm>
+
+<para>(many authors would replace <literal>\frac</literal> with the <literal>\tfrac</literal> command
+from the <filename>amsmath</filename> package), and as with this larger slash.
+</para>
+<screen>\begin{equation}
+ \lim_{n\to\infty}\pi(n) \big/ (n/\log n) = 1
+\end{equation}
+</screen>
+<para>Unlike the <literal>\left...\right</literal> pair (see <link linkend="_005cleft-_0026-_005cright">\left &amp; \right</link>), the
+commands here with &#8216;<literal>l</literal>&#8217; and&#160;&#8216;<literal>r</literal>&#8217; do not make a group.
+Strictly speaking they need not be matched so you can write something
+like this.
+</para>
+<screen>\begin{equation}
+ \Biggl[ \pi/6 ]
+\end{equation}
+</screen>
+<para>The commands with &#8216;<literal>m</literal>&#8217; are for relations, which are in the middle of
+formulas, as here.
</para>
+<screen>\begin{equation}
+ \biggl\{ a\in B \biggm| a=\sum_{0\leq i&lt;n}3i^2+4 \biggr\}
+\end{equation}
+</screen>
+<!-- xx Add discussion \bigg\mid not being good -->
+<!-- and \bigg| being right; maybe mention of \middle and braket package? -->
+
+</sect3>
</sect2>
-<sect2 label="16.2.4" id="Dots">
+<sect2 label="16.2.6" id="Dots">
<title>Dots, horizontal or vertical</title>
<indexterm role="cp"><primary>ellipses</primary></indexterm>
@@ -10739,6 +12108,52 @@ or relation symbol, <literal>\dotsi</literal> for dots with integrals, or
</para>
</sect2>
+<sect2 label="16.2.7" id="Greek-letters">
+<title>Greek letters</title>
+
+<indexterm role="cp"><primary>Greek letters</primary></indexterm>
+
+<para>The upper case versions of these Greek letters are only shown when they
+differ from Roman upper case letters.
+</para>
+<informaltable><tgroup cols="4"><colspec colwidth="10*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="15*"></colspec><colspec colwidth="45*"></colspec><thead><row><entry><para>Symbol</para></entry><entry><para>Command</para></entry><entry><para>Name</para></entry><entry></entry></row></thead><tbody><row><entry><para>&#x03B1;</para></entry><entry><para><literal>\alpha</literal></para></entry><entry><para>Alpha
+</para></entry></row><row><entry><para>&#x03B2;</para></entry><entry><para><literal>\beta</literal></para></entry><entry><para>Beta
+</para></entry></row><row><entry><para>&#x03B3;, &#x0393;</para></entry><entry><para><literal>\gamma</literal>, <literal>\Gamma</literal></para></entry><entry><para>Gamma
+</para></entry></row><row><entry><para>&#x03B4;, &#x0394;</para></entry><entry><para><literal>\delta</literal>, <literal>\Delta</literal></para></entry><entry><para>Delta
+</para></entry></row><row><entry><para>&#x03B5;, &#x03F5;</para></entry><entry><para><literal>\varepsilon</literal>, <literal>\epsilon</literal></para></entry><entry><para>Epsilon
+</para></entry></row><row><entry><para>&#x03B6;</para></entry><entry><para><literal>\zeta</literal></para></entry><entry><para>Zeta
+</para></entry></row><row><entry><para>&#x03B7;</para></entry><entry><para><literal>\eta</literal></para></entry><entry><para>Eta
+</para></entry></row><row><entry><para>&#x03B8;, &#x03D1;</para></entry><entry><para><literal>\theta</literal>, <literal>\vartheta</literal></para></entry><entry><para>Theta
+</para></entry></row><row><entry><para>&#x03B9;</para></entry><entry><para><literal>\iota</literal></para></entry><entry><para>Iota
+</para></entry></row><row><entry><para>&#x03BA;</para></entry><entry><para><literal>\kappa</literal></para></entry><entry><para>Kappa
+</para></entry></row><row><entry><para>&#x03BB;, &#x039B;</para></entry><entry><para><literal>\lambda</literal>, <literal>\Lambda</literal></para></entry><entry><para>Lambda
+</para></entry></row><row><entry><para>&#x03BC;</para></entry><entry><para><literal>\mu</literal></para></entry><entry><para>Mu
+</para></entry></row><row><entry><para>&#x03BD;</para></entry><entry><para><literal>\nu</literal></para></entry><entry><para>Nu
+</para></entry></row><row><entry><para>&#x03BE;, &#x039E;</para></entry><entry><para><literal>\xi</literal>, <literal>\Xi</literal></para></entry><entry><para>Xi
+</para></entry></row><row><entry><para>&#x03C0;, &#x03A0;</para></entry><entry><para><literal>\pi</literal>, <literal>\Pi</literal></para></entry><entry><para>Pi
+</para></entry></row><row><entry><para>&#x03C1;, &#x03F1;</para></entry><entry><para><literal>\rho</literal>, <literal>\varrho</literal></para></entry><entry><para>Rho
+</para></entry></row><row><entry><para>&#x03C3;, &#x03A3;</para></entry><entry><para><literal>\sigma</literal>, <literal>\Sigma</literal></para></entry><entry><para>Sigma
+</para></entry></row><row><entry><para>&#x03C4;</para></entry><entry><para><literal>\tau</literal></para></entry><entry><para>Tau
+</para></entry></row><row><entry><para>&#x03D5;, &#x03C6;, &#x03A6;</para></entry><entry><para><literal>\phi</literal>, <literal>\varphi</literal>, <literal>\Phi</literal></para></entry><entry><para>Phi
+</para></entry></row><row><entry><para>&#x03C7;</para></entry><entry><para><literal>\chi</literal></para></entry><entry><para>chi
+</para></entry></row><row><entry><para>&#x03C8;, &#x03A8;</para></entry><entry><para><literal>\psi</literal>, <literal>\Psi</literal></para></entry><entry><para>Psi
+</para></entry></row><row><entry><para>&#x03C9;, &#x03A9;</para></entry><entry><para><literal>\omega</literal>, <literal>\Omega</literal></para></entry><entry><para>Omega
+</para></entry></row></tbody></tgroup></informaltable>
+<indexterm role="cp"><primary>package, <literal>unicode-math</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>unicode-math</literal> package</primary></indexterm>
+
+<para>For omicron, if you are using &latex;&#8217;s default Computer Modern font
+then enter omicron just as &#8216;<literal>o</literal>&#8217; or &#8216;<literal>O</literal>&#8217;. If you like having the
+name or if your font shows a difference then you can use something like
+<literal>\newcommand\omicron{o}</literal>. The package <filename>unicode-math</filename> has
+<literal>\upomicron</literal> for upright omicron and <literal>\mitomicron</literal> for math
+italic.
+</para>
+<para>While the set membership relation symbol &#x2208; generated by
+<literal>\in</literal> is related to epsilon, it is never used for a variable.
+</para>
+
+</sect2>
</sect1>
<sect1 label="16.3" id="Math-functions">
<title>Math functions</title>
@@ -11009,9 +12424,9 @@ normal rules for mathematics texts. If you enter <literal>y=m x</literal> then
&latex; ignores the space and in the output the m is next to the x,
as <inlineequation><mathphrase>y=mx</mathphrase></inlineequation>.
</para>
-<para>But &latex;&#8217;s rules sometimes need tweaking. For example, in an
+<para>But &latex;&#8217;s rules occasionally need tweaking. For example, in an
integral the tradition is to put a small extra space between the
-<literal>f(x)</literal> and the <literal>dx</literal>, here done with the <literal>\,</literal> command.
+<literal>f(x)</literal> and the <literal>dx</literal>, here done with the <literal>\,</literal> command:
</para>
<screen>\int_0^1 f(x)\,dx
</screen>
@@ -11025,8 +12440,15 @@ a&#160;&#8216;<literal>M</literal>&#8217;.
<variablelist><varlistentry><term><literal>\;</literal>
</term><listitem><indexterm role="fn"><primary>\;</primary></indexterm>
<indexterm role="fn"><primary>\thickspace</primary></indexterm>
-<anchor id="spacing-in-math-mode-thickspace"/><para>Synonym: <literal>\thickspace</literal>. Normally <literal>5.0mu plus 5.0mu</literal>. Math
-mode only.
+<anchor id="spacing-in-math-mode-thickspace"/><para>Synonym: <literal>\thickspace</literal>. Normally <literal>5.0mu plus 5.0mu</literal>.
+With <literal>amsmath</literal>, or as of the 2020-10-01 &latex; release, can be
+used in text mode as well as math mode; before that, in math mode only.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>\negthickspace</literal>
+</term><listitem><indexterm role="fn"><primary>\negthickspace</primary></indexterm>
+<para>Normally <literal>-5.0mu plus 2.0mu minus 4.0mu</literal>.
+With <literal>amsmath</literal>, or as of the 2020-10-01 &latex; release, can be
+used in text mode as well as math mode; before that, in math mode only.
</para>
</listitem></varlistentry><varlistentry><term><literal>\:</literal>
</term><term><literal>\&gt;</literal>
@@ -11034,7 +12456,14 @@ mode only.
<indexterm role="fn"><primary>\&gt;</primary></indexterm>
<indexterm role="fn"><primary>\medspace</primary></indexterm>
<anchor id="spacing-in-math-mode-medspace"/><para>Synonym: <literal>\medspace</literal>. Normally <literal>4.0mu plus 2.0mu minus 4.0mu</literal>.
-Math mode only.
+With <literal>amsmath</literal>, or as of the 2020-10-01 &latex; release, can be
+used in text mode as well as math mode; before that, in math mode only.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>\negmedspace</literal>
+</term><listitem><indexterm role="fn"><primary>\negmedspace</primary></indexterm>
+<para>Normally <literal>-4.0mu plus 2.0mu minus 4.0mu</literal>.
+With <literal>amsmath</literal>, or as of the 2020-10-01 &latex; release, can be
+used in text mode as well as math mode; before that, in math mode only.
</para>
</listitem></varlistentry><varlistentry><term><literal>\,</literal>
</term><listitem><indexterm role="fn"><primary>\,</primary></indexterm>
@@ -11057,9 +12486,11 @@ this, before punctuation in a displayed equation.
</term><listitem><indexterm role="fn"><primary>\!</primary></indexterm>
<indexterm role="fn"><primary>\negthinspace</primary></indexterm>
<indexterm role="cp"><primary>thin space, negative</primary></indexterm>
-<anchor id="spacing-in-math-mode-negthinspace"/><para>A negative thin space. Normally <literal>-3mu</literal>. The <literal>\!</literal> command is
-math mode only but the <literal>\negthinspace</literal> command is available for
-text mode (see <link linkend="_005cthinspace-_0026-_005cnegthinspace">\thinspace &amp; \negthinspace</link>).
+<anchor id="spacing-in-math-mode-negthinspace"/><para>A negative thin space. Normally <literal>-3mu</literal>.
+With <literal>amsmath</literal>, or as of the 2020-10-01 &latex; release, can be
+used in text mode as well as math mode; before that,
+The <literal>\!</literal> command is math mode only but the <literal>\negthinspace</literal>
+command has always worked in text mode (see <link linkend="_005cthinspace-_0026-_005cnegthinspace">\thinspace &amp; \negthinspace</link>).
</para>
</listitem></varlistentry><varlistentry><term><literal>\quad</literal>
</term><listitem><indexterm role="cp"><primary>quad</primary></indexterm>
@@ -11169,23 +12600,31 @@ control over smashing a subformula box.
</screen>
<para>The <literal>\phantom</literal> command creates a box with the same height, depth,
and width as <replaceable>subformula</replaceable>, but empty. That is, this command causes
-&latex; to typeset the box but not its ink. The <literal>\vphantom</literal>
-variant also produces an invisible box with the same height and depth as
-<replaceable>subformula</replaceable>, but it has width zero. And <literal>\hphantom</literal> makes a
-box with the same width as <replaceable>subformula</replaceable> but with height and depth
-zero.
+&latex; to typeset the space but not fill it with the material. Here
+&latex; will put a box of the right size for the quotation, but empty.
</para>
-<para>Without the <literal>\vphantom</literal> in this example, the top bars of the two
-square roots would be at different heights.
-</para>
-<screen>\( \sqrt{\vphantom{a^3}a}\cdot\sqrt{a^3} \)
+<screen>\fbox{\phantom{Conservatism is the fear-filled worship of dead radicals.
+ --- Mark Twain}}
</screen>
-<para>The <literal>\vphantom{a^3}</literal> causes the first <literal>\sqrt</literal> to have inside
-it a box of the same height as the second <literal>\sqrt</literal>, so &latex;
-makes the bars align.
+<para>The <literal>\vphantom</literal> variant produces an invisible box with the same
+vertical size as <replaceable>subformula</replaceable>, the same height and depth, but having
+zero width. And <literal>\hphantom</literal> makes a box with the same width as
+<replaceable>subformula</replaceable> but with zero height and depth.
</para>
-<para>These commands often are combined with <literal>\smash</literal>. See <link linkend="_005csmash">\smash</link>
-for another example of the use of <literal>\vphantom</literal>.
+<para>In this example, the tower of exponents in the second summand expression
+is so tall that &tex; places this expression further down than its
+default. Without adjustment, the two summand expressions would be at
+different levels. The <literal>\vphantom</literal> in the first expression tells
+&tex; to leave as much vertical room as it does for the tower, so the
+two expressions come out at the same level.
+</para>
+<screen>\begin{displaymath}
+ \sum_{j\in\{0,\ldots\, 10\}\vphantom{3^{3^{3^j}}}}
+ \sum_{i\in\{0,\ldots\, 3^{3^{3^j}}\}} i\cdot j
+\end{displaymath}
+</screen>
+<para>These commands are often used in conjunction with <literal>\smash</literal>.
+See <link linkend="_005csmash">\smash</link>, which includes another example of <literal>\vphantom</literal>.
</para>
<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
@@ -11213,6 +12652,37 @@ with <literal>\leavevmode</literal>.
</para>
</sect2>
+<sect2 label="16.6.3" id="_005cmathstrut">
+<title><literal>\mathstrut</literal></title>
+
+<indexterm role="fn"><primary><literal>\mathstrut</literal></primary></indexterm>
+<indexterm role="cp"><primary>spacing, math mode</primary></indexterm>
+<indexterm role="cp"><primary>vertical spacing</primary></indexterm>
+<indexterm role="cp"><primary>math mode, spacing</primary></indexterm>
+<indexterm role="cp"><primary>invisible character</primary></indexterm>
+<indexterm role="cp"><primary>character, invisible</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\mathstrut
+</screen>
+<para>The analogue of <literal>\strut</literal> for mathematics. See <link linkend="_005cstrut">\strut</link>.
+</para>
+<para>The input <literal>$\sqrt{x} + \sqrt{x^i}$</literal> gives output where the
+second radical is taller than the first. To add extra vertical space
+without any horizontal space, so that the two have the same height, use
+<literal>$\sqrt{x\mathstrut} + \sqrt{x^i\mathstrut}$</literal>.
+</para>
+<para>The <literal>\mathstrut</literal> command adds the vertical height of an open
+parenthesis, <literal>(</literal>, but no horizontal space. It is defined as
+<literal>\vphantom{(}</literal>, so see <link linkend="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom">\phantom &amp; \vphantom &amp; \hphantom</link> for
+more. An advantage over <literal>\strut</literal> is that <literal>\mathstrut</literal> adds no
+depth, which is often the right thing for formulas. Using the height of
+an open parenthesis is just a convention; for complete control over the
+amount of space, use <literal>\rule</literal> with a width of zero. See <link linkend="_005crule">\rule</link>.
+</para>
+
+</sect2>
</sect1>
<sect1 label="16.7" id="Math-miscellany">
<title>Math miscellany</title>
@@ -11227,9 +12697,8 @@ some that don&#8217;t fit into other categories.
<sect2 label="16.7.1" id="Colon-character-_0026-_005ccolon">
<title>Colon character <literal>:</literal> &amp; <literal>\colon</literal></title>
-<indexterm role="cp"><primary>:</primary></indexterm>
<indexterm role="cp"><primary>colon character</primary></indexterm>
-<indexterm role="fn"><primary>:</primary></indexterm>
+<indexterm role="fn"><primary>: for math</primary></indexterm>
<indexterm role="fn"><primary>\colon</primary></indexterm>
<para>Synopsis, one of:
@@ -11299,52 +12768,7 @@ mode it comes out small; see the discussion of <literal>\displaystyle</literal>
</para>
</sect2>
-<sect2 label="16.7.4" id="_005cleft-_0026-_005cright">
-<title><literal>\left</literal> &amp; <literal>\right</literal></title>
-
-<indexterm role="cp"><primary>delimiters, paired</primary></indexterm>
-<indexterm role="cp"><primary>paired delimiters</primary></indexterm>
-<indexterm role="cp"><primary>matching parentheses</primary></indexterm>
-<indexterm role="cp"><primary>matching brackets</primary></indexterm>
-<indexterm role="cp"><primary>null delimiter</primary></indexterm>
-<indexterm role="fn"><primary>\left</primary></indexterm>
-<indexterm role="fn"><primary>\right</primary></indexterm>
-
-<para>Synopsis:
-</para>
-<screen>\left <replaceable>delimiter1</replaceable> ... \right <replaceable>delimiter2</replaceable>
-</screen>
-<para>Make matching parentheses, braces, or other delimiters. The delimiters
-are sized according to the math they enclose. This makes a unit vector
-surrounded by appropriate-height parentheses.
-</para>
-<screen>\begin{equation}
- \left(\begin{array}{c}
- 1 \\
- 0 \\
- \end{array}\right)
-</screen>
-<para>Every <literal>\left</literal> must have a matching <literal>\right</literal>. Leaving out the
-<literal>\left(</literal> in the above gets &#8216;<literal>Extra \right</literal>&#8217;. Leaving off the
-<literal>\right)</literal> gets &#8216;<literal>You can't use `\eqno' in math mode</literal>&#8217;.
-</para>
-<para>However, the two delimiters <replaceable>delimiter1</replaceable> and <replaceable>delimiter2</replaceable> need
-not match. A common case is that you want an unmatched brace, as
-below. Use a period, &#8216;<literal>.</literal>&#8217;, as a null delimiter.
-</para>
-<screen>\begin{equation}
- f(n)=\left\{\begin{array}{ll}
- 1 &amp;\mbox{--if \(n=0\)} \\
- f(n-1)+3n^2 &amp;\mbox{--else}
- \end{array}\right.
-\end{equation}
-</screen>
-<para>Note that to get a curly brace as a delimiter you must prefix it with a
-backslash, <literal>\{</literal>.
-</para>
-
-</sect2>
-<sect2 label="16.7.5" id="_005csqrt">
+<sect2 label="16.7.4" id="_005csqrt">
<title><literal>\sqrt</literal></title>
<indexterm role="cp"><primary>square root</primary></indexterm>
@@ -11368,7 +12792,7 @@ a large enough <literal>arg</literal>, it is vertical).
</para>
</sect2>
-<sect2 label="16.7.6" id="_005cstackrel">
+<sect2 label="16.7.5" id="_005cstackrel">
<title><literal>\stackrel</literal></title>
<indexterm role="cp"><primary>stack math</primary></indexterm>
@@ -11509,7 +12933,7 @@ styles. See its documentation on CTAN.
</screen>
<para>Generate a title. In the standard classes the title appears on a
separate page, except in the <literal>article</literal> class where it is at the top
-of the first page. (See <link linkend="Document-class-options">Document class options</link> for information about
+of the first page. (See <link linkend="Document-class-options">Document class options</link>, for information about
the <literal>titlepage</literal> document class option.)
</para>
<para>This example shows <literal>\maketitle</literal> appearing in its usual place,
@@ -11823,7 +13247,7 @@ measurement such as points (see <link linkend="Lengths_002fem">Lengths/em</link>
\qquad\includegraphics{mensmile.png}
\end{center}
</screen>
-<para>See <link linkend="Spacing-in-math-mode">Spacing in math mode</link> for <literal>\quad</literal> and <literal>\qquad</literal>. These
+<para>See <link linkend="Spacing-in-math-mode">Spacing in math mode</link>, for <literal>\quad</literal> and <literal>\qquad</literal>. These
are lengths from centuries of typesetting and so may be a better choice
in many circumstances than arbitrary lengths, such as you get with
<literal>\hspace</literal>.
@@ -12095,7 +13519,7 @@ The second causes spacing between sentences to stretch or shrink more
space between sentences (or spaces following a question mark,
exclamation point, comma, or colon) more than the space between words
that are in the middle of a sentence. Declaring <literal>\frenchspacing</literal>
-(the command is from Plain &tex;) switches to the tradition that all
+(the command is from plain &tex;) switches to the tradition that all
spaces are treated equally.
</para>
@@ -12121,7 +13545,9 @@ spaces are treated equally.
<indexterm role="cp"><primary>\NEWLINE</primary></indexterm>
<indexterm role="cp"><primary>\SPACE</primary></indexterm>
+<indexterm role="cp"><primary>\ (backslash-space)</primary></indexterm>
<indexterm role="cp"><primary>\TAB</primary></indexterm>
+<indexterm role="fn"><primary>\SPACE</primary></indexterm>
<para>This section refers to the command consisting of two characters, a
backslash followed by a space. Synopsis:
@@ -12156,7 +13582,7 @@ in <literal>\TeX\ is nice</literal>. (But using curly parentheses, as in
<literal>\TeX{} is best</literal>, has the advantage of still working if the next
character is a period.) The other common use is that it marks a period
as ending an abbreviation instead of ending a sentence, as in <literal>So
-says Prof.\ Smith</literal> (see <link linkend="_005c_0040">\@</link>).
+says Prof.\ Smith</literal> or <literal>Jones et al.\ (1993)</literal> (see <link linkend="_005c_0040">\@</link>).
</para>
<para>Under normal circumstances, <literal>\</literal><keycap>tab</keycap> and <literal>\</literal><keycap>newline</keycap>
are equivalent to backslash-space, <literal>\ </literal>.
@@ -12172,8 +13598,9 @@ are equivalent to backslash-space, <literal>\ </literal>.
<indexterm role="fn"><primary>~</primary></indexterm>
<indexterm role="cp"><primary>tie</primary></indexterm>
-<indexterm role="cp"><primary>space, hard</primary></indexterm>
<indexterm role="cp"><primary>space, unbreakable</primary></indexterm>
+<indexterm role="cp"><primary>hard space</primary></indexterm>
+<indexterm role="cp"><primary>unbreakable space</primary></indexterm>
<indexterm role="cp"><primary>NBSP</primary></indexterm>
<para>Synopsis:
@@ -12192,16 +13619,21 @@ space has length 3.33333pt plus 1.66666pt minus
<para>In addition, despite the period, &latex; does not use the
end-of-sentence spacing (see <link linkend="_005c_0040">\@</link>).
</para>
-<para>Ties prevent the end of line separation of things where that could cause
-confusion. But they also reduce &latex;&#8217;s options when it breaks lines
-into paragraphs, so you can use too many. They are also matters of
-taste, sometimes alarmingly dogmatic taste, among readers. Nevertheless,
-here are some usage models, many of them from the &tex;book.
+<para>Ties prevent the end of line separation of things where that could
+cause confusion. They also still allow hyphenation (of either of the
+tied words), so they are generally preferable to putting consecutive
+words in an <literal>\mbox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link>).
+</para>
+<para>They are also matters of taste, sometimes alarmingly dogmatic taste,
+among readers. Nevertheless, here are some usage models, many of them
+from <citetitle>The &tex;book</citetitle>.
</para>
<itemizedlist><listitem><para>Between an enumerator and its item, such as in references:
<literal>Chapter~12</literal>, or <literal>Theorem~\ref{th:Wilsons}</literal>, or
-<literal>Figure~\ref{fig:KGraph}</literal>. When cases are enumerated inline:
-<literal>(b)~Show that $f(x)$ is (1)~continuous, and (2)~bounded</literal>.
+<literal>Figure~\ref{fig:KGraph}</literal>.
+</para>
+</listitem><listitem><para>When cases are enumerated inline: <literal>(b)~Show that $f(x)$ is
+(1)~continuous, and (2)~bounded</literal>.
</para>
<indexterm role="cp"><primary>package, <literal>siunitx</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>siunitx</literal> package</primary></indexterm>
@@ -12209,10 +13641,12 @@ here are some usage models, many of them from the &tex;book.
</listitem><listitem><para>Between a number and its unit: <literal>$745.7.8$~watts</literal> (the
<filename>siunitx</filename> package has a special facility for this) or
<literal>144~eggs</literal>. This includes between a month and a date:
-<literal>October~12</literal> or <literal>12~Oct</literal>. In general, in any expressions where
-numbers and abbreviations or symbols are separated by a space:
+<literal>October~12</literal> or <literal>12~Oct</literal>. In general, in any expressions
+where numbers and abbreviations or symbols are separated by a space:
<literal>AD~565</literal>, or <literal>2:50~pm</literal>, or <literal>Boeing~747</literal>, or
-<literal>268~Plains Road</literal>, or <literal>\$$1.4$~billion</literal>.
+<literal>268~Plains Road</literal>, or <literal>\$$1.4$~billion</literal>. Other common
+choices here are a thin space (see <link linkend="_005cthinspace-_0026-_005cnegthinspace">\thinspace &amp; \negthinspace</link>) and
+no space at all.
</para>
</listitem><listitem><para>When mathematical phrases are rendered in words: <literal>equals~$n$</literal>, or
<literal>less than~$\epsilon$</literal>, or <literal>given~$X$</literal>, or <literal>modulo~$p^e$
@@ -12226,13 +13660,11 @@ common with~$m$</literal>.
</listitem><listitem><para>Between symbols in series: <literal>$1$,~$2$, or~$3$</literal> or <literal>$1$,~$2$,
\ldots,~$n$</literal>.
</para>
-</listitem><listitem><para>Between a person&#8217;s forenames and between multiple surnames:
+</listitem><listitem><para>Between a person&#8217;s given names and between multiple surnames:
<literal>Donald~E. Knuth</literal>, or <literal>Luis~I. Trabb~Pardo</literal>, or
-<literal>Charles~XII</literal> (but you must give TeX places to break the line so
-you may do <literal>Charles Louis Xavier~Joseph de~la Vall\'ee~Poussin</literal>).
-</para>
-</listitem><listitem><para>Before a dash: <literal>pages 12~--14</literal> or <literal>it is~--- it must be
-said~--- plausible</literal>.
+<literal>Charles~XII</literal>&#8212;but you must give &tex; places to break the line
+so you might do <literal>Charles Louis Xavier~Joseph de~la
+Vall\'ee~Poussin</literal>.
</para>
</listitem></itemizedlist>
@@ -12252,23 +13684,29 @@ said~--- plausible</literal>.
<screen>\thinspace
\negthinspace
</screen>
-<para>Produce an unbreakable and unstretchable space of 1/6em and
--1/6em. These are the text mode equivalents of <literal>\,</literal> and
-<literal>\!</literal> (see <link linkend="Spacing-in-math-mode_002f_005cthinspace">Spacing in math mode/\thinspace</link>). You can use
-<literal>\,</literal> as a synonym for <literal>\thinspace</literal> in text mode.
+<para>These produce unbreakable and unstretchable spaces of 1/6em and
+-1/6em, respectively. These are the text mode equivalents of
+<literal>\,</literal> and <literal>\!</literal> (see <link linkend="Spacing-in-math-mode_002f_005cthinspace">Spacing in math mode/\thinspace</link>).
</para>
-<para>The <literal>\negthinspace</literal> command is used in text mode mostly for
-fiddling with spaces. One common use of <literal>\thinspace</literal> is as the
-space between nested quotes.
+<para>You can use <literal>\,</literal> as a synonym for <literal>\thinspace</literal> in text mode.
+</para>
+<para>One common use of <literal>\thinspace</literal> is as the space between nested
+quotes:
</para>
<screen>Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace''
</screen>
<para>Another use is that some style guides call for a <literal>\thinspace</literal>
between an ellipsis and a sentence ending period (other style guides,
-though, think the three dots are quite enough already). Still another
-use is between initials, as in <literal>D.\thinspace E.\ Knuth</literal>.
+think the three dots and/or four dots are plenty). Another
+style-specific use is between initials, as in <literal>D.\thinspace E.\
+Knuth</literal>.
+</para>
+<para>&latex; provides a variety of similar spacing commands
+(see <link linkend="Spacing-in-math-mode">Spacing in math mode</link>). With <literal>amsmath</literal>, or as of the
+2020-10-01 &latex; release, they can be used in text mode as well as
+math mode, including <literal>\!</literal> for <literal>\negthinspace</literal>; before that,
+they were available only in math mode.
</para>
-
</sect1>
<sect1 label="19.9" id="_005c_002f">
<title><literal>\/</literal></title>
@@ -12281,32 +13719,45 @@ use is between initials, as in <literal>D.\thinspace E.\ Knuth</literal>.
<screen><replaceable>before-character</replaceable>\/<replaceable>after-character</replaceable>
</screen>
<para>Insert an <firstterm>italic correction</firstterm>, a small space defined by the font
-designer for each character, to avoid the character colliding with
-whatever follows. When you use <literal>\/</literal>, &latex; takes the correction
-from the font metric file, scales it by any scaling that has been
-applied to the font, and then inserts that much horizontal space.
+designer for each character (possibly zero), to avoid the character
+colliding with whatever follows. When you use <literal>\/</literal>, &latex;
+takes the correction from the font metric file, scales it by any
+scaling that has been applied to the font, and then inserts that much
+horizontal space.
</para>
<para>Here, were it not for the <literal>\/</literal>, the <replaceable>before-character</replaceable>
italic&#160;f would hit the <replaceable>after-character</replaceable> roman&#160;H
</para>
<screen>\newcommand{\companylogo}{{\it f}\/H}
</screen>
-<para>because the italic letter leans far to the right.
+<para>because the italic letter f leans far to the right.
</para>
<para>If <replaceable>after-character</replaceable> is a period or comma then don&#8217;t insert an
-italic correction since those punctuation symbols have a very small
-height. However, with semicolons or colons as well as with normal
-letters, the italic correction can help.
+italic correction since those punctuation symbols are so low to the
+baseline already. However, with semicolons or colons, as well as with
+normal letters, the italic correction can help. It is typically used
+between a switch from italic or slanted fonts to an upright font.
+</para>
+<para>When you use commands such as <literal>\emph</literal> and <literal>\textit</literal> and
+<literal>\textsl</literal> to change fonts, &latex; automatically inserts the
+italic correction when needed (see <link linkend="Font-styles">Font styles</link>). However,
+declarations such as <literal>\em</literal> and <literal>\itshape</literal> and
+<literal>\slshape</literal> do not automatically insert italic corrections.
</para>
-<para>When you use commands such as <literal>\textit</literal> or <literal>\itshape</literal> to
-change fonts, &latex; will automatically insert any needed italic
-correction (see <link linkend="Font-styles">Font styles</link>).
+<para>Upright characters can also have an italic correction. An example
+where this is needed is the name <literal>pdf\/\TeX</literal>. However, most
+upright characters have a zero italic correction. Some font creators
+do not include italic correction values even for italic fonts.
</para>
-<para>Roman characters can also have an italic correction. An example is in
-the name <literal>pdf\/\TeX</literal>.
+<indexterm role="fn"><primary>\fontdimen1</primary></indexterm>
+<indexterm role="cp"><primary>font dimension, slant</primary></indexterm>
+<para>Technically, &latex; uses another font-specific value, the so-called
+slant parameter (namely <literal>\fontdimen1</literal>), to determine whether to
+possibly insert an italic correction, rather than tying the action to
+particular font commands.
</para>
-<para>There is no concept of italic correction in math mode; spacing is done
-in a different way.
+<para>There is no concept of italic correction in math mode; math spacing is
+done in a different way.
</para>
</sect1>
@@ -12566,7 +14017,7 @@ or <literal>minus</literal> component (see <link linkend="Lengths">Lengths</link
\vspace{1ex plus 0.5ex}
The new day dawned cold.
</screen>
-<para>(See <link linkend="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip">\bigskip &amp; \medskip &amp; \smallskip</link> for common inter-paragraph
+<para>(See <link linkend="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip">\bigskip &amp; \medskip &amp; \smallskip</link>, for common inter-paragraph
spaces.)
</para>
<para>The <literal>*</literal>-version inserts vertical space that non-discardable. More
@@ -12676,7 +14127,7 @@ The two rules here are 22pt apart: the sum of the
<para>Now uncomment the second <literal>\addvspace</literal>. It does not make the gap
20pt longer; instead the gap is the sum of <literal>\baselineskip</literal>
and 20pt. So <literal>\addvspace</literal> in a sense does the opposite of
-its name &#8212; it makes sure that multiple vertical spaces do not
+its name&#8212;it makes sure that multiple vertical spaces do not
accumulate, but instead that only the largest one is used.
</para>
<para>&latex; uses this command to adjust the vertical space above or below
@@ -12702,6 +14153,9 @@ with a <literal>\par</literal> command (see <link linkend="_005cpar">\par</link>
<para>At its core, &latex; puts things in boxes and then puts the boxes on a
page. So these commands are central.
</para>
+<indexterm role="cp"><primary>package, <literal>adjustbox</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>adjustbox</literal> package</primary></indexterm>
+
<para>There are many packages on CTAN that are useful for manipulating boxes.
One useful adjunct to the commands here is <filename>adjustbox</filename>.
</para>
@@ -12730,11 +14184,11 @@ LR mode (see <link linkend="Modes">Modes</link>) so it is not broken into lines.
</para>
<para>Because <literal>text</literal> is not broken into lines, you can use <literal>\mbox</literal>
to prevent hyphenation. In this example, &latex; will not hyphenate
-the table name, &#8216;<literal>T-4</literal>&#8217;.
+the tank name, &#8216;<literal>T-34</literal>&#8217;.
</para>
-<screen>See Table~\mbox{T-4}
+<screen>The soviet tank \mbox{T-34} is a symbol of victory against nazism.
</screen>
-<para>The first two command versions, <literal>\mbox</literal> and <literal>\makebox</literal>, are
+<para>The first two command synopsis versions, <literal>\mbox</literal> and <literal>\makebox</literal>, are
roughly equivalent. They create a box just wide enough to contain the
<replaceable>text</replaceable>. (They are like plain &tex;&#8217;s <literal>\hbox</literal>.)
</para>
@@ -12757,7 +14211,7 @@ size you can say this.
</para>
<screen>\makebox[2\width]{Get a stretcher}
</screen>
-<para>For the fourth command version the optional argument <replaceable>position</replaceable>
+<para>For the fourth command synopsis version the optional argument <replaceable>position</replaceable>
gives position of the text within the box. It may take the following
values:
</para>
@@ -12791,12 +14245,11 @@ puts the value of the quiz questions to the left of those questions.
<indexterm role="cp"><primary>package, <literal>Asymptote</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>Asymptote</literal> package</primary></indexterm>
-<para>The right edge of the output &#8216;<literal>10 points </literal>&#8217; (note the ending space)
-will be just before the &#8216;<literal>What</literal>&#8217; (note the space after
-&#8216;<literal>points</literal>&#8217;). You can use <literal>\makebox</literal> similarly when making
-graphics, such as in <filename>TikZ</filename> or <filename>Asymptote</filename>, where you put the
-edge of the text at a known location, regardless of the length of that
-text.
+<para>The right edge of the output &#8216;<literal>10 points </literal>&#8217; (note the ending space
+after &#8216;<literal>points</literal>&#8217;) will be just before the &#8216;<literal>What</literal>&#8217;. You can use
+<literal>\makebox</literal> similarly when making graphics, such as in <filename>TikZ</filename>
+or <filename>Asymptote</filename>, where you put the edge of the text at a known
+location, regardless of the length of that text.
</para>
<para>For boxes with frames see&#160;<link linkend="_005cfbox-_0026-_005cframebox">\fbox &amp; \framebox</link>. For colors
see&#160;<link linkend="Colored-boxes">Colored boxes</link>.
@@ -12805,11 +14258,12 @@ see&#160;<link linkend="Colored-boxes">Colored boxes</link>.
<literal>picture</literal> environment, where the length is given in terms of
<literal>\unitlength</literal> (see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link>).
</para>
-<para>If you put a double-backslash into <replaceable>text</replaceable> then &latex; will not
-give you a new line; for instance <literal>\makebox{abc def \\ ghi}</literal>
-outputs &#8216;<literal>abc defghi</literal>&#8217; while <literal>\makebox{abc def \par ghi}</literal>
-outputs &#8216;<literal>abc def ghi</literal>&#8217;, but neither go to a second line. To get
-multiple lines see&#160;<link linkend="_005cparbox">\parbox</link> and&#160;<link linkend="minipage">minipage</link>.
+<para>As <replaceable>text</replaceable> is typeset in LR mode, neither a double backslash
+<literal>\\</literal> nor <literal>\par</literal> will give you a new line; for instance
+<literal>\makebox{abc def \\ ghi}</literal> outputs &#8216;<literal>abc defghi</literal>&#8217; while
+<literal>\makebox{abc def \par ghi}</literal> outputs &#8216;<literal>abc def ghi</literal>&#8217;, both on
+a single line. To get multiple lines see&#160;<link linkend="_005cparbox">\parbox</link>
+and&#160;<link linkend="minipage">minipage</link>.
</para>
</sect1>
@@ -12841,7 +14295,7 @@ a frame.
<literal>\framebox{...}</literal>, are roughly the same. As to the third and
fourth invocations, the optional arguments allow you to specify the box
width as <replaceable>width</replaceable> and the position of the text inside that box as
-<replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link> for the full description but
+<replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link>, for the full description but
here is an example creating an empty box that is 1/4in wide.
</para>
<screen>\setlength{\fboxsep}{0pt}\framebox[0.25in]{\strut}}
@@ -12884,7 +14338,7 @@ paragraph, and then frame the result.
And if you wish to go anywhere you must run twice as fast as that.
\end{minipage}}
</screen>
-<para>See <link linkend="Colored-boxes">Colored boxes</link> for colors other than black and white.
+<para>See <link linkend="Colored-boxes">Colored boxes</link>, for colors other than black and white.
</para>
<para>The <literal>picture</literal> environment has a version of this command where the
units depend on <literal>picture</literal>&#8217;s <literal>\unitlength</literal> (see <link linkend="_005cframebox-_0028picture_0029">\framebox
@@ -12933,10 +14387,10 @@ in that box. It should not have any paragraph-making components.
</para>
<para>There are three optional arguments, <replaceable>position</replaceable>, <replaceable>height</replaceable>, and
<replaceable>inner-pos</replaceable>. The <replaceable>position</replaceable> gives the vertical alignment of the
-<literal>parbox</literal> with respect to the surrounding material. The possible
+<firstterm>parbox</firstterm> with respect to the surrounding material. The supported
values are <literal>c</literal> or <literal>m</literal> to make the vertical center of the
-<literal>parbox</literal> lines up with the center of the adjacent line (this is the
-default), or <literal>t</literal> to match the top line of the <literal>parbox</literal> with
+parbox lines up with the center of the adjacent text line (this is the
+default), or <literal>t</literal> to match the top line of the parbox with
the baseline of the surrounding material, or <literal>b</literal> to match the
bottom line.
</para>
@@ -12965,11 +14419,11 @@ stretchable space).
</screen>
<para>Raise or lower <replaceable>text</replaceable>. This command is fragile (see <link linkend="_005cprotect">\protect</link>).
</para>
-<para>This example makes a command for the restriction of a function by
-lowering the vertical bar symbol.
+<para>This example makes a command for denoting the restriction of a function
+by lowering the vertical bar symbol.
</para>
<!-- credit: egreg https://tex.stackexchange.com/a/278631/121234 -->
-<screen>\newcommand\restricted[1]{\raisebox{-.5ex}{$|$}_{#1}}
+<screen>\newcommand*\restricted[1]{\raisebox{-.5ex}{$|$}_{#1}}
$f\restricted{A}$
</screen>
<para>The first mandatory argument <replaceable>distance</replaceable> specifies how far to raise
@@ -12991,7 +14445,7 @@ depth).
<para>This will align two graphics on their top (see <link linkend="Graphics">Graphics</link>).
</para>
<!-- credit: FAQ https://texfaq.org/FAQ-topgraph -->
-<screen>\usepackage{graphicx} \usepackage{calc} % in preamble
+<screen>\usepackage{graphicx,calc} % in preamble
...
\begin{center}
\raisebox{1ex-\height}{%
@@ -13022,44 +14476,44 @@ second is the height of <filename>meta.png</filename>.
</screen>
<para>Typeset <replaceable>text</replaceable> just as with <literal>\makebox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp;
\makebox</link>) except that &latex; does not output it but instead saves it
-in a storage bin named <replaceable>box-cmd</replaceable>. The bin name <replaceable>box-cmd</replaceable> begins
-with a backslash, <literal>\</literal>. You must have previously allocated the bin
-<replaceable>box-cmd</replaceable> with <literal>\newsavebox</literal> (see <link linkend="_005cnewsavebox">\newsavebox</link>).The
-<literal>\sbox</literal> command is robust while <literal>\savebox</literal> is fragile
-(see <link linkend="_005cprotect">\protect</link>).
+in a box register referred to by a variable named <replaceable>box-cmd</replaceable>. The
+variable name <replaceable>box-cmd</replaceable> begins with a backslash, <literal>\</literal>. You must
+have previously allocated the box register <replaceable>box-cmd</replaceable> with <literal>\newsavebox</literal>
+(see <link linkend="_005cnewsavebox">\newsavebox</link>). The <literal>\sbox</literal> command is robust while
+<literal>\savebox</literal> is fragile (see <link linkend="_005cprotect">\protect</link>).
</para>
-<para>This creates and uses a bin.
+<para>This creates and uses a box register.
</para>
<screen>\newsavebox{\fullname}
\sbox{\fullname}{John Jacob Jingleheimer Schmidt}
...
\usebox{\fullname}! His name is my name, too!
Whenever we go out, the people always shout!
-There goes \\usebox{\fullname}! Ya da da da da da da.
+There goes \usebox{\fullname}! Ya da da da da da da.
</screen>
-<para>One advantage of using and reusing a bin over a <literal>\newcommand</literal> is
-efficiency, that &latex; need not repeatedly retypeset the contents.
-See the example below.
+<para>One advantage of using and reusing a box register over a
+<literal>\newcommand</literal> macro variable is efficiency, that &latex; need not
+repeatedly retypeset the contents. See the example below.
</para>
<para>The first two command invocations,
<literal>\sbox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>}</literal> and
<literal>\savebox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>}</literal>, are roughly equivalent.
As to the third and fourth, the optional arguments allow you to specify
the box width as <replaceable>width</replaceable>, and the position of the text inside that
-box as <replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link> for the full
+box as <replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link>, for the full
description.
</para>
<para>In the <literal>\sbox</literal> and <literal>\savebox</literal> commands the <replaceable>text</replaceable> is
typeset in LR mode so it does not have line breaks (see <link linkend="Modes">Modes</link>). If
you use these then &latex; doesn&#8217;t give you an error but it ignores
-what you want: if you enter <literal>\sbox{\newbin}{test \\ test}</literal> and
-<literal>\usebox{\newbin}</literal> then you get &#8216;<literal>testtest</literal>&#8217;, while if you
-enter <literal>\sbox{\newbin}{test \par test}</literal> and
-<literal>\usebox{\newbin}</literal> then you get &#8216;<literal>test test</literal>&#8217;, but no error or
+what you want: if you enter <literal>\sbox{\newreg}{test \\ test}</literal> and
+<literal>\usebox{\newreg}</literal> then you get &#8216;<literal>testtest</literal>&#8217;, while if you
+enter <literal>\sbox{\newreg}{test \par test}</literal> and
+<literal>\usebox{\newreg}</literal> then you get &#8216;<literal>test test</literal>&#8217;, but no error or
warning. To fix this use a <literal>\parbox</literal> or <literal>minipage</literal> as here.
</para>
<!-- credit: egreg https://tex.stackexchange.com/a/41668/121234 -->
-<screen>\savebox{\abin}{%
+<screen>\savebox{\areg}{%
\begin{minipage}{\linewidth}
\begin{enumerate}
\item First item
@@ -13067,15 +14521,15 @@ warning. To fix this use a <literal>\parbox</literal> or <literal>minipage</lit
\end{enumerate}
\end{minipage}}
...
-\usebox{\abin}
+\usebox{\areg}
</screen>
-<para>As an example of the efficiency of reusing a bin&#8217;s contents, this puts
+<para>As an example of the efficiency of reusing a register&#8217;s contents, this puts
the same picture on each page of the document by putting it in the
header. &latex; only typesets it once.
</para>
<screen>\usepackage{graphicx} % all this in the preamble
-\newsavebox{\sealbin}
-\savebox{\sealbin}{%
+\newsavebox{\sealreg}
+\savebox{\sealreg}{%
\setlength{\unitlength}{1in}%
\begin{picture}(0,0)%
\put(1.5,-2.5){%
@@ -13085,13 +14539,13 @@ header. &latex; only typesets it once.
\end{tabular}}
\end{picture}%
}
-\markright{\usebox{\sealbin}}
+\markright{\usebox{\sealreg}}
\pagestyle{headings}
</screen>
<para>The <literal>picture</literal> environment is good for fine-tuning the placement.
</para>
-<para>If the bin has not already been defined then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \nobin</literal>&#8217;.
+<para>If the register <literal>\noreg</literal> has not already been defined then you get something like
+&#8216;<literal>Undefined control sequence. &lt;argument&gt; \noreg</literal>&#8217;.
</para>
</sect1>
@@ -13106,25 +14560,26 @@ header. &latex; only typesets it once.
<replaceable>text</replaceable>
\end{lrbox}
</screen>
-<para>The <replaceable>text</replaceable> inside the environment is saved in the bin
-<literal><replaceable>box-cmd</replaceable></literal>. The <replaceable>box-cmd</replaceable> must begin with a
-backslash. You must create this bin in advance with <literal>\newsavebox</literal>
-(see <link linkend="_005cnewsavebox">\newsavebox</link>). This is the environment form of the <literal>\sbox</literal>
-and <literal>\savebox</literal> commands, and is equivalent to them. See <link linkend="_005csbox-_0026-_005csavebox">\sbox &amp;
-\savebox</link> for the full information.
+<para>This is the environment form of the <literal>\sbox</literal> and <literal>\savebox</literal>
+commands, and is equivalent to them. for the full description,
+See <link linkend="_005csbox-_0026-_005csavebox">\sbox &amp; \savebox</link>.
</para>
-<para>In this example the environment is convenient for entering the
-<literal>tabular</literal>.
+<para>The <replaceable>text</replaceable> inside the environment is saved in the box register
+referred to by variable <literal><replaceable>box-cmd</replaceable></literal>. The variable name
+<replaceable>box-cmd</replaceable> must begin with a backslash, <literal>\</literal>. You must allocate
+this box register in advance with <literal>\newsavebox</literal>
+(see <link linkend="_005cnewsavebox">\newsavebox</link>). In this example the environment is convenient
+for entering the <literal>tabular</literal>.
</para>
-<screen>\newsavebox{\jhbin}
-\begin{lrbox}{\jhbin}
+<screen>\newsavebox{\jhreg}
+\begin{lrbox}{\jhreg}
\begin{tabular}{c}
\includegraphics[height=1in]{jh.png} \\
Jim Hef{}feron
\end{tabular}
\end{lrbox}
...
-\usebox{\jhbin}
+\usebox{\jhreg}
</screen>
</sect1>
@@ -13138,11 +14593,11 @@ and <literal>\savebox</literal> commands, and is equivalent to them. See <link l
</para>
<screen>\usebox{<replaceable>box-cmd</replaceable>}
</screen>
-<para>Produce the box most recently saved in the bin <replaceable>box-cmd</replaceable> by the
-commands <literal>\sbox</literal> or <literal>\savebox</literal>, or the <literal>lrbox</literal>
-environment. See <link linkend="_005csbox-_0026-_005csavebox">\sbox &amp; \savebox</link> for more information and examples.
-(Note that <replaceable>box-cmd</replaceable> starts with a backslash.) This command is
-robust (see <link linkend="_005cprotect">\protect</link>).
+<para>Produce the box most recently saved in the box register <replaceable>box-cmd</replaceable> by
+the commands <literal>\sbox</literal> or <literal>\savebox</literal>, or the <literal>lrbox</literal>
+environment. For more information and examples, See <link linkend="_005csbox-_0026-_005csavebox">\sbox &amp;
+\savebox</link>. (Note that the variable name <replaceable>box-cmd</replaceable> starts with a
+backslash, <literal>\</literal>.) This command is robust (see <link linkend="_005cprotect">\protect</link>).
</para>
</sect1>
@@ -13365,9 +14820,9 @@ but sometimes you want a one-off. Those are the second forms in the
synopses.
</para>
<screen>Colors of \textcolor[rgb]{0.33,0.14,0.47}{Purple} and
-{\color[rgb]{0.72,0.60,0.37} Gold} for the team.
+{\color[rgb]{0.72,0.60,0.37}Gold} for the team.
</screen>
-<para>The format of <replaceable>color specification </replaceable> depends on the color model
+<para>The format of <replaceable>color specification</replaceable> depends on the color model
(see <link linkend="Color-models">Color models</link>). For instance, while <literal>rgb</literal> takes three
numbers, <literal>gray</literal> takes only one.
</para>
@@ -13545,7 +15000,7 @@ rectangle (unless another size is specified in the
<literal>\includegraphics</literal> command).
</para>
</listitem></varlistentry><varlistentry><term><literal>draft</literal>
-</term><listitem><para>For each graphic file, it is not shown but instead the file name is
+</term><listitem><para>For each graphic file, it is not shown but instead its file name is
printed in a box of the correct size. In order to determine the size,
the file must be present.
</para>
@@ -13580,11 +15035,6 @@ option has &latex; to read the size from the latter.
<indexterm role="cp"><primary>graphics</primary></indexterm>
<indexterm role="cp"><primary>graphics package</primary></indexterm>
<indexterm role="cp"><primary>configuration, graphics package</primary></indexterm>
-<indexterm role="cp"><primary>EPS files</primary></indexterm>
-<indexterm role="cp"><primary>JPEG files</primary></indexterm>
-<indexterm role="cp"><primary>JPG files</primary></indexterm>
-<indexterm role="cp"><primary>PDF graphic files</primary></indexterm>
-<indexterm role="cp"><primary>PNG files</primary></indexterm>
<para>These commands configure the way &latex; searches the file system for
the graphic.
@@ -13604,15 +15054,16 @@ the documentation in <filename>grfguide.pdf</filename>, or the &latex; source, o
<para>Synopsis:
</para>
-<screen>\graphicspath{<replaceable>list of dir names inside curly brackets</replaceable>}
+<screen>\graphicspath{<replaceable>list of directories inside curly braces</replaceable>}
</screen>
<para>Declare a list of directories to search for graphics files. This allows
you to later say something like <literal>\includegraphics{lion.png}</literal>
instead of having to give its path.
</para>
-<para>&latex; always looks for graphic files first in the current directory.
-The declaration below tells the system to then look in the subdirectory
-<filename>pix</filename>, and then <filename>../pix</filename>.
+<para>&latex; always looks for graphic files first in the current directory
+(and the output directory, if specified; see <link linkend="output-directory">output directory</link>).
+The declaration below tells the system to then look in the
+subdirectory <filename>pix</filename>, and then <filename>../pix</filename>.
</para>
<screen>\usepackage{graphicx} % or graphics; put in preamble
...
@@ -13642,7 +15093,7 @@ current directory,
\usepackage{lion.png}
</screen>
<para>for each of the listed directories, &latex; concatenates it with the
-file name and searches for the result, checking for <filename>pix/lion.png</filename>
+filename and searches for the result, checking for <filename>pix/lion.png</filename>
and then <filename>../pix/lion.png</filename>. This algorithm means that the
<literal>\graphicspath</literal> command does not recursively search subdirectories:
if you issue <literal>\graphicspath{{a/}}</literal> and the graphic is in
@@ -13688,7 +15139,7 @@ files.
...
\includegraphics{lion} % will find <filename>lion.png</filename> before <filename>lion.pdf</filename>
</screen>
-<para>Because the file name <filename>lion</filename> does not have a period, &latex; uses
+<para>Because the filename <filename>lion</filename> does not have a period, &latex; uses
the extension list. For each directory in the graphics path
(see <link linkend="_005cgraphicspath">\graphicspath</link>), &latex; will try the extensions in the order
given. If it does not find such a file after trying all the directories
@@ -13704,8 +15155,13 @@ platform is not case sensitive.
your document; the printer driver has a sensible default. For example,
the most recent <filename>pdftex.def</filename> has this extension list.
</para>
-<screen>.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2
+<screen>.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2
</screen>
+<indexterm role="cp"><primary>package, <literal>grfext</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>grfext</literal> package</primary></indexterm>
+
+<para>To change the order, use the <literal>grfext</literal> package.
+</para>
<para>You can use this command anywhere in the document. You can use it more
than once. Show its value with
<literal>\makeatletter\typeout{\Gin@extensions}\makeatother</literal>.
@@ -13743,7 +15199,7 @@ extension not covered by another rule, so it covers <filename>filename.1</filena
<variablelist><varlistentry><term><replaceable>extension</replaceable>
</term><listitem><para>The file extension to which this rule applies. The extension is anything
after and including the first dot in the filename. Use the Kleene star,
-<literal>*</literal>, to denote the default behaviour for all undeclared extensions.
+<literal>*</literal>, to denote the default behavior for all undeclared extensions.
</para>
</listitem></varlistentry><varlistentry><term><replaceable>type</replaceable>
</term><listitem><para>The type of file involved. This type is a string that must be defined
@@ -13773,7 +15229,7 @@ other format is available.)
</para>
</listitem></varlistentry><varlistentry><term><replaceable>command</replaceable>
</term><listitem><para>A command that will be applied to the
-file. This is very often left blank. This command must start with a
+file. This is very often left empty. This command must start with a
single backward quote. Thus,
<literal>\DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c
#1}</literal> specifies that any file with the extension <filename>.eps.gz</filename> should
@@ -13853,10 +15309,10 @@ is <literal>\includegraphics{&quot;sister picture.jpg&quot;}</literal>.
</para>
<para>The <literal>\includegraphics{<replaceable>filename</replaceable>}</literal> command decides on the
type of graphic by splitting <replaceable>filename</replaceable> on the first dot. You can
-use <replaceable>filename</replaceable> with no dot, as in <literal>\includegraphics{turing}</literal>
-and then &latex; tries a sequence of extensions such as <literal>.png</literal> and
-<literal>.pdf</literal> until it finds a file with that extension
-(see <link linkend="_005cDeclareGraphicsExtensions">\DeclareGraphicsExtensions</link>).
+instead use <replaceable>filename</replaceable> with no dot, as in
+<literal>\includegraphics{turing}</literal>, and then &latex; tries a sequence of
+extensions such as <literal>.png</literal> and <literal>.pdf</literal> until it finds a file
+with that extension (see <link linkend="_005cDeclareGraphicsExtensions">\DeclareGraphicsExtensions</link>).
</para>
<para>If your file name contains dots before the extension then you can hide
them with curly braces, as in
@@ -13865,7 +15321,7 @@ the <filename>graphicx</filename> package then you can use the options <literal>
<literal>ext</literal>; see below. This and other filename issues are also handled
with the package <filename>grffile</filename>.
</para>
-<para>This example puts a graphic in a figure environment so &latex; can
+<para>This example puts a graphic in a <literal>figure</literal> environment so &latex; can
move it to the next page if fitting it on the current page is awkward
(see <link linkend="figure">figure</link>).
</para>
@@ -13931,8 +15387,10 @@ two will end with different widths and heights.
</para>
<para>There are many options. The primary ones are listed first.
</para>
+<indexterm role="cp"><primary>bounding box</primary></indexterm>
+<indexterm role="cp"><primary>box, bounding</primary></indexterm>
<para>Note that a graphic is placed by &latex; into a box, which is
-traditionally referred to as its bounding box (distinct from the
+traditionally referred to as its <firstterm>bounding box</firstterm> (distinct from the
PostScript BoundingBox described below). The graphic&#8217;s printed area may
go beyond this box, or sit inside this box, but when &latex; makes up a
page it puts together boxes and this is the box allocated for the
@@ -13944,7 +15402,7 @@ is <literal>\includegraphics[width=1in]{plot}</literal>. You can use the standa
&tex; dimensions (see <link linkend="Units-of-length">Units of length</link>) and also convenient is
<literal>\linewidth</literal>, or in a two-column document, <literal>\columnwidth</literal>
(see <link linkend="Page-layout-parameters">Page layout parameters</link>). An example is that by using the
-<filename>calc</filename> package you can make the graphic be 1&#160;cm narrow than
+<filename>calc</filename> package you can make the graphic be 1&#160;cm narrower than
the width of the text with
<literal>\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}</literal>.
</para>
@@ -13957,7 +15415,7 @@ layout parameters</link>). For instance, the command
graphic a quarter of the height of the text area.
</para>
</listitem></varlistentry><varlistentry><term><literal>totalheight</literal>
-</term><listitem><anchor id="includegraphics-totalheght"/><para>The graphic will be shown so its bounding box has this height plus
+</term><listitem><anchor id="includegraphics-totalheight"/><para>The graphic will be shown so its bounding box has this height plus
depth. This differs from the height if the graphic was rotated. For
instance, if it has been rotated by -90 then it will have zero height
but a large depth.
@@ -13976,7 +15434,7 @@ is the graphic wider than <literal>width</literal> nor taller than <literal>heig
</listitem></varlistentry><varlistentry><term><literal>scale</literal>
</term><listitem><para>Factor by which to scale the graphic. To make a graphic twice its
nominal size, enter <literal>\includegraphics[scale=2.0]{...}</literal>. This
-number may be any value; a number between 1 and&#160;0 will shrink the
+number may be any value; a number between 0 and&#160;1 will shrink the
graphic and a negative number will reflect it.
</para>
</listitem></varlistentry><varlistentry><term><literal>angle</literal>
@@ -14005,10 +15463,10 @@ vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default
<variablelist><anchor id="includegraphics-viewport"/><varlistentry><term><literal>viewport</literal>
</term><listitem><para>Pick out a subregion of the graphic to show. Takes four arguments,
separated by spaces and given in &tex; dimensions, as with
-<literal>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</literal>. The
-dimensions default to big points,&#160;<literal>bp</literal>. They are taken
-relative to the origin specified by the bounding box. See also the
-<literal>trim</literal> option.
+<literal>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</literal>. When
+the unit is omitted, the dimensions default to big
+points,&#160;<literal>bp</literal>. They are taken relative to the origin specified
+by the bounding box. See also the <literal>trim</literal> option.
</para>
<anchor id="includegraphics-trim"/></listitem></varlistentry><varlistentry><term><literal>trim</literal>
</term><listitem><para>Gives parts of the graphic to not show. Takes four arguments, separated
@@ -14055,7 +15513,7 @@ set with <literal>interpolate=true</literal> or just specified as here.
<anchor id="includegraphics-quiet"/></listitem></varlistentry><varlistentry><term><literal>quiet</literal>
</term><listitem><para>Do not write information to the log. You can set it with
<literal>quiet=true</literal> or just specified it with
-<literal>\includegraphics[...,quite,...]{...}</literal>,
+<literal>\includegraphics[...,quiet,...]{...}</literal>,
</para>
<anchor id="includegraphics-draft"/></listitem></varlistentry><varlistentry><term><literal>draft</literal>
</term><listitem><para>If you set it with <literal>draft=true</literal> or just specify it with
@@ -14127,7 +15585,7 @@ Only use this in conjunction with the option <literal>type</literal>.
</para>
<anchor id="includegraphics-command"/></listitem></varlistentry><varlistentry><term><literal>command</literal>
</term><listitem><para>Specify a command to be applied to this file. Only use this in
-conjunction with the option <literal>type</literal>. See <link linkend="Command-line-options">Command line options</link>
+conjunction with the option <literal>type</literal>. See <link linkend="Command-line-options">Command line options</link>,
for a discussion of enabling the <literal>\write18</literal> functionality to run
external commands.
</para>
@@ -14154,7 +15612,7 @@ external commands.
<para>Put <replaceable>material</replaceable> in a box and rotate it <replaceable>angle</replaceable> degrees
counterclockwise.
</para>
-<para>This example rotates the table column heads forty five degrees.
+<para>This example rotates the table column heads forty-five degrees.
</para>
<screen>\begin{tabular}{ll}
\rotatebox{45}{Character} &amp;\rotatebox{45}{NATO phonetic} \\
@@ -14316,7 +15774,8 @@ special meaning do not correspond to simple characters you can type.
<indexterm role="cp"><primary>characters, special</primary></indexterm>
<para>&latex; sets aside the following characters for special purposes. For
example, the percent sign&#160;<literal>%</literal> is for comments. They are
-called <firstterm>reserved characters</firstterm> or <firstterm>special characters</firstterm>.
+called <firstterm>reserved characters</firstterm> or <firstterm>special characters</firstterm>. They are
+all discussed elsewhere in this manual.
</para>
<screen># $ % &amp; { } _ ~ ^ \
</screen>
@@ -14337,13 +15796,13 @@ typing <literal>\$1.23</literal> will produce&#160;<literal>$1.23</literal> in y
<indexterm role="fn"><primary>\textbackslash</primary></indexterm>
<para>As to the last three characters, to get a tilde in the text body font
use <literal>\~{}</literal> (omitting the curly braces would result in the next
-character receiving a tilde accent). Similarly, to get a get a text
-body font circumflex use <literal>\^{}</literal>. To get a backslash in the font
-of the text body, enter <literal>\textbackslash{}</literal>.
+character receiving a tilde accent). Similarly, to get a text body
+font circumflex use <literal>\^{}</literal>. To get a backslash in the font of
+the text body, enter <literal>\textbackslash{}</literal>.
</para>
<para>To produce the reserved characters in a typewriter font use
<literal>\verb!!</literal> as below (the double backslash&#160;<literal>\\</literal> is only
-there to split the lines).
+there to split the lines in the output).
</para>
<screen>\begin{center}
\# \$ \% \&amp; \{ \} \_ \~{} \^{} \textbackslash \\
@@ -14358,6 +15817,7 @@ there to split the lines).
<indexterm role="cp"><primary>uppercase</primary></indexterm>
<indexterm role="cp"><primary>lowercase</primary></indexterm>
<indexterm role="cp"><primary>characters, case of</primary></indexterm>
+<indexterm role="cp"><primary>changing case of characters</primary></indexterm>
<para>Synopsis:
</para>
@@ -14366,13 +15826,13 @@ there to split the lines).
\MakeUppercase{<replaceable>text</replaceable>}
\MakeLowercase{<replaceable>text</replaceable>}
</screen>
-<para>Change the case of characters. The &tex; primitives commands
-<literal>\uppercase</literal> and <literal>\lowercase</literal> only work for American
-characters. The &latex; commands <literal>\MakeUppercase</literal> and
-<literal>\MakeLowercase</literal> commands also change characters accessed by
-commands such as <literal>\ae</literal> or <literal>\aa</literal>. The commands
-<literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> are robust but they have
-moving arguments (see <link linkend="_005cprotect">\protect</link>).
+<para>Change the case of characters. The &tex; primitive commands
+<literal>\uppercase</literal> and <literal>\lowercase</literal> are set up by default to work
+only with the 26 letters a&#8211;z and A&#8211;Z. The &latex; commands
+<literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> commands also change
+characters accessed by commands such as <literal>\ae</literal> or <literal>\aa</literal>. The
+commands <literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> are robust
+but they have moving arguments (see <link linkend="_005cprotect">\protect</link>).
</para>
<para>These commands do not change the case of letters used in the name of a
command within <replaceable>text</replaceable>. But they do change the case of every other
@@ -14405,10 +15865,23 @@ standard &latex; commands <literal>\MakeUppercase</literal> and
</para>
<indexterm role="cp"><primary>package, <literal>mfirstuc</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>mfirstuc</literal> package</primary></indexterm>
-
+
<para>To uppercase only the first letter of words, you can use the package
<filename>mfirstuc</filename>.
</para>
+<indexterm role="cp"><primary>package, <literal>expl3</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>expl3</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>Wright, Joseph</primary></indexterm>
+<para>Handling all the casing rules specified by Unicode, e.g., for
+non-Latin scripts, is a much bigger job than anything envisioned in
+the original &tex; and &latex;. It has been implemented in the
+<literal>expl3</literal> package as of 2020. The article &#8220;Case changing: From
+&tex; primitives to the Unicode algorithm&#8221;, (Joseph Wright,
+<citetitle>TUGboat</citetitle>&#160;41:1,
+<ulink url="https://tug.org/TUGboat/tb41-1/tb127wright-case.pdf">https://tug.org/TUGboat/tb41-1/tb127wright-case.pdf</ulink>), gives a
+good overview of the topic, past and present.
+</para>
</sect1>
<sect1 label="23.3" id="Symbols-by-font-position">
@@ -14420,13 +15893,14 @@ standard &latex; commands <literal>\MakeUppercase</literal> and
<para>You can access any character of the current font using its number with
the <literal>\symbol</literal> command. For example, the visible space character
-used in the <literal>\verb*</literal> command has the code decimal 32, so it can be
-typed as <literal>\symbol{32}</literal>.
+used in the <literal>\verb*</literal> command has the code decimal 32 in the
+standard Computer Modern typewriter font, so it can be typed as
+<literal>\symbol{32}</literal>.
</para>
<para>You can also specify numbers in octal (base 8) by using a <literal>'</literal>
-prefix, or hexadecimal (base 16) with a <literal>&quot;</literal> prefix, so the previous
-example could also be written as <literal>\symbol{'40}</literal> or
-<literal>\symbol{&quot;20}</literal>.
+prefix, or hexadecimal (base 16) with a <literal>&quot;</literal> prefix, so the
+visible space at 32 decimal could also be written as
+<literal>\symbol{'40}</literal> or <literal>\symbol{&quot;20}</literal>.
</para>
</sect1>
@@ -14437,10 +15911,13 @@ example could also be written as <literal>\symbol{'40}</literal> or
<indexterm role="cp"><primary>symbols, text</primary></indexterm>
<indexterm role="fn"><primary>textcomp package</primary></indexterm>
-<para>&latex; provides commands to generate a number of non-letter symbols in
-running text. Some of these, especially the more obscure ones, are not
-available in OT1. Unless you are using Xe&latex; or Lua&latex; then
-you may need to load the <literal>textcomp</literal> package.
+<indexterm role="cp"><primary>TS1 encoding</primary></indexterm>
+<para>&latex; provides commands to generate a number of non-letter symbols
+in running text. Some of these, especially the more obscure ones, are
+not available in OT1. As of the &latex; February 2020 release, all
+symbols are available by default; before that, it was necessary to use
+the <literal>textcomp</literal> package for some (technically, those in the
+<literal>TS1</literal> font encoding).
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\copyright</primary></indexterm><literal>\copyright</literal>
</term><term><indexterm role="fn"><primary>\textcopyright</primary></indexterm><literal>\textcopyright</literal>
@@ -14560,7 +16037,7 @@ Double and single quotation marks on the baseline.
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbigcircle</primary></indexterm><literal>\textbigcircle</literal>
</term><listitem><indexterm role="cp"><primary>big circle symbols, in text</primary></indexterm>
<indexterm role="cp"><primary>circle symbol, big, in text</primary></indexterm>
-<para>&#x25EF; Big circle symbol.
+<para>&#x25EF;, Big circle symbol.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbraceleft</primary></indexterm><literal>\textbraceleft</literal>
</term><listitem><indexterm role="cp"><primary>left brace, in text</primary></indexterm>
@@ -14578,7 +16055,7 @@ Double and single quotation marks on the baseline.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textcircled{<replaceable>letter</replaceable>}</primary></indexterm><literal>\textcircled{<replaceable>letter</replaceable>}</literal>
</term><listitem><indexterm role="cp"><primary>circled letter, in text</primary></indexterm>
-<para>&#x24B6; Circle around <replaceable>letter</replaceable>.
+<para>&#x24B6;, Circle around <replaceable>letter</replaceable>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textcompwordmark</primary></indexterm><literal>\textcompwordmark</literal>
</term><term><indexterm role="fn"><primary>\textcapitalcompwordmark</primary></indexterm><literal>\textcapitalcompwordmark</literal>
@@ -14608,13 +16085,14 @@ while the <literal>\textascendercompwordmark</literal> form has the ascender hei
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textemdash (or <literal>---</literal>)</primary></indexterm><literal>\textemdash (or <literal>---</literal>)</literal>
</term><listitem><indexterm role="cp"><primary>em-dash</primary></indexterm>
-<para>&#8212; Em-dash (used for punctuation, as in
-<literal>The playoffs --- if you are fortunate enough to make the playoffs ---
-is more like a sprint.</literal>).
+<para>&#8212; Em-dash. Used for punctuation, usually similar to commas or
+parentheses, as in &#8216;<literal>The playoffs---if you're lucky
+enough to make the playoffs---are more like a sprint.</literal>&#8217; Conventions
+for spacing around em-dashes vary widely.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textendash (or <literal>--</literal>)</primary></indexterm><literal>\textendash (or <literal>--</literal>)</literal>
</term><listitem><indexterm role="cp"><primary>e-dash</primary></indexterm>
-<para>&#8211; En-dash (used for ranges, as in <literal>See pages 12--14</literal>).
+<para>&#8211; En-dash. Used for ranges, as in &#8216;<literal>see pages 12--14</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texteuro</primary></indexterm><literal>\texteuro</literal>
</term><listitem><indexterm role="cp"><primary>euro symbol</primary></indexterm>
@@ -14622,7 +16100,11 @@ is more like a sprint.</literal>).
<indexterm role="cp"><primary>package, <literal>eurosym</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>eurosym</literal> package</primary></indexterm>
-<para>The Euro symbol: &#8364;. For an alternative glyph design, try the
+<para>The Euro currency symbol: &#8364;.
+<indexterm role="cp"><primary>package, <literal>eurosym</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>eurosym</literal> package</primary></indexterm>
+</para>
+<para>For an alternative glyph design, try the
<filename>eurosym</filename> package; also, most fonts nowadays come with their own
Euro symbol (Unicode U+20AC).
</para>
@@ -14630,10 +16112,24 @@ Euro symbol (Unicode U+20AC).
</term><listitem><indexterm role="cp"><primary>exclamation point, upside-down</primary></indexterm>
<para>&#161; Upside down exclamation point.
</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textfiguredash</primary></indexterm><literal>\textfiguredash</literal>
+</term><listitem><indexterm role="cp"><primary>figure dash character</primary></indexterm>
+<para>Dash used between numerals, Unicode U+2012. Defined in the June 2021
+release of &latex;. When used in pdf&tex;, approximated by an
+en-dash; with a Unicode engine, either typesets the glyph if available
+in the current font, or writes the usual &#8220;Missing character&#8221; warning
+to the log file.
+</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textgreater</primary></indexterm><literal>\textgreater</literal>
</term><listitem><indexterm role="cp"><primary>greater than symbol, in text</primary></indexterm>
<para>&gt; Greater than symbol.
</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texthorizontalbar</primary></indexterm><literal>\texthorizontalbar</literal>
+</term><listitem><indexterm role="cp"><primary>horizontal bar character</primary></indexterm>
+<para>Horizontal bar character, Unicode U+2015. Defined in the June 2021
+release of &latex;. Behavior as with <literal>\textfiguredash</literal> above;
+the pdf&tex; approximation is an em-dash.
+</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textless</primary></indexterm><literal>\textless</literal>
</term><listitem><indexterm role="cp"><primary>less than symbol, in text</primary></indexterm>
<para>&lt; Less than symbol.
@@ -14641,7 +16137,15 @@ Euro symbol (Unicode U+20AC).
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textleftarrow</primary></indexterm><literal>\textleftarrow</literal>
</term><listitem><indexterm role="cp"><primary>arrow, left, in text</primary></indexterm>
<indexterm role="cp"><primary>left arrow, in text</primary></indexterm>
-<para>&#x2190; Left arrow.
+<para>&#x2190;, Left arrow.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textnonbreakinghyphen</primary></indexterm><literal>\textnonbreakinghyphen</literal>
+</term><listitem><indexterm role="cp"><primary>non-breaking hyphen character</primary></indexterm>
+<indexterm role="cp"><primary>hyphen character, non-breaking</primary></indexterm>
+<para>Non-breaking hyphen character, Unicode U+2011. Defined in the June
+2021 release of &latex;. Behavior as with <literal>\textfiguredash</literal>
+above; the pdf&tex; approximation is a regular ASCII hyphen (with
+breaks disallowed after).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textordfeminine</primary></indexterm><literal>\textordfeminine</literal>
</term><term><indexterm role="fn"><primary>\textordmasculine</primary></indexterm><literal>\textordmasculine</literal>
@@ -14684,7 +16188,7 @@ Euro symbol (Unicode U+20AC).
</term><listitem><indexterm role="cp"><primary>quote, single straight</primary></indexterm>
<indexterm role="cp"><primary>straight single quote</primary></indexterm>
<indexterm role="cp"><primary>single quote, straight</primary></indexterm>
-<para>&#x0027; Straight single quote. (From TS1 encoding.)
+<para>&#x0027;, Straight single quote. (From TS1 encoding.)
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotestraightbase</primary></indexterm><literal>\textquotestraightbase</literal>
</term><term><indexterm role="fn"><primary>\textquotestraightdblbase</primary></indexterm><literal>\textquotestraightdblbase</literal>
@@ -14702,12 +16206,12 @@ Euro symbol (Unicode U+20AC).
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textrightarrow</primary></indexterm><literal>\textrightarrow</literal>
</term><listitem><indexterm role="cp"><primary>arrow, right, in text</primary></indexterm>
<indexterm role="cp"><primary>right arrow, in text</primary></indexterm>
-<para>&#x2192; Right arrow.
+<para>&#x2192;, Right arrow.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textthreequartersemdash</primary></indexterm><literal>\textthreequartersemdash</literal>
</term><listitem><indexterm role="cp"><primary>three-quarters em-dash</primary></indexterm>
<indexterm role="cp"><primary>em-dash, three-quarters</primary></indexterm>
-<para>&#xFE58; &#8220;Three-quarters&#8221; em-dash, between en-dash and em-dash.
+<para>&#xFE58;, &#8220;Three-quarters&#8221; em-dash, between en-dash and em-dash.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttrademark</primary></indexterm><literal>\texttrademark</literal>
</term><listitem><indexterm role="cp"><primary>trademark symbol</primary></indexterm>
@@ -14717,7 +16221,7 @@ Euro symbol (Unicode U+20AC).
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttwelveudash</primary></indexterm><literal>\texttwelveudash</literal>
</term><listitem><indexterm role="cp"><primary>two-thirds em-dash</primary></indexterm>
<indexterm role="cp"><primary>em-dash, two-thirds</primary></indexterm>
-<para>&#xFE58; &#8220;Two-thirds&#8221; em-dash, between en-dash and em-dash.
+<para>&#xFE58;, &#8220;Two-thirds&#8221; em-dash, between en-dash and em-dash.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textunderscore</primary></indexterm><literal>\textunderscore</literal>
</term><listitem><indexterm role="cp"><primary>underscore, in text</primary></indexterm>
@@ -14725,7 +16229,7 @@ Euro symbol (Unicode U+20AC).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textvisiblespace</primary></indexterm><literal>\textvisiblespace</literal>
</term><listitem><indexterm role="cp"><primary>visible space symbol, in text</primary></indexterm>
-<para>&#x2423; Visible space symbol.
+<para>&#x2423;, Visible space symbol.
</para>
</listitem></varlistentry></variablelist>
@@ -14744,13 +16248,16 @@ Euro symbol (Unicode U+20AC).
<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm>
<indexterm role="cp"><primary>multilingual support</primary></indexterm>
-<para>&latex; has wide support for many of the world&#8217;s scripts and languages,
-through the <literal>babel</literal> package and related support if you are using
-pdf&latex;, or <filename>polyglossia</filename> if you are using Xe&latex; or
-Lua&latex;. This section does not cover that support. It only lists
-the core &latex; commands for creating accented characters. The
-<literal>\capital...</literal> commands shown here produce alternative forms for use
-with capital letters. These are not available with OT1.
+<para>&latex; has wide support for many of the world&#8217;s scripts and
+languages, provided through the core <literal>babel</literal> package, which
+supports pdf&latex;, Xe&latex; and Lua&latex;. The
+<filename>polyglossia</filename> package provides similar support with the latter
+two engines.
+</para>
+<para>This section does not cover that support. It only lists the core
+&latex; commands for creating accented characters. The
+<literal>\capital...</literal> commands shown here produce alternative forms for
+use with capital letters. These are not available with OT1.
</para>
<para>Below, to make them easier to find, the accents are all illustrated with
lowercase &#8216;<literal>o</literal>&#8217;.
@@ -14896,6 +16403,54 @@ its box.
</para>
</listitem></varlistentry></variablelist>
+
+<sect2 label="23.5.1" id="_005caccent">
+<title><literal>\accent</literal></title>
+<indexterm role="fn"><primary>\accent</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\accent <replaceable>number</replaceable> <replaceable>character</replaceable>
+</screen>
+<para>A &tex; primitive command used to generate accented characters from
+accent marks and letters. The accent mark is selected by <replaceable>number</replaceable>,
+a numeric argument, followed by a space and then a <replaceable>character</replaceable> argument
+constructs the accented character in the current font.
+</para>
+<para>These are accented &#8216;<literal>e</literal>&#8217; characters.
+</para>
+<screen>\accent18 e
+\accent20 e
+\accent21 e
+\accent22 e
+\accent23 e
+</screen>
+<para>The first is a grave, the second is breve, etc.
+</para>
+<para>The position of the accent is determined by the font designer and so the
+outcome of <literal>\accent</literal> use may differ between fonts. In &latex; it is
+desirable to have glyphs for accented characters rather than building
+them using <literal>\accent</literal>. Using glyphs that already contain the
+accented characters (as in T1 encoding) allows correct hyphenation
+whereas <literal>\accent</literal> disables hyphenation (specifically with OT1 font
+encoding where accented glyphs are absent).
+</para>
+<para>There can be an optional font change between <replaceable>number</replaceable> and
+<replaceable>character</replaceable>. Note also that this command sets the
+<literal>\spacefactor</literal> to 1000 (see <link linkend="_005cspacefactor">\spacefactor</link>).
+</para>
+<para>An unavoidable characteristic of some Cyrillic letters and
+the majority of accented Cyrillic letters is that they must be
+assembled from multiple elements (accents, modifiers, etc.) while
+<literal>\accent</literal> provides for a single accent mark and a single letter
+combination. There are also cases where accents must appear between
+letters that \accent does not support. Still other cases exist where
+the letters I and J have dots above their lowercase counterparts that
+conflict with dotted accent marks. The use of <literal>\accent</literal> in these
+cases will not work as it cannot analyze upper/lower case.
+</para>
+
+</sect2>
</sect1>
<sect1 label="23.6" id="Additional-Latin-letters">
<title>Additional Latin letters</title>
@@ -14998,7 +16553,70 @@ font encoding, such as T1.
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="23.7" id="_005crule">
+<sect1 label="23.7" id="inputenc-package">
+<title><literal>inputenc</literal> package</title>
+
+<indexterm role="fn"><primary>inputenc</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\usepackage[<replaceable>encoding-name</replaceable>]{inputenc}
+</screen>
+<para>Declare the input file&#8217;s text encoding to be <replaceable>encoding-name</replaceable>. The
+default, if this package is not loaded, is UTF-8. Technically,
+specifying the encoding name is optional, but in practice it is not
+useful to omit it.
+</para>
+<indexterm role="cp"><primary>encoding, of input files</primary></indexterm>
+<indexterm role="cp"><primary>character encoding</primary></indexterm>
+<indexterm role="cp"><primary>Unicode</primary></indexterm>
+<para>In a computer file, the characters are stored according to a scheme
+called the <firstterm>encoding</firstterm>. There are many different encodings. The
+simplest is ASCII, which supports 95 printable characters, not enough
+for most of the world&#8217;s languages. For instance, to typeset the
+a-umlaut character &#228; in an ASCII-encoded &latex; source file, the
+sequence <literal>\&quot;a</literal> is used. This would make source files for anything
+but English hard to read; even for English, often a more extensive
+encoding is more convenient.
+</para>
+<para>The modern encoding standard, in some ways a union of the others, is
+UTF-8, one of the representations of Unicode. This is the default for
+&latex; since 2018.
+</para>
+<para>The <literal>inputenc</literal> package is how &latex; knows what encoding is
+used. For instance, the following command explicitly says that the
+input file is UTF-8 (note the lack of a dash).
+</para>
+<screen>\usepackage[utf8]{inputenc}
+</screen>
+<para>Caution: use <literal>inputenc</literal> only with the pdf&tex; engine
+(see <link linkend="TeX-engines">&tex; engines</link>). (The Xe&tex; and Lua&tex; engines assume
+that the input file is UTF-8 encoded.) If you invoke &latex; with
+either the <command>xelatex</command> command or the <command>lualatex</command>
+command, and try to declare a non-UTF-8 encoding with <literal>inputenc</literal>,
+such as <literal>latin1</literal>, then you will get the error <literal>inputenc is
+not designed for xetex or luatex</literal>.
+</para>
+<para>An <literal>inputenc</literal> package error such as <literal>Invalid UTF-8 byte &quot;96</literal>
+means that some of the material in the input file does not follow the
+encoding scheme. Often these errors come from copying material from a
+document that uses a different encoding than the input file; this one
+is a left single quote from a web page using <literal>latin1</literal> inside a
+&latex; input file that uses UTF-8. The simplest solution is to
+replace the non-UTF-8 character with its UTF-8 equivalent, or use a
+&latex; equivalent command or character.
+</para>
+<para>In some documents, such as a collection of journal articles from a
+variety of authors, changing the encoding in mid-document may be
+necessary. Use the command
+<literal>\inputencoding{<replaceable>encoding-name</replaceable>}</literal>. The most common values
+for <replaceable>encoding-name</replaceable> are: <literal>ascii</literal>, <literal>latin1</literal>,
+<literal>latin2</literal>, <literal>latin3</literal>, <literal>latin4</literal>, <literal>latin5</literal>,
+<literal>latin9</literal>, <literal>latin10</literal>, and&#160;<literal>utf8</literal>.
+</para>
+
+</sect1>
+<sect1 label="23.8" id="_005crule">
<title><literal>\rule</literal></title>
<indexterm role="fn"><primary>\rule</primary></indexterm>
@@ -15012,8 +16630,8 @@ font encoding, such as T1.
</para>
<indexterm role="cp"><primary>Halmos symbol</primary></indexterm>
<indexterm role="cp"><primary>tombstone</primary></indexterm>
-<para>This produces a rectangular blob, sometimes called a Halmos symbol,
-often used to mark the end of a proof.
+<para>This example produces a rectangular blob, sometimes called a Halmos symbol,
+or just &#8220;qed&#8221;, often used to mark the end of a proof:
</para>
<screen>\newcommand{\qedsymbol}{\rule{0.4em}{2ex}}
</screen>
@@ -15038,11 +16656,11 @@ thickness is common in &latex;.
</para>
<para>A rule that has zero width, or zero thickness, will not show up in the
output, but can cause &latex; to change the output around it.
-See <link linkend="_005cstrut">\strut</link> for examples.
+See <link linkend="_005cstrut">\strut</link>, for examples.
</para>
</sect1>
-<sect1 label="23.8" id="_005ctoday">
+<sect1 label="23.9" id="_005ctoday">
<title><literal>\today</literal></title>
<indexterm role="fn"><primary>\today</primary></indexterm>
@@ -15128,7 +16746,7 @@ a file with five included files.
<para>This will bring in material from <filename>pref.tex</filename>, <filename>chap1.tex</filename>,
<filename>chap2.tex</filename>, <filename>append.tex</filename>, and <filename>bib.tex</filename>. If you compile
this file, and then comment out all of the lines inside
-<literal>\includeonly{...}</literal> except for <literal>chap1,</literal> and compile again,
+<literal>\includeonly{...}</literal> except for <literal>chap1</literal>, and compile again,
then &latex; will only process the material in the first chapter.
Thus, your output will appear more quickly and be shorter to print.
However, the advantage of the <literal>\includeonly</literal> command is that
@@ -15136,7 +16754,7 @@ However, the advantage of the <literal>\includeonly</literal> command is that
information from the other parts of the document so these will appear in
your output correctly.
</para>
-<para>See <link linkend="Larger-book-template">Larger book template</link> for another example of <literal>\includeonly</literal>.
+<para>See <link linkend="Larger-book-template">Larger book template</link>, for another example of <literal>\includeonly</literal>.
</para>
@@ -15164,12 +16782,13 @@ This material will appear in the document.
This will not appear.
</screen>
<para>This can be useful for putting documentation or comments at the end of a
-file, or for avoiding junk characters that can be added during mailing.
-It is also useful for debugging: one strategy to localize errors is to
-put <literal>\endinput</literal> halfway through the included file and see if the
-error disappears. Now, knowing which half contains the error, moving
-<literal>\endinput</literal> to halfway through that area further narrows down the
-location. This process rapidly finds the offending line.
+file, or for avoiding junk characters that can be added if the file is
+transmitted in the body of an email. It is also useful for debugging:
+one strategy to localize errors is to put <literal>\endinput</literal> halfway
+through the included file and see if the error disappears. Now, knowing
+which half contains the error, moving <literal>\endinput</literal> to halfway
+through that area further narrows down the location. This process
+rapidly finds the offending line.
</para>
<para>After reading <literal>\endinput</literal>, &latex; continues to read to the end of
the line, so something can follow this command and be read nonetheless.
@@ -15201,10 +16820,12 @@ This allows you, for instance, to close an <literal>\if...</literal> with a
<literal>\clearpage</literal> (see <link linkend="_005cclearpage-_0026-_005ccleardoublepage">\clearpage &amp; \cleardoublepage</link>), then it
inputs the material from <filename><replaceable>filename</replaceable>.tex</filename> into the document,
and then it does another <literal>\clearpage</literal>. This command can only
-appear in the document body. The <literal>\includeonly</literal> command controls
-which files will be read by &latex; under subsequent <literal>\include</literal>
-commands. Its list of filenames is comma-separated, and it can only
-appear in the preamble.
+appear in the document body.
+</para>
+<para>The <literal>\includeonly</literal> command controls which files will be read by
+&latex; under subsequent <literal>\include</literal> commands. Its list of
+filenames is comma-separated. It must appear in the preamble or even
+earlier, e.g., the command line; it can&#8217;t appear in the document body.
</para>
<para>This example root document, <filename>constitution.tex</filename>, brings in
three files, <filename>preamble.tex</filename>, <filename>articles.tex</filename>, and
@@ -15233,7 +16854,7 @@ in Order to form a more perfect Union, ...
<para>Running &latex; on <filename>constitution.tex</filename> makes the material from the
three files appear in the document but also generates the auxiliary
files <filename>preamble.aux</filename>, <filename>articles.aux</filename>, and
-<filename>amendments.tex</filename>. These contain information such as page numbers
+<filename>amendments.aux</filename>. These contain information such as page numbers
and cross-references (see <link linkend="Cross-references">Cross references</link>). If you now comment out
<literal>\includeonly</literal>&#8217;s lines with <literal>preamble</literal> and <literal>amendments</literal>
and run &latex; again then the resulting document shows only the
@@ -15250,7 +16871,7 @@ commands.
<link linkend="_005cinput">\input</link> (which, however, does not retain the auxiliary
information).
</para>
-<para>See <link linkend="Larger-book-template">Larger book template</link> for another example using <literal>\include</literal>
+<para>See <link linkend="Larger-book-template">Larger book template</link>, for another example using <literal>\include</literal>
and <literal>\includeonly</literal>. That example also uses <literal>\input</literal> for some
material that will not necessarily start on a new page.
</para>
@@ -15301,8 +16922,8 @@ athiesm.tex.</literal>&#8217; (It will also create <filename>athiesm.aux</filen
<para>If you <literal>\include</literal> the root file in itself then you first get
&#8216;<literal>LaTeX Error: Can be used only in preamble.</literal>&#8217; Later runs get
&#8216;<literal>TeX capacity exceeded, sorry [text input levels=15]</literal>&#8217;. To fix
-this, you must remove the inclusion <literal>\include{root}</literal> but also
-delete the file <filename><replaceable>root</replaceable>.aux</filename> and rerun &latex;.
+this, you must remove the inclusion <literal>\include{<replaceable>root</replaceable>}</literal> but
+also delete the file <filename><replaceable>root</replaceable>.aux</filename> and rerun &latex;.
</para>
</sect1>
@@ -15395,7 +17016,7 @@ commands <literal>\chapter</literal>, etc.
</screen>
<para>Uncommenting the second line would cause that table to contain chapter
and section listings but not subsection listings, because the
-<literal>\section</literal> command has level&#160;1. See <link linkend="Sectioning">Sectioning</link> for level
+<literal>\section</literal> command has level&#160;1. See <link linkend="Sectioning">Sectioning</link>, for level
numbers of the sectioning units. For more on the <literal>tocdepth</literal>
see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>.
</para>
@@ -15406,7 +17027,7 @@ book template</link>.
<literal>\newpage</literal> command after the <literal>\tableofcontents</literal> command, as
above.
</para>
-<para>To make the table of contents &latex; stores the information in an
+<para>To make the table of contents, &latex; stores the information in an
auxiliary file named <filename><replaceable>root-file</replaceable>.toc</filename> (see <link linkend="Splitting-the-input">Splitting the
input</link>). For example, this &latex; file <filename>test.tex</filename>
</para>
@@ -15417,45 +17038,64 @@ input</link>). For example, this &latex; file <filename>test.tex</filename>
\subsection{First subsection}
...
</screen>
-<para>writes the following line to <filename>test.toc</filename>.
+<para>writes these lines to <filename>test.toc</filename>.
</para>
<screen>\contentsline {section}{\numberline {1}First section}{2}
\contentsline {subsection}{\numberline {1.1}First subsection}{2}
</screen>
-<para>The <literal>section</literal> or <literal>subsection</literal> is the sectioning unit. The
-hook <literal>\numberline</literal> lets you to change how the information appears
-in the table of contents. Of its two arguments, <literal>1</literal> or <literal>1.1</literal>
-is the sectioning unit number and <literal>First section</literal> or <literal>First
-subsection</literal> is the title. Finally, <literal>2</literal> is the page number on which
-the sectioning units start.
-</para>
-<para>One consequence of this auxiliary file storage strategy is that to get the
-contents page correct you must run &latex; twice, once to store the
-information and once to get it. In particular, the first time that you
-run &latex; on a new document, the table of contents page will be empty
-except for its &#8216;<literal>Contents</literal>&#8217; header. Just run it again.
+<indexterm role="fn"><primary>\contentsline</primary></indexterm>
+<para>Each line contains a single command, <literal>\contentsline</literal>
+(see <link linkend="_005ccontentsline">\contentsline</link>). The first argument, the <literal>section</literal> or
+<literal>subsection</literal>, is the sectioning unit. The second argument has two
+components. The hook <literal>\numberline</literal> determines how the sectioning
+number, <literal>1</literal> or <literal>1.1</literal>, appears in the table of contents
+(see <link linkend="_005cnumberline">\numberline</link>). The remainder of the second argument of
+<literal>\contentsline</literal>, &#8216;<literal>First section</literal>&#8217; or &#8216;<literal>First subsection</literal>&#8217;,
+is the sectioning title text. Finally, the third argument, &#8216;<literal>2</literal>&#8217;, is
+the page number on which this sectioning unit starts.
+</para>
+<para>To typeset these lines, the document class provides
+<literal>\l@<replaceable>section-unit</replaceable></literal> commands such as
+<literal>\l@section{<replaceable>text</replaceable>}{<replaceable>pagenumber</replaceable>}</literal> and
+<literal>\l@subsection{<replaceable>text</replaceable>}{<replaceable>pagenumber</replaceable>}</literal>. These commands
+often use the <literal>\@dottedtocline</literal> command
+(see <link linkend="_005c_0040dottedtocline">\@dottedtocline</link>).
+</para>
+<para>A consequence of &latex;&#8217;s strategy of using auxiliary files is that to
+get the correct information in the document you must run &latex; twice,
+once to store the information and the second time to retrieve it. In
+the ordinary course of writing a document authors run &latex; a number
+of times, but you may notice that the first time that you compile a new
+document, the table of contents page will be empty except for its
+&#8216;<literal>Contents</literal>&#8217; header. Just run &latex; again.
</para>
<para>The commands <literal>\listoffigures</literal> and <literal>\listoftables</literal> produce a
-list of figures and a list of tables. They work the same way as the
-contents commands; for instance, these work with information stored in
-<filename>.lof</filename> and <filename>.lot</filename> files.
-</para>
-<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm>
-
-<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm>
-
-<para>To change the header for the table of contents page do something like
-the first line here.
-</para>
-<screen>\renewcommand{\contentsname}{Table of contents}
-\renewcommand{\listfigurename}{Plots}
-\renewcommand{\listtablename}{Tables}
-</screen>
-<para>Similarly, the other two lines will do the other two.
-Internationalization packages such as <filename>babel</filename> or <filename>polyglossia</filename>
-will change the headers depending on the chosen base language.
+list of figures and a list of tables. Their information is stored in
+files with extension <filename>.lof</filename> and <filename>.lot</filename>. They work the same way
+as <literal>\tableofcontents</literal> but the latter is more common, so we use it
+for most examples.
+</para>
+<para>You can manually add material to the table of contents, the list of
+figures, and the list of tables. For instance, add a line about a
+section to the table of contents with
+<literal>\addcontentsline{toc}{section}{<replaceable>text</replaceable>}</literal>.
+(see <link linkend="_005caddcontentsline">\addcontentsline</link>). Add arbitrary material, that is, non-line
+material, with <literal>\addtocontents</literal>, as with the command
+<literal>\addtocontents{lof}{\protect\vspace{2ex}}</literal>, which adds
+vertical space to the list of figures (see <link linkend="_005caddtocontents">\addtocontents</link>).
+</para>
+<para>Lines in the table of contents, the list of figures, and the list of
+tables, have four parts. First is an indent. Next is a box into which
+sectioning numbers are placed, and then the third box holds the title
+text, such as &#8216;<literal>First section</literal>&#8217;. Finally there is a box up against
+the right margin, inside of which &latex; puts the page number box.
+For the indent and the width of the number box,
+see <link linkend="_005c_0040dottedtocline">\@dottedtocline</link>. The right margin box has width
+<literal>\@tocrmarg</literal> and the page number is flush right in that space,
+inside a box of width <literal>\@pnumwidth</literal>. By default
+<literal>\@tocrmarg</literal> is <literal>2.55em</literal> and <literal>\@pnumwidth</literal> is
+<literal>1.55em</literal>. Change these as with
+<literal>\renewcommand{\@tocrmarg}{3.5em}</literal>.
</para>
<indexterm role="cp"><primary>package, <literal>tocloft</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>tocloft</literal> package</primary></indexterm>
@@ -15464,14 +17104,71 @@ will change the headers depending on the chosen base language.
<indexterm role="cp"><primary><literal>tocbibbind</literal> package</primary></indexterm>
<para>CTAN has many packages for the table of contents and lists of figures
-and tables. One convenient one for adjusting some aspects of the
-default, such as spacing, is <filename>tocloft</filename>. And, <filename>tocbibbind</filename>
-will automatically add the bibliography, index, etc. to the table of
-contents.
+and tables (see <link linkend="CTAN">CTAN</link>). The package <filename>tocloft</filename> is convenient for
+adjusting some aspects of the default such as spacing. And,
+<filename>tocbibbind</filename> will automatically add the bibliography, index,
+etc. to the table of contents.
+</para>
+<para>To change the header for the table of contents page, do something like
+these commands before you call <literal>\tableofcontents</literal>, etc.
+</para>
+<screen>\renewcommand{\contentsname}{Table of Contents}
+\renewcommand{\listfigurename}{Plots}
+\renewcommand{\listtablename}{Specifications}
+</screen>
+<para><indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm>
+</para>
+<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm>
+
+<para>Internationalization packages such as <filename>babel</filename> or <filename>polyglossia</filename>
+will change these headers depending on the chosen base language.
</para>
-<sect2 label="25.1.1" id="_005caddcontentsline">
+<sect2 label="25.1.1" id="_005c_0040dottedtocline">
+<title><literal>\@dottedtocline</literal></title>
+
+<indexterm role="fn"><primary>\@dottedtocline</primary></indexterm>
+<indexterm role="cp"><primary>table of contents entry, create dotted line</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\@dottedtocline{<replaceable>section-level-num</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>numwidth</replaceable>}{<replaceable>text</replaceable>}{<replaceable>pagenumber</replaceable>}
+</screen>
+<para>Used internally by &latex; to format an entry line in the table of
+contents, list of figures, or list of tables. Authors do not directly
+enter <literal>\@dottedtocline</literal> commands.
+</para>
+<para>This command is typically used by <literal>\l@section</literal>, <literal>\l@subsection</literal>,
+etc., to format the content lines. For example, the <filename>article.cls</filename>
+file contains these definitions:
+</para>
+<screen>\newcommand*\l@section{\@dottedtocline{1}{1.5em}{2.3em}}
+\newcommand*\l@subsection{\@dottedtocline{2}{3.8em}{3.2em}}
+\newcommand*\l@subsubsection{\@dottedtocline{3}{7.0em}{4.1em}}
+</screen>
+<para>In this example, <literal>\@dottedcline</literal> appears to have been given only
+three arguments. But tracing the internal code shows that it picks up
+the final <replaceable>text</replaceable> and <replaceable>pagenumber</replaceable> arguments in the synopsis
+from a call to <literal>\contentsline</literal>.
+</para>
+<indexterm role="cp"><primary>leaders, dots in table of contents</primary></indexterm>
+<para>Between the box for the title text of a section and the right margin
+box, these <literal>\@dottedtocline</literal> commands insert <firstterm>leaders</firstterm>, that
+is, evenly-spaced dots. The dot-to-dot space is given by the command
+<literal>\@dotsep</literal>. By default it is 4.5 (it is in math units, which
+are <literal>1/18</literal>&#160;em. Change it using <literal>\renewcommand</literal>, as
+in <literal>\renewcommand{\@dotsep}{3.5}</literal>.
+</para>
+<para>In the default book class, &latex; does not use dotted leaders for
+the Part and Chapter table entries, and in the default article class
+it does not use dotted leaders for Section entries.
+</para>
+
+</sect2>
+<sect2 label="25.1.2" id="_005caddcontentsline">
<title><literal>\addcontentsline</literal></title>
<indexterm role="fn"><primary>\addcontentsline</primary></indexterm>
@@ -15482,9 +17179,7 @@ contents.
<screen>\addcontentsline{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}
</screen>
<indexterm role="fn"><primary>\contentsline</primary></indexterm>
-<para>Add an entry to the file specified by <replaceable>ext</replaceable>. Usually <replaceable>ext</replaceable> is
-one of <literal>toc</literal> for the table of contents, <literal>lof</literal> for the list of
-figures, or <literal>lot</literal> for the list of tables.
+<para>Add an entry to the auxiliary file with extension <replaceable>ext</replaceable>.
</para>
<para>The following will result in an &#8216;<literal>Appendices</literal>&#8217; line in the table of
contents.
@@ -15499,26 +17194,24 @@ where it appears in the input file.
<filename><replaceable>root-name</replaceable>.<replaceable>ext</replaceable></filename>. It writes that information as the
text of the command
<literal>\contentsline{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}{<replaceable>num</replaceable>}</literal>, where
-<literal><replaceable>num</replaceable></literal> is the current value of counter <literal><replaceable>unit</replaceable></literal>. The
-most common case is the table of contents and there <replaceable>num</replaceable> is the
-page number of the first page of <replaceable>unit</replaceable>.
+<literal><replaceable>num</replaceable></literal> is the current value of counter <literal><replaceable>unit</replaceable></literal>
+(see <link linkend="_005ccontentsline">\contentsline</link>). The most common case is the table of contents
+and there <replaceable>num</replaceable> is the page number of the first page of <replaceable>unit</replaceable>.
</para>
<para>This command is invoked by the sectioning commands <literal>\chapter</literal>,
etc., and also by <literal>\caption</literal> inside a float environment. But it is
-also used by authors. For example, in a book to have the preface
-unnumbered, you may use the starred <literal>\chapter*</literal>. But that does not
-put in table of contents information, so you can enter it manually, as
-here.
+also used by authors. For example, an author writing a book whose style
+is to have an unnumbered preface may use the starred <literal>\chapter*</literal>.
+But that command leaves out table of contents information, which can be
+entered manually, as here.
</para>
<screen>\chapter*{Preface}
\addcontentsline{toc}{chapter}{\protect\numberline{}Preface}
</screen>
<para>In the <filename>.toc</filename> file &latex; will put the line <literal>\contentsline
-{chapter}{\numberline {}Preface}{3}</literal>; note the page number
-&#8216;<literal>3</literal>&#8217;.
+{chapter}{\numberline {}Preface}{3}</literal>; note that the page number
+&#8216;<literal>3</literal>&#8217; is automatically generated by the system, not entered manually.
</para>
-<!-- xx how hardwired are these values? other unit names? -->
-
<para>All of the arguments for <literal>\addcontentsline</literal> are required.
</para>
<variablelist><varlistentry><term><replaceable>ext</replaceable>
@@ -15559,7 +17252,7 @@ will not make sense.
</para>
</sect2>
-<sect2 label="25.1.2" id="_005caddtocontents">
+<sect2 label="25.1.3" id="_005caddtocontents">
<title><literal>\addtocontents</literal></title>
<indexterm role="fn"><primary>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm>
@@ -15570,7 +17263,7 @@ will not make sense.
</screen>
<para>Add <replaceable>text</replaceable>, which may be text or formatting commands, directly to
the auxiliary file with extension <replaceable>ext</replaceable>. This is most commonly used
-for the table of contents so that is the discussion here, but this also
+for the table of contents so that is the discussion here, but it also
applies to the list of figures and list of tables.
</para>
<para>This will put some vertical space in the table of contents after the
@@ -15579,6 +17272,24 @@ applies to the list of figures and list of tables.
<screen>\tableofcontents\newpage
\addtocontents{toc}{\protect\vspace*{3ex}}
</screen>
+<para>This puts the word &#8216;<literal>Page</literal>&#8217;, in boldface, above the column of page
+numbers and after the header.
+</para>
+<screen>\tableofcontents
+\addtocontents{toc}{~\hfill\textbf{Page}\par}
+\chapter{...}
+</screen>
+<para>This adds a line announcing work by a new author.
+</para>
+<screen>\addtocontents{toc}{%
+ \protect\vspace{2ex}
+ \textbf{Chapters by N. Other Author}\par}
+</screen>
+<para>The difference between <literal>\addtocontents</literal> and <literal>\addcontentsline</literal>
+is that the latter is strictly for lines, such as with a line giving the
+page number for the start of a new subset of the chapters. As the above
+examples show, <literal>\addtocontents</literal> is for material such as spacing.
+</para>
<para>The <literal>\addtocontents</literal> command has two arguments. Both are
required.
</para>
@@ -15605,7 +17316,63 @@ move <literal>\addtocontents</literal> into the file being included.
</para>
</sect2>
-<sect2 label="25.1.3" id="_005cnofiles">
+<sect2 label="25.1.4" id="_005ccontentsline">
+<title><literal>\contentsline</literal></title>
+
+<indexterm role="cp"><primary>table of contents</primary></indexterm>
+<indexterm role="fn"><primary>\contentsline</primary></indexterm>
+<indexterm role="fn"><primary>\tableofcontents</primary></indexterm>
+<indexterm role="fn"><primary>.toc file</primary></indexterm>
+<indexterm role="fn"><primary>\listoffigures</primary></indexterm>
+<indexterm role="fn"><primary>\listoftables</primary></indexterm>
+<indexterm role="fn"><primary>.lof file</primary></indexterm>
+<indexterm role="fn"><primary>.lot file</primary></indexterm>
+<indexterm role="fn"><primary>\l@chapter</primary></indexterm>
+<indexterm role="fn"><primary>\l@section</primary></indexterm>
+<indexterm role="fn"><primary>\l@subsection</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\contentsline{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}{<replaceable>pagenumber</replaceable>}
+</screen>
+<para>Used internally by &latex; to typeset an entry of the table of
+contents, list of figures, or list of tables (see <link linkend="Table-of-contents-etc_002e">Table of contents
+etc.</link>). Authors do not directly enter <literal>\contentsline</literal> commands.
+</para>
+<para>Usually adding material to these lists is done automatically by the
+commands <literal>\chapter</literal>, <literal>\section</literal>, etc. for the table of
+contents, or by the <literal>\caption</literal> command inside of a <literal>\figure</literal>
+or <literal>\table</literal> environment (see <link linkend="figure">figure</link> and see <link linkend="table">table</link>). Thus,
+where the base file is <filename>thesis.tex</filename>, and contains the declaration
+<literal>\tableofcontents</literal>, the command <literal>\chapter{Chapter One}</literal>
+produces something like this in the file <filename>thesis.toc</filename>.
+</para>
+<screen>\contentsline {chapter}{\numberline {1}Chapter One}{3}
+</screen>
+<para>If the file contains the declaration <literal>\listoffigures</literal> then a figure
+environment involving <literal>\caption{Test}</literal> will produce
+something like this in <filename>thesis.lof</filename>.
+</para>
+<screen>\contentsline {figure}{\numberline {1.1}{\ignorespaces Test}}{6}
+</screen>
+<para>To manually add material, use
+<literal>\addcontentsline{<replaceable>filetype</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}</literal>,
+where <replaceable>filetype</replaceable> is <literal>toc</literal>, <literal>lof</literal>, or <literal>lot</literal>
+(see <link linkend="_005caddcontentsline">\addcontentsline</link>).
+</para>
+<para>For manipulating how the <literal>\contentline</literal> material is typeset, see
+the <filename>tocloft</filename> package.
+</para>
+<para>Note that the <literal>hyperref</literal> package changes the definition of
+<literal>\contentsline</literal> (and <literal>\addcontentsline</literal>) to add more
+arguments, to make hyperlinks. This is the source of the error
+<literal>Argument of \contentsline has an extra }</literal>. Fix this error by
+deleting the <filename>.toc</filename> or <filename>.lof</filename> or <filename>.lot</filename> file, and running
+&latex; again.
+</para>
+
+</sect2>
+<sect2 label="25.1.5" id="_005cnofiles">
<title><literal>\nofiles</literal></title>
<indexterm role="fn"><primary>\nofiles</primary></indexterm>
@@ -15635,6 +17402,41 @@ the old information.
</para>
</sect2>
+<sect2 label="25.1.6" id="_005cnumberline">
+<title><literal>\numberline</literal></title>
+
+<indexterm role="fn"><primary>\numberline</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\numberline{<replaceable>number</replaceable>}
+</screen>
+<para>Typeset its argument flush left in a box. This is used in a
+<literal>\contentsline</literal> command to typeset the section number
+(see <link linkend="_005ccontentsline">\contentsline</link>).
+</para>
+<para>For example, this line in a <filename>.toc</filename> file causes the <literal>1</literal> to be
+typeset flush left.
+</para>
+<screen>\contentsline {subsection}{\numberline {1.1}Motivation}{2}
+</screen>
+<para>By default, &latex; typesets the section numbers in a box of length
+<literal>\@tempdima</literal>. That length is set by the commands
+<literal>\l@section</literal>, <literal>\l@subsection</literal>, etc. Put section numbers
+inside a natural-width box with
+<literal>\renewcommand{\numberline}[1]{#1~}</literal>.
+</para>
+<para>This command is fragile, so you may need to precede it with
+<literal>\protect</literal> (see <link linkend="_005cprotect">\protect</link>). An example is the use of
+<literal>\protect</literal> in the command
+<literal>\addcontentsline{toc}{section}{\protect\numberline{}Summary}</literal>
+to get the <literal>\numberline</literal> into this command in the <filename>.toc</filename> file:
+<literal>\contentsline {section}{\numberline {}Summary}{6}</literal> (the
+page number &#8216;<literal>6</literal>&#8217; is automatically added by &latex;;
+see <link linkend="_005caddcontentsline">\addcontentsline</link>).
+</para>
+
+</sect2>
</sect1>
<sect1 label="25.2" id="Indexes">
<title>Indexes</title>
@@ -15678,12 +17480,15 @@ information back into your document and typeset it with the
<indexterm role="cp"><primary>package, <literal>multind</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>multind</literal> package</primary></indexterm>
-<para>There are many packages that apply to indexing commands. The
-<literal>showidx</literal> package causes each index entries to be shown in the
-margin on the page where the entry appears. This can help in preparing
-the index. The <literal>multind</literal> package supports multiple indexes. See
-also the &tex; FAQ entry on this topic,
-<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind</ulink>.
+<indexterm role="cp"><primary>index, multiple</primary></indexterm>
+<indexterm role="cp"><primary>multiple indexes</primary></indexterm>
+<para>There are many packages in the area of indexing. The <literal>showidx</literal>
+package causes each index entries to be shown in the margin on the
+page where the entry appears. This can help in preparing the index.
+The <literal>multind</literal> package, among others, supports multiple indexes.
+See also the &tex; FAQ entry on this topic,
+<ulink url="https://www.texfaq.org/FAQ-multind">https://www.texfaq.org/FAQ-multind</ulink>, and the CTAN topic,
+<ulink url="https://ctan.org/topic/index-multi">https://ctan.org/topic/index-multi</ulink>.
</para>
@@ -15746,7 +17551,7 @@ the output is the item &#8216;<literal>Jones</literal>&#8217; with no comma or p
followed by two subitems, like &#8216;<literal>program, 50</literal>&#8217; and &#8216;<literal>results,
51</literal>&#8217;.
</para>
-<indexterm role="cp"><primary>&#8216;see&#8217; and &#8216;see also&#8217; index entries</primary></indexterm>
+<indexterm role="cp"><primary>see and see also index entries</primary></indexterm>
<indexterm role="cp"><primary>index entries, &#8216;see&#8217; and &#8216;see also&#8217;</primary></indexterm>
<indexterm role="fn"><primary>\seename</primary></indexterm>
<indexterm role="fn"><primary>\alsoname</primary></indexterm>
@@ -15901,8 +17706,8 @@ formatted. Default: <literal>&quot;\\begin{theindex}\n&quot;</literal>.
<para>Traditionally index items are broken into groups, typically a group for
entries starting with &#8216;<literal>a</literal>&#8217;, etc. This specifier gives what is
inserted when a new group begins. Default: <literal>&quot;\n\n \\indexspace\n&quot;</literal>
-(<literal>\indexspace</literal> is a rubber length with default value <literal>10pt
-plus5pt minus3pt</literal>).
+(<literal>\indexspace</literal> is a command inserting a rubber length, by default
+<literal>10pt plus5pt minus3pt</literal>).
</para>
<anchor id="makeindex-letheadflag"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lethead_flag</primary></indexterm><literal>lethead_flag</literal>
</term><listitem><para>An integer. It governs what is inserted for a new group or letter. If
@@ -15993,14 +17798,18 @@ roman <literal>R</literal>, and uppercase alphabetic <literal>A</literal>. Defa
<literal>&quot;rnaRA&quot;</literal>.
</para>
</listitem></varlistentry></variablelist>
-<indexterm role="fn"><primary>xindy</primary></indexterm>
-<indexterm role="cp"><primary><command>xindy</command> program</primary></indexterm>
+<indexterm role="fn"><primary>xindy program</primary></indexterm>
<para>There are a number of other programs that do the job
-<command>makeindex</command> does. One is <command>xindy</command>, which does
-internationalization and can process indexes for documents marked up
-using &latex; and a number of other languages. It is highly
-configurable, both in markup terms and in terms of the collating order
-of the text, as described in its documentation.
+<command>makeindex</command> does. One is <command>xindy</command>
+(https://ctan.org/pkg/xindy), which does internationalization and can
+process indexes for documents marked up using &latex; and a number of
+other languages. It is written in Lisp, highly configurable, both in
+markup terms and in terms of the collating order of the text, as
+described in its documentation.
+</para>
+<indexterm role="fn"><primary>xindex program</primary></indexterm>
+<para>A more recent indexing program supporting Unicode is <literal>xindex</literal>,
+written in Lua (<ulink url="https://ctan.org/pkg/xindex">https://ctan.org/pkg/xindex</ulink>).
</para>
</sect2>
@@ -16020,7 +17829,7 @@ of the text, as described in its documentation.
<para>To get an index you must first include
<literal>\usepackage{makeidx}\makeindex</literal> in the document preamble and
compile the document, then run the system command <command>makeindex</command>,
-and then compile the document again. See <link linkend="Indexes">Indexes</link> for further
+and then compile the document again. See <link linkend="Indexes">Indexes</link>, for further
discussion and an example of the use of <literal>\printindex</literal>.
</para>
@@ -16115,7 +17924,7 @@ CTAN.
the document. The settings associated with the label are pairs:
<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>.
</para>
-<para>This puts the blackboard bold symbol for the real numbers &#x211D; in the
+<para>This puts the blackboard bold symbol for the real numbers &#x211D;, in the
glossary.
</para>
<screen>\newglossaryentry{R}
@@ -16528,24 +18337,6 @@ the document. To have it apply to one letter only, put it inside a
(see <link linkend="Graphics">Graphics</link>).
</para>
-<!-- I think this is not a user-level command; it is used to keep from breaking -->
-<!-- the page between the closing and the signature -->
-<!-- @node \stopbreaks and \startbreaks -->
-<!-- @section @code{\stopbreaks} and @code{\startbreaks} -->
-
-<!-- @findex \startbreak -->
-<!-- @findex \stopbreaks -->
-
-<!-- @example -->
-<!-- @code{\stopbreaks} -->
-<!-- text -->
-<!-- @code{\startbreaks} -->
-<!-- @end example -->
-
-<!-- The @code{\stopbreaks} inhibits page breaking. The @code{\startbreaks} resumes -->
-<!-- normal page breaking. -->
-<!-- -->
-<!-- -->
</sect1>
<sect1 label="26.11" id="_005ctelephone">
<title><literal>\telephone</literal></title>
@@ -16564,15 +18355,143 @@ page.
</sect1>
</chapter>
-<chapter label="27" id="Terminal-input_002foutput">
-<title>Terminal input/output</title>
+<chapter label="27" id="Input_002foutput">
+<title>Input/output</title>
<indexterm role="cp"><primary>input/output, to terminal</primary></indexterm>
<indexterm role="cp"><primary>terminal input/output</primary></indexterm>
+<indexterm role="cp"><primary>input/output</primary></indexterm>
+
+<para>&latex; uses the ability to write to a file and later read it back in
+to build document components such as a table of contents or index. You
+can also read a file that other programs written, or write a file for
+others to read. You can communicate with users through the terminal.
+And, you can issue instructions for the operating system.
+</para>
+
+
+<sect1 label="27.1" id="_005copenin-_0026-_005copenout">
+<title><literal>\openin</literal> &amp; <literal>\openout</literal></title>
+
+<indexterm role="fn"><primary>\openin</primary></indexterm>
+<indexterm role="fn"><primary>\openout</primary></indexterm>
+<indexterm role="fn"><primary>\closein</primary></indexterm>
+<indexterm role="fn"><primary>\closeout</primary></indexterm>
+<indexterm role="cp"><primary>file, opening</primary></indexterm>
+<indexterm role="cp"><primary>file, closing</primary></indexterm>
+<indexterm role="cp"><primary>open a file</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\openin <replaceable>number</replaceable>=<replaceable>filename</replaceable>
+</screen>
+<para>or:
+</para>
+<screen>\openout <replaceable>number</replaceable>=<replaceable>filename</replaceable>
+</screen>
+<para>Open a file for reading material, or for writing it. The <replaceable>number</replaceable>
+must be between 0 and 15, as in <literal>\openin3</literal> (in Lua&latex;
+<replaceable>number</replaceable> can be between 0 and 255).
+</para>
+<para>Here &tex; opens the file <filename>presidents.tex</filename> for reading.
+</para>
+<screen>\newread\presidentsfile
+\openin\presidentsfile=presidents
+\typeout{presidentsfile is \the\presidentsfile}
+\read\presidentsfile to\presidentline
+\typeout{\presidentline}
+</screen>
+<para>The <literal>\newread</literal> command allocates input stream numbers from 0
+to&#160;15 (there is also a <literal>\newwrite</literal>). The
+<literal>\presidentsfile</literal> is more memorable but under the hood it is still
+a number; the first <literal>\typeout</literal> gives something like
+&#8216;<literal>presidentsfile is 1</literal>&#8217;. In addition, <literal>\newread</literal> keeps track of
+the allocation so that if you use too many then you get an error like
+&#8216;<literal>! No room for a new \read</literal>&#8217;. The second <literal>\typeout</literal> gives the
+first line of the file, something like &#8216;<literal>1 Washington, George</literal>&#8217;.
+</para>
+<para>Ordinarily &tex; will not try to open the file until the next page
+shipout. To change this, use
+<literal>\immediate\openin <replaceable>number</replaceable>=<replaceable>filename</replaceable></literal> or
+<literal>\immediate\openout <replaceable>number</replaceable>=<replaceable>filename</replaceable></literal>.
+</para>
+<para>Close files with <literal>\closein <replaceable>number</replaceable></literal> and
+<literal>\closeout <replaceable>number</replaceable></literal>.
+</para>
+<para>How &latex; handles filenames varies among distributions, and even can
+vary among versions of a distribution. If the file does not have an
+extension then &tex; will add a <filename>.tex</filename>. This creates
+<filename>presidents.tex</filename>, writes one line to it, and closes it.
+</para>
+<screen>\newwrite\presidentsfile
+\openout\presidentsfile=presidents
+\write\presidentsfile{1 Washington, George}
+\closeout\presidentsfile
+</screen>
+<para>But filenames with a period can cause trouble: if &tex; finds a
+<replaceable>filename</replaceable> of <filename>presidents.dat</filename> it could look first for
+<filename>presidents.dat.tex</filename> and later for <filename>presidents.dat</filename>, or it
+could do the opposite. Your distribution&#8217;s documentation should say
+more, and if you find something that works for you then you are good,
+but to ensure complete portability the best thing is to use file names
+containing only the twenty six ASCII letters (not case-sensitive) and
+the ten digits, along with underscore and dash, and in particular with
+no dot or space.
+</para>
+<para>For <literal>\openin</literal>, if &tex; cannot find the file then it does not give
+an error. It just considers that the stream is not open (test for this
+with <literal>\ifeof</literal>; one recourse is the command
+<literal>\InputIfFileExists</literal>, see <link linkend="Class-and-package-commands">Class and package commands</link>). If you
+try to use the same number twice, &latex; won&#8217;t give you an error. If
+you try to use a bad number then you get an error message like &#8216;<literal>!
+Bad number (16). &lt;to be read again&gt; = l.30 \openin16=test.jh</literal>&#8217;.
+</para>
+
+</sect1>
+<sect1 label="27.2" id="_005cread">
+<title><literal>\read</literal></title>
+<indexterm role="fn"><primary>\read</primary></indexterm>
+<indexterm role="cp"><primary>file, reading</primary></indexterm>
+<indexterm role="cp"><primary>read a file</primary></indexterm>
+<para>Synopsis:
+</para>
+<screen>\read <replaceable>number</replaceable> to<replaceable>macro</replaceable>
+</screen>
+<para>Make the command <replaceable>macro</replaceable> contain the next line of input from text
+stream <replaceable>number</replaceable>, as in <literal>\read5 to\data</literal>.
+</para>
+<para>This opens the file <filename>email.tex</filename> for reading, puts the contents of
+the first line into the command <literal>\email</literal>, and then closes the file.
+</para>
+<screen>\newread\recipientfile
+\openin\recipientfile=email
+\read\recipientfile to\email
+\typeout{Email address: \email}
+\closein\recipientfile
+</screen>
+<para>If <replaceable>number</replaceable> is outside the range from 0 to&#160;15 or if no file
+of that number is open, or if the file has ended, then <literal>\read</literal>
+will take input from the terminal (or exit if interaction is not
+allowed, e.g., <literal>\nonstopmode</literal>; see <link linkend="interaction-modes">interaction modes</link>).
+(However, the natural way in &latex; to take input from the terminal
+is <literal>\typein</literal> (see <link linkend="_005ctypein">\typein</link>.)
+</para>
+<para>To read an entire file as additional &latex; source, use
+<literal>\input</literal> (see <link linkend="_005cinput">\input</link>) or <literal>\include</literal> (see <link linkend="_005cinclude-_0026-_005cincludeonly">\include &amp;
+\includeonly</link>).
+</para>
+<indexterm role="cp"><primary>package, <literal>datatool</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>datatool</literal> package</primary></indexterm>
-<sect1 label="27.1" id="_005ctypein">
+<indexterm role="cp"><primary>mail merges</primary></indexterm>
+<para>A common reason to want to read from a data file is to do mail merges.
+CTAN has a number of packages for that; one is <filename>datatool</filename>.
+</para>
+
+</sect1>
+<sect1 label="27.3" id="_005ctypein">
<title><literal>\typein</literal></title>
<indexterm role="fn"><primary>\typein</primary></indexterm>
@@ -16603,9 +18522,9 @@ the input you typed to be processed as if it had been included in the
input file in place of the <literal>\typein</literal> command.
</para>
<para>In the second command version the optional argument <literal><replaceable>cmd</replaceable></literal>
-argument must be a command name &#8212; it must begin with a backslash, \.
-This command name is then defined or redefined to be the input that you
-typed. For example, this
+argument must be a command name, that is, it must begin with a
+backslash, \. This command name is then defined or redefined to be
+the input that you typed. For example, this
</para>
<screen>\typein[\student]{Enter student name:}
\typeout{Recommendation for \student .}
@@ -16621,7 +18540,7 @@ Recommendation for John Dee.
</para>
</sect1>
-<sect1 label="27.2" id="_005ctypeout">
+<sect1 label="27.4" id="_005ctypeout">
<title><literal>\typeout</literal></title>
<indexterm role="fn"><primary>\typeout</primary></indexterm>
@@ -16658,19 +18577,373 @@ character with <literal>\csname @percentchar\endcsname</literal>.
</para>
</sect1>
+<sect1 label="27.5" id="_005cwrite">
+<title><literal>\write</literal></title>
+
+<indexterm role="fn"><primary>\write</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\write <replaceable>number</replaceable>{<replaceable>string</replaceable>}
+</screen>
+<para>Write <replaceable>string</replaceable> to the log file, to the terminal, or to a file
+opened by <literal>\openout</literal>. For instance, <literal>\write6</literal> writes to text
+stream number&#160;6.
+</para>
+<para>If the following appears in <filename><replaceable>basefile</replaceable>.tex</filename> then it opens
+<filename><replaceable>basefile</replaceable>.jh</filename>, writes &#8216;<literal>Hello World!</literal>&#8217; and a newline to
+it, and closes that file.
+</para>
+<screen>\newwrite\myfile
+\immediate\openout\myfile=\jobname.jh % \jobname is root file basename
+...
+\immediate\write\myfile{Hello world!}
+...
+\immediate\closeout\myfile
+</screen>
+<indexterm role="fn"><primary>\newwrite</primary></indexterm>
+<para>The <literal>\newwrite</literal> allocates a stream number, giving it a symbolic
+name to make life easier, so that <literal>stream
+\newwrite\myfile\the\myfile</literal> produces something like &#8216;<literal>stream 3</literal>&#8217;.
+Then <literal>\openout</literal> associates the stream number with the given file
+name. &tex; ultimately executed <literal>\write3</literal> which puts the string
+in the file.
+</para>
+<indexterm role="cp"><primary>log file, writing to</primary></indexterm>
+<indexterm role="cp"><primary>terminal, writing to</primary></indexterm>
+<indexterm role="cp"><primary><inlineequation><mathphrase>-1</mathphrase></inlineequation>, write stream number</primary></indexterm>
+<para>Typically <replaceable>number</replaceable> is between 0 and&#160;15, because typically
+&latex; authors follow the prior example and the number is allocated
+by the system. If <replaceable>number</replaceable> is outside the range from 0 to 15 or
+if it is not associated with an open file then &latex; writes
+<replaceable>string</replaceable> to the log file. If <replaceable>number</replaceable> is positive then in
+addition &latex; writes <replaceable>string</replaceable> to the terminal.
+</para>
+<para>Thus, <literal>test \write-1{Hello World!}</literal> puts &#8216;<literal>Hello World!</literal>&#8217;
+followed by a newline in the log file. (This is what the <literal>\wlog</literal>
+command does; see <link linkend="_005cwlog">\wlog</link>). And <literal>\write100{Hello World!}</literal>
+puts the same in the log file but also puts &#8216;<literal>Hello World!</literal>&#8217;
+followed by a newline in the terminal output. (But 16, 17, and 18 are
+special as <replaceable>number</replaceable>; see below.)
+</para>
+<indexterm role="cp"><primary>Lua&tex;, 256 output streams in</primary></indexterm>
+<para>In Lua&tex;, instead of 16 output streams there are 256
+(see <link linkend="TeX-engines">&tex; engines</link>).
+</para>
+<indexterm role="fn"><primary>\@auxout</primary></indexterm>
+<indexterm role="fn"><primary>\@mainaux</primary></indexterm>
+<para>Use <literal>\write\@auxout{<replaceable>string</replaceable>}</literal> to write to the current
+<filename>.aux</filename> file, which is associated with either the root file or
+with the current include file; and use
+<literal>\write\@mainaux{<replaceable>string</replaceable>}</literal> to write to the main
+<filename>.aux</filename>. These symbolic names are defined by &latex;.
+</para>
+<!-- credit: David Carlisle https://tex.stackexchange.com/a/115933/121234 -->
+<para>By default &latex; does not write <replaceable>string</replaceable> to the file right
+away. This is because, for example, you may need <literal>\write</literal> to
+save the current page number, but when &tex; comes across a
+<literal>\write</literal> it typically does not know what the page number is,
+since it has not yet done the page breaking. So, you use <literal>\write</literal>
+in one of three contexts:
+</para>
+<screen>\immediate\write\@auxout{<replaceable>string</replaceable>} %1
+\write\@auxout{<replaceable>string</replaceable>} %2
+\protected@write\@auxout{}{<replaceable>string</replaceable>} %3
+</screen>
+<orderedlist numeration="arabic"><listitem><indexterm role="cp"><primary>immediate <literal>\write</literal></primary></indexterm>
+<indexterm role="fn"><primary>\immediate\write</primary></indexterm>
+<para>With the first, &latex; writes <replaceable>string</replaceable> to the file immediately.
+Any macros in <replaceable>string</replaceable> are fully expanded (just as in
+<literal>\edef</literal>) so to prevent expansion you must use <literal>\noexpand</literal>,
+<literal>toks</literal>, etc., except that you should use <literal>#</literal> instead of
+<literal>##</literal>).
+</para>
+</listitem><listitem><indexterm role="cp"><primary>delayed <literal>\write</literal></primary></indexterm>
+<indexterm role="cp"><primary>whatsit item</primary></indexterm>
+<indexterm role="fn"><primary>\shipout and expansion</primary></indexterm>
+<para>With the second, <replaceable>string</replaceable> is stored on the current list of things
+(as a &tex; &#8220;whatsit&#8221; item) and kept until the page is shipped out
+and likewise the macros are unexpanded until <literal>\shipout</literal>. At
+<literal>\shipout</literal>, <replaceable>string</replaceable> is fully expanded.
+</para>
+</listitem><listitem><indexterm role="fn"><primary>\protected@write</primary></indexterm>
+<para>The third, <literal>\protected@write</literal>, is like the second except that
+you can use <literal>\protect</literal> to avoid expansion. The extra first
+argument allows you to locally insert extra definitions to make more
+macros protected or to have some other special definition for the
+write.
+</para></listitem></orderedlist>
+<para>As a simple example of expansion with <literal>\write</literal>, <replaceable>string</replaceable> here
+contains a control sequence <literal>\triplex</literal> which we&#8217;ve defined to be
+the text &#8216;<literal>XYZ</literal>&#8217;:
+</para>
+<screen>\newwrite\jhfile
+\openout\jhfile=test.jh
+\newcommand{\triplex}{XYZ}
+\write\jhfile{test \triplex test}
+</screen>
+<para>This results in the file <filename>test.jh</filename> containing the text
+&#8216;<literal>test XYZtest</literal>&#8217; followed by a newline.
+</para>
+<indexterm role="cp"><primary><literal>\write</literal> streams 16, 17, 18</primary></indexterm>
+<para>The cases where <replaceable>number</replaceable> is 16, 17, or 18 are special. Because of
+<literal>\write</literal>&#8217;s behavior when <replaceable>number</replaceable> is outside the range from 0
+to 15 described above, in Plain&#160;&tex; <literal>\write16</literal> and
+<literal>\write17</literal> were sometimes used to write to the log file and the
+terminal; however, in &latex;, the natural way to do that is with
+<literal>\typeout</literal> (see <link linkend="_005ctypeout">\typeout</link>). The <literal>\write18</literal> command is
+even more special; modern &tex; systems use it for giving commands to
+the operating system (see <link linkend="_005cwrite18">\write18</link>).
+</para>
+<indexterm role="cp"><primary>newline, in <literal>\write</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>^^J</literal>, in <literal>\write</literal></primary></indexterm>
+<para>Ordinarily <literal>\write</literal> outputs a single line. You can include a
+newline with <literal>^^J</literal>. Thus, this produces two lines in the log
+file:
+</para>
+<screen>\wlog{Parallel lines have a lot in common.^^JBut they never meet.}
+</screen>
+<indexterm role="cp"><primary>package, <literal>answers</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>answers</literal> package</primary></indexterm>
+
+<para>A common case where authors need to write their own file is for
+answers to exercises, or another situation where you want to write
+out verbatim, without expanding the macros. CTAN has a number of
+packages for this; one is <filename>answers</filename>.
+</para>
+
+
+<sect2 label="27.5.1" id="_005cwrite-and-security">
+<title><literal>\write</literal> and security</title>
+
+<indexterm role="cp"><primary>security and <literal>\write</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>\write</literal> and security</primary></indexterm>
+
+<para>The ability to write files raises security issues. If you compiled a
+downloaded &latex; file and it overwrote your password file then you
+would be justifiably troubled.
+</para>
+<para>Thus, by default &tex; systems only allow you to open files for
+writing that are in the current directory or output directory, if
+specified (see <link linkend="output-directory">output directory</link>), or in a subdirectory of
+those. So, this code
+</para>
+<screen>\newwrite\jhfile
+\openout\jhfile=../test.jh
+</screen>
+<para>gives an error like:
+</para><screen>Not writing to ../test.jh (openout_any = p).
+! I can't write on file `../test.jh'
+</screen>
+<indexterm role="cp"><primary>parent directories, cannot write to</primary></indexterm>
+<para>You can get just such an error when using commands such as
+<literal>\include{../filename}</literal> because &latex; will try to open
+<filename>../filename.aux</filename>. The simplest solution is to put the included
+files in the same directory as the root file, or in subdirectories.
+</para>
+
+</sect2>
+<sect2 label="27.5.2" id="_005cmessage">
+<title><literal>\message</literal></title>
+
+<indexterm role="fn"><primary>\message</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\message{<replaceable>string</replaceable>}
+</screen>
+<para>Write <replaceable>string</replaceable> to the log file and the terminal.
+</para>
+<para>Typically, &latex; authors use <literal>\typeout</literal> (see <link linkend="_005ctypeout">\typeout</link>). It
+allows you to use <literal>\protect</literal> on any fragile commands in
+<replaceable>string</replaceable> (see <link linkend="_005cprotect">\protect</link>). But <literal>\typeout</literal> always inserts a
+newline at the end of <replaceable>string</replaceable> while <literal>\message</literal> does not, so
+the latter can be useful.
+</para>
+<para>With this example document body.
+</para>
+<screen>before\message{One Two}\message{Three}\message{Four^^JI}
+\message{declare a thumb war.}After
+</screen>
+<para>under some circumstances (see below) &latex; writes the following to
+both the terminal and the log file.
+</para>
+<screen>One Two Three Four
+I declare a thumb war.
+</screen>
+<para>The <literal>^^J</literal> produces a newline. Also, in the output document,
+between &#8216;<literal>before</literal>&#8217; and &#8216;<literal>After</literal>&#8217; will be a single space (from
+the end of line following &#8216;<literal>I}</literal>&#8217;).
+</para>
+<para>While <literal>\message</literal> allows you more control over formatting, a
+gotcha is that &latex; may mess up that formatting because it inserts
+line breaks depending on what it has already written. Contrast this
+document body, where the &#8216;<literal>Two</literal>&#8217; has moved, to the one given above.
+</para>
+<screen>before\message{One}\message{Two Three}\message{Four^^JI}
+\message{declare a thumb war.}After
+</screen>
+<para>This can happen: when &latex; is outputting the messages to the
+terminal, now the message with &#8216;<literal>One</literal>&#8217; is shorter and it fits at the
+end of the output terminal line, and so &latex; breaks the line between
+it and the &#8216;<literal>Two Three</literal>&#8217;. That line break appears also in the log
+file. This line break insertion can depend on, for instance, the length
+of the full path names of included files. So producing finely-formatted
+lines in a way that is portable is hard, likely requiring
+starting your message at the beginning of a line.
+</para>
+
+</sect2>
+<sect2 label="27.5.3" id="_005cwlog">
+<title><literal>\wlog</literal></title>
+
+<indexterm role="fn"><primary>\wlog</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\wlog{<replaceable>string</replaceable>}
+</screen>
+<para>Write <replaceable>string</replaceable> to the log file.
+</para>
+<screen>\wlog{Did you hear about the mathematician who hates negatives?}
+\wlog{He'll stop at nothing to avoid them.}
+</screen>
+<para>Ordinarily <replaceable>string</replaceable> appears in a single separate line. Use
+<literal>^^J</literal> to insert a newline.
+</para>
+<screen>\wlog{Helvetica and Times Roman walk into a bar.}
+\wlog{The barman says,^^JWe don't serve your type.}
+</screen>
+
+</sect2>
+<sect2 label="27.5.4" id="_005cwrite18">
+<title><literal>\write18</literal></title>
+
+<indexterm role="fn"><primary>\write18</primary></indexterm>
+<indexterm role="cp"><primary>external commands</primary></indexterm>
+<indexterm role="cp"><primary>commands, run from &latex;</primary></indexterm>
+<indexterm role="cp"><primary>system commands, run from &latex;</primary></indexterm>
+<indexterm role="cp"><primary>shell access</primary></indexterm>
+<!-- Derived from: Joseph Wright: https://tex.stackexchange.com/a/20446/121234 -->
+
+<para>Synopsis:
+</para>
+<screen>\write18{<replaceable>shell_command</replaceable>}
+</screen>
+<para>Issue a command to the operating system shell. The operating system
+runs the command and &latex;&#8217;s execution is blocked until that
+finishes.
+</para>
+<indexterm role="cp"><primary>package, <literal>Asymptote</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>Asymptote</literal> package</primary></indexterm>
+
+<para>This sequence (on Unix)
+</para>
+<screen>\usepackage{graphicx} % in preamble
+ ...
+\newcommand{\fignum}{1}
+\immediate\write18{cd pix &amp;&amp; asy figure\fignum}
+\includegraphics{pix\figure\fignum.pdf}
+</screen>
+<para>will run Asymptote (the <literal>asy</literal> program) on <filename>pix/figure1.asy</filename>,
+so that the document can later read in the resulting graphic
+(see <link linkend="_005cincludegraphics">\includegraphics</link>). Like any <literal>\write</literal>, here &latex;
+expands macros in <replaceable>shell_command</replaceable> so that <literal>\fignum</literal> is
+replaced by &#8216;<literal>1</literal>&#8217;.
+</para>
+<para>Another example is that you can automatically run Bib&tex; at the start
+of each &latex; run (see <link linkend="Using-BibTeX">Using BibTeX</link>) by including
+<literal>\immediate\write18{bibtex8 \jobname}</literal> as the first line of the
+file. Note that <literal>\jobname</literal> expands to the basename of the root
+file unless the <literal>--jobname</literal> option is passed on the command line,
+in which case this is the option argument.
+</para>
+<para>You sometimes need to do a multi-step process to get the information
+that you want. This will insert into the input a list of all PDF files
+in the current directory (but see <filename>texosquery</filename> below):
+</para>
+<screen>\immediate\write18{ls *.pdf &gt; tmp.dat}
+\input{tmp.dat}
+</screen>
+<para>The standard behavior of any <literal>\write</literal> is to wait until a page is
+being shipped out before expanding the macros or writing to the stream
+(see <link linkend="_005cwrite">\write</link>). But sometimes you want it done now. For this, use
+<literal>\immediate\write18{<replaceable>shell_command</replaceable>}</literal>.
+</para>
+<para>There are obvious security issues with allowing system commands inside
+a &latex; file. If you download a file off the net and it contains
+commands to delete all your files then you would be unhappy. The
+standard settings in modern distributions turn off full shell
+access. You can turn it on, if you are sure the shell commands are
+safe, by compiling with <literal>latex --enable-write18 <replaceable>filename</replaceable></literal>
+(see <link linkend="Command-line-options">Command line options</link>). (The <literal>--shell-escape</literal> option is
+a synonym, in &tex; Live.)
+</para>
+<indexterm role="cp"><primary>restricted shell access</primary></indexterm>
+<para>In the place of full shell access, modern distributions by default use
+a restricted version that allows some commands to work, such as those
+that run Metafont to generate missing fonts, even if you do not use
+the <literal>enable-write18</literal> option. By default this list of allowed
+commands is short and features only commands that are under the
+control of the distribution maintainers (see <link linkend="Command-line-options">Command line
+options</link>).
+</para>
+<indexterm role="fn"><primary>/bin/sh, used by <literal>\write18</literal></primary></indexterm>
+<indexterm role="fn"><primary>sh, used by <literal>\write18</literal></primary></indexterm>
+<indexterm role="fn"><primary>cmd.exe, used by <literal>\write18</literal></primary></indexterm>
+<indexterm role="fn"><primary>SHELL, environment variables</primary></indexterm>
+<para>The <replaceable>shell_command</replaceable> text is always passed to <filename>/bin/sh</filename> on
+Unix-like operating systems, and the DOS command interpreter
+<filename>cmd.exe</filename> on Windows. Any different shell set by the user, and
+the <literal>SHELL</literal> environment variable, is ignored.
+</para>
+<indexterm role="cp"><primary>package, <literal>texosquery</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>texosquery</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>system information</primary></indexterm>
+<indexterm role="cp"><primary>operating system information</primary></indexterm>
+<indexterm role="cp"><primary>locale information, from system</primary></indexterm>
+<indexterm role="cp"><primary>directory listings, from system</primary></indexterm>
+<para>If what you need is system information, such as the operating system
+name, locale information, or directory contents, take a look at the
+<filename>texosquery</filename> package, which provides a convenient and secure
+interface for this, unlike the above examples using the raw
+<literal>\write18</literal>: <ulink url="https://ctan.org/pkg/texosquery">https://ctan.org/pkg/texosquery</ulink>.
+</para>
+<indexterm role="cp"><primary>package, <literal>shellesc</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>shellesc</literal> package</primary></indexterm>
+
+<indexterm role="fn"><primary>\ShellEscape</primary></indexterm>
+<indexterm role="fn"><primary>\DelayedShellEscape</primary></indexterm>
+<para>&latex; provides a package <literal>shellesc</literal> on top of the primitive
+<literal>\write18</literal> command. Its primary purpose is to provide a command
+<literal>\ShellEscape</literal> which works identically on all &tex; engines;
+Lua&tex; intentionally did not retain <literal>\write18</literal> as a way to
+invoke a shell command, so some engine-specific code is needed. The
+<literal>shellesc</literal> package also provides a command
+<literal>\DelayedShellEscape</literal>, executed at <literal>\output</literal> time, for the
+same reason.
+</para>
+
+</sect2>
+</sect1>
</chapter>
-<chapter label="28" id="Command-line">
-<title>Command line</title>
+<chapter label="28" id="Command-line-interface">
+<title>Command line interface</title>
-<indexterm role="cp"><primary>command line</primary></indexterm>
+<anchor id="Command-line"/><!-- old name -->
+<indexterm role="cp"><primary>command line interface</primary></indexterm>
+<indexterm role="cp"><primary>interface, command line</primary></indexterm>
+<indexterm role="cp"><primary>CLI</primary></indexterm>
<para>Synopsis (from a terminal command line):
</para>
<screen>pdflatex <replaceable>options</replaceable> <replaceable>argument</replaceable>
</screen>
-<para>Run &latex; on <replaceable>argument</replaceable>. In place of <command>pdflatex</command> you can
-also use <command>xelatex</command>, or <literal>lualatex</literal>, or <literal>dviluatex</literal>, or
-<literal>latex</literal>.
+<para>Run &latex; on <replaceable>argument</replaceable>. In place of <command>pdflatex</command> you
+can also use (for PDF output) <command>xelatex</command> or <literal>lualatex</literal>, or
+(for DVI output) <literal>latex</literal> or <literal>dvilualatex</literal>, among others
+(see <link linkend="TeX-engines">&tex; engines</link>).
</para>
<para>For example, this will run &latex; on the file <filename>thesis.tex</filename>,
creating the output <filename>thesis.pdf</filename>.
@@ -16678,19 +18951,20 @@ creating the output <filename>thesis.pdf</filename>.
<screen>pdflatex thesis
</screen>
<para><indexterm role="fn"><primary>.tex, default extension</primary></indexterm>
-Note that <filename>.tex</filename> is the default file extension.
-</para>
-<para>pdf&tex; is a development of the original &tex; program, as are
-Xe&tex; and Lua&tex; (see <link linkend="TeX-engines">&tex; engines</link>). They are completely
-backward compatible. But the original program had a custom output
-format, DVI, while the newer ones can output directly to PDF. This
-allows them to take advantage of the extra features in PDF such as
-hyperlinks, support for modern image formats such as JPG and PNG, and
-ubiquitous viewing programs. In short, if you run <command>pdflatex</command> or
-<command>xelatex</command> or <command>lualatex</command> then you will by default get PDF
-and have access to all its modern features. If you run <command>latex</command>,
-or <literal>dvilualatex</literal>, then you will get DVI. The description here
-assumes pdf&latex;.
+Note that <filename>.tex</filename> is the default file name extension.
+</para>
+<para>pdf&tex; is an extension of the original &tex; program, as are
+Xe&tex; and Lua&tex; (see <link linkend="TeX-engines">&tex; engines</link>). The first two are
+completely backward compatible and the latter, almost so. Perhaps the
+most fundamental new feature for all three is that the original &tex;
+output its own DVI format, while the newer ones can output directly to
+PDF. This allows them to take advantage of the extra features in PDF
+such as hyperlinks, support for modern image formats such as JPG and
+PNG, and ubiquitous viewing programs. In short, if you run
+<command>pdflatex</command> or <command>xelatex</command> or <command>lualatex</command> then you
+will by default get PDF and have access to all its modern features.
+If you run <command>latex</command>, or <literal>dvilualatex</literal>, then you will get
+DVI. The description here assumes pdf&latex;.
</para>
<para>See <link linkend="Command-line-options">Command line options</link>, for a selection of the most useful
command line options. As to <replaceable>argument</replaceable>, the usual case is that it
@@ -16702,10 +18976,10 @@ input</link>).
</para>
<para>If you gave no arguments or options then <command>pdflatex</command> prompts for
input from the terminal. You can escape from this by entering
-<literal>&lt;control&gt;-D</literal>.
+<userinput>CTRL-D</userinput>.
</para>
<para>If &latex; finds an error in your document then by default it stops and
-asks you about it. See <link linkend="Recovering-from-errors">Recovering from errors</link> for an outline of what
+asks you about it. See <link linkend="Recovering-from-errors">Recovering from errors</link>, for an outline of what
to do.
</para>
@@ -16720,9 +18994,12 @@ authoring. For a full list, try running &#8216;<literal>latex --help</literal>&#
command line.
</para>
<para>With many implementations you can specify command line options by
-prefixing them with &#8216;<literal>-</literal>&#8217; or &#8216;<literal>--</literal>&#8217;. This is the case for
-both &tex; Live (and Mac&tex;) and MiK&tex;. We will use both
-conventions interchangeably.
+prefixing them with &#8216;<literal>-</literal>&#8217; or &#8216;<literal>--</literal>&#8217;. This is the case for both
+&tex; Live (including Mac&tex;) and MiK&tex;. We will use both
+conventions interchangeably. If an option takes a value, it can be
+specified either as a separate argument (&#8216;<literal>--foo val</literal>&#8217;), or as one
+argument with an &#8216;<literal>=</literal>&#8217; sign (&#8216;<literal>--foo=val</literal>&#8217;), but there can be no
+spaces around the &#8216;<literal>=</literal>&#8217;. We will generally use the &#8216;<literal>=</literal>&#8217; syntax.
</para>
<variablelist><indexterm role="fn"><primary>--version command-line option</primary></indexterm>
<varlistentry><term><literal>-version</literal>
@@ -16734,18 +19011,22 @@ and exit.
</listitem></varlistentry><varlistentry><term><literal>-help</literal>
</term><listitem><para>Give a brief usage message that is useful as a prompt and exit.
</para>
-<indexterm role="fn"><primary>--interaction command-line option</primary></indexterm>
+<anchor id="interaction-modes"/><indexterm role="fn"><primary>--interaction command-line option</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>-interaction=<replaceable>mode</replaceable></literal>
-</term><listitem><para>&tex; compiles a document in one of four interaction modes:
+</term><listitem><indexterm role="cp"><primary>batchmode</primary></indexterm>
+<indexterm role="cp"><primary>scrollmode</primary></indexterm>
+<indexterm role="cp"><primary>errorstopmode</primary></indexterm>
+<indexterm role="cp"><primary>nonstopmode</primary></indexterm>
+<para>&tex; compiles a document in one of four interaction modes:
<literal>batchmode</literal>, <literal>nonstopmode</literal>, <literal>scrollmode</literal>,
-<literal>errorstopmode</literal>. In <firstterm>errorstop mode</firstterm> (the default), &tex;
-stops at each error and asks for user intervention. In <firstterm>batch
-mode</firstterm> it prints nothing on the terminal, errors are scrolled as if the
-user hit <literal>&lt;return&gt;</literal> at every error, and missing files cause the
-job to abort. In <firstterm>nonstop mode</firstterm>, diagnostic message appear on the
-terminal but as in batch mode there is no user interaction. In
-<firstterm>scroll mode</firstterm>, &tex; only stops for missing files or keyboard
-input.
+<literal>errorstopmode</literal>. In <firstterm>errorstopmode</firstterm> (the default), &tex;
+stops at each error and asks for user intervention. In <firstterm>batchmode</firstterm>
+it prints nothing on the terminal, errors are scrolled as if the user
+hit <userinput>RETURN</userinput> at every error, and missing files cause the job to
+abort. In <firstterm>nonstopmode</firstterm>, diagnostic message appear on the terminal
+but as in batch mode there is no user interaction. In
+<firstterm>scrollmode</firstterm>, &tex; stops for missing files or keyboard
+input, but nothing else.
</para>
<para>For instance, starting &latex; with this command line
</para>
@@ -16753,54 +19034,54 @@ input.
</screen>
<para>eliminates most terminal output.
</para>
+<indexterm role="cp"><primary>jobname</primary></indexterm>
+<indexterm role="cp"><primary>filename for current job</primary></indexterm>
<indexterm role="fn"><primary>--jobname command-line option</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>-jobname=<replaceable>string</replaceable></literal>
-</term><listitem><para>Set the value of &tex;&#8217;s <literal>jobname</literal> to the string. The log file
+</term><listitem><para>Set the value of &tex;&#8217;s <firstterm>jobname</firstterm> to the string. The log file
and output file will then be named <filename><replaceable>string</replaceable>.log</filename> and
-<filename><replaceable>string</replaceable>.pdf</filename>.
-</para>
-<para>When you run <literal><command>pdflatex</command> <replaceable>options</replaceable> <replaceable>argument</replaceable></literal>, if
-<replaceable>argument</replaceable> does not start with a backslash then &tex; considers it
-the name of a file to input. Otherwise it waits for the first
-<literal>\input</literal> instruction and the name of the input file will be the job
-name. This is used to name the log file the output file. The
-<literal>jobname</literal> option overrides that process and directly specifies the
-name. See <link linkend="Command-line-input">Command line input</link> for an example of its use.
+<filename><replaceable>string</replaceable>.pdf</filename>. see <link linkend="Jobname">Jobname</link>.
</para>
+<anchor id="output-directory"/><indexterm role="cp"><primary>output directory for all external files</primary></indexterm>
<indexterm role="fn"><primary>--output-directory command-line option</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>-output-directory=<replaceable>directory</replaceable></literal>
</term><listitem><para>Write files in the directory <replaceable>directory</replaceable>. It must already exist.
-</para>
-<indexterm role="fn"><primary>--shell-escape command-line option</primary></indexterm>
-<indexterm role="fn"><primary>--no-shell-escape command-line option</primary></indexterm>
+This applies to all external files created by &tex; or &latex;, such
+as the <filename>.log</filename> file for the run, the <filename>.aux</filename>, <filename>.toc</filename>,
+etc., files created by &latex;, as well as the main <filename>.pdf</filename> or
+<filename>.dvi</filename> output file itself.
+</para>
+<para>When specified, the output directory <replaceable>directory</replaceable> is also
+automatically checked first for any file that it is input, so that the
+external files can be read back in, if desired. The true current
+directory (in which &latex; was run) remains unchanged, and is also
+checked for input files.
+</para>
+<indexterm role="cp"><primary>shell escape</primary></indexterm>
+<indexterm role="cp"><primary><literal>\write18</literal>, enabling</primary></indexterm>
<indexterm role="fn"><primary>--enable-write18 command-line option</primary></indexterm>
<indexterm role="fn"><primary>--disable-write18 command-line option</primary></indexterm>
-</listitem></varlistentry><varlistentry><term><literal>--shell-escape</literal>
-</term><term><literal>--no-shell-escape</literal>
-</term><term><literal>--enable-write18</literal>
+<indexterm role="fn"><primary>--shell-escape command-line option</primary></indexterm>
+<indexterm role="fn"><primary>--no-shell-escape command-line option</primary></indexterm>
+</listitem></varlistentry><varlistentry><term><literal>--enable-write18</literal>
</term><term><literal>--disable-write18</literal>
-</term><listitem><para>Enable or disable <literal>\write18{<replaceable>shell command</replaceable>}</literal>. The first two
-options are for with &tex; Live or Mac&tex; while the second two are
-for MiK&tex;.
-</para>
-<indexterm role="cp"><primary>package, <literal>sagetex</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>sagetex</literal> package</primary></indexterm>
-
-<para>Sometimes you want to run external system commands from inside a
-&latex; file. For instance the package <filename>sagetex</filename> allows you to
-have the mathematics software system <emphasis>Sage</emphasis> do calculations or draw
-graphs and then incorporate that output in your document. For this
-&tex; provides the <literal>\write18</literal> command.
-</para>
-<para>But with this functionality enabled, security issues could happen if you
-compiled a &latex; file from the Internet. By default <literal>\write18</literal>
-is disabled. (More precisely, by default &tex; Live, Mac&tex;, and
-MiK&tex; only allow the execution of a limited number of &tex;-related
-programs, which they distribute.)
-</para>
-<para>If you invoke &latex; with the option <literal>no-shell-escape</literal>, and in
-your document you call <literal>\write18{ls -l}</literal>, then you do not get an
-error but the log file says &#8216;<literal>runsystem(ls -l)...disabled</literal>&#8217;.
+</term><term><literal>--shell-escape</literal>
+</term><term><literal>--no-shell-escape</literal>
+</term><listitem><para>Enable or disable <literal>\write18{<replaceable>shell_command</replaceable>}</literal>
+(see <link linkend="_005cwrite18">\write18</link>). The first two options are supported by both
+&tex; Live and MiK&tex;, while the second two are synonyms supported
+by &tex; Live.
+</para>
+<para>Enabling this functionality has major security implications, since it
+allows a &latex; file to run any command whatsoever. Thus, by
+default, unrestricted <literal>\write18</literal> is not allowed. (The default
+for &tex; Live, Mac&tex;, and MiK&tex; is to allow the execution of
+a limited number of &tex;-related programs, which they distribute.)
+</para>
+<para>For example, if you invoke &latex; with the option
+<literal>no-shell-escape</literal>, and in your document you call
+<literal>\write18{ls -l}</literal>, then you do not get an error but the log
+file says &#8216;<literal>runsystem(ls -l)...disabled</literal>&#8217;.
</para>
<indexterm role="fn"><primary>--halt-on-error command-line option</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>-halt-on-error</literal>
@@ -16820,17 +19101,19 @@ error messages. These are only available with &tex; Live or Mac&tex;.
<indexterm role="cp"><primary>input, on command line</primary></indexterm>
-<para>As part of the command line invocation <literal>pdflatex <replaceable>options</replaceable>
-<replaceable>argument</replaceable></literal> you can specify arbitrary &latex; input by starting
-<replaceable>argument</replaceable> with a backslash. This allows you to do some special
-effects.
+<para>As part of the command line invocation
+</para>
+<screen><replaceable>latex-engine</replaceable> <replaceable>options</replaceable> <replaceable>argument</replaceable>
+</screen>
+<para>you can specify arbitrary &latex; input by starting
+<replaceable>argument</replaceable> with a backslash. (All the engines support this.) This
+allows you to do some special effects.
</para>
<indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm>
-
-<para>For example, this file (which uses the <filename>hyperref</filename> package for
-hyperlinks) can produce two kinds of output, one for paper and one for a
-PDF.
+<para>For example, this file (which uses the
+<filename>hyperref</filename> package for hyperlinks) can produce two kinds of
+output, one to be read on physical paper and one to be read online.
</para>
<screen>\ifdefined\paperversion % in preamble
\newcommand{\urlcolor}{black}
@@ -16844,10 +19127,15 @@ PDF.
</screen>
<para>Compiling this document <filename>book.tex</filename> with the command line
<literal>pdflatex book</literal> will give the &#8216;<literal>CTAN</literal>&#8217; link in blue. But
-compiling it with <literal>pdflatex &quot;\def\paperversion{}\input book.tex&quot;</literal>
-has the link in black. (Note the use of double quotes to prevent
-interpretation of the symbols by the command line shell; your system may
-do this differently.)
+compiling it with
+</para>
+<screen>pdflatex &quot;\def\paperversion{}\input book.tex&quot;
+</screen>
+<para>has the link in black. We use double quotes to prevent
+interpretation of the symbols by the command line shell. (This
+usually works on both Unix and Windows systems, but there are many
+peculiarities to shell quoting, so read your system documentation if
+need be.)
</para>
<para>In a similar way, from the single file <filename>main.tex</filename> you can compile
two different versions.
@@ -16857,22 +19145,107 @@ two different versions.
pdflatex -jobname=teachers &quot;\def\teachers{}\input{main}&quot;
</screen>
<para>The <literal>jobname</literal> option is there because otherwise both files would be
-called <filename>main.pdf</filename> and the second would overwrite the first.
+called <filename>main.pdf</filename> and the second would overwrite the first. (See
+the next section.)
+</para>
+<para>In this example, we pass the <literal>draft</literal> option to the
+<filename>graphicx</filename> package:
+</para>
+<screen>pdflatex &quot;\PassOptionsToPackage{draft}{graphicx}\input{aa.tex}&quot;
+</screen>
+<para>so the graphic files are read for their bounding box size information
+but replaced in the PDF by a box with same size and that contains only
+the file name, which speeds up compilation time and saves printer ink.
</para>
-<para>A final example. This loads the package <filename>graphicx</filename> with the option
-<literal>draft</literal>
+
+</sect1>
+<sect1 label="28.3" id="Jobname">
+<title>Jobname</title>
+
+<indexterm role="fn"><primary><literal>\jobname</literal></primary></indexterm>
+<indexterm role="cp"><primary>jobname</primary></indexterm>
+<indexterm role="cp"><primary>document root name</primary></indexterm>
+<indexterm role="cp"><primary>name of document root</primary></indexterm>
+
+<para>Running &latex; creates a number of files, including the main PDF (or
+DVI) output but also including others. These files are named with the
+so-called <firstterm>jobname</firstterm>. The most common case is also the simplest,
+where for instance the command <literal>pdflatex thesis</literal> creates
+<literal>thesis.pdf</literal> and also <literal>thesis.log</literal> and <literal>thesis.aux</literal>.
+Here the job name is <literal>thesis</literal>.
+</para>
+<para>In general, &latex; is invoked as <literal><replaceable>latex-engine</replaceable>
+<replaceable>options</replaceable> <replaceable>argument</replaceable></literal>, where <replaceable>latex-engine</replaceable> is
+<command>pdflatex</command>, <command>lualatex</command>, etc. (see <link linkend="TeX-engines">&tex; engines</link>).
+If <replaceable>argument</replaceable> does not start with a backslash, as is the case
+above with <literal>thesis</literal>, then &tex; considers it to be the name of
+the file to input as the main document. The name of that root file,
+without the <filename>.tex</filename> extension, is the jobname. If <replaceable>argument</replaceable>
+does start with a backslash, or if &tex; is in interactive mode, then
+it waits for the first <literal>\input</literal> command, and the jobname is the
+argument to <literal>\input</literal>.
+</para>
+<para>There are two more possibilities for the jobname. It can be directly
+specified with the <literal>-jobname</literal> option, as in <literal>pdflatex
+-jobname=myname</literal> (see <link linkend="Command-line-input">Command line input</link> for a real example).
+</para>
+<indexterm role="fn"><primary>texput, jobname default</primary></indexterm>
+<indexterm role="cp"><primary>fallback jobname</primary></indexterm>
+<para>The final possibility is <filename>texput</filename>, which is the final fallback
+default if no other name is available to &tex;. For example, if no
+<literal>-jobname</literal> option was specified, and the compilation stops before
+there is any output, then the log file will be named
+<filename>texput.log</filename>.
+</para>
+<indexterm role="fn"><primary>\documentclass, and <literal>texput</literal> jobname</primary></indexterm>
+<indexterm role="fn"><primary>\RequirePackage, and <literal>texput</literal> jobname</primary></indexterm>
+<para>A special case of this is that in &latex; versions of (approximately)
+2020 or later, the jobname is also <filename>texput</filename> if the first
+<literal>\input</literal> occurs as a result of being called by either
+<literal>\documentclass</literal> or <literal>\RequirePackage</literal>. So this will produce
+a file named <filename>texput.pdf</filename>:
+</para>
+<screen>pdflatex &quot;\documentclass{minimal}\begin{document}Hello!\end{document}&quot;
+</screen>
+<para>However, this special case only applies to those two commands. Thus, with
</para>
<!-- credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234 -->
-<screen>pdflatex -jobname=aa &quot;\RequirePackage[draft]{graphicx}\input{aa.tex}&quot;
+<screen>pdflatex &quot;\documentclass{article}\usepackage{lipsum}\input{thesis}&quot;
+</screen>
+<para>the output file is <filename>lipsum.pdf</filename>, as <literal>\usepackage</literal> calls
+<literal>\input</literal>.
+</para>
+<indexterm role="fn"><primary>\jobname</primary></indexterm>
+<para>Within the document, the macro <literal>\jobname</literal> expands to the jobname.
+(When you run &latex; on a file whose name contains spaces, the string
+returned by <literal>\jobname</literal> contains matching start and end quotes.)
+In the expansion of that macro, all characters are of
+catcode&#160;12 (other) except that spaces are category&#160;10,
+including letters that are normally catcode&#160;11.
+</para>
+<indexterm role="fn"><primary>\IfBeginWith* macro from <filename>xstring</filename></primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>xstring</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>xstring</literal> package</primary></indexterm>
+
+<para>Because of this catcode situation, using the jobname in a conditional
+can become complicated. One solution is to use the macro
+<literal>\IfBeginWith</literal> from the <filename>xstring</filename> package in its star
+variant, which is insensitive to catcode. For example, in the
+following text the footnote &#8220;Including Respublica Bananensis
+Francorum.&#8221; is only present if the task name starts with
+<filename>my-doc</filename>.
+</para>
+<screen>If a democracy is just a regime where citizens vote then
+all banana republics \IfBeginWith*{\jobname}{my-doc}%
+{\footnote{Including Respublica Bananensis Francorum.}}{} are
+democracies.
</screen>
-<para>so the graphic files are read for their size information but not
-incorporated into the PDF. (The <literal>jobname</literal> option is there because
-otherwise the output file would be <filename>graphicx.pdf</filename>, as
-<literal>\RequirePackage</literal> does an <literal>\input</literal> of its own.)
+<para>Manipulating the value of <literal>\jobname</literal> inside of a document does not
+change the name of the output file or the log file.
</para>
</sect1>
-<sect1 label="28.3" id="Recovering-from-errors">
+<sect1 label="28.4" id="Recovering-from-errors">
<title>Recovering from errors</title>
<para>If &latex; finds an error in your document then it gives you an error
@@ -16889,8 +19262,8 @@ l.5 The \PN
{} problem is a million dollar one.
?
</screen>
-<para>The simplest thing is to enter &#8216;<literal>x</literal>&#8217; and <literal>&lt;return&gt;</literal> and fix the
-typo. You could instead enter &#8216;<literal>?</literal>&#8217; and <literal>&lt;return&gt;</literal> to see other
+<para>The simplest thing is to enter <userinput>x</userinput> and <userinput>RETURN</userinput> and fix the
+typo. You could instead enter <userinput>?</userinput> and <userinput>RETURN</userinput> to see other
options.
</para>
<indexterm role="cp"><primary>&#8216;<literal>*</literal>&#8217; prompt</primary></indexterm>
@@ -16899,9 +19272,10 @@ options.
<para>There are two other error scenarios. The first is that you forgot to
include the <literal>\end{document}</literal> or misspelled it. In this case
&latex; gives you a &#8216;<literal>*</literal>&#8217; prompt. You can get back to the command
-line by typing <literal>\stop</literal> and <literal>&lt;return&gt;</literal>.
+line by typing <userinput>\stop</userinput> and <userinput>RETURN</userinput>; this command does its
+best to exit &latex; immediately, whatever state it may be in.
</para>
-<para>The last scenario is that you mistyped the file name. For instance,
+<para>The last scenario is that you mistyped the filename. For instance,
instead of <literal>pdflatex test</literal> you might type <literal>pdflatex tste</literal>.
</para>
<screen>! I can't find file `tste'.
@@ -16910,8 +19284,8 @@ instead of <literal>pdflatex test</literal> you might type <literal>pdflatex tst
(Press Enter to retry, or Control-D to exit)
Please type another input file name:
</screen>
-<para>The simplest thing is to enter <literal>&lt;Control&gt;</literal> and &#8216;<literal>d</literal>&#8217; (holding
-them down at the same time), and then retype the correct command line.
+<para>The simplest thing is to enter <userinput>CTRL d</userinput> (holding the Control and d
+keys down at the same time), and then retype the correct command line.
</para>
</sect1>
@@ -16922,9 +19296,9 @@ them down at the same time), and then retype the correct command line.
<indexterm role="cp"><primary>document templates</primary></indexterm>
<indexterm role="cp"><primary>templates, document</primary></indexterm>
-<para>Although not reference material, perhaps these document templates will
+<para>Although illustrative material, perhaps these document templates will
be useful. Additional template resources are listed at
-<ulink url="http://tug.org/interest.html#latextemplates">http://tug.org/interest.html#latextemplates</ulink>.
+<ulink url="https://tug.org/interest.html#latextemplates">https://tug.org/interest.html#latextemplates</ulink>.
</para>
@@ -16933,6 +19307,9 @@ be useful. Additional template resources are listed at
<indexterm role="cp"><primary><literal>beamer</literal> template and class</primary></indexterm>
<indexterm role="cp"><primary>template, <literal>beamer</literal></primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>beamer</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>beamer</literal> package</primary></indexterm>
+
<para>The <literal>beamer</literal> class creates presentation slides. It has a vast
array of features, but here is a basic template:
@@ -16941,7 +19318,7 @@ array of features, but here is a basic template:
\title{Beamer Class template}
\author{Alex Author}
-\date{July 31, 2007}
+\date{July 31, 2020}
\begin{document}
@@ -16959,16 +19336,17 @@ array of features, but here is a basic template:
\end{document}
</screen>
-<para>One web resource for this:
-<ulink url="http://robjhyndman.com/hyndsight/beamer/">http://robjhyndman.com/hyndsight/beamer/</ulink>.
+<para>The Beamer package on CTAN: <ulink url="https://ctan.org/pkg/beamer">https://ctan.org/pkg/beamer</ulink>.
</para>
</sect1>
<sect1 label="A.2" id="article-template">
<title><literal>article</literal> template</title>
-<indexterm role="cp"><primary>template, <literal>article</literal></primary></indexterm>
+<indexterm role="cp"><primary>template (simple), <literal>article</literal></primary></indexterm>
+<para>A simple template for an article.
+</para>
<screen>\documentclass{article}
\title{Article Class Template}
\author{Alex Author}
@@ -16984,6 +19362,7 @@ Additional text.
\section{Second section}
Some more text.
+
\end{document}
</screen>
@@ -16993,8 +19372,8 @@ Some more text.
<indexterm role="cp"><primary>template, <literal>book</literal></primary></indexterm>
-<para>This is a straightforward template for a book. See See <link linkend="Larger-book-template">Larger book
-template</link> for a more elaborate one.
+<para>This is a straightforward template for a book. See <link linkend="Larger-book-template">Larger book
+template</link>, for a more elaborate one.
</para>
<screen>\documentclass{book}
\title{Book Class Template}
@@ -17011,6 +19390,7 @@ Some other text.
\section{A subtopic}
The end.
+
\end{document}
</screen>
@@ -17020,19 +19400,22 @@ The end.
<indexterm role="cp"><primary>template, <literal>book</literal></primary></indexterm>
-<para>This is a more elaborate template for a book. It has
-<literal>\frontmatter</literal>, <literal>\mainmatter</literal>, and <literal>\backmatter</literal> to
-control the typography of the three main areas of a book
-(see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp; \mainmatter &amp; \backmatter</link>). The book has a
-bibliography and an index.
+<para>This is a somewhat elaborate template for a book. See <link linkend="book-template">book template</link>,
+for a simpler one.
</para>
-<para>Notable is that it uses <literal>\include</literal> and <literal>\includeonly</literal>
+<para>This template uses <literal>\frontmatter</literal>, <literal>\mainmatter</literal>, and
+<literal>\backmatter</literal> to control the typography of the three main areas
+of a book (see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp; \mainmatter &amp; \backmatter</link>). The
+book has a bibliography and an index.
+</para>
+<para>Also notable is that it uses <literal>\include</literal> and <literal>\includeonly</literal>
(see <link linkend="Splitting-the-input">Splitting the input</link>). While you are working on a chapter you
can comment out all the other chapter entries from the argument to
-<literal>\includeonly</literal>. That will speed up compilation without losing any
-information such as cross-references. (Material that does not need to
-come on a new page is brought in with <literal>\input</literal> instead of
-<literal>\include</literal>. You don&#8217;t get the cross-reference benefit this way.)
+<literal>\includeonly</literal>. That will speed up compilation without losing
+any information such as cross-references. (Material that does not
+need to come on a new page is brought in with <literal>\input</literal> instead of
+<literal>\include</literal>. You don&#8217;t get the cross-reference benefit with
+<literal>\input</literal>.)
</para>
<screen>\documentclass[titlepage]{book}
\usepackage{makeidx}\makeindex
@@ -17041,11 +19424,12 @@ come on a new page is brought in with <literal>\input</literal> instead of
\author{Alex Author}
\includeonly{%
- frontcover,
+% frontcover,
preface,
chap1,
- ...
+% appenA,
}
+
\begin{document}
\frontmatter
\include{frontcover}
@@ -17053,111 +19437,22 @@ come on a new page is brought in with <literal>\input</literal> instead of
\maketitle \input{dedication} \input{copyright}
\tableofcontents
\include{preface}
+
\mainmatter
\include{chap1}
...
\appendix
-\include{appena}
+\include{appenA}
...
+
\backmatter
\bibliographystyle{apalike}
\addcontentsline{toc}{chapter}{Bibliography}
\bibliography
\addcontentsline{toc}{chapter}{Index}
\printindex
-\include{backcover}
-\end{document}
-</screen>
-
-</sect1>
-<sect1 label="A.5" id="tugboat-template">
-<title><literal>tugboat</literal> template</title>
-
-<indexterm role="cp"><primary>template, TUGboat</primary></indexterm>
-<indexterm role="cp"><primary>TUGboat template</primary></indexterm>
-<indexterm role="cp"><primary><literal>ltugboat</literal> class</primary></indexterm>
-
-<para><citetitle>TUGboat</citetitle> is the journal of the &tex; Users Group,
-<ulink url="http://tug.org/TUGboat">http://tug.org/TUGboat</ulink>.
-</para>
-<screen>\documentclass{ltugboat}
-
-\usepackage{graphicx}
-\usepackage{ifpdf}
-\ifpdf
-\usepackage[breaklinks,hidelinks]{hyperref}
-\else
-\usepackage{url}
-\fi
-
-%%% Start of metadata %%%
-
-\title{Example \TUB\ article}
-% repeat info for each author.
-\author{First Last}
-\address{Street Address \\ Town, Postal \\ Country}
-\netaddress{user (at) example dot org}
-\personalURL{http://example.org/~user/}
-
-%%% End of metadata %%%
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
-This is an example article for \TUB{}.
-Please write an abstract.
-\end{abstract}
-
-\section{Introduction}
-
-This is an example article for \TUB, linked from
-\url{http://tug.org/TUGboat/location.html}.
-
-We recommend the \texttt{graphicx} package for image inclusions, and the
-\texttt{hyperref} package if active urls are desired (in the \acro{PDF}
-output). Nowadays \TUB\ is produced using \acro{PDF} files exclusively.
-
-The \texttt{ltugboat} class provides these abbreviations (and many more):
-% verbatim blocks are often better in \small
-\begin{verbatim}[\small]
-\AllTeX \AMS \AmS \AmSLaTeX \AmSTeX \aw \AW
-\BibTeX \CTAN \DTD \HTML
-\ISBN \ISSN \LaTeXe
-\mf \MFB
-\plain \POBox \PS
-\SGML \TANGLE \TB \TP
-\TUB \TUG \tug
-\UNIX \XeT \WEB \WEAVE
-
-\, \bull \Dash \dash \hyph
-
-\acro{FRED} -&gt; {\small[er] fred} % please use!
-\cs{fred} -&gt; \fred
-\meta{fred} -&gt; &lt;fred&gt;
-\nth{n} -&gt; 1st, 2nd, ...
-\sfrac{3/4} -&gt; 3/4
-\booktitle{Book of Fred}
-\end{verbatim}
-
-For references to other \TUB\ issue, please use the format
-\textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for our \nth{100} issue.
-
-This file is just a template. The \TUB\ style documentation is the
-\texttt{ltubguid} document at \url{http://ctan.org/pkg/tugboat}. (For
-\CTAN\ references, where sensible we recommend that form of url, using
-\texttt{/pkg/}; or, if you need to refer to a specific file location,
-\texttt{http://mirror.ctan.org/\textsl{path}}.)
-
-Email \verb|tugboat@tug.org| if problems or questions.
-
-\bibliographystyle{plain} % we recommend the plain bibliography style
-\nocite{book-minimal} % just making the bibliography non-empty
-\bibliography{xampl} % xampl.bib comes with BibTeX
-
-\makesignature
+\include{backcover}
\end{document}
</screen>