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.dbk2999
1 files changed, 1820 insertions, 1179 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.dbk b/info/latex2e-help-texinfo/latex2e.dbk
index 4569eac934..bba0d26b09 100644
--- a/info/latex2e-help-texinfo/latex2e.dbk
+++ b/info/latex2e-help-texinfo/latex2e.dbk
@@ -3,18 +3,18 @@
<!ENTITY tex "TeX">
<!ENTITY latex "LaTeX">
]>
-<book id="latex2e.dbk" lang="en">
+<book id="latex2e.dbk" lang="">
<title>&latex;2e: An unofficial reference manual</title>
-<subtitle>January 2023</subtitle>
-<titleabbrev>&latex;2e unofficial reference manual (January 2023)</titleabbrev>
+<subtitle>May 2024</subtitle>
+<titleabbrev>&latex;2e unofficial reference manual (May 2024)</titleabbrev>
<bookinfo><title>&latex;2e: An unofficial reference manual</title>
-<subtitle>January 2023</subtitle>
-<titleabbrev>&latex;2e unofficial reference manual (January 2023)</titleabbrev>
+<subtitle>May 2024</subtitle>
+<titleabbrev>&latex;2e unofficial reference manual (May 2024)</titleabbrev>
<authorgroup>
<collab><collabname><ulink url="https://latexref.xyz">https://latexref.xyz</ulink></collabname></collab>
</authorgroup>
<legalnotice><para>This document is an unofficial reference manual for &latex;, a
-document preparation system, version of January 2023.
+document preparation system, version of May 2024.
</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
@@ -83,6 +83,8 @@ by the &latex; maintainers.
<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>.
+This is a public list; you can (un)subscribe, view the archives, etc.,
+at <ulink url="https://lists.tug.org/latexrefman">https://lists.tug.org/latexrefman</ulink>.
</para>
<para>This document is a reference, not a tutorial. There is a vast array
of other information available about &latex;, at all levels. Here
@@ -101,8 +103,7 @@ are a few introductions.
<para>A longer introduction to &latex;, translated to many languages.
</para>
</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.
+</term><listitem><para>Overview of getting started with &tex; and &latex;.
</para>
</listitem></varlistentry></variablelist>
@@ -128,11 +129,12 @@ 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>&latex; is implemented as a set of so-called &#8220;macros&#8221; (a &tex;
+<firstterm>format</firstterm>) 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 input document is marked up, that is, to mean the set of commands
@@ -156,7 +158,7 @@ sensible, such as in plain text, write it as &#8216;<literal>LaTeX</literal>&#82
<indexterm role="cp"><primary>hello, world</primary></indexterm>
<para>&latex; files have a simple global structure, with a standard beginning
-and ending. This is a small example.
+and ending. Here is a small example:
</para>
<screen>\documentclass{article}
\begin{document}
@@ -167,21 +169,22 @@ Hello, \LaTeX\ world.
<literal>\end{document}</literal> line.
</para>
<indexterm role="cp"><primary>document class, defined</primary></indexterm>
-<para>Here, the &#8216;<literal>article</literal>&#8217; is the <firstterm>document class</firstterm>. It is implemented
-in a file <filename>article.cls</filename>. You can use any document class on your
-system. A few document classes are defined by &latex; itself, and vast
-array of others are widely available. See <link linkend="Document-classes">Document classes</link>.
+<para>Here, the &#8216;<literal>article</literal>&#8217; is the <firstterm>document class</firstterm>. It is
+implemented in a file <filename>article.cls</filename>. You can use any document
+class available on your system. A few document classes are defined by
+&latex; itself, and a vast array of others are available.
+See <link linkend="Document-classes">Document classes</link>.
</para>
<indexterm role="cp"><primary>preamble, defined</primary></indexterm>
<para>You can include other &latex; commands between the
<literal>\documentclass</literal> and the <literal>\begin{document}</literal> commands.
This area is called the <firstterm>preamble</firstterm>.
</para>
-<para>The <literal>\begin{document}</literal>, <literal>\end{document}</literal> pair defines an
<indexterm role="cp"><primary>environment</primary></indexterm>
-<firstterm>environment</firstterm>; the &#8216;<literal>document</literal>&#8217; environment (and no others) is
-required in all &latex; documents (see <link linkend="document">document</link>). &latex; make
-available to you many environments that are documented here
+<para>The <literal>\begin{document}</literal> &#8230; <literal>\end{document}</literal> pair
+defines an <firstterm>environment</firstterm>; the &#8216;<literal>document</literal>&#8217; environment (and no
+others) is required in all &latex; documents (see <link linkend="document">document</link>).
+&latex; provides many environments that are documented here
(see <link linkend="Environments">Environments</link>). Many more are available to you from external
packages, most importantly those available at CTAN (see <link linkend="CTAN">CTAN</link>).
</para>
@@ -280,8 +283,8 @@ open-ended.
<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
+<para>&latex; is a large set of commands (macros) 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>
@@ -308,7 +311,8 @@ command <command>etex</command>, but this is plain &tex; (and produces
</para>
<para>In other &tex; distributions, <command>latex</command> may invoke e-&tex;
rather than pdf&tex;. In any case, the e-&tex; extensions can be
-assumed to be available in &latex;.
+assumed to be available in &latex;, and a few extensions beyond
+e-&tex;, particularly for file manipulation.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lualatex</primary></indexterm><literal>lualatex</literal>
</term><listitem><indexterm role="cp"><primary>Lua&tex;</primary></indexterm>
@@ -336,6 +340,15 @@ 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><varlistentry><term><indexterm role="fn"><primary>hilatex</primary></indexterm><literal>hilatex</literal>
+</term><listitem><indexterm role="cp"><primary>Hi&tex;</primary></indexterm>
+<indexterm role="cp"><primary>HINT format</primary></indexterm>
+<indexterm role="cp"><primary>mobile output</primary></indexterm>
+<para>If &latex; is invoked via the system command <command>hilatex</command>, the
+Hi&tex; engine is run (<ulink url="https://ctan.org/pkg/hitex">https://ctan.org/pkg/hitex</ulink>). This
+program produces its own format, named HINT, designed especially for
+high-quality typesetting on mobile devices.
+</para>
</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
@@ -343,7 +356,7 @@ 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:
+all of the above, except <literal>hitex</literal>:
</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>
@@ -374,8 +387,215 @@ before being released.
<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="Input-text">
+<title>Input text</title>
+
+<para>To a first approximation, most input characters in &latex; print as
+themselves. But there are exceptions, as discussed in the following
+sections.
+</para>
+
+
+<sect2 label="2.4.1" id="Input-encodings">
+<title>Input encodings</title>
+
+<indexterm role="cp"><primary>character encoding</primary></indexterm>
+<indexterm role="cp"><primary>input encodings</primary></indexterm>
+<indexterm role="cp"><primary>encodings, input</primary></indexterm>
+
+<para>The input to &tex; (or any computer program) ultimately consists of a
+sequence of bytes. (Nowadays, a byte is almost universally an
+eight-bit number, i.e., an integer between 0 and 255, inclusive.) The
+input encoding defines how to interpret that sequence of bytes, and
+thus how &latex; behaves.
+</para>
+<!-- UTF-8 -->
+<indexterm role="cp"><primary>Unicode</primary></indexterm>
+<para>Today, by far the most common way to encode text is with <firstterm>UTF-8</firstterm>, a
+so-called &#8220;Unicode Transformation Format&#8221; which specifies how to
+transform a sequence of 8-bit bytes to Unicode code points, which are
+defined independent of any particular representation. The Unicode
+encoding defines code points for virtually all characters used
+today in written text.
+</para>
+<para>When &tex; was created, Unicode and UTF-8 did not exist and the 7-bit
+ASCII encoding was by far the most widely used. So &tex; does not
+require Unicode for text input. UTF-8 is a superset of ASCII, so a
+pure 7-bit ASCII document is also UTF-8.
+</para>
+<para>Since 2018, the default input encoding for &latex; is UTF-8.
+Some methods for handling documents written in some other encoding,
+such as ISO-8859-1 (Latin 1), are explained in <link linkend="inputenc-package">inputenc package</link>.
+</para>
+<para>You can easily find more about all these topics in any introductory
+computer text or online. For example, you might start at:
+<ulink url="https://en.wikipedia.org/wiki/Unicode">https://en.wikipedia.org/wiki/Unicode</ulink>.
+</para>
+</sect2>
+<sect2 label="2.4.2" id="Ligatures">
+<title>Ligatures</title>
+
+<indexterm role="cp"><primary>ligatures</primary></indexterm>
+
+<para>A <firstterm>ligature</firstterm> combines two or more letters (more generally,
+characters) into a single glyph. For example, in Latin-based
+typography, the two letters &#8216;<literal>f</literal>&#8217; and &#8216;<literal>i</literal>&#8217; are often combined
+into the glyph &#8216;fi&#8217;.
+</para>
+<para>&tex; supports ligatures automatically. To continue the example, if
+the input has the word &#8216;<literal>fine</literal>&#8217;, written as four separate ASCII
+characters, &tex; will output the word &#8216;fine&#8217; (with the default
+fonts), with three typeset glyphs.
+</para>
+<para>In traditional &tex;, the available ligatures, if any, are defined by
+the current font. &tex; also uses the ligature mechanism to produce
+a few typographical characters which were not available in any
+computer encoding when &tex; was invented. In all, in the original
+Computer Modern fonts, the following input character sequences are
+defined to lead to ligatures:
+</para>
+<indexterm role="cp"><primary>f-ligatures</primary></indexterm>
+<indexterm role="cp"><primary>double quotation marks, as ligatures</primary></indexterm>
+<indexterm role="cp"><primary>quotation marks, as ligatures</primary></indexterm>
+<indexterm role="cp"><primary>en-dash, as ligature</primary></indexterm>
+<indexterm role="cp"><primary>em-dash, as ligature</primary></indexterm>
+<indexterm role="cp"><primary>inverted exclamation mark, as ligature</primary></indexterm>
+<indexterm role="cp"><primary>inverted question mark, as ligature</primary></indexterm>
+<indexterm role="cp"><primary>Spanish exclamation mark, as ligature</primary></indexterm>
+<indexterm role="cp"><primary>Spanish question mark, as ligature</primary></indexterm>
+
+<variablelist><varlistentry><term>&#8216;<literal>ff</literal>&#8217;
+</term><listitem><para>ff (ff ligature, U+FB00)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>fi</literal>&#8217;
+</term><listitem><para>fi (fi ligature, U+FB01)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>fl</literal>&#8217;
+</term><listitem><para>fl (fl ligature, U+FB02)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>ffi</literal>&#8217;
+</term><listitem><para>ffi (ffi ligature, U+FB03)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>ffl</literal>&#8217;
+</term><listitem><para>ffl (ffl ligature, U+FB04)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>``</literal>&#8217;
+</term><listitem><para>&#8220; (left double quotation mark, U+201C)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>''</literal>&#8217;
+</term><listitem><para>&#8221; (right double quotation mark, U+201D)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>--</literal>&#8217;
+</term><listitem><para>&#8211; (en-dash, U+2013)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>---</literal>&#8217;
+</term><listitem><para>&#8212; (em-dash, U+2014)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>!`</literal>&#8217;
+</term><listitem><para>!&#8216; (inverted exclamation mark, U+00A1)
+</para></listitem></varlistentry><varlistentry><term>&#8216;<literal>?`</literal>&#8217;
+</term><listitem><para>?&#8216; (inverted question mark, U+00BF)
+</para></listitem></varlistentry></variablelist>
+<para>(For the f-ligatures above, the text in parentheses shows the
+individual characters, so in the typeset output you can easily see the
+difference between the ligature and the original character sequence.)
+</para>
+<para>Nowadays it&#8217;s usually possible to directly input the punctuation
+characters as Unicode characters, and &latex; supports that (see
+previous section). But even today, it can still often be useful to
+use the ASCII ligature input form; for example, the difference between
+an en-dash and em-dash, as a single glyph, can be all but impossible
+to discern, but the difference between two and three ASCII hyphen
+characters is clear. Similarly with quotation marks, in some fonts.
+</para>
+<para>Thus, even the engines with native support for UTF-8, namely Lua&tex;
+and Xe&tex;, also support the ASCII ligature input sequences by
+default, independent of the font used. They also need to do so for
+compatibility.
+</para>
+<indexterm role="cp"><primary>alphabetic presentation forms Unicode block</primary></indexterm>
+<para>By the way, the f-ligatures are also available in Unicode (the
+&#8220;Alphabetic Presentation Forms&#8221; block starting at U+FB00), but it&#8217;s
+almost never desirable to use them as input characters, since in
+principle it should be up to the typesetter and the current font
+whether to use ligatures. Also, in practice, using them will
+typically cause searches to fail, that is, a search for the two
+characters &#8216;<literal>fi</literal>&#8217; will not be matched by the ligature &#8216;fi&#8217; at
+U+FB01.
+</para>
+
+</sect2>
+<sect2 label="2.4.3" id="Special-characters">
+<title>Special characters: <literal>\ { } % $ &amp; _ ^ # ~</literal></title>
+
+<anchor id="Reserved-characters"/><!-- old node name -->
+<indexterm role="cp"><primary>reserved characters, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>special characters, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>meaning of special characters</primary></indexterm>
+
+<para>Besides ligatures (see previous section), a few individual characters
+have special meaning to &latex;. They are called <firstterm>reserved
+characters</firstterm> or <firstterm>special characters</firstterm>. Here they are:
+</para>
+<variablelist><varlistentry><term>&#8216;<literal>\</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>\ character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>backslash, meaning of</primary></indexterm>
+<para>Introduces a command name, as seen throughout this manual.
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>{</literal>&#8217;
+</term><term>&#8216;<literal>}</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>{ character, meaning of</primary></indexterm>
+<indexterm role="fn"><primary>} character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>left brace, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>right brace, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>braces, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>curly braces, meaning of</primary></indexterm>
+<para>Delimits a required argument to a command or a level of grouping, as
+seen throughout this manual.
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>%</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>% character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>percent character, meaning of</primary></indexterm>
+<para>Starts a comment: the &#8216;<literal>%</literal>&#8217; and all remaining characters on the
+current line are ignored.
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>$</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>$ character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>dollar sign character, meaning of</primary></indexterm>
+<para>Starts and ends math mode (see <link linkend="Math-formulas">Math formulas</link>).
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>&amp;</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>&amp; character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>ampersand character, meaning of</primary></indexterm>
+<para>Separates cells in a table (see <link linkend="tabular">tabular</link>).
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>_</literal>&#8217;
+</term><term>&#8216;<literal>^</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>_ character, meaning of</primary></indexterm>
+<indexterm role="fn"><primary>^ character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>underscore character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>hat character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>caret character, meaning of</primary></indexterm>
+<para>Introduce a subscript or superscript, respectively, in math
+(see <link linkend="Subscripts-_0026-superscripts">Subscripts &amp; superscripts</link>); they produce an error outside
+math mode. As a little-used special feature, two superscript
+characters in a row can introduce special notation for an arbitrary
+character.
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>#</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary># character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>number sign character (<literal>#</literal>), meaning of</primary></indexterm>
+<indexterm role="cp"><primary>sharp character (<literal>#</literal>), meaning of</primary></indexterm>
+<indexterm role="cp"><primary>hash character (<literal>#</literal>), meaning of</primary></indexterm>
+<para>Stands for arguments in a macro definition (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
+\renewcommand</link>).
+</para>
+</listitem></varlistentry><varlistentry><term>&#8216;<literal>~</literal>&#8217;
+</term><listitem><indexterm role="fn"><primary>~ character, meaning of</primary></indexterm>
+<indexterm role="cp"><primary>tilde character, meaning of</primary></indexterm>
+<para>Produces a nonbreakable interword space (see <link linkend="_007e">~</link>).
+</para>
+</listitem></varlistentry></variablelist>
+<para>See <link linkend="Printing-special-characters">Printing special characters</link>, for how to typeset these
+characters when you need them literally.
+</para>
+
+</sect2>
</sect1>
-<sect1 label="2.4" id="LaTeX-command-syntax">
+<sect1 label="2.5" id="LaTeX-command-syntax">
<title>&latex; command syntax</title>
<indexterm role="cp"><primary>command syntax</primary></indexterm>
@@ -386,17 +606,18 @@ before being released.
character, <literal>\</literal>. The name itself then consists of either
(a)&#160;a string of letters or (b)&#160;a single non-letter.
</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 command names are lowercase, but in any event you must enter all
-commands in the same case as they are defined.
+<para>&latex; commands names are case sensitive; for example,
+<literal>\pagebreak</literal> differs from <literal>\Pagebreak</literal> (the latter is not a
+standard command). 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
arguments may be either required or optional. Required arguments are
contained in curly braces, <literal>{...}</literal>. Optional arguments are
contained in square brackets, <literal>[...]</literal>. Generally, but not
universally, if the command accepts an optional argument, it comes
-first, before any required arguments.
+first, before any required arguments; optional arguments could come
+after required arguments, or both before and after.
</para>
<para>Inside of an optional argument, to use the character close square
bracket&#160;(<literal>]</literal>) hide it inside curly braces, as
@@ -405,10 +626,10 @@ 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>&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
-to command.
+<para>&latex; has the convention that some commands have a <literal>*</literal> form
+that is closely related to the form without a <literal>*</literal>, such as
+<literal>\chapter</literal> and <literal>\chapter*</literal>. The difference in behavior
+varies from command to command.
</para>
<para>This manual describes all accepted options and <literal>*</literal>-forms for the
commands it covers (barring unintentional omissions, a.k.a. bugs).
@@ -423,12 +644,13 @@ commands it covers (barring unintentional omissions, a.k.a. bugs).
<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
+syntax. We won&#8217;t try to cover that in this document; see the related
package documentation and other &latex; manuals.
</para>
+
</sect1>
-<sect1 label="2.5" id="Environment">
-<title>Environment</title>
+<sect1 label="2.6" id="Environment-syntax">
+<title>Environment syntax</title>
<para>Synopsis:
</para>
@@ -460,12 +682,53 @@ the table to be aligned on its top row) while the second argument is
required (it specifies the formatting of columns).
</para>
<screen>\begin{tabular}[t]{r|l}
- ... rows of table ...
+ ... <replaceable>rows-of-table</replaceable> ...
\end{tabular}
</screen>
</sect1>
-<sect1 label="2.6" id="CTAN">
+<sect1 label="2.7" id="_005cDocumentMetadata">
+<title><literal>\DocumentMetadata</literal>: Producing tagged PDF output</title>
+
+<indexterm role="fn"><primary>\DocumentMetadata</primary></indexterm>
+<indexterm role="cp"><primary>tagged PDF</primary></indexterm>
+<indexterm role="cp"><primary>PDF, tagged</primary></indexterm>
+<indexterm role="cp"><primary>metadata, adding</primary></indexterm>
+<indexterm role="cp"><primary>accessibility</primary></indexterm>
+
+<para>The <literal>\DocumentMetadata</literal> command was added to &latex; in 2022.
+It enables so-called &#8220;tagging&#8221; of the PDF output, aiding
+accessibility of the PDF. It is supported best with Lua&latex;;
+pdf&latex; and Xe&latex; are supported as well as possible
+(see <link linkend="TeX-engines">&tex; engines</link>).
+</para>
+<para>It is unlike nearly any other command in &latex; in that it must
+occur before the <literal>\documentclass</literal> command that starts a &latex;
+document proper (see <link linkend="_005cdocumentclass">\documentclass</link>). Therefore it must be
+called with <literal>\RequirePackage</literal> rather than <literal>\usepackage</literal>
+(see <link linkend="_005cRequirePackage">\RequirePackage</link>).
+</para>
+<indexterm role="cp"><primary>package, <literal>latex-lab</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>latex-lab</literal> package</primary></indexterm>
+
+<indexterm role="fn"><primary>documentmetadata-support-doc document</primary></indexterm>
+<para>This support is still in development, so we will not try to list all
+the possible settings. Please see the
+<literal>documentmetadata-support-doc</literal> document, part of the
+<literal>latex-lab</literal> package (<ulink url="https://ctan.org/pkg/latex-lab">https://ctan.org/pkg/latex-lab</ulink>). Here
+is a simple example which enables most tagging currently implemented:
+</para>
+<screen>\DocumentMetadata{testphase={phase-III,firstaid}}
+\documentclass{article}
+...
+</screen>
+<para>As you can see from the key name <literal>testphase</literal>, this is all still
+in an experimental phase. The &latex; developers strongly encourage
+users to give it a try and report problems, so it can be improved.
+</para>
+
+</sect1>
+<sect1 label="2.8" id="CTAN">
<title>CTAN: The Comprehensive &tex; Archive Network</title>
<indexterm role="cp"><primary>CTAN</primary></indexterm>
@@ -481,7 +744,7 @@ 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 <literal>ctan.org</literal> web site
+<para>In addition to its 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>
@@ -504,12 +767,13 @@ site. The list of mirrors is at <ulink url="https://ctan.org/mirrors">https://ct
<chapter label="3" id="Document-classes">
<title>Document classes</title>
-<indexterm role="cp"><primary>document classes</primary></indexterm>
+<anchor id="_005cdocumentclass"/><indexterm role="cp"><primary>document classes</primary></indexterm>
<indexterm role="cp"><primary>classes of documents</primary></indexterm>
<indexterm role="fn"><primary>\documentclass</primary></indexterm>
-<para>The document&#8217;s overall class is defined with this command, which is
-normally the first command in a &latex; source file.
+<para>The document&#8217;s overall class is defined with the <literal>\documentclass</literal>
+command, which is normally the first command in a &latex; source
+file.
</para>
<screen>\documentclass[<replaceable>options</replaceable>]{<replaceable>class</replaceable>}
</screen>
@@ -519,8 +783,8 @@ normally the first command in a &latex; source file.
<indexterm role="fn"><primary>letter class</primary></indexterm>
<indexterm role="fn"><primary>slides class</primary></indexterm>
<para>The following document <replaceable>class</replaceable> names are built into &latex;.
-(Many other document classes are available as separate packages;
-see <link linkend="Overview">Overview</link>.)
+Many other document classes are available as separate packages
+(see <link linkend="Overview">Overview</link>).
</para>
<variablelist><varlistentry><term><literal>article</literal>
</term><listitem><anchor id="document-classes-article"/><para>For a journal article, a presentation, and miscellaneous general use.
@@ -540,7 +804,7 @@ 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 nowadays. The
-<literal>beamer</literal> package is perhaps the most prevalent
+<literal>beamer</literal> package is perhaps the most prevalent replacement
(<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>
@@ -563,13 +827,17 @@ specify more than one <replaceable>option</replaceable>, separate them with a co
</para>
<screen>\documentclass[<replaceable>option1</replaceable>,<replaceable>option2</replaceable>,...]{<replaceable>class</replaceable>}
</screen>
+<para>&latex; automatically passes options specified for
+<literal>\documentclass</literal> on to any other loaded classes that can handle
+them.
+</para>
<para>Here is the list of the standard class options.
</para>
<indexterm role="fn"><primary>10pt option</primary></indexterm>
<indexterm role="fn"><primary>11pt option</primary></indexterm>
<indexterm role="fn"><primary>12pt option</primary></indexterm>
<para>All of the standard classes except <literal>slides</literal> accept the following
-options for selecting the typeface size (default is <literal>10pt</literal>):
+options for selecting the typeface size; the default is <literal>10pt</literal>:
</para>
<screen>10pt 11pt 12pt
</screen>
@@ -580,7 +848,7 @@ options for selecting the typeface size (default is <literal>10pt</literal>):
<indexterm role="fn"><primary>legalpaper option</primary></indexterm>
<indexterm role="fn"><primary>letterpaper option</primary></indexterm>
<para>All of the standard classes accept these options for selecting the paper
-size (these show height by width):
+size (dimensions are listed height by width):
</para>
<variablelist><varlistentry><term><literal>a4paper</literal>
</term><listitem><para>210 by 297mm (about 8.25 by 11.75&#160;inches)
@@ -607,14 +875,12 @@ size (these show height by width):
<para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex;
(see <link linkend="TeX-engines">&tex; engines</link>), options other than <literal>letterpaper</literal> set
-the print area but you must also set the physical paper size. One way
-to do that is to put <literal>\pdfpagewidth=\paperwidth</literal> and
-<literal>\pdfpageheight=\paperheight</literal> in your document&#8217;s preamble.
-<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm>
-</para>
-<para>The <literal>geometry</literal> package provides flexible ways of setting the print
-area and physical page size.
+the print area but you must also set the physical paper size. Usually,
+the <literal>geometry</literal> package is the best way to do that; it
+provides flexible ways of setting the print area and physical page size.
+Otherwise, setting the paper size is engine-dependent. For example,
+with pdf&latex;, you could include <literal>\pdfpagewidth=\paperwidth</literal> and
+<literal>\pdfpageheight=\paperheight</literal> in the preamble.
</para>
<indexterm role="fn"><primary>draft option</primary></indexterm>
<indexterm role="fn"><primary>final option</primary></indexterm>
@@ -699,32 +965,44 @@ the time at the bottom of each note.
</para>
</sect1>
-<sect1 label="3.2" id="Additional-packages">
-<title>Additional packages</title>
+<sect1 label="3.2" id="_005cusepackage">
+<title><literal>\usepackage</literal>: Additional packages</title>
+<anchor id="Additional-packages"/><!-- original node name -->
<indexterm role="cp"><primary>loading additional packages</primary></indexterm>
<indexterm role="cp"><primary>packages, loading additional</primary></indexterm>
<indexterm role="cp"><primary>additional packages, loading</primary></indexterm>
<indexterm role="fn"><primary>\usepackage</primary></indexterm>
-<para>Load a package <replaceable>pkg</replaceable>, with the package options given in the comma-separated
-list <replaceable>options</replaceable>, as here.
+<para>To load a package <replaceable>pkg</replaceable>, with the package options given in the
+comma-separated list <replaceable>options</replaceable>:
</para>
-<screen>\usepackage[<replaceable>options</replaceable>]{<replaceable>pkg</replaceable>}.
+<screen>\usepackage[<replaceable>options</replaceable>]{<replaceable>pkg</replaceable>}[<replaceable>mindate</replaceable>]
</screen>
<para>To specify more than one package you can separate them with a comma,
as in <literal>\usepackage{<replaceable>pkg1</replaceable>,<replaceable>pkg2</replaceable>,...}</literal>, or use multiple
<literal>\usepackage</literal> commands.
</para>
+<para>If the <replaceable>mindate</replaceable> optional argument is given, &latex; gives a
+warning if the loaded package has an earlier date, i.e., is too old.
+The <replaceable>mindate</replaceable> argument must be in the form <literal>YYYY/MM/DD</literal>.
+More info on this: <ulink url="https://tex.stackexchange.com/questions/47743">https://tex.stackexchange.com/questions/47743</ulink>.
+</para>
+<para><literal>\usepackage</literal> must be used in the document preamble, between the
+<literal>\documentclass</literal> declaration and the <literal>\begin{document}</literal>.
+Occasionally it is necessary to load packages before the
+<literal>\documentclass</literal>; see <literal>\RequirePackage</literal> for that
+(see <link linkend="_005cRequirePackage">\RequirePackage</link>).
+</para>
<indexterm role="cp"><primary>global options</primary></indexterm>
<indexterm role="cp"><primary>options, global</primary></indexterm>
-<para>Any options given in the <literal>\documentclass</literal> command that are unknown
-to the selected document class are passed on to the packages loaded with
-<literal>\usepackage</literal>.
+<para>Any options given in the global <literal>\documentclass</literal> command that are
+unknown to the selected document class are passed on to the packages
+loaded with <literal>\usepackage</literal>.
</para>
</sect1>
-<sect1 label="3.3" id="Class-and-package-construction">
-<title>Class and package construction</title>
+<sect1 label="3.3" id="Class-and-package-creation">
+<title>Class and package creation</title>
<indexterm role="cp"><primary>document class commands</primary></indexterm>
<indexterm role="cp"><primary>commands, document class</primary></indexterm>
@@ -736,27 +1014,29 @@ standard header for each page, then you could create a new class
<literal>smcmemo.cls</literal> and begin your documents with
<literal>\documentclass{smcmemo}</literal>.
</para>
-<para>What separates a package from a document class is that the commands in a
-package are useful across classes while those in a document class are
-specific to that class. Thus, a command to set page headers is for a
-package while a command to make the page headers say <literal>Memo from the
-SMC Math Department</literal> is for a class.
<indexterm role="cp"><primary>class and package difference</primary></indexterm>
<indexterm role="cp"><primary>difference between class and package</primary></indexterm>
-</para>
-<para>Inside of a class or package file you can use the at-sign <literal>@</literal> as a
-character in command names without having to surround the code
-containing that command with <literal>\makeatletter</literal> and
-<literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>. This allow
-you to create commands that users will not accidentally redefine.
-Another technique is to preface class- or package-specific commands with
-some string to prevent your class or package from interfering with
-others. For instance, the class <literal>smcmemo</literal> might have commands
+<para>What separates a package from a document class is that the commands in
+a package are useful across classes while those in a document class
+are specific to that class. Thus, a command to set page headers is
+for a package while a command to make the page headers be
+<literal>Memo from the SMC Math Department</literal> is for a class.
+</para>
+<para>Inside of a class or package definition you can use the at-sign
+<literal>@</literal> as a character in command names without having to surround
+the code containing that command with <literal>\makeatletter</literal> and
+<literal>\makeatother</literal> (see <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>). This
+allows you to create commands that users will not accidentally
+redefine.
+</para>
+<para>It is also highly desirable to prefix class- or package-specific
+commands with your package name or similar string, to prevent your
+definitions from clashing with those from other packages. For
+instance, the class <literal>smcmemo</literal> might have commands
<literal>\smc@tolist</literal>, <literal>\smc@fromlist</literal>, etc.
</para>
-
<sect2 label="3.3.1" id="Class-and-package-structure">
<title>Class and package structure</title>
@@ -769,7 +1049,8 @@ others. For instance, the class <literal>smcmemo</literal> might have commands
<indexterm role="cp"><primary>package options</primary></indexterm>
<para>A class file or package file typically has four parts.
-</para><orderedlist numeration="arabic"><listitem><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex;
+</para>
+<orderedlist numeration="arabic"><listitem><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex;
package or class and describes itself, using the <literal>\NeedsTeXFormat</literal>
and <literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands.
</para>
@@ -793,6 +1074,7 @@ document font size.
usually does most of its work: declaring new variables, commands and
fonts, and loading other files.
</para></listitem></orderedlist>
+<indexterm role="cp"><primary>class file example</primary></indexterm>
<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
<filename>.tex</filename> file.
@@ -802,422 +1084,22 @@ where &latex; can find it, for example in the same directory as the
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
\ProcessOptions\relax
\LoadClass{article}
-</screen><indexterm role="cp"><primary>class file example</primary></indexterm>
-
+</screen>
<para>It identifies itself, handles the class options via the default of
passing them all to the <literal>article</literal> class, and then loads the
<literal>article</literal> class to provide the basis for this class&#8217;s code.
</para>
+<indexterm role="fn"><primary>clsguide document</primary></indexterm>
+<indexterm role="cp"><primary>Class Guide, document</primary></indexterm>
+<indexterm role="cp"><primary>class writing tutorial document</primary></indexterm>
<para>For more, see the official guide for class and package writers, the
-Class Guide, at
-<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>
-
-</sect2>
-<sect2 label="3.3.2" id="Class-and-package-commands">
-<title>Class and package commands</title>
-<indexterm role="cp"><primary>class and package commands</primary></indexterm>
-<indexterm role="cp"><primary>commands, class and package</primary></indexterm>
-
-<para>These are the commands designed to help writers of classes or packages.
-</para>
-<variablelist><varlistentry><term><literal>\AtBeginDvi{specials}</literal>
-</term><listitem><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm>
-<para>Save in a box register things that are written to the <filename>.dvi</filename> file
-at the beginning of the shipout of the first page of the document.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\AtEndOfClass{<replaceable>code</replaceable>}</literal>
-</term><term><literal>\AtEndOfPackage{<replaceable>code</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\AtEndOfClass</primary></indexterm>
-<indexterm role="fn"><primary>\AtEndOfPackage</primary></indexterm>
-<para>Hook to insert <replaceable>code</replaceable> to be executed when &latex; finishes
-processing the current class or package. You can use these hooks
-multiple times; the <literal>code</literal> will be executed in the order that you
-called it. See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\CheckCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
-</term><term><literal>\CheckCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\CheckCommand</primary></indexterm>
-<indexterm role="fn"><primary>\CheckCommand*</primary></indexterm>
-<indexterm role="cp"><primary>new command, checking</primary></indexterm>
-<para>Like <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>) but does
-not define <replaceable>cmd</replaceable>; instead it checks that the current definition of
-<replaceable>cmd</replaceable> is exactly as given by <replaceable>definition</replaceable> and is or is not
-<indexterm role="cp"><primary>long command</primary></indexterm>
-<firstterm>long</firstterm> as expected. A long command is a command that accepts
-<literal>\par</literal> within an argument. The <replaceable>cmd</replaceable> command is expected to be
-long with the unstarred version of <literal>\CheckCommand</literal>. Raises an
-error when the check fails. This allows you to check before you start
-redefining <literal>cmd</literal> yourself that no other package has already
-redefined this command.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal>
-</term><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal>
-</term><term><literal>\ClassWarningNoLine{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal>
-</term><term><literal>\ClassInfo{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal>
-</term><term><literal>\ClassInfoNoLine{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal>
-</term><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal>
-</term><term><literal>\PackageWarning{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal>
-</term><term><literal>\PackageWarningNoLine{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal>
-</term><term><literal>\PackageInfo{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal>
-</term><term><literal>\PackageInfoNoLine{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\ClassError</primary></indexterm>
-<indexterm role="fn"><primary>\PackageError</primary></indexterm>
-<indexterm role="fn"><primary>\ClassWarning</primary></indexterm>
-<indexterm role="fn"><primary>\PackageWarning</primary></indexterm>
-<indexterm role="fn"><primary>\ClassWarningNoLine</primary></indexterm>
-<indexterm role="fn"><primary>\PackageWarningNoLine</primary></indexterm>
-<indexterm role="fn"><primary>\ClassInfo</primary></indexterm>
-<indexterm role="fn"><primary>\PackageInfo</primary></indexterm>
-<indexterm role="fn"><primary>\ClassInfoNoLine</primary></indexterm>
-<indexterm role="fn"><primary>\PackageInfoNoLine</primary></indexterm>
-<para>Produce an error message, or warning or informational messages.
-</para>
-<para>For <literal>\ClassError</literal> and <literal>\PackageError</literal> the message is
-<replaceable>error text</replaceable>, followed by &tex;&#8217;s <literal>?</literal> error prompt. If the
-user then asks for help by typing <literal>h</literal>, they see the <replaceable>help
-text</replaceable>.
-</para>
-<para>The four warning commands are similar except that they write
-<replaceable>warning text</replaceable> on the screen with no error prompt. The four info
-commands write <replaceable>info text</replaceable> only in the transcript file. The
-<literal>NoLine</literal> versions do not show the number of the line generating the
-message, while the other versions do show that number.
-</para>
-<para>To format the messages, including the <replaceable>help text</replaceable>: use
-<literal>\protect</literal> to stop a command from expanding, get a line break with
-<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal> when a space
-character does not allow it, like after a command. Note that &latex;
-appends a period to the messages.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\CurrentOption</literal>
-</term><listitem><indexterm role="fn"><primary>\CurrentOption</primary></indexterm>
-<para>Expands to the name of the currently-being-processed option. Can only
-be used within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal>
-or <literal>\DeclareOption*</literal>.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal>
-</term><term><literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\DeclareOption</primary></indexterm>
-<indexterm role="fn"><primary>\DeclareOption*</primary></indexterm>
-<indexterm role="cp"><primary>class options</primary></indexterm>
-<indexterm role="cp"><primary>package options</primary></indexterm>
-<indexterm role="cp"><primary>options, class</primary></indexterm>
-<indexterm role="cp"><primary>options, package</primary></indexterm>
-<para>Make an option available to a user to invoke in their
-<literal>\documentclass</literal> command. For example, the <literal>smcmemo</literal> class
-could have an option <literal>\documentclass[logo]{smcmemo}</literal> allowing
-users to put the institutional logo on the first page. The class file
-must contain <literal>\DeclareOption{logo}{<replaceable>code</replaceable>}</literal> (and later,
-<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 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>
-<screen>\DeclareOption*{%
-\PassOptionsToClass{\CurrentOption}{article}%
-}
-</screen>
-<para>Another example is that the class <literal>smcmemo</literal> may allow users to keep
-lists of memo recipients in external files. Then the user could invoke
-<literal>\documentclass[math]{smcmemo}</literal> and it will read the file
-<literal>math.memo</literal>. This code handles the file if it exists and otherwise
-passes the option to the <literal>article</literal> class.
-</para>
-<screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
- \PassOptionsToClass{\CurrentOption}{article}}}
-</screen>
-</listitem></varlistentry><varlistentry><term><literal>\DeclareRobustCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
-</term></varlistentry><varlistentry><term><literal>* \DeclareRobustCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\DeclareRobustCommand</primary></indexterm>
-<indexterm role="fn"><primary>\DeclareRobustCommand*</primary></indexterm>
-<indexterm role="cp"><primary>new command, definition</primary></indexterm>
-<para>Like <literal>\newcommand</literal> and <literal>\newcommand*</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
-\renewcommand</link>) but these declare a robust command, even if some code
-within the <replaceable>definition</replaceable> is fragile. (For a discussion of robust and
-fragile commands see <link linkend="_005cprotect">\protect</link>.) Use this command to define new
-robust commands or to redefine existing commands and make them
-robust. Unlike <literal>\newcommand</literal> these do not give an error if macro
-<replaceable>cmd</replaceable> already exists; instead, a log message is put into the
-transcript file if a command is redefined.
-</para>
-<para>Commands defined this way are a bit less efficient than those defined
-using <literal>\newcommand</literal> so unless the command&#8217;s data is fragile and the
-command is used within a moving argument, use <literal>\newcommand</literal>.
-</para>
-<indexterm role="cp"><primary>package, <literal>etoolbox</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>etoolbox</literal> package</primary></indexterm>
-<para>The <literal>etoolbox</literal> package offers the commands
-<literal>\newrobustcmd</literal>, <literal>\newrobustcmd*</literal>, as well as the commands
-<literal>\renewrobustcmd</literal>, <literal>\renewrobustcmd*</literal>, and the commands
-<literal>\providerobustcmd</literal>, and <literal>\providerobustcmd*</literal>. These are
-similar to <literal>\newcommand</literal>, <literal>\newcommand*</literal>,
-<literal>\renewcommand</literal>, <literal>\renewcommand*</literal>, <literal>\providecommand</literal>, and
-<literal>\providecommand*</literal>, but define a robust <replaceable>cmd</replaceable> with two
-advantages as compared to <literal>\DeclareRobustCommand</literal>:
-</para><orderedlist numeration="arabic"><listitem><para>They use the low-level e-&tex; protection mechanism rather than the
-higher level &latex; <literal>\protect</literal> mechanism, so they do not incur
-the slight loss of performance mentioned above, and
-</para></listitem><listitem><para>They make the same distinction between <literal>\new&#8230;</literal>,
-<literal>\renew&#8230;</literal>, and <literal>\provide&#8230;</literal>, as the standard
-commands, so they do not just make a log message when you redefine
-<replaceable>cmd</replaceable> that already exists, in that case you need to use either
-<literal>\renew&#8230;</literal> or <literal>\provide&#8230;</literal> or you get an error.
-</para></listitem></orderedlist>
-</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>filename</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
-</term><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
-name</replaceable></filename> or <replaceable>false code</replaceable> otherwise. In the first case it executing
-<replaceable>true code</replaceable> and then inputs the file. Thus the command
+Class Guide, at <ulink url="https://ctan.org/pkg/clsguide">https://ctan.org/pkg/clsguide</ulink> (much of the
+description here derives from this document), or the tutorial at
+<ulink url="https://tug.org/TUGboat/tb26-3/tb84heff.pdf">https://tug.org/TUGboat/tb26-3/tb84heff.pdf</ulink>.
</para>
-<screen>\IfFileExists{img.pdf}{%
- \includegraphics{img.pdf}}{\typeout{!! img.pdf not found}
-</screen>
-<para>will include the graphic <filename>img.pdf</filename> if it is found and otherwise
-give a warning.
-</para>
-<para>This command looks for the file in all search paths that &latex; uses,
-not only in the current directory. To look only in the current
-directory do something like <literal>\IfFileExists{./filename}{<replaceable>true
-code</replaceable>}{<replaceable>false code</replaceable>}</literal>. If you ask for a filename without a
-<literal>.tex</literal> extension then &latex; will first look for the file by
-appending the <literal>.tex</literal>; for more on how &latex; handles file
-extensions see <link linkend="_005cinput">\input</link>.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\LoadClass[<replaceable>options list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><term><literal>\LoadClassWithOptions{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><listitem><indexterm role="fn"><primary>\LoadClass</primary></indexterm>
-<indexterm role="fn"><primary>\LoadClassWithOptions</primary></indexterm>
-<para>Load a class, as with <literal>\documentclass[<replaceable>options
-list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release info</replaceable>]</literal>. An example is
-<literal>\LoadClass[twoside]{article}</literal>.
-</para>
-<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The
-<replaceable>release date</replaceable> is optional. If present it must have the form
-<replaceable>YYYY/MM/DD</replaceable>.
-<!-- BTW, there are at-macros documented in macros2e.pdf to check the version -->
-<!-- and do some actions conditionnally on version later or not to some -->
-<!-- date. -->
+<para>See <link linkend="Class-and-package-commands">Class and package commands</link>, for some of the commands
+specifically intended for class and package writers.
</para>
-<para>If you request a <replaceable>release date</replaceable> and the date of the package
-installed on your system is earlier, then you get a warning on the
-screen and in the log like this.
-</para>
-<screen>You have requested, on input line 4, version `2038/01/19' of
-document class article, but only version `2014/09/29 v1.4h
-Standard LaTeX document class' is available.
-</screen>
-<para>The command version <literal>\LoadClassWithOptions</literal> uses the list of
-options for the current class. This means it ignores any options passed
-to it via <literal>\PassOptionsToClass</literal>. This is a convenience command
-that lets you build classes on existing ones, such as the standard
-<literal>article</literal> class, without having to track which options were passed.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\ExecuteOptions{<replaceable>options-list</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm>
-<para>For each option <replaceable>option</replaceable> in the <replaceable>options-list</replaceable>, in order, this command
-executes the command <literal>\ds@<replaceable>option</replaceable></literal>. If this command is not
-defined then that option is silently ignored.
-</para>
-<para>It can be used to provide a default option list before
-<literal>\ProcessOptions</literal>. For example, if in a class file you want the
-default to be 11pt fonts then you could specify
-<literal>\ExecuteOptions{11pt}\ProcessOptions\relax</literal>.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format date</replaceable>]</literal>
-</term><listitem><indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm>
-<para>Specifies the format that this class must be run under. Often issued
-as the first line of a class file, and most often used as:
-<literal>\NeedsTeXFormat{LaTeX2e}</literal>. When a document using that class is
-processed, the format name given here must match the format that is
-actually being run (including that the <replaceable>format</replaceable> string is case
-sensitive). If it does not match then execution stops with an error
-like &#8216;<literal>This file needs format `LaTeX2e' but this is `xxx'.</literal>&#8217;
-</para>
-<para>To specify a version of the format that you know to have certain
-features, include the optional <replaceable>format date</replaceable> on which those features
-were implemented. If present it must be in the form <literal>YYYY/MM/DD</literal>.
-If the format version installed on your system is earlier than
-<replaceable>format date</replaceable> then you get a warning like this.
-</para>
-<screen>You have requested release `2038/01/20' of LaTeX, but only
-release `2016/02/01' is available.
-</screen>
-</listitem></varlistentry><varlistentry><term><literal>\OptionNotUsed</literal>
-</term><listitem><indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm>
-<para>Adds the current option to the list of unused options. Can only be used
-within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> or
-<literal>\DeclareOption*</literal>.
-</para>
-<!-- I cannot reproduce this behavior as it is documented in clsguide. -->
-<!-- In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues -->
-<!-- on the console a warning like @code{LaTeX Warning: Unused global -->
-<!-- option(s): [unusedoption].} with the list of not-used options when it -->
-<!-- reaches @code{\begin@{document@}}. -->
-
-</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>option list</replaceable>}{<replaceable>class name</replaceable>}</literal>
-</term><term><literal>\PassOptionsToPackage{<replaceable>option list</replaceable>}{<replaceable>package name</replaceable>}</literal>
-</term><listitem><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm>
-<indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm>
-<para>Adds the options in the comma-separated list <replaceable>option list</replaceable> to the
-options used by any future <literal>\RequirePackage</literal> or <literal>\usepackage</literal>
-command for package <replaceable>package name</replaceable> or the class <replaceable>class name</replaceable>.
-</para>
-<para>The reason for these commands is: you may load a package any number of
-times with no options but if you want options then you may only supply
-them when you first load the package. Loading a package with options
-more than once will get you an error like <literal>Option clash for package
-foo.</literal> (&latex; throws an error even if there is no conflict between the
-options.)
-</para>
-<para>If your own code is bringing in a package twice then you can collapse
-that to once, for example replacing the two
-<literal>\RequirePackage[landscape]{geometry}</literal> and
-<literal>\RequirePackage[margins=1in]{geometry}</literal> with the single command
-<literal>\RequirePackage[landscape,margins=1in]{geometry}</literal>.
-</para>
-<para>However, imagine that you are loading <filename>firstpkg</filename> and inside that
-package it loads <filename>secondpkg</filename>, and you need the second package to be
-loaded with option <literal>draft</literal>. Then before doing the first package
-you must queue up the options for the second package, like this.
-</para>
-<screen>\PassOptionsToPackage{draft}{secondpkg}
-\RequirePackage{firstpkg}
-</screen>
-<para>(If <literal>firstpkg.sty</literal> loads an option in conflict with what you want
-then you may have to alter its source.)
-</para>
-<para>These commands are useful for general users as well as class and package
-writers. For instance, suppose a user wants to load the <literal>graphicx</literal>
-package with the option <literal>draft</literal> and also wants to use a class
-<literal>foo</literal> that loads the <literal>graphicx</literal> package, but without that
-option. The user could start their &latex; file with
-<literal>\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}</literal>.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\ProcessOptions</literal>
-</term><term><literal>\ProcessOptions*<replaceable>\@options</replaceable></literal>
-</term><listitem><indexterm role="fn"><primary>\ProcessOptions</primary></indexterm>
-<indexterm role="fn"><primary>\ProcessOptions*</primary></indexterm>
-<para>Execute the code for each option that the user has invoked. Include it
-in the class file as <literal>\ProcessOptions\relax</literal> (because of the
-existence of the starred command).
-</para>
-<para>Options come in two types. <firstterm>Local options</firstterm> have been specified for this
-particular package in the <replaceable>options</replaceable> argument of
-<literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>,
-<literal>\usepackage[<replaceable>options</replaceable>]</literal>, or
-<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. <firstterm>Global options</firstterm> are those given
-by the class user in <literal>\documentclass[<replaceable>options</replaceable>]</literal> (If an option
-is specified both locally and globally then it is local.)
-</para>
-<para>When <literal>\ProcessOptions</literal> is called for a package <filename>pkg.sty</filename>, the
-following happens:
-</para><orderedlist numeration="arabic"><listitem><para>For each option <replaceable>option</replaceable> so far declared
-with <literal>\DeclareOption</literal>, it looks to see if that option is either a
-global or a local option for <literal>pkg</literal>. If so then it executes the
-declared code. This is done in the order in which these options were
-given in <filename>pkg.sty</filename>.
-</para></listitem><listitem><para>For each remaining local option, it executes the command
-<literal>\ds@</literal><replaceable>option</replaceable> if it has been defined somewhere (other than by
-a <literal>\DeclareOption</literal>); otherwise, it executes the default option code
-given in <literal>\DeclareOption*</literal>. If no default option code has been
-declared then it gives an error message. This is done in the order in
-which these options were specified.
-</para></listitem></orderedlist>
-<para>When <literal>\ProcessOptions</literal> is called for a class it works in the same
-way except that all options are local, and the default <replaceable>code</replaceable> for
-<literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error.
-</para>
-<para>The starred version <literal>\ProcessOptions*</literal> executes the
-options in the order specified in the calling commands, rather than in
-the order of declaration in the class or package. For a package this
-means that the global options are processed first.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal>
-</term><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal>
-</term><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><listitem><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm>
-<indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm>
-<para>Identifies the class or package, printing a message to the screen and
-the log file.
-</para>
-<para>When you load a class or package, for example with
-<literal>\documentclass{smcmemo}</literal> or <literal>\usepackage{test}</literal>, &latex;
-inputs a file. If the name of the file does not match the class or
-package name declared in it then you get a warning. Thus, if you invoke
-<literal>\documentclass{smcmemo}</literal>, and the file <filename>smcmemo.cls</filename> has
-the statement <literal>\ProvidesClass{xxx}</literal> then you get a warning like
-<literal>You have requested document class `smcmemo', but the document
-class provides 'xxx'.</literal> This warning does not prevent &latex; from
-processing the rest of the class file normally.
-</para>
-<para>If you include the optional argument then you must include a date,
-before any spaces, of the form <literal>YYYY/MM/DD</literal>. The rest of the
-optional argument is free-form, although it traditionally identifies the
-class, and is written to the screen during compilation and to the log
-file. Thus, if your file <filename>smcmemo.cls</filename> contains the line
-<literal>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</literal> and
-your document&#8217;s first line is <literal>\documentclass{smcmemo}</literal> then you
-will see <literal>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</literal>.
-</para>
-<para>The date in the optional argument allows class and package users to ask
-to be warned if the version of the class or package is earlier than
-<replaceable>release date</replaceable>. For instance, a user could enter
-<literal>\documentclass{smcmemo}[2018/10/12]</literal> or
-<literal>\usepackage{foo}[[2017/07/07]]</literal> to require a class or package
-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>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>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>
-</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>option list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><term><literal>\RequirePackageWithOptions{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
-</term><listitem><indexterm role="fn"><primary>\RequirePackage</primary></indexterm>
-<indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm>
-<para>Load a package, like the command <literal>\usepackage</literal> (see <link linkend="Additional-packages">Additional
-packages</link>). The &latex; development team strongly recommends use of
-these commands over Plain&#160;&tex;&#8217;s <literal>\input</literal>; see the Class
-Guide. An example is
-<literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>.
-</para>
-<para>The <replaceable>option list</replaceable>, if present, is a comma-separated list. The
-<replaceable>release date</replaceable>, if present, must have the form <replaceable>YYYY/MM/DD</replaceable>. If
-the release date of the package as installed on your system is earlier
-than <replaceable>release date</replaceable> then you get a warning like <literal>You have
-requested, on input line 9, version `2017/07/03' of package jhtest, but
-only version `2000/01/01' is available</literal>.
-</para>
-<para>The <literal>\RequirePackageWithOptions</literal> version uses the list of options
-for the current class. This means it ignores any options passed to it
-via <literal>\PassOptionsToClass</literal>. This is a convenience command to allow
-easily building classes on existing ones without having to track which
-options were passed.
-</para>
-<para>The difference between <literal>\usepackage</literal> and <literal>\RequirePackage</literal> is
-small. The <literal>\usepackage</literal> command is intended for the document file
-while <literal>\RequirePackage</literal> is intended for package and class files.
-Thus, using <literal>\usepackage</literal> before the <literal>\documentclass</literal> command
-causes &latex; to give error like <literal>\usepackage before
-\documentclass</literal>, but you can use <literal>\RequirePackage</literal> there.
-</para></listitem></varlistentry></variablelist>
</sect2>
</sect1>
@@ -1309,6 +1191,7 @@ 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>
@@ -1323,21 +1206,26 @@ 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>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.
+</term><listitem><indexterm role="cp"><primary>OT1 encoding</primary></indexterm>
+<para>The original 7-bit 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.
+</term><listitem><indexterm role="cp"><primary>T1 encoding</primary></indexterm>
+<indexterm role="cp"><primary>Cork encoding</primary></indexterm>
+<para>&tex; text extended. Sometimes called the Cork encoding for the
+users group meeting where it was developed (1990). 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.
+</term><listitem><indexterm role="cp"><primary>TS1 (text companion) encoding</primary></indexterm>
+<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>.
@@ -1350,13 +1238,13 @@ 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>The &latex; team reserves 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
@@ -1642,9 +1530,9 @@ mathematics.
<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>\DeclareTextSymbol{\guillemetleft}{T1}{19}
</screen>
-<para>The command <literal>\DeclareTextCommand{\guillemotleft}{T1}{\char
+<para>The command <literal>\DeclareTextCommand{\guillemetleft}{T1}{\char
19}</literal> has the same effect but is slower (see <link linkend="_005cDeclareTextCommand-_0026-_005cProvideTextCommand">\DeclareTextCommand &amp;
\ProvideTextCommand</link>).
</para>
@@ -3633,7 +3521,7 @@ switches the chapters back to being not numbered.
</sect1>
<sect1 label="6.8" id="_005c_0040startsection">
-<title><literal>\@startsection</literal>, typesetting sectional unit headings</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>
@@ -3645,15 +3533,15 @@ switches the chapters back to being not numbered.
<para>Used to help redefine the behavior of commands that start sectioning
divisions such as <literal>\section</literal> or <literal>\subsection</literal>.
</para>
-<para>Note that the <literal>titlesec</literal> package makes manipulation of sectioning
+<para>The <literal>titlesec</literal> package makes manipulation of sectioning
easier. Further, while most requirements for sectioning commands can be
satisfied with <literal>\@startsection</literal>, some cannot. For instance, in
the standard &latex; <literal>book</literal> and <literal>report</literal> classes the commands
-<literal>\chapter</literal> and <literal>\report</literal> are not constructed in this way. To
+<literal>\chapter</literal> and <literal>\report</literal> are not constructed using this. To
make such a command you may want to use the <literal>\secdef</literal> command.
<!-- xx define, and make a cross reference to, secdef. -->
</para>
-<para>Technically, <literal>\@startsection</literal> has the form
+<para>The <literal>\@startsection</literal> macro is used like this:
</para>
<screen>\@startsection{<replaceable>name</replaceable>}
{<replaceable>level</replaceable>}
@@ -3672,7 +3560,7 @@ make such a command you may want to use the <literal>\secdef</literal> command.
{<replaceable>style</replaceable>}}
</screen>
<para>redefines <literal>\section</literal> while keeping its standard calling form
-<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (in which, for reminder,
+<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (in which, as a 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
@@ -3720,8 +3608,8 @@ the title into the left margin.
is inserted before this sectioning unit&#8217;s title. This space will be
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>
+header is not indented; if it is non-negative then the first paragraph
+is indented. (Example: the negative of <literal>1pt plus 2pt minus 3pt</literal>
is <literal>-1pt plus -2pt minus -3pt</literal>.)
</para>
<para>For example, if <replaceable>beforeskip</replaceable> is <literal>-3.5ex plus -1ex minus -0.2ex</literal>
@@ -4110,6 +3998,7 @@ uses <literal>hyperref</literal> then they all must use it.
<indexterm role="cp"><primary>environments</primary></indexterm>
<indexterm role="fn"><primary>\begin</primary></indexterm>
<indexterm role="fn"><primary>\end</primary></indexterm>
+<anchor id="Environment"/><!-- old name -->
<para>&latex; provides many environments for delimiting certain behavior.
An environment begins with <literal>\begin</literal> and ends with <literal>\end</literal>,
@@ -4492,19 +4381,19 @@ displayed equation facilities. For example, there are a number of
ways in that package for having math text broken across lines.
</para>
<indexterm role="fn"><primary>\[...\] display math</primary></indexterm>
-<para>The construct <literal>\[<replaceable>math</replaceable>\]</literal> is a synonym for the environment
+<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.
</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
+<para>The construct <literal>$$<replaceable>math</replaceable>$$</literal> from Plain&#160;&tex; is
+sometimes used as a synonym for &latex;&#8217;s <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.)
+consistency checks.
</para>
<para>The output from this example is centered and alone on its line.
</para>
@@ -4750,7 +4639,7 @@ except that &latex; puts an equation number flush to the right margin.
The equation number is generated using the <literal>equation</literal> counter.
</para>
<para>You should have no blank lines between <literal>\begin{equation}</literal> and
-<literal>\begin{equation}</literal>, or &latex; will tell you that there is a
+<literal>\end{equation}</literal>, or &latex; will tell you that there is a
missing dollar sign.
</para>
<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
@@ -5047,13 +4936,12 @@ see&#160;<link linkend="flushright">flushright</link>.
</para>
<para>Unlike the <literal>flushright</literal> environment, the <literal>\raggedleft</literal>
command does not start a new paragraph; it only changes how &latex;
-formats paragraph units. To affect a paragraph unit&#8217;s format, the
+formats paragraph units. To affect a paragraph unit&#8217;s formatting, 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>,
-where one just have mutatis mutandis to replace <literal>\raggedright</literal> by
-<literal>\raggedleft</literal>.
+<para>See <link linkend="_005craggedright">\raggedright</link>, for an example related to this environment;
+just replace <literal>\raggedright</literal> there by <literal>\raggedleft</literal>.
</para>
</sect2>
@@ -5168,8 +5056,9 @@ see <link linkend="_005cparindent-_0026-_005cparskip">\parindent &amp; \parskip<
<screen>\newenvironment{itemize*}%
{\begin{itemize}%
\setlength{\itemsep}{0pt}%
- \setlength{\parsep}{0pt}}%
- \setlength{\parskip}{0pt}}%
+ \setlength{\parsep}{0pt}%
+ \setlength{\parskip}{0pt}%
+ }%
{\end{itemize}}
</screen>
@@ -5272,7 +5161,7 @@ different than the values shown here.) See also the figure that follows
the list. Each is a length (see <link linkend="Lengths">Lengths</link>). The vertical spaces are
normally rubber lengths, with <literal>plus</literal> and <literal>minus</literal> components,
to give &tex; flexibility in setting the page. Change each with a
-command such as <literal>\setlength{itemsep}{2pt plus1pt minus1pt}</literal>.
+command such as <literal>\setlength{\itemsep}{2pt plus1pt minus1pt}</literal>.
For some effects these lengths should be zero or negative.
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal>
@@ -6659,14 +6548,16 @@ function \= fact(n : integer) : integer;\\
</screen>
<indexterm role="cp"><primary>package, <literal>algorithm2e</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>algorithm2e</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm>
+
<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm>
+
<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm>
-<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm>
-
<para>This example is just for illustration of the environment. To actually
typeset computer code in typewriter like this, a verbatim environment
(see <link linkend="verbatim">verbatim</link>) would normally be best. For pretty-printed code,
@@ -7569,11 +7460,11 @@ help with this.
<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm>
-<para>One common use of verbatim input is to typeset computer code. There are
-packages that are an improvement the <literal>verbatim</literal> environment. For
-instance, one improvement is to allow the verbatim inclusion of external
-files, or parts of those files. Such packages include <literal>listings</literal>,
-and <literal>minted</literal>.
+<para>One common use of verbatim input is to typeset computer code. Some
+packages offer many features not provided by the <literal>verbatim</literal>
+environment; two of the most popular are <literal>listings</literal> and
+<literal>minted</literal>. For example, they are capable of pretty-printing,
+line numbering, and selecting parts of files for a continuing listing.
</para>
<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm>
@@ -7584,7 +7475,10 @@ 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 (see <link linkend="CTAN">CTAN</link>).
+<para>For a list of all the relevant packages, see CTAN (see <link linkend="CTAN">CTAN</link>),
+particularly the topics <literal>listing</literal>
+(<ulink url="https://ctan.org/topic/listing">https://ctan.org/topic/listing</ulink>) and <literal>verbatim</literal>
+(<ulink url="https://ctan.org/topic/verbatim">https://ctan.org/topic/verbatim</ulink>).
</para>
@@ -7636,15 +7530,6 @@ space character.
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>
-<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm>
-
-<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm>
-
-<para>For computer code there are many packages with advantages over
-<literal>\verb</literal>. One is <literal>listings</literal>, another is <literal>minted</literal>.
-</para>
<indexterm role="cp"><primary>package, <literal>cprotect</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>cprotect</literal> package</primary></indexterm>
@@ -7920,7 +7805,23 @@ requires care.
</para>
</sect1>
-<sect1 label="9.5" id="_005cdiscretionary">
+<sect1 label="9.5" id="_005cslash">
+<title><literal>\slash</literal>: breakable &#8216;<literal>/</literal>&#8217;</title>
+
+<indexterm role="fn"><primary>\slash</primary></indexterm>
+<indexterm role="cp"><primary>slash character, breakable</primary></indexterm>
+
+<para>The <literal>\slash</literal> command produces a &#8216;<literal>/</literal>&#8217; character and then a
+penalty of the same value as an explicit &#8216;<literal>-</literal>&#8217; character
+(<literal>\exhyphenpenalty</literal>). This allows &tex; to break a line at the
+&#8216;<literal>/</literal>&#8217;, similar to a hyphen. Hyphenation is allowed in the word part
+preceding the &#8216;<literal>/</literal>&#8217;, but not after. For example:
+</para>
+<screen>The input\slash output of the program is complicated.
+</screen>
+
+</sect1>
+<sect1 label="9.6" id="_005cdiscretionary">
<title><literal>\discretionary</literal> (generalized hyphenation point)</title>
<indexterm role="cp"><primary>hyphenation, discretionary</primary></indexterm>
<indexterm role="cp"><primary>discretionary hyphenation</primary></indexterm>
@@ -7950,7 +7851,7 @@ automatically by &tex;&#8217;s hyphenation algorithm.
</sect1>
-<sect1 label="9.6" id="_005cfussy-_0026-_005csloppy">
+<sect1 label="9.7" id="_005cfussy-_0026-_005csloppy">
<title><literal>\fussy</literal> &amp; <literal>\sloppy</literal></title>
<anchor id="_005cfussy"/><anchor id="_005csloppy"/><indexterm role="fn"><primary>\fussy</primary></indexterm>
@@ -7971,7 +7872,7 @@ that paragraph-ending material in the scope of the command.
</para>
-<sect2 label="9.6.1" id="sloppypar">
+<sect2 label="9.7.1" id="sloppypar">
<title><literal>sloppypar</literal></title>
<indexterm role="fn"><primary>environment, <literal>sloppypar</literal></primary></indexterm>
@@ -8007,7 +7908,7 @@ that paragraph-ending material in the scope of the command.
</sect2>
</sect1>
-<sect1 label="9.7" id="_005chyphenation">
+<sect1 label="9.8" id="_005chyphenation">
<title><literal>\hyphenation</literal></title>
<indexterm role="fn"><primary>\hyphenation</primary></indexterm>
@@ -8019,14 +7920,14 @@ that paragraph-ending material in the scope of the command.
</screen>
<para>Declares allowed hyphenation points within the words in the list. The
words in that list are separated by spaces. Show permitted points for
-hyphenation with a dash character, <literal>-</literal>.
+hyphenation with an ASCII dash character, <literal>-</literal>.
</para>
<para>Here is an example:
</para>
<screen>\hyphenation{hat-er il-lit-e-ra-ti tru-th-i-ness}
</screen>
<para>Use lowercase letters. &tex; will only hyphenate if the word matches
-exactly, no inflections are tried. Multiple <literal>\hyphenation</literal>
+exactly; no inflections are tried. Multiple <literal>\hyphenation</literal>
commands accumulate.
</para>
<!-- xx Re-align on LaTeX-fr which also mentions fontenc, and that -->
@@ -8035,7 +7936,7 @@ commands accumulate.
</sect1>
-<sect1 label="9.8" id="_005clinebreak-_0026-_005cnolinebreak">
+<sect1 label="9.9" id="_005clinebreak-_0026-_005cnolinebreak">
<title><literal>\linebreak</literal> &amp; <literal>\nolinebreak</literal></title>
<anchor id="_005clinebreak"/><anchor id="_005cnolinebreak"/><indexterm role="fn"><primary>\linebreak</primary></indexterm>
@@ -8287,11 +8188,10 @@ does not have these effects.
</para>
<indexterm role="fn"><primary>\samepage</primary></indexterm>
<indexterm role="fn"><primary>samepage environment</primary></indexterm>
-<para>(There is an obsolete declaration <literal>\samepage</literal>, which tries to only
-allow a break between two paragraphs. There is a related environment
-<literal>samepage</literal>, also obsolete. Neither of these work reliably. For
-more on keeping material on the same page, see the FAQ entry
-<ulink url="https://texfaq.org/FAQ-nopagebrk">https://texfaq.org/FAQ-nopagebrk</ulink>.)
+<para>A declaration <literal>\samepage</literal> and corresponding <literal>samepage</literal>
+environment try to only allow breaks between paragraphs. They are not
+perfectly reliable. For more on keeping material on the same page,
+see the FAQ entry <ulink url="https://texfaq.org/FAQ-nopagebrk">https://texfaq.org/FAQ-nopagebrk</ulink>.)
</para>
</sect1>
@@ -8330,7 +8230,8 @@ include a bibliographic style with that behavior (see <link linkend="Using-BibTe
<screen>\footnote{<replaceable>text</replaceable>}
\footnote[<replaceable>number</replaceable>]{<replaceable>text</replaceable>}
</screen>
-<para>Place a footnote <replaceable>text</replaceable> at the bottom of the current page.
+<para>Place a footnote <replaceable>text</replaceable> at the bottom of the current page, with a
+footnote marker at the current position in the text.
</para>
<screen>There are over a thousand footnotes in Gibbon's
\textit{Decline and Fall of the Roman Empire}.\footnote{%
@@ -8362,12 +8263,16 @@ you make the change local then you may want to reset the counter with
<variablelist><varlistentry><term><indexterm role="fn"><primary>\footnoterule</primary></indexterm><literal>\footnoterule</literal>
</term><listitem><anchor id="footnote-footnoterule"/><para>Produces the rule separating the main text on a page from the page&#8217;s
footnotes. Default dimensions in the standard document classes (except
-<literal>slides</literal>, where it does not appear) is: vertical thickness of
+<literal>slides</literal>, where it does not appear) are: vertical thickness of
<literal>0.4pt</literal>, and horizontal size of <literal>0.4\columnwidth</literal> long.
Change the rule with something like this.
</para>
<!-- Credit egreg: https://tex.stackexchange.com/a/21917 -->
-<screen>\renewcommand{\footnoterule}{% Kerns avoid vertical space
+<screen>% \footnoterule is expanded in vertical mode, thus \kern
+% commands ensure that no vertical space is created,
+% and the rule is separated vertically with 2pt
+% above the note text.
+\renewcommand*{\footnoterule}{%
\kern -3pt % This -3 is negative
\hrule width \textwidth height 1pt % of the sum of this 1
\kern 2pt} % and this 2
@@ -8428,8 +8333,8 @@ and the third theorem.\footnotemark[\value{footnote}]
<para>If there are intervening footnotes then you must remember the value of
the number of the common mark. This example gives the same
institutional affiliation to both the first and third authors
-(<literal>\thanks</literal> is a version of <literal>\footnote</literal>), by-hand giving the
-number of the footnote.
+(<literal>\thanks</literal> is a version of <literal>\footnote</literal>), by explicitly
+specifying the number of the footnote (&#8216;<literal>1</literal>&#8217;).
</para>
<screen>\title{A Treatise on the Binomial Theorem}
\author{J Moriarty\thanks{University of Leeds}
@@ -8438,17 +8343,6 @@ number of the footnote.
\begin{document}
\maketitle
</screen>
-<para>This uses a counter to remember the footnote number. The third sentence
-is followed by the same footnote marker as the first.
-</para>
-<screen>\newcounter{footnoteValueSaver}
-All babies are illogical.\footnote{%
- Lewis Carroll.}\setcounter{footnoteValueSaver}{\value{footnote}}
-Nobody is despised who can manage a crocodile.\footnote{%
- Captain Hook.}
-Illogical persons are despised.\footnotemark[\value{footnoteValueSaver}]
-Therefore, anyone who can manage a crocodile is not a baby.
-</screen>
<indexterm role="cp"><primary>package, <literal>cleveref</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>cleveref</literal> package</primary></indexterm>
@@ -8470,6 +8364,17 @@ But the key lemma is from Tinker.\cref{fn:TE}
<para>It will work with the package <literal>hyperref</literal>.
</para>
+<para>This uses a counter to remember the footnote number. The third sentence
+is followed by the same footnote marker as the first.
+</para>
+<screen>\newcounter{footnoteValueSaver}
+All babies are illogical.\footnote{%
+ Lewis Carroll.}\setcounter{footnoteValueSaver}{\value{footnote}}
+Nobody is despised who can manage a crocodile.\footnote{%
+ Captain Hook.}
+Illogical persons are despised.\footnotemark[\value{footnoteValueSaver}]
+Therefore, anyone who can manage a crocodile is not a baby.
+</screen>
</sect1>
<sect1 label="11.3" id="_005cfootnotetext">
@@ -8507,7 +8412,9 @@ examples.
section starts, as usual, but also at the bottom of the table of
contents, where it is not likely to be desired. The simplest way
to have it not appear on the table of contents is to use the optional
-argument to <literal>\section</literal>
+argument to <literal>\section</literal>.
+<!-- xx Same issue with table/figure captions and -->
+<!-- \listoftable/\listoffigures, and same sort of fix can be used. -->
</para>
<screen>\section[Please]{Please\footnote{%
Don't footnote in chapter and section headers!}}
@@ -8566,7 +8473,7 @@ part of the regular footnote sequence, use the <literal>\footnotemark</literal>
Little is known other than her death.}%
\stepcounter{mpFootnoteValueSaver}%
\footnotetext[\value{mpFootnoteValueSaver}]{%
- Relationship is unresolved in XXI.}
+ Relationship is unresolved.}
\end{center}
</screen>
<indexterm role="cp"><primary>package, <literal>tablefootnote</literal></primary></indexterm>
@@ -8647,7 +8554,7 @@ second.\footnotefrom{%
\newcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>}
\newcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>}
</screen>
-<para>or all the same possibilities with <literal>\renewcommand</literal> instead of
+<para>or the same six possibilities with <literal>\renewcommand</literal> instead of
<literal>\newcommand</literal>:
</para>
<screen>\renewcommand{\<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>}
@@ -8657,17 +8564,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 <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>
-<indexterm role="fn"><primary>\long</primary></indexterm>
+<indexterm role="fn"><primary>\long, not defining a command as</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.
+multiple paragraphs of text (i.e., a <literal>\par</literal> token; 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 (examples follow):
</para>
@@ -8823,8 +8729,8 @@ whitespace in the output (see <link linkend="_005cnewcommand-_0026-_005crenewcom
<para>Just as the <literal>\relax</literal> command does nothing, the following input
will simply print &#8216;<literal>Hello!</literal>&#8217; :
</para>
-<screen>Hel\relax <!-- /@w --> <!-- /@w --> <!-- /@w -->
- <!-- /@w --> <!-- /@w --> <!-- /@w -->lo!
+<screen>Hel\relax&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->
+&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->&amp;#160;<!-- /@w -->lo!
</screen>
<para>This is because blanks after <literal>\relax</literal>, including the newline, are
ignored, and blanks at the beginning of a line are also ignored
@@ -8991,7 +8897,7 @@ 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
+<literal>\agentsecret&amp;#160;*<!-- /@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>
@@ -9454,20 +9360,16 @@ relative to the font&#8217;s design size, which is a value defined in the
<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. A
fragile command can break when it is used in the argument to certain
-other commands. Commands that contain data that &latex; writes to an
-auxiliary file and re-reads later are fragile. This includes material
-that goes into a table of contents, list of figures, list of tables,
-etc. Fragile commands also include line breaks, any command that has an
-optional argument, and many more. To prevent such commands from
-breaking, one solution is to preceded them with the command
-<literal>\protect</literal>.
+other commands, typically those that write material to the table of
+contents, the cross-reference file, etc. To prevent fragile
+commands from causing errors, one solution is to precede them with the
+command <literal>\protect</literal>.
</para>
<para>For example, when &latex; runs the <literal>\section{<replaceable>section
name</replaceable>}</literal> command it writes the <replaceable>section name</replaceable> text to the
<filename>.aux</filename> auxiliary file, moving it there for use elsewhere in the
-document such as in the table of contents. Any argument that is
-internally expanded by &latex; without typesetting it directly is
-referred to as a
+document such as in the table of contents. Such an argument that is
+used in multiple places is referred to as a
<indexterm role="cp"><primary>moving arguments</primary></indexterm>
<firstterm>moving argument</firstterm>. A command is fragile if it can
expand during this process into invalid &tex; code. Some examples of
@@ -9477,34 +9379,52 @@ command (see <link linkend="figure">figure</link>), in the <literal>\thanks{...}
<literal>array</literal> environments (see <link linkend="tabular">tabular</link>).
</para>
<para>If you get strange errors from commands used in moving arguments, try
-preceding it with <literal>\protect</literal>. Every fragile commands must be
+preceding it with <literal>\protect</literal>. Each fragile command must be
protected with their own <literal>\protect</literal>.
</para>
<para>Although usually a <literal>\protect</literal> command doesn&#8217;t hurt, length
-commands are robust and should not be preceded by a <literal>\protect</literal>
-command. Nor can a <literal>\protect</literal> command be used in the argument to
-<literal>\addtocounter</literal> or <literal>\setcounter</literal> command.
-</para>
-<para>In this example the <literal>\caption</literal> command gives a mysterious error
-about an extra curly brace. Fix the problem by preceding each
-<literal>\raisebox</literal> command with <literal>\protect</literal>.
+commands such as <literal>\parindent</literal> should not be preceded by a
+<literal>\protect</literal> command (see <link linkend="Lengths">Lengths</link>. Nor can a <literal>\protect</literal>
+command be used in the argument to <literal>\addtocounter</literal> or
+<literal>\setcounter</literal> command (see <link linkend="_005csetcounter">\setcounter</link> and
+<link linkend="_005caddtocounter">\addtocounter</link>. These commands are already robust.
+</para>
+<para>As of the October 2019 release of &latex;
+(<ulink url="https://www.latex-project.org/news/latex2e-news/ltnews30.pdf">https://www.latex-project.org/news/latex2e-news/ltnews30.pdf</ulink>),
+most commands that had been previously fragile were fixed to be
+robust. For example, any command taking an optional argument, such as
+<literal>\root</literal> or <literal>\raisebox</literal>, was fragile, but is now
+robust. Similarly, <literal>\(...\)</literal> math was fragile and is now robust
+(<literal>$...$</literal> has always been robust).
+</para>
+<indexterm role="fn"><primary>\verb, as fragile command</primary></indexterm>
+<para>Perhaps the most commonly used remaining fragile command is
+<literal>\verb</literal>; for example,
</para>
<screen>\begin{figure}
...
- \caption{Company headquarters of A\raisebox{1pt}{B}\raisebox{-1pt}{C}}
+ \caption{This \verb|\command| causes an error.}
\end{figure}
</screen>
-<para>In the next example the <literal>\tableofcontents</literal> command gives an error
-because the <literal>\(..\)</literal> in the section title expands to illegal &tex;
-in the <filename>.toc</filename> file. You can solve this by changing <literal>\(..\)</literal>
-to <literal>\protect\(..\protect\)</literal>.
+<para>Adding <literal>\protect</literal> does not help here. It&#8217;s usually feasible to
+rewrite the caption (or section heading or whatever) to use
+<literal>\texttt</literal>, often the simplest solution.
</para>
-<screen>\begin{document}
-\tableofcontents
-...
-\section{Einstein's \( e=mc^2 \)}
-...
+<indexterm role="cp"><primary>package, <literal>cprotect</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>cprotect</literal> package</primary></indexterm>
+
+<indexterm role="fn"><primary>\cprotect</primary></indexterm>
+<para>Alternatively, to use <literal>\verb</literal>, you can apply the
+<literal>\cprotect</literal> command from <literal>cprotect</literal> package
+(<ulink url="https://ctan.org/pkg/cprotect">https://ctan.org/pkg/cprotect</ulink>) to the <literal>\caption</literal>:
+</para>
+<screen>\cprotect\caption{This \verb|\command| is ok with \verb|\cprotect|.}
</screen>
+<indexterm role="fn"><primary>\cprotEnv</primary></indexterm>
+<para><literal>\cprotect</literal> also allows use of <literal>\begin...\end</literal> environments
+in moving arguments, where they are normally not allowed, via a
+similar prefix command <literal>\cprotEnv</literal>.
+</para>
</sect1>
<sect1 label="12.12" id="_005cignorespaces-_0026-_005cignorespacesafterend">
@@ -9591,7 +9511,7 @@ inconvenient. The solution is to change to
</sect1>
<sect1 label="12.13" id="xspace-package">
-<title>xspace package</title>
+<title><literal>xspace</literal> package</title>
<indexterm role="fn"><primary>\xspace</primary></indexterm>
<indexterm role="cp"><primary>package, <literal>xspace</literal></primary></indexterm>
@@ -9600,7 +9520,7 @@ inconvenient. The solution is to change to
<indexterm role="cp"><primary>spaces, ignore around commands</primary></indexterm>
<indexterm role="cp"><primary>commands, ignore spaces</primary></indexterm>
-<para>Synopsis:
+<para>This is an add-on package, not part of core &latex;. Synopsis:
</para>
<screen>\usepackage{xspace}
...
@@ -9610,15 +9530,15 @@ inconvenient. The solution is to change to
adds a space unless the command is followed by certain punctuation
characters.
</para>
-<para>After a command control sequence that is a control word (see <link linkend="Control-sequences">Control
+<para>After a control sequence that is a control word (see <link linkend="Control-sequences">Control
sequences</link>, as opposed to control symbols such as <literal>\$</literal>), &tex;
-gobbles blank characters. Thus, in the first sentence below, the output
-has &#8216;<literal>Vermont</literal>&#8217; placed snugly against the period, without any
-intervening space.
+gobbles blank characters. Thus, in the first sentence below, the
+output has &#8216;<literal>Vermont</literal>&#8217; placed snugly against the period, without
+any intervening space, despite the space in the input.
</para>
<screen>\newcommand{\VT}{Vermont}
Our college is in \VT .
-The \VT{} summers are nice.
+\VT{} summers are nice.
</screen>
<para>But because of the gobbling, the second sentence needs the empty curly
braces or else there would be no space separating &#8216;<literal>Vermont</literal>&#8217; from
@@ -9637,10 +9557,10 @@ Our college is in \VT .
</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> which adds
-<literal>\myfni</literal> and&#160;<literal>\myfnii</literal> to the list, and remove from that
-list as with <literal>\xspaceremoveexception{!}</literal>.
+and the commands <literal>\footnote</literal> or <literal>\footnotemark</literal>. You can
+add to that list as with <literal>\xspaceaddexceptions{\myfni \myfnii}</literal>
+which adds <literal>\myfni</literal> and&#160;<literal>\myfnii</literal> to the list; and you
+can 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
@@ -9648,9 +9568,655 @@ a definition means that the command will usually get the spacing right.
But it isn&#8217;t easy to predict when to enter empty 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 inserting the empty braces.
+error-prone than instead of always inserting the empty braces.
+</para>
+
+</sect1>
+<sect1 label="12.14" id="Class-and-package-commands">
+<title>Class and package commands</title>
+
+<indexterm role="cp"><primary>class and package commands</primary></indexterm>
+<indexterm role="cp"><primary>package and class commands</primary></indexterm>
+<indexterm role="cp"><primary>commands, class and package</primary></indexterm>
+
+<para>These are commands designed to help writers of classes or packages.
+</para>
+
+<sect2 label="12.14.1" id="_005cAtBeginDvi-_0026-_005cAtEndDvi">
+<title><literal>\AtBeginDvi</literal> &amp; <literal>\AtEndDvi</literal></title>
+
+<anchor id="_005cAtBeginDvi"/><anchor id="_005cAtEndDvi"/><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm>
+<indexterm role="fn"><primary>\AtEndDvi</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\AtBeginDvi{<replaceable>code</replaceable>}
+\AtEndDvi{<replaceable>code</replaceable>}
+</screen>
+<para><literal>\AtBeginDvi</literal> saves, in a box register, <replaceable>code</replaceable> to be executed
+at the beginning of the shipout of the first page of the document.
+Despite the name, it applies to DVI, PDF, and XDV output. It fills
+the <literal>shipout/firstpage</literal> hook; new code should use that hook
+directly.
+</para>
+<indexterm role="cp"><primary>package, <literal>atenddvi</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>atenddvi</literal> package</primary></indexterm>
+
+<para>Similarly, <literal>\AtEndDvi</literal> (previously available only with the
+<literal>atenddvi</literal> package) is code executed when finalizing the main
+output document.
+</para>
+
+</sect2>
+<sect2 label="12.14.2" id="_005cAtEndOfClass-_0026-_005cAtEndOfPackage">
+<title><literal>\AtEndOfClass</literal> &amp; <literal>\AtEndOfPackage</literal></title>
+
+<anchor id="_005cAtEndOfClass"/><anchor id="_005cAtEndOfPackage"/><indexterm role="fn"><primary>\AtEndOfClass</primary></indexterm>
+<indexterm role="fn"><primary>\AtEndOfPackage</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\AtEndOfClass{<replaceable>code</replaceable>}
+\AtEndOfPackage{<replaceable>code</replaceable>}
+</screen>
+<para>Hooks to insert <replaceable>code</replaceable> to be executed when &latex; finishes
+processing the current class resp. package.
+</para>
+<para>These hooks can be used multiple times; each <literal>code</literal> segment will
+be executed in the order called. Many packages and classes use these
+commands.
+</para>
+<para>See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>.
+</para>
+
+</sect2>
+<sect2 label="12.14.3" id="_005cCheckCommand">
+<title><literal>\CheckCommand</literal></title>
+
+<indexterm role="fn"><primary>\CheckCommand</primary></indexterm>
+<indexterm role="cp"><primary>new command, checking definition of</primary></indexterm>
+<indexterm role="cp"><primary>long command</primary></indexterm>
+<indexterm role="cp"><primary><literal>\long</literal> command, checking for</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\CheckCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}
+\CheckCommand* (same parameters)
+</screen>
+<para>Like <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>) but does
+not define <replaceable>cmd</replaceable>; instead it checks that the current definition of
+<replaceable>cmd</replaceable> is exactly as given by <replaceable>definition</replaceable> and is or is not
+<firstterm><literal>\long</literal></firstterm> as expected. A long command is a command that
+accepts <literal>\par</literal> within an argument.
+</para>
+<para>With the unstarred version of <literal>\CheckCommand</literal>, <replaceable>cmd</replaceable> is
+expected to be <literal>\long</literal>; with the starred version, <replaceable>cmd</replaceable> must
+not be <literal>\long</literal>
+</para>
+<para><literal>\CheckCommand</literal> raises an error when the check fails. This
+allows you to check before you start redefining <literal>cmd</literal> yourself
+that no other package has already redefined this command.
+</para>
+
+</sect2>
+<sect2 label="12.14.4" id="_005cClassError-and-_005cPackageError-and-others">
+<title><literal>\ClassError</literal> and <literal>\PackageError</literal> and others</title>
+
+<anchor id="_005cClassError"/><anchor id="_005cClassWarning"/><anchor id="_005cClassWarningNoLine"/><anchor id="_005cClassInfo"/><anchor id="_005cClassInfoNoLine"/><anchor id="_005cPackageError"/><anchor id="_005cPackageWarning"/><anchor id="_005cPackageWarningNoLine"/><anchor id="_005cPackageInfo"/><anchor id="_005cPackageInfoNoLine"/>
+<para>Produce error, warning, and informational messages for classes:
+</para>
+<variablelist><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error-text</replaceable>}{<replaceable>help-text</replaceable>}</literal>
+</term><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning-text</replaceable>}</literal>
+</term><term><literal>\ClassWarningNoLine{<replaceable>class name</replaceable>}{<replaceable>warning-text</replaceable>}</literal>
+</term><term><literal>\ClassInfo{<replaceable>class name</replaceable>}{<replaceable>info-text</replaceable>}</literal>
+</term><term><literal>\ClassInfoNoLine{<replaceable>class name</replaceable>}{<replaceable>info-text</replaceable>}</literal>
+</term><listitem><indexterm role="fn"><primary>\ClassError</primary></indexterm>
+<indexterm role="fn"><primary>\ClassWarning</primary></indexterm>
+<indexterm role="fn"><primary>\ClassWarningNoLine</primary></indexterm>
+<indexterm role="fn"><primary>\ClassInfo</primary></indexterm>
+<indexterm role="fn"><primary>\ClassInfoNoLine</primary></indexterm>
+</listitem></varlistentry></variablelist>
+<para>and the same for packages:
+</para><variablelist><varlistentry><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error-text</replaceable>}{<replaceable>help-text</replaceable>}</literal>
+</term><term><literal>\PackageWarning{<replaceable>package name</replaceable>}{<replaceable>warning-text</replaceable>}</literal>
+</term><term><literal>\PackageWarningNoLine{<replaceable>package name</replaceable>}{<replaceable>warning-text</replaceable>}</literal>
+</term><term><literal>\PackageInfo{<replaceable>package name</replaceable>}{<replaceable>info-text</replaceable>}</literal>
+</term><term><literal>\PackageInfoNoLine{<replaceable>package name</replaceable>}{<replaceable>info-text</replaceable>}</literal>
+</term><listitem><indexterm role="fn"><primary>\PackageError</primary></indexterm>
+<indexterm role="fn"><primary>\PackageWarning</primary></indexterm>
+<indexterm role="fn"><primary>\PackageWarningNoLine</primary></indexterm>
+<indexterm role="fn"><primary>\PackageInfo</primary></indexterm>
+<indexterm role="fn"><primary>\PackageInfoNoLine</primary></indexterm>
+</listitem></varlistentry></variablelist>
+<para>For <literal>\ClassError</literal> and <literal>\PackageError</literal> the message is
+<replaceable>error-text</replaceable>, followed by &tex;&#8217;s &#8216;<literal>?</literal>&#8217; error prompt. If the
+user then asks for help by typing <literal>h</literal>, they see the <replaceable>help
+text</replaceable>.
+</para>
+<para>The four <literal>Warning</literal> commands are similar except that they write
+<replaceable>warning-text</replaceable> on the screen with no error prompt. The four
+<literal>Info</literal> commands write <replaceable>info-text</replaceable> only in the transcript
+file. The <literal>NoLine</literal> versions omit the number of the line
+generating the message, while the other versions do show that number.
+</para>
+<indexterm role="cp"><primary><literal>\protect</literal>, and message text</primary></indexterm>
+<indexterm role="cp"><primary><literal>\space</literal>, and message text</primary></indexterm>
+<indexterm role="cp"><primary><literal>\MessageBreak</literal>, and message text</primary></indexterm>
+<para>To format the messages, including the <replaceable>help-text</replaceable>: use
+<literal>\protect</literal> to stop a command from expanding, get a line break
+with <literal>\MessageBreak</literal>, and get a space with <literal>\space</literal> when a
+space character is ignore, most commonly after a command.
+</para>
+<para>&latex; appends a period to the messages.
+</para>
+
+</sect2>
+<sect2 label="12.14.5" id="_005cCurrentOption">
+<title><literal>\CurrentOption</literal></title>
+
+<indexterm role="fn"><primary>\CurrentOption</primary></indexterm>
+<indexterm role="cp"><primary>option, currently being processed</primary></indexterm>
+
+<para>Expands to the name of the option currently being processed. This can
+only be used within the <replaceable>code</replaceable> argument of either
+<literal>\DeclareOption</literal> or <literal>\DeclareOption*</literal>.
+</para>
+
+</sect2>
+<sect2 label="12.14.6" id="_005cDeclareOption">
+<title><literal>\DeclareOption</literal></title>
+
+<indexterm role="fn"><primary>\DeclareOption</primary></indexterm>
+<indexterm role="cp"><primary>class options</primary></indexterm>
+<indexterm role="cp"><primary>package options</primary></indexterm>
+<indexterm role="cp"><primary>options, class</primary></indexterm>
+<indexterm role="cp"><primary>options, package</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}
+\DeclareOption*{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}
+</screen>
+<para>Define an option a user can include in their <literal>\documentclass</literal>
+command. For example, a class <literal>smcmemo</literal> could have an option
+<literal>logo</literal> allowing users to put the institutional logo on the first
+page. The document would start with
+<literal>\documentclass[logo]{smcmemo}</literal>. To enable this, the class file
+must contain <literal>\DeclareOption{logo}{<replaceable>code</replaceable>}</literal> (and later,
+<literal>\ProcessOptions</literal>).
+</para>
+<indexterm role="cp"><primary>default option processing</primary></indexterm>
+<indexterm role="cp"><primary>option processing by default</primary></indexterm>
+<indexterm role="cp"><primary><literal>Unused global option</literal> warning, handling</primary></indexterm>
+<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> This can be changed by using
+<literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>, which executes <replaceable>code</replaceable> for
+any unknown option.
+</para>
+<para>For example, many classes extend an existing class, using code such as
+<literal>\LoadClass{article}</literal> (see <link linkend="_005cLoadClass">\LoadClass</link>). In this case, it
+makes sense to pass any otherwise-unknown options to the underlying
+class, like this:
+</para>
+<screen>\DeclareOption*{%
+ \PassOptionsToClass{\CurrentOption}{article}%
+}
+</screen>
+<para>As another example, our class <literal>smcmemo</literal> might allow users to keep
+lists of memo recipients in external files, so the user could invoke
+<literal>\documentclass[math]{smcmemo}</literal> and it will read the file
+<literal>math.memo</literal>. This code inputs the file if it exists, while if it
+doesn&#8217;t, the option is passed to the <literal>article</literal> class:
+</para>
+<screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}
+ {}{%
+ \PassOptionsToClass{\CurrentOption}{article}}}
+</screen>
+
+</sect2>
+<sect2 label="12.14.7" id="_005cDeclareRobustCommand">
+<title><literal>\DeclareRobustCommand</literal></title>
+
+<indexterm role="fn"><primary>\DeclareRobustCommand</primary></indexterm>
+<indexterm role="cp"><primary>new command, definition</primary></indexterm>
+<indexterm role="cp"><primary>robust command, defining</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareRobustCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}
+\DeclareRobustCommand* (same parameters
+</screen>
+<para><literal>\DeclareRobustCommand</literal> and its starred form are generally like
+<literal>\newcommand</literal> and <literal>\newcommand*</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
+\renewcommand</link>), with the addition that they define a so-called
+<firstterm>robust</firstterm> command, even if some code within the <replaceable>definition</replaceable> is
+fragile. (For a discussion of robust and fragile commands,
+see <link linkend="_005cprotect">\protect</link>.)
+</para>
+<para>Also unlike <literal>\newcommand</literal>, these do not give an error if macro
+<replaceable>cmd</replaceable> already exists; instead, a log message is put into the
+transcript file if a command is redefined. Thus,
+<literal>\DeclareRobustCommand</literal> can be used to define new robust commands
+or to redefine existing commands, making them robust.
+</para>
+<para>The starred form, <literal>\DeclareRobustCommand*</literal>, disallows the
+arguments from containing multiple paragraphs, just like the starred
+form of <literal>\newcommand</literal> and <literal>\renewcommand</literal>. The meaning of
+the arguments is the same.
+</para>
+<para>Commands defined this way are a bit less efficient than those defined
+using <literal>\newcommand</literal> so unless the command&#8217;s data is fragile and the
+command is used within a moving argument, use <literal>\newcommand</literal>.
+</para>
+<indexterm role="cp"><primary>package, <literal>etoolbox</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>etoolbox</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>e-&tex;, and robust commands</primary></indexterm>
+<indexterm role="fn"><primary>\newrobustcmd (<literal>etoolbox</literal> package)</primary></indexterm>
+<indexterm role="fn"><primary>\renewrobustcmd (<literal>etoolbox</literal> package)</primary></indexterm>
+<indexterm role="fn"><primary>\providerobustcmd (<literal>etoolbox</literal> package)</primary></indexterm>
+
+<para>Related to this, the <literal>etoolbox</literal> package offers three commands
+and their starred forms: <literal>\newrobustcmd</literal>(<literal>*</literal>)
+<literal>\renewrobustcmd</literal>(<literal>*</literal>), and
+<literal>\providerobustcmd</literal>(<literal>*</literal>). They are similar to
+<literal>\newcommand</literal>, <literal>\renewcommand</literal>, and <literal>\providecommand</literal>
+and their own starred forms, but define a robust <replaceable>cmd</replaceable>. They have
+two possible advantages compared to <literal>\DeclareRobustCommand</literal>:
+</para>
+<orderedlist numeration="arabic"><listitem><para>They use the low-level e-&tex; protection mechanism rather than the
+higher-level &latex; <literal>\protect</literal> mechanism, so they do not incur
+the slight loss of performance mentioned above, and
+</para>
+</listitem><listitem><para>They make the same distinction between <literal>\new&#8230;</literal>,
+<literal>\renew&#8230;</literal>, and <literal>\provide&#8230;</literal>, as the standard
+commands. That is, they do not just write a log message when you
+redefine <replaceable>cmd</replaceable> that already exists; you need to use either
+<literal>\renew&#8230;</literal> or <literal>\provide&#8230;</literal>, or you get an error.
+This may or may not be a benefit.
+</para></listitem></orderedlist>
+
+</sect2>
+<sect2 label="12.14.8" id="_005cExecuteOptions">
+<title><literal>\ExecuteOptions</literal></title>
+
+<indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\ExecuteOptions{<replaceable>option-list</replaceable>}
+</screen>
+<indexterm role="fn"><primary>\ds@<replaceable>option</replaceable></primary></indexterm>
+<para>For each option <replaceable>option</replaceable> in <replaceable>option-list</replaceable>, in order, this
+command executes the command <literal>\ds@<replaceable>option</replaceable></literal>. If this
+command is not defined then that option is silently ignored.
+</para>
+<para>This can be used to provide a default option list before
+<literal>\ProcessOptions</literal>. For example, if in a class file you want the
+default to be 11pt fonts then you could specify
+<literal>\ExecuteOptions{11pt}\ProcessOptions\relax</literal>.
+</para>
+
+</sect2>
+<sect2 label="12.14.9" id="_005cIfFileExists-_0026-_005cInputIfFileExists">
+<title><literal>\IfFileExists</literal> &amp; <literal>\InputIfFileExists</literal></title>
+
+<anchor id="_005cIfFileExists"/><anchor id="_005cInputIfFileExists"/><indexterm role="fn"><primary>\IfFileExists</primary></indexterm>
+<indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm>
+
+<para>Synopses:
</para>
+<screen>\IfFileExists{<replaceable>filename</replaceable>}{<replaceable>true-code</replaceable>}{<replaceable>false-code</replaceable>}
+\InputIfFileExists{<replaceable>filename</replaceable>}{<replaceable>true-code</replaceable>}{<replaceable>false-code</replaceable>}
+</screen>
+<para><literal>\IfFileExists</literal> executes <replaceable>true-code</replaceable> if &latex; finds the
+file <filename><replaceable>filename</replaceable></filename> or <replaceable>false-code</replaceable> otherwise. In the
+first case it executing <replaceable>true-code</replaceable> and then inputs the file.
+Thus the command
+</para>
+<screen>\IfFileExists{img.pdf}{%
+ \includegraphics{img.pdf}}
+ {\typeout{!! img.pdf not found}
+</screen>
+<para>will include the graphic <filename>img.pdf</filename> if it is found and otherwise
+give a warning.
+</para>
+<para>This command looks for the file in all search paths that &latex;
+uses, not only in the current directory. To look only in the current
+directory do something like
+<literal>\IfFileExists{./<replaceable>filename</replaceable>}{<replaceable>true-code</replaceable>}{<replaceable>false-code</replaceable>}</literal>.
+If you ask for a filename without a <literal>.tex</literal> extension then
+&latex; will first look for the file by appending the <literal>.tex</literal>;
+for more on how &latex; handles file extensions see <link linkend="_005cinput">\input</link>.
+</para>
+<para><literal>\InputIfFileExists</literal> is similar, but, as the name states,
+automatically <literal>\input</literal>s <replaceable>filename</replaceable> if it exists. The
+<replaceable>true-code</replaceable> is executed just before the <literal>\input</literal>; if the file
+doesn&#8217;t exist, the <replaceable>false-code</replaceable> is executed. An example:
+</para>
+<screen>\InputIfFileExists{mypkg.cfg}
+ {\PackageInfo{Loading mypkg.cfg for configuration information}}
+ {\PackageInfo{No mypkg.cfg found}}
+</screen>
+</sect2>
+<sect2 label="12.14.10" id="_005cLoadClass-_0026-_005cLoadClassWithOptions">
+<title><literal>\LoadClass</literal> &amp; <literal>\LoadClassWithOptions</literal></title>
+
+<anchor id="_005cLoadClass"/><anchor id="_005cLoadClassWithOptions"/><indexterm role="fn"><primary>\LoadClass</primary></indexterm>
+<indexterm role="fn"><primary>\LoadClassWithOptions</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\LoadClass[<replaceable>options-list</replaceable>]{<replaceable>class-name</replaceable>}[<replaceable>release-date</replaceable>]
+\LoadClassWithOptions{<replaceable>class-name</replaceable>}[<replaceable>release-date</replaceable>]
+</screen>
+<para>Load a class, as with
+<literal>\documentclass[<replaceable>options-list</replaceable>]{<replaceable>class-name</replaceable>}[<replaceable>release-date</replaceable>]</literal>.
+An example: <literal>\LoadClass[twoside]{article}</literal>.
+</para>
+<para>The <replaceable>options-list</replaceable>, if present, is a comma-separated list. The
+<replaceable>release-date</replaceable> is also optional. If present it must have the form
+<literal>YYYY/MM/DD</literal>.
+<!-- BTW, there are at-macros documented in macros2e.pdf to check the version -->
+<!-- and do some actions conditionnally on version later or not to some -->
+<!-- date. -->
+</para>
+<para>If you request <replaceable>release-date</replaceable> and the date of the package
+installed on your system is earlier, then you get a warning on the
+screen and in the log like this:
+</para>
+<screen>You have requested, on input line 4, version `2038/01/19' of
+document class article, but only version `2014/09/29 v1.4h
+Standard LaTeX document class' is available.
+</screen>
+<indexterm role="fn"><primary>\PassOptionsToClass, ignoring</primary></indexterm>
+<para>The command version <literal>\LoadClassWithOptions</literal> uses the list of
+options for the current class. This means it ignores any options passed
+to it via <literal>\PassOptionsToClass</literal>. This is a convenience command
+that lets you build classes on existing ones, such as the standard
+<literal>article</literal> class, without having to track which options were passed.
+</para>
+
+</sect2>
+<sect2 label="12.14.11" id="_005cNeedsTeXFormat">
+<title><literal>\NeedsTeXFormat</literal></title>
+
+<indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm>
+<indexterm role="cp"><primary>format, requiring</primary></indexterm>
+<indexterm role="cp"><primary>version of format, requiring</primary></indexterm>
+<indexterm role="cp"><primary>date of format, requiring</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format-date</replaceable>]
+</screen>
+<para>Specifies the format that this class must be run under. Often issued
+as the first line of a class file, and most often used as:
+<literal>\NeedsTeXFormat{LaTeX2e}</literal>. When a document using that class
+is processed, the format being run must exactly match the <replaceable>format</replaceable>
+name given, including case. If it does not match then execution stops
+with an error like &#8216;<literal>This file needs format `LaTeX2e' but this is
+`plain'.</literal>&#8217;.
+</para>
+<para>To require a version of the format that you know to have certain
+features, include the optional <replaceable>format-date</replaceable> on which those
+features were implemented. If present, it must be in the form
+<literal>YYYY/MM/DD</literal>. If the format version installed on your system is
+earlier than <replaceable>format date</replaceable> then you get a warning like this.
+</para>
+<screen>You have requested release `2038/01/20' of LaTeX, but only
+release `2016/02/01' is available.
+</screen>
+
+</sect2>
+<sect2 label="12.14.12" id="_005cOptionNotUsed">
+<title><literal>\OptionNotUsed</literal></title>
+
+<indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm>
+
+<indexterm role="cp"><primary>unused options, adding to list</primary></indexterm>
+<indexterm role="cp"><primary>options, list of unused</primary></indexterm>
+<para>Adds the current option to the list of unused options. Can only be used
+within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> or
+<literal>\DeclareOption*</literal>.
+</para>
+<!-- xx I cannot reproduce this behavior as it is documented in clsguide. -->
+<!-- In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues -->
+<!-- on the console a warning like @code{LaTeX Warning: Unused global -->
+<!-- option(s): [unusedoption].} with the list of not-used options when it -->
+<!-- reaches @code{\begin@{document@}}. -->
+
+
+</sect2>
+<sect2 label="12.14.13" id="_005cPassOptionsToClass-_0026-_005cPassOptionsToPackage">
+<title><literal>\PassOptionsToClass</literal> &amp; <literal>\PassOptionsToPackage</literal></title>
+
+<anchor id="_005cPassOptionsToClass"/><anchor id="_005cPassOptionsToPackage"/><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm>
+<indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\PassOptionsToClass{<replaceable>options</replaceable>}{<replaceable>clsname</replaceable>}
+\PassOptionsToPackage{<replaceable>option</replaceable>}{<replaceable>pkgname</replaceable>}
+</screen>
+<para>Adds the options in the comma-separated list <replaceable>options</replaceable> to the
+options used by any future <literal>\RequirePackage</literal> or
+<literal>\usepackage</literal> command for the class <replaceable>clsname</replaceable> or the package
+<replaceable>pkgname</replaceable>, respectively.
+</para>
+<indexterm role="cp"><primary>option clash</primary></indexterm>
+<indexterm role="cp"><primary>conflict between package options</primary></indexterm>
+<para>The reason for these commands is that although you may load a package
+any number of times with no options, if you can specify options only
+the first time you load the package. Loading a package with options
+more than once will get you an error like <literal>Option clash for
+package foo.</literal>. &latex; throws an error even if there is no conflict
+between the options.
+</para>
+<para>If your own code is bringing in a package twice then you can combine
+the calls; for example, replacing the two
+</para>
+<screen>\RequirePackage[landscape]{geometry}
+\RequirePackage[margins=1in]{geometry}
+</screen>
+<para>with the single command
+</para>
+<screen>\RequirePackage[landscape,margins=1in]{geometry}
+</screen>
+<para>However, suppose you are loading <filename>firstpkg</filename> and inside that
+package it loads <filename>secondpkg</filename>, and you need <literal>secondpkg</literal> to be
+loaded with option <literal>draft</literal>. Then before load the first package
+you must tell &latex; about the desired options for the second
+package, like this:
+</para>
+<screen>\PassOptionsToPackage{draft}{secondpkg}
+\RequirePackage{firstpkg}
+</screen>
+<para>If <literal>firstpkg.sty</literal> loads an option in conflict with what you want
+then you may have to alter its source, or yours.
+</para>
+<para>These commands are useful for general users as well as class and package
+writers. For instance, suppose a user wants to load the <literal>graphicx</literal>
+package with the option <literal>draft</literal> and also wants to use a class
+<literal>foo</literal> that loads the <literal>graphicx</literal> package, but without that
+option. The user could start their &latex; file with
+<literal>\PassOptionsToPackage{draft}{graphicx} \documentclass{foo}</literal>.
+</para>
+
+</sect2>
+<sect2 label="12.14.14" id="_005cProcessOptions">
+<title><literal>\ProcessOptions</literal></title>
+
+<indexterm role="fn"><primary>\ProcessOptions</primary></indexterm>
+<indexterm role="cp"><primary>processing options</primary></indexterm>
+<indexterm role="cp"><primary>options, processing</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\ProcessOptions<replaceable>\@options</replaceable>
+\ProcessOptions*<replaceable>\@options</replaceable>
+</screen>
+<para>Execute the code for each option that the user has invoked. Invoke it
+in the class file as <literal>\ProcessOptions\relax</literal> (because of the
+existence of the starred version, described below).
+</para>
+<indexterm role="cp"><primary>options, global and local</primary></indexterm>
+<indexterm role="cp"><primary>local options</primary></indexterm>
+<indexterm role="cp"><primary>global options</primary></indexterm>
+<para>Options come in two types. <firstterm>Local options</firstterm> have been specified
+for this particular package in <literal>\usepackage[<replaceable>options</replaceable>]</literal>,
+<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>, or the <replaceable>options</replaceable> argument
+of <literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>. <firstterm>Global options</firstterm>
+are those given by the class user in
+<literal>\documentclass[<replaceable>options</replaceable>]</literal>. If an option is specified both
+locally and globally then it is local.
+</para>
+<para>When <literal>\ProcessOptions</literal> is called for a package <filename>pkg.sty</filename>, the
+following happens:
+</para>
+<orderedlist numeration="arabic"><listitem><para>For each option <replaceable>option</replaceable> so far declared with
+<literal>\DeclareOption</literal>, <literal>\ProcessOptions</literal> looks to see if that
+option is either global or local for <literal>pkg</literal>. If so, then it
+executes the declared code. This is done in the order in which these
+options were given in <filename>pkg.sty</filename>.
+</para>
+</listitem><listitem><para>For each remaining local option, it executes the command
+<literal>\ds@</literal><replaceable>option</replaceable> if it has been defined somewhere (other than by
+a <literal>\DeclareOption</literal>); otherwise, it executes the default option code
+given in <literal>\DeclareOption*</literal>. If no default option code has been
+declared then it gives an error message. This is done in the order in
+which these options were specified.
+</para></listitem></orderedlist>
+<para>When <literal>\ProcessOptions</literal> is called for a class it works in the same
+way except that all options are local, and the default <replaceable>code</replaceable> for
+<literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error.
+</para>
+<para>The starred version <literal>\ProcessOptions*</literal> executes the
+options in the order specified in the calling commands, rather than in
+the order of declaration in the class or package. For a package, this
+means that the global options are processed first.
+</para>
+
+</sect2>
+<sect2 label="12.14.15" id="_005cProvidesClass-_0026-_005cProvidesPackage">
+<title><literal>\ProvidesClass</literal> &amp; <literal>\ProvidesPackage</literal></title>
+
+<anchor id="_005cProvidesClass"/><anchor id="_005cProvidesPackage"/><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm>
+<indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\ProvidesClass{<replaceable>clsname</replaceable>}[<replaceable>release-date</replaceable> [<replaceable>info-text</replaceable>]]
+\ProvidesPackage{<replaceable>pkgname</replaceable>}[<replaceable>release-date</replaceable> [<replaceable>info-text</replaceable>]]
+</screen>
+<para>Identifies the class or package being defined, printing a message to
+the screen and the log file.
+</para>
+<para>When you load a class or package, for example with
+<literal>\documentclass{smcmemo}</literal> or <literal>\usepackage{test}</literal>,
+&latex; inputs a file (<filename>smcmemo.cls</filename> and <filename>test.sty</filename>,
+respectively). If the name of the file does not match the class or
+package name declared in it then you get a warning. Thus, if you
+invoke <literal>\documentclass{smcmemo}</literal>, and the file
+<filename>smcmemo.cls</filename> has the statement <literal>\ProvidesClass{foo}</literal> then
+you get a warning like <literal>You have requested document class
+`smcmemo', but the document class provides 'foo'.</literal> This warning does
+not prevent &latex; from processing the rest of the class file
+normally.
+</para>
+<para>If you include the optional argument then you must include a date,
+before any spaces, of the form <literal>YYYY/MM/DD</literal>. The rest of the
+optional argument is free-form, although it traditionally identifies
+the class. It is written to the screen during compilation and to the
+log file. Thus, if your file <filename>smcmemo.cls</filename> contains the line
+<literal>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</literal> and
+your document&#8217;s first line is <literal>\documentclass{smcmemo}</literal> then
+you will see <literal>Document Class: smcmemo 2008/06/01 v1.0 SMC memo
+class</literal>.
+</para>
+<para>The date in the optional argument allows class and package users to
+ask to be warned if the version of the class or package is earlier
+than <replaceable>release date</replaceable>. For instance, a user could enter
+<literal>\documentclass{smcmemo}[2018/10/12]</literal> or
+<literal>\usepackage{foo}[[2017/07/07]]</literal> to require a class or package
+with certain features by specifying that it must be released no
+earlier than the given date. Perhaps more importantly, the date
+serves as documentation of the last release. (In practice, package
+users rarely include a date, and class users almost never do.)
+</para>
+
+</sect2>
+<sect2 label="12.14.16" id="_005cProvidesFile">
+<title><literal>\ProvidesFile</literal></title>
+
+<indexterm role="fn"><primary>\ProvidesFile</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\ProvidesFile{<replaceable>filename</replaceable>}[<replaceable>info-text</replaceable>]
+</screen>
+<para>Declare a file other than the main class and package files, such as a
+configuration or font definition file. It writes the given
+information to the log file, essentially like <literal>\ProvidesClass</literal>
+and <literal>\ProvidesPackage</literal> (see the previous section).
+</para>
+<para>For example:
+</para>
+<screen>\ProvidesFile{smcmemo.cfg}[2017/10/12 config file for smcmemo.cls]
+</screen>
+<para>writes this into the log:
+</para>
+<screen>File: smcmemo.cfg 2017/10/12 config file for smcmemo.cls
+</screen>
+
+</sect2>
+<sect2 label="12.14.17" id="_005cRequirePackage-_0026-_005cRequirePackageWithOptions">
+<title><literal>\RequirePackage</literal> &amp; <literal>\RequirePackageWithOptions</literal></title>
+
+<anchor id="_005cRequirePackage"/><anchor id="_005cRequirePackageWithOptions"/><indexterm role="fn"><primary>\RequirePackage</primary></indexterm>
+<indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\RequirePackage[<replaceable>option-list</replaceable>]{<replaceable>pkgname</replaceable>}[<replaceable>release-date</replaceable>]
+\RequirePackageWithOptions{<replaceable>pkgname</replaceable>}[<replaceable>release-date</replaceable>]
+</screen>
+<para>Load a package, like the command <literal>\usepackage</literal> (see <link linkend="Additional-packages">Additional
+packages</link>). An example:
+
+<literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>
+</para>
+<para>The initial optional argument <replaceable>option-list</replaceable>, if present, must be a
+comma-separated list. The trailing optional argument
+<replaceable>release-date</replaceable>, if present, must have the form <literal>YYYY/MM/DD</literal>.
+If the release date of the package as installed on your system is
+earlier than <replaceable>release-date</replaceable> then you get a warning like &#8216;<literal>You
+have requested, on input line 9, version `2017/07/03' of package
+jhtest, but only version `2000/01/01' is available</literal>&#8217;.
+</para>
+<para>The <literal>\RequirePackageWithOptions</literal> variant uses the list of options
+for the current class. This means it ignores any options passed to it
+via <literal>\PassOptionsToClass</literal>. This is a convenience command to
+allow easily building classes on existing ones without having to track
+which options were passed.
+</para>
+<para>The difference between <literal>\usepackage</literal> and <literal>\RequirePackage</literal>
+is small. The <literal>\usepackage</literal> command is intended to be used in
+documents, while <literal>\RequirePackage</literal> is intended for package and
+class files. The most significant difference in practice is that
+<literal>\RequirePackage</literal> can be used in a document before the
+<literal>\documentclass</literal> command, while <literal>\usepackage</literal> gives an error
+there. The most common need for this nowadays is for the
+<literal>\DocumentMetadata</literal> command (see <link linkend="_005cDocumentMetadata">\DocumentMetadata</link>).
+</para>
+<para>The &latex; development team strongly recommends use of these and
+related commands over Plain&#160;&tex;&#8217;s <literal>\input</literal>; see the Class
+Guide (<ulink url="https://ctan.org/pkg/clsguide">https://ctan.org/pkg/clsguide</ulink>).
+</para>
+
+</sect2>
</sect1>
</chapter>
<chapter label="13" id="Counters">
@@ -9703,7 +10269,6 @@ up to four levels of nesting (see <link linkend="enumerate">enumerate</link>).
</para>
-
<sect1 label="13.1" id="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">
<title><literal>\alph \Alph \arabic \roman \Roman \fnsymbol</literal>: Printing counters</title>
@@ -9982,10 +10547,10 @@ placement.
\newcommand{\showhbox}[2]{%
\fboxsep=0pt\fbox{\hbox to #1{#2}}}
</screen>
-<para>This example uses those commands to show a black bar 100&#160;points
-long between &#8216;<literal>XXX</literal>&#8217; and &#8216;<literal>YYY</literal>&#8217;. This length is rigid.
+<para>This next example uses those commands to show a black bar 100&#160;points
+long between &#8216;<literal>ABC</literal>&#8217; and &#8216;<literal>XYZ</literal>&#8217;. This length is rigid.
</para>
-<screen>XXX\showhbox{100pt}{\blackbar{100pt}}YYY
+<screen>ABC\showhbox{100pt}{\blackbar{100pt}}XYZ
</screen>
<para>As for rubber lengths, shrinking is simpler one: with <literal>1cm minus
0.05cm</literal>, the natural length is 1cm but &tex; can shrink it down
@@ -9993,10 +10558,10 @@ as far as 0.95cm. Beyond that, &tex; refuses to shrink any more.
Thus, below the first one works fine, producing a space of
98&#160;points between the two bars.
</para>
-<screen>XXX\showhbox{300pt}{%
+<screen>ABC\showhbox{300pt}{%
\blackbar{101pt}\hspace{100pt minus 2pt}\blackbar{101pt}}YYY
-XXX\showhbox{300pt}{%
+ABC\showhbox{300pt}{%
\blackbar{105pt}\hspace{100pt minus 1pt}\blackbar{105pt}}YYY
</screen>
<para>But the second one gets a warning like &#8216;<literal>Overfull \hbox (1.0pt too
@@ -10009,10 +10574,10 @@ the total to less than 309&#160;points.
beyond the given amount, it will do it. Here the first line is fine,
producing a space of 110&#160;points between the bars.
</para>
-<screen>XXX\showhbox{300pt}{%
+<screen>ABC\showhbox{300pt}{%
\blackbar{95pt}\hspace{100pt plus 10pt}\blackbar{95pt}}YYY
-XXX\showhbox{300pt}{%
+ABC\showhbox{300pt}{%
\blackbar{95pt}\hspace{100pt plus 1pt}\blackbar{95pt}}YYY
</screen>
<para>In the second line &tex; needs a stretch of 10&#160;points and only
@@ -10026,7 +10591,7 @@ length but it gives you a warning like &#8216;<literal>Underfull \hbox (badness
<para>If &tex; is setting two or more rubber lengths then it allocates the
stretch or shrink in proportion.
</para>
-<screen>XXX\showhbox{300pt}{%
+<screen>ABC\showhbox{300pt}{%
\blackbar{100pt}% left
\hspace{0pt plus 50pt}\blackbar{80pt}\hspace{0pt plus 10pt}% middle
\blackbar{100pt}}YYY % right
@@ -10040,7 +10605,7 @@ from the first space and 1/6 from the second.
<para>The <literal>plus</literal> or <literal>minus</literal> component of a rubber length can contain
a <firstterm>fill</firstterm> component, as in <literal>1in plus2fill</literal>. This gives the
length infinite stretchability or shrinkability so that &tex; could set
-it to any distance. Here the two figures will be equal-spaced across
+it to any distance. Here the two figures will be equally spaced across
the page.
</para>
<screen>\begin{minipage}{\linewidth}
@@ -12637,41 +13202,42 @@ one without a dot, <literal>\imath</literal> or <literal>jmath</literal> (see <l
</para>
</sect1>
-<sect1 label="16.5" id="Over_002d-and-Underlining">
-<title>Over- and Underlining</title>
+<sect1 label="16.5" id="Over_002d-or-under-math">
+<title>Over- or under math</title>
+<anchor id="Over_002d-and-Underlining"/><!-- original node name -->
<indexterm role="cp"><primary>overlining</primary></indexterm>
<indexterm role="cp"><primary>underlining</primary></indexterm>
-<para>&latex; provides commands for making overlines or underlines, or
-putting braces over or under some material.
+<para>&latex; provides commands for putting lines, braces, and arrows over
+or under math material.
</para>
-<variablelist>
-<varlistentry><term><indexterm role="fn"><primary>\underline{<replaceable>text</replaceable>}</primary></indexterm><literal>\underline{<replaceable>text</replaceable>}</literal>
-</term><listitem><para>Underline <replaceable>text</replaceable>. Works inside math mode, and outside.
+<variablelist><varlistentry><term><indexterm role="fn"><primary>\underline{<replaceable>math</replaceable>}</primary></indexterm><literal>\underline{<replaceable>math</replaceable>}</literal>
+</term><listitem><para>Underline <replaceable>math</replaceable>. For example: <literal>\underline{x+y}</literal>.
The line is always completely below the text, taking account of
descenders, so in <literal>\(\underline{y}\)</literal> the line is lower than in
-<literal>\(\underline{x}\)</literal>. This command is fragile (see <link linkend="_005cprotect">\protect</link>).
+<literal>\(\underline{x}\)</literal>. As of approximately 2019, this command
+and others in this section are robust; before that, they were fragile
+(see <link linkend="_005cprotect">\protect</link>).
</para>
<indexterm role="cp"><primary>package, <literal>ulem</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>ulem</literal> package</primary></indexterm>
-<para>Note that the package <literal>ulem</literal> does text mode underlining and allows
-line breaking as well as a number of other features. See the
-documentation on CTAN. See also&#160;<link linkend="_005chrulefill-_0026-_005cdotfill">\hrulefill &amp; \dotfill</link> for
-producing a line, for such things as a signature.
+<para>The package <literal>ulem</literal> (<ulink url="https://ctan.org/pkg/uelem">https://ctan.org/pkg/uelem</ulink>) does
+text mode underlining and allows line breaking as well as a number of
+other features. See also&#160;<link linkend="_005chrulefill-_0026-_005cdotfill">\hrulefill &amp; \dotfill</link> for
+producing a line for such things as a signature or placeholder.
</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overline{<replaceable>text</replaceable>}</primary></indexterm><literal>\overline{<replaceable>text</replaceable>}</literal>
-</term><listitem><para>Put a horizontal line over <replaceable>text</replaceable>. Works inside math mode, and
-outside. For example, <literal>\overline{x+y}</literal>.
-Note that this differs from the command <literal>\bar</literal> (see <link linkend="Math-accents">Math
-accents</link>).
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overline{<replaceable>math</replaceable>}</primary></indexterm><literal>\overline{<replaceable>math</replaceable>}</literal>
+</term><listitem><para>Put a horizontal line over <replaceable>math</replaceable>. For example: <literal>\overline{x+y}</literal>.
+This differs from the accent command <literal>\bar</literal> (see <link linkend="Math-accents">Math accents</link>).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\underbrace{<replaceable>math</replaceable>}</literal>
-</term><listitem><para>Put a brace under <replaceable>math</replaceable>. For example, this
-<literal>(1-\underbrace{1/2)+(1/2}-1/3)</literal> emphasizes the telescoping part.
-Attach text to the brace by using the subscript command, <literal>_</literal>, or
-superscript, <literal>^</literal>, as here.
+</term><listitem><para>Put a brace under <replaceable>math</replaceable>. For example:
+<literal>(1-\underbrace{1/2)+(1/2}-1/3)</literal>.
+</para>
+<para>You can attach text to the brace as a subscript (<literal>_</literal>) or
+superscript (<literal>^</literal>) as here:
</para>
<screen>\begin{displaymath}
1+1/2+\underbrace{1/3+1/4}_{&gt;1/2}+
@@ -12682,16 +13248,25 @@ superscript, <literal>^</literal>, as here.
unconnected to the underbrace.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\overbrace{<replaceable>math</replaceable>}</literal>
-</term><listitem><para>Put a brace over <replaceable>math</replaceable>, as with
-<literal>\overbrace{x+x+\cdots+x}^{\mbox{\(k\) times}}</literal>. See also
-<literal>\underbrace</literal>.
+</term><listitem><para>Put a brace over <replaceable>math</replaceable>. For example:
+
+<literal>\overbrace{x+x+\cdots+x}^{\mbox{\(k\) times}}</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overrightarrow{<replaceable>math</replaceable>}</primary></indexterm><literal>\overrightarrow{<replaceable>math</replaceable>}</literal>
+</term><listitem><para>Put a right arrow over <replaceable>math</replaceable>. For example:
+<literal>\overrightarrow{x+y}</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overleftarrow{<replaceable>math</replaceable>}</primary></indexterm><literal>\overleftarrow{<replaceable>math</replaceable>}</literal>
+</term><listitem><para>Put a left arrow over <replaceable>math</replaceable>. For example:
+<literal>\overleftarrow{a+b}</literal>.
</para>
</listitem></varlistentry></variablelist>
<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
-<para>The package <literal>mathtools</literal> adds an over- and underbrace, as well as
-some improvements on the braces. See the documentation on CTAN.
+<para>The package <literal>mathtools</literal> (<ulink url="https://ctan.org/pkg/mathtools">https://ctan.org/pkg/mathtools</ulink>)
+adds an over- and underbracket, as well as some improvements on the
+braces.
</para>
</sect1>
@@ -12850,11 +13425,11 @@ appear in other contexts. However, it doesn&#8217;t change into horizontal
mode. So if it starts a paragraph then you should first put a
<literal>\leavevmode</literal>, as in the bottom line below.
</para>
-<screen>xxx xxx xxx
+<screen>Text above.
-\smash{yyy} % no paragraph indent
+\smash{smashed, no indent} % no paragraph indent
-\leavevmode\smash{zzz} % usual paragraph indent
+\leavevmode\smash{smashed, with indent} % usual paragraph indent
</screen>
<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
@@ -13365,11 +13940,11 @@ To have no date, instead use <literal>\date{}</literal>.
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\thanks{<replaceable>text</replaceable>}</primary></indexterm><literal>\thanks{<replaceable>text</replaceable>}</literal>
</term><listitem><indexterm role="cp"><primary>thanks, for titlepage</primary></indexterm>
<indexterm role="cp"><primary>credit footnote</primary></indexterm>
-<para>Optional. Produce a footnote. You can use it in the author information
-for acknowledgements as illustrated above, but you can also use it in
-the title, or any place a footnote mark makes sense. It can be any text
-at all so you can use it for any purpose, such as to print an email
-address.
+<para>Optional. Produce a footnote. You can use it in the author
+information for acknowledgements as illustrated above, but you can
+also use it in the title, or anywhere that a footnote mark makes
+sense. It can be any text at all so you can use it for any purpose,
+such as to print an email address.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\title{<replaceable>text</replaceable>}</primary></indexterm><literal>\title{<replaceable>text</replaceable>}</literal>
</term><listitem><indexterm role="cp"><primary>title, for titlepage</primary></indexterm>
@@ -13380,11 +13955,11 @@ omit the <literal>\title</literal> declaration then the <literal>\maketitle</lit
yields error &#8216;<literal>LaTeX Error: No \title given</literal>&#8217;.
</para>
</listitem></varlistentry></variablelist>
-<para>To make your own title page, see&#160;<link linkend="titlepage">titlepage</link>. You can either
+<para>To make your own title page, see <link linkend="titlepage">titlepage</link>. You can either
create this as a one-off or you can include it as part of a renewed
-<literal>\maketitle</literal> command. (Many publishers will provide a class to use
+<literal>\maketitle</literal> command. Many publishers will provide a class to use
in place of <literal>article</literal> that formats the title according to their
-house requirements.)
+house requirements.
</para>
</sect1>
@@ -13404,18 +13979,11 @@ contents and other page references. This declaration has global scope
so its effect is not stopped by an end of group such as a closing brace
or an end of environment.
</para>
-<para>In this example, before the &#8216;<literal>Main</literal>&#8217; section the pages are numbered
-&#8216;<literal>a</literal>&#8217;, etc. Starting on the page containing the
-<literal>\pagenumbering</literal> call in that section, the pages are numbered
-&#8216;<literal>1</literal>&#8217;, etc.
+<para>By default, &latex; numbers pages starting at 1, using Arabic
+numerals.
</para>
-<screen>\begin{document}\pagenumbering{alph}
- ...
-\section{Main}\pagenumbering{arabic}
- ...
-</screen>
<para>The argument <replaceable>number-style</replaceable> is one of the following (see
-also&#160;<link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>).
+also <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>).
</para>
<variablelist><varlistentry><term><literal>arabic</literal>
</term><listitem><para>Arabic numerals: 1, 2, &#8230;
@@ -13435,25 +14003,41 @@ get &#8216;<literal>LaTeX Error: Counter too large</literal>&#8217;.
get &#8216;<literal>LaTeX Error: Counter too large</literal>&#8217;.
</para>
</listitem></varlistentry><varlistentry><term><literal>gobble</literal>
-</term><listitem><indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm>
+</term><listitem><para>no page number is output, though the number is still reset.
+References to that page also are blank.
+</para>
+<indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm>
-<para>&latex; does not output a page number, although it
-does get reset. References to that page also are blank. (This does not
-work with the popular package <literal>hyperref</literal> so to have the page number
-not appear you may want to instead use <literal>\pagestyle{empty}</literal> or
-<literal>\thispagestyle{empty}</literal>.)
+
+<para>This setting does not work with the popular package <literal>hyperref</literal>,
+so to omit page numbers you may want to instead use
+<literal>\pagestyle{empty}</literal> or <literal>\thispagestyle{empty}</literal>.
</para>
</listitem></varlistentry></variablelist>
+<para>If you want to typeset the page number in some other way, or change
+where the page number appears on the page, see&#160;<link linkend="_005cpagestyle">\pagestyle</link>
+(in short: use the <literal>fancyhdr</literal> package). The list above of
+&latex;&#8217;s built-in numbering styles cannot be extended.
+</para>
<para>Traditionally, if a document has front matter&#8212;preface, table of
-contents, etc.&#8212;then it is numbered with lowercase Roman numerals. The
-main matter of a document uses arabic. See <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp; \mainmatter
-&amp; \backmatter</link>.
+contents, etc.&#8212;then it is numbered with lowercase Roman
+numerals. The main matter of a document uses arabic. &latex;
+implements this, by providing explicit commands for the different parts
+(see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp; \mainmatter &amp; \backmatter</link>).
</para>
-<para>If you want to change where the page number appears on the page,
-see&#160;<link linkend="_005cpagestyle">\pagestyle</link>. If you want to change the value of the page
-number, then you manipulate the <literal>page</literal> counter (see <link linkend="Counters">Counters</link>).
+<para>As an explicit example, before the &#8216;<literal>Main</literal>&#8217; section the pages are
+numbered &#8216;<literal>a</literal>&#8217;, etc. Starting on the page containing the
+<literal>\pagenumbering</literal> call in that section, the pages are numbered
+&#8216;<literal>1</literal>&#8217;, etc.
+</para>
+<screen>\begin{document}\pagenumbering{alph}
+ ...
+\section{Main}\pagenumbering{arabic}
+ ...
+</screen>
+<para>If you want to change the value of the page number, then you
+manipulate the <literal>page</literal> counter (see <link linkend="Counters">Counters</link>).
</para>
-
</sect1>
<sect1 label="18.3" id="_005cpagestyle">
<title><literal>\pagestyle</literal></title>
@@ -13473,11 +14057,11 @@ from the current page onwards.
<indexterm role="cp"><primary>package, <literal>fancyhdr</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>fancyhdr</literal> package</primary></indexterm>
-<para>A discussion with an example is below. Note first that the package
+<para>A discussion with an example is below. First, however: the package
<literal>fancyhdr</literal> is now the standard way to manipulate headers and
footers. New documents that need to do anything other than one of the
standard options below should use this package. See its documentation
-on CTAN.
+(<ulink url="https://ctan.org/pkg/fancyhdr">https://ctan.org/pkg/fancyhdr</ulink>).
</para>
<para>Values for <replaceable>style</replaceable>:
</para>
@@ -13588,6 +14172,36 @@ To make the page entirely empty, the command
</para>
</sect1>
+<sect1 label="18.5" id="_005cthepage">
+<title><literal>\thepage</literal></title>
+
+<indexterm role="fn"><primary>\thepage</primary></indexterm>
+
+<para>If you want to change the appearance of page numbers only in the page
+headers, for example by adding an ornament, typesetting in small caps,
+etc., then the <literal>fancyhdr</literal> package, as mentioned in a previous
+section, is the best approach.
+</para>
+<indexterm role="cp"><primary>page number representation</primary></indexterm>
+<indexterm role="cp"><primary>table of contents, page numbers in</primary></indexterm>
+<indexterm role="cp"><primary>cross-references, page numbers in</primary></indexterm>
+<para>On the other hand, you may want to change how page numbers are denoted
+everywhere, including the table of contents and cross-references, as
+well as the page headers. In this case, you should redefine
+<literal>\thepage</literal>, which is the command &latex; uses for the
+representation of page numbers.
+</para>
+<para>However, <literal>\thepage</literal> should do any typesetting or other
+complicated maneuvers, but merely expand to the intended page number
+representation. The results of a complicated redefinition of
+<literal>\thepage</literal> are not predictable, but &latex;&#8217;s report of page
+numbers in diagnostic messages, at least, will become unusable.
+</para>
+<para>There is some discussion of this issue at
+<ulink url="https://tex.stackexchange.com/questions/687258">https://tex.stackexchange.com/questions/687258</ulink>.
+</para>
+
+</sect1>
</chapter>
<chapter label="19" id="Spaces">
<title>Spaces</title>
@@ -13764,13 +14378,14 @@ X\hbox to 0pt{\hss Z}Y
<screen>\spacefactor=<replaceable>integer</replaceable>
</screen>
<indexterm role="fn"><primary>\spacefactor</primary></indexterm>
-<para>Influence &latex;&#8217;s glue stretch and shrink behavior. Most user-level
-documents do not use this command.
+<indexterm role="cp"><primary>space factor</primary></indexterm>
+<para>Influence &latex;&#8217;s stretching and shrinking of glue. Few user-level
+documents need to use this.
</para>
<para>While &latex; is laying out the material, it may stretch or shrink the
gaps between words. (This space is not a character; it is called the
-<firstterm>interword glue</firstterm>; see <link linkend="_005chspace">\hspace</link>). The <literal>\spacefactor</literal> command
-(from Plain&#160;&tex;) allows you to, for instance, have the space
+<firstterm>interword glue</firstterm>; see <link linkend="_005chspace">\hspace</link>). The <literal>\spacefactor</literal> parameter
+(a &tex; primitive) allows you to, for instance, have the space
after a period stretch more than the space after a word-ending letter.
</para>
<para>After &latex; places each character, or rule or other box, it sets a
@@ -13780,48 +14395,49 @@ can happen. A space factor that is larger than the normal value means
that the glue can stretch more and shrink less. Normally, the space
factor is 1000. This value is in effect following most characters, and
any non-character box or math formula. But it is 3000 after a period,
-exclamation mark, or question mark, it is 2000 after a colon, 1500 after
+exclamation mark, or question mark, 2000 after a colon, 1500 after
a semicolon, 1250 after a comma, and 0 after a right parenthesis or
bracket, or closing double quote or single quote. Finally, it is 999
after a capital letter.
</para>
<para>If the space factor&#160;<replaceable>f</replaceable> is 1000 then the glue gap will be the
font&#8217;s normal space value (for Computer Modern Roman 10 point this is
-3.3333&#160;points). Otherwise, if the space factor <replaceable>f</replaceable> is greater
+3.3333pt). Otherwise, if the space factor <replaceable>f</replaceable> is greater
than 2000 then &tex; adds the font&#8217;s extra space value (for Computer
-Modern Roman 10 point this is 1.11111&#160;points), and then the font&#8217;s
+Modern Roman 10 point this is 1.11111pt), and then the font&#8217;s
normal stretch value is multiplied by <inlineequation><mathphrase>f /1000</mathphrase></inlineequation> and the normal
shrink value is multiplied by <inlineequation><mathphrase>1000/f</mathphrase></inlineequation> (for Computer Modern Roman
-10 point these are 1.66666 and 1.11111&#160;points).
+10 point these are 1.66666 and 1.11111pt).
</para>
-<para>For example, consider the period ending <literal>A man's best friend is his
-dog.</literal> After it, &tex; puts in a fixed extra space, and also allows the
-glue to stretch 3 times as much and shrink 1/3 as much, as the glue
-after <literal>friend</literal>, which does not end in a period.
+<para>For example, consider the period ending &#8216;<literal>A man's best friend is
+his dog.</literal>&#8217;. After it, &tex; puts in a fixed extra space, and also
+allows the glue to stretch 3 times as much and shrink 1/3 as much, as
+the glue after <literal>friend</literal> or any of the other words, since they are
+not followed by punctuation.
</para>
<para>The rules for space factors are even more complex because they play
-additional roles. In practice, there are two consequences. First, if a
-period or other punctuation is followed by a right parenthesis or
-bracket, or right single or double quote then the spacing effect of that
-period carries through those characters (that is, the following glue
-will have increased stretch and shrink). Second, if
-punctuation comes after a capital letter then its effect is not in place
-so you get an ordinary space. This second case also affects abbreviations
-that do not end in a capital letter (see <link linkend="_005c_0040">\@</link>).
+additional roles. In practice, there are two consequences. First, if
+a period or other punctuation is followed by a right parenthesis or
+bracket, or right single or double quote then the spacing effect of
+that period carries through those characters (that is, the following
+glue will have increased stretch and shrink). Second, if punctuation
+comes after a capital letter then the normal effect of the period is
+does not happen, so you get an ordinary space. This second case also
+affects abbreviations that do not end in a capital letter
+(see <link linkend="_005c_0040">\@</link>).
</para>
<para>You can only use <literal>\spacefactor</literal> in paragraph mode or LR mode
(see <link linkend="Modes">Modes</link>). You can see the current value with
<literal>\the\spacefactor</literal> or <literal>\showthe\spacefactor</literal>.
</para>
-<para>(Comment, not really related to <literal>\spacefactor</literal>: if you get errors
-like &#8216;<literal>You can't use `\spacefactor' in vertical mode</literal>&#8217;, or &#8216;<literal>You
-can't use `\spacefactor' in math mode.</literal>&#8217;, or &#8216;<literal>Improper \spacefactor</literal>&#8217;
-then you have probably tried to redefine an internal command.
-See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>.)
+<para>Finally, not especially related to <literal>\spacefactor</literal> itself: if you
+get errors like &#8216;<literal>You can't use `\spacefactor' in vertical mode</literal>&#8217;,
+or &#8216;<literal>You can't use `\spacefactor' in math mode.</literal>&#8217;, or
+&#8216;<literal>Improper \spacefactor</literal>&#8217; then you have probably tried to redefine
+an internal command. See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>.
</para>
-
<sect2 label="19.5.1" id="_005c_0040">
<title><literal>\@</literal></title>
@@ -13830,30 +14446,34 @@ See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter &amp;
<indexterm role="cp"><primary>period, sentence-ending</primary></indexterm>
<indexterm role="cp"><primary>period, abbreviation-ending</primary></indexterm>
<indexterm role="cp"><primary>period, spacing after</primary></indexterm>
+<indexterm role="cp"><primary>sentence-ending punctuation</primary></indexterm>
+<indexterm role="cp"><primary>non-sentence-ending punctuation</primary></indexterm>
+<indexterm role="cp"><primary>punctuation, sentence-ending</primary></indexterm>
<anchor id="_005cAT"/><!-- old name -->
<para>Synopsis:
</para>
<screen><replaceable>capital-letter</replaceable>\@.
</screen>
-<para>Treat a period as sentence-ending, where &latex; would otherwise think
-it is part of an abbreviation. &latex; thinks that a period ends an
-abbreviation if the period comes after a capital letter, and otherwise
-thinks the period ends the sentence. By default, in justifying a line
-&latex; adjusts the space after a sentence-ending period (or a question
-mark, exclamation point, comma, or colon) more than it adjusts the space
-between words (see <link linkend="_005cspacefactor">\spacefactor</link>).
+<para>Treat a period (or other punctuation) as sentence-ending, where
+&latex; would otherwise think it is part of an abbreviation.
+&latex; thinks that a period ends an abbreviation if the period comes
+after a capital letter, and otherwise thinks the period ends the
+sentence.
</para>
<para>This example shows the two cases to remember.
</para>
<screen>The songs \textit{Red Guitar}, etc.\ are by Loudon Wainwright~III\@.
</screen>
-<para>The second period ends the sentence, despite that it is preceded by a
-capital. We tell &latex; that it ends the sentence by putting
-<literal>\@</literal> before it. The first period ends the abbreviation
-&#8216;<literal>etc.</literal>&#8217; but not the sentence. The backslash-space, <literal>\ </literal>,
-produces a mid-sentence space.
+<para>The first period ends the abbreviation &#8216;<literal>etc.</literal>&#8217; but not the
+sentence. The backslash-space, <literal>\ </literal>, produces a mid-sentence
+space. The second period ends the sentence, despite it being preceded
+by a capital letter. We tell &latex; that it ends the sentence by
+putting <literal>\@</literal> before it.
</para>
+<indexterm role="cp"><primary>right parentheses/quotes, and spacing</primary></indexterm>
+<indexterm role="cp"><primary>parentheses and ends of sentences</primary></indexterm>
+<indexterm role="cp"><primary>quotes and ends of sentences</primary></indexterm>
<para>So: if you have a capital letter followed by a period that ends the
sentence, then put <literal>\@</literal> before the period. This holds even if
there is an intervening right parenthesis or bracket, or right single or
@@ -13865,17 +14485,24 @@ those characters. For example, this
</screen>
<para>will have correct inter-sentence spacing after the period.
</para>
-<para>The <literal>\@</literal> command is only for a text mode. If you use it outside of
-a text mode then you get &#8216;<literal>You can't use `\spacefactor' in vertical
-mode</literal>&#8217; (see <link linkend="Modes">Modes</link>).
+<para>The <literal>\@</literal> command is only for text modes. If you use it outside
+of a text mode then you get the error &#8216;<literal>You can't use
+`\spacefactor' in vertical mode</literal>&#8217; (see <link linkend="Modes">Modes</link>).
</para>
-<para>Comment: the converse case is a period ending an abbreviation whose last
-letter is not a capital letter, and that abbreviation is not the last
-word in the sentence. For that case follow the period with a
+<indexterm role="cp"><primary>question marks, ending a sentence</primary></indexterm>
+<indexterm role="cp"><primary>exclamation points, ending a sentence</primary></indexterm>
+<para>All the above applies equally to question marks and exclamation points
+as periods, since all are sentence-ending punctuation, and &latex;
+increases the space after each in the same way, when they end a
+sentence. &latex; also increases spacing after colon, semicolon, and
+comma characters (see <link linkend="_005cspacefactor">\spacefactor</link>).
+</para>
+<para>In addition: the converse case is a period (or other punctuation) that
+does not end a sentence. For that case, follow the period with a
backslash-space, (<literal>\ </literal>), or a tie, (<literal>~</literal>), or <literal>\@</literal>.
Examples are <literal>Nat.\ Acad.\ Science</literal>, and <literal>Mr.~Bean</literal>, and
<literal>(manure, etc.\@) for sale</literal> (note in the last one that the
-<literal>\@</literal> comes before the closing parenthesis).
+<literal>\@</literal> comes after the period but before the closing parenthesis).
</para>
</sect2>
@@ -13892,18 +14519,21 @@ Examples are <literal>Nat.\ Acad.\ Science</literal>, and <literal>Mr.~Bean</lit
<screen>\frenchspacing
\nonfrenchspacing
</screen>
-<para>The first declaration causes &latex; to handle spacing between
-sentences in the same way as spacing between words in the middle of a
-sentence. The second switches back to the default handling in which
-spacing between sentences stretches or shrinks more
-(see <link linkend="_005cspacefactor">\spacefactor</link>).
+<para><literal>\frenchspacing</literal> causes &latex; to make spacing after all
+punctuation, including periods, be the same as the space between words
+in the middle of a sentence. <literal>\nonfrenchspacing</literal> switches back
+to the default handling in which spacing after most punctuation stretches
+or shrinks differently than a word space (see <link linkend="_005cspacefactor">\spacefactor</link>).
</para>
-<para>Some typographic traditions, including English, prefer to adjust the
-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
-spaces are treated equally.
+<para>In American English, the typesetting tradition is to adjust, typically
+increasing, the space after punctuation more than the space between
+words that are in the middle of a sentence. Declaring
+<literal>\frenchspacing</literal> (the command is inherited from plain &tex;)
+switches to the tradition that all spaces are treated equally.
+</para>
+<para>If your &latex; document specifies the language being used, for
+example with the <literal>babel</literal> package, the necessary settings
+should be taken care of for you.
</para>
</sect2>
@@ -13929,20 +14559,20 @@ spaces are treated equally.
<indexterm role="cp"><primary>\<keycap>NEWLINE</keycap></primary></indexterm>
<indexterm role="cp"><primary>\<keycap>SPACE</keycap></primary></indexterm>
<indexterm role="cp"><primary>\<keycap>TAB</keycap></primary></indexterm>
-<indexterm role="fn"><primary>\ <!-- /@w --> (backslash-space)</primary></indexterm>
+<indexterm role="fn"><primary>\&amp;#160;<!-- /@w --> (backslash-space)</primary></indexterm>
<indexterm role="fn"><primary>\<keycap>SPACE</keycap></primary></indexterm>
<para>This section refers to the command consisting of two characters, a
-backslash followed by a space.
-Synopsis:
+backslash followed by a space. Synopsis:
</para>
-<screen>\ <!-- /@w -->
+<screen>\&amp;#160;<!-- /@w -->
</screen>
<para>Produce a space. By default it produces white space of length
3.33333pt plus 1.66666pt minus 1.11111pt.
</para>
-<para>When you type one or more blanks between words, &latex; produces white
-space. But that is different than an explicit space. This illustrates.
+<para>When you type one or more blanks between words, &latex; produces
+whitespace that is different than an explicit space. This
+illustrates:
</para>
<screen>\begin{tabular}{rl}
One blank:&amp; makes some space \\
@@ -13974,9 +14604,9 @@ or <literal>Jones et al.\ (1993)</literal> (see <link linkend="_005c_0040">\@</l
<para>Under normal circumstances, <literal>\</literal><keycap>TAB</keycap> and <literal>\</literal><keycap>NEWLINE</keycap>
are equivalent to backslash-space, <literal>\ </literal>.
</para>
-<anchor id="Leading-blanks"/><para>Please also note that in order to allow source code indentation, under
-normal circumstances, &tex; ignores leading blanks in a line. So the
-following prints &#8216;<literal>one word</literal>&#8217;:
+<anchor id="Leading-blanks"/><para>In order to allow source code indentation, under normal circumstances,
+&tex; ignores leading blanks in a line. So the following prints
+&#8216;<literal>one word</literal>&#8217;:
</para>
<screen>one
word
@@ -13991,7 +14621,7 @@ the newline after &#8216;<literal>one</literal>&#8217;, not by the space before
</sect1>
<sect1 label="19.7" id="_007e">
-<title><literal>~</literal></title>
+<title><literal>~</literal>, <literal>\nobreakspace</literal></title>
<indexterm role="fn"><primary>~</primary></indexterm>
<indexterm role="cp"><primary>tie</primary></indexterm>
@@ -14004,10 +14634,14 @@ the newline after &#8216;<literal>one</literal>&#8217;, not by the space before
</para>
<screen><replaceable>before</replaceable>~<replaceable>after</replaceable>
</screen>
+<indexterm role="fn"><primary>\nobreakspace</primary></indexterm>
+<indexterm role="cp"><primary>no-break space, Unicode U+00A0</primary></indexterm>
<para>The <firstterm>tie</firstterm> character, <literal>~</literal>, produces a space between <replaceable>before</replaceable> and
<replaceable>after</replaceable> at which the line will not be broken. By default the white
space has length 3.33333pt plus 1.66666pt minus
-1.11111pt (see <link linkend="Lengths">Lengths</link>).
+1.11111pt (see <link linkend="Lengths">Lengths</link>). The command <literal>\nobreakspace</literal>
+and the Unicode input character U+00A0 (also in many 8-bit encodings)
+are synonyms.
</para>
<!-- This paragraph is not translated to French, as the French translation -->
<!-- uses a term that means ``unbreakable''. -->
@@ -14023,14 +14657,14 @@ in <citetitle>The &tex;book</citetitle>.
<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. 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>Ties prevent a line break 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>Exactly where ties should be used is something of a matter 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 label and number, such as in references:
<literal>Chapter~12</literal>, or <literal>Theorem~\ref{th:Wilsons}</literal>, or
@@ -14613,7 +15247,7 @@ enough to contain the <replaceable>text</replaceable>. (They are like plain &te
<para>In the third version the optional argument <replaceable>width</replaceable> specifies the
width of the box. Note that the space occupied by the text need not
equal the width of the box. For one thing, <replaceable>text</replaceable> can be too small;
-this creates a full-line box
+this creates a full-line box:
</para>
<screen>\makebox[\linewidth]{Chapter Exam}
</screen>
@@ -15025,317 +15659,7 @@ backslash, <literal>\</literal>.) This command is robust (see <link linkend="_0
</sect1>
</chapter>
-<chapter label="21" id="Color">
-<title>Color</title>
-
-<indexterm role="cp"><primary>color</primary></indexterm>
-
-<para>You can add color to text, rules, etc. You can also have color in a box
-or on an entire page and write text on top of it.
-</para>
-<para>Color support comes as an additional package. So put
-<literal>\usepackage{color}</literal> in your document preamble to use the
-commands described here.
-</para>
-<para>Many other packages also supplement &latex;&#8217;s color abilities.
-Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and
-significantly extends the capabilities described here, including adding
-&#8216;<literal>HTML</literal>&#8217; and &#8216;<literal>Hsb</literal>&#8217; color models.
-</para>
-
-
-<sect1 label="21.1" id="Color-package-options">
-<title><literal>color</literal> package options</title>
-
-<indexterm role="cp"><primary>color package options</primary></indexterm>
-<indexterm role="cp"><primary>options, color package</primary></indexterm>
-
-<para>Synopsis (must be in the document preamble):
-</para>
-<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{color}
-</screen>
-<para>When you load the <filename>color</filename> package there are two kinds of available
-options.
-</para>
-<para>The first specifies the <firstterm>printer driver</firstterm>. &latex; doesn&#8217;t contain
-information about different output systems but instead depends on
-information stored in a file. Normally you should not specify the
-driver option in the document, and instead rely on your system&#8217;s
-default. One advantage of this is that it makes the document portable
-across systems. For completeness we include a list of the drivers. The
-currently relevant ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>,
-<filename>dvisvgm</filename>, <filename>luatex</filename>, <filename>pdftex</filename>, <filename>xetex</filename>. The two
-<filename>xdvi</filename> and <filename>oztex</filename> are essentially aliases for <filename>dvips</filename>
-(and <filename>xdvi</filename> is monochrome). Ones that should not be used for new
-systems are: <filename>dvipdf</filename>, <filename>dvipdfm</filename>, <filename>dviwin</filename>,
-<filename>dvipsone</filename>, <filename>emtex</filename>, <filename>pctexps</filename>, <filename>pctexwin</filename>,
-<filename>pctexhp</filename>, <filename>pctex32</filename>, <filename>truetex</filename>, <filename>tcidvi</filename>,
-<filename>vtex</filename> (and <filename>dviwindo</filename> is an alias for <filename>dvipsone</filename>).
-</para>
-<para>The second kind of options, beyond the drivers, are below.
-</para>
-<variablelist>
-<varlistentry><term><literal>monochrome</literal>
-</term><listitem><para>Disable the color commands, so that they do not generate errors but do
-not generate color either.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>dvipsnames</literal>
-</term><listitem><para>Make available a list of 68 color names that are often used,
-particularly in legacy documents. These color names were originally
-provided by the <filename>dvips</filename> driver, giving the option name.
-</para>
-</listitem></varlistentry><varlistentry><term><literal>nodvipsnames</literal>
-</term><listitem><para>Do not load that list of color names, saving &latex; a tiny amount of
-memory space.
-</para>
-</listitem></varlistentry></variablelist>
-
-</sect1>
-<sect1 label="21.2" id="Color-models">
-<title>Color models</title>
-
-<indexterm role="cp"><primary>color models</primary></indexterm>
-
-<para>A <firstterm>color model</firstterm> is a way of representing colors. &latex;&#8217;s
-capabilities depend on the printer driver. However, the <filename>pdftex</filename>,
-<filename>xetex</filename>, and <filename>luatex</filename> printer drivers are today by far the
-most commonly used. The models below work for those drivers. All but
-one of these is also supported by essentially all other printer drivers
-used today.
-</para>
-<para>Note that color combination can be additive or subtractive. Additive
-mixes colors of light, so that for instance combining full intensities
-of red, green, and blue produces white. Subtractive mixes pigments,
-such as with inks, so that combining full intensity of cyan, magenta,
-and yellow makes black.
-</para>
-<variablelist><anchor id="color-models-cmyk"/><varlistentry><term><literal>cmyk</literal>
-</term><listitem><para>A comma-separated list with four real numbers between 0 and 1,
-inclusive. The first number is the intensity of cyan, the second is
-magenta, and the others are yellow and black. A number value of 0 means
-minimal intensity, while a 1 is for full intensity. This model is often
-used in color printing. It is a subtractive model.
-</para>
-<anchor id="color-models-gray"/></listitem></varlistentry><varlistentry><term><literal>gray</literal>
-</term><listitem><para>A single real number between 0 and 1, inclusive. The colors are shades
-of grey. The number 0 produces black while 1 gives white.
-</para>
-<anchor id="color-models-rgb"/></listitem></varlistentry><varlistentry><term><literal>rgb</literal>
-</term><listitem><para>A comma-separated list with three real numbers between 0 and 1,
-inclusive. The first number is the intensity of the red component, the
-second is green, and the third the blue. A number value of 0 means that
-none of that component is added in, while a 1 means full intensity.
-This is an additive model.
-</para>
-<anchor id="color-models-RGB"/></listitem></varlistentry><varlistentry><term><literal>RGB</literal>
-</term><listitem><para>(<filename>pdftex</filename>, <filename>xetex</filename>, <filename>luatex</filename> drivers) A comma-separated
-list with three integers between 0 and 255, inclusive. This model is a
-convenience for using <literal>rgb</literal> since outside of &latex; colors are
-often described in a red-green-blue model using numbers in this range.
-The values entered here are converted to the <literal>rgb</literal> model by
-dividing by 255.
-</para>
-<anchor id="color-models-named"/></listitem></varlistentry><varlistentry><term><literal>named</literal>
-</term><listitem><para>Colors are accessed by name, such as &#8216;<literal>PrussianBlue</literal>&#8217;. The list of
-names depends on the driver, but all support the names &#8216;<literal>black</literal>&#8217;,
-&#8216;<literal>blue</literal>&#8217;, &#8216;<literal>cyan</literal>&#8217;, &#8216;<literal>green</literal>&#8217;, &#8216;<literal>magenta</literal>&#8217;, &#8216;<literal>red</literal>&#8217;,
-&#8216;<literal>white</literal>&#8217;, and &#8216;<literal>yellow</literal>&#8217; (See the <literal>dvipsnames</literal> option in
-<link linkend="Color-package-options">Color package options</link>).
-</para>
-</listitem></varlistentry></variablelist>
-
-</sect1>
-<sect1 label="21.3" id="Commands-for-color">
-<title>Commands for color</title>
-
-<indexterm role="cp"><primary>color package commands</primary></indexterm>
-
-<para>These are the commands available with the <filename>color</filename> package.
-</para>
-
-
-<sect2 label="21.3.1" id="Define-colors">
-<title>Define colors</title>
-
-<indexterm role="cp"><primary>color</primary></indexterm>
-<indexterm role="cp"><primary>define color</primary></indexterm>
-<indexterm role="cp"><primary>color, define</primary></indexterm>
-
-<para>Synopsis:
-</para>
-<screen>\definecolor{<replaceable>name</replaceable>}{<replaceable>model</replaceable>}{<replaceable>specification</replaceable>}
-</screen>
-<para>Give the name <replaceable>name</replaceable> to the color. For example, after this
-</para>
-<screen>\definecolor{silver}{rgb}{0.75,0.75,0.74}
-</screen>
-<para>you can use that color name with <literal>Hi ho,
-\textcolor{silver}{Silver}!</literal>.
-</para>
-<para>This example gives the color a more abstract name, so it could change and
-not be misleading.
-</para>
-<screen>\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex
-\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}}
-</screen>
-<para>Often a document&#8217;s colors are defined in the preamble, or in the class
-or style, rather than in the document body.
-</para>
-
-</sect2>
-<sect2 label="21.3.2" id="Colored-text">
-<title>Colored text</title>
-
-<indexterm role="cp"><primary>color</primary></indexterm>
-<indexterm role="cp"><primary>colored text</primary></indexterm>
-
-<para>Synopses:
-</para>
-<screen>\textcolor{<replaceable>name</replaceable>}{...}
-\textcolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}{...}
-</screen>
-<para>or
-</para>
-<screen>\color{<replaceable>name</replaceable>}
-\color[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}
-</screen>
-<para>The affected text gets the color. This line
-</para>
-<screen>\textcolor{magenta}{My name is Ozymandias, King of Kings;}
-Look on my works, ye Mighty, and despair!
-</screen>
-<para>causes the first half to be in magenta while the rest is in black. You
-can use a color declared with <literal>\definecolor</literal> in exactly the same
-way that we just used the builtin color &#8216;<literal>magenta</literal>&#8217;.
-</para>
-<screen>\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0}
-I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}.
-</screen>
-<para>The two <literal>\textcolor</literal> and <literal>\color</literal> differ in that the first is
-a command form, enclosing the text to be colored as an argument. Often
-this form is more convenient, or at least more explicit. The second
-form is a declaration, as in <literal>The moon is made of {\color{green}
-green} cheese</literal>, so it is in effect until the end of the current group
-or environment. This is sometimes useful when writing macros or as
-below where it colors everything inside the <literal>center</literal> environment,
-including the vertical and horizontal lines.
-</para>
-<screen>\begin{center} \color{blue}
- \begin{tabular}{l|r}
- UL &amp;UR \\ \hline
- LL &amp;LR
- \end{tabular}
-\end{center}
-</screen>
-<para>You can use color in equations. A document might have this definition
-in the preamble
-</para>
-<screen>\definecolor{highlightcolor}{RGB}{225,15,0}
-</screen>
-<para>and then contain this equation.
-</para>
-<screen>\begin{equation}
- \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a)
-\end{equation}
-</screen>
-<para>Typically the colors used in a document are declared in a class or style
-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.
-</screen>
-<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>
-<screen>The selection was \textcolor[gray]{0.5}{grayed out}.
-</screen>
-<para>Colors inside colors do not combine. Thus
-</para>
-<screen>\textcolor{green}{kind of \textcolor{blue}{blue}}
-</screen>
-<para>has a final word that is blue, not a combination of blue and green.
-</para>
-<!-- xx address coloring a line of a table? -->
-
-
-</sect2>
-<sect2 label="21.3.3" id="Colored-boxes">
-<title>Colored boxes</title>
-
-<indexterm role="cp"><primary>color</primary></indexterm>
-<indexterm role="cp"><primary>colored boxes</primary></indexterm>
-<indexterm role="cp"><primary>box, colored</primary></indexterm>
-
-<para>Synopses:
-</para>
-<screen>\colorbox{<replaceable>name</replaceable>}{...}
-\colorbox[<replaceable>model name</replaceable>]{<replaceable>box background color</replaceable>}{...}
-</screen>
-<para>or
-</para>
-<screen>\fcolorbox{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...}
-\fcolorbox[<replaceable>model name</replaceable>]{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...}
-</screen>
-<para>Make a box with the stated background color. The <literal>\fcolorbox</literal>
-command puts a frame around the box. For instance this
-</para>
-<screen>Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}}
-</screen>
-<para>makes a cyan-colored box that is five centimeters long and gets its
-depth and height from the <literal>\strut</literal> (so the depth is
-<literal>-.3\baselineskip</literal> and the height is <literal>\baselineskip</literal>). This
-puts white text on a blue background.
-</para>
-<screen>\colorbox{blue}{\textcolor{white}{Welcome to the machine.}}
-</screen>
-<para>The <literal>\fcolorbox</literal> commands use the same parameters as <literal>\fbox</literal>
-(see <link linkend="_005cfbox-_0026-_005cframebox">\fbox &amp; \framebox</link>), <literal>\fboxrule</literal> and <literal>\fboxsep</literal>, to
-set the thickness of the rule and the boundary between the box interior
-and the surrounding rule. &latex;&#8217;s defaults are <literal>0.4pt</literal> and
-<literal>3pt</literal>, respectively.
-</para>
-<para>This example changes the thickness of the border to 0.8 points. Note
-that it is surrounded by curly braces so that the change ends at the end
-of the second line.
-</para>
-<screen>{\setlength{\fboxrule}{0.8pt}
-\fcolorbox{black}{red}{Under no circumstances turn this knob.}}
-</screen>
-
-</sect2>
-<sect2 label="21.3.4" id="Colored-pages">
-<title>Colored pages</title>
-
-<indexterm role="cp"><primary>color</primary></indexterm>
-<indexterm role="cp"><primary>colored page</primary></indexterm>
-<indexterm role="cp"><primary>page, colored</primary></indexterm>
-<indexterm role="cp"><primary>background, colored</primary></indexterm>
-
-<para>Synopses:
-</para>
-<screen>\pagecolor{<replaceable>name</replaceable>}
-\pagecolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}
-\nopagecolor
-</screen>
-<para>The first two set the background of the page, and all subsequent pages,
-to the color. For an explanation of the specification in the second
-form see <link linkend="Colored-text">Colored text</link>. The third returns the background to normal,
-which is a transparent background. (If that is not supported use
-<literal>\pagecolor{white}</literal>, although that will make a white background
-rather than the default transparent background.)
-</para>
-<screen> ...
-\pagecolor{cyan}
- ...
-\nopagecolor
-</screen>
-
-</sect2>
-</sect1>
-</chapter>
-<chapter label="22" id="Graphics">
+<chapter label="21" id="Graphics">
<title>Graphics</title>
<indexterm role="cp"><primary>graphics</primary></indexterm>
@@ -15378,7 +15702,7 @@ see their documentation on CTAN.
</para>
-<sect1 label="22.1" id="Graphics-package-options">
+<sect1 label="21.1" id="Graphics-package-options">
<title><literal>graphics</literal> package options</title>
<indexterm role="cp"><primary>graphics package options</primary></indexterm>
@@ -15452,7 +15776,7 @@ option has &latex; to read the size from the latter.
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="22.2" id="Graphics-package-configuration">
+<sect1 label="21.2" id="Graphics-package-configuration">
<title><literal>graphics</literal> package configuration</title>
<indexterm role="cp"><primary>graphics</primary></indexterm>
@@ -15470,7 +15794,7 @@ the documentation in <filename>grfguide.pdf</filename>, or the &latex; source, o
</para>
-<sect2 label="22.2.1" id="_005cgraphicspath">
+<sect2 label="21.2.1" id="_005cgraphicspath">
<title><literal>\graphicspath</literal></title>
<indexterm role="fn"><primary>\graphicspath</primary></indexterm>
@@ -15541,7 +15865,7 @@ instead in <filename>book/plots</filename>.
</para>
</sect2>
-<sect2 label="22.2.2" id="_005cDeclareGraphicsExtensions">
+<sect2 label="21.2.2" id="_005cDeclareGraphicsExtensions">
<title><literal>\DeclareGraphicsExtensions</literal></title>
<indexterm role="fn"><primary>\DeclareGraphicsExtensions</primary></indexterm>
@@ -15591,7 +15915,7 @@ than once. Show its value with
</para>
</sect2>
-<sect2 label="22.2.3" id="_005cDeclareGraphicsRule">
+<sect2 label="21.2.3" id="_005cDeclareGraphicsRule">
<title><literal>\DeclareGraphicsRule</literal></title>
<indexterm role="fn"><primary>\DeclareGraphicsRule</primary></indexterm>
@@ -15667,7 +15991,7 @@ See the documentation for your &tex; distribution.
</listitem></varlistentry></variablelist>
</sect2>
</sect1>
-<sect1 label="22.3" id="Commands-for-graphics">
+<sect1 label="21.3" id="Commands-for-graphics">
<title>Commands for graphics</title>
<indexterm role="cp"><primary>graphics package commands</primary></indexterm>
@@ -15678,7 +16002,7 @@ See the documentation for your &tex; distribution.
</para>
-<sect2 label="22.3.1" id="_005cincludegraphics">
+<sect2 label="21.3.1" id="_005cincludegraphics">
<title><literal>\includegraphics</literal></title>
<indexterm role="cp"><primary>graphics</primary></indexterm>
@@ -15990,8 +16314,8 @@ override a prior setting of <literal>true</literal>, you can set it to <literal>
</listitem></varlistentry></variablelist>
<para>These following options allow a user to override &latex;&#8217;s method of
choosing the graphic type based on the filename extension. An example
-is that <literal>\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}</literal>
-will read the file <filename>lion.xxx</filename> as though it were
+is that <literal>\includegraphics[type=png,ext=.xyz,read=.xyz]{lion}</literal>
+will read the file <filename>lion.xyz</filename> as though it were
<filename>lion.png</filename>. For more on these, see <link linkend="_005cDeclareGraphicsRule">\DeclareGraphicsRule</link>.
</para>
<variablelist><anchor id="includegraphics-type"/><varlistentry><term><literal>type</literal>
@@ -16014,7 +16338,7 @@ external commands.
</listitem></varlistentry></variablelist>
</sect2>
-<sect2 label="22.3.2" id="_005crotatebox">
+<sect2 label="21.3.2" id="_005crotatebox">
<title><literal>\rotatebox</literal></title>
<indexterm role="cp"><primary>rotation</primary></indexterm>
@@ -16092,7 +16416,7 @@ setting <literal>units=6.283185</literal> changes to radians counterclockwise.
</listitem></varlistentry></variablelist>
</sect2>
-<sect2 label="22.3.3" id="_005cscalebox">
+<sect2 label="21.3.3" id="_005cscalebox">
<title><literal>\scalebox</literal></title>
<indexterm role="cp"><primary>graphics, scaling</primary></indexterm>
@@ -16135,7 +16459,7 @@ immediately followed by its mirror reflection against a vertical axis.
</para>
</sect2>
-<sect2 label="22.3.4" id="_005cresizebox">
+<sect2 label="21.3.4" id="_005cresizebox">
<title><literal>\resizebox</literal></title>
<indexterm role="cp"><primary>graphics, scaling</primary></indexterm>
@@ -16176,6 +16500,315 @@ text two inches wide but keep the original height with
</sect2>
</sect1>
</chapter>
+<chapter label="22" id="Color">
+<title>Color</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+
+<para>You can add color to text, rules, etc. You can also have color in a box
+or on an entire page and write text on top of it.
+</para>
+<para>Color support comes as an additional package. So put
+<literal>\usepackage{color}</literal> in your document preamble to use the
+commands described here.
+</para>
+<para>Many other packages also supplement &latex;&#8217;s color abilities.
+Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and
+significantly extends the capabilities described here, including adding
+&#8216;<literal>HTML</literal>&#8217; and &#8216;<literal>Hsb</literal>&#8217; color models.
+</para>
+
+
+<sect1 label="22.1" id="Color-package-options">
+<title><literal>color</literal> package options</title>
+
+<indexterm role="cp"><primary>color package options</primary></indexterm>
+<indexterm role="cp"><primary>options, color package</primary></indexterm>
+
+<para>Synopsis (must be in the document preamble):
+</para>
+<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{color}
+</screen>
+<para>When you load the <filename>color</filename> package there are two kinds of available
+options.
+</para>
+<para>The first specifies the <firstterm>printer driver</firstterm>. &latex; doesn&#8217;t contain
+information about different output systems but instead depends on
+information stored in a file. Normally you should not specify the
+driver option in the document, and instead rely on your system&#8217;s
+default. One advantage of this is that it makes the document portable
+across systems. For completeness we include a list of the drivers. The
+currently relevant ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>,
+<filename>dvisvgm</filename>, <filename>luatex</filename>, <filename>pdftex</filename>, <filename>xetex</filename>. The two
+<filename>xdvi</filename> and <filename>oztex</filename> are essentially aliases for <filename>dvips</filename>
+(and <filename>xdvi</filename> is monochrome). Ones that should not be used for new
+systems are: <filename>dvipdf</filename>, <filename>dvipdfm</filename>, <filename>dviwin</filename>,
+<filename>dvipsone</filename>, <filename>emtex</filename>, <filename>pctexps</filename>, <filename>pctexwin</filename>,
+<filename>pctexhp</filename>, <filename>pctex32</filename>, <filename>truetex</filename>, <filename>tcidvi</filename>,
+<filename>vtex</filename> (and <filename>dviwindo</filename> is an alias for <filename>dvipsone</filename>).
+</para>
+<para>The second kind of options, beyond the drivers, are below.
+</para>
+<variablelist><varlistentry><term><literal>monochrome</literal>
+</term><listitem><para>Disable the color commands, so that they do not generate errors but do
+not generate color either.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>dvipsnames</literal>
+</term><listitem><para>Make available a list of 68 color names that are often used,
+particularly in legacy documents. These color names were originally
+provided by the <filename>dvips</filename> driver, giving the option name.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>nodvipsnames</literal>
+</term><listitem><para>Do not load that list of color names, saving &latex; a tiny amount of
+memory space.
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect1>
+<sect1 label="22.2" id="Color-models">
+<title>Color models</title>
+
+<indexterm role="cp"><primary>color models</primary></indexterm>
+
+<para>A <firstterm>color model</firstterm> is a way of representing colors. &latex;&#8217;s
+capabilities depend on the printer driver. However, the <filename>pdftex</filename>,
+<filename>xetex</filename>, and <filename>luatex</filename> printer drivers are today by far the
+most commonly used. The models below work for those drivers. All but
+one of these is also supported by essentially all other printer drivers
+used today.
+</para>
+<para>Note that color combination can be additive or subtractive. Additive
+mixes colors of light, so that for instance combining full intensities
+of red, green, and blue produces white. Subtractive mixes pigments,
+such as with inks, so that combining full intensity of cyan, magenta,
+and yellow makes black.
+</para>
+<variablelist><anchor id="color-models-cmyk"/><varlistentry><term><literal>cmyk</literal>
+</term><listitem><para>A comma-separated list with four real numbers between 0 and 1,
+inclusive. The first number is the intensity of cyan, the second is
+magenta, and the others are yellow and black. A number value of 0 means
+minimal intensity, while a 1 is for full intensity. This model is often
+used in color printing. It is a subtractive model.
+</para>
+<anchor id="color-models-gray"/></listitem></varlistentry><varlistentry><term><literal>gray</literal>
+</term><listitem><para>A single real number between 0 and 1, inclusive. The colors are shades
+of grey. The number 0 produces black while 1 gives white.
+</para>
+<anchor id="color-models-rgb"/></listitem></varlistentry><varlistentry><term><literal>rgb</literal>
+</term><listitem><para>A comma-separated list with three real numbers between 0 and 1,
+inclusive. The first number is the intensity of the red component, the
+second is green, and the third the blue. A number value of 0 means that
+none of that component is added in, while a 1 means full intensity.
+This is an additive model.
+</para>
+<anchor id="color-models-RGB"/></listitem></varlistentry><varlistentry><term><literal>RGB</literal>
+</term><listitem><para>(<filename>pdftex</filename>, <filename>xetex</filename>, <filename>luatex</filename> drivers) A comma-separated
+list with three integers between 0 and 255, inclusive. This model is a
+convenience for using <literal>rgb</literal> since outside of &latex; colors are
+often described in a red-green-blue model using numbers in this range.
+The values entered here are converted to the <literal>rgb</literal> model by
+dividing by 255.
+</para>
+<anchor id="color-models-named"/></listitem></varlistentry><varlistentry><term><literal>named</literal>
+</term><listitem><para>Colors are accessed by name, such as &#8216;<literal>PrussianBlue</literal>&#8217;. The list of
+names depends on the driver, but all support the names &#8216;<literal>black</literal>&#8217;,
+&#8216;<literal>blue</literal>&#8217;, &#8216;<literal>cyan</literal>&#8217;, &#8216;<literal>green</literal>&#8217;, &#8216;<literal>magenta</literal>&#8217;, &#8216;<literal>red</literal>&#8217;,
+&#8216;<literal>white</literal>&#8217;, and &#8216;<literal>yellow</literal>&#8217; (See the <literal>dvipsnames</literal> option in
+<link linkend="Color-package-options">Color package options</link>).
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect1>
+<sect1 label="22.3" id="Commands-for-color">
+<title>Commands for color</title>
+
+<indexterm role="cp"><primary>color package commands</primary></indexterm>
+
+<para>These are the commands available with the <filename>color</filename> package.
+</para>
+
+
+<sect2 label="22.3.1" id="Define-colors">
+<title>Define colors</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>define color</primary></indexterm>
+<indexterm role="cp"><primary>color, define</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\definecolor{<replaceable>name</replaceable>}{<replaceable>model</replaceable>}{<replaceable>specification</replaceable>}
+</screen>
+<para>Give the name <replaceable>name</replaceable> to the color. For example, after this
+</para>
+<screen>\definecolor{silver}{rgb}{0.75,0.75,0.74}
+</screen>
+<para>you can use that color name with <literal>Hi ho,
+\textcolor{silver}{Silver}!</literal>.
+</para>
+<para>This example gives the color a more abstract name, so it could change and
+not be misleading.
+</para>
+<screen>\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex
+\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}}
+</screen>
+<para>Often a document&#8217;s colors are defined in the preamble, or in the class
+or style, rather than in the document body.
+</para>
+
+</sect2>
+<sect2 label="22.3.2" id="Colored-text">
+<title>Colored text</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored text</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\textcolor{<replaceable>name</replaceable>}{...}
+\textcolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}{...}
+</screen>
+<para>or
+</para>
+<screen>\color{<replaceable>name</replaceable>}
+\color[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}
+</screen>
+<para>The affected text gets the color. This line
+</para>
+<screen>\textcolor{magenta}{My name is Ozymandias, King of Kings;}
+Look on my works, ye Mighty, and despair!
+</screen>
+<para>causes the first half to be in magenta while the rest is in black. You
+can use a color declared with <literal>\definecolor</literal> in exactly the same
+way that we just used the builtin color &#8216;<literal>magenta</literal>&#8217;.
+</para>
+<screen>\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0}
+I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}.
+</screen>
+<para>The two <literal>\textcolor</literal> and <literal>\color</literal> differ in that the first is
+a command form, enclosing the text to be colored as an argument. Often
+this form is more convenient, or at least more explicit. The second
+form is a declaration, as in <literal>The moon is made of {\color{green}
+green} cheese</literal>, so it is in effect until the end of the current group
+or environment. This is sometimes useful when writing macros or as
+below where it colors everything inside the <literal>center</literal> environment,
+including the vertical and horizontal lines.
+</para>
+<screen>\begin{center} \color{blue}
+ \begin{tabular}{l|r}
+ UL &amp;UR \\ \hline
+ LL &amp;LR
+ \end{tabular}
+\end{center}
+</screen>
+<para>You can use color in equations. A document might have this definition
+in the preamble
+</para>
+<screen>\definecolor{highlightcolor}{RGB}{225,15,0}
+</screen>
+<para>and then contain this equation.
+</para>
+<screen>\begin{equation}
+ \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a)
+\end{equation}
+</screen>
+<para>Typically the colors used in a document are declared in a class or style
+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.
+</screen>
+<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>
+<screen>The selection was \textcolor[gray]{0.5}{grayed out}.
+</screen>
+<para>Colors inside colors do not combine. Thus
+</para>
+<screen>\textcolor{green}{kind of \textcolor{blue}{blue}}
+</screen>
+<para>has a final word that is blue, not a combination of blue and green.
+</para>
+<!-- xx address coloring a line of a table? -->
+
+
+</sect2>
+<sect2 label="22.3.3" id="Colored-boxes">
+<title>Colored boxes</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored boxes</primary></indexterm>
+<indexterm role="cp"><primary>box, colored</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\colorbox{<replaceable>name</replaceable>}{...}
+\colorbox[<replaceable>model name</replaceable>]{<replaceable>box background color</replaceable>}{...}
+</screen>
+<para>or
+</para>
+<screen>\fcolorbox{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...}
+\fcolorbox[<replaceable>model name</replaceable>]{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...}
+</screen>
+<para>Make a box with the stated background color. The <literal>\fcolorbox</literal>
+command puts a frame around the box. For instance this
+</para>
+<screen>Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}}
+</screen>
+<para>makes a cyan-colored box that is five centimeters long and gets its
+depth and height from the <literal>\strut</literal> (so the depth is
+<literal>-.3\baselineskip</literal> and the height is <literal>\baselineskip</literal>). This
+puts white text on a blue background.
+</para>
+<screen>\colorbox{blue}{\textcolor{white}{Welcome to the machine.}}
+</screen>
+<para>The <literal>\fcolorbox</literal> commands use the same parameters as <literal>\fbox</literal>
+(see <link linkend="_005cfbox-_0026-_005cframebox">\fbox &amp; \framebox</link>), <literal>\fboxrule</literal> and <literal>\fboxsep</literal>, to
+set the thickness of the rule and the boundary between the box interior
+and the surrounding rule. &latex;&#8217;s defaults are <literal>0.4pt</literal> and
+<literal>3pt</literal>, respectively.
+</para>
+<para>This example changes the thickness of the border to 0.8 points. Note
+that it is surrounded by curly braces so that the change ends at the end
+of the second line.
+</para>
+<screen>{\setlength{\fboxrule}{0.8pt}
+\fcolorbox{black}{red}{Under no circumstances turn this knob.}}
+</screen>
+
+</sect2>
+<sect2 label="22.3.4" id="Colored-pages">
+<title>Colored pages</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored page</primary></indexterm>
+<indexterm role="cp"><primary>page, colored</primary></indexterm>
+<indexterm role="cp"><primary>background, colored</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\pagecolor{<replaceable>name</replaceable>}
+\pagecolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}
+\nopagecolor
+</screen>
+<para>The first two set the background of the page, and all subsequent pages,
+to the color. For an explanation of the specification in the second
+form see <link linkend="Colored-text">Colored text</link>. The third returns the background to normal,
+which is a transparent background. (If that is not supported use
+<literal>\pagecolor{white}</literal>, although that will make a white background
+rather than the default transparent background.)
+</para>
+<screen> ...
+\pagecolor{cyan}
+ ...
+\nopagecolor
+</screen>
+
+</sect2>
+</sect1>
+</chapter>
<chapter label="23" id="Special-insertions">
<title>Special insertions</title>
@@ -16187,20 +16820,22 @@ special meaning do not correspond to simple characters you can type.
</para>
-<sect1 label="23.1" id="Reserved-characters">
-<title>Reserved characters</title>
+<sect1 label="23.1" id="Printing-special-characters">
+<title>Printing special characters</title>
-<indexterm role="cp"><primary>reserved characters</primary></indexterm>
-<indexterm role="cp"><primary>characters, reserved</primary></indexterm>
-<indexterm role="cp"><primary>special characters</primary></indexterm>
-<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>. They are
-all discussed elsewhere in this manual.
+<indexterm role="cp"><primary>reserved characters, printing</primary></indexterm>
+<indexterm role="cp"><primary>special characters, printing</primary></indexterm>
+<indexterm role="cp"><primary>printing special characters</primary></indexterm>
+<indexterm role="cp"><primary>escaping special characters</primary></indexterm>
+
+<para>&latex; sets aside a few characters for special purposes; they are
+called reserved characters or special characters. Here they are:
</para>
<screen># $ % &amp; { } _ ~ ^ \
</screen>
+<para>The meaning of all the special characters is given elsewhere
+in this manual (see <link linkend="Reserved-characters">Reserved characters</link>).
+</para>
<indexterm role="fn"><primary>\#</primary></indexterm>
<indexterm role="fn"><primary>\$</primary></indexterm>
<indexterm role="fn"><primary>\%</primary></indexterm>
@@ -16210,8 +16845,8 @@ all discussed elsewhere in this manual.
<indexterm role="fn"><primary>\}</primary></indexterm>
<para>If you want a reserved character to be printed as itself, in the text
body font, for all but the final three characters in that list simply
-put a backslash&#160;<literal>\</literal> in front of the character. Thus,
-typing <literal>\$1.23</literal> will produce&#160;<literal>$1.23</literal> in your output.
+put a <literal>\</literal> in front of the character. Thus, typing <literal>\$1.23</literal>
+will produce <literal>$1.23</literal> in your output.
</para>
<indexterm role="fn"><primary>\~</primary></indexterm>
<indexterm role="fn"><primary>\^</primary></indexterm>
@@ -16222,12 +16857,12 @@ 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> in the
-example is only there to split the lines in the output).
+<para>To produce the reserved characters in a typewriter font, use
+<literal>\verb!!</literal> as below (the <literal>\newline</literal> in the example is there
+only to split the lines in the output).
</para>
<screen>\begin{center}
- \# \$ \% \&amp; \{ \} \_ \~{} \^{} \textbackslash \\
+ \# \$ \% \&amp; \{ \} \_ \~{} \^{} \textbackslash \newline
\verb!# $ % &amp; { } _ ~ ^ \!
\end{center}
</screen>
@@ -16276,7 +16911,7 @@ you need to do expansion. Here the <literal>\Schoolname</literal> produces
</para>
<screen>\newcommand{\schoolname}{College of Mathematics}
\newcommand{\Schoolname}{\expandafter\MakeUppercase
- <!-- /@w -->\expandafter{\schoolname}}
+&amp;#160;<!-- /@w -->\expandafter{\schoolname}}
</screen>
<indexterm role="cp"><primary>package, <literal>textcase</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>textcase</literal> package</primary></indexterm>
@@ -16366,7 +17001,9 @@ the <literal>textcomp</literal> package for some (technically, those in the
<indexterm role="cp"><primary>logo, &latex;2e</primary></indexterm>
<para>The &latex;2e logo.
</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\guillemotleft (&#171;)</primary></indexterm><literal>\guillemotleft (&#171;)</literal>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\guillemetleft (&#171;)</primary></indexterm><literal>\guillemetleft (&#171;)</literal>
+</term><term><indexterm role="fn"><primary>\guillemetright (&#187;)</primary></indexterm><literal>\guillemetright (&#187;)</literal>
+</term><term><indexterm role="fn"><primary>\guillemotleft (&#171;)</primary></indexterm><literal>\guillemotleft (&#171;)</literal>
</term><term><indexterm role="fn"><primary>\guillemotright (&#187;)</primary></indexterm><literal>\guillemotright (&#187;)</literal>
</term><term><indexterm role="fn"><primary>\guilsinglleft (&#8249;)</primary></indexterm><literal>\guilsinglleft (&#8249;)</literal>
</term><term><indexterm role="fn"><primary>\guilsinglright (&#8250;)</primary></indexterm><literal>\guilsinglright (&#8250;)</literal>
@@ -16378,8 +17015,12 @@ the <literal>textcomp</literal> package for some (technically, those in the
<indexterm role="cp"><primary>single angle quotation marks</primary></indexterm>
<indexterm role="cp"><primary>French quotation marks</primary></indexterm>
<indexterm role="cp"><primary>quotation marks, French</primary></indexterm>
+<indexterm role="cp"><primary>guillemots, birds</primary></indexterm>
<para>&#171;, &#187;, &#8249;, &#8250;
Double and single angle quotation marks, commonly used in French.
+The commands <literal>@guillemotleft</literal> and <literal>@guillemotright</literal> are
+synonyms for <literal>@guillemet...</literal>; these are misspellings inherited
+from Adobe. (Guillemots are seabirds; guillemets are French quotes.)
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ldots</primary></indexterm><literal>\ldots</literal>
</term><term><indexterm role="fn"><primary>\textellipsis</primary></indexterm><literal>\textellipsis</literal>
@@ -16997,58 +17638,57 @@ font encoding, such as T1.
</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>Declare the input file&#8217;s text encoding to be <replaceable>encoding-name</replaceable>. (For
+basic background, see <link linkend="Input-encodings">Input encodings</link>). 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 &#8216;<literal>&#228;</literal>&#8217; 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>The <literal>inputenc</literal> package tells &latex; 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>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>, <literal>utf8</literal>.
+</para>
<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>.
+(see <link linkend="TeX-engines">&tex; engines</link>); with <command>xelatex</command> or
+<command>lualatex</command>, declaring a non-UTF-8 encoding with
+<literal>inputenc</literal>, such as <literal>latin1</literal>, 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.
+document that uses a different encoding than the input file. The
+simplest solution is often to replace the non-UTF-8 character with a
+UTF-8 or &latex; equivalent.
+</para>
+<indexterm role="cp"><primary>package, <literal>luainputenc</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>luainputenc</literal> package</primary></indexterm>
+
+<indexterm role="fn"><primary>\XeTeXinputencoding</primary></indexterm>
+<indexterm role="fn"><primary>\XeTeXdefaultencoding</primary></indexterm>
+<para>If you need to process a non-UTF-8 document with Lua&tex;, you can
+use the <literal>luainputenc</literal> package
+(<ulink url="https://ctan.org/pkg/luainputenc">https://ctan.org/pkg/luainputenc</ulink>). With Xe&tex;, the
+<literal>\XeTeXinputencoding</literal> and <literal>\XeTeXdefaultencoding</literal> primitives
+can be used (for an explanation and examples, see
+<ulink url="https://tex.stackexchange.com/questions/324948">https://tex.stackexchange.com/questions/324948</ulink>).
+</para>
+<indexterm role="pg"><primary>recode to change character encoding</primary></indexterm>
+<indexterm role="pg"><primary>iconv to change character encoding</primary></indexterm>
+<para>It&#8217;s also possible to re-encode a document from an 8-bit encoding to
+UTF-8 outside of &tex;, using system utilities. For example,
+&#8216;<literal>recode latin1..utf8</literal>&#8217; or &#8216;<literal>iconv -f latin1 -t utf8</literal>&#8217;.
</para>
<indexterm role="fn"><primary>\inputencoding</primary></indexterm>
-<anchor id="_005cinputencoding"/><para>In some documents, such as a collection of journal articles from a
+<anchor id="_005cinputencoding"/><para>In a few 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>.
+necessary. You can use the command
+<literal>\inputencoding{<replaceable>encoding-name</replaceable>}</literal> for this.
</para>
</sect1>
@@ -19519,18 +20159,18 @@ specified either as a separate argument (&#8216;<literal>--foo val</literal>&#82
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>
+<variablelist><varlistentry><term><indexterm role="fn"><primary>--version command-line option</primary></indexterm>
+<literal>-version</literal>
</term><listitem><para>Show the current version, like &#8216;<literal>pdfTeX 3.14159265-2.6-1.40.16 (TeX
Live 2015/Debian)</literal>&#8217; along with a small amount of additional information,
and exit.
</para>
-<indexterm role="fn"><primary>--help command-line option</primary></indexterm>
-</listitem></varlistentry><varlistentry><term><literal>-help</literal>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>--help command-line option</primary></indexterm>
+<literal>-help</literal>
</term><listitem><para>Give a brief usage message that is useful as a prompt and exit.
</para>
-<anchor id="interaction-modes"/><indexterm role="fn"><primary>--interaction command-line option</primary></indexterm>
-</listitem></varlistentry><varlistentry><term><literal>-interaction=<replaceable>mode</replaceable></literal>
+<anchor id="interaction-modes"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>--interaction command-line option</primary></indexterm>
+<literal>-interaction=<replaceable>mode</replaceable></literal>
</term><listitem><indexterm role="cp"><primary>batchmode</primary></indexterm>
<indexterm role="cp"><primary>scrollmode</primary></indexterm>
<indexterm role="cp"><primary>errorstopmode</primary></indexterm>
@@ -19552,17 +20192,17 @@ input, but nothing else.
</screen>
<para>eliminates most terminal output.
</para>
-<indexterm role="cp"><primary>jobname</primary></indexterm>
+</listitem></varlistentry><varlistentry><term><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>
+<literal>-jobname=<replaceable>string</replaceable></literal>
</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>. see <link linkend="Jobname">Jobname</link>.
</para>
-<anchor id="output-directory"/><indexterm role="cp"><primary>output directory for all external files</primary></indexterm>
+<anchor id="output-directory"/></listitem></varlistentry><varlistentry><term><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>
+<literal>-output-directory=<replaceable>directory</replaceable></literal>
</term><listitem><para>Write files in the directory <replaceable>directory</replaceable>. It must already exist.
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>,
@@ -19575,13 +20215,13 @@ 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>
+</listitem></varlistentry><varlistentry><term><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>
<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>
+<literal>--enable-write18</literal>
</term><term><literal>--disable-write18</literal>
</term><term><literal>--shell-escape</literal>
</term><term><literal>--no-shell-escape</literal>
@@ -19601,13 +20241,13 @@ a limited number of &tex;-related programs, which they distribute.)
<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>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>--halt-on-error command-line option</primary></indexterm>
+<literal>-halt-on-error</literal>
</term><listitem><para>Stop processing at the first error.
</para>
-<indexterm role="fn"><primary>--file-line-error command-line option</primary></indexterm>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>--file-line-error command-line option</primary></indexterm>
<indexterm role="fn"><primary>--no-file-line-error command-line option</primary></indexterm>
-</listitem></varlistentry><varlistentry><term><literal>-file-line-error</literal>
+<literal>-file-line-error</literal>
</term></varlistentry><varlistentry><term><literal>-no-file-line-error</literal>
</term><listitem><para>Enable or disable <literal><replaceable>filename</replaceable>:<replaceable>lineno</replaceable>:<replaceable>error</replaceable></literal>-style
error messages. These are only available with &tex; Live or Mac&tex;.
@@ -19664,7 +20304,7 @@ 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. (see <link linkend="Jobname">Jobname</link>.)
+first (see <link linkend="Jobname">Jobname</link>).
</para>
<para>In this example we use the command line to select which parts of a
document to include. For a book named <filename>mybook.tex</filename> and structured
@@ -19706,19 +20346,20 @@ 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. This file is referred to as the <firstterm>root
-file</firstterm> (see <link linkend="Splitting-the-input">Splitting the input</link>, and&#160;<link linkend="_005cinput">\input</link>). The name of
-that root file, without the <filename>.tex</filename> extension if any, 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>.
+<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. This file is referred
+to as the <firstterm>root file</firstterm> (see <link linkend="Splitting-the-input">Splitting the input</link>, and
+<link linkend="_005cinput">\input</link>). The name of that root file, without the <filename>.tex</filename>
+extension if any, 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).
+-jobname=myname</literal> (see <link linkend="Command-line-input">Command line input</link> for a practical example).
</para>
<indexterm role="fn"><primary>texput, jobname default</primary></indexterm>
<indexterm role="cp"><primary>fallback jobname</primary></indexterm>