summaryrefslogtreecommitdiff
path: root/info/latex2e-help-texinfo/latex2e.texi
diff options
context:
space:
mode:
Diffstat (limited to 'info/latex2e-help-texinfo/latex2e.texi')
-rw-r--r--info/latex2e-help-texinfo/latex2e.texi5188
1 files changed, 3918 insertions, 1270 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.texi b/info/latex2e-help-texinfo/latex2e.texi
index d4f0726deb..aec0978aa8 100644
--- a/info/latex2e-help-texinfo/latex2e.texi
+++ b/info/latex2e-help-texinfo/latex2e.texi
@@ -1,8 +1,8 @@
\input texinfo
-@c $Id: latex2e.texi 710 2018-10-14 14:32:52Z karl $
+@c $Id: latex2e.texi 935 2021-07-23 17:48:15Z jimhefferon $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename latex2e.info
-@set UPDATED October 2018
+@set UPDATED July 2021
@include common.texi
@settitle @LaTeX{}2e unofficial reference manual (@value{UPDATED})
@comment %**end of header (This is for running Texinfo on a region.)
@@ -10,31 +10,29 @@
@c latex 2.09 commands should all be present now,
@c xx but latex2e stuff is missing.
@c xx random list of a few of the missing items is at the end of this file
+@c xx read through latex2e news for things to update.
@c
@c xx ctan, distributions, components of TeX
-@c xx classes and packages -- required, additional, useful; oberdiek; fonts
-@c
+@c xx classes and packages: required, additional, useful; oberdiek; fonts
@c xx merge permuted-index
@c xx merge latex-manual from savannah
@c xx merge display style math
+@c xx check recent ltnews for (lots of) changes
+@c xx \write of non-ASCII chars (vincent mail of 14 Mar 2020 21:39:41)
+@c xx \nonstopmode etc., if they are officially supported by LaTeX?
@c xx JH explain nfss somewhere
@c xx JH expand BiBTeX
@c xx JH expand theorem, AMS math
@c xx JH something on code listings
@c xx JH ligatures
-@c xx JH \xspace
-@c xx JH \stretch
-@c xx JH \mathstrut
-@c xx JH \phantom https://tex.stackexchange.com/questions/4519/how-do-i-create-an-invisible-character
-@c xx JH \baselineskip https://texfaq.org/FAQ-baselinepar
-@c xx JH \contentsline, \@@dottedtocline?
-@c xx JH more on \write18, beyond what's mentioned in Command line.
-@c xx JH \numexpr, \dimexpr, \glueexpr, \muexpr
+@c xx JH \caption
@c
@c xx The typeset source2e has an index with all kernel
@c xx commands, though some are internal and shouldn't be included.
@c xx classes.dtx et al. define additional commands.
@c xx See also http://ctan.org/pkg/macros2e.
+@c
+@c xx All the special characters should be definitively described.
@copying
This document is an unofficial reference manual for @LaTeX{}, a
@@ -55,7 +53,7 @@ latex2e-reference by Martin Herbert Dietze. (From these references no
text was directly copied.)
Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
-2014, 2015, 2016, 2017, 2018 Karl Berry.@*
+2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Karl Berry.@*
Copyright 1988, 1994, 2007 Stephen Gilmore.@*
Copyright 1994, 1995, 1996 Torsten Martinsen.
@@ -93,6 +91,32 @@ into another language, under the above conditions for modified versions.
\global\hbadness=4444 % don't complain much
@end tex
+@html
+<div class='intro'> <p>This is an unofficial reference manual for
+LaTeX. See below for the <a href='#SEC_Overview'>Table of Contents</a>.
+If you want a tutorial then please instead visit <a
+href="https://www.learnlatex.org/"><code>learnlatex.org</code></a> or <a
+href='https://ctan.org/topic/tut-latex'>this list</a>.</p>
+
+<p>This manual has two versions. One has <a
+href="https://latexref.xyz/">separate web pages for each section or
+subsection</a>. It's also available as a <a
+href="https://latexref.xyz/dev/latex2e.html">single web page</a> and
+as a <a href="https://latexref.xyz/dev/latex2e.pdf">pdf</a>.</p>
+
+<p> This document is not official. It has not been reviewed by the
+LaTeX maintainers. Our goal is to cover all (non-private) LaTeX
+commands. Your comments and contributions, including bug reports, are
+very welcome. See <a href='https://latexref.xyz/dev/'>our project
+page</a> for more, including <a
+href='https://latexref.xyz/dev/#license'>license information</a> and
+information on how you can
+<a href='https://latexref.xyz/dev/writing.html'>contribute to this manual</a>
+as well as
+<a href='https://latexref.xyz/dev/mirroring.html'>mirror it</a>.</p>
+<!-- End of opening header -->
+@end html
+
@titlepage
@title @LaTeX{}2e: An unofficial reference manual
@subtitle @value{UPDATED}
@@ -137,11 +161,13 @@ into another language, under the above conditions for modified versions.
@set NeedsAMSSymb @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{amssymb} package.
@set NeedsSTIX @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{stix} package.
+@ifnottex
@node Top
@top @LaTeX{}2e: An unofficial reference manual
This document is an unofficial reference manual (version of
@value{UPDATED}) for @LaTeX{}2e, a document preparation system.
+@end ifnottex
@menu
* About this document:: Bug reporting, etc.
@@ -170,13 +196,12 @@ This document is an unofficial reference manual (version of
* Splitting the input:: Dealing with big files by splitting.
* Front/back matter:: Tables of contents, glossaries, indexes.
* Letters:: The @code{letter} class.
-* Terminal input/output:: User interaction.
-* Command line:: System-independent command-line behavior.
+* Input/output:: User interaction.
+* Command line interface:: Common command-line options.
* Document templates:: Starter templates for various document classes.
* Index:: General index.
@end menu
-
@node About this document
@chapter About this document
@@ -185,15 +210,11 @@ This is an unofficial reference manual for the @LaTeX{}2e document
preparation system, which is a macro package for the @TeX{}
typesetting program (@pxref{Overview}).
-This document's home page is @url{@value{LTXREFMAN_HOME_PAGE}}. There
-you can get the sources, subscribe to the mailing list or read its
-archives, see other infrastructure, and get the current output in
-various formats. In particular, the output comes in two web formats.
-Probably the most convenient one, shown at @url{http://latexref.xyz/},
-has pages for each topic and so is good for a quick lookup; see also the
-note there about easy-to-remember links. The other, shown at
-@url{http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co},
-has all the information on single page.
+This document's home page is @url{@value{LTXREFMAN_HOME_PAGE}}; it has
+separate web pages for each topic. Alternatively.
+@url{https://latexref.xyz/dev/latex2e.html} has the entire document on
+a single page. For other output formats, the sources, and plenty more
+information, see @url{https://latexref.xyz/dev/}.
@cindex @LaTeX{} vs.@: @LaTeX{}2e
In this document, we will mostly just use `@LaTeX{}' rather than
@@ -203,40 +224,34 @@ frozen decades ago.
@cindex unofficial nature of this manual
@cindex @LaTeX{} Project team
@findex @email{@value{LTXREFMAN_BUGS}} @r{email address}
-@LaTeX{} is currently maintained by a group of volunteers
-(@url{http://latex-project.org}). The official documentation written by
-the @LaTeX{} project is available from their web site. This document is
-completely unofficial and has not been reviewed by the @LaTeX{}
-maintainers.
+@LaTeX{} is maintained by a group of volunteers
+(@url{https://latex-project.org}). The official documentation written
+by the @LaTeX{} project is available from their web site. The present
+document is completely unofficial and has not been written or reviewed
+by the @LaTeX{} maintainers.
@cindex bug reporting
@cindex reporting bugs
Do not send bug reports or anything else about this document to them.
Instead, please send all comments to @email{@value{LTXREFMAN_BUGS}}.
-This document is a reference. There is a vast array of other sources
-of information about @LaTeX{}, at all levels. Here are a few
-introductions.
+This document is a reference, not a tutorial. There is a vast array
+of other information available about @LaTeX{}, at all levels. Here
+are a few introductions.
@table @url
-@item http://ctan.org/pkg/latex-doc-ptr
+@item https://ctan.org/pkg/latex-doc-ptr
@findex latex-doc-ptr @r{document}
Two pages of recommended references to @LaTeX{} documentation.
-@item http://ctan.org/pkg/first-latex-doc
+@item https://ctan.org/pkg/first-latex-doc
@findex first-latex-doc @r{document}
Writing your first document, with a bit of both text and math.
-@item http://ctan.org/pkg/usrguide
-@findex usrguide @r{official documentation}
-The guide for document authors that is maintained as part of @LaTeX{}.
-Many other guides by many other people are also available, independent
-of @LaTeX{} itself; one such is the next item:
-
-@item http://ctan.org/pkg/lshort
+@item https://ctan.org/pkg/lshort
@findex lshort @r{document}
-A short introduction to @LaTeX{}, translated to many languages.
+A longer introduction to @LaTeX{}, translated to many languages.
-@item http://tug.org/begin.html
+@item https://tug.org/begin.html
Introduction to the @TeX{} system, including @LaTeX{}, with further
references.
@@ -253,21 +268,25 @@ references.
@cindex @LaTeX{} overview
@LaTeX{} is a system for typesetting documents. It was originally
-created by Leslie Lamport and is now maintained by a group of volunteers
-(@url{http://latex-project.org}). It is widely used, particularly for
-complex and technical documents, such as those involving mathematics.
-
-@cindex macro package, @LaTeX{} as
-A @LaTeX{} user writes an input file containing text along with
-interspersed commands, for instance commands describing how the text
-should be formatted. It is implemented as a set of related commands
-that interface with Donald@tie{}E. Knuth's @TeX{} typesetting program
-(the technical term is that @LaTeX{} is a @dfn{macro package} for the
-@TeX{} engine). The user produces the output document by giving that
-input file to the @TeX{} engine.
+created by Leslie Lamport in 1984, but has been maintained by a group
+of volunteers for many years now (@url{https://latex-project.org}).
+It is widely used, particularly but not exclusively for mathematical
+and technical documents.
+
+@cindex UTF-8, default @LaTeX{} input encoding
+A @LaTeX{} user writes an input file containing text to be typeset
+along with interspersed commands. The default encoding for the text is
+UTF-8 (as of 2018). The commands specify, for example, how the text
+should be formatted.
+
+@LaTeX{} is implemented as a set of related so-called ``macros'' which
+use Donald@tie{}E. Knuth's @TeX{} typesetting program or one of its
+derivatives, collectively known as ``engines''. 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.)
The term @LaTeX{} is also sometimes used to mean the language in which
-the document is marked up, that is, to mean the set of commands
+the input document is marked up, that is, to mean the set of commands
available to a @LaTeX{} user.
@cindex Lamport @TeX{}
@@ -280,9 +299,9 @@ sensible, such as in plain text, write it as @samp{LaTeX}.
@menu
* Starting and ending:: The standard beginning and end of a document.
* Output files:: Files produced.
-* @TeX{} engines:: Programs that can compile @TeX{} and @LaTeX{}.
+* @TeX{} engines:: Programs that can compile @TeX{} and @LaTeX{}.
* @LaTeX{} command syntax:: General syntax of @LaTeX{} commands.
-* Environment:: Area of the source giving distinct behavior.
+* Environment:: An area of the source with distinct behavior.
* CTAN:: Our repository.
@end menu
@@ -355,7 +374,7 @@ it to a PostScript @code{.ps} file with @command{dvips} or to a
Portable Document Format @code{.pdf} file with @command{dvipdfmx}.
The contents of the file can be dumped in human-readable form with
@command{dvitype}. A vast array of other DVI utility programs are
-available (@url{http://mirror.ctan.org/dviware}).
+available (@url{https://mirror.ctan.org/dviware}).
@item .pdf
@findex .pdf @r{file}
@@ -369,7 +388,7 @@ self-contained file, with all fonts and images included.
@end table
-@LaTeX{} also produces at least two additional files.
+@LaTeX{} always produces at least two additional files.
@table @code
@item .log
@@ -421,30 +440,38 @@ open-ended.
@cindex engines, @TeX{}
@cindex implementations of @TeX{}
-@cindex UTF-8
+@cindex UTF-8, engine support for
@cindex Unicode input, native
@cindex TrueType fonts
@cindex OpenType fonts
-@LaTeX{} is defined to be a set of commands that are run by a @TeX{}
-implementation (@pxref{Overview}). This section gives a terse
-overview of the main programs (see also@tie{}@ref{Command line}).
+@cindex @TeX{} format (@code{.fmt}) files
+@cindex @LaTeX{} format (@code{.fmt}) files
+@cindex format files, @TeX{}
+@findex .fmt @r{file}
+@LaTeX{} is a large set of commands that is executed by a @TeX{}
+program (@pxref{Overview}). Such a set of commands is called a
+@dfn{format}, and is embodied in a binary @code{.fmt} file, which can
+be read much more quickly than the corresponding @TeX{} source.
-@table @code
+This section gives a terse overview of the @TeX{} programs that are
+commonly available (see also @ref{Command line interface}).
+
+@ftable @code
@item latex
@itemx pdflatex
-@cindex pdf@TeX{} engine
@findex etex @r{command}
+@cindex pdf@TeX{} engine
@cindex e-@TeX{}
@anchor{tex engines latex}
-In @TeX{} Live (@url{http://tug.org/texlive}), if @LaTeX{} is invoked
+In @TeX{} Live (@url{https://tug.org/texlive}), if @LaTeX{} is invoked
via either the system command @command{latex} or @command{pdflatex},
-then the pdf@TeX{} engine is run (@url{http://ctan.org/pkg/pdftex}).
+then the pdf@TeX{} engine is run (@url{https://ctan.org/pkg/pdftex}).
When invoked as @command{latex}, the main output is a @file{.dvi}
file; as @command{pdflatex}, the main output is a @file{.pdf} file.
pdf@TeX{} incorporates the e-@TeX{} extensions to Knuth's original
-program (@url{http://ctan.org/pkg/etex}), including additional
+program (@url{https://ctan.org/pkg/etex}), including additional
programming features and bi-directional typesetting, and has plenty of
extensions of its own. e-@TeX{} is available on its own as the system
command @command{etex}, but this is plain @TeX{} (and produces
@@ -455,26 +482,23 @@ rather than pdf@TeX{}. In any case, the e-@TeX{} extensions can be
assumed to be available in @LaTeX{}.
@item lualatex
-@findex lualatex @r{command}
@cindex Lua@TeX{}
@anchor{tex engines lualatex}
If @LaTeX{} is invoked via the system command @command{lualatex}, the
-Lua@TeX{} engine is run (@url{http://ctan.org/pkg/luatex}). This
+Lua@TeX{} engine is run (@url{https://ctan.org/pkg/luatex}). This
program allows code written in the scripting language Lua
(@url{http://luatex.org}) to interact with @TeX{}'s typesetting.
Lua@TeX{} handles UTF-8 Unicode input natively, can handle OpenType
and TrueType fonts, and produces a @file{.pdf} file by default.
-There is also @command{dvilualatex} to produce a @file{.dvi} file,
-but this is rarely used.
+There is also @command{dvilualatex} to produce a @file{.dvi} file.
@item xelatex
-@findex xelatex @r{command}
@cindex Xe@TeX{}
@findex .xdv @r{file}
@findex xdvipdfmx
@anchor{tex engines xelatex}
If @LaTeX{} is invoked with the system command @command{xelatex}, the
-Xe@TeX{} engine is run (@url{http://tug.org/xetex}). Like Lua@TeX{},
+Xe@TeX{} engine is run (@url{https://tug.org/xetex}). Like Lua@TeX{},
Xe@TeX{} natively supports UTF-8 Unicode and TrueType and OpenType
fonts, though the implementation is completely different, mainly using
external libraries instead of internal code. Xe@TeX{} produces a
@@ -485,12 +509,46 @@ and translates that to PDF using the (@code{x})@code{dvipdfmx}
program, but this process is automatic. The @code{.xdv} file is only
useful for debugging.
-@end table
+@item platex
+@itemx uplatex
+These commands provide significant additional support for Japanese and
+other languages; the @code{u} variant supports Unicode. See
+@url{https://ctan.org/pkg/ptex} and @url{https://ctan.org/pkg/uptex}.
+@end ftable
-Other variants of @LaTeX{} and @TeX{} exist, e.g., to provide
-additional support for Japanese and other languages ([u]p@TeX{},
-@url{http://ctan.org/pkg/ptex}, @url{http://ctan.org/pkg/uptex}).
+As of 2019, there is a companion @code{-dev} command and format for
+all of the above:
+
+@ftable @code
+@item dvilualatex-dev
+@itemx latex-dev
+@itemx lualatex-dev
+@itemx pdflatex-dev
+@itemx platex-dev
+@itemx uplatex-dev
+@itemx xelatex-dev
+@cindex release candidates
+@cindex prerelease testing
+These are candidates for an upcoming @LaTeX{} release. The main
+purpose is to find and address compatibility problems before an
+official release.
+
+These @code{-dev} formats make it easy for anyone to help test
+documents and code: you can run, say, @code{pdflatex-dev} instead of
+@code{pdflatex}, without changing anything else in your environment.
+Indeed, it is easiest and most helpful to always run the @code{-dev}
+versions instead of bothering to switch back and forth. During quiet
+times after a release, the commands will be equivalent.
+
+These are not daily snapshots or untested development code. They
+undergo the same extensive regression testing by the @LaTeX{} team
+before being released.
+
+For more information, see ``The @LaTeX{} release workflow and the
+@LaTeX{} @code{dev} formats'' by Frank Mittelbach, @cite{TUGboat} 40:2,
+@url{https://tug.org/TUGboat/tb40-2/tb125mitt-dev.pdf}.
+@end ftable
@node @LaTeX{} command syntax
@section @LaTeX{} command syntax
@@ -505,7 +563,7 @@ character, @code{\}. The name itself then consists of either
@LaTeX{} commands names are case sensitive so that @code{\pagebreak}
differs from @code{\Pagebreak} (the latter is not a standard command).
-Most commands are lowercase, but in any event you must enter all
+Most command names are lowercase, but in any event you must enter all
commands in the same case as they are defined.
A command may be followed by zero, one, or more arguments. These
@@ -522,12 +580,6 @@ argument comes last, with no required argument after it, then to make
the first character of the following text be an open square bracket,
hide it inside curly braces.
-Some of @LaTeX{}'s commands are a @dfn{declaration}. Such a command
-changes the value the meaning of some other command or parameter. For
-instance, the @code{\mainmatter} declaration changes the typesetting of
-page numbers from roman numerals to arabic (@pxref{\frontmatter &
-\mainmatter & \backmatter}).
-
@LaTeX{} has the convention that some commands have a @code{*} form that
is related to the form without a @code{*}, such as @code{\chapter} and
@code{\chapter*}. The exact difference in behavior varies from command
@@ -536,6 +588,14 @@ to command.
This manual describes all accepted options and @code{*}-forms for the
commands it covers (barring unintentional omissions, a.k.a.@: bugs).
+@PkgIndex{expl3}
+@PkgIndex{xparse}
+@cindex @LaTeX{}3 syntax
+As of the 2020-10-01 release of @LaTeX{}, the @code{expl3} and
+@code{xparse} packages are part of the @LaTeX{}2e format. They
+provide a completely different underlying programming language
+syntax. We won't try to cover them in this document; see the related
+package documentation and other @LaTeX{} manuals.
@node Environment
@section Environment
@@ -543,14 +603,14 @@ commands it covers (barring unintentional omissions, a.k.a.@: bugs).
Synopsis:
@example
-\begin@{@var{environment name}@}
+\begin@{@var{environment-name}@}
...
-\end@{@var{environment name}@}
+\end@{@var{environment-name}@}
@end example
-An area of @LaTeX{} source, inside of which there is a distinct
-behavior. For instance, for poetry in @LaTeX{} put the lines between
-@code{\begin@{verse@}} and @code{\end@{verse@}}.
+An @dfn{environment} is an area of @LaTeX{} source, inside of which
+there is a distinct behavior. For instance, for poetry in @LaTeX{}
+put the lines between @code{\begin@{verse@}} and @code{\end@{verse@}}.
@example
\begin@{verse@}
@@ -559,12 +619,12 @@ behavior. For instance, for poetry in @LaTeX{} put the lines between
\end@{verse@}
@end example
-@xref{Environments} for a list of environments. Particularly notable is
+@xref{Environments}, for a list of environments. Particularly notable is
that every @LaTeX{} document must have a @code{document} environment,
a @code{\begin@{document@} ... \end@{document@}} pair.
-The @var{environment name} at the beginning must exactly match that at
-the end. This includes the case where @var{environment name} ends in a
+The @var{environment-name} at the beginning must exactly match that at
+the end. This includes the case where @var{environment-name} ends in a
star@tie{}(@code{*}); both the @code{\begin} and @code{\end} texts must
include the star.
@@ -581,7 +641,7 @@ required (it specifies the formatting of columns).
@node CTAN
-@section CTAN: the Comprehensive @TeX{} Archive Network
+@section CTAN: The Comprehensive @TeX{} Archive Network
@cindex CTAN
@@ -596,20 +656,22 @@ person or a small number of people. For instance, many publishers have
a package that allows authors to format papers to that publisher's
specifications.
-In addition to the massive holdings, the web site offers features such
-as search by name or by functionality.
+In addition to the massive holdings, the @code{ctan.org} web site
+offers features such as search by name or by functionality.
@cindex DANTE e.V.
+CTAN is not a single host, but instead is a set of hosts, one of which
+is the so-called ``master''. The master host actively manages the
+material, for instance, by accepting uploads of new or updated
+packages. For many years, it has been hosted by the German @TeX{}
+group, DANTE e.V.
+
@cindex mirrors of CTAN
-CTAN is not a single site, but instead is a set of sites. One of the
-sites is the core. This site actively manages the material, for
-instance, by accepting uploads of new or updated packages. It is
-hosted by the German @TeX{} group DANTE e.V. Other sites around the
-world help out by mirroring, that is, automatically syncing their
-collections with the core site and then in turn making their copies
-publicly available. This gives users close to their location better
-access and relieves the load on the core site. The list of mirrors is
-at @url{https://ctan.org/mirrors}.
+Other sites around the world help out by mirroring, that is,
+automatically syncing their collections with the master site and then
+in turn making their copies publicly available. This gives users close
+to their location better access and relieves the load on the master
+site. The list of mirrors is at @url{https://ctan.org/mirrors}.
@node Document classes
@@ -658,9 +720,10 @@ such as technical reports or theses, which may contain several chapters.
@item slides
@anchor{document classes slides}
-For slide presentations---rarely used today. In its place the
-@code{beamer} package is perhaps the most prevalent (@pxref{beamer
-template}).
+For slide presentations---rarely used nowadays. The
+@code{beamer} package is perhaps the most prevalent
+(@url{https://ctan.org/pkg/beamer}). @xref{beamer template}, for a
+small template for a beamer document.
@end table
@@ -806,6 +869,7 @@ Typeset in one or two columns; default is @code{onecolumn}.
@itemx twoside
@findex \evensidemargin
@findex \oddsidemargin
+@c xx TODO re-align on the French version which is more accurate.
Selects one- or two-sided layout; default is @code{oneside}, except
that in the @code{book} class the default is @code{twoside}.
@@ -927,9 +991,9 @@ declare @code{\documentclass[11pt]@{article@}} to set the default
document font size.
@item
-Finally, in the @dfn{more declarations part} the class or package usually does
-most of its work: declaring new variables, commands and fonts, and
-loading other files.
+Finally, in the @dfn{more declarations part} the class or package
+usually does most of its work: declaring new variables, commands and
+fonts, and loading other files.
@end enumerate
Here is a starting class file, which should be saved as @file{stub.cls}
@@ -952,7 +1016,7 @@ passing them all to the @code{article} class, and then loads the
For more, see the official guide for class and package writers, the
Class Guide, at
-@url{http://www.latex-project.org/help/documentation/clsguide.pdf} (much
+@url{https://www.latex-project.org/help/documentation/clsguide.pdf} (much
of the descriptions here derive from this document), or the tutorial
@url{https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf}.
@@ -1056,10 +1120,10 @@ must contain @code{\DeclareOption@{logo@}@{@var{code}@}} (and later,
@code{\ProcessOptions}).
If you request an option that has not been declared, by default this
-will produce a warning like @code{Unused global option(s): [badoption].}
-Change this behaviour with the starred version
-@code{\DeclareOption*@{@var{code}@}}. For example, many classes extend
-an existing class, using a declaration such as
+will produce a warning like @code{Unused global option(s):
+[badoption].} Change this behavior with the starred version
+@code{\DeclareOption*@{@var{code}@}}. For example, many classes
+extend an existing class, using a command such as
@code{\LoadClass@{article@}}, and for passing extra options to the
underlying class use code such as this.
@@ -1120,8 +1184,8 @@ commands, so they do not just make a log message when you redefine
@end enumerate
-@item \IfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@}
-@item \InputIfFileExists@{@var{file name}@}@{@var{true code}@}@{@var{false code}@}
+@item \IfFileExists@{@var{filename}@}@{@var{true code}@}@{@var{false code}@}
+@item \InputIfFileExists@{@var{filename}@}@{@var{true code}@}@{@var{false code}@}
@findex \IfFileExists
@findex \InputIfFileExists
Execute @var{true code} if @LaTeX{} finds the file @file{@var{file
@@ -1342,12 +1406,12 @@ with certain features by specifying that it must be released no earlier
than the given date. (Although, in practice package users only rarely
include a date, and class users almost never do.)
-@item \ProvidesFile@{@var{file name}@}[@var{additional information}]
+@item \ProvidesFile@{@var{filename}@}[@var{additional information}]
@findex \ProvidesFile
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 @code{File: test.config
-2017/10/12 config file for test.cls} for @var{file name} equal to
+2017/10/12 config file for test.cls} for @var{filename} equal to
@samp{test.config} and @var{additional information} equal to
@samp{2017/10/12 config file for test.cls}.
@@ -1390,16 +1454,613 @@ causes @LaTeX{} to give error like @code{\usepackage before
@cindex typefaces
@cindex fonts
-Two important aspects of selecting a @dfn{font} are specifying a size
-and a style. The @LaTeX{} commands for doing this are described here.
+@LaTeX{} comes with powerful font capacities. For one thing, its New
+Font Selection Scheme allows you to work easily with the font families
+in your document (for instance, see@tie{}@ref{Font styles}). And,
+@LaTeX{} documents can use most fonts that are available today,
+including versions of Times Roman, Helvetica, Courier, etc. (Note,
+though, that many fonts do not have support for mathematics.)
+
+The first typeface in the @TeX{} world was the Computer Modern family,
+developed by Donald Knuth. It is the default for @LaTeX{} documents and
+is still the most widely used. But changing to another font often only
+involves a few commands. For instance, putting the following in your
+preamble gives you a Palatino-like font, which is handsome and more
+readable online than many other fonts, while still allowing you to
+typeset mathematics. (This example is from Michael Sharpe,
+@url{https://math.ucsd.edu/~msharpe/RcntFnts.pdf}.)
+
+@example
+\usepackage[osf]@{newpxtext@} % osf for text, not math
+\usepackage@{cabin@} % sans serif
+\usepackage[varqu,varl]@{inconsolata@} % sans serif typewriter
+\usepackage[bigdelims,vvarbb]@{newpxmath@} % bb from STIX
+\usepackage[cal=boondoxo]@{mathalfa@} % mathcal
+@end example
+
+@noindent
+In addition, the @command{xelatex} or @command{lualatex} engines allow
+you to use any fonts on your system that are in OpenType or TrueType
+format (@pxref{@TeX{} engines}).
+
+The @LaTeX{} Font Catalogue (@url{https://tug.org/FontCatalogue}) shows
+font sample graphics and copy-and-pasteable source to use many fonts,
+including many with support for mathematics. It aims to cover all Latin
+alphabet free fonts available for easy use with @LaTeX{}.
+
+More information is also available from the @TeX{} Users Group, at
+@url{https://www.tug.org/fonts/}.
@menu
+* fontenc package:: Encoding of the font.
* Font styles:: Select roman, italics, etc.
* Font sizes:: Select point size.
* Low-level font commands:: Select encoding, family, series, shape.
@end menu
+@node fontenc package
+@section @code{fontenc} package
+
+@cindex font encoding
+@cindex UTF-8, font support for
+@cindex T1
+@cindex OT1
+@findex fontenc
+
+Synopsis:
+
+@example
+\usepackage[@var{font_encoding}]@{fontenc@}
+@end example
+
+or
+
+@example
+\usepackage[@var{font_encoding1}, @var{font_encoding2}, ...]@{fontenc@}
+@end example
+
+Specify the font encodings. A font encoding is a mapping of the
+character codes to the font glyphs that are used to typeset your output.
+
+This package only applies if you use the @code{pdflatex} engine
+(@pxref{@TeX{} engines}). If you use the @command{xelatex} or
+@command{lualatex} engine then instead use the @file{fontspec} package.
+
+@TeX{}'s original font family, Computer Modern, has a limited character
+set. For instance, to make common accented characters you must use
+@code{\accent} (@pxref{\accent}) but this disables hyphenation. @TeX{}
+users have agreed on a number of standards to access the larger sets of
+characters provided by modern fonts. If you are using
+@command{pdflatex} then this in the preamble
+
+@example
+\usepackage[T1]@{fontenc@}
+@end example
+
+@noindent
+gives you support for the most widespread European languages, including
+French, German, Italian, Polish, and others. In particular, if you have
+words with accented letters then @LaTeX{} will hyphenate them and your
+output can be copied and pasted. (The optional second line allows you
+to directly enter accented characters into your source file.)
+
+@PkgIndex{lmodern} @PkgIndex{cm-super}
+If you are using an encoding such as @code{T1} and the characters appear
+blurry or do not magnify well then your fonts may be bitmapped,
+sometimes called raster or Type@tie{}3. You want vector fonts. Use a
+package such as @file{lmodern} or @file{cm-super} to get a font that
+extends @LaTeX{}'s default using vector fonts.
+
+For each @var{font_encoding} given as an option but not already
+declared, this package loads the encoding definition files, named
+@file{@var{font_encoding}enc.def}. It also sets @code{\encodingdefault}
+to be the last encoding in the option list.
+
+These are the common values for @var{font_encoding}.
+
+@table @code
+@item OT1
+The original encoding for @TeX{}. Limited to mostly English characters.
+
+@item OMS, OML
+Math symbols and math letters encoding.
+
+@item T1
+@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.
+
+@item TS1
+Text Companion encoding.
+@end table
+
+@noindent
+@LaTeX{}'s default is to load @code{OML}, @code{T1}, @code{OT1}, and
+then @code{OMS}, and set the default to @code{OT1}.
+
+Even if you do not use accented letters, you may need to specify a font
+encoding if your font requires it.
+
+If you use @code{T1}@tie{}encoded fonts other than the default Computer
+Modern family then you may need to load the package that selects your
+fonts before loading @file{fontenc}, to prevent the system from loading
+any @code{T1}@tie{}encoded fonts from the default.
+
+The @LaTeX{} team reserve encoding names starting with: @samp{T} for the
+standard text encodings with 256 characters, @samp{TS} for symbols that
+extend the corresponding T encodings, @samp{X} for test encodings,
+@samp{M} for standard math encodings with 256 characters, @samp{A} for
+special applications, @samp{OT} for standard text encodings with 128
+characters, and @samp{OM} for standard math encodings with 128
+characters (@samp{O} stands for @samp{obsolete}).
+
+This package provides a number of commands, detailed below. Many of
+them are encoding-specific, so if you have defined a command that works
+for one encoding but the current encoding is different then the command
+is not in effect.
+
+@menu
+* \DeclareFontEncoding:: Define an encoding.
+* \DeclareTextAccent:: Define an accent in the encoding.
+* \DeclareTextAccentDefault:: Fallback for using an accent in the encoding.
+* \DeclareTextCommand & \ProvideTextCommand:: New encoding-specific command.
+* \DeclareTextCommandDefault & \ProvideTextCommandDefault:: Fallback for encoding-specific commands.
+* \DeclareTextComposite:: Directly access an accented glyph, in the encoding.
+* \DeclareTextCompositeCommand:: Run code in slot, in the encoding.
+* \DeclareTextSymbol:: Define a symbol in the encoding.
+* \DeclareTextSymbolDefault:: Fallback for a symbol in the encoding.
+* \LastDeclaredEncoding:: Save most recently declared encoding.
+* \UseTextSymbol & \UseTextAccent:: Temporarily switch to another encoding.
+@end menu
+
+
+@node \DeclareFontEncoding
+@subsection @code{\DeclareFontEncoding}
+
+@cindex font encoding, declaring
+@cindex encoding, font
+@cindex accents, defining
+@findex \DeclareFontEncoding
+
+Synopsis:
+
+@example
+\DeclareFontEncoding@{@var{encoding}@}@{@var{text-settings}@}@{@var{math-settings}@}
+@end example
+
+Declare the font encoding @var{encoding}. It also saves the value of
+@var{encoding} in @code{\LastDeclaredEncoding}
+(@pxref{\LastDeclaredEncoding}).
+
+The file @file{t1enc.def} contains this line (followed by many others).
+
+@example
+\DeclareFontEncoding@{T1@}@{@}@{@}
+@end example
+
+The @var{text-settings} are the commands that @LaTeX{} will run every
+time it switches from one encoding to another with the
+@code{\selectfont} or @code{\fontencoding} command. The
+@var{math-settings} are the commands that @LaTeX{} will use whenever the
+font is accessed as a math alphabet.
+
+@LaTeX{} ignores any space characters inside @var{text-settings} and
+@var{math-settings}, to prevent unintended spaces in the output.
+
+If you invent an encoding you should pick a two or three letter name
+starting with @samp{L} for @samp{local}, or @samp{E} for
+@samp{experimental}.
+
+Note that output encoding files may be read several times by @LaTeX{} so
+using, e.g., @code{\newcommand} may cause an error. In addition, such
+files should contain @code{\ProvidesFile} line (@pxref{Class and package
+commands}).
+
+Note also that you should use the @code{\...Default} commands only in a
+package, not in the encoding definition files, since those files
+should only contain declarations specific to that encoding.
+
+
+@node \DeclareTextAccent
+@subsection @code{\DeclareTextAccent}
+
+@cindex font encoding
+@cindex accents, defining
+@findex \DeclareTextAccent
+
+Synopsis:
+
+@example
+\DeclareTextAccent@{@var{cmd}@}@{@var{encoding}@}@{@var{slot}@}
+@end example
+
+Define an accent, to be put on top of other glyphs, in the encoding
+@var{encoding} at the location @var{slot}.
+
+This line from @file{t1enc.def} declares that to make a circumflex
+accent as in @code{\^A}, the system will put the accent in slot@tie{}2
+over the @samp{A} character, which is represented in ASCII as@tie{}65.
+(This holds unless there is a relevant @code{DeclareTextComposite} or
+@code{\DeclareTextCompositeCommand} declaration;
+@pxref{\DeclareTextComposite}.)
+
+@example
+\DeclareTextAccent@{\^@}@{T1@}@{2@}
+@end example
+
+If @var{cmd} has already been defined then @code{\DeclareTextAccent}
+does not give an error but it does log the redefinition in the
+transcript file.
+
+
+@node \DeclareTextAccentDefault
+@subsection @code{\DeclareTextAccentDefault}
+
+@cindex accents, defining
+@findex \DeclareTextAccent
+@findex \DeclareTextAccentDefault
+
+Synopsis:
+
+@example
+\DeclareTextAccentDefault@{@var{cmd}@}@{@var{encoding}@}
+@end example
+
+If there is an encoding-specific accent command @var{cmd} but there is
+no associated @code{\DeclareTextAccent} for that encoding then this
+command will pick up the slack, by saying to use it as described for
+@var{encoding}.
+
+For example, to make the encoding @code{OT1} be the default encoding for
+the accent @code{\"}, declare this.
+
+@example
+\DeclareTextAccentDefault@{\"@}@{OT1@}
+@end example
+
+@noindent
+If you issue a @code{\"} when the current encoding does not have a
+definition for that accent then @LaTeX{} will use the definition from
+@code{OT1}
+
+That is, this command is equivalent to this call (@pxref{\UseTextSymbol
+& \UseTextAccent}).
+
+@example
+\DeclareTextCommandDefault[1]@{@var{cmd}@}
+ @{\UseTextAccent@{@var{encoding}@}@{@var{cmd}@}@{#1@}@}
+@end example
+
+Note that @code{\DeclareTextAccentDefault} works for any one-argument
+@file{fontenc} command, not just the accent command.
+
+
+@node \DeclareTextCommand & \ProvideTextCommand
+@subsection @code{\DeclareTextCommand} & @code{\ProvideTextCommand}
+
+@findex \DeclareTextCommand
+@findex \DeclareTextCommandDefault
+@findex \ProvideTextCommand
+
+Synopsis, one of:
+
+@example
+\DeclareTextCommand@{@var{cmd}@}@{@var{encoding}@}@{@var{defn}@}
+\DeclareTextCommand@{@var{cmd}@}@{@var{encoding}@}[@var{nargs}]@{@var{defn@}}
+\DeclareTextCommand@{@var{cmd}@}@{@var{encoding}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+@end example
+
+or one of:
+
+@example
+\ProvideTextCommand@{@var{cmd}@}@{@var{encoding}@}@{@var{defn}@}
+\ProvideTextCommand@{@var{cmd}@}@{@var{encoding}@}[@var{nargs}]@{@var{defn}@}
+\ProvideTextCommand@{@var{cmd}@}@{@var{encoding}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
+@end example
+
+Define the command @var{cmd}, which will be specific to one encoding.
+The command name @var{cmd} must begin with a backslash, \. These
+commands can only appear in the preamble. Redefining @code{cmd} does
+not cause an error. The defined command will be robust even if the code
+in @var{defn} is fragile (@pxref{\protect}).
+
+For example, the file @file{t1enc.def} contains this line.
+
+@example
+\DeclareTextCommand@{\textperthousand@}@{T1@}@{\%\char 24 @}
+@end example
+
+With that, you can express parts per thousand.
+
+@example
+\usepackage[T1]@{fontenc@} % in preamble
+ ...
+Legal limit is \( 0.8 \)\textperthousand.
+@end example
+
+@noindent
+If you change the font encoding to @code{OT1} then you get an error like
+@samp{LaTeX Error: Command \textperthousand unavailable in encoding
+OT1}.
+
+The @code{\ProvideTextCommand} variant does the same, except that it
+does nothing if @var{cmd} is already defined. The
+@code{\DeclareTextSymbol} command is faster than this one for simple
+slot-to-glyph association (@pxref{\DeclareTextSymbol})
+
+The optional @var{nargs} and @var{optargsdefault} arguments play the
+same role here as in @code{\newcommand} (@pxref{\newcommand &
+\renewcommand}). Briefly, @var{nargs} is an integer from 0 to 9
+specifying the number of arguments that the defined command @code{cmd}
+takes. This number includes any optional argument. Omitting this
+argument is the same as specifying 0, meaning that @var{cmd} will have
+no arguments. And, if @var{optargsdefault} is present then the first
+argument of @code{\@var{cmd}} is optional, with default value
+@var{optargdefault} (which may be the empty string). If
+@var{optargsdefault} is not present then @code{\@var{cmd}} does not take
+an optional argument.
+
+
+@node \DeclareTextCommandDefault & \ProvideTextCommandDefault
+@subsection @code{\DeclareTextCommandDefault} & @code{\ProvideTextCommandDefault }
+
+@findex \DeclareTextCommand
+@findex \DeclareTextCommandDefault
+@findex \ProvideTextCommand
+@findex \ProvideTextCommandDefault
+
+Synopsis:
+
+@example
+\DeclareTextCommandDefault@{@var{cmd}@}@{@var{defn}@}
+@end example
+
+or:
+
+@example
+\ProvideTextCommandDefault@{@var{cmd}@}@{@var{defn}@}
+@end example
+
+Give a default definition for @var{cmd}, for when that command is not
+defined in the encoding currently in force. This default should only use
+encodings known to be available.
+
+This makes @code{\copyright} available.
+
+@example
+\DeclareTextCommandDefault@{\copyright@}@{\textcircled@{c@}@}
+@end example
+
+It uses only an encoding (OMS) that is always available.
+
+The @code{\DeclareTextCommandDefault} should not occur in the encoding
+definition files since those files should declare only commands for use
+when you select that encoding. It should instead be in a package.
+
+As with the related non-default commands, the
+@code{\ProvideTextCommandDefault} has exactly the same behavior as
+@code{\DeclareTextCommandDefault} except that it does nothing if
+@var{cmd} is already defined (@pxref{\DeclareTextCommand &
+\ProvideTextCommand}). So, packages can use it to provide fallbacks
+that other packages can improve upon.
+
+
+@node \DeclareTextComposite
+@subsection @code{\DeclareTextComposite}
+
+@cindex accents, defining
+@findex \DeclareTextComposite
+
+Synopsis:
+
+@example
+\DeclareTextComposite@{@var{cmd}@}@{@var{encoding}@}@{@var{simple_object}@}@{@var{slot}@}
+@end example
+
+Access an accented glyph directly, that is, without having to put an
+accent over a separate character.
+
+This line from @file{t1enc.def} means that @code{\^o} will cause
+@LaTeX{} to typeset lowercase@tie{}@samp{o} by taking the character
+directly from location 224 in the font.
+
+@example
+\DeclareTextComposite@{\^@}@{T1@}@{o@}@{244@}
+@end example
+
+@xref{fontenc package}, for a list of common encodings. The
+@var{simple_object} should be a single character or a single command.
+The @var{slot} argument is usually a positive integer represented in
+decimal (although octal or hexadecimal are possible). Normally
+@var{cmd} has already been declared for this encoding, either with
+@code{\DeclareTextAccent} or with a one-argument
+@code{\DeclareTextCommand}. In @file{t1enc.def}, the above line follows
+the @code{\DeclareTextAccent@{\^@}@{T1@}@{2@}} command.
+
+
+@node \DeclareTextCompositeCommand
+@subsection @code{\DeclareTextCompositeCommand}
+
+@cindex accents, defining
+@findex \DeclareTextCompositeCommand
+
+Synopsis:
+
+@example
+\DeclareTextCompositeCommand@{@var{cmd}@}@{@var{encoding}@}@{@var{arg}@}@{@var{code}@}
+@end example
+
+A more general version of @code{\DeclareTextComposite} that runs
+arbitrary code with @var{cmd}.
+
+This allows accents on @samp{i} to act like accents on dotless@tie{}i,
+@code{\i}.
+
+@example
+\DeclareTextCompositeCommand@{\'@}@{OT1@}@{i@}@{\'\i@}
+@end example
+
+@xref{fontenc package}, for a list of common encodings. Normally
+@var{cmd} will have already been declared with @code{\DeclareTextAccent}
+or as a one argument @code{\DeclareTextCommand}.
+
+
+@node \DeclareTextSymbol
+@subsection @code{\DeclareTextSymbol}
+
+@cindex symbol, defining
+@findex \DeclareTextSymbol
+
+Synopsis:
+
+@example
+\DeclareTextSymbol@{@var{cmd}@}@{@var{encoding}@}@{@var{slot}@}
+@end example
+
+Define a symbol in the encoding @var{encoding} at the location
+@var{slot}. Symbols defined in this way are for use in text, not
+mathematics.
+
+For example, this line from @file{t1enc.def} declares the number of the
+glyph to use for @BES{00AB}, the left guillemet.
+
+@example
+\DeclareTextSymbol@{\guillemotleft@}@{T1@}@{19@}
+@end example
+
+@noindent
+The command @code{\DeclareTextCommand@{\guillemotleft@}@{T1@}@{\char
+19@}} has the same effect but is slower (@pxref{\DeclareTextCommand &
+\ProvideTextCommand}).
+
+@xref{fontenc package}, for a list of common encodings. The @var{slot}
+can be specified in decimal, or octal (as in @code{'023}), or
+hexadecimal (as in @code{"13}), although decimal has the advantage that
+single quote or double quote could be redefined by another package.
+
+If @var{cmd} has already been defined then @code{\DeclareTextSymbol}
+does not give an error but it does log the redefinition in the
+transcript file.
+
+
+@node \DeclareTextSymbolDefault
+@subsection @code{\DeclareTextSymbolDefault}
+
+@cindex accents, defining
+@findex \DeclareTextSymbol
+@findex \DeclareTextSymbolDefault
+
+Synopsis:
+
+@example
+\DeclareTextSymbolDefault@{@var{cmd}@}@{@var{encoding}@}
+@end example
+
+If there is an encoding-specific symbol command @var{cmd} but there is no
+associated @code{\DeclareTextSymbol} for that encoding, then this command
+will pick up the slack, by saying to get the symbol as described for
+@var{encoding}.
+
+For example, to declare that if the current encoding has no meaning for
+@code{\textdollar} then use the one from @code{OT1}, declare this.
+
+@example
+\DeclareTextSymbolDefault@{\textdollar@}@{OT1@}
+@end example
+
+That is, this command is equivalent to this call (@pxref{\UseTextSymbol
+& \UseTextAccent}).
+
+@example
+\DeclareTextCommandDefault@{@var{cmd}@}
+ @{\UseTextSymbol@{@var{encoding}@}@{@var{cmd}@}@}
+@end example
+
+Note that @code{\DeclareTextSymbolDefault} can be used to define a
+default for any zero-argument @file{fontenc} command.
+
+
+@node \LastDeclaredEncoding
+@subsection @code{\LastDeclaredEncoding}
+
+@findex \LastDeclaredEncoding
+
+Synopsis:
+
+@example
+\LastDeclaredEncoding
+@end example
+
+Get the name of the most recently declared encoding. The
+@code{\DeclareFontEncoding} command stores the name so that it can be
+retrieved with this command (@pxref{\DeclareFontEncoding}).
+
+This relies on @code{\LastDeclaredEncoding} rather than give the
+name of the encoding explicitly.
+
+@example
+\DeclareFontEncoding@{JH1@}@{@}@{@}
+\DeclareTextAccent@{\'@}@{\LastDeclaredEncoding@}@{0@}
+@end example
+
+
+@node \UseTextSymbol & \UseTextAccent
+@subsection @code{\UseTextSymbol} & @code{\UseTextAccent}
+
+@findex \UseTextSymbol
+@findex \UseTextAccent
+
+Synopsis:
+
+@example
+\UseTextSymbol@{@var{encoding}@}@{@var{cmd}@}
+@end example
+
+or:
+
+@example
+\UseTextAccent@{@var{encoding}@}@{@var{cmd}@}@{@var{text}@}
+@end example
+
+Use a symbol or accent not from the current encoding.
+
+In general, to use a @file{fontenc} command in an encoding where it is
+not defined, and if the command has no arguments, then you can use it
+like this:
+
+@example
+\UseTextSymbol@{OT1@}@{\ss@}
+@end example
+
+@noindent
+which is equivalent to this (note the outer braces form a group, so @LaTeX{}
+reverts back to the prior encoding after the @code{\ss}):
+
+@example
+@{\fontencoding@{OT1@}\selectfont\ss@}
+@end example
+
+Similarly, to use a @file{fontenc} command in an encoding where it is
+not defined, and if the command has one argument, you can use it like this:
+
+@example
+\UseTextAccent@{OT1@}@{\'@}@{a@}
+@end example
+
+@noindent
+which is equivalent to this (again note the outer braces forming a group):
+
+@example
+@{fontencoding@{OT1@}\selectfont\'@{\fontencoding@{@var{enc_in_use}@}\selectfont a@}@}
+@end example
+
+@noindent
+Here, @var{enc_in_use} is the encoding in force before this sequence
+of commands, so that @samp{a} is typeset using the current encoding
+and only the accent is taken from @code{OT1}.
+
+
@node Font styles
@section Font styles
@@ -1409,17 +2070,19 @@ and a style. The @LaTeX{} commands for doing this are described here.
The following type style commands are supported by @LaTeX{}.
+@cindex declaration form of font style commands
In the table below the listed commands, the @code{\text...} commands,
-is used with an argument, as in @code{\textit@{@var{text}@}}. This is
-the preferred form. But shown after it, in parenthesis, is the
-corresponding declaration form, which is sometimes useful. This form
-takes no arguments, as in @code{@{\itshape @var{text}@}}. The scope of
-the declaration form lasts until the next type style command or the end
-of the current group. In addition, each has an environment form such as
-@code{\begin@{itshape@}...\end@{itshape@}}.
-
-These commands, in both the argument form and the declaration form, are
-cumulative; for instance you can get bold sans serif by saying either of
+are used with an argument as in @code{\textit@{@var{text}@}}. This is
+the preferred form. But shown after it in parenthesis is the
+corresponding @dfn{declaration form}, which is often useful. This
+form takes no arguments, as in @code{@{\itshape @var{text}@}}. The
+scope of the declaration form lasts until the next type style command
+or the end of the current group. In addition, each has an environment
+form such as @code{\begin@{itshape@}...\end@{itshape@}}, which we'll
+describe further at the end of the section.
+
+These commands, in any of the three forms, are cumulative; for instance
+you can get bold sans serif by saying either of
@code{\sffamily\bfseries} or @code{\bfseries\sffamily}.
@findex \nocorrlist
@@ -1427,7 +2090,7 @@ cumulative; for instance you can get bold sans serif by saying either of
One advantage of these commands is that they automatically insert italic
corrections if needed (@pxref{\/}). Specifically, they insert the
italic correction unless the following character is in the list
-@code{\nocorrlist}, which by default consists of a period and a comma.
+@code{\nocorrlist}, which by default consists of period and comma.
To suppress the automatic insertion of italic correction, use
@code{\nocorr} at the start or end of the command argument, such as
@code{\textit@{\nocorr text@}} or @code{\textsc@{text \nocorr@}}.
@@ -1501,8 +2164,8 @@ used as declarations: @code{@{\@var{cmd}...@}} instead of
(The unconditional commands below are an older version of font
switching. The earlier commands are an improvement in most
-circumstances. But sometimes an unconditional font switch is precisely
-what you want.)
+circumstances. But sometimes an unconditional font switch is what is
+needed.)
@ftable @code
@item \bf
@@ -1593,17 +2256,15 @@ formulas. @code{\mathversion@{normal@}} restores the default.
@cindex numerals, old-style
@cindex old-style numerals
@cindex lining numerals
-@PkgIndex{textcomp}
-Finally, the command @code{\oldstylenums@{@var{numerals}@}} will typeset
-so-called ``old-style'' numerals, which have differing heights and
-depths (and sometimes widths) from the standard ``lining'' numerals,
-which all have the same height as uppercase letters. @LaTeX{}'s
-default fonts support this, and will respect @code{\textbf} (but not
-other styles; there are no italic old-style numerals in Computer
-Modern). Many other fonts have old-style numerals also; sometimes the
-@code{textcomp} package must be loaded, and sometimes package options
-are provided to make them the default. FAQ entry:
-@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf}.
+Finally, the command @code{\oldstylenums@{@var{numerals}@}} will
+typeset so-called ``old-style'' numerals, which have differing heights
+and depths (and sometimes widths) from the standard ``lining''
+numerals, which all have the same height as uppercase letters.
+@LaTeX{}'s default fonts support this, and will respect @code{\textbf}
+(but not other styles; there are no italic old-style numerals in
+Computer Modern). Many other fonts have old-style numerals also;
+sometimes package options are provided to make them the default. FAQ
+entry: @url{https://www.texfaq.org/FAQ-osf}.
@node Font sizes
@@ -1654,8 +2315,9 @@ options}).
@tab 24.88 @tab 24.88 @tab 24.88
@end multitable
-The commands are listed here in declaration forms. You use them by
-declaring them, as with this example.
+@cindex declaration form of font size commands
+The commands are listed here in declaration (not environment) form,
+since that is how they are typically used. For example.
@example
\begin@{quotation@} \small
@@ -1664,12 +2326,24 @@ declaring them, as with this example.
@end example
@noindent
-The scope of the @code{\small} lasts until the end of the
-@code{quotation} environment. It would also end at the next type style
-command or the end of the current group, so you could enclose it in
-extra curly braces @code{@{\small We are here, we are here, we are
-here!@}}. You can instead use the environment form of these commands;
-for instance, @code{\begin@{tiny@}...\end@{tiny@}}.
+Here, the scope of the @code{\small} lasts until the end of the
+@code{quotation} environment. It would also end at the next type
+style command or the end of the current group, so you could enclose it
+in curly braces @code{@{\small This text is typeset in the small font.@}}.
+
+@cindex environment form of font size commands
+An @dfn{environment form} of each of these commands is also defined; for
+instance, @code{\begin@{tiny@}...\end@{tiny@}}. However, in practice
+this form can easily lead to unwanted spaces at the beginning and/or
+end of the environment without careful consideration, so it's
+generally less error-prone to stick to the declaration form.
+
+(Aside: Technically, due to the way @LaTeX{} defines @code{\begin} and
+@code{\end}, nearly every command that does not take an argument
+technically has an environment form. But in almost all cases, it would
+only cause confusion to use it. The reason for mentioning the
+environment form of the font size declarations specifically is that
+this particular use is not rare.)
@node Low-level font commands
@@ -1703,7 +2377,7 @@ hyphenate words containing accented letters. For more, see
@cindex families, of fonts
@cindex font catalogue
Select the font family. The web page
-@url{http://www.tug.dk/FontCatalogue/} provides one way to browse
+@url{https://tug.org/FontCatalogue/} provides one way to browse
through many of the fonts easily used with @LaTeX{}. Here are
examples of some common families.
@@ -1861,25 +2535,8 @@ vertical space between lines, baseline to baseline. It is stored in the
parameter @code{\baselineskip}. The default @code{\baselineskip} for
the Computer Modern typeface is 1.2 times the @code{\fontsize}.
Changing @code{\baselineskip} directly is inadvisable since its value is
-reset every time a size change happens; see @code{\baselinestretch}, next.
-
-@anchor{low level font commands baselinestretch}
-@item \baselinestretch
-@findex \baselinestretch
-@LaTeX{} multiplies the line spacing by the value of the
-@code{\baselinestretch} parameter; the default factor is 1. A change
-takes effect when @code{\selectfont} (see below) is called. You can
-make a line skip change happen for the entire document, for instance
-doubling it, by doing @code{\renewcommand@{\baselinestretch@}@{2.0@}} in
-the preamble.
-
-@PkgIndex{setspace}
-@cindex double spacing
-However, the best way to double-space a document is to use the
-@file{setspace} package. In addition to offering a number of spacing
-options, this package keeps the line spacing single-spaced in places
-where that is typically desirable, such as footnotes and figure
-captions. See the package documentation.
+reset every time a size change happens; instead use
+@code{\baselinestretch}. (@pxref{\baselineskip & \baselinestretch}).
@anchor{low level font commands linespread}
@item \linespread@{@var{factor}@}
@@ -1927,6 +2584,7 @@ Commands for controlling the general page layout.
* \flushbottom:: Make all text pages the same height.
* \raggedbottom:: Allow text pages of differing height.
* Page layout parameters:: @code{\headheight} @code{\footskip}.
+* \baselineskip & \baselinestretch:: Space between lines.
* Floats:: Figures, tables, etc.
@end menu
@@ -1978,24 +2636,24 @@ These parameters control typesetting in two-column output:
@item \columnsep
@anchor{twocolumn columnsep}
The distance between columns. The default is 35pt. Change it with a
-command such as @code{\setlength@{\columnsep@}@{40pt@}} You must change
-it before the two column environment starts; in the preamble is a good
+command such as @code{\setlength@{\columnsep@}@{40pt@}}. You must change
+it before the two column mode starts; in the preamble is a good
place.
@item \columnseprule
@anchor{twocolumn columnseprule}
-The width of the rule between columns. The rule appears halfway between
-the two columns. The default is 0pt, meaning that there is no rule.
-Change it with a command such as
+The width of the rule between columns. The default is 0pt, meaning that
+there is no rule. Otherwise, the rule appears halfway between the two
+columns. Change it with a command such as
@code{\setlength@{\columnseprule@}@{0.4pt@}}, before the two-column
-environment starts.
+mode starts.
@item \columnwidth
@anchor{twocolumn columnwidth}
The width of a single column. In one-column mode this is equal to
@code{\textwidth}. In two-column mode by default @LaTeX{} sets the
-width of each of the two columns to be half of @code{\textwidth} minus
-@code{\columnsep}.
+width of each of the two columns, @code{\columnwidth}, to be half of
+@code{\textwidth} minus @code{\columnsep}.
@end ftable
@@ -2011,13 +2669,13 @@ The following parameters control float behavior of two-column output.
The maximum fraction at the top of a two-column page that may be
occupied by two-column wide floats. The default is 0.7, meaning that
the height of a @code{table*} or @code{figure*} environment must not
-exceed @code{0.7\textheight} . If the height of your starred float
+exceed @code{0.7\textheight}. If the height of your starred float
environment exceeds this then you can take one of the following actions
to prevent it from floating all the way to the back of the document:
@itemize @bullet
@item
-Use the @code{[tp]} location specifier to tell LaTeX to try to put
+Use the @code{[tp]} location specifier to tell @LaTeX{} to try to put
the bulky float on a page by itself, as well as at the top of a page.
@item
@@ -2032,28 +2690,28 @@ to avoid going to float pages so soon.
You can redefine it, as with
@code{\renewcommand@{\dbltopfraction@}@{0.9@}}.
-@anchor{twocolumn dblfloatpagefraction}
@item \dblfloatpagefraction
+@anchor{twocolumn dblfloatpagefraction}
For a float page of two-column wide floats, this is the minimum fraction
that must be occupied by floats, limiting the amount of blank space.
@LaTeX{}'s default is @code{0.5}. Change it with @code{\renewcommand}.
-@anchor{twocolumn dblfloatsep}
@item \dblfloatsep
+@anchor{twocolumn dblfloatsep}
On a float page of two-column wide floats, this length is the distance
between floats, at both the top and bottom of the page. The default is
@code{12pt plus2pt minus2pt} for a document set at @code{10pt} or
@code{11pt}, and @code{14pt plus2pt minus4pt} for a document set at
@code{12pt}.
-@anchor{twocolumn dbltextfloatsep}
@item \dbltextfloatsep
+@anchor{twocolumn dbltextfloatsep}
This length is the distance between a multi-column float at the top or
bottom of a page and the main text. The default is @code{20pt plus2pt
minus4pt}.
-@anchor{twocolumn dbltopnumber}
@item \dbltopnumber
+@anchor{twocolumn dbltopnumber}
On a float page of two-column wide floats, this counter gives the
maximum number of floats allowed at the top of the page. The @LaTeX{}
default is @code{2}.
@@ -2162,7 +2820,7 @@ at all type sizes.
Vertical distance between the bottom of the header line and the top of
the main text. The default in the @code{article} and @code{report}
classes is @samp{25pt}. In the @code{book} class the default is: if the
-document is set at 10pt then it is @samp{0.25in}, and at 11pt and 12pt
+document is set at 10pt then it is @samp{0.25in}, and at 11pt or 12pt
it is @samp{0.275in}.
@item \footskip
@@ -2225,12 +2883,13 @@ distance.
@findex \evensidemargin
@anchor{page layout parameters oddsidemargin}
@anchor{page layout parameters evensidemargin}
-The @code{\oddsidemargin} is the extra distance between the left side of
+@c xx TODO re-align on French version that is more complete/accurate.
+The @code{\oddsidemargin} length is the extra distance between the left side of
the page and the text's left margin, on odd-numbered pages when the
document class option @code{twoside} is chosen and on all pages when
@code{oneside} is in effect. When @code{twoside} is in effect, on
even-numbered pages the extra distance on the left is
-@code{evensidemargin}.
+@code{\evensidemargin}.
@LaTeX{}'s default is that @code{\oddsidemargin} is 40% of the
difference between @code{\paperwidth} and @code{\textwidth}, and
@@ -2284,9 +2943,9 @@ Inside a minipage (@pxref{minipage}) or @code{\parbox}
specified width, and revert to their normal values at the end of the
@code{minipage} or @code{\parbox}.
+@item \hsize
@findex \hsize
@anchor{page layout parameters hsize}
-@item \hsize
This entry is included for completeness: @code{\hsize} is the @TeX{}
primitive parameter used when text is broken into lines. It should not
be used in normal @LaTeX{} documents.
@@ -2294,6 +2953,7 @@ be used in normal @LaTeX{} documents.
@item \topmargin
@findex topmargin
@anchor{page layout parameters topmargin}
+@c xxx TODO re-align on French version that is more accurate.
Space between the top of the @TeX{} page (one inch from the top of the
paper, by default) and the top of the header. The value is computed
based on many other parameters: @code{\paperheight @minus{} 2in @minus{}
@@ -2310,6 +2970,119 @@ same as the font size, e.g., @samp{10pt} at a type size of 10pt.
@end ftable
+@node \baselineskip & \baselinestretch
+@section @code{\baselineskip} & @code{\baselinestretch}
+
+@findex \baselineskip
+@findex \baselinestretch
+@findex \linespread
+@cindex space between lines
+@cindex interline space
+@cindex leading
+@cindex double spacing
+
+The @code{\baselineskip} is a rubber length (@pxref{Lengths}). It gives
+the leading, the normal distance between lines in a paragraph, from
+baseline to baseline.
+
+Ordinarily document authors do not directly change @code{\baselineskip}
+while writing. Instead, it is set by the low level font selection
+command @code{\fontsize} (@pxref{low level font commands fontsize}).
+The @code{\baselineskip}'s value is reset every time a font change
+happens and so any direct change to @code{\baselineskip} would vanish
+the next time there was a font switch. For how to influence line
+spacing, see the discussion of @code{\baselinestretch} below.
+
+Usually, a font's size and baseline skip is assigned by the font
+designer. These numbers are nominal in the sense that if, for instance,
+a font's style file has the command @code{\fontsize@{10pt@}@{12pt@}}
+then that does not mean that the characters in the font are 10pt tall;
+for instance, parentheses and accented capitals may be taller. Nor does
+it mean that if the lines are spaced less than 12pt apart then they risk
+touching. Rather these numbers are typographic judgements. (Often, the
+@code{\baselineskip} is about twenty percent larger than the font size.)
+
+@c adapted from FAQ
+The @code{\baselineskip} is not a property of each line but of the
+entire paragraph. As a result, large text in the middle of a paragraph,
+such as a single @code{@{\Huge Q@}}, will be squashed into its line.
+@TeX{} will make sure it doesn't scrape up against the line above but
+won't change the @code{\baselineskip} for that one line to make extra
+room above. For the fix, use a @code{\strut} (@pxref{\strut}).
+
+The value of @code{\baselineskip} that @TeX{} uses for the paragraph is
+the value in effect at the blank line or command that ends the paragraph
+unit. So if a document contains this paragraph then its lines will be
+scrunched together, compared to lines in surrounding paragraphs.
+
+@c Adapted from B Beeton's "Lapses in TeX" TB 42:1 p 13.
+@example
+Many people see a page break between text and a displayed equation as
+bad style, so in effect the display is part of the paragraph.
+Because this display is in footnotesize, the entire paragraph has the
+baseline spacing matching that size.
+@{\footnotesize $$a+b = c$$@}
+@end example
+
+@findex \lineskip
+@findex \lineskiplimit
+@findex \prevdepth
+The process for making paragraphs is that when a new line is added, if
+the depth of the previous line plus the height of the new line is less
+than @code{\baselineskip} then @TeX{} inserts vertical glue to make up
+the difference. There are two fine points. The first is that if the
+lines would be too close together, closer than @code{\lineskiplimit},
+then @TeX{} instead uses @code{\lineskip} as the interline glue. The
+second is that @TeX{} doesn't actually use the depth of the previous
+line. Instead it uses @code{\prevdepth}, which usually contains that
+depth. But at the beginning of the paragraph (or any vertical list)
+or just after a rule, @code{\prevdepth} has the value -1000pt and this
+special value tells @TeX{} not to insert any interline glue at the
+paragraph start.
+
+In the standard classes @code{\lineskiplimit} is 0pt and
+@code{\lineskip} is 1pt. By the prior paragraph then, the distance
+between lines can approach zero but if it becomes zero (or less than
+zero) then the lines jump to 1pt apart.
+
+Sometimes authors must, for editing purposes, put the document in double
+space or one-and-a-half space. The right way to influence the interline
+distance is via @code{\baselinestretch}. It scales
+@code{\baselineskip}, and has a default value of 1.0. It is a command,
+not a length, so change the scale factor as in
+@code{\renewcommand@{\baselinestretch@}@{1.5@}\selectfont}.
+
+The most straightforward way to change the line spacing for an entire
+document is to put @code{\linespread@{@var{factor}@}} in the preamble.
+For double spacing, take @var{factor} to be 1.6 and for one-and-a-half
+spacing use 1.3. These number are rough: for instance, since the
+@code{\baselineskip} is about 1.2 times the font size, multiplying by
+1.6 gives a font size to baseline ratio of about 2. (The
+@code{\linespread} command is defined as
+@code{\renewcommand@{\baselinestretch@}@{@var{factor}@}} so it won't
+take effect until a font setting happens. But that always takes place at
+the start of a document, so there you don't need to follow it with
+@code{\selectfont}.)
+
+@PkgIndex{setspace}
+A simpler approach is the @file{setspace} package. The basic example:
+
+@example
+\usepackage@{setspace@}
+\doublespacing % or \onehalfspacing for 1.5
+@end example
+
+In the preamble these will start the document off with that sizing.
+But you can also use these declarations in the document body to change
+the spacing from that point forward, and consequently there is
+@code{\singlespacing} to return the spacing to normal. In the
+document body, a better practice than using the declarations is to use
+environments, such as @code{\begin@{doublespace@}
+... \end@{doublespace@}}. The package also has commands to do
+arbitrary spacing: @code{\setstretch@{@var{factor}@}} and
+@code{\begin@{spacing@}@{@var{factor}@} ... \end@{spacing@}}.
+
+
@node Floats
@section Floats
@@ -2355,7 +3128,7 @@ both @code{article} and @code{book} classes, is @code{tbp}.
allowed for full-width floats (@code{figure*}) with double-column
output. To ameliorate this, use the @file{stfloats} or
@file{dblfloatfix} package, but see the discussion at caveats in the
-FAQ: @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat}.
+FAQ: @url{https://www.texfaq.org/FAQ-2colfloat}.
@item h
(Here)---at the position in the text where the @code{figure} environment
@@ -2367,7 +3140,7 @@ automatically added.
To absolutely force a float to appear ``here'', you can
@code{\usepackage@{float@}} and use the @code{H} specifier which it
defines. For further discussion, see the FAQ entry at
-@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere}.
+@url{https://www.texfaq.org/FAQ-figurehere}.
@item p
@cindex float page
@@ -2495,13 +3268,13 @@ Maximum number of floats that can appear on a text page; default 3.
@end ftable
The principal @TeX{}@tie{}FAQ entry relating to floats
-@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats} contains
+@url{https://www.texfaq.org/FAQ-floats} contains
suggestions for relaxing @LaTeX{}'s default parameters to reduce the
problem of floats being pushed to the end. A full explanation of the
float placement algorithm is in Frank Mittelbach's article ``How to
influence the position of float environments like figure and table in
@LaTeX{}?''
-(@url{http://latex-project.org/papers/tb111mitt-float.pdf}).
+(@url{https://www.latex-project.org/publications/2014-FMi-TUB-tb111mitt-float-placement.pdf}).
@node Sectioning
@@ -2512,12 +3285,14 @@ influence the position of float environments like figure and table in
@cindex chapter
@cindex section
@cindex subsection
+@cindex subsubsection
@cindex paragraph
@cindex subparagraph
@findex \part
@findex \chapter
@findex \section
@findex \subsection
+@findex \subsubsection
@findex \paragraph
@findex \subparagraph
@@ -2559,8 +3334,8 @@ not available in @code{article}.
@cindex @code{*}-form of sectioning commands
All these commands have a @code{*}-form that prints @var{title} as usual
-but is not numbered and does not make an entry in the table of contents.
-An example of using this is for an appendix in an @code{article} . The
+but does not number it and does not make an entry in the table of contents.
+An example of using this is for an appendix in an @code{article}. The
input @code{\appendix\section@{Appendix@}} gives the output @samp{A
Appendix} (@pxref{\appendix}). You can lose the numbering@tie{}@samp{A}
by instead entering @code{\section*@{Appendix@}} (articles often omit a
@@ -2583,11 +3358,19 @@ of contents will have an entry for this sectioning unit
(@pxref{Sectioning/tocdepth}).
@LaTeX{} expects that before you have a @code{\subsection} you will have
-a @code{\section} and, in a book, that before a @code{\section} you will
-have a @code{\chapter}. Otherwise you can get a something like a
-subsection numbered @samp{3.0.1}.
+a @code{\section} and, in a @code{book} class document, that before a
+@code{\section} you will have a @code{\chapter}. Otherwise you can get
+something like a subsection numbered @samp{3.0.1}.
-Two counters relate to the appearance of sectioning commands.
+@PkgIndex{titlesec}
+@LaTeX{} lets you change the appearance of the sectional units. As a
+simple example, you can change the section numbering to upper-case
+letters with @code{\renewcommand\thesection@{\Alph@{section@}@}} in the
+preamble (@pxref{\alph \Alph \arabic \roman \Roman \fnsymbol}). CTAN
+has many packages that make this adjustment easier, notably
+@file{titlesec}.
+
+Two counters relate to the appearance of headings made by sectioning commands.
@ftable @code
@item secnumdepth
@@ -2595,16 +3378,16 @@ Two counters relate to the appearance of sectioning commands.
@cindex section numbers, printing
@anchor{sectioning secnumdepth}
@anchor{Sectioning/secnumdepth}
-Controls which sectioning commands are
-numbered. Suppress numbering of sectioning at any depth greater than
-@var{level} @code{\setcounter@{secnumdepth@}@{@var{level}@}}
-(@pxref{\setcounter}). See the above table for the level numbers. For
-instance, if the @code{secnumdepth} is 1 in an @code{article} then a
-@code{\section@{Introduction@}} command will produce output like @samp{1
-Introduction} while @code{\subsection@{Discussion@}} will produce output
-like @samp{Discussion}, without the number. @LaTeX{}'s default
-@code{secnumdepth} is@tie{}3 in @file{article} class and @tie{}2 in the
-@file{book} and @file{report} classes.
+Controls which sectioning unit are numbered. Setting the counter with
+@code{\setcounter@{secnumdepth@}@{@var{level}@}} will suppress
+numbering of sectioning at any depth greater than @var{level}
+(@pxref{\setcounter}). See the above table for the level numbers.
+For instance, if the @code{secnumdepth} is 1 in an @code{article} then
+a @code{\section@{Introduction@}} command will produce output like
+@samp{1 Introduction} while @code{\subsection@{Discussion@}} will
+produce output like @samp{Discussion}, without the number. @LaTeX{}'s
+default @code{secnumdepth} is@tie{}3 in @file{article} class and
+@tie{}2 in the @file{book} and @file{report} classes.
@item tocdepth
@findex tocdepth @r{counter}
@@ -2617,7 +3400,7 @@ sectioning units at @var{level} be the smallest ones listed
(@pxref{\setcounter}). See the above table for the level numbers. For
instance, if @code{tocdepth} is@tie{}1 then the table of contents will
list sections but not subsections. @LaTeX{}'s default
-@code{secnumdepth} is@tie{}3 in @file{article} class and @tie{}2 in the
+@code{tocdepth} is@tie{}3 in @file{article} class and @tie{}2 in the
@file{book} and @file{report} classes.
@end ftable
@@ -2630,7 +3413,7 @@ list sections but not subsections. @LaTeX{}'s default
* \subsubsection & \paragraph & \subparagraph:: Lower divisions.
* \appendix:: Start appendices.
* \frontmatter & \mainmatter & \backmatter:: The three parts of a book.
-* \@@startsection:: Layout of sectional units.
+* \@@startsection:: Sectional unit headings.
@end menu
@@ -2689,7 +3472,7 @@ out the break in the table of contents.
For determining which sectional units are numbered and which appear in
the table of contents, the level number of a part is@tie{}-1
-(@pxref{Sectioning/secnumdepth} and @pxref{Sectioning/tocdepth}).
+(@pxref{Sectioning/secnumdepth}, and @ref{Sectioning/tocdepth}).
@PkgIndex{indentfirst}
In the class @code{article}, if a paragraph immediately follows the part
@@ -2765,7 +3548,7 @@ the title but that doesn't work well with running headers so it omits
the break in the contents
@example
-\chapter[Given it all\\ my story]@{Given it all\\ my story@}
+\chapter[Given it all; my story]@{Given it all\\ my story@}
@end example
For determining which sectional units are numbered and which appear in
@@ -2955,13 +3738,13 @@ holds in @code{article} except that there are no chapters in that class
so it looks like @samp{2.3 @var{title}}.
The @code{*}@tie{}form shows @var{title}.
-But it does not show the section number, does not increment the
-@code{section} counter, and produces no table of contents entry.
+But it does not show the subsection number, does not increment the
+@code{subsection} counter, and produces no table of contents entry.
-The optional argument @var{toc-title} will appear as the section title
+The optional argument @var{toc-title} will appear as the subsection title
in the table of contents (@pxref{Table of contents etc.}). If it is
-not present then @var{title} will be there. This shows the full name in
-the title of the section,
+not present then @var{title} will be there. This shows the full text in
+the title of the subsection,
@example
\subsection[$\alpha,\beta,\gamma$ paper]@{\textit@{The Origin of
@@ -3124,36 +3907,43 @@ In this book
@noindent
the first two will generate output numbered @samp{Chapter 1} and
@samp{Chapter 2}. After the @code{\appendix} the numbering will be
-@samp{Appendix A} and @samp{Appendix B}. @xref{Larger book template}
+@samp{Appendix A} and @samp{Appendix B}. @xref{Larger book template},
for another example.
-@PkgIndex{appendix} The @file{appendix} package adds the command
+@PkgIndex{appendix}
+The @file{appendix} package adds the command
@code{\appendixpage} to put a separate @samp{Appendices} in the document
body before the first appendix, and the command @code{\addappheadtotoc}
to do the same in the table of contents. You can reset the name
-@samp{Appendix} with a command like
+@samp{Appendices} with a command like
@code{\renewcommand@{\appendixname@}@{Specification@}}, as well as a
number of other features. See the documentation on CTAN.
@node \frontmatter & \mainmatter & \backmatter
-
@section @code{\frontmatter}, @code{\mainmatter}, @code{\backmatter}
@findex \frontmatter
@cindex book, front matter
+@cindex front matter of a book
@findex \mainmatter
@cindex book, main matter
+@cindex main matter of a book
@findex \backmatter
@cindex book, back matter
@cindex book, end matter
+@cindex back matter of a book
+@cindex end matter of a book
-Synopsis, one of:
+Synopsis, one or more of:
@example
\frontmatter
+...
\mainmatter
+...
\backmatter
+...
@end example
Format a @code{book} class document differently according to which part
@@ -3166,18 +3956,22 @@ pages, such as the title page, are traditionally not numbered.) The
back matter may contain such things as a glossary, notes, a
bibliography, and an index.
-The @code{\frontmatter} declaration makes the pages numbered in
-lowercase roman, and makes chapters not numbered, although each
-chapter's title appears in the table of contents; if you use other
-sectioning commands here, use the @code{*}-version (@pxref{Sectioning}).
-The @code{\mainmatter} changes the behavior back to the expected
-version, and resets the page number. The @code{\backmatter} leaves the
-page numbering alone but switches the chapters back to being not
-numbered. @xref{Larger book template} for an example using the three.
+The @code{\frontmatter} command makes the pages numbered in lowercase
+roman, and makes chapters not numbered, although each chapter's title
+appears in the table of contents; if you use other sectioning commands
+here, use the @code{*}-version (@pxref{Sectioning}).
+
+The @code{\mainmatter} command changes the behavior back to the expected
+version, and resets the page number.
+
+The @code{\backmatter} command leaves the page numbering alone but
+switches the chapters back to being not numbered.
+
+@xref{Larger book template}, for an example using these three commands.
@node \@@startsection
-@section @code{\@@startsection}
+@section @code{\@@startsection}, typesetting sectional unit headings
@findex \@@startsection
@cindex section, redefining
@@ -3223,12 +4017,13 @@ so that issuing
@end example
@noindent
-redefines @code{\section} to have the form
-@code{\section*[@var{toctitle}]@{@var{title}@}} (here too, the
-star@tie{}@code{*} is optional). @xref{Sectioning}. This implies that
-when you write a command like @code{\renewcommand@{section@}@{...@}},
-the @code{\@@startsection@{...@}} must come last in the definition. See
-the examples below.
+redefines @code{\section} while keeping its standard calling form
+@code{\section*[@var{toctitle}]@{@var{title}@}} (in which, for reminder,
+the star@tie{}@code{*} is optional). @xref{Sectioning}. This implies
+that when you write a command like
+@code{\renewcommand@{\section@}@{...@}}, the
+@code{\@@startsection@{...@}} must come last in the definition. See the
+examples below.
@table @var
@@ -3249,7 +4044,7 @@ example below.
@anchor{startsection level}
@anchor{\@@startsection/level}
An integer giving the depth of the sectioning command.
-@xref{Sectioning} for the list of standard level numbers.
+@xref{Sectioning}, for the list of standard level numbers.
If @var{level} is less than or equal to the value of the counter
@code{secnumdepth} then titles for this sectioning command will be
@@ -3278,7 +4073,7 @@ the title into the left margin.
@anchor{\@@startsection/beforeskip}
The absolute value of this length is the amount of vertical space that
is inserted before this sectioning unit's title. This space will be
-discarded if the sectioning unit happens to start at the top of a fresh
+discarded if the sectioning unit happens to start at the beginning of a
page. If this number is negative then the first paragraph following the
header is not indented, if it is non-negative then the first paragraph
is indented. (Note that the negative of @code{1pt plus 2pt minus 3pt}
@@ -3341,20 +4136,31 @@ produce titles that are bold and uppercase.
These are @LaTeX{}'s defaults for the first three sectioning units that
are defined with @code{\@@startsection}, for the @file{article},
-@file{book}, and @file{report} classes. For section, the @var{level} is
-1, the @var{indent} is 0@dmn{pt}, the @var{beforeskip} is @code{-3.5ex
-plus -1ex minus -0.2ex}, the @var{afterskip} is @code{2.3ex plus 0.2ex},
-and the @var{style} is @code{\normalfont\Large\bfseries}. For
-subsection, the @var{level} is 2, the @var{indent} is 0@dmn{pt}, the
-@var{beforeskip} is @code{-3.25ex plus -1ex minus -0.2ex}, the
-@var{afterskip} is @code{1.5ex plus 0.2ex}, and the @var{style} is
-@code{\normalfont\large\bfseries}. For subsubsection, the @var{level}
-is 3, the @var{indent} is 0@dmn{pt}, the @var{beforeskip} is
-@code{-3.25ex plus -1ex minus -0.2ex}, the @var{afterskip} is
-@code{1.5ex plus 0.2ex}, and the @var{style} is
+@file{book}, and @file{report} classes.
+
+@itemize
+@item
+For @code{section}: @var{level} is 1, @var{indent} is 0@dmn{pt},
+@var{beforeskip} is @code{-3.5ex plus -1ex minus -0.2ex},
+@var{afterskip} is @code{2.3ex plus 0.2ex}, and @var{style} is
+@code{\normalfont\Large\bfseries}.
+
+@item
+For @code{subsection}: @var{level} is 2, @var{indent} is 0@dmn{pt},
+@var{beforeskip} is @code{-3.25ex plus -1ex minus @w{-0.2ex}},
+@var{afterskip} is @code{1.5ex plus 0.2ex}, and @var{style} is
+@code{\normalfont\large\bfseries}.
+
+@item
+@raggedright
+For @code{subsubsection}: @var{level} is 3, @var{indent} is 0@dmn{pt},
+@var{beforeskip} is @code{-3.25ex plus -1ex minus -0.2ex},
+@var{afterskip} is @code{1.5ex plus 0.2ex}, and @var{style} is
@code{\normalfont\normalsize\bfseries}.
+@end raggedright
+@end itemize
-Here are examples. They go either in a package or class file or in the
+Some examples follow. These go either in a package or class file or in the
preamble of a @LaTeX{} document. If you put them in the preamble they
must go between a @code{\makeatletter} command and a
@code{\makeatother}. (Probably the error message @code{You can't use
@@ -3465,6 +4271,7 @@ having to enter the ``Theorem.''
* \label:: Assign a symbolic name to a piece of text.
* \pageref:: Refer to a page number.
* \ref:: Refer to a section, figure or similar.
+* xr package:: References from another document.
@end menu
@@ -3616,6 +4423,81 @@ The @file{cleveref} package includes text such as @samp{Theorem} in the
reference. See the documentation on CTAN.
+@node xr package
+@section @code{xr} package
+
+@findex @code{xr} package
+@findex @code{xr-hyper} package
+@findex \externaldocument
+@cindex cross referencing, across documents
+
+Synopsis:
+
+@example
+\usepackage@{xr@}
+ \externaldocument@{@var{document-basename}@}
+@end example
+
+or
+
+@example
+\usepackage@{xr@}
+ \externaldocument[@var{reference-prefix}]@{@var{document-basename}@}
+@end example
+
+Make cross references to the external document
+@code{@var{document-basename}.tex}.
+
+Here is an example. If @code{lectures.tex} has this in the preamble
+
+@example
+\usepackage@{xr@}
+ \externaldocument@{exercises@}
+ \externaldocument[H-]@{hints@}
+ \externaldocument@{answers@}
+@end example
+
+then it can use cross reference labels from the other three documents.
+Suppose that @code{exercises.tex} has an enumerated list containing
+this,
+
+@example
+\item \label@{exer:EulersThm@} What if every vertex has odd degree?
+@end example
+
+and @code{hints.tex} has an enumerated list with this,
+
+@example
+\item \label@{exer:EulersThm@} Distinguish the case of two vertices.
+@end example
+
+and @code{answers.tex} has an enumerated list with this.
+
+@example
+\item \label@{ans:EulersThm@} There is no Euler path, except if there
+ are exactly two vertices.
+@end example
+
+After compiling the exercises, hints, and answers documents, entering
+this in the body of @code{lectures.tex} will result in the lectures
+getting the reference numbers used in the other documents.
+
+@example
+See Exercise~\ref@{exer:EulersThm@}, with Hint~\ref@{H-exer:EulersThm@}.
+The solution is Answer~\ref@{ans:EulersThm@}.
+@end example
+
+The prefix @code{H-} for the reference from the hints file is needed
+because the label in the hints file is the same as the label in the
+exercises file. Without that prefix, both references would get the
+number from the later file.
+
+Note: if the document uses the @code{hyperref} package then in place of
+@code{xr}, put @code{\usepackage@{xr-hyper@}} before the
+@code{\usepackage@{hyperref@}}. Also, if any of the multiple documents
+uses @code{hyperref} then they all must use it.
+
+
@node Environments
@chapter Environments
@@ -3705,6 +4587,7 @@ default only in the @code{report} class.
\end@{abstract@}
@end example
+@PkgIndex abstract
The next example produces a one column abstract in a two column document (for
a more flexible solution, use the package @file{abstract}).
@@ -3878,7 +4761,7 @@ ending.
\begin@{center@}
My father considered that anyone who went to chapel and didn't drink
alcohol was not to be tolerated.\\
- I grew up in that belief. --Richard Burton
+ I grew up in that belief. ---Richard Burton
\end@{center@}
@end example
@@ -3975,10 +4858,10 @@ missing \item}.
This example shows the environment used for a sequence of definitions.
@example
-\begin@{definition@}
+\begin@{description@}
\item[lama] A priest.
\item[llama] A beast.
-\end@{definition@}
+\end@{description@}
@end example
@noindent
@@ -4034,9 +4917,9 @@ Synopsis:
\end@{displaymath@}
@end example
-Environment to typeset the math text on its own line, in display style
-and centered. To make the text be flush-left use the global option
-@code{fleqn}; see @ref{Document class options}.
+Environment to typeset the @var{mathematical text} on its own line, in
+display style and centered. To make the text be flush-left use the
+global option @code{fleqn}; see @ref{Document class options}.
In the @code{displaymath} environment no equation number is added to the
math text. One way to get an equation number is to use the
@@ -4049,18 +4932,20 @@ Note that the @file{amsmath} package has significantly more extensive
displayed equation facilities. For example, there are a number of
ways in that package for having math text broken across lines.
-The construct @code{\[@var{math text}\]} is essentially a synonym for
-@code{\begin@{displaymath@}@var{math text}\end@{displaymath@}} but the
-latter is easier to work with in the source file; for instance,
+@findex \[...\] @r{display math}
+The construct @code{\[@var{math}\]} is a synonym for the environment
+@code{\begin@{displaymath@} @var{math} \end@{displaymath@}} 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
-@code{displaymath} will likely be unique. (The construct
-@code{$$@var{math text}$$} from Plain@tie{}@TeX{} is sometimes
-mistakenly used as a synonym for @code{displaymath}. It is not a
-synonym, because the @code{displaymath} environment checks that it isn't
-started in math mode and that it ends in math mode begun by the matching
-environment start, because the @code{displaymath} environment has
-different vertical spacing, and because the @code{displaymath}
-environment honors the @code{fleqn} option.)
+@code{displaymath} will likely be unique.
+
+@findex $$...$$ @r{plain @TeX{} display math}
+(Aside: The construct @code{$$@var{math}$$} from Plain@tie{}@TeX{} is
+sometimes mistakenly used as a synonym for @code{displaymath}. It is
+not a synonym, and is not officially supported in @LaTeX{} at all;
+@code{$$} doesn't support the @code{fleqn} option (@pxref{Document
+class options}), has different vertical spacing, and doesn't perform
+consistency checks.)
The output from this example is centered and alone on its line.
@@ -4247,7 +5132,7 @@ For a list of counter-labeling commands see @ref{\alph \Alph \arabic
The @code{eqnarray} environment is obsolete. It has infelicities,
including spacing that is inconsistent with other mathematics elements.
(See ``Avoid eqnarray!''@: by Lars Madsen
-@url{http://tug.org/TUGboat/tb33-1/tb103madsen.pdf}). New documents
+@url{https://tug.org/TUGboat/tb33-1/tb103madsen.pdf}). New documents
should include the @file{amsmath} package and use the displayed
mathematics environments provided there, such as the @code{align}
environment. We include a description only for completeness and for
@@ -4409,7 +5294,7 @@ end of the document, on a page of floats.
@node filecontents
-@section @code{filecontents}: Write an external file
+@section @code{filecontents}
@EnvIndex{filecontents}
@EnvIndex{filecontents*}
@@ -4419,7 +5304,7 @@ end of the document, on a page of floats.
Synopsis:
@example
-\begin@{filecontents@}@{@var{filename}@}
+\begin@{filecontents@}[@var{option}]@{@var{filename}@}
@var{text}
\end@{filecontents@}
@end example
@@ -4428,29 +5313,52 @@ Synopsis:
or
@example
-\begin@{filecontents*@}@{@var{filename}@}
+\begin@{filecontents*@}[@var{option}]@{@var{filename}@}
@var{text}
\end@{filecontents*@}
@end example
-Create a file named @var{filename} and fill it with @var{text}. The
-unstarred version of the environment @code{filecontents} prefixes the
-content of the created file with a header; see the example below. The
-starred version @code{filecontents*} does not include the header.
+Create a file named @var{filename} in the current directory (or the
+output directory, if specified; @pxref{output directory}) and write
+@var{text} to it. By default, an existing file is not overwritten.
+
+The unstarred version of the environment
+@code{filecontents} prefixes the content of the created file with a
+header of @TeX{} comments; see the example below. The starred
+version @code{filecontents*} does not include the header.
+
+The possible options are:
+
+@table @code
+@item force
+@itemx overwrite
+@cindex @code{force} option for @code{filecontents}
+@cindex @code{overwrite} option for @code{filecontents}
+Overwrite an existing file.
+
+@item noheader
+@cindex @code{noheader} option for @code{filecontents}
+Omit the header. Equivalent to using @code{filecontents*}.
+
+@item nosearch
+@cindex @code{nosearch} option for @code{filecontents}
+Only check the current directory (and the output directory, if
+specified) for an existing file, not the entire search path.
-This environment can be used anywhere in the preamble, although it often
-appears before the @code{\documentclass} command. It is typically used
-when a source file requires a nonstandard style or class file. The
-environment will write that file to the directory containing the source
-and thus make the source file self-contained. Another use is to include
-@code{bib} references in the file, again to make it self-contained.
+@end table
-The environment checks whether a file of that name already exists and if
-so, does not do anything. There is a @file{filecontents} package that
-redefines the @code{filecontents} environment so that instead of doing
-nothing in that case, it will overwrite the existing file.
+These options were added in a 2019 release of @LaTeX{}.
-For example, this document
+@cindex self-contained sources
+@cindex source files, making self-contained
+This environment can be used anywhere in the preamble, although it
+often appears before the @code{\documentclass} command. It is
+commonly used to create a @code{.bib} or other such data file from the
+main document source, to make the source file self-contained.
+Similarly, it can be used to create a custom style or class file,
+again making the source self-contained.
+
+For example, this document:
@example
\documentclass@{article@}
@@ -4464,7 +5372,7 @@ Article by \myname.
@end example
@noindent
-produces this file @file{JH.sty}.
+produces this file @file{JH.sty}:
@example
%% LaTeX2e file `JH.sty'
@@ -4496,7 +5404,7 @@ Synopsis:
An environment that creates a paragraph whose lines are flush to the
left-hand margin, and ragged right. If you have lines that are too long
then @LaTeX{} will linebreak them in a way that avoids hyphenation and
-stretching or shrinking spaces. To force a new line use a double
+stretching or shrinking interword spaces. To force a new line use a double
backslash, @code{\\}. For the declaration form
see@tie{}@ref{\raggedright}.
@@ -4543,7 +5451,7 @@ or
@end example
A declaration which causes lines to be flush to the left margin and
-ragged right. It can be used inside an environment such as @code{quote}
+ragged right. It can be used inside an @var{environment} such as @code{quote}
or in a @code{parbox}. For the environment form
see@tie{}@ref{flushleft}.
@@ -4586,11 +5494,13 @@ delimit its effect.
An environment that creates a paragraph whose lines are flush to the
right-hand margin and ragged left. If you have lines that are too long
to fit the margins then @LaTeX{} will linebreak them in a way that
-avoids hyphenation and stretching or shrinking spaces. To force a new
+avoids hyphenation and stretching or shrinking inter-word spaces. To force a new
line use a double backslash, @code{\\}. For the declaration form
see@tie{}@ref{\raggedleft}.
-For an example related to this environment, see@tie{}@ref{flushleft}.
+For an example related to this environment, see@tie{}@ref{flushleft},
+where one just have mutatis mutandis to replace @code{flushleft} by
+@code{flushright}.
@menu
* \raggedleft:: Declaration form of the @code{flushright} environment.
@@ -4621,7 +5531,7 @@ or
@end example
A declaration which causes lines to be flush to the right margin and
-ragged left. It can be used inside an environment such as @code{quote}
+ragged left. It can be used inside an @var{environment} such as @code{quote}
or in a @code{parbox}. For the environment form
see@tie{}@ref{flushright}.
@@ -4631,7 +5541,9 @@ formats paragraph units. To affect a paragraph unit's format, the
scope of the declaration must contain the blank line or @code{\end}
command that ends the paragraph unit.
-For an example related to this environment, see@tie{}@ref{\raggedright}.
+For an example related to this environment, see@tie{}@ref{\raggedright},
+where one just have mutatis mutandis to replace @code{\raggedright} by
+@code{\raggedleft}.
@node itemize
@@ -4654,8 +5566,8 @@ Synopsis:
\end@{itemize@}
@end example
-Produce a list that is unordered, sometimes called a bullet list. The
-environment must have at least one @code{\item}; having none causes the
+Produce an @dfn{unordered list}, sometimes called a bullet list. There
+must be at least one @code{\item} within the environment; having none causes the
@LaTeX{} error @samp{Something's wrong--perhaps a missing \item}.
This gives a two-item list.
@@ -4668,17 +5580,23 @@ This gives a two-item list.
@end example
@noindent
-As a top-level list each label would come out as a bullet, @bullet{}.
-The format of the labeling depends on the nesting level; see below.
+With the default locale---without loading e.g.@: @file{babel} package
+with another language than USenglish---as a top-level list each label
+would come out as a bullet, @bullet{}. The format of the labeling
+depends on the nesting level; see below.
@findex \item
Start list items with the @code{\item} command (@pxref{\item}). If you
give @code{\item} an optional argument by following it with square
-brackets, as in @code{\item[Optional label]}, then by default it will
-appear in bold and be flush right, so it could extend into the left
-margin. For labels that are flush left see the @ref{description}
-environment. Following the @code{\item} is optional text, which may
-contain multiple paragraphs.
+brackets, as in @code{\item[@var{Optional label}]}, then by default
+@var{Optional label} will appear in bold and be flush right, so it could
+extend into the left margin. For labels that are flush left see the
+@ref{description} environment. Following the @code{\item} is the text of
+the item, which may be empty or contain multiple paragraphs.
+
+Unordered lists can be nested within one another, up to four levels deep.
+They can also be nested within other paragraph-making environments, such
+as @code{enumerate} (@pxref{enumerate}).
@findex \labelitemi
@findex \labelitemii
@@ -4688,23 +5606,21 @@ contain multiple paragraphs.
@anchor{itemize labelitemii}
@anchor{itemize labelitemiii}
@anchor{itemize labelitemiv}
-Itemized lists can be nested within one another, up to four levels deep.
-They can also be nested within other paragraph-making environments, such
-as @code{enumerate} (@pxref{enumerate}). The @code{itemize} environment
-uses the commands @code{\labelitemi} through @code{\labelitemiv} to
-produce the default label (this also uses the convention of lowercase
-roman numerals at the end of the command names that signify the nesting
-level). These are the default marks at each level.
+The @code{itemize} environment uses the commands @code{\labelitemi}
+through @code{\labelitemiv} to produce the default label (note the
+convention of lowercase roman numerals at the end of the command names
+that signify the nesting level). These are the default marks at each
+level.
@enumerate
@item @bullet{} (bullet, from @code{\textbullet})
@item @b{-@w{-}} (bold en-dash, from @code{\normalfont\bfseries\textendash})
@item * (asterisk, from @code{\textasteriskcentered})
@iftex
-@item @math{\cdot} (centered dot, from @code{\textperiodcentered})
+@item @math{\cdot} (vertically centered dot, from @code{\textperiodcentered})
@end iftex
@ifnottex
-@item . (centered dot, rendered here as a period, from @code{\textperiodcentered})
+@item . (vertically centered dot, rendered here as a period, from @code{\textperiodcentered})
@end ifnottex
@end enumerate
@@ -4731,18 +5647,20 @@ the first level use diamonds.
@anchor{itemize leftmarginvi}
The distance between the left margin of the enclosing environment and
the left margin of the @code{itemize} list is determined by the
-parameters @code{\leftmargini} through @code{\leftmarginvi}. (Note the
-convention of using lowercase roman numerals a the end of the command
-name to denote the nesting level.) The defaults are: @code{2.5em} in
-level 1 (@code{2em} in two-column mode), @code{2.2em} in level 2,
-@code{1.87em} in level 3, and @code{1.7em} in level 4, with smaller
-values for more deeply nested levels.
+parameters @code{\leftmargini} through @code{\leftmarginvi}. (This also
+uses the convention of using lowercase roman numerals a the end of the
+command name to denote the nesting level.) The defaults are:
+@code{2.5em} in level 1 (@code{2em} in two-column mode), @code{2.2em} in
+level 2, @code{1.87em} in level 3, and @code{1.7em} in level 4, with
+smaller values for more deeply nested levels.
+@PkgIndex{enumitem}
For other major @LaTeX{} labeled list environments, see
-@ref{description} and @ref{enumerate}. For information about list
-layout parameters, including the default values, and for information
-about customizing list layout, see @ref{list}. The package
-@file{enumitem} is useful for customizing lists.
+@ref{description} and @ref{enumerate}. The @code{itemize},
+@code{enumerate} and @code{description} environment use the same list
+layout parameters. For a description, including the default values, and
+for information about customizing list layout, see @ref{list}. The
+package @file{enumitem} is useful for customizing lists.
This example greatly reduces the margin space for outermost itemized
lists.
@@ -4827,11 +5745,11 @@ environment.
The mandatory first argument @var{labeling} specifies the default
labeling of list items. It can contain text and @LaTeX{} commands, as
-above where it contains both @samp{Item} and @samp{\Roman@{...@}}.
+above where it contains both @samp{Item} and @samp{\Roman@{@dots{}@}}.
@LaTeX{} forms the label by putting the @var{labeling} argument in a box
of width @code{\labelwidth}. If the label is wider than that, the
additional material extends to the right. When making an instance of a
-list you can override the default labeling by giving @code{\item} an
+@code{list} you can override the default labeling by giving @code{\item} an
optional argument by including square braces and the text, as in the
above @code{\item[Special label.]}; @pxref{\item}.
@@ -4853,7 +5771,7 @@ definition of the environment add
@code{\newcommand@{\namedmakelabel@}[1]@{\textsc@{#1@}@}}, and between
the @code{\setlength} command and the parenthesis that closes the
@var{spacing} argument also add @code{\let\makelabel\namedmakelabel}.
-Then the items will be typeset in small caps. Similarly, changing the
+Then the labels will be typeset in small caps. Similarly, changing the
second code line to @code{\let\makelabel\fbox} puts the labels inside a
framed box. Another example of the @code{\makelabel} command is below,
in the definition of the @code{redlabel} environment.
@@ -4882,7 +5800,7 @@ and @samp{report} classes at 10 point size are: @code{4pt plus2pt
minus1pt}, @code{\parsep} (that is, @code{2pt plus1pt minus1pt}), and
@code{\topsep} (that is, @code{2pt plus1pt minus1pt}). The defaults at
11 point are: @code{4.5pt plus2pt minus1pt}, @code{\parsep} (that is,
-@code{2pt plus1pt minus1pt}), and @code{topsep} (that is, @code{2pt
+@code{2pt plus1pt minus1pt}), and @code{\topsep} (that is, @code{2pt
plus1pt minus1pt}). The defaults at 12 point are: @code{5pt plus2.5pt
minus1pt}, @code{\parsep} (that is, @code{2.5pt plus1pt minus1pt}), and
@code{\topsep} (that is, @code{2.5pt plus1pt minus1pt}).
@@ -4941,15 +5859,14 @@ item. A negative value makes this an ``outdent''. Its default value
is @code{0pt}.
@item \parsep
-@anchor{list parsep}
-Vertical space between paragraphs within an item. In the @samp{book}
-and @samp{article} classes The defaults for the first three levels in
-@LaTeX{}'s @samp{article}, @samp{book}, and @samp{report} classes at 10
-point size are: @code{4pt plus2pt minus1pt}, @code{2pt plus1pt
-minus1pt}, and @code{0pt}. The defaults at 11 point size are:
-@code{4.5pt plus2pt minus1pt}, @code{2pt plus1pt minus1pt}, and
-@code{0pt}. The defaults at 12 point size are: @code{5pt plus2.5pt
-minus1pt}, @code{2.5pt plus1pt minus1pt}, and @code{0pt}.
+@anchor{list parsep} Vertical space between paragraphs within an item.
+The defaults for the first three levels in @LaTeX{}'s @samp{article},
+@samp{book}, and @samp{report} classes at 10 point size are: @code{4pt
+plus2pt minus1pt}, @code{2pt plus1pt minus1pt}, and @code{0pt}. The
+defaults at 11 point size are: @code{4.5pt plus2pt minus1pt},
+@code{2pt plus1pt minus1pt}, and @code{0pt}. The defaults at 12 point
+size are: @code{5pt plus2.5pt minus1pt}, @code{2.5pt plus1pt
+minus1pt}, and @code{0pt}.
@item \partopsep
@anchor{list partopsep}
@@ -5088,7 +6005,7 @@ edge of the label lines up with the left edge of the item text.
\let\makelabel=\makeredlabel
@}
@}
-@{\end@{list@} @}
+@{\end@{list@}@}
@end example
@menu
@@ -5117,7 +6034,7 @@ An entry in a list. The entries are prefixed by a label, whose default
depends on the list type.
Because the optional label is surrounded by square brackets
-@samp{[...]}, if you have an item whose text starts with @samp{[}, you
+@samp{[...]}, if you have an item whose text starts with [, you
have to hide the bracket inside curly braces, as in: @code{\item
@{[@} is an open square bracket}; otherwise, @LaTeX{} will think it
marks the start of an optional label.
@@ -5158,7 +6075,7 @@ Synopsis:
A restricted version of the list environment, in which margins are not
indented and an @code{\item} without an optional argument produces no
text. It is most often used in macros, to define an environment where
-the @code{\item} command as part of the environment's definition. For
+the @code{\item} command is part of the environment's definition. For
instance, the @code{center} environment is defined essentially like
this:
@@ -5195,7 +6112,7 @@ default) they have no paragraph indent and are vertically separated.
@section @code{math}
@EnvIndex{math}
-@cindex in-line formulas
+@cindex inline formulas
Synopsis:
@@ -5205,6 +6122,8 @@ Synopsis:
\end@{math@}
@end example
+@findex $ @r{inline math}
+@findex \(...\) @r{inline math}
The @code{math} environment inserts given @var{math} material within
the running text. @code{\(...\)} and @code{$...$} are synonyms.
@xref{Math formulas}.
@@ -5262,25 +6181,31 @@ It gives the width of the box into which @var{contents} are typeset.
There are three optional arguments, @var{position}, @var{height}, and
@var{inner-pos}. You need not include all three. For example, get the
default @var{position} and set the @var{height} with
-@code{\begin@{minipage@}[c][2.54cm] @var{contents} \end@{minipage@}}.
-(Get the natural height with an empty argument, @code{[]}.)
+@code{\begin@{minipage@}[c][2.54cm]@{\columnwidth@} @var{contents}
+\end@{minipage@}}. (Get the natural height with an empty argument,
+@code{[]}.)
The optional argument @var{position} governs how the @code{minipage}
vertically aligns with the surrounding material.
@table @code
@item c
+@c xx Clarify what it means when adjacent text lines do not have aligned
+@c vertical center with each other
(synonym @code{m}) Default. Positions the @code{minipage} so its
-vertical center lines up with the center of the adjacent text line (what
-Plain @TeX{} calls @code{\vcenter}).
+vertical center lines up with the center of the adjacent text line.
@item t
+@findex \vtop @r{plain @TeX{}}
+@c xx Is there any reason why the word ``match'' is used instead of word
+@c ``align''. Do we mean some more permissive alignment?
Match the top line in the @code{minipage} with the baseline of the
-surrounding text (Plain @TeX{}'s @code{\vtop}.
+surrounding text (plain @TeX{}'s @code{\vtop}).
@item b
+@findex \vbox @r{plain @TeX{}}
Match the bottom line in the @code{minipage} with the baseline of the
-surrounding text (Plain @TeX{}'s @code{\vbox}.
+surrounding text (plain @TeX{}'s @code{\vbox}).
@end table
To see the effects of these, contrast running this
@@ -5294,6 +6219,8 @@ To see the effects of these, contrast running this
@noindent
with the results of changing @code{c} to @code{b} or@tie{}@code{t}.
+@c xx Clarify what happens if user enter a rubber length instead of a
+@c rigid length.
The optional argument @var{height} is a rigid length (@pxref{Lengths}).
It sets the height of the @code{minipage}. You can enter any value
larger than, or equal to, or smaller than the @code{minipage}'s natural
@@ -5301,12 +6228,12 @@ height and @LaTeX{} will not give an error or warning. You can also set
it to a height of zero or a negative value.
The final optional argument @var{inner-pos} controls the placement of
-@var{content} inside the box. These are the possible values are (the
+@var{contents} inside the box. These are the possible values are (the
default is the value of @var{position}).
@table @code
@item t
-Place @var{content} at the top of the box.
+Place @var{contents} at the top of the box.
@item c
Place it in the vertical center.
@@ -5376,20 +6303,28 @@ Footnotes appear at the bottom of the text ended by the next
This puts a table containing data side by side with a map graphic. They
are vertically centered.
+@PkgIndex{siunitx}
@example
+% siunitx to have the S column specifier,
+% which aligns numbers on their decimal point.
+\usepackage@{siunitx@}
\newcommand*@{\vcenteredhbox@}[1]@{\begin@{tabular@}@{@@@{@}c@@@{@}@}#1\end@{tabular@}@}
...
\begin@{center@}
\vcenteredhbox@{\includegraphics[width=0.3\textwidth]@{nyc.png@}@}
\hspace@{0.1\textwidth@}
\begin@{minipage@}@{0.5\textwidth@}
- \begin@{tabular@}@{r|l@}
- \multicolumn@{1@}@{r@}@{Borough@} &Pop (million) \\ \hline
- The Bronx &$1.5$ \\
- Brooklyn &$2.6$ \\
- Manhattan &$1.6$ \\
- Queens &$2.3$ \\
- Staten Island &$0.5$
+ \begin@{tabular@}@{r|S@}
+ % \multicolumn to remove vertical bar between column headers
+ \multicolumn@{1@}@{r@}@{Borough@} &
+ % braces to prevent siunitx from misinterpreting the
+ % period as a decimal separator
+ @{Pop. (million)@} \\ \hline
+ The Bronx &1.5 \\
+ Brooklyn &2.6 \\
+ Manhattan &1.6 \\
+ Queens &2.3 \\
+ Staten Island &0.5
\end@{tabular@}
\end@{minipage@}
\end@{center@}
@@ -5406,7 +6341,7 @@ are vertically centered.
Synopses:
@example
\begin@{picture@}(@var{width},@var{height})
- @var{picture commands}
+ @var{picture command}
\end@{picture@}
@end example
@@ -5415,17 +6350,20 @@ or
@example
\begin@{picture@}(@var{width},@var{height})(@var{xoffset},@var{yoffset})
- @var{picture commands}
+ @var{picture command}
\end@{picture@}
@end example
+@noindent
+Where there may be any number of @var{picture command}'s.
+
An environment to create simple pictures containing lines, arrows,
-boxes, circles, and text. Note that while this environment is not
-obsolete, new documents typically use much more powerful graphics
-creation systems, such as @code{TikZ}, @code{PSTricks}, @code{MetaPost},
-or @code{Asymptote}. These are not covered in this document; see CTAN.
+boxes, circles, and text. This environment is not obsolete, but new
+documents typically use much more powerful graphics creation systems,
+such as TikZ, PSTricks, MetaPost, or Asymptote. None of these are
+covered in this document; see CTAN.
-This shows the parallelogram law for adding vectors.
+To start, here's an example showing the parallelogram law for adding vectors.
@findex \unitlength
@example
@@ -5435,45 +6373,25 @@ This shows the parallelogram law for adding vectors.
\put(2,1)@{\makebox(0,0)[l]@{\ first leg@}@}
\put(4,2)@{\vector(1,2)@{2@}@}
\put(5,4)@{\makebox(0,0)[l]@{\ second leg@}@}
- \put(0,0)@{\line(1,1)@{6@}@}
+ \put(0,0)@{\vector(1,1)@{6@}@}
\put(3,3)@{\makebox(0,0)[r]@{sum\ @}@}
\end@{picture@}
@end example
-You can also use this environment to place arbitrary material at an
-exact location.
-
-@example
-\usepackage@{color,graphicx@} % in preamble
- ...
-\begin@{center@}
-\setlength@{\unitlength@}@{\textwidth@}
-\begin@{picture@}(1,1) % leave space, \textwidth wide and tall
- \put(0,0)@{\includegraphics[width=\textwidth]@{desertedisland.jpg@}@}
- \put(0.25,0.35)@{\textcolor@{red@}@{X Treasure here@}@}
-\end@{picture@}
-\end@{center@}
-@end example
-
-@noindent
-The red@tie{}X will be precisely a quarter of the @code{\linewidth} from
-the left margin, and @code{0.35\linewidth} up from the bottom. Another
-example of this usage is to put similar code in the page header to get
-repeat material on each of a document's pages.
-
The @code{picture} environment has one required argument, a pair of
-numbers (@var{width},@var{height}). Multiply these by the value
-@code{\unitlength} to get the nominal size of the output, the space that
-@LaTeX{} reserves on the output page. This nominal size need not be how
-large the picture really is; @LaTeX{} will draw things from the picture
-outside the picture's box.
+positive real numbers (@var{width},@var{height}). Multiply these by the
+value @code{\unitlength} to get the nominal size of the output, i.e.@:
+the space that @LaTeX{} reserves on the output page. This nominal size
+need not be how large the picture really is; @LaTeX{} will draw things
+from the picture outside the picture's box.
This environment also has an optional argument
(@var{xoffset},@var{yoffset}). It is used to shift the origin. Unlike
most optional arguments, this one is not contained in square brackets.
-As with the required argument, it consists of two real numbers.
-Multiply these by @code{\unitlength} to get the point at the lower-left
-corner of the picture.
+As with the required argument, it consists of a pair of two real
+numbers, but these may also be negative or null. Multiply these
+by @code{\unitlength} to get the coordinates of the point at the
+lower-left corner of the picture.
For example, if @code{\unitlength} has been set to @code{1mm}, the
command
@@ -5493,24 +6411,27 @@ optional argument.
@cindex position, in picture
Each @var{picture command} tells @LaTeX{} where to put something by
-naming its position. A @dfn{position} is a pair such as @code{(2.4,-5)}
+providing its position. A @dfn{position} is a pair such as @code{(2.4,-5)}
giving the x- and y-coordinates. A @dfn{coordinate} is a not a length,
it is a real number (it may have a decimal point or a minus sign). It
specifies a length in multiples of the unit length @code{\unitlength},
so if @code{\unitlength} has been set to @code{1cm}, then the coordinate
-2.54 specifies a length of 2.54 centimeters.
+@code{2.54} specifies a length of 2.54 centimeters.
-@LaTeX{}'s default for @code{\unitlength} is @code{1pt}. it is a rigid
+@LaTeX{}'s default for @code{\unitlength} is @code{1pt}. It is a rigid
length (@pxref{Lengths}). Change it with the @code{\setlength} command
(@pxref{\setlength}). Make this change only outside of a @code{picture}
environment.
-Coordinates are given with respect to an origin, which is normally at
+The @code{picture} environment supports using standard arithmetic
+expressions as well as numbers.
+
+Coordinates are given with respect to an origin, which is by default at
the lower-left corner of the picture. Note that when a position appears
as an argument, as with @code{\put(1,2)@{...@}}, it is not enclosed in
braces since the parentheses serve to delimit the argument. Also,
unlike in some computer graphics systems, larger y-coordinates are
-further up the page.
+further up the page, for example, @math{y = 1} is @emph{above} @math{y = 0}.
There are four ways to put things in a picture: @code{\put},
@code{\multiput}, @code{\qbezier}, and @code{\graphpaper}. The most
@@ -5547,27 +6468,31 @@ line of length one; rather the line has a change in the x coordinate of
The @code{\multiput}, @code{qbezier}, and @code{graphpaper} commands are
described below.
-This draws a rectangle with a wavy top, using @code{\qbezier} for
-that curve.
+You can also use this environment to place arbitrary material at an
+exact location. For example:
@example
-\begin@{picture@}(3,1.5)
- \put(0,0)@{\vector(1,0)@{8@}@} % x axis
- \put(0,0)@{\vector(0,1)@{4@}@} % y axis
- \put(2,0)@{\line(0,1)@{3@}@} % left side rectangle
- \put(4,0)@{\line(0,1)@{3.5@}@} % right side
- \qbezier(2,3)(2.5,2.9)(3,3.25)
- \qbezier(3,3.25)(3.5,3.6)(4,3.5)
- \thicklines % below here, lines are twice as thick
- \put(2,3)@{\line(4,1)@{2@}@}
- \put(4.5,2.5)@{\framebox@{Trapezoidal Rule@}@}
+\usepackage@{color,graphicx@} % in preamble
+ ...
+\begin@{center@}
+\setlength@{\unitlength@}@{\textwidth@}
+\begin@{picture@}(1,1) % leave space, \textwidth wide and tall
+ \put(0,0)@{\includegraphics[width=\textwidth]@{desertedisland.jpg@}@}
+ \put(0.25,0.35)@{\textcolor@{red@}@{X Treasure here@}@}
\end@{picture@}
+\end@{center@}
@end example
+@noindent
+The red@tie{}X will be precisely a quarter of the @code{\textwidth} from
+the left margin, and @code{0.35\textwidth} up from the bottom of the
+picture. Another example of this usage is to put similar code in the
+page header to get repeat material on each of a document's pages.
+
@menu
* \put:: Place an object at a specified place.
* \multiput:: Draw multiple instances of an object.
-* \qbezier:: Draw a quadratic Bezier curve.
+* \qbezier:: Draw a quadratic B@'ezier curve.
* \graphpaper:: Draw graph paper.
* \line:: Draw a straight line.
* \linethickness:: Set thickness of horizontal and vertical lines.
@@ -5674,6 +6599,22 @@ intermediate points. The default is to draw a smooth curve whose
maximum number of points is @code{\qbeziermax} (change this value with
@code{\renewcommand}).
+This draws a rectangle with a wavy top, using @code{\qbezier} for
+that curve.
+
+@example
+\begin@{picture@}(8,4)
+ \put(0,0)@{\vector(1,0)@{8@}@} % x axis
+ \put(0,0)@{\vector(0,1)@{4@}@} % y axis
+ \put(2,0)@{\line(0,1)@{3@}@} % left side
+ \put(4,0)@{\line(0,1)@{3.5@}@} % right side
+ \qbezier(2,3)(2.5,2.9)(3,3.25)
+ \qbezier(3,3.25)(3.5,3.6)(4,3.5)
+ \thicklines % below here, lines are twice as thick
+ \put(2,3)@{\line(4,1)@{2@}@}
+ \put(4.5,2.5)@{\framebox@{Trapezoidal Rule@}@}
+\end@{picture@}
+@end example
@node \graphpaper
@subsection @code{\graphpaper}
@@ -5686,7 +6627,8 @@ Synopsis:
\graphpaper[@var{spacing}](@var{x_init},@var{y_init})(@var{x_dimen},@var{y_dimen})
@end example
-Draw a coordinate grid. Requires the @code{graphpap} package.
+@PkgIndex{graphpap}
+Draw a coordinate grid. Requires the @file{graphpap} package.
The grid's origin is @code{(@var{x_init},@var{y_init})}.
Grid lines come every @var{spacing} units (the default is 10).
The grid extends @var{x_dimen} units to the right and @var{y_dimen} units up.
@@ -5719,7 +6661,7 @@ Synopsis:
Draw a line. It slopes such that it vertically rises @var{y_rise} for
every horizontal @var{x_run}. The @var{travel} is the total horizontal
-change@tie{}--- it is not the length of the vector, it is the change in
+change---it is not the length of the vector, it is the change in
@math{x}. In the special case of vertical lines, where
(@var{x_run},@var{y_rise})=(0,1), the @var{travel} gives the change in
@math{y}.
@@ -5764,9 +6706,10 @@ relatively prime, so that @var{(x_run,y_rise)} can be (2,1) but not
(4,2) (if you choose the latter then instead of lines you get sequences
of arrowheads; the solution is to switch to the former). To get lines
of arbitrary slope and plenty of other shapes in a system like
-@code{picture}, see the package @file{pict2e} on CTAN. Another solution
-is to use a full-featured graphics system such as @file{TikZ}, or
-@file{PSTricks}, or @file{MetaPost}, or @file{Asymptote}
+@code{picture}, see the package @file{pict2e}
+(@url{https://ctan.org/pkg/pict2e}). Another solution
+is to use a full-featured graphics system such as TikZ, PSTricks,
+MetaPost, or Asymptote.
@node \linethickness
@@ -5830,8 +6773,8 @@ This draws a circle of radius 6, centered at @code{(5,7)}.
\put(5,7)@{\circle@{6@}@}
@end example
-The available radii for @code{circle} are, in points, the even
-numbers from 2 to 20, inclusive. For @code{circle*} they are all the
+The available radii for @code{\circle} are, in points, the even
+numbers from 2 to 20, inclusive. For @code{\circle*} they are all the
integers from 1 to 15.
@@ -5947,7 +6890,7 @@ Synopsis:
Draw a line ending in an arrow. The slope of that line is: it
vertically rises @var{y_rise} for every horizontal @var{x_run}. The
-@var{travel} is the total horizontal change@tie{}--- it is not the
+@var{travel} is the total horizontal change---it is not the
length of the vector, it is the change in @math{x}. In the special case
of vertical vectors, if (@var{x_run},@var{y_rise})=(0,1), then
@var{travel} gives the change in @math{y}.
@@ -6162,6 +7105,8 @@ between paragraphs (it is the rubber length @code{\parsep}).
@node tabbing
@section @code{tabbing}
+@c xx TODO align on the French which is more precise and has more illustrative examples.
+
@EnvIndex{tabbing}
@cindex tab stops, using
@cindex lining text up using tab stops
@@ -6188,12 +7133,12 @@ widths, ended by a @code{\kill} command (which is described below):
@example
\begin@{tabbing@}
-\hspace@{0.75in@} \= \hspace@{0.40in@} \= \hspace@{0.40in@} \kill
-Ship \> Guns \> Year \\
-\textit@{Sophie@} \> 14 \> 1800 \\
-\textit@{Polychrest@} \> 24 \> 1803 \\
-\textit@{Lively@} \> 38 \> 1804 \\
-\textit@{Surprise@} \> 28 \> 1805 \\
+\hspace@{1.2in@}\=\hspace@{1in@}\=\kill
+Ship \>Guns \>Year \\
+\textit@{Sophie@} \>14 \>1800 \\
+\textit@{Polychrest@} \>24 \>1803 \\
+\textit@{Lively@} \>38 \>1804 \\
+\textit@{Surprise@} \>28 \>1805 \\
\end@{tabbing@}
@end example
@@ -6204,10 +7149,10 @@ determined automatically by @LaTeX{}, while in @code{tabbing} the user
sets the tab stops. Another distinction is that @code{tabular}
generates a box, but @code{tabbing} can be broken across pages.
Finally, while @code{tabular} can be used in any mode, @code{tabbing}
-can be used only in paragraph mode and it starts a new paragraph.
+can be used only in paragraph mode and it always starts a new paragraph,
+without indentation.
-A @code{tabbing} environment always starts a new paragraph, without
-indentation. Moreover, as shown in the example above, there is no need
+Moreover, as shown in the example above, there is no need
to use the starred form of the @code{\hspace} command at the beginning
of a tabbed row. The right margin of the @code{tabbing} environment is
the end of line, so that the width of the environment is
@@ -6220,8 +7165,9 @@ rows}. The first tabbed row begins immediately after
@code{\kill}. The last row may omit the @code{\\} and end with just
@code{\end@{tabbing@}}.
-At any point the @code{tabbing} environment has a current tab stop
-pattern, a sequence of @math{@var{n} > 0} tab stops, numbered 0, 1,
+@cindex pattern, current tab stops, @r{tabbing}
+At any point the @code{tabbing} environment has a @dfn{current tab stop
+pattern}, a sequence of @math{@var{n} > 0} tab stops, numbered 0, 1,
etc. These create @var{n} corresponding columns. Tab stop@tie{}0 is
always the left margin, defined by the enclosing environment. Tab
stop number@tie{}@var{i} is set if it is assigned a horizontal
@@ -6380,20 +7326,18 @@ This example @code{table} environment contains a @code{tabular}
@end example
@noindent
-but you can put many different kinds of content in a @code{table},
-including text, @LaTeX{} commands, etc.
+but you can put many different kinds of content in a @code{table}:
+the @var{table body} may contain text, @LaTeX{} commands, graphics, etc. It is
+typeset in a @code{parbox} of width @code{\textwidth}.
For the possible values of @var{placement} and their effect on the
float placement algorithm, see @ref{Floats}.
-The table body is typeset in a @code{parbox} of width @code{\textwidth}.
-It can contain text, commands, graphics, etc.
-
The label is optional; it is used for cross references (@pxref{Cross
references}).
@findex \caption
The @code{\caption} command is also optional. It specifies caption text
-for the table. By default it is numbered. If its optional
+@var{title} for the table. By default it is numbered. If its optional
@var{lottitle} is present then that text is used in the list of tables
instead of @var{title} (@pxref{Table of contents etc.}).
@@ -6457,7 +7401,7 @@ illustrates many of the features.
The output will have two left-aligned columns with a vertical bar
between them. This is specified in @code{tabular}'s argument
@code{@{l|l@}}.
-@findex &
+@findex & @r{for table cells}
Put the entries into different columns by separating them with an
ampersand, @code{&}. The end of each row is marked with a double
backslash, @code{\\}. Put a horizontal rule below a row, after a double
@@ -6573,7 +7517,7 @@ a @code{\centering}, @code{\raggedright}, or @code{\raggedleft}
declaration (when used in a @code{p}-column element these declarations
must appear inside braces, as with @code{@{\centering .. \\
..@}}). Otherwise @LaTeX{} will misinterpret the double backslash as
-ending the row. Instead, to get a line break in there use
+ending the tabular row. Instead, to get a line break in there use
@code{\newline} (@pxref{\newline}).
@item *@{@var{num}@}@{@var{cols}@}
@@ -6836,7 +7780,7 @@ Synopsis:
Produce a bibliography or reference list. There are two ways to produce
bibliographic lists. This environment is suitable when you have only a
-few references and can maintain the list by hand. @xref{Using BibTeX}
+few references and can maintain the list by hand. @xref{Using BibTeX},
for a more sophisticated approach.
This shows the environment with two entries.
@@ -6859,15 +7803,17 @@ Together they are \cite@{latexdps, texbook@}.
@noindent
This styles the first reference as @samp{[1] Leslie ...}, and so that
-@code{\cite@{latexdps@}} produces the matching @samp{... based on [1]}.
-The second @code{\cite} produces @samp{[1, 2]}. You must compile the
-document twice to resolve these references.
+@code{... based on \cite@{latexdps@}} produces the matching
+@samp{... based on [1]}. The second @code{\cite} produces @samp{[1,
+2]}. You must compile the document twice to resolve these references.
The mandatory argument @var{widest-label} is text that, when typeset, is
as wide as the widest item label produced by the @code{\bibitem}
commands. The tradition is to use @code{9} for bibliographies with less
than 10 references, @code{99} for ones with less than 100, etc.
+@findex \bibname
+@findex \refname
The bibliographic list is headed by a title such as @samp{Bibliography}.
To change it there are two cases. In the @file{book} and @file{report}
classes, where the top level sectioning is @code{\chapter} and the
@@ -6875,7 +7821,7 @@ default title is @samp{Bibliography}, that title is in the macro
@code{\bibname}. For @file{article}, where the class's top level
sectioning is @code{\section} and the default is @samp{References}, the
title is in macro @code{\refname}. Change it by redefining the command,
-as with @code{\renewcommand@{\refname@}@{Cited references@}} after
+as with @code{\renewcommand@{\refname@}@{Cited references@}}, after
@code{\begin@{document@}}.
@PkgIndex{babel}
@@ -6883,6 +7829,8 @@ Language support packages such as @file{babel} will automatically
redefine @code{\refname} or @code{\bibname} to fit the selected
language.
+@xref{list}, for the list layout control parameters.
+
@menu
* \bibitem:: Specify a bibliography item.
* \cite:: Refer to a bibliography item.
@@ -6909,16 +7857,16 @@ or
\bibitem[@var{label}]@{@var{cite_key}@}
@end example
-Generate an entry labeled by @var{label}. The default is for @LaTeX{} to
-generates a number using the @code{enumi} counter. The @dfn{citation key}
+Generate an entry labeled by default by a number generated using the
+@code{enumi} counter. The @dfn{citation key}
@cindex citation key
-@var{cite_key} is a string of
+@var{cite_key} can be any string of
letters, numbers, and punctuation symbols (but not comma).
-@xref{thebibliography} for an example.
+@xref{thebibliography}, for an example.
-The optional @var{label} changes the default label from an integer to the
-given string. With this
+When provided, the optional @var{label} becomes the entry label and the
+@code{enumi} counter is not incremented. With this
@example
\begin@{thebibliography@}
@@ -6950,8 +7898,8 @@ Warning: There were multiply-defined labels}.
Under the hood, @LaTeX{} remembers the @var{cite_key} and @var{label}
information because @code{\bibitem} writes it to the auxiliary file
-@file{@var{filename}.aux}. For instance, the above example causes
-@code{\bibcite@{latexdps@}@{Lamport, 1993@}} and
+@file{@var{jobname}.aux} (@pxref{Jobname}). For instance, the above
+example causes the two @code{\bibcite@{latexdps@}@{Lamport, 1993@}} and
@code{\bibcite@{texbook@}@{1@}} to appear in that file. The @file{.aux}
file is read by the @code{\begin@{document@}} command and then the
information is available for @code{\cite} commands. This explains why
@@ -7000,20 +7948,21 @@ The ultimate source is \cite@{texbook@}.
@end example
@noindent
-produces output like @samp{... source is [1]}. (You can change the
-appearance of the citation with bibliography styles. More is in
-@ref{Using BibTeX}.)
+produces output like @samp{... source is [1]}. You can change the
+appearance of the citation and of the reference by using bibliography
+styles if you generate automatically the @code{thebibliography}
+environment. More information in @ref{Using BibTeX}.
The optional argument @var{subcite} is appended to the citation. For
example, @code{See 14.3 in \cite[p.~314]@{texbook@}} might produce
@samp{See 14.3 in [1, p.@tie{}314]}.
In addition to what appears in the output, @code{\cite} writes
-information to the auxiliary file @file{@var{filename}.aux}. For
-instance, @code{\cite@{latexdps@}} writes @samp{\citation@{latexdps@}}
-to that file. This information is used by Bib@TeX{} to include in your
-reference list only those works that you have actually cited; see
-@ref{\nocite} also.
+information to the auxiliary file @file{@var{jobname}.aux}
+(@pxref{Jobname}). For instance, @code{\cite@{latexdps@}} writes
+@samp{\citation@{latexdps@}} to that file. This information is used by
+Bib@TeX{} to include in your reference list only those works that you
+have actually cited; see @ref{\nocite} also.
If @var{keys} is not in your bibliography information then you get
@samp{LaTeX Warning: There were undefined references}, and in the output
@@ -7037,12 +7986,12 @@ Synopsis:
@end example
Produces no output but writes @var{keys} to the auxiliary file
-@file{@var{doc-filename}.aux}.
+@file{@var{jobname}.aux} (@pxref{Jobname}).
The mandatory argument @var{keys} is a comma-separated list of one or
more citation keys (@pxref{\bibitem}). This information is used by
Bib@TeX{} to include these works in your reference list even though you
-have not cited them (@pxref{\cite}).
+have not explicitly cited them (@pxref{\cite}).
@node Using BibTeX
@@ -7057,7 +8006,7 @@ have not cited them (@pxref{\cite}).
As described in @code{thebibliography} (@pxref{thebibliography}), a
sophisticated approach to managing bibliographies is provided by the
Bib@TeX{} program. This is only an introduction; see the full
-documentation on CTAN.
+documentation on CTAN (@pxref{CTAN}).
With Bib@TeX{}, you don't use @code{thebibliography}
(@pxref{thebibliography}). Instead, include these lines.
@@ -7087,7 +8036,7 @@ Like @code{plain}, but more compact labels.
@noindent Many, many other Bib@TeX{} style files exist,
tailored to the demands of various publications. See CTAN's listing
-@url{http://mirror.ctan.org/biblio/bibtex/contrib}.
+@url{https://mirror.ctan.org/biblio/bibtex/contrib}.
The @code{\bibliography} command is what actually produces the
bibliography. Its argument is a comma-separated list, referring to
@@ -7244,8 +8193,13 @@ the string @code{\end@{verbatim@}}.
@PkgIndex{cprotect}
You cannot use the verbatim environment in the argument to macros, for
instance in the argument to a @code{\section}. This is not the same as
-commands being fragile (@pxref{\protect}), instead it just cannot appear
-there. (But the @code{cprotect} package can help with this.)
+commands being fragile (@pxref{\protect}), instead it just cannot work,
+as the @code{verbatim} environment changes the catcode regime before
+processing its contents, and restore it immediately afterward,
+nevertheless with a macro argument the content of the argument has
+already be converted to a token list along the catcode regime in effect
+when the macro was called. However, the @code{cprotect} package can
+help with this.
@PkgIndex{listings}
@PkgIndex{minted}
@@ -7260,7 +8214,7 @@ and @code{minted}.
A package that provides many more options for verbatim environments is
@code{fancyvrb}. Another is @code{verbatimbox}.
-For a list of all the relevant packages, see CTAN.
+For a list of all the relevant packages, see CTAN (@pxref{CTAN}).
@menu
* \verb:: The macro form of the @code{verbatim} environment.
@@ -7296,13 +8250,13 @@ exclamation point, @code{!}. The second instead uses plus, @code{+},
because the exclamation point is part of @code{literal-text}.
The single-character delimiter @var{char} surrounds
-@var{literal-text}@tie{}--- it must be the same character before and
-after. No spaces come between @code{\verb} or @code{\verb*} and
-@var{char}, or between @var{char} and @var{literal-text}, or between
-@var{literal-text} and the second occurrence of @var{char} (the synopsis
-shows a space only to distinguish one component from the other). The
-delimiter must not appear in @var{literal-text}. The @var{literal-text}
-cannot include a line break.
+@var{literal-text}---it must be the same character before and after.
+No spaces come between @code{\verb} or @code{\verb*} and @var{char},
+or between @var{char} and @var{literal-text}, or between
+@var{literal-text} and the second occurrence of @var{char} (the
+synopsis shows a space only to distinguish one component from the
+other). The delimiter must not appear in @var{literal-text}. The
+@var{literal-text} cannot include a line break.
@cindex visible space
The @code{*}-form differs only in that spaces are printed with a visible
@@ -7311,15 +8265,16 @@ space character.
(Namely, {\tt\char`\ }.)
@end tex
-The output from this will include a character showing the spaces.
+The output from this will include a visible space on both side of word
+@samp{with}:
@example
-The commands's first argument is \verb*!filename with extension! and ...
+The command's first argument is \verb*!filename with extension! and ...
@end example
@PkgIndex{url}
For typesetting Internet addresses, urls, the package @code{url}
-provides an option that is better than the @code{\verb} command, since
+is a better option than the @code{\verb} command, since
it allows line breaks.
@PkgIndex{listings}
@@ -7330,8 +8285,12 @@ For computer code there are many packages with advantages over
@PkgIndex{cprotect}
You cannot use @code{\verb} in the argument to a macro, for instance in
the argument to a @code{\section}. It is not a question of @code{\verb}
-being fragile (@pxref{\protect}), instead it just cannot appear there.
-(But the @code{cprotect} package can help with this.)
+being fragile (@pxref{\protect}), instead it just cannot work, as the
+@code{\verb} command changes the catcode regime before reading its
+argument, and restore it immediately afterward, nevertheless with a
+macro argument the content of the argument has already be converted to a
+token list along the catcode regime in effect when the macro was called.
+However, the @code{cprotect} package can help with this.
@node verse
@@ -7509,8 +8468,8 @@ internally) the same as @code{\\}, followed by @code{\relax}. So each
new line in the input will also be a new line in the output. The
@code{\restorecr} command restores normal line-breaking behavior.
-This is not the way to show verbatim text or computer code.
-@xref{verbatim} instead.
+This is not the way to show verbatim text or computer code. Use
+@code{verbatim} (@pxref{verbatim}) instead.
With @LaTeX{}'s usual defaults, this
@@ -7780,7 +8739,7 @@ underrepresented groups.
When you issue @code{\linebreak}, the spaces in the line are stretched
out so that it extends to the right margin. @xref{\\}
-and@tie{}@ref{\newline} to have the spaces not stretched out.
+and@tie{}@ref{\newline}, to have the spaces not stretched out.
@@ -7818,7 +8777,7 @@ second one is lousy; to break the current page @LaTeX{} doesn't look as
far ahead as the next page break. So occasionally you may want to
influence page breaks while preparing a final version of a document.
-@xref{Layout} for more material that is relevant to page breaking.
+@xref{Layout}, for more material that is relevant to page breaking.
@menu
* \clearpage & \cleardoublepage:: Start a new page; eject floats.
@@ -7925,7 +8884,7 @@ proposition that all men are created equal.
@end example
@noindent
-makes a new page start after @samp{continent,} and the cut-off line is
+makes a new page start after @samp{continent}, and the cut-off line is
not right justified. In addition, @code{\newpage} does not vertically
stretch out the page, as @code{\pagebreak} does.
@@ -8010,13 +8969,13 @@ that all men are created equal.
@end example
@noindent
-does not give a page break at @samp{continent,} but instead at
-@samp{nation,} since that is where @LaTeX{} breaks that line. In
+does not give a page break at @samp{continent}, but instead at
+@samp{nation}, since that is where @LaTeX{} breaks that line. In
addition, with @code{\pagebreak} the vertical space on the page is
stretched out where possible so that it extends to the normal bottom
margin. This can look strange, and if @code{\flushbottom} is in effect
this can cause you to get @samp{Underfull \vbox (badness 10000) has
-occurred while \output is active}. @xref{\newpage} for a command that
+occurred while \output is active}. @xref{\newpage}, for a command that
does not have these effects.
@@ -8133,7 +9092,7 @@ sectioning command such as @code{\chapter} (it can only be used in outer
paragraph mode; @pxref{Modes}). There are some workarounds; see
following sections.
-@cindex Footnotes, in a minipage
+@cindex footnotes, in a minipage
@cindex mpfootnote counter
In a @code{minipage} environment the @code{\footnote} command uses the
@code{mpfootnote} counter instead of the @code{footnote} counter, so
@@ -8234,7 +9193,7 @@ that command, but must appear in outer paragraph mode (@pxref{Modes}).
The optional argument @var{number} changes the number of the footnote
mark.
-@xref{\footnotemark} and@tie{}@ref{Footnotes in a table} for usage
+@xref{\footnotemark} and@tie{}@ref{Footnotes in a table}, for usage
examples.
@@ -8389,6 +9348,7 @@ second.\footnotefrom@{%
* \newfont:: Define a new font name.
* \protect:: Using tricky commands.
* \ignorespaces & \ignorespacesafterend:: Discard extra spaces.
+* xspace package:: Space after a macro, conditionally.
@end menu
@@ -8424,13 +9384,16 @@ or one of these.
\renewcommand*@{\@var{cmd}@}[@var{nargs}][@var{optargdefault}]@{@var{defn}@}
@end example
-Define or redefine a command. See also the discussion of
-@code{\DeclareRobustCommand} in @ref{Class and package commands}.
+Define or redefine a command (see also the discussion of
+@code{\DeclareRobustCommand} in @ref{Class and package commands}).
+
@cindex starred form, defining new commands
@cindex *-form, defining new commands
-The starred form of these two requires that the arguments not contain
-multiple paragraphs of text (in plain @TeX{} terms that it not be
-@code{\long}).
+@findex \long
+The starred form of these two forbids the arguments from containing
+multiple paragraphs of text (in plain @TeX{} terms, the commands
+are not @code{\long}). With the default form, arguments can be
+multiple paragraphs.
These are the parameters:
@@ -8452,8 +9415,8 @@ different number of arguments than the old version.
@item optargdefault
Optional; if this argument is present then the first argument of
@code{\@var{cmd}} is optional, with default value @var{optargdefault}
-(which may be the empty string). If this argument is not present then
-@code{\@var{cmd}} does not take an optional argument.
+(which may be the empty string). If @var{optargsdefault} is not present
+then @code{\@var{cmd}} does not take an optional argument.
@cindex positional parameter
That is, if @code{\@var{cmd}} is used with square brackets, as in
@@ -8576,14 +9539,14 @@ If no command of this name already exists then this has the same effect
as @code{\newcommand}. If a command of this name already exists then
this definition does nothing. This is particularly useful in a file
that may be loaded more than once, such as a style file.
-@xref{\newcommand & \renewcommand} for the description of the arguments.
+@xref{\newcommand & \renewcommand}, for the description of the arguments.
This example
@example
\providecommand@{\myaffiliation@}@{Saint Michael's College@}
\providecommand@{\myaffiliation@}@{Saint Michael's College@}
-From \myaffiliation.
+>From \myaffiliation.
@end example
@noindent
@@ -8625,17 +9588,17 @@ or class writers. The convention prevents authors who are just using a
package or class from accidentally replacing such a command with one of
their own, because by default the at-sign has catcode@tie{}12.
-The pair @code{\makeatletter} and @code{\makeatother} changes the
-default code and then changes it back. Use them inside a @file{.tex}
-file, in the preamble, when you are defining or redefining commands
-named with @code{@@}, by having them surround your definition. Don't
-use these inside @file{.sty} or @file{.cls} files since the
-@code{\usepackage} and @code{\documentclass} commands already arrange
-that the at-sign has the character code of a letter, catcode@tie{}11.
+Use the pair @code{\makeatletter} and @code{\makeatother} inside a
+@file{.tex} file, typically in the preamble, when you are defining or
+redefining commands named with @code{@@}, by having them surround your
+definition. Don't use these inside @file{.sty} or @file{.cls} files
+since the @code{\usepackage} and @code{\documentclass} commands already
+arrange that the at-sign has the character code of a letter,
+catcode@tie{}11.
@PkgIndex{macros2e}
For a comprehensive list of macros with an at-sign in their names see
-@url{http://ctan.org/pkg/macros2e}.
+@url{https://ctan.org/pkg/macros2e}.
In this example the class file has a command
@code{\thesis@@universityname} that the user wants to change. These
@@ -8671,28 +9634,34 @@ Examples are the @code{table} and @code{table*} environments and the
When defining environments, following this pattern is straightforward
because @code{\newenvironment} and @code{\renewenvironment} allow the
-environment name to contain a star. For commands the situation is more
-complex. As in the synopsis above, there will be a user-called command,
-given above as @code{\mycmd}, which peeks ahead to see if it is followed
-by a star. For instance, @LaTeX{} does not really have a
-@code{\section*} command; instead, the @code{\section} command peeks
-ahead. This command does not accept arguments but instead expands to
-one of two commands that do accept arguments. In the synopsis these two
-are @code{\mycmd@@nostar} and @code{\mycmd@@star}. They could take the
-same number of arguments or a different number, or no arguments at all.
-As always, in a @LaTeX{} document a command using at-sign@tie{}@code{@@}
-must be enclosed inside a @code{\makeatletter ... \makeatother} block
+environment name to contain a star. So you just have to write
+@code{\newenvironment@{@var{myenv}@}} or
+@code{\newenvironment@{@var{myenv}*@}} and continue the definition as
+usual. For commands the situation is more complex as the star not being
+a letter cannot be part of the command name. As in the synopsis above,
+there will be a user-called command, given above as @code{\mycmd}, which
+peeks ahead to see if it is followed by a star. For instance, @LaTeX{}
+does not really have a @code{\section*} command; instead, the
+@code{\section} command peeks ahead. This command does not accept
+arguments but instead expands to one of two commands that do accept
+arguments. In the synopsis these two are @code{\mycmd@@nostar} and
+@code{\mycmd@@star}. They could take the same number of arguments or a
+different number, or no arguments at all. As always, in a @LaTeX{}
+document a command using an at-sign@tie{}@code{@@} in its name must be
+enclosed inside a @code{\makeatletter ... \makeatother} block
(@pxref{\makeatletter & \makeatother}).
This example of @code{\@@ifstar} defines the command @code{\ciel} and a
variant @code{\ciel*}. Both have one required argument. A call to
-@code{\ciel@{night@}} will return "starry night sky" while
-@code{\ciel*@{blue@}} will return "starry not blue sky".
+@code{\ciel@{blue@}} will return "not starry blue sky" while
+@code{\ciel*@{night@}} will return "starry night sky".
@example
-\newcommand*@{\ciel@@unstarred@}[1]@{starry #1 sky@}
-\newcommand*@{\ciel@@starred@}[1]@{starry not #1 sky@}
+\makeatletter
+\newcommand*@{\ciel@@unstarred@}[1]@{not starry #1 sky@}
+\newcommand*@{\ciel@@starred@}[1]@{starry #1 sky@}
\newcommand*@{\ciel@}@{\@@ifstar@{\ciel@@starred@}@{\ciel@@unstarred@}@}
+\makeatother
@end example
In the next example, the starred variant takes a different number of
@@ -8708,16 +9677,28 @@ arguments than the unstarred one. With this definition, Agent 007's
\@@ifstar@{\agentsecret@@starred@}@{\agentsecret@@unstarred@}@}
@end example
-There are two sometimes more convenient ways to accomplish the work of
-@code{\@@ifstar}. The @file{suffix} package allows the construct
-@code{\newcommand\mycommand@{@var{unstarred version}@}} followed by
-@code{\WithSuffix\newcommand\mycommand*@{@var{starred version}@}}. And
-@LaTeX{}3 has the @file{xparse} package that allows this code.
+After a command name, a star is handled similarly to an optional
+argument. (This differs from environment names in which the star is
+part of the name itself and as such could be in any position.) Thus,
+it is technically possible to put any number of spaces between the
+command and the star. Thus @code{\agentsecret*@{Bond@}} and
+@code{\agentsecret@w{ *}@{Bond@}} are equivalent. However, the
+standard practice is not to insert any such spaces.
+
+@PkgIndex{suffix}
+@PkgIndex{xparse}
+There are two alternative ways to accomplish the work of
+@code{\@@ifstar}. (1)@tie{}The @file{suffix} package allows the
+construct @code{\newcommand\mycommand@{@var{unstarred-variant}@}}
+followed by
+@code{\WithSuffix\newcommand\mycommand*@{@var{starred-variant}@}}.
+(2)@tie{}@LaTeX{} provides the @file{xparse} package, which allows
+this code:
@example
\NewDocumentCommand\foo@{s@}@{\IfBooleanTF#1
- @{@var{starred version}@}%
- @{@var{unstarred version}@}%
+ @{@var{starred-variant}@}%
+ @{@var{unstarred-variant}@}%
@}
@end example
@@ -9277,7 +10258,7 @@ or
Both commands cause @LaTeX{} to ignore spaces after the end of the
command up until the first non-space character. The first is a command
-from Plain @TeX{}, and the second is @LaTeX{}-specific.
+from plain @TeX{}, and the second is @LaTeX{}-specific.
The @code{ignorespaces} is often used when defining commands via
@code{\newcommand}, or @code{\newenvironment}, or @code{\def}. The
@@ -9308,10 +10289,9 @@ as given, if a title accidentally starts with a space then
@code{\fullname} will reproduce that.
@example
-\makeatletter
-\newcommand@{\honorific@}[1]@{\def\@@honorific@{#1@}@} % remember title
-\newcommand@{\fullname@}[1]@{\@@honorific~#1@} % put title before name
-\makeatother
+\newcommand@{\honorific@}[1]@{\def\honorific@{#1@}@} % remember title
+\newcommand@{\fullname@}[1]@{\honorific~#1@} % put title before name
+
\begin@{tabular@}@{|l|@}
\honorific@{Mr/Ms@} \fullname@{Jones@} \\ % no extra space here
\honorific@{ Mr/Ms@} \fullname@{Jones@} % extra space before title
@@ -9320,11 +10300,11 @@ as given, if a title accidentally starts with a space then
@noindent
To fix this, change to
-@code{\newcommand@{\fullname@}[1]@{\ignorespaces\@@honorific~#1@}}.
+@code{\newcommand@{\fullname@}[1]@{\ignorespaces\honorific~#1@}}.
The @code{\ignorespaces} is also often used in a @code{\newenvironment}
-at the end of the @var{begin} clause, that is, as part of the second
-argument, as in @code{\begin@{newenvironment@}@{@var{env
+at the end of the @var{begin} clause, as in
+@code{\begin@{newenvironment@}@{@var{env
name}@}@{... \ignorespaces@}@{...@}}.
To strip spaces off the end of an environment use
@@ -9351,6 +10331,66 @@ inconvenient. The solution is to change to
@code{\newenvironment@{eq@}@{\begin@{equation@}@}@{\end@{equation@}\ignorespacesafterend@}}.
+@node xspace package
+@section xspace package
+
+@findex \xspace
+@cindex spaces, ignore around commands
+@cindex commands, ignore spaces
+
+Synopsis:
+
+@example
+\usepackage@{xspace@}
+ ...
+\newcommand@{...@}@{...\xspace@}
+@end example
+
+The @code{\xspace} macro, when used at the end of a command, adds a
+space unless the command is followed by certain punctuation characters.
+
+After a command name that uses letters (as opposed to single character
+command names using non-letters such as @code{\$}), @TeX{} gobbles white
+space. Thus, in the first sentence below, the output has @samp{Vermont}
+placed snugly against the period, without any intervening space.
+
+@example
+\newcommand@{\VT@}@{Vermont@}
+Our college is in \VT .
+The \VT@{@} summers are nice.
+@end example
+
+But because of the gobbling, the second sentence needs the dummy curly
+braces or else there would be no space separating @samp{Vermont} from
+@samp{summers}. (Many authors instead instead use a backslash-space
+@code{\ } for this. @xref{\(SPACE)}.)
+
+The @file{xspace} package provides @code{\xspace}. It is for writing
+commands which are designed to be used mainly in text. It inserts a
+space after that command unless what immediately follows is in a list of
+exceptions. In this example, the dummy braces are not needed.
+
+@example
+\newcommand@{\VT@}@{Vermont\xspace@}
+Our college is in \VT .
+\VT summers are nice.
+@end example
+
+The default exception list contains the characters @code{,.'/?;:!~-)},
+the open curly brace and the backslash-space command discussed above,
+and the commands @code{\footnote} or @code{\footnotemark}. Add to that
+list as with @code{\xspaceaddexceptions@{\myfni \myfnii@}} and remove
+from that list as with @code{\xspaceremoveexception@{!@}}.
+
+@c David Carlisle https://tex.stackexchange.com/a/86620/339
+A comment: many experts prefer not to use @code{\xspace}. Putting it in
+a definition means that the command will usually get the spacing right.
+But it isn't easy to predict when to enter dummy braces because
+@code{\xspace} will get it wrong, such as when it is followed by another
+command, and so @code{\xspace} can make editing material harder and more
+error-prone than instead always remembering the dummy braces.
+
+
@node Counters
@chapter Counters
@@ -9586,7 +10626,7 @@ Here it is in Roman: \Roman@{exercise@}.
Synopsis:
@example
-\addtocounter@{@var{counter}@}@{@var{value}@
+\addtocounter@{@var{counter}@}@{@var{value}@}
@end example
Globally increment @var{counter} by the amount specified by the
@@ -9640,7 +10680,7 @@ within it. (For the definition of ``counters numbered within'',
@pxref{\newcounter}.)
This command differs from @code{\refstepcounter} in that this one does
-not influence references@tie{}--- it does not define the current
+not influence references; that is, it does not define the current
@code{\ref} value to be the result of @code{\thecounter}
(@pxref{\refstepcounter}).
@@ -9680,14 +10720,20 @@ bogus month value produces no output).
A @dfn{length} is a measure of distance. Many @LaTeX{} commands take a
length as an argument.
+@cindex rigid lengths
+@cindex rubber lengths
+@cindex dimen @r{plain @TeX{}}
+@cindex skip @r{plain @TeX{}}
+@cindex glue @r{plain @TeX{}}
Lengths come in two types. A @dfn{rigid length} such as @code{10pt}
-does not contain a @code{plus} or @code{minus} component. (Plain @TeX{}
-calls this a @dfn{dimen}.) A @dfn{rubber length} (what Plain @TeX{}
-calls a @dfn{skip}) such as as with @code{1cm plus0.05cm minus0.01cm}
-can contain either or both of those components. In that rubber length,
-the @code{1cm} is the @dfn{natural length} while the other two, the
-@code{plus} and @code{minus} components, allow @TeX{} to stretch or
-shrink the length to optimize placement.
+does not contain a @code{plus} or @code{minus} component. (Plain
+@TeX{} calls this a @dfn{dimen}.) A @dfn{rubber length} (what plain
+@TeX{} calls a @dfn{skip} or @dfn{glue}) such as with @code{1cm
+plus0.05cm minus0.01cm} can contain either or both of those
+components. In that rubber length, the @code{1cm} is the @dfn{natural
+length} while the other two, the @code{plus} and @code{minus}
+components, allow @TeX{} to stretch or shrink the length to optimize
+placement.
The illustrations below use these two commands.
@@ -9798,6 +10844,8 @@ that after @code{\setlength@{\ylength@}@{1in plus 0.2in@}} and
* \settodepth:: Set a length to the depth of something.
* \settoheight:: Set a length to the height of something.
* \settowidth:: Set a length to the width of something.
+* \stretch:: Add infinite stretchability.
+* Expressions:: Compute with lengths and integers.
@c * Predefined lengths:: Lengths that are, like, predefined.
@end menu
@@ -9813,10 +10861,10 @@ math mode.
@table @code
@item pt
@findex pt
-@cindex Point
+@cindex point
@anchor{units of length pt}
-Point, 1/72.27 inch. The conversion to metric units, to two decimal
-places, is 1@dmn{point} = 2.85@dmn{mm} = 28.45@dmn{cm}.
+Point, 1/72.27 inch. The conversion to metric units
+is 1@dmn{point} = 2.845@dmn{mm} = .2845@dmn{cm}.
@item pc
@cindex pica
@@ -9832,37 +10880,37 @@ Inch, 72.27 pt
@item bp
@findex bp
-@cindex Big point
+@cindex big point
@anchor{units of length bp}
Big point, 1/72 inch. This length is the definition of a point in
PostScript and many desktop publishing systems.
@item cm
-@cindex Centimeter
+@cindex centimeter
@findex cm
@anchor{units of length cm}
Centimeter
@item mm
-@cindex Millimeter
+@cindex millimeter
@findex mm
@anchor{units of length mm}
Millimeter
@item dd
-@cindex Didot point
+@cindex didot point
@findex dd
@anchor{units of length dd}
Didot point, 1.07 pt
@item cc
-@cindex Cicero
+@cindex cicero
@findex cc
@anchor{units of length cc}
Cicero, 12 dd
@item sp
-@cindex Scaled point
+@cindex scaled point
@findex sp
@anchor{units of length sp}
Scaled point, 1/65536 pt
@@ -10070,6 +11118,161 @@ then you get something like @samp{Undefined control sequence. <argument>
@samp{Missing number, treated as zero. <to be read again> \setbox}.
+@node \stretch
+@section @code{\stretch}
+
+@findex \stretch
+
+Synopsis:
+
+@example
+\stretch@{@var{number}@}
+@end example
+
+Produces a rubber length with zero natural length and @var{number} times
+@code{\fill} units of stretchability (@pxref{Lengths}). The
+@var{number} can be positive or negative. This command is robust
+(@pxref{\protect}).
+
+It works for both vertical and horizontal spacing. In this horizontal
+example, @LaTeX{} produces three tick marks, and the distance between
+the first and second is half again as long as the distance between the
+second and third.
+
+@example
+\rule@{0.4pt@}@{1ex@}\hspace@{\stretch@{1.5@}@}%
+ \rule@{0.4pt@}@{1ex@}\hspace@{\stretch@{1@}@}%
+ \rule@{0.4pt@}@{1ex@}
+@end example
+
+In this vertical example, the @samp{We dedicate @dots{}} will have three
+times as much space under it as above it.
+
+@example
+\newenvironment@{dedication@}@{% in document preamble
+ \clearpage\thispagestyle@{empty@}%
+ \vspace*@{\stretch@{1@}@} % stretchable space at top
+ \it
+@}@{%
+ \vspace@{\stretch@{3@}@} % space at bot is 3x as at top
+ \clearpage
+@}
+ ...
+\begin@{dedication@} % in document body
+We dedicate this book to our wives.
+\end@{dedication@}
+@end example
+
+
+@node Expressions
+@section Expressions
+
+@findex expressions
+
+@c Much from Joseph Wright's https://tex.stackexchange.com/a/245663/339
+Synopsis, one of:
+
+@example
+\numexpr @var{expression}
+\dimexpr @var{expression}
+\glueexpr @var{expression}
+\muglue @var{expression}
+@end example
+
+Any place where you may write an integer, or a @TeX{} dimen, or @TeX{}
+glue, or muglue, you can instead write an expression to compute that
+type of quantity.
+
+An example is that @code{\the\dimexpr\linewidth-4pt\relax} will
+produce as output the length that is four points less than width of a
+line (the only purpose of @code{\the} is to show the result in the
+document). Analogously, @code{\romannumeral\numexpr6+3\relax} will
+produce @samp{ix}, and @code{\the\glueexpr 5pt plus 1pt * 2 \relax}
+will produce @samp{10.0pt plus 2.0pt}.
+
+A convenience here over doing calculations by allocating registers and
+then using @code{\advance}, etc., is that the evaluation of expressions
+does not involve assignments and can therefore be performed in places
+where assignments are not allowed. The next example computes the width
+of the @code{\parbox}.
+
+@example
+\newlength@{\offset@}\setlength@{\offset@}@{2em@}
+\begin@{center@}
+\parbox@{\dimexpr\linewidth-\offset*3@}@{With malice toward none
+with charity for all with firmness in the right as God gives us to see
+the right let us strive on to finish the work we are in to bind up the
+nation's wounds, to care for him who shall have borne the battle and
+for his widow and his orphan \textasciitilde\ to do all which may
+achieve and cherish a just and lasting peace among ourselves and with
+all nations. ---Abraham Lincoln, Second Inaugural Address, from the
+memorial@}
+\end@{center@}
+@end example
+
+The @var{expression} consists of one or more terms of the same type
+(integer, dimension, etc.) that are added or subtracted. A term that is
+a type of number, dimension, etc., consists of a factor of that type,
+optionally multiplied or divided by factors. A factor of a type is
+either a quantity of that type or a parenthesized subexpression. The
+expression produces a result of the given type, so that @code{\numexpr}
+produces an integer, @code{\dimexpr} produces a dimension, etc.
+
+In the quotation example above, changing to
+@code{\dimexpr\linewidth-3*\offset} gives the error @code{Illegal unit
+of measure (pt inserted)}. This is because for @code{\dimexpr} and
+@code{\glueexpr}, the input consists of a dimension or glue value
+followed by an optional multiplication factor, and not the other way
+around. Thus @code{\the\dimexpr 1pt*10\relax} is valid and produces
+@samp{10.0pt}, but @code{\the\dimexpr 10*1pt\relax} gives the
+@code{Illegal unit} error.
+
+The expressions absorb tokens and carry out appropriate mathematics up
+to a @code{\relax} (which will be absorbed), or up to the first
+non-valid token. Thus, @code{\the\numexpr2+3px} will print
+@samp{5px}, because @LaTeX{} reads the @code{\numexpr2+3}, which is
+made up of numbers, and then finds the letter @code{p}, which cannot
+be part of a number. It therefore terminates the expression and
+produces the @samp{5}, followed by the regular text @samp{px}.
+
+This termination behavior is useful in comparisons. In
+@code{\ifnum\numexpr\parindent*2 < 10pt Yes\else No\fi}, the less than
+sign terminates the expression and the result is @samp{No} (in a
+standard @LaTeX{} article).
+
+Expressions may use the operators @code{+}, @code{-}, @code{*} and
+@code{/} along with parentheses for subexpressions, @code{(...)}. In
+glue expressions the @code{plus} and @code{minus} parts do not need
+parentheses to be affected by a factor. So @code{\the\glueexpr 5pt plus
+1pt * 2 \relax} results in @samp{10pt plus 2pt}.
+
+@TeX{} will coerce other numerical types in the same way as it does when
+doing register assignment. Thus @code{\the\numexpr\dimexpr
+1pt\relax\relax} will result in @samp{65536}, which is @code{1pt}
+converted to scaled points (@TeX{}'s internal unit) and then coerced
+into an integer. With a @code{\glueexpr} here, the stretch and shrink
+would be dropped. Going the other way, a @code{\numexpr} inside a
+@code{\dimexpr} or @code{\glueexpr} will need appropriate units, as in
+@code{\the\dimexpr\numexpr 1 + 2\relax pt\relax}, which produces
+@samp{3.0pt}.
+
+The details of the arithmetic: each factor is checked to be in the
+allowed range, numbers must be less than @math{2^{31}} in absolute
+value, and dimensions or glue components must be less than
+@math{2^{14}} points, or @code{mu}, or @code{fil}, etc. The
+arithmetic operations are performed individually, except for a scaling
+operation (a multiplication immediately followed by a division) which
+is done as one combined operation with a 64-bit product as
+intermediate value. The result of each operation is again checked to
+be in the allowed range.
+
+Finally, division and scaling take place with rounding (unlike @TeX{}'s
+@code{\divide}, which truncates). Thus
+@code{\the\dimexpr 5pt*(3/2)\relax} puts @samp{10.0pt} in the document,
+because it rounds @code{3/2} to @code{2}, while
+@code{\the\dimexpr 5pt*(4/3)\relax} produces @samp{5.0pt}.
+
+
@node Making paragraphs
@chapter Making paragraphs
@@ -10223,7 +11426,7 @@ first outputs an empty box whose width is @code{\parindent}. These
commands are robust (@pxref{\protect}).
Ordinarily you create a new paragraph by putting in a blank line.
-@xref{\par} for the difference between this command and @code{\par}. To
+@xref{\par}, for the difference between this command and @code{\par}. To
start a paragraph without an indent, or to continue an interrupted
paragraph, use @code{\noindent}.
@@ -10269,20 +11472,22 @@ look on CTAN for the package @code{indentfirst}.
@findex \parindent
@findex \parskip
@cindex paragraph indentation
+@cindex horizontal paragraph indentation
@cindex vertical space before paragraphs
Synopsis:
@example
-\setlength@{\parskip@}@{@var{horizontal len}@}
-\setlength@{\parinden@}@{@var{vertical len}@}
+\setlength@{\parindent@}@{@var{horizontal len}@}
+\setlength@{\parskip@}@{@var{vertical len}@}
@end example
-Both are a rubber lengths (@pxref{Lengths}). They give the indentation
-of ordinary paragraphs, not paragraphs inside minipages
-(@pxref{minipage}), and the vertical space between paragraphs.
+Both are rubber lengths (@pxref{Lengths}). They affect the
+indentation of ordinary paragraphs, not paragraphs inside
+minipages (@pxref{minipage}), and the vertical space between
+paragraphs, respectively.
-This, put in the preamble,
+For example, if this is put in the preamble:
@example
\setlength@{\parindent@}@{0em@}
@@ -10290,16 +11495,20 @@ This, put in the preamble,
@end example
@noindent
-arranges that the document will have paragraphs that are not indented,
-but instead are vertically separated by about the height of a lowercase
-@samp{x}.
+The document will have paragraphs that are not indented, but instead
+are vertically separated by about the height of a lowercase @samp{x}.
In standard @LaTeX{} documents, the default value for @code{\parindent}
in one-column documents is @code{15pt} when the default text size is
-@code{10pt} , @code{17pt} for @code{11pt}, and @code{1.5em} for
-@code{12pt}. In two-column documents it is @code{1em}. The default
-value for @code{\parskip} in @LaTeX{}'s standard document styles is
-@code{0pt plus1pt}.
+@code{10pt}, @code{17pt} for @code{11pt}, and @code{1.5em} for
+@code{12pt}. In two-column documents it is @code{1em}. (These values
+are set before @LaTeX{} calls @code{\normalfont} so @code{em} is derived
+from the default font, Computer Modern. If you use a different font
+then to set @code{\parindent} in units matching that font, do
+@code{\AtBeginDocument@{\setlength@{\parindent@}@{1em@}@}}.)
+
+The default value for @code{\parskip} in @LaTeX{}'s standard document
+styles is @code{0pt plus1pt}.
@node Marginal notes
@@ -10349,8 +11558,9 @@ These parameters affect the formatting of the note:
@ftable @code
@item \marginparpush
@anchor{marginal notes marginparpush}
-Minimum vertical space between notes; default @samp{7pt} for
-@samp{12pt} documents, @samp{5pt} else.
+Minimum vertical space between notes; default @samp{7pt} for @samp{12pt}
+documents, @samp{5pt} else. See also@tie{}@ref{page layout parameters
+marginparpush}.
@item \marginparsep
@anchor{marginal notes marginparsep}
@@ -10510,9 +11720,9 @@ see their documentation on CTAN.
@cindex superscript
@cindex subscript
+@findex ^ @r{superscript}
+@findex _ @r{subscript}
@cindex exponent
-@findex _
-@findex ^
Synopsis (in math mode or display math mode), one of:
@@ -10579,13 +11789,13 @@ To put a superscript or subscript before a symbol, use a construct like
subscript something to attach to and keeps it from accidentally
attaching to a prior symbols.
-Using the subscript or superscript command outside of math mode or
+Using the subscript or superscript character outside of math mode or
display math mode, as in @code{the expression x^2}, will get you
the error @samp{Missing $ inserted}.
@PkgIndex{mhchem}
A common reason to want subscripts outside of a mathematics mode is to
-typeset chemical formulas. There are packages for that such as
+typeset chemical formulas. There are packages for that, such as
@file{mhchem}; see CTAN.
@@ -10596,13 +11806,13 @@ typeset chemical formulas. There are packages for that such as
@cindex symbols, math
@cindex greek letters
-@PkgIndex{symbols}
+@PkgIndex{comprehensive}
@LaTeX{} provides almost any mathematical or technical symbol that
-anyone uses. For example, if you include @code{$\pi$} in your source,
-you will get the pi symbol @BES{03C0,\pi}. See the @file{Comprehensive
-@LaTeX{} Symbol List} at
-@url{https://ctan.org/tex-archive/info/symbols/comprehensive/}.
+anyone uses. For example, if you include @code{$\pi$} in your source,
+you will get the pi symbol @BES{03C0,\pi}. See the ``Comprehensive
+@LaTeX{} Symbol List'' package at
+@url{https://ctan.org/pkg/comprehensive}.
Here is a list of commonly-used symbols. It is by no means exhaustive.
Each symbol is described with a short phrase, and its symbol class,
@@ -10688,20 +11898,20 @@ union@tie{}@code{\cup}.
(operator). (Note that the name has only one p.)
@item \bigvee
-@BES{22C1,\bigvee} Variable-sized, or n-ary, logical-and (operator).
+@BES{22C1,\bigvee} Variable-sized, or n-ary, logical-or (operator).
@item \bigwedge
-@BES{22C0,\bigwedge} Variable-sized, or n-ary, logical-or (operator).
+@BES{22C0,\bigwedge} Variable-sized, or n-ary, logical-and (operator).
@item \bot
-@BES{22A5,} Up tack, bottom, least element of a partially ordered
+@BES{22A5}, Up tack, bottom, least element of a partially ordered
set, or a contradiction (ordinary). See also@tie{}@code{\top}.
@item \bowtie
@BES{22C8,\bowtie} Natural join of two relations (relation).
@item \Box
-@BES{25A1,} Modal operator for necessity; square open box
+@BES{25A1,\Box} Modal operator for necessity; square open box
(ordinary). @value{NeedsAMSSymb}
@c bb Best Unicode equivalent?
@@ -10729,7 +11939,7 @@ variable-sized operator@tie{}@code{\bigcirc}.
@BES{2663,\clubsuit} Club card suit (ordinary).
@item \complement
-@BES{2201,} Set complement, used as a superscript as in
+@BES{2201}, Set complement, used as a superscript as in
@code{$S^\complement$} (ordinary). @value{NeedsAMSSymb} Also used:
@code{$S^@{\mathsf@{c@}@}$} or@tie{}@code{$\bar@{S@}$}.
@@ -10760,7 +11970,7 @@ turnstile@tie{}@code{\vdash}.
@BES{03B4,\delta} Greek lowercase delta (ordinary).
@item \Diamond
-@BES{25C7,} Large diamond operator (ordinary). @value{NeedsAMSSymb}
+@BES{25C7,\Diamond} Large diamond operator (ordinary). @value{NeedsAMSSymb}
@item \diamond
@BES{22C4,\diamond} Diamond operator (binary). Similar: large
@@ -10879,7 +12089,7 @@ epsilon@tie{}@code{\varepsilon}.
@BES{03B9,\iota} Lowercase Greek letter (ordinary).
@item \Join
-@BES{2A1D,} Condensed bowtie symbol (relation). Not available in Plain
+@BES{2A1D,\Join} Condensed bowtie symbol (relation). Not available in Plain
@TeX{}.
@item \jmath
@@ -10897,8 +12107,8 @@ accents}).
@BES{03BB,\lambda} Lowercase Greek letter (ordinary).
@item \land
-@BES{2227,\land} Logical and (binary). This is a synonym for @code{\wedge}.
-See also logical or@tie{}@code{\lor}.
+@BES{2227,\land} Logical and (binary). Synonym:@tie{}@code{\wedge}.
+See also logical@tie{}or@tie{}@code{\lor}.
@item \langle
@BES{27E8,\langle} Left angle, or sequence, bracket (opening). Similar:
@@ -10921,7 +12131,7 @@ shaved off (opening). Matches@tie{}@code{\rceil}.
for@tie{}@code{\leq}.
@item \leadsto
-@BES{21DD,} Squiggly right arrow (relation). @value{NeedsAMSSymb}
+@BES{21DD,\leadsto} Squiggly right arrow (relation).
To get this symbol outside of math mode you can put
@code{\newcommand*@{\Leadsto@}@{\ensuremath@{\leadsto@}@}} in the
preamble and then use @code{\Leadsto} instead.
@@ -10958,8 +12168,8 @@ for@tie{}@code{\le}.
@BES{230A,\lfloor} Left floor bracket (opening). Matches:@tie{}@code{\floor}.
@item \lhd
-@BES{25C1,} Arrowhead, that is, triangle, pointing left (binary).
-@value{NeedsAMSSymb} For the normal subgroup symbol you should load
+@BES{25C1,\lhd} Arrowhead, that is, triangle, pointing left (binary).
+For the normal subgroup symbol you should load
@file{amssymb} and use@tie{}@code{\vartriangleleft} (which is a relation
and so gives better spacing).
@@ -10987,15 +12197,16 @@ double-line double-headed arrow@tie{}@code{\Longleftrightarrow}.
double-line right arrow@tie{}@code{\Longrightarrow}.
@item \lor
-@BES{2228,\lor} Logical or (binary). Synonym: wedge@tie{}@code{\wedge}.
+@BES{2228,\lor} Logical or (binary). Synonym:@tie{}@code{\vee}.
+See also logical@tie{}and@tie{}@code{\land}.
@item \mapsto
-@BES{21A6,\mapsto} Single-line left arrow starting with vertical bar (relation).
+@BES{21A6,\mapsto} Single-line left arrow starting with vertical bar
+(relation).
Similar: longer version@tie{}@code{\longmapsto}.
@item \mho
-@BES{2127,} Conductance, half-circle rotated capital omega (ordinary).
-@value{NeedsAMSSymb}
+@BES{2127,\mho} Conductance, half-circle rotated capital omega (ordinary).
@item \mid
@BES{2223,\mid} Single-line vertical bar (relation). A typical use of
@@ -11105,6 +12316,9 @@ of@tie{}@code{\in}.
same glyph but the spacing is different because it is in the class
ordinary.
+@item \Phi
+@BES{03A6,\Phi} Uppercase Greek letter (ordinary).
+
@item \phi
@BES{03D5,\phi} Lowercase Greek letter (ordinary). The variant form is
@code{\varphi}@tie{}@BES{03C6,\varphi}.
@@ -11169,11 +12383,11 @@ double-line, or blackboard bold, R@tie{}@code{\mathbb@{R@}}; to access
this, load the @file{amsfonts} package.
@item \restriction
-@BES{21BE,} Restriction of a function (relation). Synonym:
+@BES{21BE}, Restriction of a function (relation). Synonym:
@code{\upharpoonright}. @value{NeedsAMSSymb}
@item \revemptyset
-@BES{29B0,} Reversed empty set symbol (ordinary). Related:
+@BES{29B0}, Reversed empty set symbol (ordinary). Related:
@code{\varnothing}. @value{NeedsSTIX}
@item \rfloor
@@ -11181,8 +12395,8 @@ this, load the @file{amsfonts} package.
off (closing). Matches@tie{}@code{\lfloor}.
@item \rhd
-@BES{25C1,} Arrowhead, that is, triangle, pointing right (binary).
-@value{NeedsAMSSymb} For the normal subgroup symbol you should instead
+@BES{25C1,\rhd} Arrowhead, that is, triangle, pointing right (binary).
+For the normal subgroup symbol you should instead
load @file{amssymb} and use@tie{}@code{\vartriangleright} (which is a
relation and so gives better spacing).
@@ -11255,7 +12469,7 @@ union@tie{}@code{cup}. Related: variable-sized
operator@tie{}@code{\bigsqcup}.
@item \sqsubset
-@BES{228F,} Square subset symbol (relation). Similar:
+@BES{228F}, Square subset symbol (relation). Similar:
subset@tie{}@code{\subset}. @value{NeedsAMSSymb}
@item \sqsubseteq
@@ -11263,7 +12477,7 @@ subset@tie{}@code{\subset}. @value{NeedsAMSSymb}
equal to@tie{}@code{\subseteq}.
@item \sqsupset
-@BES{2290,} Square superset symbol (relation). Similar:
+@BES{2290}, Square superset symbol (relation). Similar:
superset@tie{}@code{\supset}. @value{NeedsAMSSymb}
@item \sqsupseteq
@@ -11325,7 +12539,7 @@ also@tie{}@code{\cdot}.
Synonym:@tie{}@code{\rightarrow}.
@item \top
-@BES{22A4,} Top, greatest element of a partially ordered set
+@BES{22A4,\top} Top, greatest element of a partially ordered set
(ordinary). See also@tie{}@code{\bot}.
@item \triangle
@@ -11344,15 +12558,15 @@ is a relation and so gives better spacing).
relation and so gives better spacing).
@item \unlhd
-@BES{22B4,} Left-pointing not-filled underlined arrowhead, that is,
-triangle, with a line under (binary). @value{NeedsAMSSymb} For the
+@BES{22B4,\unlhd} Left-pointing not-filled underlined arrowhead, that is,
+triangle, with a line under (binary). For the
normal subgroup symbol load @file{amssymb} and
use@tie{}@code{\vartrianglelefteq} (which is a relation and so gives
better spacing).
@item \unrhd
-@BES{22B5,} Right-pointing not-filled underlined arrowhead, that is,
-triangle, with a line under (binary). @value{NeedsAMSSymb} For the
+@BES{22B5,\unrhd} Right-pointing not-filled underlined arrowhead, that is,
+triangle, with a line under (binary). For the
normal subgroup symbol load @file{amssymb} and
use@tie{}@code{\vartrianglerighteq} (which is a relation and so gives
better spacing).
@@ -11378,7 +12592,7 @@ arrow@tie{}@code{\updownarrow}.
arrow@tie{}@code{\Updownarrow}.
@item \upharpoonright
-@BES{21BE,} Up harpoon, with barb on right side
+@BES{21BE}, Up harpoon, with barb on right side
(relation). Synonym:@tie{}@code{@backslashchar{}restriction}.
@value{NeedsAMSSymb}
@@ -11400,7 +12614,7 @@ more widely used in mathematics than the non-variant lunate epsilon form
membership@tie{}@code{\in}.
@item \vanothing
-@BES{2205,} Empty set symbol. Similar: @code{\emptyset}. Related:
+@BES{2205}, Empty set symbol. Similar: @code{\emptyset}. Related:
@code{\revemptyset}. @value{NeedsAMSSymb}
@item \varphi
@@ -11436,38 +12650,15 @@ logical and@tie{}@code{\wedge}. Similar: variable-sized
operator@tie{}@code{\bigvee}.
@item \Vert
-@BES{2016,\Vert} Vertical double bar (ordinary). Similar: vertical single
-bar@tie{}@code{\vert}.
-
-For a norm symbol, you can use the @file{mathtools} package and put in
-your preamble
-@code{\DeclarePairedDelimiter\norm@{\lVert@}@{\rVert@}}. This gives you
-three command variants for double-line vertical bars that are correctly
-horizontally spaced: if in the document body you write the starred
-version @code{$\norm*@{M^\perp@}$} then the height of the vertical bars
-will match the height of the argument, whereas with
-@code{\norm@{M^\perp@}} the bars do not grow with the height of the
-argument but instead are the default height, and @code{\norm[@var{size
-command}]@{M^\perp@}} also gives bars that do not grow but are set to
-the size given in the @var{size command}, e.g., @code{\Bigg}.
+@BES{2016,\Vert} Vertical double bar (ordinary). @xref{Delimiters},
+for how to use the @file{mathtools} package to create flexibly-sized
+norm symbols.
@item \vert
-@BES{007C,\vert} Single line vertical bar (ordinary). Similar: double-line
-vertical bar@tie{}@code{\Vert}. For such that, as in the definition of a
-set, use@tie{}@code{\mid} because it is a relation.
-
-For absolute value you can use the @file{mathtools} package and in your
-preamble put
-@code{\DeclarePairedDelimiter\abs@{\lvert@}@{\rvert@}}. This gives you
-three command variants for single-line vertical bars that are correctly
-horizontally spaced: if in the document body you write the starred
-version @code{$\abs*@{\frac@{22@}@{7@}@}$} then the height of the
-vertical bars will match the height of the argument, whereas with
-@code{\abs@{\frac@{22@}@{7@}@}} the bars do not grow with the height of
-the argument but instead are the default height, and
-@code{\abs[@var{size command}]@{\frac@{22@}@{7@}@}} also gives bars that
-do not grow but are set to the size given in the @var{size command},
-e.g., @code{\Bigg}.
+@BES{007C,\vert} Single line vertical bar (ordinary). For ``such
+that'', as in the definition of a set, use@tie{}@code{\mid} because it
+is a relation. @xref{Delimiters}, for how to use the @file{mathtools}
+package to create flexibly-sized absolute-value symbols.
@item \wedge
@BES{2227,\wedge} Logical and (binary). Synonym:@tie{}@code{\land}. See also
@@ -11513,13 +12704,156 @@ Underscore in math mode: _.
@end ftable
@menu
+* Arrows:: List of arrows.
+* \boldmath & \unboldmath:: Symbols in boldface.
* Blackboard bold:: Doublestruck characters.
* Calligraphic:: Cursive characters.
-* \boldmath & \unboldmath:: Symbols in boldface.
+* Delimiters:: Parentheses, braces, etc.
* Dots:: Ellipses, etc.
+* Greek letters:: List of Greek letters.
@end menu
+@node Arrows
+@subsection Arrows
+
+@cindex arrows
+@cindex symbols, arrows
+@findex math, arrows
+
+@PkgIndex{amsfonts}
+@PkgIndex{latexsym}
+These are the arrows that come with standard @LaTeX{}. The
+@file{latexsym} and @file{amsfonts} packages contain many more.
+
+@multitable @columnfractions .10 .40 .50
+@headitem Symbol@tab Command@tab
+@item
+@BES{021D3,\Downarrow} @tab @code{\Downarrow} @tab
+@item
+@BES{02193,\downarrow} @tab @code{\downarrow} @tab
+@item
+@BES{021A9,\hookleftarrow} @tab @code{\hookleftarrow} @tab
+@item
+@BES{021AA,\hookrightarrow} @tab @code{\hookrightarrow} @tab
+@item
+@BES{2190,\leftarrow} @tab @code{\leftarrow} @tab
+@item
+@BES{021D0,\Leftarrow} @tab @code{\Leftarrow} @tab
+@item
+@BES{021D4,\Leftrightarrow} @tab @code{\Leftrightarrow} @tab
+@item
+@BES{02194,\leftrightarrow} @tab @code{\leftrightarrow} @tab
+@item
+@BES{027F5,\longleftarrow} @tab @code{\longleftarrow} @tab
+@item
+@BES{027F8,\Longleftarrow} @tab @code{\Longleftarrow} @tab
+@item
+@BES{027F7,\longleftrightarrow} @tab @code{\longleftrightarrow} @tab
+@item
+@BES{027FA,\Longleftrightarrow} @tab @code{\Longleftrightarrow} @tab
+@item
+@BES{027FC,\longmapsto} @tab @code{\longmapsto} @tab
+@item
+@BES{027F9,\Longrightarrow} @tab @code{\Longrightarrow} @tab
+@item
+@BES{027F6,\longrightarrow} @tab @code{\longrightarrow} @tab
+@item
+@BES{021A6,\mapsto} @tab @code{\mapsto} @tab
+@item
+@BES{02197,\nearrow} @tab @code{\nearrow} @tab
+@item
+@BES{02196,\nwarrow} @tab @code{\nwarrow} @tab
+@item
+@BES{021D2,\Rightarrow} @tab @code{\Rightarrow} @tab
+@item
+@BES{02192,\rightarrow} @tab @code{\rightarrow}, or @code{\to} @tab
+@item
+@BES{02198,\searrow} @tab @code{\searrow} @tab
+@item
+@BES{02199,\swarrow} @tab @code{\swarrow} @tab
+@item
+@BES{02191,\uparrow} @tab @code{\uparrow} @tab
+@item
+@BES{021D1,\Uparrow} @tab @code{\Uparrow} @tab
+@item
+@BES{02195,\updownarrow} @tab @code{\updownarrow} @tab
+@item
+@BES{021D5,\Updownarrow} @tab @code{\Updownarrow} @tab
+@end multitable
+
+An example of the difference between @code{\to} and @code{\mapsto}
+is: @code{\( f\colon D\to C \) given by \( n\mapsto n^2 \)}.
+
+@PkgIndex{amscd}
+@PkgIndex{tikz-cd}
+For commutative diagrams there are a number of packages, including
+@file{tikz-cd} and @file{amscd}.
+
+
+@node \boldmath & \unboldmath
+@subsection @code{\boldmath} & @code{\unboldmath}
+
+@cindex boldface mathematics
+@cindex symbols, boldface
+@findex \boldmath
+@findex \unboldmath
+
+Synopsis (used in paragraph mode or LR mode):
+
+@example
+\boldmath \( @var{math} \)
+@end example
+
+@noindent
+or
+
+@example
+\unboldmath \( @var{math} \)
+@end example
+
+@findex \boldmath
+@findex \unboldmath
+Declarations to change the letters and symbols in @var{math} to be in
+a bold font, or to countermand that and bring back the regular
+(non-bold) default. They must be used when not in math mode or display
+math mode (@pxref{Modes}). Both commands are fragile
+(@pxref{\protect}).
+
+In this example each @code{\boldmath} command takes place inside an
+@code{\mbox},
+
+@example
+we have $\mbox@{\boldmath \( v \)@} = 5\cdot\mbox@{\boldmath \( u \)$@}$
+@end example
+
+@noindent
+which means @code{\boldmath} is only called in a text mode, here LR
+mode, and explains why @LaTeX{} must switch to math mode to set @code{v}
+and @code{u}.
+
+If you use either command inside math mode, as with @code{Trouble: \(
+\boldmath x \)}, then you get something like @samp{LaTeX Font Warning:
+Command \boldmath invalid in math mode on input line 11} and @samp{LaTeX
+Font Warning: Command \mathversion invalid in math mode on input line
+11}.
+
+@PkgIndex{bm}
+There are many issues with @code{\boldmath}. New documents should use
+the @file{bm} package provided by the @LaTeX{} Project team. A complete
+description is outside the scope of this document (see the full
+documentation on CTAN) but even this small example
+
+@example
+\usepackage@{bm@} % in preamble
+...
+we have $\bm@{v@} = 5\cdot\bm@{u@}$
+@end example
+
+@noindent
+shows that it is an improvement over @code{\boldmath}.
+
+
@node Blackboard bold
@subsection Blackboard bold
@@ -11545,7 +12879,7 @@ Here
@end example
@noindent
-the @code{\mathbb@{N@}} gives blackboard bold symbol @BES{2115,}
+the @code{\mathbb@{N@}} gives blackboard bold symbol @BES{2115},
representing the natural numbers.
If you use other than an uppercase letter then you do not get an error
@@ -11577,72 +12911,351 @@ Let the graph be \( \mathcal@{G@} \).
@end example
If you use something other than an uppercase letter then you do not get
-an error. Instead you get unexpected output. For instance,
-@code{\mathcal@{g@}} outputs a close curly brace symbol, while
-@code{\mathcal@{+@}} outputs a plus sign.
+an error but you also do not get math calligraphic output. For instance,
+@code{\mathcal@{g@}} outputs a close curly brace symbol.
-@node \boldmath & \unboldmath
-@subsection @code{\boldmath} & @code{\unboldmath}
+@node Delimiters
+@subsection Delimiters
-@cindex boldface mathematics
-@cindex symbols, boldface
-@findex \boldmath
-@findex \unboldmath
+@cindex delimiters
+@cindex parentheses
+@cindex braces
+@cindex curly braces
+@cindex brackets
-Synopsis (used in paragraph mode or LR mode):
+Delimiters are parentheses, braces, or other characters used to mark
+the start and end of subformulas. This formula has three sets of
+parentheses delimiting the three subformulas.
@example
-\boldmath \( @var{math} \)
+(z-z_0)^2 = (x-x_0)^2 + (y-y_0)^2
@end example
@noindent
-or
+The delimiters do not need to match, so you can enter @code{\( [0,1) \)}.
+
+Here are the common delimiters:
+
+@multitable @columnfractions .11 .20 .40 .29
+@headitem Delimiter@tab Command@tab Name
+@item
+( @tab @code{(} @tab Left parenthesis
+@item
+) @tab @code{)} @tab Right parenthesis
+@item
+\@} @tab @code{@{} or @code{\lbrace} @tab Left brace
+@item
+\@{ @tab @code{@}} or @code{\rbrace} @tab Right brace
+@item
+[ @tab @code{[} or @code{\lbrack} @tab Left bracket
+@item
+] @tab @code{]} or @code{\rbrack} @tab Right bracket
+@item
+@BES{230A,\lfloor} @tab @code{\lfloor} @tab Left floor bracket
+@item
+@BES{230B,\rfloor} @tab @code{\rfloor} @tab Right floor bracket
+@item
+@BES{2308,\lceil} @tab @code{\lceil} @tab Left ceiling bracket
+@item
+@BES{2309,\rceil} @tab @code{\rceil} @tab Right ceiling bracket
+@item
+@BES{27E8,\langle} @tab @code{\langle} @tab Left angle bracket
+@item
+@BES{27E9,\rangle} @tab @code{\rangle} @tab Right angle bracket
+@item
+/ @tab @code{/} @tab Slash, or forward slash
+@item
+\ @tab @code{\backslash} @tab Reverse slash, or backslash
+@item
+| @tab @code{|} or @code{\vert} @tab Vertical bar
+@item
+@BES{2016,\|} @tab @code{\|} or @code{\Vert} @tab Double vertical bar
+@end multitable
+
+@PkgIndex{mathtools}
+The @file{mathtools} package allows you to create commands for paired
+delimiters. For instance, if you put
+@code{\DeclarePairedDelimiter\abs@{\lvert@}@{\rvert@}} in your preamble
+then you get two commands for single-line vertical bars (they only work
+in math mode). The starred version, such as
+@code{\abs*@{\frac@{22@}@{7@}@}}, has the height of the vertical bars
+match the height of the argument. The unstarred version, such as
+@code{\abs@{\frac@{22@}@{7@}@}}, has the bars fixed at a default height.
+This version accepts an optional argument, as in @code{\abs[@var{size
+command}]@{\frac@{22@}@{7@}@}}, where the height of the bars is given in
+@var{size command}, such as @code{\Bigg}. Using @code{\lVert} and
+@code{\rVert} as the symbols will give you a norm symbol with the same
+behavior.
+
+@menu
+* \left & \right:: Automatically sized delimiters.
+* \bigl & \bigr etc.:: Manually sized delimiters.
+@end menu
+
+
+@node \left & \right
+@subsubsection @code{\left} & @code{\right}
+
+@cindex delimiters, paired
+@cindex paired delimiters
+@cindex matching parentheses
+@cindex matching brackets
+@cindex null delimiter
+@findex \left
+@findex \right
+
+@c Credit: SE userPhilipp https://tex.stackexchange.com/a/12793
+
+Synopsis:
@example
-\unboldmath \( @var{math} \)
+\left @var{delimiter1} ... \right @var{delimiter2}
@end example
-@findex \boldmath
-@findex \unboldmath
-Declarations to change the letters and symbols in @var{math} to be in
-a bold font, or to countermand that and bring back the regular
-(non-bold) default. They must be used when not in math mode or display
-math mode (@pxref{Modes}). Both commands are fragile
-(@pxref{\protect}).
+Make matching parentheses, braces, or other delimiters. @LaTeX{} makes
+the delimiters tall enough to just cover the size of the formula that
+they enclose.
-In this example each @code{\boldmath} command takes place inside an
-@code{\mbox},
+This makes a unit vector surrounded by parentheses tall enough to cover
+the entries.
@example
-we have $\mbox@{\boldmath \( v \)@} = 5\cdot\mbox@{\boldmath \( u \)$@}$
+\begin@{equation@}
+ \left(\begin@{array@}@{c@}
+ 1 \\
+ 0 \\
+ \end@{array@}\right)
+\end@{equation@}
+@end example
+
+@xref{Delimiters}, for a list of the common delimiters.
+
+Every @code{\left} must have a matching @code{\right}. In the above
+example, leaving out the @code{\left(} gets the error message
+@samp{Extra \right}. Leaving out the @code{\right)} gets @samp{You
+can't use `\eqno' in math mode}.
+
+@PkgIndex{amsmath}
+@PkgIndex{mathtools}
+However, @var{delimiter1} and @var{delimiter2} need not match. A common
+case is that you want an unmatched brace, as below. Use a period,
+@samp{.}, as a null delimiter.
+
+@example
+\begin@{equation@}
+ f(n)=\left\@{\begin@{array@}@{ll@}
+ 1 &\mbox@{--if \(n=0\)@} \\
+ f(n-1)+3n^2 &\mbox@{--else@}
+ \end@{array@}\right.
+\end@{equation@}
@end example
@noindent
-which means @code{\boldmath} is only called in a text mode, here LR
-mode, and explains why @LaTeX{} must switch to math mode to set @code{v}
-and @code{u}.
+Note that to get a curly brace as a delimiter you must prefix it with a
+backslash, @code{\@{}. (The packages @file{amsmath} and
+@file{mathtools} allow you to get the above construct through in a
+@code{cases} environment.)
-If you use either command inside math mode, as with @code{Trouble: \(
-\boldmath x \)}, then you get something like @samp{LaTeX Font Warning:
-Command \boldmath invalid in math mode on input line 11} and @samp{LaTeX
-Font Warning: Command \mathversion invalid in math mode on input line
-11}.
+The @code{\left ... \right} pair make a group. One consequence is that
+the formula enclosed in the @code{\left ... \right} pair cannot have
+line breaks in the output. This includes both manual line breaks and
+@LaTeX{}-generated automatic ones. In this example, @LaTeX{} breaks the
+equation to make the formula fit the margins.
-@PkgIndex{bm}
-There are many issues with @code{\boldmath}. New documents should use
-the @file{bm} package provided by the @LaTeX{} Project team. A complete
-description is outside the scope of this document (see the full
-documentation on CTAN) but even this small example
+@example
+Lorem ipsum dolor sit amet
+\( (a+b+c+d+e+f+g+h+i+j+k+l+m+n+o+p+q+r+s+t+u+v+w+x+y+z) \)
+@end example
+
+@noindent
+But with @code{\left} and @code{\right}
@example
-\usepackage@{bm@} % in preamble
-...
-we have $\bm@{v@} = 5\cdot\bm@{u@}$
+Lorem ipsum dolor sit amet
+\( \left(a+b+c+d+e+f+g+h+i+j+k+l+m+n+o+p+q+r+s+t+u+v+w+x+y+z\right) \)
@end example
@noindent
-shows that it is an improvement over @code{\boldmath}.
+@LaTeX{} won't break the line, causing the formula to extend into the
+margin.
+
+Because @code{\left ... \right} make a group, all the usual grouping
+rules hold. Here, the value of @code{\testlength} set inside the
+equation will be forgotten, and the output is @samp{1.2pt}.
+
+@example
+\newlength@{\testlength@} \setlength@{\testlength@}@{1.2pt@}
+\begin@{equation@}
+ \left( a+b=c \setlength@{\testlength@}@{3.4pt@} \right)
+ \the\testlength
+\end@{equation@}
+@end example
+
+The @code{\left ... \right} pair affect the horizontal spacing of the
+enclosed formula, in two ways. The first is that in @code{\( \sin(x) =
+\sin\left(x\right) \)} the one after the equals sign has more space
+around the @code{x}. That's because @code{\left( ... \right)} inserts
+an inner node while @code{( ... )} inserts an opening node. The second
+way that the pair affect the horizontal spacing is that because they
+form a group, the enclosed subformula will be typeset at its natural
+width, with no stretching or shrinking to make the line fit better.
+
+@TeX{} scales the delimiters according to the height and depth of the
+contained formula. Here @LaTeX{} grows the brackets to extend the full
+height of the integral.
+
+@example
+\begin@{equation@}
+ \left[ \int_@{x=r_0@}^@{\infty@} -G\frac@{Mm@}@{r^2@}\, dr \right]
+\end@{equation@}
+@end example
+
+Manual sizing is often better. For instance, although below the rule
+has no depth, @TeX{} will create delimiters that extend far below the
+rule.
+
+@example
+\begin@{equation@}
+ \left( \rule@{1pt@}@{1cm@} \right)
+\end@{equation@}
+@end example
+
+@noindent
+@TeX{} can choose delimiters that are too small, as in @code{\( \left|
+|x|+|y| \right| \)}. It can also choose delimiters that are too large,
+as here.
+
+@example
+\begin@{equation@}
+ \left( \sum_@{0\leq i<n@} i^k \right)
+\end@{equation@}
+@end example
+
+@noindent
+A third awkward case is when a long displayed formula is on more than
+one line and you must match the sizes of the opening and closing
+delimiter; you can't use @code{\left} on the first line and
+@code{\right} on the last because they must be paired.
+
+To size the delimiters manually, see@tie{}@ref{\bigl & \bigr etc.}.
+
+
+@node \bigl & \bigr etc.
+@subsubsection @code{\bigl}, @code{\bigr}, etc.
+
+Synopsis, one of:
+
+@example
+\bigl@var{delimiter1} ... \bigr@var{delimiter2}
+\Bigl@var{delimiter1} ... \bigr@var{delimiter2}
+\biggl@var{delimiter1} ... \biggr@var{delimiter2}
+\Biggl@var{delimiter1} ... \Biggr@var{delimiter2}
+@end example
+
+@noindent
+(as with @code{\bigl[...\bigr]}; strictly speaking they need not be
+paired, see below), or one of:
+
+@example
+\bigm@var{delimiter}
+\Bigm@var{delimiter}
+\biggm@var{delimiter}
+\Biggm@var{delimiter}
+@end example
+
+@noindent
+(as with @code{\bigm|}), or one of:
+
+@example
+\big@var{delimiter}
+\Big@var{delimiter}
+\bigg@var{delimiter}
+\Bigg@var{delimiter}
+@end example
+
+@noindent
+(as with @code{\big[}).
+
+Produce manually-sized delimiters. For delimiters that are
+automatically sized see@tie{}@ref{\left & \right}).
+
+This produces slightly larger outer vertical bars.
+
+@example
+ \bigl| |x|+|y| \bigr|
+@end example
+
+The commands above are listed in order of increasing size. You can use
+the smallest size such as @code{\bigl...\bigr} in a paragraph without
+causing @LaTeX{} to spread the lines apart. The larger sizes are meant
+for displayed equations.
+
+@xref{Delimiters}, for a list of the common delimiters. In the family of
+commands with @samp{l} and @samp{r}, @var{delimiter1} and
+@var{delimiter2} need not be the same.
+
+The @samp{l} and @samp{r} commands produce open and close delimiters
+that insert no horizontal space between a preceding atom and the
+delimiter, while the commands without @samp{l} and @samp{r} insert some
+space (because each delimiter is set as an ordinary variable). Compare
+these two.
+
+@c credit: Martin Heller https://tex.stackexchange.com/a/1234
+@example
+\begin@{tabular@}@{l@}
+ \(\displaystyle \sin\biggl(\frac@{1@}@{2@}\biggr) \) \\ % good
+ \(\displaystyle \sin\bigg(\frac@{1@}@{2@}\bigg) \) \\ % bad
+\end@{tabular@}
+@end example
+
+@noindent
+The traditional typographic treatment is on the first line. On the
+second line the output will have some extra space between the
+@code{\sin} and the open parenthesis.
+
+Commands without @samp{l} or@tie{}@samp{r} do give correct spacing in
+some circumstances, as with this large vertical line
+
+@example
+\begin@{equation@}
+ \int_@{x=a@}^b x^2\,dx = \frac@{1@}@{3@} x^3 \Big|_@{x=a@}^b
+\end@{equation@}
+@end example
+
+@PkgIndex{amsmath}
+@noindent
+(many authors would replace @code{\frac} with the @code{\tfrac} command
+from the @file{amsmath} package), and as with this larger slash.
+
+@example
+\begin@{equation@}
+ \lim_@{n\to\infty@}\pi(n) \big/ (n/\log n) = 1
+\end@{equation@}
+@end example
+
+Unlike the @code{\left...\right} pair (@pxref{\left & \right}), the
+commands here with @samp{l} and@tie{}@samp{r} do not make a group.
+Strictly speaking they need not be matched so you can write something
+like this.
+
+@example
+\begin@{equation@}
+ \Biggl[ \pi/6 ]
+\end@{equation@}
+@end example
+
+The commands with @samp{m} are for relations, which are in the middle of
+formulas, as here.
+
+@example
+\begin@{equation@}
+ \biggl\@{ a\in B \biggm| a=\sum_@{0\leq i<n@}3i^2+4 \biggr\@}
+\end@{equation@}
+@end example
+
+@c xx Add discussion \bigg\mid not being good
+@c and \bigg| being right; maybe mention of \middle and braket package?
@node Dots
@@ -11721,6 +13334,78 @@ or relation symbol, @code{\dotsi} for dots with integrals, or
@code{\dotso} for others.
+@node Greek letters
+@subsection Greek letters
+
+@cindex Greek letters
+
+The upper case versions of these Greek letters are only shown when they
+differ from Roman upper case letters.
+
+@multitable @columnfractions .10 .30 .15 .45
+@headitem Symbol@tab Command@tab Name@tab
+@item
+@BES{03B1,\alpha}@tab @code{\alpha}@tab Alpha
+@item
+@BES{03B2,\beta}@tab @code{\beta}@tab Beta
+@item
+@BES{03B3,\gamma}, @BES{0393,\Gamma}@tab @code{\gamma}, @code{\Gamma}@tab Gamma
+@item
+@BES{03B4,\delta}, @BES{0394,\Delta}@tab @code{\delta}, @code{\Delta}@tab Delta
+@item
+@BES{03B5,\varepsilon}, @BES{03F5,\epsilon}@tab
+ @code{\varepsilon}, @code{\epsilon}@tab Epsilon
+@item
+@BES{03B6,\zeta}@tab @code{\zeta}@tab Zeta
+@item
+@BES{03B7,\eta}@tab @code{\eta}@tab Eta
+@item
+@BES{03B8,\theta}, @BES{03D1,\vartheta}@tab @code{\theta}, @code{\vartheta}@tab
+ Theta
+@item
+@BES{03B9,\iota}@tab @code{\iota}@tab Iota
+@item
+@BES{03BA,\kappa}@tab @code{\kappa}@tab Kappa
+@item
+@BES{03BB,\lambda}, @BES{039B,\Lambda}@tab @code{\lambda}, @code{\Lambda}@tab
+ Lambda
+@item
+@BES{03BC,\mu}@tab @code{\mu}@tab Mu
+@item
+@BES{03BD,\nu}@tab @code{\nu}@tab Nu
+@item
+@BES{03BE,\xi}, @BES{039E,\Xi}@tab @code{\xi}, @code{\Xi}@tab Xi
+@item
+@BES{03C0,\pi}, @BES{03A0,\Pi}@tab @code{\pi}, @code{\Pi}@tab Pi
+@item
+@BES{03C1,\rho}, @BES{03F1,\varrho}@tab @code{\rho}, @code{\varrho}@tab Rho
+@item
+@BES{03C3,\sigma}, @BES{03A3,\Sigma}@tab @code{\sigma}, @code{\Sigma}@tab Sigma
+@item
+@BES{03C4,\tau}@tab @code{\tau}@tab Tau
+@item
+@BES{03D5,\phi}, @BES{03C6,\varphi}, @BES{03A6,\Phi}@tab
+ @code{\phi}, @code{\varphi}, @code{\Phi}@tab Phi
+@item
+@BES{03C7,\chi}@tab @code{\chi}@tab chi
+@item
+@BES{03C8,\psi}, @BES{03A8,\Psi}@tab @code{\psi}, @code{\Psi}@tab Psi
+@item
+@BES{03C9,\omega}, @BES{03A9,\Omega}@tab @code{\omega}, @code{\Omega}@tab Omega
+@end multitable
+
+@PkgIndex{unicode-math}
+For omicron, if you are using @LaTeX{}'s default Computer Modern font
+then enter omicron just as @samp{o} or @samp{O}. If you like having the
+name or if your font shows a difference then you can use something like
+@code{\newcommand\omicron@{o@}}. The package @file{unicode-math} has
+@code{\upomicron} for upright omicron and @code{\mitomicron} for math
+italic.
+
+While the set membership relation symbol @BES{2208,\in} generated by
+@code{\in} is related to epsilon, it is never used for a variable.
+
+
@node Math functions
@section Math functions
@@ -12143,9 +13828,9 @@ normal rules for mathematics texts. If you enter @code{y=m x} then
@LaTeX{} ignores the space and in the output the m is next to the x,
as @math{y=mx}.
-But @LaTeX{}'s rules sometimes need tweaking. For example, in an
+But @LaTeX{}'s rules occasionally need tweaking. For example, in an
integral the tradition is to put a small extra space between the
-@code{f(x)} and the @code{dx}, here done with the @code{\,} command.
+@code{f(x)} and the @code{dx}, here done with the @code{\,} command:
@example
\int_0^1 f(x)\,dx
@@ -12163,8 +13848,15 @@ a@tie{}@samp{M}.
@findex \;
@findex \thickspace
@anchor{spacing in math mode thickspace}
-Synonym: @code{\thickspace}. Normally @code{5.0mu plus 5.0mu}. Math
-mode only.
+Synonym: @code{\thickspace}. Normally @code{5.0mu plus 5.0mu}.
+With @code{amsmath}, or as of the 2020-10-01 @LaTeX{} release, can be
+used in text mode as well as math mode; before that, in math mode only.
+
+@item \negthickspace
+@findex \negthickspace
+Normally @code{-5.0mu plus 2.0mu minus 4.0mu}.
+With @code{amsmath}, or as of the 2020-10-01 @LaTeX{} release, can be
+used in text mode as well as math mode; before that, in math mode only.
@item \:
@itemx \>
@@ -12173,7 +13865,14 @@ mode only.
@findex \medspace
@anchor{spacing in math mode medspace}
Synonym: @code{\medspace}. Normally @code{4.0mu plus 2.0mu minus 4.0mu}.
-Math mode only.
+With @code{amsmath}, or as of the 2020-10-01 @LaTeX{} release, can be
+used in text mode as well as math mode; before that, in math mode only.
+
+@item \negmedspace
+@findex \negmedspace
+Normally @code{-4.0mu plus 2.0mu minus 4.0mu}.
+With @code{amsmath}, or as of the 2020-10-01 @LaTeX{} release, can be
+used in text mode as well as math mode; before that, in math mode only.
@item \,
@findex \,
@@ -12201,9 +13900,11 @@ The antiderivative is
@findex \negthinspace
@cindex thin space, negative
@anchor{spacing in math mode negthinspace}
-A negative thin space. Normally @code{-3mu}. The @code{\!} command is
-math mode only but the @code{\negthinspace} command is available for
-text mode (@pxref{\thinspace & \negthinspace}).
+A negative thin space. Normally @code{-3mu}.
+With @code{amsmath}, or as of the 2020-10-01 @LaTeX{} release, can be
+used in text mode as well as math mode; before that,
+The @code{\!} command is math mode only but the @code{\negthinspace}
+command has always worked in text mode (@pxref{\thinspace & \negthinspace}).
@item \quad
@cindex quad
@@ -12222,8 +13923,9 @@ both text and math mode.
@end table
@menu
-* \smash:: Eliminate height or depth of a subformula.
-* \phantom & \vphantom & \hphantom:: Make empty box with the same size as the argument.
+* \smash:: Eliminate height or depth of a subformula.
+* \phantom & \vphantom & \hphantom:: Make empty box same size as argument.
+* \mathstrut:: Add some vertical space to a formula.
@end menu
@@ -12333,25 +14035,35 @@ or
The @code{\phantom} command creates a box with the same height, depth,
and width as @var{subformula}, but empty. That is, this command causes
-@LaTeX{} to typeset the box but not its ink. The @code{\vphantom}
-variant also produces an invisible box with the same height and depth as
-@var{subformula}, but it has width zero. And @code{\hphantom} makes a
-box with the same width as @var{subformula} but with height and depth
-zero.
-
-Without the @code{\vphantom} in this example, the top bars of the two
-square roots would be at different heights.
+@LaTeX{} to typeset the space but not fill it with the material. Here
+@LaTeX{} will put a box of the right size for the quotation, but empty.
@example
-\( \sqrt@{\vphantom@{a^3@}a@}\cdot\sqrt@{a^3@} \)
+\fbox@{\phantom@{Conservatism is the fear-filled worship of dead radicals.
+ --- Mark Twain@}@}
@end example
-The @code{\vphantom@{a^3@}} causes the first @code{\sqrt} to have inside
-it a box of the same height as the second @code{\sqrt}, so @LaTeX{}
-makes the bars align.
+The @code{\vphantom} variant produces an invisible box with the same
+vertical size as @var{subformula}, the same height and depth, but having
+zero width. And @code{\hphantom} makes a box with the same width as
+@var{subformula} but with zero height and depth.
+
+In this example, the tower of exponents in the second summand expression
+is so tall that @TeX{} places this expression further down than its
+default. Without adjustment, the two summand expressions would be at
+different levels. The @code{\vphantom} in the first expression tells
+@TeX{} to leave as much vertical room as it does for the tower, so the
+two expressions come out at the same level.
-These commands often are combined with @code{\smash}. @xref{\smash}
-for another example of the use of @code{\vphantom}.
+@example
+\begin@{displaymath@}
+ \sum_@{j\in\@{0,\ldots\, 10\@}\vphantom@{3^@{3^@{3^j@}@}@}@}
+ \sum_@{i\in\@{0,\ldots\, 3^@{3^@{3^j@}@}\@}@} i\cdot j
+\end@{displaymath@}
+@end example
+
+These commands are often used in conjunction with @code{\smash}.
+@xref{\smash}, which includes another example of @code{\vphantom}.
@PkgIndex{mathtools}
The three phantom commands appear often but note that @LaTeX{} provides
@@ -12374,6 +14086,38 @@ mode. So if one of these starts a paragraph then you should prefix it
with @code{\leavevmode}.
+@node \mathstrut
+@subsection @code{\mathstrut}
+
+@findex @code{\mathstrut}
+@cindex spacing, math mode
+@cindex vertical spacing
+@cindex math mode, spacing
+@cindex invisible character
+@cindex character, invisible
+
+Synopsis:
+
+@example
+\mathstrut
+@end example
+
+The analogue of @code{\strut} for mathematics. @xref{\strut}.
+
+The input @code{$\sqrt@{x@} + \sqrt@{x^i@}$} gives output where the
+second radical is taller than the first. To add extra vertical space
+without any horizontal space, so that the two have the same height, use
+@code{$\sqrt@{x\mathstrut@} + \sqrt@{x^i\mathstrut@}$}.
+
+The @code{\mathstrut} command adds the vertical height of an open
+parenthesis, @code{(}, but no horizontal space. It is defined as
+@code{\vphantom@{(@}}, so see @ref{\phantom & \vphantom & \hphantom} for
+more. An advantage over @code{\strut} is that @code{\mathstrut} adds no
+depth, which is often the right thing for formulas. Using the height of
+an open parenthesis is just a convention; for complete control over the
+amount of space, use @code{\rule} with a width of zero. @xref{\rule}.
+
+
@node Math miscellany
@section Math miscellany
@@ -12386,7 +14130,6 @@ some that don't fit into other categories.
* Colon character & \colon:: Colon.
* \*:: Discretionary multiplication.
* \frac:: Fraction.
-* \left & \right:: Paired delimiters.
* \sqrt:: Radicals.
* \stackrel:: Text over a relation.
@end menu
@@ -12395,9 +14138,8 @@ some that don't fit into other categories.
@node Colon character & \colon
@subsection Colon character @code{:} & @code{\colon}
-@cindex :
@cindex colon character
-@findex :
+@findex : @r{for math}
@findex \colon
Synopsis, one of:
@@ -12469,57 +14211,6 @@ mode it comes out small; see the discussion of @code{\displaystyle}
(@pxref{Math formulas}).
-@node \left & \right
-@subsection @code{\left} & @code{\right}
-
-@cindex delimiters, paired
-@cindex paired delimiters
-@cindex matching parentheses
-@cindex matching brackets
-@cindex null delimiter
-@findex \left
-@findex \right
-
-Synopsis:
-
-@example
-\left @var{delimiter1} ... \right @var{delimiter2}
-@end example
-
-Make matching parentheses, braces, or other delimiters. The delimiters
-are sized according to the math they enclose. This makes a unit vector
-surrounded by appropriate-height parentheses.
-
-@example
-\begin@{equation@}
- \left(\begin@{array@}@{c@}
- 1 \\
- 0 \\
- \end@{array@}\right)
-@end example
-
-Every @code{\left} must have a matching @code{\right}. Leaving out the
-@code{\left(} in the above gets @samp{Extra \right}. Leaving off the
-@code{\right)} gets @samp{You can't use `\eqno' in math mode}.
-
-However, the two delimiters @var{delimiter1} and @var{delimiter2} need
-not match. A common case is that you want an unmatched brace, as
-below. Use a period, @samp{.}, as a null delimiter.
-
-@example
-\begin@{equation@}
- f(n)=\left\@{\begin@{array@}@{ll@}
- 1 &\mbox@{--if \(n=0\)@} \\
- f(n-1)+3n^2 &\mbox@{--else@}
- \end@{array@}\right.
-\end@{equation@}
-@end example
-
-@noindent
-Note that to get a curly brace as a delimiter you must prefix it with a
-backslash, @code{\@{}.
-
-
@node \sqrt
@subsection @code{\sqrt}
@@ -12717,7 +14408,7 @@ Synopsis:
Generate a title. In the standard classes the title appears on a
separate page, except in the @code{article} class where it is at the top
-of the first page. (@xref{Document class options} for information about
+of the first page. (@xref{Document class options}, for information about
the @code{titlepage} document class option.)
This example shows @code{\maketitle} appearing in its usual place,
@@ -13025,7 +14716,7 @@ Horizontal space
* \hfill:: Stretchable horizontal space.
* \hss:: Infinitely stretchable/shrinkable horizontal space.
* \spacefactor:: Stretchability of following space
-* \(SPACE):: Backslash-space; and explicit space.
+* \(SPACE):: Backslash-space, and explicit space.
* ~:: Tie, an unbreakable space.
* \thinspace & \negthinspace:: One-sixth of an em, and negative one-sixth.
* \/:: Italic correction.
@@ -13072,7 +14763,7 @@ This puts a suitable gap between two graphics.
@end example
@noindent
-@xref{Spacing in math mode} for @code{\quad} and @code{\qquad}. These
+@xref{Spacing in math mode}, for @code{\quad} and @code{\qquad}. These
are lengths from centuries of typesetting and so may be a better choice
in many circumstances than arbitrary lengths, such as you get with
@code{\hspace}.
@@ -13378,7 +15069,7 @@ 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 @code{\frenchspacing}
-(the command is from Plain @TeX{}) switches to the tradition that all
+(the command is from plain @TeX{}) switches to the tradition that all
spaces are treated equally.
@@ -13403,7 +15094,9 @@ Reset the @LaTeX{} space factor values to the default
@cindex \NEWLINE
@cindex \SPACE
+@cindex \ (backslash-space)
@cindex \TAB
+@findex \SPACE
This section refers to the command consisting of two characters, a
backslash followed by a space. Synopsis:
@@ -13443,7 +15136,7 @@ in @code{\TeX\ is nice}. (But using curly parentheses, as in
@code{\TeX@{@} is best}, has the advantage of still working if the next
character is a period.) The other common use is that it marks a period
as ending an abbreviation instead of ending a sentence, as in @code{So
-says Prof.\ Smith} (@pxref{\@@}).
+says Prof.\ Smith} or @code{Jones et al.\ (1993)} (@pxref{\@@}).
Under normal circumstances, @code{\}@key{tab} and @code{\}@key{newline}
are equivalent to backslash-space, @code{\ }.
@@ -13458,8 +15151,9 @@ are equivalent to backslash-space, @code{\ }.
@findex ~
@cindex tie
-@cindex space, hard
@cindex space, unbreakable
+@cindex hard space
+@cindex unbreakable space
@cindex NBSP
Synopsis:
@@ -13483,28 +15177,36 @@ Thanks to Prof.~Lerman.
In addition, despite the period, @LaTeX{} does not use the
end-of-sentence spacing (@pxref{\@@}).
-Ties prevent the end of line separation of things where that could cause
-confusion. But they also reduce @LaTeX{}'s options when it breaks lines
-into paragraphs, so you can use too many. They are also matters of
-taste, sometimes alarmingly dogmatic taste, among readers. Nevertheless,
-here are some usage models, many of them from the @TeX{}book.
+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 @code{\mbox} (@pxref{\mbox & \makebox}).
+
+They are also matters of taste, sometimes alarmingly dogmatic taste,
+among readers. Nevertheless, here are some usage models, many of them
+from @cite{The @TeX{}book}.
@itemize @bullet
@item
Between an enumerator and its item, such as in references:
@code{Chapter~12}, or @code{Theorem~\ref@{th:Wilsons@}}, or
-@code{Figure~\ref@{fig:KGraph@}}. When cases are enumerated inline:
-@code{(b)~Show that $f(x)$ is (1)~continuous, and (2)~bounded}.
+@code{Figure~\ref@{fig:KGraph@}}.
+
+@item
+When cases are enumerated inline: @code{(b)~Show that $f(x)$ is
+(1)~continuous, and (2)~bounded}.
@PkgIndex{siunitx}
@item
Between a number and its unit: @code{$745.7.8$~watts} (the
@file{siunitx} package has a special facility for this) or
@code{144~eggs}. This includes between a month and a date:
-@code{October~12} or @code{12~Oct}. In general, in any expressions where
-numbers and abbreviations or symbols are separated by a space:
+@code{October~12} or @code{12~Oct}. In general, in any expressions
+where numbers and abbreviations or symbols are separated by a space:
@code{AD~565}, or @code{2:50~pm}, or @code{Boeing~747}, or
-@code{268~Plains Road}, or @code{\$$1.4$~billion}.
+@code{268~Plains Road}, or @code{\$$1.4$~billion}. Other common
+choices here are a thin space (@pxref{\thinspace & \negthinspace}) and
+no space at all.
@item
When mathematical phrases are rendered in words: @code{equals~$n$}, or
@@ -13521,14 +15223,11 @@ Between symbols in series: @code{$1$,~$2$, or~$3$} or @code{$1$,~$2$,
\ldots,~$n$}.
@item
-Between a person's forenames and between multiple surnames:
+Between a person's given names and between multiple surnames:
@code{Donald~E. Knuth}, or @code{Luis~I. Trabb~Pardo}, or
-@code{Charles~XII} (but you must give TeX places to break the line so
-you may do @code{Charles Louis Xavier~Joseph de~la Vall\'ee~Poussin}).
-
-@item
-Before a dash: @code{pages 12~--14} or @code{it is~--- it must be
-said~--- plausible}.
+@code{Charles~XII}---but you must give @TeX{} places to break the line
+so you might do @code{Charles Louis Xavier~Joseph de~la
+Vall\'ee~Poussin}.
@end itemize
@@ -13550,14 +15249,14 @@ Synopsis, one of:
\negthinspace
@end example
-Produce an unbreakable and unstretchable space of 1/6@dmn{em} and
--1/6@dmn{em}. These are the text mode equivalents of @code{\,} and
-@code{\!} (@pxref{Spacing in math mode/\thinspace}). You can use
-@code{\,} as a synonym for @code{\thinspace} in text mode.
+These produce unbreakable and unstretchable spaces of 1/6@dmn{em} and
+-1/6@dmn{em}, respectively. These are the text mode equivalents of
+@code{\,} and @code{\!} (@pxref{Spacing in math mode/\thinspace}).
+
+You can use @code{\,} as a synonym for @code{\thinspace} in text mode.
-The @code{\negthinspace} command is used in text mode mostly for
-fiddling with spaces. One common use of @code{\thinspace} is as the
-space between nested quotes.
+One common use of @code{\thinspace} is as the space between nested
+quotes:
@example
Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace''
@@ -13566,9 +15265,15 @@ Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace''
@noindent
Another use is that some style guides call for a @code{\thinspace}
between an ellipsis and a sentence ending period (other style guides,
-though, think the three dots are quite enough already). Still another
-use is between initials, as in @code{D.\thinspace E.\ Knuth}.
+think the three dots and/or four dots are plenty). Another
+style-specific use is between initials, as in @code{D.\thinspace E.\
+Knuth}.
+@LaTeX{} provides a variety of similar spacing commands
+(@pxref{Spacing in math mode}). With @code{amsmath}, or as of the
+2020-10-01 @LaTeX{} release, they can be used in text mode as well as
+math mode, including @code{\!} for @code{\negthinspace}; before that,
+they were available only in math mode.
@node \/
@section @code{\/}
@@ -13583,10 +15288,11 @@ Synopsis:
@end example
Insert an @dfn{italic correction}, a small space defined by the font
-designer for each character, to avoid the character colliding with
-whatever follows. When you use @code{\/}, @LaTeX{} takes the correction
-from the font metric file, scales it by any scaling that has been
-applied to the font, and then inserts that much horizontal space.
+designer for each character (possibly zero), to avoid the character
+colliding with whatever follows. When you use @code{\/}, @LaTeX{}
+takes the correction from the font metric file, scales it by any
+scaling that has been applied to the font, and then inserts that much
+horizontal space.
Here, were it not for the @code{\/}, the @var{before-character}
italic@tie{}f would hit the @var{after-character} roman@tie{}H
@@ -13596,22 +15302,34 @@ italic@tie{}f would hit the @var{after-character} roman@tie{}H
@end example
@noindent
-because the italic letter leans far to the right.
+because the italic letter f leans far to the right.
If @var{after-character} is a period or comma then don't insert an
-italic correction since those punctuation symbols have a very small
-height. However, with semicolons or colons as well as with normal
-letters, the italic correction can help.
+italic correction since those punctuation symbols are so low to the
+baseline already. However, with semicolons or colons, as well as with
+normal letters, the italic correction can help. It is typically used
+between a switch from italic or slanted fonts to an upright font.
-When you use commands such as @code{\textit} or @code{\itshape} to
-change fonts, @LaTeX{} will automatically insert any needed italic
-correction (@pxref{Font styles}).
+When you use commands such as @code{\emph} and @code{\textit} and
+@code{\textsl} to change fonts, @LaTeX{} automatically inserts the
+italic correction when needed (@pxref{Font styles}). However,
+declarations such as @code{\em} and @code{\itshape} and
+@code{\slshape} do not automatically insert italic corrections.
-Roman characters can also have an italic correction. An example is in
-the name @code{pdf\/\TeX}.
+Upright characters can also have an italic correction. An example
+where this is needed is the name @code{pdf\/\TeX}. However, most
+upright characters have a zero italic correction. Some font creators
+do not include italic correction values even for italic fonts.
-There is no concept of italic correction in math mode; spacing is done
-in a different way.
+@findex \fontdimen1
+@cindex font dimension, slant
+Technically, @LaTeX{} uses another font-specific value, the so-called
+slant parameter (namely @code{\fontdimen1}), to determine whether to
+possibly insert an italic correction, rather than tying the action to
+particular font commands.
+
+There is no concept of italic correction in math mode; math spacing is
+done in a different way.
@node \hrulefill & \dotfill
@@ -13907,7 +15625,7 @@ The new day dawned cold.
@end example
@noindent
-(@xref{\bigskip & \medskip & \smallskip} for common inter-paragraph
+(@xref{\bigskip & \medskip & \smallskip}, for common inter-paragraph
spaces.)
The @code{*}-version inserts vertical space that non-discardable. More
@@ -14029,7 +15747,7 @@ The two rules here are 22@dmn{pt} apart: the sum of the
Now uncomment the second @code{\addvspace}. It does not make the gap
20@dmn{pt} longer; instead the gap is the sum of @code{\baselineskip}
and 20@dmn{pt}. So @code{\addvspace} in a sense does the opposite of
-its name --- it makes sure that multiple vertical spaces do not
+its name---it makes sure that multiple vertical spaces do not
accumulate, but instead that only the largest one is used.
@LaTeX{} uses this command to adjust the vertical space above or below
@@ -14053,6 +15771,7 @@ with a @code{\par} command (@pxref{\par}), as in the above example.
At its core, @LaTeX{} puts things in boxes and then puts the boxes on a
page. So these commands are central.
+@PkgIndex{adjustbox}
There are many packages on CTAN that are useful for manipulating boxes.
One useful adjunct to the commands here is @file{adjustbox}.
@@ -14092,13 +15811,13 @@ LR mode (@pxref{Modes}) so it is not broken into lines. The
Because @code{text} is not broken into lines, you can use @code{\mbox}
to prevent hyphenation. In this example, @LaTeX{} will not hyphenate
-the table name, @samp{T-4}.
+the tank name, @samp{T-34}.
@example
-See Table~\mbox@{T-4@}
+The soviet tank \mbox@{T-34@} is a symbol of victory against nazism.
@end example
-The first two command versions, @code{\mbox} and @code{\makebox}, are
+The first two command synopsis versions, @code{\mbox} and @code{\makebox}, are
roughly equivalent. They create a box just wide enough to contain the
@var{text}. (They are like plain @TeX{}'s @code{\hbox}.)
@@ -14130,7 +15849,7 @@ size you can say this.
\makebox[2\width]@{Get a stretcher@}
@end example
-For the fourth command version the optional argument @var{position}
+For the fourth command synopsis version the optional argument @var{position}
gives position of the text within the box. It may take the following
values:
@@ -14165,12 +15884,11 @@ puts the value of the quiz questions to the left of those questions.
@noindent
@PkgIndex{TikZ}
@PkgIndex{Asymptote}
-The right edge of the output @samp{10 points } (note the ending space)
-will be just before the @samp{What} (note the space after
-@samp{points}). You can use @code{\makebox} similarly when making
-graphics, such as in @file{TikZ} or @file{Asymptote}, where you put the
-edge of the text at a known location, regardless of the length of that
-text.
+The right edge of the output @samp{10 points } (note the ending space
+after @samp{points}) will be just before the @samp{What}. You can use
+@code{\makebox} similarly when making graphics, such as in @file{TikZ}
+or @file{Asymptote}, where you put the edge of the text at a known
+location, regardless of the length of that text.
For boxes with frames see@tie{}@ref{\fbox & \framebox}. For colors
see@tie{}@ref{Colored boxes}.
@@ -14179,11 +15897,12 @@ There is a related version of @code{\makebox} that is used within the
@code{picture} environment, where the length is given in terms of
@code{\unitlength} (@pxref{\makebox (picture)}).
-If you put a double-backslash into @var{text} then @LaTeX{} will not
-give you a new line; for instance @code{\makebox@{abc def \\ ghi@}}
-outputs @samp{abc defghi} while @code{\makebox@{abc def \par ghi@}}
-outputs @samp{abc def ghi}, but neither go to a second line. To get
-multiple lines see@tie{}@ref{\parbox} and@tie{}@ref{minipage}.
+As @var{text} is typeset in LR mode, neither a double backslash
+@code{\\} nor @code{\par} will give you a new line; for instance
+@code{\makebox@{abc def \\ ghi@}} outputs @samp{abc defghi} while
+@code{\makebox@{abc def \par ghi@}} outputs @samp{abc def ghi}, both on
+a single line. To get multiple lines see@tie{}@ref{\parbox}
+and@tie{}@ref{minipage}.
@node \fbox & \framebox
@@ -14219,7 +15938,7 @@ The first two command invocations, @code{\fbox@{...@}} and
@code{\framebox@{...@}}, are roughly the same. As to the third and
fourth invocations, the optional arguments allow you to specify the box
width as @var{width} and the position of the text inside that box as
-@var{position}. @xref{\mbox & \makebox} for the full description but
+@var{position}. @xref{\mbox & \makebox}, for the full description but
here is an example creating an empty box that is 1/4@dmn{in} wide.
@example
@@ -14274,7 +15993,7 @@ paragraph, and then frame the result.
\end@{minipage@}@}
@end example
-@xref{Colored boxes} for colors other than black and white.
+@xref{Colored boxes}, for colors other than black and white.
The @code{picture} environment has a version of this command where the
units depend on @code{picture}'s @code{\unitlength} (@pxref{\framebox
@@ -14326,10 +16045,10 @@ in that box. It should not have any paragraph-making components.
There are three optional arguments, @var{position}, @var{height}, and
@var{inner-pos}. The @var{position} gives the vertical alignment of the
-@code{parbox} with respect to the surrounding material. The possible
+@dfn{parbox} with respect to the surrounding material. The supported
values are @code{c} or @code{m} to make the vertical center of the
-@code{parbox} lines up with the center of the adjacent line (this is the
-default), or @code{t} to match the top line of the @code{parbox} with
+parbox lines up with the center of the adjacent text line (this is the
+default), or @code{t} to match the top line of the parbox with
the baseline of the surrounding material, or @code{b} to match the
bottom line.
@@ -14359,12 +16078,12 @@ Synopsis, one of:
Raise or lower @var{text}. This command is fragile (@pxref{\protect}).
-This example makes a command for the restriction of a function by
-lowering the vertical bar symbol.
+This example makes a command for denoting the restriction of a function
+by lowering the vertical bar symbol.
@c credit: egreg https://tex.stackexchange.com/a/278631/121234
@example
-\newcommand\restricted[1]@{\raisebox@{-.5ex@}@{$|$@}_@{#1@}@}
+\newcommand*\restricted[1]@{\raisebox@{-.5ex@}@{$|$@}_@{#1@}@}
$f\restricted@{A@}$
@end example
@@ -14392,7 +16111,7 @@ This will align two graphics on their top (@pxref{Graphics}).
@c credit: FAQ https://texfaq.org/FAQ-topgraph
@example
-\usepackage@{graphicx@} \usepackage@{calc@} % in preamble
+\usepackage@{graphicx,calc@} % in preamble
...
\begin@{center@}
\raisebox@{1ex-\height@}@{%
@@ -14426,13 +16145,13 @@ Synopsis, one of:
Typeset @var{text} just as with @code{\makebox} (@pxref{\mbox &
\makebox}) except that @LaTeX{} does not output it but instead saves it
-in a storage bin named @var{box-cmd}. The bin name @var{box-cmd} begins
-with a backslash, @code{\}. You must have previously allocated the bin
-@var{box-cmd} with @code{\newsavebox} (@pxref{\newsavebox}).The
-@code{\sbox} command is robust while @code{\savebox} is fragile
-(@pxref{\protect}).
+in a box register referred to by a variable named @var{box-cmd}. The
+variable name @var{box-cmd} begins with a backslash, @code{\}. You must
+have previously allocated the box register @var{box-cmd} with @code{\newsavebox}
+(@pxref{\newsavebox}). The @code{\sbox} command is robust while
+@code{\savebox} is fragile (@pxref{\protect}).
-This creates and uses a bin.
+This creates and uses a box register.
@example
\newsavebox@{\fullname@}
@@ -14440,34 +16159,34 @@ This creates and uses a bin.
...
\usebox@{\fullname@}! His name is my name, too!
Whenever we go out, the people always shout!
-There goes \\usebox@{\fullname@}! Ya da da da da da da.
+There goes \usebox@{\fullname@}! Ya da da da da da da.
@end example
@noindent
-One advantage of using and reusing a bin over a @code{\newcommand} is
-efficiency, that @LaTeX{} need not repeatedly retypeset the contents.
-See the example below.
+One advantage of using and reusing a box register over a
+@code{\newcommand} macro variable is efficiency, that @LaTeX{} need not
+repeatedly retypeset the contents. See the example below.
The first two command invocations,
@code{\sbox@{@var{box-cmd}@}@{@var{text}@}} and
@code{\savebox@{@var{box-cmd}@}@{@var{text}@}}, are roughly equivalent.
As to the third and fourth, the optional arguments allow you to specify
the box width as @var{width}, and the position of the text inside that
-box as @var{position}. @xref{\mbox & \makebox} for the full
+box as @var{position}. @xref{\mbox & \makebox}, for the full
description.
In the @code{\sbox} and @code{\savebox} commands the @var{text} is
typeset in LR mode so it does not have line breaks (@pxref{Modes}). If
you use these then @LaTeX{} doesn't give you an error but it ignores
-what you want: if you enter @code{\sbox@{\newbin@}@{test \\ test@}} and
-@code{\usebox@{\newbin@}} then you get @samp{testtest}, while if you
-enter @code{\sbox@{\newbin@}@{test \par test@}} and
-@code{\usebox@{\newbin@}} then you get @samp{test test}, but no error or
+what you want: if you enter @code{\sbox@{\newreg@}@{test \\ test@}} and
+@code{\usebox@{\newreg@}} then you get @samp{testtest}, while if you
+enter @code{\sbox@{\newreg@}@{test \par test@}} and
+@code{\usebox@{\newreg@}} then you get @samp{test test}, but no error or
warning. To fix this use a @code{\parbox} or @code{minipage} as here.
@c credit: egreg https://tex.stackexchange.com/a/41668/121234
@example
-\savebox@{\abin@}@{%
+\savebox@{\areg@}@{%
\begin@{minipage@}@{\linewidth@}
\begin@{enumerate@}
\item First item
@@ -14475,17 +16194,17 @@ warning. To fix this use a @code{\parbox} or @code{minipage} as here.
\end@{enumerate@}
\end@{minipage@}@}
...
-\usebox@{\abin@}
+\usebox@{\areg@}
@end example
-As an example of the efficiency of reusing a bin's contents, this puts
+As an example of the efficiency of reusing a register's contents, this puts
the same picture on each page of the document by putting it in the
header. @LaTeX{} only typesets it once.
@example
\usepackage@{graphicx@} % all this in the preamble
-\newsavebox@{\sealbin@}
-\savebox@{\sealbin@}@{%
+\newsavebox@{\sealreg@}
+\savebox@{\sealreg@}@{%
\setlength@{\unitlength@}@{1in@}%
\begin@{picture@}(0,0)%
\put(1.5,-2.5)@{%
@@ -14495,15 +16214,15 @@ header. @LaTeX{} only typesets it once.
\end@{tabular@}@}
\end@{picture@}%
@}
-\markright@{\usebox@{\sealbin@}@}
+\markright@{\usebox@{\sealreg@}@}
\pagestyle@{headings@}
@end example
@noindent
The @code{picture} environment is good for fine-tuning the placement.
-If the bin has not already been defined then you get something like
-@samp{Undefined control sequence. <argument> \nobin}.
+If the register @code{\noreg} has not already been defined then you get something like
+@samp{Undefined control sequence. <argument> \noreg}.
@node lrbox
@@ -14519,26 +16238,27 @@ Synopsis:
\end@{lrbox@}
@end example
-The @var{text} inside the environment is saved in the bin
-@code{@var{box-cmd}}. The @var{box-cmd} must begin with a
-backslash. You must create this bin in advance with @code{\newsavebox}
-(@pxref{\newsavebox}). This is the environment form of the @code{\sbox}
-and @code{\savebox} commands, and is equivalent to them. @xref{\sbox &
-\savebox} for the full information.
+This is the environment form of the @code{\sbox} and @code{\savebox}
+commands, and is equivalent to them. for the full description,
+@xref{\sbox & \savebox}.
-In this example the environment is convenient for entering the
-@code{tabular}.
+The @var{text} inside the environment is saved in the box register
+referred to by variable @code{@var{box-cmd}}. The variable name
+@var{box-cmd} must begin with a backslash, @code{\}. You must allocate
+this box register in advance with @code{\newsavebox}
+(@pxref{\newsavebox}). In this example the environment is convenient
+for entering the @code{tabular}.
@example
-\newsavebox@{\jhbin@}
-\begin@{lrbox@}@{\jhbin@}
+\newsavebox@{\jhreg@}
+\begin@{lrbox@}@{\jhreg@}
\begin@{tabular@}@{c@}
\includegraphics[height=1in]@{jh.png@} \\
Jim Hef@{@}feron
\end@{tabular@}
\end@{lrbox@}
...
-\usebox@{\jhbin@}
+\usebox@{\jhreg@}
@end example
@@ -14554,11 +16274,11 @@ Synopsis:
\usebox@{@var{box-cmd}@}
@end example
-Produce the box most recently saved in the bin @var{box-cmd} by the
-commands @code{\sbox} or @code{\savebox}, or the @code{lrbox}
-environment. @xref{\sbox & \savebox} for more information and examples.
-(Note that @var{box-cmd} starts with a backslash.) This command is
-robust (@pxref{\protect}).
+Produce the box most recently saved in the box register @var{box-cmd} by
+the commands @code{\sbox} or @code{\savebox}, or the @code{lrbox}
+environment. For more information and examples, @xref{\sbox &
+\savebox}. (Note that the variable name @var{box-cmd} starts with a
+backslash, @code{\}.) This command is robust (@pxref{\protect}).
@node Color
@@ -14823,10 +16543,10 @@ synopses.
@example
Colors of \textcolor[rgb]@{0.33,0.14,0.47@}@{Purple@} and
-@{\color[rgb]@{0.72,0.60,0.37@} Gold@} for the team.
+@{\color[rgb]@{0.72,0.60,0.37@}Gold@} for the team.
@end example
-The format of @var{color specification } depends on the color model
+The format of @var{color specification} depends on the color model
(@pxref{Color models}). For instance, while @code{rgb} takes three
numbers, @code{gray} takes only one.
@@ -15033,7 +16753,7 @@ rectangle (unless another size is specified in the
@code{\includegraphics} command).
@item draft
-For each graphic file, it is not shown but instead the file name is
+For each graphic file, it is not shown but instead its file name is
printed in a box of the correct size. In order to determine the size,
the file must be present.
@@ -15068,11 +16788,6 @@ option has @LaTeX{} to read the size from the latter.
@cindex graphics
@cindex graphics package
@cindex configuration, graphics package
-@cindex EPS files
-@cindex JPEG files
-@cindex JPG files
-@cindex PDF graphic files
-@cindex PNG files
These commands configure the way @LaTeX{} searches the file system for
the graphic.
@@ -15098,16 +16813,17 @@ the documentation in @file{grfguide.pdf}, or the @LaTeX{} source, or your
Synopsis:
@example
-\graphicspath@{@var{list of dir names inside curly brackets}@}
+\graphicspath@{@var{list of directories inside curly braces}@}
@end example
Declare a list of directories to search for graphics files. This allows
you to later say something like @code{\includegraphics@{lion.png@}}
instead of having to give its path.
-@LaTeX{} always looks for graphic files first in the current directory.
-The declaration below tells the system to then look in the subdirectory
-@file{pix}, and then @file{../pix}.
+@LaTeX{} always looks for graphic files first in the current directory
+(and the output directory, if specified; @pxref{output directory}).
+The declaration below tells the system to then look in the
+subdirectory @file{pix}, and then @file{../pix}.
@example
\usepackage@{graphicx@} % or graphics; put in preamble
@@ -15142,7 +16858,7 @@ current directory,
@noindent
for each of the listed directories, @LaTeX{} concatenates it with the
-file name and searches for the result, checking for @file{pix/lion.png}
+filename and searches for the result, checking for @file{pix/lion.png}
and then @file{../pix/lion.png}. This algorithm means that the
@code{\graphicspath} command does not recursively search subdirectories:
if you issue @code{\graphicspath@{@{a/@}@}} and the graphic is in
@@ -15192,7 +16908,7 @@ files.
@end example
@noindent
-Because the file name @file{lion} does not have a period, @LaTeX{} uses
+Because the filename @file{lion} does not have a period, @LaTeX{} uses
the extension list. For each directory in the graphics path
(@pxref{\graphicspath}), @LaTeX{} will try the extensions in the order
given. If it does not find such a file after trying all the directories
@@ -15209,9 +16925,12 @@ your document; the printer driver has a sensible default. For example,
the most recent @file{pdftex.def} has this extension list.
@example
-.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2
+.pdf,.png,.jpg,.mps,.jpeg,.jbig2,.jb2,.PDF,.PNG,.JPG,.JPEG,.JBIG2,.JB2
@end example
+@PkgIndex{grfext}
+To change the order, use the @code{grfext} package.
+
You can use this command anywhere in the document. You can use it more
than once. Show its value with
@code{\makeatletter\typeout@{\Gin@@extensions@}\makeatother}.
@@ -15256,7 +16975,7 @@ This describes the four arguments.
@item extension
The file extension to which this rule applies. The extension is anything
after and including the first dot in the filename. Use the Kleene star,
-@code{*}, to denote the default behaviour for all undeclared extensions.
+@code{*}, to denote the default behavior for all undeclared extensions.
@item type
The type of file involved. This type is a string that must be defined
@@ -15286,7 +17005,7 @@ other format is available.)
@item command
A command that will be applied to the
-file. This is very often left blank. This command must start with a
+file. This is very often left empty. This command must start with a
single backward quote. Thus,
@code{\DeclareGraphicsRule@{.eps.gz@}@{eps@}@{.eps.bb@}@{`gunzip -c
#1@}} specifies that any file with the extension @file{.eps.gz} should
@@ -15378,10 +17097,10 @@ is @code{\includegraphics@{"sister picture.jpg"@}}.
The @code{\includegraphics@{@var{filename}@}} command decides on the
type of graphic by splitting @var{filename} on the first dot. You can
-use @var{filename} with no dot, as in @code{\includegraphics@{turing@}}
-and then @LaTeX{} tries a sequence of extensions such as @code{.png} and
-@code{.pdf} until it finds a file with that extension
-(@pxref{\DeclareGraphicsExtensions}).
+instead use @var{filename} with no dot, as in
+@code{\includegraphics@{turing@}}, and then @LaTeX{} tries a sequence of
+extensions such as @code{.png} and @code{.pdf} until it finds a file
+with that extension (@pxref{\DeclareGraphicsExtensions}).
If your file name contains dots before the extension then you can hide
them with curly braces, as in
@@ -15390,7 +17109,7 @@ the @file{graphicx} package then you can use the options @code{type} and
@code{ext}; see below. This and other filename issues are also handled
with the package @file{grffile}.
-This example puts a graphic in a figure environment so @LaTeX{} can
+This example puts a graphic in a @code{figure} environment so @LaTeX{} can
move it to the next page if fitting it on the current page is awkward
(@pxref{figure}).
@@ -15465,8 +17184,10 @@ two will end with different widths and heights.
There are many options. The primary ones are listed first.
+@cindex bounding box
+@cindex box, bounding
Note that a graphic is placed by @LaTeX{} into a box, which is
-traditionally referred to as its bounding box (distinct from the
+traditionally referred to as its @dfn{bounding box} (distinct from the
PostScript BoundingBox described below). The graphic's printed area may
go beyond this box, or sit inside this box, but when @LaTeX{} makes up a
page it puts together boxes and this is the box allocated for the
@@ -15480,7 +17201,7 @@ is @code{\includegraphics[width=1in]@{plot@}}. You can use the standard
@TeX{} dimensions (@pxref{Units of length}) and also convenient is
@code{\linewidth}, or in a two-column document, @code{\columnwidth}
(@pxref{Page layout parameters}). An example is that by using the
-@file{calc} package you can make the graphic be 1@tie{}cm narrow than
+@file{calc} package you can make the graphic be 1@tie{}cm narrower than
the width of the text with
@code{\includegraphics[width=\linewidth-1.0cm]@{hefferon.jpg@}}.
@@ -15494,7 +17215,7 @@ layout parameters}). For instance, the command
graphic a quarter of the height of the text area.
@item totalheight
-@anchor{includegraphics totalheght}
+@anchor{includegraphics totalheight}
The graphic will be shown so its bounding box has this height plus
depth. This differs from the height if the graphic was rotated. For
instance, if it has been rotated by -90 then it will have zero height
@@ -15518,7 +17239,7 @@ is the graphic wider than @code{width} nor taller than @code{height} (or
@item scale
Factor by which to scale the graphic. To make a graphic twice its
nominal size, enter @code{\includegraphics[scale=2.0]@{...@}}. This
-number may be any value; a number between 1 and@tie{}0 will shrink the
+number may be any value; a number between 0 and@tie{}1 will shrink the
graphic and a negative number will reflect it.
@item angle
@@ -15550,10 +17271,10 @@ These are lesser-used options.
@item viewport
Pick out a subregion of the graphic to show. Takes four arguments,
separated by spaces and given in @TeX{} dimensions, as with
-@code{\includegraphics[.., viewport=0in 0in 1in 0.618in]@{...@}}. The
-dimensions default to big points,@tie{}@code{bp}. They are taken
-relative to the origin specified by the bounding box. See also the
-@code{trim} option.
+@code{\includegraphics[.., viewport=0in 0in 1in 0.618in]@{...@}}. When
+the unit is omitted, the dimensions default to big
+points,@tie{}@code{bp}. They are taken relative to the origin specified
+by the bounding box. See also the @code{trim} option.
@anchor{includegraphics trim}
@item trim
@@ -15611,7 +17332,7 @@ set with @code{interpolate=true} or just specified as here.
@item quiet
Do not write information to the log. You can set it with
@code{quiet=true} or just specified it with
-@code{\includegraphics[...,quite,...]@{...@}},
+@code{\includegraphics[...,quiet,...]@{...@}},
@anchor{includegraphics draft}
@item draft
@@ -15709,7 +17430,7 @@ Only use this in conjunction with the option @code{type}.
@anchor{includegraphics command}
@item command
Specify a command to be applied to this file. Only use this in
-conjunction with the option @code{type}. @xref{Command line options}
+conjunction with the option @code{type}. @xref{Command line options},
for a discussion of enabling the @code{\write18} functionality to run
external commands.
@@ -15740,7 +17461,7 @@ Synopses if you use the @file{graphicx} package:
Put @var{material} in a box and rotate it @var{angle} degrees
counterclockwise.
-This example rotates the table column heads forty five degrees.
+This example rotates the table column heads forty-five degrees.
@example
\begin@{tabular@}@{ll@}
@@ -15913,6 +17634,7 @@ special meaning do not correspond to simple characters you can type.
* Text symbols:: Inserting other non-letter symbols in text.
* Accents:: Inserting accents.
* Additional Latin letters:: Inserting other non-English characters.
+* inputenc package:: Set the input file text encoding.
* \rule:: Inserting lines and rectangles.
* \today:: Inserting today's date.
@end menu
@@ -15927,7 +17649,8 @@ special meaning do not correspond to simple characters you can type.
@cindex characters, special
@LaTeX{} sets aside the following characters for special purposes. For
example, the percent sign@tie{}@code{%} is for comments. They are
-called @dfn{reserved characters} or @dfn{special characters}.
+called @dfn{reserved characters} or @dfn{special characters}. They are
+all discussed elsewhere in this manual.
@example
# $ % & @{ @} _ ~ ^ \
@@ -15950,13 +17673,13 @@ typing @code{\$1.23} will produce@tie{}@code{$1.23} in your output.
@findex \textbackslash
As to the last three characters, to get a tilde in the text body font
use @code{\~@{@}} (omitting the curly braces would result in the next
-character receiving a tilde accent). Similarly, to get a get a text
-body font circumflex use @code{\^@{@}}. To get a backslash in the font
-of the text body, enter @code{\textbackslash@{@}}.
+character receiving a tilde accent). Similarly, to get a text body
+font circumflex use @code{\^@{@}}. To get a backslash in the font of
+the text body, enter @code{\textbackslash@{@}}.
To produce the reserved characters in a typewriter font use
@code{\verb!!} as below (the double backslash@tie{}@code{\\} is only
-there to split the lines).
+there to split the lines in the output).
@example
\begin@{center@}
@@ -15972,6 +17695,7 @@ there to split the lines).
@cindex uppercase
@cindex lowercase
@cindex characters, case of
+@cindex changing case of characters
Synopsis:
@@ -15982,13 +17706,13 @@ Synopsis:
\MakeLowercase@{@var{text}@}
@end example
-Change the case of characters. The @TeX{} primitives commands
-@code{\uppercase} and @code{\lowercase} only work for American
-characters. The @LaTeX{} commands @code{\MakeUppercase} and
-@code{\MakeLowercase} commands also change characters accessed by
-commands such as @code{\ae} or @code{\aa}. The commands
-@code{\MakeUppercase} and @code{\MakeLowercase} are robust but they have
-moving arguments (@pxref{\protect}).
+Change the case of characters. The @TeX{} primitive commands
+@code{\uppercase} and @code{\lowercase} are set up by default to work
+only with the 26 letters a--z and A--Z. The @LaTeX{} commands
+@code{\MakeUppercase} and @code{\MakeLowercase} commands also change
+characters accessed by commands such as @code{\ae} or @code{\aa}. The
+commands @code{\MakeUppercase} and @code{\MakeLowercase} are robust
+but they have moving arguments (@pxref{\protect}).
These commands do not change the case of letters used in the name of a
command within @var{text}. But they do change the case of every other
@@ -16019,10 +17743,21 @@ The @file{textcase} package brings some of the missing feature of the
standard @LaTeX{} commands @code{\MakeUppercase} and
@code{\MakeLowerCase}.
-@PkgIndex{mfirstuc}
+@PkgIndex{mfirstuc}
To uppercase only the first letter of words, you can use the package
@file{mfirstuc}.
+@PkgIndex{expl3}
+@cindex Wright, Joseph
+Handling all the casing rules specified by Unicode, e.g., for
+non-Latin scripts, is a much bigger job than anything envisioned in
+the original @TeX{} and @LaTeX{}. It has been implemented in the
+@code{expl3} package as of 2020. The article ``Case changing: From
+@TeX{} primitives to the Unicode algorithm'', (Joseph Wright,
+@cite{TUGboat}@tie{}41:1,
+@url{https://tug.org/TUGboat/tb41-1/tb127wright-case.pdf}), gives a
+good overview of the topic, past and present.
+
@node Symbols by font position
@section Symbols by font position
@@ -16033,13 +17768,14 @@ To uppercase only the first letter of words, you can use the package
You can access any character of the current font using its number with
the @code{\symbol} command. For example, the visible space character
-used in the @code{\verb*} command has the code decimal 32, so it can be
-typed as @code{\symbol@{32@}}.
+used in the @code{\verb*} command has the code decimal 32 in the
+standard Computer Modern typewriter font, so it can be typed as
+@code{\symbol@{32@}}.
You can also specify numbers in octal (base 8) by using a @code{'}
-prefix, or hexadecimal (base 16) with a @code{"} prefix, so the previous
-example could also be written as @code{\symbol@{'40@}} or
-@code{\symbol@{"20@}}.
+prefix, or hexadecimal (base 16) with a @code{"} prefix, so the
+visible space at 32 decimal could also be written as
+@code{\symbol@{'40@}} or @code{\symbol@{"20@}}.
@node Text symbols
@@ -16049,10 +17785,13 @@ example could also be written as @code{\symbol@{'40@}} or
@cindex symbols, text
@findex textcomp @r{package}
-@LaTeX{} provides commands to generate a number of non-letter symbols in
-running text. Some of these, especially the more obscure ones, are not
-available in OT1. Unless you are using Xe@LaTeX{} or Lua@LaTeX{} then
-you may need to load the @code{textcomp} package.
+@cindex TS1 encoding
+@LaTeX{} provides commands to generate a number of non-letter symbols
+in running text. Some of these, especially the more obscure ones, are
+not available in OT1. As of the @LaTeX{} February 2020 release, all
+symbols are available by default; before that, it was necessary to use
+the @code{textcomp} package for some (technically, those in the
+@code{TS1} font encoding).
@ftable @code
@item \copyright
@@ -16173,7 +17912,7 @@ The @TeX{} logo.
@item \textbigcircle
@cindex big circle symbols, in text
@cindex circle symbol, big, in text
-@BES{25EF,} Big circle symbol.
+@BES{25EF}, Big circle symbol.
@item \textbraceleft
@cindex left brace, in text
@@ -16191,7 +17930,7 @@ The @TeX{} logo.
@item \textcircled@{@var{letter}@}
@cindex circled letter, in text
-@BES{24B6,} Circle around @var{letter}.
+@BES{24B6}, Circle around @var{letter}.
@item \textcompwordmark
@itemx \textcapitalcompwordmark
@@ -16221,19 +17960,24 @@ $ Dollar sign.
@item \textemdash @r{(or @code{---})}
@cindex em-dash
---- Em-dash (used for punctuation, as in
-@code{The playoffs --- if you are fortunate enough to make the playoffs ---
-is more like a sprint.}).
+@raggedright
+--- Em-dash. Used for punctuation, usually similar to commas or
+parentheses, as in `@code{The playoffs---if you're lucky
+enough to make the playoffs---are more like a sprint.}' Conventions
+for spacing around em-dashes vary widely.
+@end raggedright
@item \textendash @r{(or @code{--})}
@cindex e-dash
--- En-dash (used for ranges, as in @code{See pages 12--14}).
+-- En-dash. Used for ranges, as in `@code{see pages 12--14}'.
@item \texteuro
@cindex euro symbol
@cindex currency, euro
@PkgIndex{eurosym}
-The Euro symbol: @euro{}. For an alternative glyph design, try the
+The Euro currency symbol: @euro{}.
+@PkgIndex{eurosym}
+For an alternative glyph design, try the
@file{eurosym} package; also, most fonts nowadays come with their own
Euro symbol (Unicode U+20AC).
@@ -16241,10 +17985,24 @@ Euro symbol (Unicode U+20AC).
@cindex exclamation point, upside-down
@exclamdown{} Upside down exclamation point.
+@item \textfiguredash
+@cindex figure dash character
+Dash used between numerals, Unicode U+2012. Defined in the June 2021
+release of @LaTeX{}. When used in pdf@TeX{}, approximated by an
+en-dash; with a Unicode engine, either typesets the glyph if available
+in the current font, or writes the usual ``Missing character'' warning
+to the log file.
+
@item \textgreater
@cindex greater than symbol, in text
> Greater than symbol.
+@item \texthorizontalbar
+@cindex horizontal bar character
+Horizontal bar character, Unicode U+2015. Defined in the June 2021
+release of @LaTeX{}. Behavior as with @code{\textfiguredash} above;
+the pdf@TeX{} approximation is an em-dash.
+
@item \textless
@cindex less than symbol, in text
< Less than symbol.
@@ -16252,7 +18010,15 @@ Euro symbol (Unicode U+20AC).
@item \textleftarrow
@cindex arrow, left, in text
@cindex left arrow, in text
-@BES{2190,} Left arrow.
+@BES{2190}, Left arrow.
+
+@item \textnonbreakinghyphen
+@cindex non-breaking hyphen character
+@cindex hyphen character, non-breaking
+Non-breaking hyphen character, Unicode U+2011. Defined in the June
+2021 release of @LaTeX{}. Behavior as with @code{\textfiguredash}
+above; the pdf@TeX{} approximation is a regular ASCII hyphen (with
+breaks disallowed after).
@item \textordfeminine
@itemx \textordmasculine
@@ -16295,7 +18061,7 @@ Euro symbol (Unicode U+20AC).
@cindex quote, single straight
@cindex straight single quote
@cindex single quote, straight
-@BES{0027,} Straight single quote. (From TS1 encoding.)
+@BES{0027}, Straight single quote. (From TS1 encoding.)
@item \textquotestraightbase
@itemx \textquotestraightdblbase
@@ -16313,12 +18079,12 @@ Single and double straight quotes on the baseline.
@item \textrightarrow
@cindex arrow, right, in text
@cindex right arrow, in text
-@BES{2192,} Right arrow.
+@BES{2192}, Right arrow.
@item \textthreequartersemdash
@cindex three-quarters em-dash
@cindex em-dash, three-quarters
-@BES{FE58,} ``Three-quarters'' em-dash, between en-dash and em-dash.
+@BES{FE58}, ``Three-quarters'' em-dash, between en-dash and em-dash.
@item \texttrademark
@cindex trademark symbol
@@ -16328,7 +18094,7 @@ Single and double straight quotes on the baseline.
@item \texttwelveudash
@cindex two-thirds em-dash
@cindex em-dash, two-thirds
-@BES{FE58,} ``Two-thirds'' em-dash, between en-dash and em-dash.
+@BES{FE58}, ``Two-thirds'' em-dash, between en-dash and em-dash.
@item \textunderscore
@cindex underscore, in text
@@ -16336,7 +18102,7 @@ _ Underscore.
@item \textvisiblespace
@cindex visible space symbol, in text
-@BES{2423,} Visible space symbol.
+@BES{2423}, Visible space symbol.
@end ftable
@@ -16351,13 +18117,16 @@ _ Underscore.
@PkgIndex{babel}
@PkgIndex{polyglossia}
@cindex multilingual support
-@LaTeX{} has wide support for many of the world's scripts and languages,
-through the @code{babel} package and related support if you are using
-pdf@LaTeX{}, or @file{polyglossia} if you are using Xe@LaTeX{} or
-Lua@LaTeX{}. This section does not cover that support. It only lists
-the core @LaTeX{} commands for creating accented characters. The
-@code{\capital...} commands shown here produce alternative forms for use
-with capital letters. These are not available with OT1.
+@LaTeX{} has wide support for many of the world's scripts and
+languages, provided through the core @code{babel} package, which
+supports pdf@LaTeX{}, Xe@LaTeX{} and Lua@LaTeX{}. The
+@file{polyglossia} package provides similar support with the latter
+two engines.
+
+This section does not cover that support. It only lists the core
+@LaTeX{} commands for creating accented characters. The
+@code{\capital...} commands shown here produce alternative forms for
+use with capital letters. These are not available with OT1.
Below, to make them easier to find, the accents are all illustrated with
lowercase @samp{o}.
@@ -16504,6 +18273,61 @@ its box.
@end table
+@menu
+* \accent:: Low level command to produce an accented character.
+@end menu
+
+
+@node \accent
+@subsection @code{\accent}
+@findex \accent
+
+Synopsis:
+
+@example
+\accent @var{number} @var{character}
+@end example
+
+A @TeX{} primitive command used to generate accented characters from
+accent marks and letters. The accent mark is selected by @var{number},
+a numeric argument, followed by a space and then a @var{character} argument
+constructs the accented character in the current font.
+
+These are accented @samp{e} characters.
+
+@example
+\accent18 e
+\accent20 e
+\accent21 e
+\accent22 e
+\accent23 e
+@end example
+
+@noindent
+The first is a grave, the second is breve, etc.
+
+The position of the accent is determined by the font designer and so the
+outcome of @code{\accent} use may differ between fonts. In @LaTeX{} it is
+desirable to have glyphs for accented characters rather than building
+them using @code{\accent}. Using glyphs that already contain the
+accented characters (as in T1 encoding) allows correct hyphenation
+whereas @code{\accent} disables hyphenation (specifically with OT1 font
+encoding where accented glyphs are absent).
+
+There can be an optional font change between @var{number} and
+@var{character}. Note also that this command sets the
+@code{\spacefactor} to 1000 (@pxref{\spacefactor}).
+
+An unavoidable characteristic of some Cyrillic letters and
+the majority of accented Cyrillic letters is that they must be
+assembled from multiple elements (accents, modifiers, etc.) while
+@code{\accent} provides for a single accent mark and a single letter
+combination. There are also cases where accents must appear between
+letters that \accent does not support. Still other cases exist where
+the letters I and J have dots above their lowercase counterparts that
+conflict with dotted accent marks. The use of @code{\accent} in these
+cases will not work as it cannot analyze upper/lower case.
+
@node Additional Latin letters
@section Additional Latin letters
@@ -16608,6 +18432,72 @@ font encoding, such as @sc{T1}.
@end table
+@node inputenc package
+@section @code{inputenc} package
+
+@findex inputenc
+
+Synopsis:
+
+@example
+\usepackage[@var{encoding-name}]@{inputenc@}
+@end example
+
+Declare the input file's text encoding to be @var{encoding-name}. 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.
+
+@cindex encoding, of input files
+@cindex character encoding
+@cindex Unicode
+In a computer file, the characters are stored according to a scheme
+called the @dfn{encoding}. There are many different encodings. The
+simplest is ASCII, which supports 95 printable characters, not enough
+for most of the world's languages. For instance, to typeset the
+a-umlaut character @"{a} in an ASCII-encoded @LaTeX{} source file, the
+sequence @code{\"a} 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.
+
+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.
+
+The @code{inputenc} 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).
+
+@example
+\usepackage[utf8]@{inputenc@}
+@end example
+
+Caution: use @code{inputenc} only with the pdf@TeX{} engine
+(@pxref{@TeX{} engines}). (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 or the @command{lualatex}
+command, and try to declare a non-UTF-8 encoding with @code{inputenc},
+such as @code{latin1}, then you will get the error @code{inputenc is
+not designed for xetex or luatex}.
+
+An @code{inputenc} package error such as @code{Invalid UTF-8 byte "96}
+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 @code{latin1} 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.
+
+In some documents, such as a collection of journal articles from a
+variety of authors, changing the encoding in mid-document may be
+necessary. Use the command
+@code{\inputencoding@{@var{encoding-name}@}}. The most common values
+for @var{encoding-name} are: @code{ascii}, @code{latin1},
+@code{latin2}, @code{latin3}, @code{latin4}, @code{latin5},
+@code{latin9}, @code{latin10}, and@tie{}@code{utf8}.
+
+
@node \rule
@section @code{\rule}
@@ -16624,8 +18514,8 @@ Produce a @dfn{rule}, a filled-in rectangle.
@cindex Halmos symbol
@cindex tombstone
-This produces a rectangular blob, sometimes called a Halmos symbol,
-often used to mark the end of a proof.
+This example produces a rectangular blob, sometimes called a Halmos symbol,
+or just ``qed'', often used to mark the end of a proof:
@example
\newcommand@{\qedsymbol@}@{\rule@{0.4em@}@{2ex@}@}
@@ -16654,7 +18544,7 @@ thickness is common in @LaTeX{}.
A rule that has zero width, or zero thickness, will not show up in the
output, but can cause @LaTeX{} to change the output around it.
-@xref{\strut} for examples.
+@xref{\strut}, for examples.
@node \today
@@ -16743,7 +18633,7 @@ a file with five included files.
This will bring in material from @file{pref.tex}, @file{chap1.tex},
@file{chap2.tex}, @file{append.tex}, and @file{bib.tex}. If you compile
this file, and then comment out all of the lines inside
-@code{\includeonly@{...@}} except for @code{chap1,} and compile again,
+@code{\includeonly@{...@}} except for @code{chap1}, and compile again,
then @LaTeX{} will only process the material in the first chapter.
Thus, your output will appear more quickly and be shorter to print.
However, the advantage of the @code{\includeonly} command is that
@@ -16751,7 +18641,7 @@ However, the advantage of the @code{\includeonly} command is that
information from the other parts of the document so these will appear in
your output correctly.
-@xref{Larger book template} for another example of @code{\includeonly}.
+@xref{Larger book template}, for another example of @code{\includeonly}.
@menu
* \endinput:: Stop including material from a file.
@@ -16788,12 +18678,13 @@ This will not appear.
@end example
This can be useful for putting documentation or comments at the end of a
-file, or for avoiding junk characters that can be added during mailing.
-It is also useful for debugging: one strategy to localize errors is to
-put @code{\endinput} halfway through the included file and see if the
-error disappears. Now, knowing which half contains the error, moving
-@code{\endinput} to halfway through that area further narrows down the
-location. This process rapidly finds the offending line.
+file, or for avoiding junk characters that can be added if the file is
+transmitted in the body of an email. It is also useful for debugging:
+one strategy to localize errors is to put @code{\endinput} halfway
+through the included file and see if the error disappears. Now, knowing
+which half contains the error, moving @code{\endinput} to halfway
+through that area further narrows down the location. This process
+rapidly finds the offending line.
After reading @code{\endinput}, @LaTeX{} continues to read to the end of
the line, so something can follow this command and be read nonetheless.
@@ -16826,10 +18717,12 @@ The @code{\include} command does three things: it executes
@code{\clearpage} (@pxref{\clearpage & \cleardoublepage}), then it
inputs the material from @file{@var{filename}.tex} into the document,
and then it does another @code{\clearpage}. This command can only
-appear in the document body. The @code{\includeonly} command controls
-which files will be read by @LaTeX{} under subsequent @code{\include}
-commands. Its list of filenames is comma-separated, and it can only
-appear in the preamble.
+appear in the document body.
+
+The @code{\includeonly} command controls which files will be read by
+@LaTeX{} under subsequent @code{\include} commands. Its list of
+filenames is comma-separated. It must appear in the preamble or even
+earlier, e.g., the command line; it can't appear in the document body.
This example root document, @file{constitution.tex}, brings in
three files, @file{preamble.tex}, @file{articles.tex}, and
@@ -16864,7 +18757,7 @@ in Order to form a more perfect Union, ...
Running @LaTeX{} on @file{constitution.tex} makes the material from the
three files appear in the document but also generates the auxiliary
files @file{preamble.aux}, @file{articles.aux}, and
-@file{amendments.tex}. These contain information such as page numbers
+@file{amendments.aux}. These contain information such as page numbers
and cross-references (@pxref{Cross references}). If you now comment out
@code{\includeonly}'s lines with @code{preamble} and @code{amendments}
and run @LaTeX{} again then the resulting document shows only the
@@ -16881,7 +18774,7 @@ The @code{\include} command makes a new page. To avoid that, see
@ref{\input} (which, however, does not retain the auxiliary
information).
-@xref{Larger book template} for another example using @code{\include}
+@xref{Larger book template}, for another example using @code{\include}
and @code{\includeonly}. That example also uses @code{\input} for some
material that will not necessarily start on a new page.
@@ -16938,8 +18831,8 @@ athiesm.tex.} (It will also create @file{athiesm.aux}.)
If you @code{\include} the root file in itself then you first get
@samp{LaTeX Error: Can be used only in preamble.} Later runs get
@samp{TeX capacity exceeded, sorry [text input levels=15]}. To fix
-this, you must remove the inclusion @code{\include@{root@}} but also
-delete the file @file{@var{root}.aux} and rerun @LaTeX{}.
+this, you must remove the inclusion @code{\include@{@var{root}@}} but
+also delete the file @file{@var{root}.aux} and rerun @LaTeX{}.
@node \input
@@ -17048,7 +18941,7 @@ This example illustrates the first command, @code{\tableofcontents}.
@noindent
Uncommenting the second line would cause that table to contain chapter
and section listings but not subsection listings, because the
-@code{\section} command has level@tie{}1. @xref{Sectioning} for level
+@code{\section} command has level@tie{}1. @xref{Sectioning}, for level
numbers of the sectioning units. For more on the @code{tocdepth}
@pxref{Sectioning/tocdepth}.
@@ -17059,7 +18952,7 @@ If you want a page break after the table of contents, write a
@code{\newpage} command after the @code{\tableofcontents} command, as
above.
-To make the table of contents @LaTeX{} stores the information in an
+To make the table of contents, @LaTeX{} stores the information in an
auxiliary file named @file{@var{root-file}.toc} (@pxref{Splitting the
input}). For example, this @LaTeX{} file @file{test.tex}
@@ -17073,63 +18966,146 @@ input}). For example, this @LaTeX{} file @file{test.tex}
@end example
@noindent
-writes the following line to @file{test.toc}.
+writes these lines to @file{test.toc}.
@example
\contentsline @{section@}@{\numberline @{1@}First section@}@{2@}
\contentsline @{subsection@}@{\numberline @{1.1@}First subsection@}@{2@}
@end example
+@findex \contentsline
@noindent
-The @code{section} or @code{subsection} is the sectioning unit. The
-hook @code{\numberline} lets you to change how the information appears
-in the table of contents. Of its two arguments, @code{1} or @code{1.1}
-is the sectioning unit number and @code{First section} or @code{First
-subsection} is the title. Finally, @code{2} is the page number on which
-the sectioning units start.
-
-One consequence of this auxiliary file storage strategy is that to get the
-contents page correct you must run @LaTeX{} twice, once to store the
-information and once to get it. In particular, the first time that you
-run @LaTeX{} on a new document, the table of contents page will be empty
-except for its @samp{Contents} header. Just run it again.
+Each line contains a single command, @code{\contentsline}
+(@pxref{\contentsline}). The first argument, the @code{section} or
+@code{subsection}, is the sectioning unit. The second argument has two
+components. The hook @code{\numberline} determines how the sectioning
+number, @code{1} or @code{1.1}, appears in the table of contents
+(@pxref{\numberline}). The remainder of the second argument of
+@code{\contentsline}, @samp{First section} or @samp{First subsection},
+is the sectioning title text. Finally, the third argument, @samp{2}, is
+the page number on which this sectioning unit starts.
+
+To typeset these lines, the document class provides
+@code{\l@@@var{section-unit}} commands such as
+@code{\l@@section@{@var{text}@}@{@var{pagenumber}@}} and
+@code{\l@@subsection@{@var{text}@}@{@var{pagenumber}@}}. These commands
+often use the @code{\@@dottedtocline} command
+(@pxref{\@@dottedtocline}).
+
+A consequence of @LaTeX{}'s strategy of using auxiliary files is that to
+get the correct information in the document you must run @LaTeX{} twice,
+once to store the information and the second time to retrieve it. In
+the ordinary course of writing a document authors run @LaTeX{} a number
+of times, but you may notice that the first time that you compile a new
+document, the table of contents page will be empty except for its
+@samp{Contents} header. Just run @LaTeX{} again.
The commands @code{\listoffigures} and @code{\listoftables} produce a
-list of figures and a list of tables. They work the same way as the
-contents commands; for instance, these work with information stored in
-@file{.lof} and @file{.lot} files.
+list of figures and a list of tables. Their information is stored in
+files with extension @file{.lof} and @file{.lot}. They work the same way
+as @code{\tableofcontents} but the latter is more common, so we use it
+for most examples.
+
+You can manually add material to the table of contents, the list of
+figures, and the list of tables. For instance, add a line about a
+section to the table of contents with
+@code{\addcontentsline@{toc@}@{section@}@{@var{text}@}}.
+(@pxref{\addcontentsline}). Add arbitrary material, that is, non-line
+material, with @code{\addtocontents}, as with the command
+@code{\addtocontents@{lof@}@{\protect\vspace@{2ex@}@}}, which adds
+vertical space to the list of figures (@pxref{\addtocontents}).
+
+Lines in the table of contents, the list of figures, and the list of
+tables, have four parts. First is an indent. Next is a box into which
+sectioning numbers are placed, and then the third box holds the title
+text, such as @samp{First section}. Finally there is a box up against
+the right margin, inside of which @LaTeX{} puts the page number box.
+For the indent and the width of the number box,
+@pxref{\@@dottedtocline}. The right margin box has width
+@code{\@@tocrmarg} and the page number is flush right in that space,
+inside a box of width @code{\@@pnumwidth}. By default
+@code{\@@tocrmarg} is @code{2.55em} and @code{\@@pnumwidth} is
+@code{1.55em}. Change these as with
+@code{\renewcommand@{\@@tocrmarg@}@{3.5em@}}.
-@PkgIndex{babel}
-@PkgIndex{polyglossia}
-To change the header for the table of contents page do something like
-the first line here.
+@PkgIndex{tocloft}
+@PkgIndex{tocbibbind}
+CTAN has many packages for the table of contents and lists of figures
+and tables (@pxref{CTAN}). The package @file{tocloft} is convenient for
+adjusting some aspects of the default such as spacing. And,
+@file{tocbibbind} will automatically add the bibliography, index,
+etc. to the table of contents.
+
+To change the header for the table of contents page, do something like
+these commands before you call @code{\tableofcontents}, etc.
@example
-\renewcommand@{\contentsname@}@{Table of contents@}
+\renewcommand@{\contentsname@}@{Table of Contents@}
\renewcommand@{\listfigurename@}@{Plots@}
-\renewcommand@{\listtablename@}@{Tables@}
+\renewcommand@{\listtablename@}@{Specifications@}
@end example
@noindent
-Similarly, the other two lines will do the other two.
+@PkgIndex{babel}
+@PkgIndex{polyglossia}
Internationalization packages such as @file{babel} or @file{polyglossia}
-will change the headers depending on the chosen base language.
-
-@PkgIndex{tocloft}
-@PkgIndex{tocbibbind}
-CTAN has many packages for the table of contents and lists of figures
-and tables. One convenient one for adjusting some aspects of the
-default, such as spacing, is @file{tocloft}. And, @file{tocbibbind}
-will automatically add the bibliography, index, etc. to the table of
-contents.
+will change these headers depending on the chosen base language.
@menu
+* \@@dottedtocline:: Format entry line in table of contents, etc.
* \addcontentsline:: Add an entry to table of contents, etc.
* \addtocontents:: Add text directly to table of contents file, etc.
+* \contentsline:: Set line in table of contents, etc.
* \nofiles:: Prevent writing to auxiliary files.
+* \numberline:: Put its number argument flush left in a box.
@end menu
+@node \@@dottedtocline
+@subsection @code{\@@dottedtocline}
+
+@findex \@@dottedtocline
+@cindex table of contents entry, create dotted line
+
+Synopsis:
+
+@example
+\@@dottedtocline@{@var{section-level-num}@}@{@var{indent}@}@{@var{numwidth}@}@{@var{text}@}@{@var{pagenumber}@}
+@end example
+
+Used internally by @LaTeX{} to format an entry line in the table of
+contents, list of figures, or list of tables. Authors do not directly
+enter @code{\@@dottedtocline} commands.
+
+This command is typically used by @code{\l@@section}, @code{\l@@subsection},
+etc., to format the content lines. For example, the @file{article.cls}
+file contains these definitions:
+
+@example
+\newcommand*\l@@section@{\@@dottedtocline@{1@}@{1.5em@}@{2.3em@}@}
+\newcommand*\l@@subsection@{\@@dottedtocline@{2@}@{3.8em@}@{3.2em@}@}
+\newcommand*\l@@subsubsection@{\@@dottedtocline@{3@}@{7.0em@}@{4.1em@}@}
+@end example
+
+@noindent
+In this example, @code{\@@dottedcline} appears to have been given only
+three arguments. But tracing the internal code shows that it picks up
+the final @var{text} and @var{pagenumber} arguments in the synopsis
+from a call to @code{\contentsline}.
+
+@cindex leaders, dots in table of contents
+Between the box for the title text of a section and the right margin
+box, these @code{\@@dottedtocline} commands insert @dfn{leaders}, that
+is, evenly-spaced dots. The dot-to-dot space is given by the command
+@code{\@@dotsep}. By default it is 4.5 (it is in math units, which
+are @code{1/18}@tie{}em. Change it using @code{\renewcommand}, as
+in @code{\renewcommand@{\@@dotsep@}@{3.5@}}.
+
+In the default book class, @LaTeX{} does not use dotted leaders for
+the Part and Chapter table entries, and in the default article class
+it does not use dotted leaders for Section entries.
+
+
@node \addcontentsline
@subsection @code{\addcontentsline}
@@ -17143,9 +19119,7 @@ Synopsis:
@end example
@findex \contentsline
-Add an entry to the file specified by @var{ext}. Usually @var{ext} is
-one of @code{toc} for the table of contents, @code{lof} for the list of
-figures, or @code{lot} for the list of tables.
+Add an entry to the auxiliary file with extension @var{ext}.
The following will result in an @samp{Appendices} line in the table of
contents.
@@ -17163,16 +19137,16 @@ The @code{\addcontentsline} command writes information to the file
@file{@var{root-name}.@var{ext}}. It writes that information as the
text of the command
@code{\contentsline@{@var{unit}@}@{@var{text}@}@{@var{num}@}}, where
-@code{@var{num}} is the current value of counter @code{@var{unit}}. The
-most common case is the table of contents and there @var{num} is the
-page number of the first page of @var{unit}.
+@code{@var{num}} is the current value of counter @code{@var{unit}}
+(@pxref{\contentsline}). The most common case is the table of contents
+and there @var{num} is the page number of the first page of @var{unit}.
This command is invoked by the sectioning commands @code{\chapter},
etc., and also by @code{\caption} inside a float environment. But it is
-also used by authors. For example, in a book to have the preface
-unnumbered, you may use the starred @code{\chapter*}. But that does not
-put in table of contents information, so you can enter it manually, as
-here.
+also used by authors. For example, an author writing a book whose style
+is to have an unnumbered preface may use the starred @code{\chapter*}.
+But that command leaves out table of contents information, which can be
+entered manually, as here.
@example
\chapter*@{Preface@}
@@ -17181,10 +19155,8 @@ here.
@noindent
In the @file{.toc} file @LaTeX{} will put the line @code{\contentsline
-@{chapter@}@{\numberline @{@}Preface@}@{3@}}; note the page number
-@samp{3}.
-
-@c xx how hardwired are these values? other unit names?
+@{chapter@}@{\numberline @{@}Preface@}@{3@}}; note that the page number
+@samp{3} is automatically generated by the system, not entered manually.
All of the arguments for @code{\addcontentsline} are required.
@@ -17245,7 +19217,7 @@ Synopsis:
Add @var{text}, which may be text or formatting commands, directly to
the auxiliary file with extension @var{ext}. This is most commonly used
-for the table of contents so that is the discussion here, but this also
+for the table of contents so that is the discussion here, but it also
applies to the list of figures and list of tables.
This will put some vertical space in the table of contents after the
@@ -17256,6 +19228,30 @@ This will put some vertical space in the table of contents after the
\addtocontents@{toc@}@{\protect\vspace*@{3ex@}@}
@end example
+@noindent
+This puts the word @samp{Page}, in boldface, above the column of page
+numbers and after the header.
+
+@example
+\tableofcontents
+\addtocontents@{toc@}@{~\hfill\textbf@{Page@}\par@}
+\chapter@{...@}
+@end example
+
+@noindent
+This adds a line announcing work by a new author.
+
+@example
+\addtocontents@{toc@}@{%
+ \protect\vspace@{2ex@}
+ \textbf@{Chapters by N. Other Author@}\par@}
+@end example
+
+The difference between @code{\addtocontents} and @code{\addcontentsline}
+is that the latter is strictly for lines, such as with a line giving the
+page number for the start of a new subset of the chapters. As the above
+examples show, @code{\addtocontents} is for material such as spacing.
+
The @code{\addtocontents} command has two arguments. Both are
required.
@@ -17283,6 +19279,67 @@ table of contents can come out in the wrong order. The solution is to
move @code{\addtocontents} into the file being included.
+@node \contentsline
+@subsection @code{\contentsline}
+
+@cindex table of contents
+@findex \contentsline
+@findex \tableofcontents
+@findex .toc @r{file}
+@findex \listoffigures
+@findex \listoftables
+@findex .lof @r{file}
+@findex .lot @r{file}
+@findex \l@@chapter
+@findex \l@@section
+@findex \l@@subsection
+
+Synopsis:
+
+@example
+\contentsline@{@var{unit}@}@{@var{text}@}@{@var{pagenumber}@}
+@end example
+
+Used internally by @LaTeX{} to typeset an entry of the table of
+contents, list of figures, or list of tables (@pxref{Table of contents
+etc.}). Authors do not directly enter @code{\contentsline} commands.
+
+Usually adding material to these lists is done automatically by the
+commands @code{\chapter}, @code{\section}, etc. for the table of
+contents, or by the @code{\caption} command inside of a @code{\figure}
+or @code{\table} environment (@pxref{figure} and @pxref{table}). Thus,
+where the base file is @file{thesis.tex}, and contains the declaration
+@code{\tableofcontents}, the command @code{\chapter@{Chapter One@}}
+produces something like this in the file @file{thesis.toc}.
+
+@example
+\contentsline @{chapter@}@{\numberline @{1@}Chapter One@}@{3@}
+@end example
+
+If the file contains the declaration @code{\listoffigures} then a figure
+environment involving @code{\caption@{Test@}} will produce
+something like this in @file{thesis.lof}.
+
+@example
+\contentsline @{figure@}@{\numberline @{1.1@}@{\ignorespaces Test@}@}@{6@}
+@end example
+
+To manually add material, use
+@code{\addcontentsline@{@var{filetype}@}@{@var{unit}@}@{@var{text}@}},
+where @var{filetype} is @code{toc}, @code{lof}, or @code{lot}
+(@pxref{\addcontentsline}).
+
+For manipulating how the @code{\contentline} material is typeset, see
+the @file{tocloft} package.
+
+Note that the @code{hyperref} package changes the definition of
+@code{\contentsline} (and @code{\addcontentsline}) to add more
+arguments, to make hyperlinks. This is the source of the error
+@code{Argument of \contentsline has an extra @}}. Fix this error by
+deleting the @file{.toc} or @file{.lof} or @file{.lot} file, and running
+@LaTeX{} again.
+
+
@node \nofiles
@subsection @code{\nofiles}
@@ -17317,6 +19374,44 @@ a @file{.toc} then the table of contents page will continue to show
the old information.
+@node \numberline
+@subsection @code{\numberline}
+
+@findex \numberline
+
+Synopsis:
+
+@example
+\numberline@{@var{number}@}
+@end example
+
+Typeset its argument flush left in a box. This is used in a
+@code{\contentsline} command to typeset the section number
+(@pxref{\contentsline}).
+
+For example, this line in a @file{.toc} file causes the @code{1} to be
+typeset flush left.
+
+@example
+\contentsline @{subsection@}@{\numberline @{1.1@}Motivation@}@{2@}
+@end example
+
+By default, @LaTeX{} typesets the section numbers in a box of length
+@code{\@@tempdima}. That length is set by the commands
+@code{\l@@section}, @code{\l@@subsection}, etc. Put section numbers
+inside a natural-width box with
+@code{\renewcommand@{\numberline@}[1]@{#1~@}}.
+
+This command is fragile, so you may need to precede it with
+@code{\protect} (@pxref{\protect}). An example is the use of
+@code{\protect} in the command
+@code{\addcontentsline@{toc@}@{section@}@{\protect\numberline@{@}Summary@}}
+to get the @code{\numberline} into this command in the @file{.toc} file:
+@code{\contentsline @{section@}@{\numberline @{@}Summary@}@{6@}} (the
+page number @samp{6} is automatically added by @LaTeX{};
+@pxref{\addcontentsline}).
+
+
@node Indexes
@section Indexes
@@ -17358,12 +19453,15 @@ information back into your document and typeset it with the
@PkgIndex{showidx}
@PkgIndex{multind}
-There are many packages that apply to indexing commands. The
-@code{showidx} package causes each index entries to be shown in the
-margin on the page where the entry appears. This can help in preparing
-the index. The @code{multind} package supports multiple indexes. See
-also the @TeX{} FAQ entry on this topic,
-@url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind}.
+@cindex index, multiple
+@cindex multiple indexes
+There are many packages in the area of indexing. The @code{showidx}
+package causes each index entries to be shown in the margin on the
+page where the entry appears. This can help in preparing the index.
+The @code{multind} package, among others, supports multiple indexes.
+See also the @TeX{} FAQ entry on this topic,
+@url{https://www.texfaq.org/FAQ-multind}, and the CTAN topic,
+@url{https://ctan.org/topic/index-multi}.
@menu
* \index:: Declare an index entry.
@@ -17439,8 +19537,8 @@ the output is the item @samp{Jones} with no comma or page number,
followed by two subitems, like @samp{program, 50} and @samp{results,
51}.
-@cindex `see' and `see also' index entries
-@cindex index entries, `see' and `see also'
+@cindex see and see also index entries
+@cindex index entries, `see' and `see also'
@findex \seename
@findex \alsoname
@PkgIndex{babel} @PkgIndex{polyglossia}
@@ -17603,8 +19701,8 @@ Postamble of the output file. Default: @code{"\n\n\\end@{theindex@}\n"}.
Traditionally index items are broken into groups, typically a group for
entries starting with @samp{a}, etc. This specifier gives what is
inserted when a new group begins. Default: @code{"\n\n \\indexspace\n"}
-(@code{\indexspace} is a rubber length with default value @code{10pt
-plus5pt minus3pt}).
+(@code{\indexspace} is a command inserting a rubber length, by default
+@code{10pt plus5pt minus3pt}).
@anchor{makeindex letheadflag}
@item lethead_flag
@@ -17715,14 +19813,18 @@ roman @code{R}, and uppercase alphabetic @code{A}. Default:
@end ftable
-@findex xindy
-@cindex @command{xindy} program
+@findex xindy @r{program}
There are a number of other programs that do the job
-@command{makeindex} does. One is @command{xindy}, which does
-internationalization and can process indexes for documents marked up
-using @LaTeX{} and a number of other languages. It is highly
-configurable, both in markup terms and in terms of the collating order
-of the text, as described in its documentation.
+@command{makeindex} does. One is @command{xindy}
+(https://ctan.org/pkg/xindy), which does internationalization and can
+process indexes for documents marked up using @LaTeX{} and a number of
+other languages. It is written in Lisp, highly configurable, both in
+markup terms and in terms of the collating order of the text, as
+described in its documentation.
+
+@findex xindex @r{program}
+A more recent indexing program supporting Unicode is @code{xindex},
+written in Lua (@url{https://ctan.org/pkg/xindex}).
@node \printindex
@@ -17743,7 +19845,7 @@ Place the index into the output.
To get an index you must first include
@code{\usepackage@{makeidx@}\makeindex} in the document preamble and
compile the document, then run the system command @command{makeindex},
-and then compile the document again. @xref{Indexes} for further
+and then compile the document again. @xref{Indexes}, for further
discussion and an example of the use of @code{\printindex}.
@@ -17849,7 +19951,7 @@ Declare a new entry for a glossary. The @var{label} must be unique for
the document. The settings associated with the label are pairs:
@code{@var{key}=@var{value}}.
-This puts the blackboard bold symbol for the real numbers @BES{211D,} in the
+This puts the blackboard bold symbol for the real numbers @BES{211D}, in the
glossary.
@example
@@ -18315,24 +20417,6 @@ For this you must put @code{\usepackage@{graphicx@}} in the preamble
(@pxref{Graphics}).
-@c I think this is not a user-level command; it is used to keep from breaking
-@c the page between the closing and the signature
-@c @node \stopbreaks and \startbreaks
-@c @section @code{\stopbreaks} and @code{\startbreaks}
-
-@c @findex \startbreak
-@c @findex \stopbreaks
-
-@c @example
-@c @code{\stopbreaks}
-@c text
-@c @code{\startbreaks}
-@c @end example
-
-@c The @code{\stopbreaks} inhibits page breaking. The @code{\startbreaks} resumes
-@c normal page breaking.
-@c
-@c
@node \telephone
@section @code{\telephone}
@@ -18350,18 +20434,159 @@ pagestyle is selected. If so, it appears on the lower right of the
page.
-@node Terminal input/output
-@chapter Terminal input/output
+@node Input/output
+@chapter Input/output
@cindex input/output, to terminal
@cindex terminal input/output
+@cindex input/output
+
+@LaTeX{} uses the ability to write to a file and later read it back in
+to build document components such as a table of contents or index. You
+can also read a file that other programs written, or write a file for
+others to read. You can communicate with users through the terminal.
+And, you can issue instructions for the operating system.
@menu
+* \openin & \openout:: Open a file.
+* \read:: Read text from a file.
* \typein:: Read text from the terminal.
* \typeout:: Write text to the terminal.
+* \write:: Write text to a file or terminal.
@end menu
+@node \openin & \openout
+@section @code{\openin} & @code{\openout}
+
+@findex \openin
+@findex \openout
+@findex \closein
+@findex \closeout
+@cindex file, opening
+@cindex file, closing
+@cindex open a file
+
+Synopsis:
+
+@example
+\openin @var{number}=@var{filename}
+@end example
+
+or:
+
+@example
+\openout @var{number}=@var{filename}
+@end example
+
+Open a file for reading material, or for writing it. The @var{number}
+must be between 0 and 15, as in @code{\openin3} (in Lua@LaTeX{}
+@var{number} can be between 0 and 255).
+
+Here @TeX{} opens the file @file{presidents.tex} for reading.
+
+@example
+\newread\presidentsfile
+\openin\presidentsfile=presidents
+\typeout@{presidentsfile is \the\presidentsfile@}
+\read\presidentsfile to\presidentline
+\typeout@{\presidentline@}
+@end example
+
+@noindent
+The @code{\newread} command allocates input stream numbers from 0
+to@tie{}15 (there is also a @code{\newwrite}). The
+@code{\presidentsfile} is more memorable but under the hood it is still
+a number; the first @code{\typeout} gives something like
+@samp{presidentsfile is 1}. In addition, @code{\newread} keeps track of
+the allocation so that if you use too many then you get an error like
+@samp{! No room for a new \read}. The second @code{\typeout} gives the
+first line of the file, something like @samp{1 Washington, George}.
+
+Ordinarily @TeX{} will not try to open the file until the next page
+shipout. To change this, use
+@code{\immediate\openin @var{number}=@var{filename}} or
+@code{\immediate\openout @var{number}=@var{filename}}.
+
+Close files with @code{\closein @var{number}} and
+@code{\closeout @var{number}}.
+
+How @LaTeX{} handles filenames varies among distributions, and even can
+vary among versions of a distribution. If the file does not have an
+extension then @TeX{} will add a @file{.tex}. This creates
+@file{presidents.tex}, writes one line to it, and closes it.
+
+@example
+\newwrite\presidentsfile
+\openout\presidentsfile=presidents
+\write\presidentsfile@{1 Washington, George@}
+\closeout\presidentsfile
+@end example
+
+@noindent
+But filenames with a period can cause trouble: if @TeX{} finds a
+@var{filename} of @file{presidents.dat} it could look first for
+@file{presidents.dat.tex} and later for @file{presidents.dat}, or it
+could do the opposite. Your distribution's documentation should say
+more, and if you find something that works for you then you are good,
+but to ensure complete portability the best thing is to use file names
+containing only the twenty six ASCII letters (not case-sensitive) and
+the ten digits, along with underscore and dash, and in particular with
+no dot or space.
+
+For @code{\openin}, if @TeX{} cannot find the file then it does not give
+an error. It just considers that the stream is not open (test for this
+with @code{\ifeof}; one recourse is the command
+@code{\InputIfFileExists}, @pxref{Class and package commands}). If you
+try to use the same number twice, @LaTeX{} won't give you an error. If
+you try to use a bad number then you get an error message like @samp{!
+Bad number (16). <to be read again> = l.30 \openin16=test.jh}.
+
+
+@node \read
+@section @code{\read}
+
+@findex \read
+@cindex file, reading
+@cindex read a file
+
+Synopsis:
+
+@example
+\read @var{number} to@var{macro}
+@end example
+
+Make the command @var{macro} contain the next line of input from text
+stream @var{number}, as in @code{\read5 to\data}.
+
+This opens the file @file{email.tex} for reading, puts the contents of
+the first line into the command @code{\email}, and then closes the file.
+
+@example
+\newread\recipientfile
+\openin\recipientfile=email
+\read\recipientfile to\email
+\typeout@{Email address: \email@}
+\closein\recipientfile
+@end example
+
+If @var{number} is outside the range from 0 to@tie{}15 or if no file
+of that number is open, or if the file has ended, then @code{\read}
+will take input from the terminal (or exit if interaction is not
+allowed, e.g., @code{\nonstopmode}; @pxref{interaction modes}).
+(However, the natural way in @LaTeX{} to take input from the terminal
+is @code{\typein} (@pxref{\typein}.)
+
+To read an entire file as additional @LaTeX{} source, use
+@code{\input} (@pxref{\input}) or @code{\include} (@pxref{\include &
+\includeonly}).
+
+@PkgIndex{datatool}
+@cindex mail merges
+A common reason to want to read from a data file is to do mail merges.
+CTAN has a number of packages for that; one is @file{datatool}.
+
+
@node \typein
@section @code{\typein}
@@ -18401,9 +20626,9 @@ the input you typed to be processed as if it had been included in the
input file in place of the @code{\typein} command.
In the second command version the optional argument @code{@var{cmd}}
-argument must be a command name --- it must begin with a backslash, \.
-This command name is then defined or redefined to be the input that you
-typed. For example, this
+argument must be a command name, that is, it must begin with a
+backslash, \. This command name is then defined or redefined to be
+the input that you typed. For example, this
@example
\typein[\student]@{Enter student name:@}
@@ -18468,10 +20693,401 @@ This command can be useful for simple debugging, as here:
produces on the command line @samp{The length is 5.0pt}.
-@node Command line
-@chapter Command line
+@node \write
+@section @code{\write}
+
+@findex \write
+
+Synopsis:
+
+@example
+\write @var{number}@{@var{string}@}
+@end example
+
+Write @var{string} to the log file, to the terminal, or to a file
+opened by @code{\openout}. For instance, @code{\write6} writes to text
+stream number@tie{}6.
-@cindex command line
+If the following appears in @file{@var{basefile}.tex} then it opens
+@file{@var{basefile}.jh}, writes @samp{Hello World!} and a newline to
+it, and closes that file.
+
+@example
+\newwrite\myfile
+\immediate\openout\myfile=\jobname.jh % \jobname is root file basename
+...
+\immediate\write\myfile@{Hello world!@}
+...
+\immediate\closeout\myfile
+@end example
+
+@findex \newwrite
+@noindent
+The @code{\newwrite} allocates a stream number, giving it a symbolic
+name to make life easier, so that @code{stream
+\newwrite\myfile\the\myfile} produces something like @samp{stream 3}.
+Then @code{\openout} associates the stream number with the given file
+name. @TeX{} ultimately executed @code{\write3} which puts the string
+in the file.
+
+@cindex log file, writing to
+@cindex terminal, writing to
+@cindex @math{-1}, write stream number
+Typically @var{number} is between 0 and@tie{}15, because typically
+@LaTeX{} authors follow the prior example and the number is allocated
+by the system. If @var{number} is outside the range from 0 to 15 or
+if it is not associated with an open file then @LaTeX{} writes
+@var{string} to the log file. If @var{number} is positive then in
+addition @LaTeX{} writes @var{string} to the terminal.
+
+Thus, @code{test \write-1@{Hello World!@}} puts @samp{Hello World!}
+followed by a newline in the log file. (This is what the @code{\wlog}
+command does; @pxref{\wlog}). And @code{\write100@{Hello World!@}}
+puts the same in the log file but also puts @samp{Hello World!}
+followed by a newline in the terminal output. (But 16, 17, and 18 are
+special as @var{number}; see below.)
+
+@cindex Lua@TeX{}, 256 output streams in
+In Lua@TeX{}, instead of 16 output streams there are 256
+(@pxref{@TeX{} engines}).
+
+@findex \@@auxout
+@findex \@@mainaux
+Use @code{\write\@@auxout@{@var{string}@}} to write to the current
+@file{.aux} file, which is associated with either the root file or
+with the current include file; and use
+@code{\write\@@mainaux@{@var{string}@}} to write to the main
+@file{.aux}. These symbolic names are defined by @LaTeX{}.
+
+@c credit: David Carlisle https://tex.stackexchange.com/a/115933/121234
+By default @LaTeX{} does not write @var{string} to the file right
+away. This is because, for example, you may need @code{\write} to
+save the current page number, but when @TeX{} comes across a
+@code{\write} it typically does not know what the page number is,
+since it has not yet done the page breaking. So, you use @code{\write}
+in one of three contexts:
+
+@example
+\immediate\write\@@auxout@{@var{string}@} %1
+\write\@@auxout@{@var{string}@} %2
+\protected@@write\@@auxout@{@}@{@var{string}@} %3
+@end example
+
+@enumerate
+@item
+@cindex immediate @code{\write}
+@findex \immediate\write
+With the first, @LaTeX{} writes @var{string} to the file immediately.
+Any macros in @var{string} are fully expanded (just as in
+@code{\edef}) so to prevent expansion you must use @code{\noexpand},
+@code{toks}, etc., except that you should use @code{#} instead of
+@code{##}).
+
+@item
+@cindex delayed @code{\write}
+@cindex whatsit item
+@findex \shipout @r{and expansion}
+With the second, @var{string} is stored on the current list of things
+(as a @TeX{} ``whatsit'' item) and kept until the page is shipped out
+and likewise the macros are unexpanded until @code{\shipout}. At
+@code{\shipout}, @var{string} is fully expanded.
+
+@item
+@findex \protected@@write
+The third, @code{\protected@@write}, is like the second except that
+you can use @code{\protect} to avoid expansion. The extra first
+argument allows you to locally insert extra definitions to make more
+macros protected or to have some other special definition for the
+write.
+@end enumerate
+
+As a simple example of expansion with @code{\write}, @var{string} here
+contains a control sequence @code{\triplex} which we've defined to be
+the text @samp{XYZ}:
+
+@example
+\newwrite\jhfile
+\openout\jhfile=test.jh
+\newcommand@{\triplex@}@{XYZ@}
+\write\jhfile@{test \triplex test@}
+@end example
+
+@noindent
+This results in the file @file{test.jh} containing the text
+@samp{test XYZtest} followed by a newline.
+
+@cindex @code{\write} streams 16, 17, 18
+The cases where @var{number} is 16, 17, or 18 are special. Because of
+@code{\write}'s behavior when @var{number} is outside the range from 0
+to 15 described above, in Plain@tie{}@TeX{} @code{\write16} and
+@code{\write17} were sometimes used to write to the log file and the
+terminal; however, in @LaTeX{}, the natural way to do that is with
+@code{\typeout} (@pxref{\typeout}). The @code{\write18} command is
+even more special; modern @TeX{} systems use it for giving commands to
+the operating system (@pxref{\write18}).
+
+@cindex newline, in @code{\write}
+@cindex @code{^^J}, in @code{\write}
+Ordinarily @code{\write} outputs a single line. You can include a
+newline with @code{^^J}. Thus, this produces two lines in the log
+file:
+
+@example
+\wlog@{Parallel lines have a lot in common.^^JBut they never meet.@}
+@end example
+
+@PkgIndex{answers}
+A common case where authors need to write their own file is for
+answers to exercises, or another situation where you want to write
+out verbatim, without expanding the macros. CTAN has a number of
+packages for this; one is @file{answers}.
+
+@menu
+* \write and security:: Security.
+* \message:: Write text to the log file and terminal.
+* \wlog:: Write text to the log file.
+* \write18:: Run an operating system command.
+@end menu
+
+
+@node \write and security
+@subsection @code{\write} and security
+
+@cindex security and @code{\write}
+@cindex @code{\write} and security
+
+The ability to write files raises security issues. If you compiled a
+downloaded @LaTeX{} file and it overwrote your password file then you
+would be justifiably troubled.
+
+Thus, by default @TeX{} systems only allow you to open files for
+writing that are in the current directory or output directory, if
+specified (@pxref{output directory}), or in a subdirectory of
+those. So, this code
+
+@example
+\newwrite\jhfile
+\openout\jhfile=../test.jh
+@end example
+
+@noindent
+gives an error like:
+@example
+Not writing to ../test.jh (openout_any = p).
+! I can't write on file `../test.jh'
+@end example
+
+@cindex parent directories, cannot write to
+You can get just such an error when using commands such as
+@code{\include@{../filename@}} because @LaTeX{} will try to open
+@file{../filename.aux}. The simplest solution is to put the included
+files in the same directory as the root file, or in subdirectories.
+
+
+@node \message
+@subsection @code{\message}
+
+@findex \message
+
+Synopsis:
+
+@example
+\message@{@var{string}@}
+@end example
+
+Write @var{string} to the log file and the terminal.
+
+Typically, @LaTeX{} authors use @code{\typeout} (@pxref{\typeout}). It
+allows you to use @code{\protect} on any fragile commands in
+@var{string} (@pxref{\protect}). But @code{\typeout} always inserts a
+newline at the end of @var{string} while @code{\message} does not, so
+the latter can be useful.
+
+With this example document body.
+
+@example
+before\message@{One Two@}\message@{Three@}\message@{Four^^JI@}
+\message@{declare a thumb war.@}After
+@end example
+
+@noindent
+under some circumstances (see below) @LaTeX{} writes the following to
+both the terminal and the log file.
+
+@example
+One Two Three Four
+I declare a thumb war.
+@end example
+
+@noindent
+The @code{^^J} produces a newline. Also, in the output document,
+between @samp{before} and @samp{After} will be a single space (from
+the end of line following @samp{I@}}).
+
+While @code{\message} allows you more control over formatting, a
+gotcha is that @LaTeX{} may mess up that formatting because it inserts
+line breaks depending on what it has already written. Contrast this
+document body, where the @samp{Two} has moved, to the one given above.
+
+@example
+before\message@{One@}\message@{Two Three@}\message@{Four^^JI@}
+\message@{declare a thumb war.@}After
+@end example
+
+This can happen: when @LaTeX{} is outputting the messages to the
+terminal, now the message with @samp{One} is shorter and it fits at the
+end of the output terminal line, and so @LaTeX{} breaks the line between
+it and the @samp{Two Three}. That line break appears also in the log
+file. This line break insertion can depend on, for instance, the length
+of the full path names of included files. So producing finely-formatted
+lines in a way that is portable is hard, likely requiring
+starting your message at the beginning of a line.
+
+
+@node \wlog
+@subsection @code{\wlog}
+
+@findex \wlog
+
+Synopsis:
+
+@example
+\wlog@{@var{string}@}
+@end example
+
+Write @var{string} to the log file.
+
+@example
+\wlog@{Did you hear about the mathematician who hates negatives?@}
+\wlog@{He'll stop at nothing to avoid them.@}
+@end example
+
+Ordinarily @var{string} appears in a single separate line. Use
+@code{^^J} to insert a newline.
+
+@example
+\wlog@{Helvetica and Times Roman walk into a bar.@}
+\wlog@{The barman says,^^JWe don't serve your type.@}
+@end example
+
+
+@node \write18
+@subsection @code{\write18}
+
+@findex \write18
+@cindex external commands
+@cindex commands, run from @LaTeX{}
+@cindex system commands, run from @LaTeX{}
+@cindex shell access
+@c Derived from: Joseph Wright: https://tex.stackexchange.com/a/20446/121234
+
+Synopsis:
+
+@example
+\write18@{@var{shell_command}@}
+@end example
+
+Issue a command to the operating system shell. The operating system
+runs the command and @LaTeX{}'s execution is blocked until that
+finishes.
+
+@PkgIndex{Asymptote}
+This sequence (on Unix)
+
+@example
+\usepackage@{graphicx@} % in preamble
+ ...
+\newcommand@{\fignum@}@{1@}
+\immediate\write18@{cd pix && asy figure\fignum@}
+\includegraphics@{pix\figure\fignum.pdf@}
+@end example
+
+@noindent
+will run Asymptote (the @code{asy} program) on @file{pix/figure1.asy},
+so that the document can later read in the resulting graphic
+(@pxref{\includegraphics}). Like any @code{\write}, here @LaTeX{}
+expands macros in @var{shell_command} so that @code{\fignum} is
+replaced by @samp{1}.
+
+Another example is that you can automatically run Bib@TeX{} at the start
+of each @LaTeX{} run (@pxref{Using BibTeX}) by including
+@code{\immediate\write18@{bibtex8 \jobname@}} as the first line of the
+file. Note that @code{\jobname} expands to the basename of the root
+file unless the @code{--jobname} option is passed on the command line,
+in which case this is the option argument.
+
+You sometimes need to do a multi-step process to get the information
+that you want. This will insert into the input a list of all PDF files
+in the current directory (but see @file{texosquery} below):
+
+@example
+\immediate\write18@{ls *.pdf > tmp.dat@}
+\input@{tmp.dat@}
+@end example
+
+The standard behavior of any @code{\write} is to wait until a page is
+being shipped out before expanding the macros or writing to the stream
+(@pxref{\write}). But sometimes you want it done now. For this, use
+@code{\immediate\write18@{@var{shell_command}@}}.
+
+There are obvious security issues with allowing system commands inside
+a @LaTeX{} file. If you download a file off the net and it contains
+commands to delete all your files then you would be unhappy. The
+standard settings in modern distributions turn off full shell
+access. You can turn it on, if you are sure the shell commands are
+safe, by compiling with @code{latex --enable-write18 @var{filename}}
+(@pxref{Command line options}). (The @code{--shell-escape} option is
+a synonym, in @TeX{} Live.)
+
+@cindex restricted shell access
+In the place of full shell access, modern distributions by default use
+a restricted version that allows some commands to work, such as those
+that run Metafont to generate missing fonts, even if you do not use
+the @code{enable-write18} option. By default this list of allowed
+commands is short and features only commands that are under the
+control of the distribution maintainers (@pxref{Command line
+options}).
+
+@findex /bin/sh@r{, used by @code{\write18}}
+@findex sh@r{, used by @code{\write18}}
+@findex cmd.exe@r{, used by @code{\write18}}
+@findex SHELL@r{, environment variables}
+The @var{shell_command} text is always passed to @file{/bin/sh} on
+Unix-like operating systems, and the DOS command interpreter
+@file{cmd.exe} on Windows. Any different shell set by the user, and
+the @code{SHELL} environment variable, is ignored.
+
+@PkgIndex{texosquery}
+@cindex system information
+@cindex operating system information
+@cindex locale information, from system
+@cindex directory listings, from system
+If what you need is system information, such as the operating system
+name, locale information, or directory contents, take a look at the
+@file{texosquery} package, which provides a convenient and secure
+interface for this, unlike the above examples using the raw
+@code{\write18}: @url{https://ctan.org/pkg/texosquery}.
+
+@PkgIndex{shellesc}
+@findex \ShellEscape
+@findex \DelayedShellEscape
+@LaTeX{} provides a package @code{shellesc} on top of the primitive
+@code{\write18} command. Its primary purpose is to provide a command
+@code{\ShellEscape} which works identically on all @TeX{} engines;
+Lua@TeX{} intentionally did not retain @code{\write18} as a way to
+invoke a shell command, so some engine-specific code is needed. The
+@code{shellesc} package also provides a command
+@code{\DelayedShellEscape}, executed at @code{\output} time, for the
+same reason.
+
+
+@node Command line interface
+@chapter Command line interface
+
+@anchor{Command line}@c old name
+@cindex command line interface
+@cindex interface, command line
+@cindex CLI
Synopsis (from a terminal command line):
@@ -18479,9 +21095,10 @@ Synopsis (from a terminal command line):
pdflatex @var{options} @var{argument}
@end example
-Run @LaTeX{} on @var{argument}. In place of @command{pdflatex} you can
-also use @command{xelatex}, or @code{lualatex}, or @code{dviluatex}, or
-@code{latex}.
+Run @LaTeX{} on @var{argument}. In place of @command{pdflatex} you
+can also use (for PDF output) @command{xelatex} or @code{lualatex}, or
+(for DVI output) @code{latex} or @code{dvilualatex}, among others
+(@pxref{@TeX{} engines}).
For example, this will run @LaTeX{} on the file @file{thesis.tex},
creating the output @file{thesis.pdf}.
@@ -18492,19 +21109,20 @@ pdflatex thesis
@noindent
@findex .tex, @r{default extension}
-Note that @file{.tex} is the default file extension.
-
-pdf@TeX{} is a development of the original @TeX{} program, as are
-Xe@TeX{} and Lua@TeX{} (@pxref{@TeX{} engines}). They are completely
-backward compatible. But the original program had a custom output
-format, DVI, while the newer ones can output directly to PDF. This
-allows them to take advantage of the extra features in PDF such as
-hyperlinks, support for modern image formats such as JPG and PNG, and
-ubiquitous viewing programs. In short, if you run @command{pdflatex} or
-@command{xelatex} or @command{lualatex} then you will by default get PDF
-and have access to all its modern features. If you run @command{latex},
-or @code{dvilualatex}, then you will get DVI. The description here
-assumes pdf@LaTeX{}.
+Note that @file{.tex} is the default file name extension.
+
+pdf@TeX{} is an extension of the original @TeX{} program, as are
+Xe@TeX{} and Lua@TeX{} (@pxref{@TeX{} engines}). The first two are
+completely backward compatible and the latter, almost so. Perhaps the
+most fundamental new feature for all three is that the original @TeX{}
+output its own DVI format, while the newer ones can output directly to
+PDF. This allows them to take advantage of the extra features in PDF
+such as hyperlinks, support for modern image formats such as JPG and
+PNG, and ubiquitous viewing programs. In short, if you run
+@command{pdflatex} or @command{xelatex} or @command{lualatex} then you
+will by default get PDF and have access to all its modern features.
+If you run @command{latex}, or @code{dvilualatex}, then you will get
+DVI. The description here assumes pdf@LaTeX{}.
@xref{Command line options}, for a selection of the most useful
command line options. As to @var{argument}, the usual case is that it
@@ -18516,15 +21134,16 @@ input}).
If you gave no arguments or options then @command{pdflatex} prompts for
input from the terminal. You can escape from this by entering
-@code{<control>-D}.
+@kbd{CTRL-D}.
If @LaTeX{} finds an error in your document then by default it stops and
-asks you about it. @xref{Recovering from errors} for an outline of what
+asks you about it. @xref{Recovering from errors}, for an outline of what
to do.
@menu
-* Command line options:: Read text from the terminal.
-* Command line input:: Write text to the terminal.
+* Command line options:: Commonly used command line options.
+* Command line input:: Specify LaTeX code on the command line.
+* Jobname:: How @TeX{} sets the current job name.
* Recovering from errors:: When something goes wrong.
@end menu
@@ -18539,9 +21158,12 @@ authoring. For a full list, try running @samp{latex --help} from the
command line.
With many implementations you can specify command line options by
-prefixing them with @samp{-} or @samp{--}. This is the case for
-both @TeX{} Live (and Mac@TeX{}) and MiK@TeX{}. We will use both
-conventions interchangeably.
+prefixing them with @samp{-} or @samp{--}. This is the case for both
+@TeX{} Live (including Mac@TeX{}) and MiK@TeX{}. We will use both
+conventions interchangeably. If an option takes a value, it can be
+specified either as a separate argument (@samp{--foo val}), or as one
+argument with an @samp{=} sign (@samp{--foo=val}), but there can be no
+spaces around the @samp{=}. We will generally use the @samp{=} syntax.
@table @code
@findex --version @r{command-line option}
@@ -18554,18 +21176,23 @@ and exit.
@item -help
Give a brief usage message that is useful as a prompt and exit.
+@anchor{interaction modes}
@findex --interaction @r{command-line option}
@item -interaction=@var{mode}
+@cindex batchmode
+@cindex scrollmode
+@cindex errorstopmode
+@cindex nonstopmode
@TeX{} compiles a document in one of four interaction modes:
@code{batchmode}, @code{nonstopmode}, @code{scrollmode},
-@code{errorstopmode}. In @dfn{errorstop mode} (the default), @TeX{}
-stops at each error and asks for user intervention. In @dfn{batch
-mode} it prints nothing on the terminal, errors are scrolled as if the
-user hit @code{<return>} at every error, and missing files cause the
-job to abort. In @dfn{nonstop mode}, diagnostic message appear on the
-terminal but as in batch mode there is no user interaction. In
-@dfn{scroll mode}, @TeX{} only stops for missing files or keyboard
-input.
+@code{errorstopmode}. In @dfn{errorstopmode} (the default), @TeX{}
+stops at each error and asks for user intervention. In @dfn{batchmode}
+it prints nothing on the terminal, errors are scrolled as if the user
+hit @kbd{RETURN} at every error, and missing files cause the job to
+abort. In @dfn{nonstopmode}, diagnostic message appear on the terminal
+but as in batch mode there is no user interaction. In
+@dfn{scrollmode}, @TeX{} stops for missing files or keyboard
+input, but nothing else.
For instance, starting @LaTeX{} with this command line
@@ -18576,52 +21203,55 @@ pdflatex -interaction=batchmode @var{filename}
@noindent
eliminates most terminal output.
+@cindex jobname
+@cindex filename for current job
@findex --jobname @r{command-line option}
@item -jobname=@var{string}
-Set the value of @TeX{}'s @code{jobname} to the string. The log file
+Set the value of @TeX{}'s @dfn{jobname} to the string. The log file
and output file will then be named @file{@var{string}.log} and
-@file{@var{string}.pdf}.
-
-When you run @code{@command{pdflatex} @var{options} @var{argument}}, if
-@var{argument} does not start with a backslash then @TeX{} considers it
-the name of a file to input. Otherwise it waits for the first
-@code{\input} instruction and the name of the input file will be the job
-name. This is used to name the log file the output file. The
-@code{jobname} option overrides that process and directly specifies the
-name. @xref{Command line input} for an example of its use.
+@file{@var{string}.pdf}. @pxref{Jobname}.
+@anchor{output directory}
+@cindex output directory for all external files
@findex --output-directory @r{command-line option}
@item -output-directory=@var{directory}
Write files in the directory @var{directory}. It must already exist.
-
-@findex --shell-escape @r{command-line option}
-@findex --no-shell-escape @r{command-line option}
+This applies to all external files created by @TeX{} or @LaTeX{}, such
+as the @file{.log} file for the run, the @file{.aux}, @file{.toc},
+etc., files created by @LaTeX{}, as well as the main @file{.pdf} or
+@file{.dvi} output file itself.
+
+When specified, the output directory @var{directory} is also
+automatically checked first for any file that it is input, so that the
+external files can be read back in, if desired. The true current
+directory (in which @LaTeX{} was run) remains unchanged, and is also
+checked for input files.
+
+@cindex shell escape
+@cindex @code{\write18}, enabling
@findex --enable-write18 @r{command-line option}
@findex --disable-write18 @r{command-line option}
-@item --shell-escape
-@itemx --no-shell-escape
-@itemx --enable-write18
+@findex --shell-escape @r{command-line option}
+@findex --no-shell-escape @r{command-line option}
+@item --enable-write18
@itemx --disable-write18
-Enable or disable @code{\write18@{@var{shell command}@}}. The first two
-options are for with @TeX{} Live or Mac@TeX{} while the second two are
-for MiK@TeX{}.
-
-@PkgIndex{sagetex}
-Sometimes you want to run external system commands from inside a
-@LaTeX{} file. For instance the package @file{sagetex} allows you to
-have the mathematics software system @i{Sage} do calculations or draw
-graphs and then incorporate that output in your document. For this
-@TeX{} provides the @code{\write18} command.
-
-But with this functionality enabled, security issues could happen if you
-compiled a @LaTeX{} file from the Internet. By default @code{\write18}
-is disabled. (More precisely, by default @TeX{} Live, Mac@TeX{}, and
-MiK@TeX{} only allow the execution of a limited number of @TeX{}-related
-programs, which they distribute.)
-
-If you invoke @LaTeX{} with the option @code{no-shell-escape}, and in
-your document you call @code{\write18@{ls -l@}}, then you do not get an
-error but the log file says @samp{runsystem(ls -l)...disabled}.
+@itemx --shell-escape
+@itemx --no-shell-escape
+Enable or disable @code{\write18@{@var{shell_command}@}}
+(@pxref{\write18}). The first two options are supported by both
+@TeX{} Live and MiK@TeX{}, while the second two are synonyms supported
+by @TeX{} Live.
+
+Enabling this functionality has major security implications, since it
+allows a @LaTeX{} file to run any command whatsoever. Thus, by
+default, unrestricted @code{\write18} is not allowed. (The default
+for @TeX{} Live, Mac@TeX{}, and MiK@TeX{} is to allow the execution of
+a limited number of @TeX{}-related programs, which they distribute.)
+
+For example, if you invoke @LaTeX{} with the option
+@code{no-shell-escape}, and in your document you call
+@code{\write18@{ls -l@}}, then you do not get an error but the log
+file says @samp{runsystem(ls -l)...disabled}.
@findex --halt-on-error @r{command-line option}
@item -halt-on-error
@@ -18641,15 +21271,19 @@ error messages. These are only available with @TeX{} Live or Mac@TeX{}.
@cindex input, on command line
-As part of the command line invocation @code{pdflatex @var{options}
-@var{argument}} you can specify arbitrary @LaTeX{} input by starting
-@var{argument} with a backslash. This allows you to do some special
-effects.
+As part of the command line invocation
-@PkgIndex{hyperref}
-For example, this file (which uses the @file{hyperref} package for
-hyperlinks) can produce two kinds of output, one for paper and one for a
-PDF.
+@example
+@var{latex-engine} @var{options} @var{argument}
+@end example
+
+@noindent you can specify arbitrary @LaTeX{} input by starting
+@var{argument} with a backslash. (All the engines support this.) This
+allows you to do some special effects.
+
+@PkgIndex{hyperref} For example, this file (which uses the
+@file{hyperref} package for hyperlinks) can produce two kinds of
+output, one to be read on physical paper and one to be read online.
@example
\ifdefined\paperversion % in preamble
@@ -18666,10 +21300,17 @@ PDF.
@noindent
Compiling this document @file{book.tex} with the command line
@code{pdflatex book} will give the @samp{CTAN} link in blue. But
-compiling it with @code{pdflatex "\def\paperversion@{@}\input book.tex"}
-has the link in black. (Note the use of double quotes to prevent
-interpretation of the symbols by the command line shell; your system may
-do this differently.)
+compiling it with
+
+@example
+pdflatex "\def\paperversion@{@}\input book.tex"
+@end example
+
+@noindent has the link in black. We use double quotes to prevent
+interpretation of the symbols by the command line shell. (This
+usually works on both Unix and Windows systems, but there are many
+peculiarities to shell quoting, so read your system documentation if
+need be.)
In a similar way, from the single file @file{main.tex} you can compile
two different versions.
@@ -18682,21 +21323,110 @@ pdflatex -jobname=teachers "\def\teachers@{@}\input@{main@}"
@noindent
The @code{jobname} option is there because otherwise both files would be
-called @file{main.pdf} and the second would overwrite the first.
+called @file{main.pdf} and the second would overwrite the first. (See
+the next section.)
-A final example. This loads the package @file{graphicx} with the option
-@code{draft}
+In this example, we pass the @code{draft} option to the
+@file{graphicx} package:
+
+@example
+pdflatex "\PassOptionsToPackage@{draft@}@{graphicx@}\input@{aa.tex@}"
+@end example
+
+@noindent
+so the graphic files are read for their bounding box size information
+but replaced in the PDF by a box with same size and that contains only
+the file name, which speeds up compilation time and saves printer ink.
+
+
+@node Jobname
+@section Jobname
+
+@findex @code{\jobname}
+@cindex jobname
+@cindex document root name
+@cindex name of document root
+
+Running @LaTeX{} creates a number of files, including the main PDF (or
+DVI) output but also including others. These files are named with the
+so-called @dfn{jobname}. The most common case is also the simplest,
+where for instance the command @code{pdflatex thesis} creates
+@code{thesis.pdf} and also @code{thesis.log} and @code{thesis.aux}.
+Here the job name is @code{thesis}.
+
+In general, @LaTeX{} is invoked as @code{@var{latex-engine}
+@var{options} @var{argument}}, where @var{latex-engine} is
+@command{pdflatex}, @command{lualatex}, etc.@: (@pxref{@TeX{} engines}).
+If @var{argument} does not start with a backslash, as is the case
+above with @code{thesis}, then @TeX{} considers it to be the name of
+the file to input as the main document. The name of that root file,
+without the @file{.tex} extension, is the jobname. If @var{argument}
+does start with a backslash, or if @TeX{} is in interactive mode, then
+it waits for the first @code{\input} command, and the jobname is the
+argument to @code{\input}.
+
+There are two more possibilities for the jobname. It can be directly
+specified with the @code{-jobname} option, as in @code{pdflatex
+-jobname=myname} (@pxref{Command line input} for a real example).
+
+@findex texput@r{, jobname default}
+@cindex fallback jobname
+The final possibility is @file{texput}, which is the final fallback
+default if no other name is available to @TeX{}. For example, if no
+@code{-jobname} option was specified, and the compilation stops before
+there is any output, then the log file will be named
+@file{texput.log}.
+
+@findex \documentclass@r{, and @code{texput} jobname}
+@findex \RequirePackage@r{, and @code{texput} jobname}
+A special case of this is that in @LaTeX{} versions of (approximately)
+2020 or later, the jobname is also @file{texput} if the first
+@code{\input} occurs as a result of being called by either
+@code{\documentclass} or @code{\RequirePackage}. So this will produce
+a file named @file{texput.pdf}:
+
+@example
+pdflatex "\documentclass@{minimal@}\begin@{document@}Hello!\end@{document@}"
+@end example
+
+However, this special case only applies to those two commands. Thus, with
@c credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234
@example
-pdflatex -jobname=aa "\RequirePackage[draft]@{graphicx@}\input@{aa.tex@}"
+pdflatex "\documentclass@{article@}\usepackage@{lipsum@}\input@{thesis@}"
@end example
@noindent
-so the graphic files are read for their size information but not
-incorporated into the PDF. (The @code{jobname} option is there because
-otherwise the output file would be @file{graphicx.pdf}, as
-@code{\RequirePackage} does an @code{\input} of its own.)
+the output file is @file{lipsum.pdf}, as @code{\usepackage} calls
+@code{\input}.
+
+@findex \jobname
+Within the document, the macro @code{\jobname} expands to the jobname.
+(When you run @LaTeX{} on a file whose name contains spaces, the string
+returned by @code{\jobname} contains matching start and end quotes.)
+In the expansion of that macro, all characters are of
+catcode@tie{}12 (other) except that spaces are category@tie{}10,
+including letters that are normally catcode@tie{}11.
+
+@findex \IfBeginWith*@r{ macro from @file{xstring}}
+@PkgIndex xstring
+Because of this catcode situation, using the jobname in a conditional
+can become complicated. One solution is to use the macro
+@code{\IfBeginWith} from the @file{xstring} package in its star
+variant, which is insensitive to catcode. For example, in the
+following text the footnote ``Including Respublica Bananensis
+Francorum.''@: is only present if the task name starts with
+@file{my-doc}.
+
+@example
+If a democracy is just a regime where citizens vote then
+all banana republics \IfBeginWith*@{\jobname@}@{my-doc@}%
+@{\footnote@{Including Respublica Bananensis Francorum.@}@}@{@} are
+democracies.
+@end example
+
+Manipulating the value of @code{\jobname} inside of a document does not
+change the name of the output file or the log file.
@node Recovering from errors
@@ -18722,8 +21452,8 @@ l.5 The \PN
@end example
@noindent
-The simplest thing is to enter @samp{x} and @code{<return>} and fix the
-typo. You could instead enter @samp{?} and @code{<return>} to see other
+The simplest thing is to enter @kbd{x} and @kbd{RETURN} and fix the
+typo. You could instead enter @kbd{?} and @kbd{RETURN} to see other
options.
@cindex @samp{*} prompt
@@ -18732,9 +21462,10 @@ options.
There are two other error scenarios. The first is that you forgot to
include the @code{\end@{document@}} or misspelled it. In this case
@LaTeX{} gives you a @samp{*} prompt. You can get back to the command
-line by typing @code{\stop} and @code{<return>}.
+line by typing @kbd{\stop} and @kbd{RETURN}; this command does its
+best to exit @LaTeX{} immediately, whatever state it may be in.
-The last scenario is that you mistyped the file name. For instance,
+The last scenario is that you mistyped the filename. For instance,
instead of @code{pdflatex test} you might type @code{pdflatex tste}.
@example
@@ -18746,8 +21477,8 @@ Please type another input file name:
@end example
@noindent
-The simplest thing is to enter @code{<Control>} and @samp{d} (holding
-them down at the same time), and then retype the correct command line.
+The simplest thing is to enter @kbd{CTRL d} (holding the Control and d
+keys down at the same time), and then retype the correct command line.
@node Document templates
@@ -18756,16 +21487,15 @@ them down at the same time), and then retype the correct command line.
@cindex document templates
@cindex templates, document
-Although not reference material, perhaps these document templates will
+Although illustrative material, perhaps these document templates will
be useful. Additional template resources are listed at
-@url{http://tug.org/interest.html#latextemplates}.
+@url{https://tug.org/interest.html#latextemplates}.
@menu
* beamer template::
* article template::
* book template::
* Larger book template::
-* tugboat template::
@end menu
@@ -18774,6 +21504,7 @@ be useful. Additional template resources are listed at
@cindex @code{beamer} template and class
@cindex template, @code{beamer}
+@PkgIndex{beamer}
The @code{beamer} class creates presentation slides. It has a vast
array of features, but here is a basic template:
@@ -18783,7 +21514,7 @@ array of features, but here is a basic template:
\title{Beamer Class template}
\author{Alex Author}
-\date{July 31, 2007}
+\date{July 31, 2020}
\begin{document}
@@ -18802,14 +21533,15 @@ array of features, but here is a basic template:
\end{document}
@end verbatim
-One web resource for this:
-@url{http://robjhyndman.com/hyndsight/beamer/}.
+The Beamer package on CTAN: @url{https://ctan.org/pkg/beamer}.
@node article template
@section @code{article} template
-@cindex template, @code{article}
+@cindex template (simple), @code{article}
+
+A simple template for an article.
@verbatim
\documentclass{article}
@@ -18827,6 +21559,7 @@ Additional text.
\section{Second section}
Some more text.
+
\end{document}
@end verbatim
@@ -18836,8 +21569,8 @@ Some more text.
@cindex template, @code{book}
-This is a straightforward template for a book. See @xref{Larger book
-template} for a more elaborate one.
+This is a straightforward template for a book. @xref{Larger book
+template}, for a more elaborate one.
@verbatim
\documentclass{book}
@@ -18855,6 +21588,7 @@ Some other text.
\section{A subtopic}
The end.
+
\end{document}
@end verbatim
@@ -18864,19 +21598,22 @@ The end.
@cindex template, @code{book}
-This is a more elaborate template for a book. It has
-@code{\frontmatter}, @code{\mainmatter}, and @code{\backmatter} to
-control the typography of the three main areas of a book
-(@pxref{\frontmatter & \mainmatter & \backmatter}). The book has a
-bibliography and an index.
+This is a somewhat elaborate template for a book. @xref{book template},
+for a simpler one.
+
+This template uses @code{\frontmatter}, @code{\mainmatter}, and
+@code{\backmatter} to control the typography of the three main areas
+of a book (@pxref{\frontmatter & \mainmatter & \backmatter}). The
+book has a bibliography and an index.
-Notable is that it uses @code{\include} and @code{\includeonly}
+Also notable is that it uses @code{\include} and @code{\includeonly}
(@pxref{Splitting the input}). While you are working on a chapter you
can comment out all the other chapter entries from the argument to
-@code{\includeonly}. That will speed up compilation without losing any
-information such as cross-references. (Material that does not need to
-come on a new page is brought in with @code{\input} instead of
-@code{\include}. You don't get the cross-reference benefit this way.)
+@code{\includeonly}. That will speed up compilation without losing
+any information such as cross-references. (Material that does not
+need to come on a new page is brought in with @code{\input} instead of
+@code{\include}. You don't get the cross-reference benefit with
+@code{\input}.)
@verbatim
\documentclass[titlepage]{book}
@@ -18886,11 +21623,12 @@ come on a new page is brought in with @code{\input} instead of
\author{Alex Author}
\includeonly{%
- frontcover,
+% frontcover,
preface,
chap1,
- ...
+% appenA,
}
+
\begin{document}
\frontmatter
\include{frontcover}
@@ -18898,112 +21636,22 @@ come on a new page is brought in with @code{\input} instead of
\maketitle \input{dedication} \input{copyright}
\tableofcontents
\include{preface}
+
\mainmatter
\include{chap1}
...
\appendix
-\include{appena}
+\include{appenA}
...
+
\backmatter
\bibliographystyle{apalike}
\addcontentsline{toc}{chapter}{Bibliography}
\bibliography
\addcontentsline{toc}{chapter}{Index}
\printindex
-\include{backcover}
-\end{document}
-@end verbatim
-
-
-@node tugboat template
-@section @code{tugboat} template
-
-@cindex template, TUGboat
-@cindex TUGboat template
-@cindex @code{ltugboat} class
-
-@cite{TUGboat} is the journal of the @TeX{} Users Group,
-@url{http://tug.org/TUGboat}.
-
-@verbatim
-\documentclass{ltugboat}
-
-\usepackage{graphicx}
-\usepackage{ifpdf}
-\ifpdf
-\usepackage[breaklinks,hidelinks]{hyperref}
-\else
-\usepackage{url}
-\fi
-
-%%% Start of metadata %%%
-
-\title{Example \TUB\ article}
-
-% repeat info for each author.
-\author{First Last}
-\address{Street Address \\ Town, Postal \\ Country}
-\netaddress{user (at) example dot org}
-\personalURL{http://example.org/~user/}
-
-%%% End of metadata %%%
-
-\begin{document}
-\maketitle
-
-\begin{abstract}
-This is an example article for \TUB{}.
-Please write an abstract.
-\end{abstract}
-
-\section{Introduction}
-
-This is an example article for \TUB, linked from
-\url{http://tug.org/TUGboat/location.html}.
-
-We recommend the \texttt{graphicx} package for image inclusions, and the
-\texttt{hyperref} package if active urls are desired (in the \acro{PDF}
-output). Nowadays \TUB\ is produced using \acro{PDF} files exclusively.
-
-The \texttt{ltugboat} class provides these abbreviations (and many more):
-% verbatim blocks are often better in \small
-\begin{verbatim}[\small]
-\AllTeX \AMS \AmS \AmSLaTeX \AmSTeX \aw \AW
-\BibTeX \CTAN \DTD \HTML
-\ISBN \ISSN \LaTeXe
-\mf \MFB
-\plain \POBox \PS
-\SGML \TANGLE \TB \TP
-\TUB \TUG \tug
-\UNIX \XeT \WEB \WEAVE
-
-\, \bull \Dash \dash \hyph
-
-\acro{FRED} -> {\small[er] fred} % please use!
-\cs{fred} -> \fred
-\meta{fred} -> <fred>
-\nth{n} -> 1st, 2nd, ...
-\sfrac{3/4} -> 3/4
-\booktitle{Book of Fred}
-\end{verbatim}
-
-For references to other \TUB\ issue, please use the format
-\textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for our \nth{100} issue.
-
-This file is just a template. The \TUB\ style documentation is the
-\texttt{ltubguid} document at \url{http://ctan.org/pkg/tugboat}. (For
-\CTAN\ references, where sensible we recommend that form of url, using
-\texttt{/pkg/}; or, if you need to refer to a specific file location,
-\texttt{http://mirror.ctan.org/\textsl{path}}.)
-
-Email \verb|tugboat@tug.org| if problems or questions.
-
-\bibliographystyle{plain} % we recommend the plain bibliography style
-\nocite{book-minimal} % just making the bibliography non-empty
-\bibliography{xampl} % xampl.bib comes with BibTeX
-
-\makesignature
+\include{backcover}
\end{document}
@end verbatim
@@ -19023,7 +21671,7 @@ Email \verb|tugboat@tug.org| if problems or questions.
% % where |\T1\foo| is \emph{one} control sequence, not two!
\newcommand
-\def\ProvideTextCommand -- same with \providecommand
+\def\ProvideTextCommand % same with \providecommand
\@onlypreamble\DeclareTextCommand
\@onlypreamble\DeclareTextSymbol
\gdef\TextSymbolUnavailable#1{%