summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk')
-rw-r--r--Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk3231
1 files changed, 2717 insertions, 514 deletions
diff --git a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
index b282655c48e..e19d3d75c39 100644
--- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
+++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
@@ -4,14 +4,15 @@
<!ENTITY latex "LaTeX">
]>
<book id="latex2e.dbk" lang="en">
-<title>&latex;2e unofficial reference manual (November 2016)</title>
+
+
+<title>&latex;2e unofficial reference manual (March 2018)</title>
<!-- %**end of header (This is for running Texinfo on a region.) -->
<!-- latex 2.09 commands should all be present now, -->
<!-- xx but latex2e stuff is missing. -->
<!-- xx random list of a few of the missing items is at the end of this file -->
<!-- -->
-<!-- xx misc commands from clsguide.pdf -->
<!-- xx ending a run with errors -->
<!-- xx ctan, distributions, components of TeX -->
<!-- xx classes and packages - required, additional, useful; oberdiek; fonts -->
@@ -22,6 +23,7 @@
<!-- xx merge latex-manual from savannah -->
<!-- xx merge display style math -->
<!-- xx vertical mode, horizontal mode -->
+<!-- xx JH Discuss restricted execution -->
<!-- -->
<!-- xx The typeset source2e has an index with all kernel -->
<!-- xx commands, though some are internal and shouldn't be included. -->
@@ -29,7 +31,7 @@
<!-- xx See also http://ctan.org/pkg/macros2e. -->
<bookinfo><legalnotice><para>This document is an unofficial reference manual for &latex;, a
-document preparation system, version of November 2016.
+document preparation system, version of March 2018.
</para>
<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in
the VMS Help Library. The pre-translation version was written by
@@ -44,7 +46,7 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n
text was directly copied).
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
-2014, 2015, 2016 Karl Berry.
+2014, 2015, 2016, 2017, 2018 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
@@ -68,7 +70,7 @@ into another language, under the above conditions for modified versions.
<para>This document is an unofficial reference manual for &latex;, a
-document preparation system, version of November 2016.
+document preparation system, version of March 2018.
</para>
<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in
the VMS Help Library. The pre-translation version was written by
@@ -83,7 +85,7 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n
text was directly copied).
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
-2014, 2015, 2016 Karl Berry.
+2014, 2015, 2016, 2017, 2018 Karl Berry.
Copyright 1988, 1994, 2007 Stephen Gilmore.
@@ -109,12 +111,11 @@ into another language, under the above conditions for modified versions.
<!-- Best Effort Symbol -->
-
<chapter label="" id="Top">
<title>&latex;2e: An unofficial reference manual</title>
<para>This document is an unofficial reference manual (version of
-November 2016) for &latex;2e, a document preparation system.
+March 2018) for &latex;2e, a document preparation system.
</para>
@@ -122,31 +123,31 @@ November 2016) for &latex;2e, a document preparation system.
<chapter label="1" id="About-this-document">
<title>About this document</title>
-<indexterm role="cp"><primary>bug reporting</primary></indexterm>
-<indexterm role="cp"><primary>reporting bugs</primary></indexterm>
-<indexterm role="fn"><primary><ulink url="http://home.gna.org/latexrefman">http://home.gna.org/latexrefman</ulink> home page</primary></indexterm>
+<indexterm role="fn"><primary><ulink url="http://puszcza.gnu.org.ua/software/latexrefman/">http://puszcza.gnu.org.ua/software/latexrefman/</ulink> home page</primary></indexterm>
<para>This is an unofficial reference manual for the &latex;2e document
preparation system, which is a macro package for the &tex;
typesetting program (see <link linkend="Overview">Overview</link>). This document&#8217;s home page is
-<ulink url="http://home.gna.org/latexrefman">http://home.gna.org/latexrefman</ulink>. That page has links to the
+<ulink url="http://puszcza.gnu.org.ua/software/latexrefman/">http://puszcza.gnu.org.ua/software/latexrefman/</ulink>. That page has links to the
current output in various formats, sources, mailing list archives and
subscriptions, and other infrastructure.
</para>
<indexterm role="cp"><primary>&latex; vs. &latex;2e</primary></indexterm>
<para>In this document, we will mostly just use &#8216;&latex;&#8217; rather than
&#8216;&latex;2e&#8217;, since the previous version of &latex;&#160;(2.09) was
-retired many years ago.
+frozen decades ago.
</para>
<indexterm role="cp"><primary>unofficial nature of this manual</primary></indexterm>
<indexterm role="cp"><primary>&latex; Project team</primary></indexterm>
-<indexterm role="fn"><primary><email>latexrefman-discuss@gna.org</email> email address</primary></indexterm>
+<indexterm role="fn"><primary><email>latexrefman@tug.org</email> email address</primary></indexterm>
<para>&latex; is currently maintained by a group of volunteers
(<ulink url="http://latex-project.org">http://latex-project.org</ulink>). The official documentation written by
the &latex; project is available from their web site. This document is
completely unofficial and has not been reviewed by the &latex;
-maintainers. Do not send bug reports or anything else about this
-document to them. Instead, please send all comments to
-<email>latexrefman-discuss@gna.org</email>.
+maintainers.
+<indexterm role="cp"><primary>bug reporting</primary></indexterm>
+<indexterm role="cp"><primary>reporting bugs</primary></indexterm>
+Do not send bug reports or anything else about this document to them.
+Instead, please send all comments to <email>latexrefman@tug.org</email>.
</para>
<para>This document is a reference. There is a vast array of other sources
of information about &latex;, at all levels. Here are a few
@@ -162,8 +163,9 @@ introductions.
</para>
</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/usrguide">http://ctan.org/pkg/usrguide</ulink>
</term><listitem><indexterm role="fn"><primary>usrguide official documentation</primary></indexterm>
-<para>The guide for document authors that is maintained as part of &latex;;
-there are plenty of others available elsewhere.
+<para>The guide for document authors that is maintained as part of &latex;.
+Many other guides by many other people are also available, independent
+of &latex; itself; one such is the next item:
</para>
</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/lshort">http://ctan.org/pkg/lshort</ulink>
</term><listitem><indexterm role="fn"><primary>lshort document</primary></indexterm>
@@ -438,7 +440,8 @@ commands it covers (barring unintentional omissions, a.k.a. bugs).
</para>
-<anchor id="Environment"/>
+<sect2 label="2.4.1" id="Environment">
+<title>Environments</title>
<para>Synopsis:
</para>
@@ -472,14 +475,18 @@ required (it specifies the formatting of columns).
\end{tabular}
</screen>
-<anchor id="Declaration"/>
+</sect2>
+<sect2 label="2.4.2" id="Declaration">
+<title>Command declarations</title>
<para>A command that changes the value, or changes the meaning, of some other
command or parameter. For instance, the <literal>\mainmatter</literal> command
changes the setting of page numbers from roman numerals to arabic.
</para>
-<anchor id="_005cmakeatletter-and-_005cmakeatother"/>
+</sect2>
+<sect2 label="2.4.3" id="_005cmakeatletter-and-_005cmakeatother">
+<title><literal>\makeatletter</literal> and <literal>\makeatother</literal></title>
<para>Synopsis:
</para>
@@ -497,7 +504,7 @@ character category code, or
<indexterm role="cp"><primary>catcode</primary></indexterm>
<indexterm role="cp"><primary>character category code</primary></indexterm>
<indexterm role="cp"><primary>category code, character</primary></indexterm>
-<firstterm>catcode</firstterm> for shorter. For instance, the backslash&#160;<literal>\</literal> is
+<firstterm>catcode</firstterm> for short. For instance, the backslash&#160;<literal>\</literal> is
assigned the catcode 0, for characters that start a command. These two
commands alter the catcode assigned to <literal>@</literal>.
</para>
@@ -511,36 +518,96 @@ So under the default category codes, user-defined commands cannot
contain an <literal>@</literal>. But <literal>\makeatletter</literal> and <literal>\makeatother</literal>
allow users to define or redefine commands named with <literal>@</literal>.
</para>
-<para>Use these inside a <filename>.tex</filename> file, in the preamble. Don&#8217;t use them
-inside <filename>.sty</filename> or <filename>.cls</filename> files since the <literal>\usepackage</literal>
-and <literal>\documentclass</literal> commands set the at sign to have the character
-code of a letter.
+<para>Use these two commands inside a <filename>.tex</filename> file, in the preamble, when
+defining or redefining a command with <literal>@</literal> in its name. Don&#8217;t use
+them inside <filename>.sty</filename> or <filename>.cls</filename> files since the
+<literal>\usepackage</literal> and <literal>\documentclass</literal> commands set the at sign to
+have the character code of a letter.
</para>
<indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm>
-<indexterm role="cp"><primary><literal>macros2e</literal> package For a comprehensive list of macros with an at-sign</primary></indexterm>
-<para>in their names, see document
-<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. These macros are mainly useful
-to package or class authors; examples that may be useful to document
-authors are provided hereinafter.
-</para>
-<para>The example code below, if put in the preamble, redefines the
-section command to center the section title, put it in bold type,
-and adjust the spacing.
-</para>
-<!-- xxx TODO, make \@startsection a separate node, see latex2e-fr.texi -->
-<!-- From http://zoonek.free.fr/LaTeX/LaTeX_samples_section/0.html -->
+<indexterm role="cp"><primary><literal>macros2e</literal> package</primary></indexterm>
+
+<para>For a comprehensive list of macros with an at-sign
+in their names see <ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. These macros are
+mainly intended to package or class authors.
+</para>
+<para>The example below is typical. In the user&#8217;s class file is a command
+<literal>\thesis@universityname</literal>. The user wants to change the
+definition. These three lines should go in the preamble, before the
+<literal>\begin{document}</literal>.
+</para>
<screen>\makeatletter
-\renewcommand\section{%
- \@startsection{section}% Name
- {1}% Level: 0=part, 1=chapter, etc.
- {0pt}% Heading indent
- {-3.5ex plus -1ex minus -.2ex}% Beforeskip (if neg, no head indent)
- {2.3ex plus.2ex}% Afterskip (if neg, run-in heading)
- {\centering\normalfont\Large\bfseries}} % Style of head
+\renewcommand{\thesis@universityname}{Saint Michael's College}
\makeatother
</screen>
-<!-- xx TODO document \@ifstar, see latex2e-fr.texi -->
+
+<sect3 label="2.4.3.1" id="_005c_0040ifstar">
+<title><literal>\@ifstar</literal></title>
+
+<indexterm role="fn"><primary>\@ifstar</primary></indexterm>
+<indexterm role="cp"><primary>commands, star-variants</primary></indexterm>
+<indexterm role="cp"><primary>star-variants, commands</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}}
+\newcommand{\mycmd@nostar}[<replaceable>non-starred command number of args</replaceable>]{<replaceable>body of non-starred command</replaceable>}
+\newcommand{\mycmd@star}[<replaceable>starred command number of args</replaceable>]{<replaceable>body of starred command</replaceable>}
+</screen>
+<para>Many standard &latex; environments or commands have a variant with the
+same name but ending with a star character&#160;<literal>*</literal>, an asterisk.
+Examples are the <literal>table</literal> and <literal>table*</literal> environments and the
+<literal>\section</literal> and <literal>\section*</literal> commands.
+</para>
+<para>When defining environments, following this pattern is straightforward
+because <literal>\newenvironment</literal> and <literal>\renewenvironment</literal> allow the
+environment name to contain a star. For commands the situation is more
+complex. As in the synopsis above, there will be a user-called command,
+given above as <literal>\mycmd</literal>, which peeks ahead to see if it is followed
+by a star. For instance, &latex; does not really have a
+<literal>\section*</literal> command; instead, the <literal>\section</literal> command peeks
+ahead. This command does not accept arguments but instead expands to
+one of two commands that do accept arguments. In the synopsis these two
+are <literal>\mycmd@nostar</literal> and <literal>\mycmd@star</literal>. They could take the
+same number of arguments or a different number, or no arguments at all.
+As always, in a &latex; document a command using at-sign&#160;<literal>@</literal>
+must be enclosed inside a <literal>\makeatletter ... \makeatother</literal> block
+(see <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>).
+</para>
+<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a
+variant <literal>\ciel*</literal>. Both have one required argument. A call to
+<literal>\ciel{night}</literal> will return &quot;starry night sky&quot; while
+<literal>\ciel*{blue}</literal> will return &quot;starry not blue sky&quot;.
+</para>
+<screen>\newcommand*{\ciel@unstarred}[1]{starry #1 sky}
+\newcommand*{\ciel@starred}[1]{starry not #1 sky}
+\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}
+</screen>
+<para>In the next example, the starred variant takes a different number of
+arguments than does the unstarred one. With this definition, Agent
+007&#8217;s <literal>``My name is \agentsecret*{Bond},
+\agentsecret{James}{Bond}.''</literal> is equivalent to <literal>``My name is
+\textsc{Bond}, \textit{James} textsc{Bond}.''</literal>
+</para>
+<screen>\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}}
+\newcommand*{\agentsecret@starred}[1]{\textsc{#1}}
+\newcommand*{\agentsecret}{\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
+</screen>
+<para>There are two sometimes more convenient ways to accomplish the work of
+<literal>\@ifstar</literal>. The <filename>suffix</filename> package allows the construct
+<literal>\newcommand\mycommand{<replaceable>unstarred version</replaceable>}</literal> followed by
+<literal>\WithSuffix\newcommand\mycommand*{<replaceable>starred version</replaceable>}</literal>. And
+&latex;3 has the <filename>xparse</filename> package that allows this code.
+</para>
+<screen>\NewDocumentCommand\foo{s}{\IfBooleanTF#1
+ {<replaceable>starred version</replaceable>}%
+ {<replaceable>unstarred version</replaceable>}%
+ }
+</screen>
+
+</sect3>
+</sect2>
</sect1>
</chapter>
<chapter label="3" id="Document-classes">
@@ -645,12 +712,16 @@ size (these show height by width):
<indexterm role="fn"><primary>\pdfpageheight</primary></indexterm>
<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm>
+
<para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex;
(see <link linkend="TeX-engines">&tex; engines</link>), options other than <literal>letterpaper</literal> set
the print area but you must also set the physical paper size. One way
to do that is to put <literal>\pdfpagewidth=\paperwidth</literal> and
-<literal>\pdfpageheight=\paperheight</literal> in your document&#8217;s preamble. The
-<literal>geometry</literal> package provides flexible ways of setting the print
+<literal>\pdfpageheight=\paperheight</literal> in your document&#8217;s preamble.
+<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm>
+</para>
+<para>The <literal>geometry</literal> package provides flexible ways of setting the print
area and physical page size.
</para>
<indexterm role="fn"><primary>draft option</primary></indexterm>
@@ -781,14 +852,14 @@ SMC Math Department</literal> is for a class.
<indexterm role="cp"><primary>difference between class and package</primary></indexterm>
</para>
<para>Inside of a class or package file you can use the at-sign <literal>@</literal> as a
-character in command names without having to surround that command with
-<literal>\makeatletter</literal> and <literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and
-\makeatother</link>. This allow you to create commands that users will not
-accidentally redefine. Another technique is to preface class- or
-package-specific commands with some string to prevent your class or
-package from interacting with others. For instance, the class
-<literal>smcmemo</literal> might have commands <literal>\smc@tolist</literal>,
-<literal>\smc@fromlist</literal>, etc.
+character in command names without having to surround the code
+containing that command with <literal>\makeatletter</literal> and
+<literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>. This allow
+you to create commands that users will not accidentally redefine.
+Another technique is to preface class- or package-specific commands with
+some string to prevent your class or package from interfering with
+others. For instance, the class <literal>smcmemo</literal> might have commands
+<literal>\smc@tolist</literal>, <literal>\smc@fromlist</literal>, etc.
</para>
@@ -804,29 +875,32 @@ package from interacting with others. For instance, the class
<indexterm role="cp"><primary>class options</primary></indexterm>
<indexterm role="cp"><primary>package options</primary></indexterm>
-<para>A class file or package file typically has four parts. (1)&#160;In the
-identification part, the file says that it is a &latex; package or
-class and describes itself, using the <literal>\NeedsTeXFormat</literal> and
-<literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands. (2)&#160;The
-preliminary declarations part declares some commands and can also load
-other files. Usually these commands will be those needed for the code
-used in the next part. For example, an <literal>smcmemo</literal> class might be
-called with an option to read in a file with a list of people for the
-to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and therefore
-needs to define a command
+<para>A class file or package file typically has four parts.
+</para><orderedlist numeration="arabic"><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex;
+package or class and describes itself, using the <literal>\NeedsTeXFormat</literal>
+and <literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands.
+</para><listitem><para>The <firstterm>preliminary declarations part</firstterm> declares some commands and
+can also load other files. Usually these commands will be those needed
+for the code used in the next part. For example, an <literal>smcmemo</literal>
+class might be called with an option to read in a file with a list of
+people for the to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and
+therefore needs to define a command
<literal>\newcommand{\setto}[1]{\def\@tolist{#1}}</literal> used in that
-file. (3)&#160;In the handle options part the class or package declares
+file.
+</para></listitem><listitem><para>In the <firstterm>handle options part</firstterm> the class or package declares
and processes its options. Class options allow a user to start their
document as <literal>\documentclass[<replaceable>option list</replaceable>]{<replaceable>class
name</replaceable>}</literal>, to modify the behavior of the class. An example is when you
declare <literal>\documentclass[11pt]{article}</literal> to set the default
-document font size. Finally, (4)&#160;in the more declarations part the
-class or package usually does most of its work: declaring new variables,
-commands and fonts, and loading other files.
-</para>
-<para>Here is a starting class file, which should be saved as <literal>stub.cls</literal>
+document font size.
+</para></listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package usually does
+most of its work: declaring new variables, commands and fonts, and
+loading other files.
+</para></listitem></orderedlist>
+
+<para>Here is a starting class file, which should be saved as <filename>stub.cls</filename>
where &latex; can find it, for example in the same directory as the
-<literal>.tex</literal> file.
+<filename>.tex</filename> file.
</para>
<screen>\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{stub}[2017/07/06 stub to start building classes from]
@@ -855,7 +929,7 @@ of the descriptions here derive from this document), or the tutorial
</para>
<variablelist><varlistentry><term><literal>\AtBeginDvi{specials}</literal>
</term><listitem><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm>
-<para>Save in a box register things that are written to the <literal>.dvi</literal> file
+<para>Save in a box register things that are written to the <filename>.dvi</filename> file
at the beginning of the shipout of the first page of the document.
</para>
</listitem></varlistentry><varlistentry><term><literal>\AtEndOfClass{<replaceable>code</replaceable>}</literal>
@@ -867,6 +941,22 @@ processing the current class or package. You can use these hooks
multiple times; the <literal>code</literal> will be executed in the order that you
called it. See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>.
</para>
+</listitem></varlistentry><varlistentry><term><literal>\CheckCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
+</term></varlistentry><varlistentry><term><literal>\CheckCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
+</term><listitem><indexterm role="fn"><primary>\CheckCommand</primary></indexterm>
+<indexterm role="fn"><primary>\CheckCommand*</primary></indexterm>
+<indexterm role="cp"><primary>new command, check</primary></indexterm>
+<para>Like <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>) but does
+not define <replaceable>cmd</replaceable>; instead it checks that the current definition of
+<replaceable>cmd</replaceable> is exactly as given by <replaceable>definition</replaceable> and is or is not
+<indexterm role="cp"><primary>long command</primary></indexterm>
+<firstterm>long</firstterm> as expected. A long command is a command that accepts
+<literal>\par</literal> within an argument. The <replaceable>cmd</replaceable> command is expected to be
+long with the unstarred version of <literal>\CheckCommand</literal>. Raises an
+error when the check fails. This allows you to check before you start
+redefining <literal>cmd</literal> yourself that no other package has already
+redefined this command.
+</para>
</listitem></varlistentry><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal>
</term></varlistentry><varlistentry><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal>
</term></varlistentry><varlistentry><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal>
@@ -902,8 +992,9 @@ message, while the other versions do show that number.
</para>
<para>To format the messages, including the <replaceable>help text</replaceable>: use
<literal>\protect</literal> to stop a command from expanding, get a line break with
-<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal>. Note that
-&latex; appends a period to the messages.
+<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal> when a space
+character does not allow it, like after a command. Note that &latex;
+appends a period to the messages.
</para>
</listitem></varlistentry><varlistentry><term><literal>\CurrentOption</literal>
</term><listitem><indexterm role="fn"><primary>\CurrentOption</primary></indexterm>
@@ -912,7 +1003,7 @@ be used within the <replaceable>code</replaceable> argument of either <literal>\
or <literal>\DeclareOption*</literal>.
</para>
</listitem></varlistentry><varlistentry><term><literal>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal>
-</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal>
+</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\DeclareOption</primary></indexterm>
<indexterm role="fn"><primary>\DeclareOption*</primary></indexterm>
<indexterm role="cp"><primary>class options</primary></indexterm>
@@ -947,16 +1038,54 @@ passes the option to the <literal>article</literal> class.
<screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
\PassOptionsToClass{\CurrentOption}{article}}}
</screen>
+</listitem></varlistentry><varlistentry><term><literal>\DeclareRobustCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
+</term></varlistentry><varlistentry><term><literal>\DeclareRobustCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal>
+</term><listitem><indexterm role="fn"><primary>\DeclareRobustCommand</primary></indexterm>
+<indexterm role="fn"><primary>\DeclareRobustCommand*</primary></indexterm>
+<indexterm role="cp"><primary>new command, definition</primary></indexterm>
+<para>Like <literal>\newcommand</literal> and <literal>\newcommand*</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
+\renewcommand</link>) but these declare a robust command, even if some code
+within the <replaceable>definition</replaceable> is fragile. (For a discussion of robust and
+fragile commands see <link linkend="_005cprotect">\protect</link>.) Use this command to define new
+robust commands or to redefine existing commands and make them
+robust. Unlike <literal>\newcommand</literal> these do not give an error if macro
+<replaceable>cmd</replaceable> already exists; instead, a log message is put into the
+transcript file if a command is redefined.
+</para>
+<para>Commands defined this way are a bit less efficient than those defined
+using <literal>\newcommand</literal> so unless the command&#8217;s data is fragile and the
+command is used within a moving argument, use <literal>\newcommand</literal>.
+</para>
+<indexterm role="cp"><primary>package, <literal>etoolbox</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>etoolbox</literal> package</primary></indexterm>
+
+<para>The <literal>etoolbox</literal> package offers commands <literal>\newrobustcmd</literal>,
+<literal>\newrobustcmd*</literal>, <literal>\renewrobustcmd</literal>, <literal>\renewrobustcmd*</literal>,
+<literal>\providerobustcmd</literal>, and <literal>\providerobustcmd*</literal> which are similar
+to <literal>\newcommand</literal>, <literal>\newcommand*</literal>, <literal>\renewcommand</literal>,
+<literal>\renewcommand*</literal>, <literal>\providecommand</literal>, and
+<literal>\providecommand*</literal>, but define a robust <replaceable>cmd</replaceable> with two advantages
+as compared to <literal>\DeclareRobustCommand</literal>:
+</para><orderedlist numeration="arabic"><listitem><para>They use the low-level e-&tex; protection mechanism rather than the
+higher level &latex; <literal>\protect</literal> mechanism, so they do not incur
+the slight loss of performance mentioned above, and
+</para></listitem><listitem><para>They make the same distinction between <literal>\new&#8230;</literal>,
+<literal>\renew&#8230;</literal>, and <literal>\provide&#8230;</literal>, as the standard
+commands, so they do not just make a log message when you redefine
+<replaceable>cmd</replaceable> that already exists, in that case you need to use either
+<literal>\renew&#8230;</literal> or <literal>\provide&#8230;</literal> or you get an error.
+</para></listitem></orderedlist>
+
</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
</term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\IfFileExists</primary></indexterm>
<indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm>
-<para>Execute <replaceable>true code</replaceable> if &latex; can find the file and <replaceable>false
-code</replaceable> otherwise. In the second case it inputs the file immediately
-after executing <replaceable>true code</replaceable>. Thus
+<para>Execute <replaceable>true code</replaceable> if &latex; can find the file <filename><replaceable>file
+name</replaceable></filename> and <replaceable>false code</replaceable> otherwise. In the second case it inputs the
+file immediately after executing <replaceable>true code</replaceable>. Thus
<literal>\IfFileExists{img.pdf}{\includegraphics{img.pdf}}{\typeout{WARNING:
-img.pdf not found}}</literal> will include the graphic if it is found but
-otherwise just give a warning.
+img.pdf not found}}</literal> will include the graphic <filename>img.pdf</filename> if it is
+found but otherwise just give a warning.
</para>
<para>This command looks for the file in all search paths that &latex; uses,
not only in the current directory. To look only in the current
@@ -976,7 +1105,12 @@ list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release
</para>
<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The
<replaceable>release date</replaceable> is optional. If present it must have the form
-<replaceable>YYYY/MM/DD</replaceable>. If you request a <replaceable>release date</replaceable> and the date of
+<replaceable>YYYY/MM/DD</replaceable>.
+<!-- BTW, there are at-macros documented in macros2e.pdf to check the version -->
+<!-- and do some actions conditionnally on version later or not to some -->
+<!-- date. -->
+</para>
+<para>If you request a <replaceable>release date</replaceable> and the date of
the package installed on your system is earlier, then you get a warning
on the screen and in the log like <literal>You have requested, on input
line 4, version `2038/01/19' of document class article, but only version
@@ -990,8 +1124,8 @@ that lets you build classes on existing ones, such as the standard
</para>
</listitem></varlistentry><varlistentry><term><literal>\ExecuteOptions{<replaceable>options-list</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm>
-<para>For each option in the <replaceable>options-list</replaceable>, in order, this command
-executes the command <literal>\ds@</literal><replaceable>option</replaceable>. If this command is not
+<para>For each option <replaceable>option</replaceable> in the <replaceable>options-list</replaceable>, in order, this command
+executes the command <literal>\ds@<replaceable>option</replaceable></literal>. If this command is not
defined then that option is silently ignored.
</para>
<para>It can be used to provide a default option list before
@@ -1001,13 +1135,13 @@ default to be 11pt fonts then you could specify
</para>
</listitem></varlistentry><varlistentry><term><literal>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format date</replaceable>]</literal>
</term><listitem><indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm>
-<para>Specifies the format that this class should be run under. Often issued
+<para>Specifies the format that this class must be run under. Often issued
as the first line of a class file, and most often used as:
-<literal>\NeedsTeXFormat{LaTeX2e}</literal>. The format that you specify must
-exactly match the one installed on your system that you invoked,
-including that the string is case sensitive. If it does not match then
-execution stops with an error like &#8216;<literal>This file needs format `xxx'
-but this is `LaTeX2e'.</literal>&#8217;
+<literal>\NeedsTeXFormat{LaTeX2e}</literal>. When a document using that class is
+processed, the format name given here must match the format that is
+actually being run (including that the <replaceable>format</replaceable> string is case
+sensitive). If it does not match then execution stops with an error
+like &#8216;<literal>This file needs format `LaTeX2e' but this is `xxx'.</literal>&#8217;
</para>
<para>To specify a version of the format that you know to have certain
features, include the optional <replaceable>format date</replaceable> on which those features
@@ -1015,8 +1149,7 @@ were implemented. If present it must be in the form <literal>YYYY/MM/DD</litera
If the format version installed on your system is earlier than
<replaceable>format date</replaceable> then you get a warning like &#8216;<literal>You have requested
release `2038/01/20' of LaTeX, but only release `2016/02/01' is
-available.</literal>&#8217; (The &latex; kernel has been frozen for many years so you
-probably do not not need to specify the format date.)
+available.</literal>&#8217;
</para>
</listitem></varlistentry><varlistentry><term><literal>\OptionNotUsed</literal>
</term><listitem><indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm>
@@ -1030,8 +1163,8 @@ within the <replaceable>code</replaceable> argument of either <literal>\DeclareO
<!-- option(s): [unusedoption].} with the list of not-used options when it -->
<!-- reaches @code{\begin@{document@}}. -->
-</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>options list</replaceable>}{<replaceable>class name</replaceable>}</literal>
-</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>options list</replaceable>}{<replaceable>package name</replaceable>}</literal>
+</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>option list</replaceable>}{<replaceable>class name</replaceable>}</literal>
+</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>option list</replaceable>}{<replaceable>package name</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm>
<indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm>
<para>Adds the options in the comma-separated list <replaceable>option list</replaceable> to the
@@ -1045,16 +1178,17 @@ more than once will get you an error like <literal>Option clash for package
foo.</literal> (&latex; throws an error even if there is no conflict between the
options.)
</para>
-<para>If your code is bringing in a package twice then you can collapse that
-to once, for example replacing the two
+<para>If your own code is bringing in a package twice then you can collapse
+that to once, for example replacing the two
<literal>\RequirePackage[landscape]{geometry}\RequirePackage[margins=1in]{geometry}</literal>
with the single
<literal>\RequirePackage[landscape,margins=1in]{geometry}</literal>. But if you
are loading a package that in turn loads another package then you need
-to queue up the options you desire. For instance, suppose the package
-<literal>foo</literal> loads the package <literal>geometry</literal>. Instead of <literal>
-\RequirePackage{foo}\RequirePackage[draft]{graphics}</literal> you must write
-<literal>\PassOptionsToPackage{draft}{graphics}
+to queue up the options you desire for this other package. For
+instance, suppose the package <literal>foo</literal> loads the package
+<literal>geometry</literal>. Instead of
+<literal>\RequirePackage{foo}\RequirePackage[draft]{graphics}</literal> you must
+write <literal>\PassOptionsToPackage{draft}{graphics}
\RequirePackage{foo}</literal>. (If <literal>foo.sty</literal> loads an option in conflict
with what you want then you may have to look into altering its source.)
</para>
@@ -1073,66 +1207,70 @@ option. The user could start their &latex; file with
in the class file as <literal>\ProcessOptions\relax</literal> (because of the
existence of the starred command).
</para>
-<para>Options come in two types. &#8216;Local&#8217; options have been specified for this
+<para>Options come in two types. <firstterm>Local options</firstterm> have been specified for this
particular package in the <replaceable>options</replaceable> argument of
<literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>,
<literal>\usepackage[<replaceable>options</replaceable>]</literal>, or
-<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. &#8216;Global&#8217; options are those given
+<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. <firstterm>Global options</firstterm> are those given
by the class user in <literal>\documentclass[<replaceable>options</replaceable>]</literal> (If an option
is specified both locally and globally then it is local.)
</para>
-<para>When <literal>\ProcessOptions</literal> is called for a package <literal>pkg.sty</literal>, the
-following happens. (1) For each option <replaceable>option</replaceable> so far declared
+<para>When <literal>\ProcessOptions</literal> is called for a package <filename>pkg.sty</filename>, the
+following happens:
+</para><orderedlist numeration="arabic"><listitem><para>For each option <replaceable>option</replaceable> so far declared
with <literal>\DeclareOption</literal>, it looks to see if that option is either a
global or a local option for <literal>pkg</literal>. If so then it executes the
declared code. This is done in the order in which these options were
-given in <literal>pkg.sty</literal>. (2) For each remaining local option, it
-executes the command <literal>\ds@</literal><replaceable>option</replaceable> if it has been defined
-somewhere (other than by a <literal>\DeclareOption</literal>); otherwise, it
-executes the default option code given in <literal>\DeclareOption*</literal>. If no
-default option code has been declared then it gives an error message.
-This is done in the order in which these options were specified.
-</para>
+given in <filename>pkg.sty</filename>.
+</para></listitem><listitem><para>For each remaining local option, it executes the command
+<literal>\ds@</literal><replaceable>option</replaceable> if it has been defined somewhere (other than by
+a <literal>\DeclareOption</literal>); otherwise, it executes the default option code
+given in <literal>\DeclareOption*</literal>. If no default option code has been
+declared then it gives an error message. This is done in the order in
+which these options were specified.
+</para></listitem></orderedlist>
<para>When <literal>\ProcessOptions</literal> is called for a class it works in the same
-way except that all options are local, and the default value for
+way except that all options are local, and the default <replaceable>code</replaceable> for
<literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error.
</para>
-<para>The starred version <literal>\ProcessOptions*</literal><replaceable>\@options</replaceable> executes the
+<para>The starred version <literal>\ProcessOptions*</literal> executes the
options in the order specified in the calling commands, rather than in
the order of declaration in the class or package. For a package this
means that the global options are processed first.
</para>
-</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>&lt;release date&gt;</replaceable> <replaceable>&lt;brief additional information&gt;</replaceable>]</literal>
-</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>&lt;release date&gt;</replaceable> <replaceable>&lt;brief additional information&gt;</replaceable>]</literal>
+</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal>
+</term></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal>
+</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal>
+</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
</term><listitem><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm>
<indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm>
<para>Identifies the class or package, printing a message to the screen and the log file.
</para>
<para>When a user writes <literal>\documentclass{smcmemo}</literal> then &latex; loads
-the file <literal>smcmemo.cls</literal>. Similarly, a user writing
+the file <filename>smcmemo.cls</filename>. Similarly, a user writing
<literal>\usepackage{test}</literal> prompts &latex; to load the file
<literal>test.sty</literal>. If the name of the file does not match the declared
class or package name then you get a warning. Thus, if you invoke
-<literal>\documentclass{smcmemo}</literal>, and the file <literal>smcmemo.cls</literal> has
+<literal>\documentclass{smcmemo}</literal>, and the file <filename>smcmemo.cls</filename> has
the statement <literal>\ProvidesClass{xxx}</literal> then you get a warning like
<literal>You have requested document class `smcmemo', but the document
class provides 'xxx'.</literal> This warning does not prevent &latex; from
processing the rest of the class file normally.
</para>
-<para>If you include the optional part then you must include the date, before
-the first space, and it must have the form <literal>YYYY/MM/DD</literal>. The rest
-of the optional part is free-form, although it traditionally identifies
+<para>If you include the optional argument, then you must include the date, before
+the first space if any, and it must have the form <literal>YYYY/MM/DD</literal>. The rest
+of the optional argument is free-form, although it traditionally identifies
the class, and is written to the screen during compilation and to the
-log file. Thus, if your file <literal>smcmem.cls</literal> contains the line
-<literal>\ProvidesClass{smcmem}[2008/06/01 SMC memo class]</literal> and your
-document&#8217;s first line is <literal>\documentclass{smcmem}</literal> then you will
-see <literal>Document Class: smcmemo 2008/06/01 SMC memo class</literal>.
+log file. Thus, if your file <filename>smcmemo.cls</filename> contains the line
+<literal>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</literal> and your
+document&#8217;s first line is <literal>\documentclass{smcmemo}</literal> then you will
+see <literal>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</literal>.
</para>
-<para>The date in the optional portion allows class and package users to ask
+<para>The date in the optional argument allows class and package users to ask
to be warned if the version of the class or package installed on their
-system is earlier than <replaceable>release date</replaceable>, by using the optional calls
-such as <literal>\documentclass{smcmem}[2018/10/12]</literal> or
+system is earlier than <replaceable>release date</replaceable>, by using the optional arguments
+such as <literal>\documentclass{smcmemo}[2018/10/12]</literal> or
<literal>\usepackage{foo}[[2017/07/07]]</literal>. (Note that package users only
rarely include a date, and class users almost never do.)
</para>
@@ -1141,19 +1279,21 @@ rarely include a date, and class users almost never do.)
<para>Declare a file other than the main class and package files, such as
configuration files or font definition files. Put this command in that
file and you get in the log a string like <literal>File: test.config
-2017/10/12 config file for test.cls</literal>.
+2017/10/12 config file for test.cls</literal> for <replaceable>file name</replaceable> equal to
+&#8216;<literal>test.config</literal>&#8217; and <replaceable>additional information</replaceable> equal to
+&#8216;<literal>2017/10/12 config file for test.cls</literal>&#8217;.
</para>
-</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>options list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
+</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>option list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
</term></varlistentry><varlistentry><term><literal>\RequirePackageWithOptions{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal>
</term><listitem><indexterm role="fn"><primary>\RequirePackage</primary></indexterm>
<indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm>
-<para>Load a package, like the author command <literal>\usepackage</literal>.
+<para>Load a package, like the document author command <literal>\usepackage</literal>.
See <link linkend="Additional-packages">Additional packages</link>. An example is
<literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>. Note that the
&latex; development team strongly recommends use of these commands over
Plain&#160;&tex;&#8217;s <literal>\input</literal>; see the Class Guide.
</para>
-<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The
+<para>The <replaceable>option list</replaceable>, if present, is a comma-separated list. The
<replaceable>release date</replaceable>, if present, must have the form <replaceable>YYYY/MM/DD</replaceable>. If
the release date of the package as installed on your system is earlier
than <replaceable>release date</replaceable> then you get a warning like <literal>You have
@@ -1383,10 +1523,11 @@ formulas. <literal>\mathversion{normal}</literal> restores the default.
<indexterm role="cp"><primary>lining numerals</primary></indexterm>
<indexterm role="cp"><primary>package, <literal>textcomp</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm>
+
<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset
so-called &#8220;old-style&#8221; numerals, which have differing heights and
depths (and sometimes widths) from the standard &#8220;lining&#8221; numerals,
-which all have the same height as upper-case letters. &latex;&#8217;s
+which all have the same height as uppercase letters. &latex;&#8217;s
default fonts support this, and will respect <literal>\textbf</literal> (but not
other styles; there are no italic old-style numerals in Computer
Modern). Many other fonts have old-style numerals also; sometimes the
@@ -1469,7 +1610,8 @@ Knuth&#8217;s original encoding for Computer Modern (the default), and
<literal>T1</literal>, also known as the Cork encoding, which has support for the
accented characters used by the most widespread European languages
(German, French, Italian, Polish and others), which allows &tex; to
-hyphenate words containing accented letters.
+hyphenate words containing accented letters. For more, see
+<ulink url="https://ctan.org/pkg/encguide">https://ctan.org/pkg/encguide</ulink>.
</para>
</listitem></varlistentry><varlistentry><term><literal>\fontfamily{<replaceable>family</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\fontfamily</primary></indexterm>
@@ -1480,29 +1622,48 @@ hyphenate words containing accented letters.
through many of the fonts easily used with &latex;. Here are
examples of some common families:
</para>
-<!-- Sorry about the ugly @t{@ }. The idea is to make the lists line up -->
-<!-- in Info. Since the items are so short, it seems nice to have them -->
-<!-- on the same line instead of using @table. -->
-
-<itemizedlist><listitem><para><!-- /@w --> <literal>pag</literal><literal>&#160;</literal> Avant Garde
-</para></listitem><listitem><para><!-- /@w --> <literal>fvs</literal><literal>&#160;</literal> Bitstream Vera Sans
-</para></listitem><listitem><para><!-- /@w --> <literal>pbk</literal><literal>&#160;</literal> Bookman
-</para></listitem><listitem><para><!-- /@w --> <literal>bch</literal><literal>&#160;</literal> Charter
-</para></listitem><listitem><para><!-- /@w --> <literal>ccr</literal><literal>&#160;</literal> Computer Concrete
-</para></listitem><listitem><para><!-- /@w --> <literal>cmr</literal><literal>&#160;</literal> Computer Modern
-</para></listitem><listitem><para><!-- /@w --> <literal>pcr</literal><literal>&#160;</literal> Courier
-</para></listitem><listitem><para><!-- /@w --> <literal>phv</literal><literal>&#160;</literal> Helvetica
-</para></listitem><listitem><para><!-- /@w --> <literal>fi4</literal><literal>&#160;</literal> Inconsolata
-</para></listitem><listitem><para><!-- /@w --> <literal>lmr</literal><literal>&#160;</literal> Latin Modern
-</para></listitem><listitem><para><!-- /@w --> <literal>lmss</literal> Latin Modern Sans
-</para></listitem><listitem><para><!-- /@w --> <literal>lmtt</literal> Latin Modern Typewriter
-</para></listitem><listitem><para><!-- /@w --> <literal>pnc</literal><literal>&#160;</literal> New Century Schoolbook
-</para></listitem><listitem><para><!-- /@w --> <literal>ppl</literal><literal>&#160;</literal> Palatino
-</para></listitem><listitem><para><!-- /@w --> <literal>ptm</literal><literal>&#160;</literal> Times
-</para></listitem><listitem><para><!-- /@w --> <literal>uncl</literal> Uncial
-</para></listitem><listitem><para><!-- /@w --> <literal>put</literal><literal>&#160;</literal> Utopia
-</para></listitem><listitem><para><!-- /@w --> <literal>pzc</literal><literal>&#160;</literal> Zapf Chancery
-</para></listitem></itemizedlist>
+<informaltable><tgroup cols="2"><colspec colwidth="4*"></colspec><colspec colwidth="31*"></colspec><tbody><row><entry><para><literal>pag</literal>
+</para></entry><entry><para>Avant Garde
+</para></entry></row><row><entry><para><literal>fvs</literal>
+</para></entry><entry><para>Bitstream Vera Sans
+</para></entry></row><row><entry><para><literal>pbk</literal>
+</para></entry><entry><para>Bookman
+</para></entry></row><row><entry><para><literal>bch</literal>
+</para></entry><entry><para>Charter
+</para></entry></row><row><entry><para><literal>ccr</literal>
+</para></entry><entry><para>Computer Concrete
+</para></entry></row><row><entry><para><literal>cmr</literal>
+</para></entry><entry><para>Computer Modern
+</para></entry></row><row><entry><para><literal>cmss</literal>
+</para></entry><entry><para>Computer Modern Sans Serif
+</para></entry></row><row><entry><para><literal>cmtt</literal>
+</para></entry><entry><para>Computer Modern Typewriter
+</para></entry></row><row><entry><para><literal>pcr</literal>
+</para></entry><entry><para>Courier
+</para></entry></row><row><entry><para><literal>phv</literal>
+</para></entry><entry><para>Helvetica
+</para></entry></row><row><entry><para><literal>fi4</literal>
+</para></entry><entry><para>Inconsolata
+</para></entry></row><row><entry><para><literal>lmr</literal>
+</para></entry><entry><para>Latin Modern
+</para></entry></row><row><entry><para><literal>lmss</literal>
+</para></entry><entry><para>Latin Modern Sans
+</para></entry></row><row><entry><para><literal>lmtt</literal>
+</para></entry><entry><para>Latin Modern Typewriter
+</para></entry></row><row><entry><para><literal>pnc</literal>
+</para></entry><entry><para>New Century Schoolbook
+</para></entry></row><row><entry><para><literal>ppl</literal>
+</para></entry><entry><para>Palatino
+</para></entry></row><row><entry><para><literal>ptm</literal>
+</para></entry><entry><para>Times
+</para></entry></row><row><entry><para><literal>uncl</literal>
+</para></entry><entry><para>Uncial
+</para></entry></row><row><entry><para><literal>put</literal>
+</para></entry><entry><para>Utopia
+</para></entry></row><row><entry><para><literal>pzc</literal>
+</para></entry><entry><para>Zapf Chancery
+</para></entry></row></tbody></tgroup></informaltable>
+
</listitem></varlistentry><varlistentry><term><literal>\fontseries{<replaceable>series</replaceable>}</literal>
</term><listitem><indexterm role="fn"><primary>\fontseries</primary></indexterm>
<indexterm role="cp"><primary>series, of fonts</primary></indexterm>
@@ -1510,39 +1671,64 @@ examples of some common families:
<firstterm>width</firstterm>. Typically, a font supports only a few of the possible
combinations. Some common combined series values include:
</para>
-<itemizedlist><listitem><para><!-- /@w --> <literal>m</literal><literal>&#160;</literal> Medium (normal)
-</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal>&#160;</literal> Bold
-</para></listitem><listitem><para><!-- /@w --> <literal>c</literal><literal>&#160;</literal> Condensed
-</para></listitem><listitem><para><!-- /@w --> <literal>bc</literal> Bold condensed
-</para></listitem><listitem><para><!-- /@w --> <literal>bx</literal> Bold extended
-</para></listitem></itemizedlist>
+<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="17*"></colspec><tbody><row><entry><para><literal>m</literal>
+</para></entry><entry><para>Medium (normal)
+</para></entry></row><row><entry><para><literal>b</literal>
+</para></entry><entry><para>Bold
+</para></entry></row><row><entry><para><literal>c</literal>
+</para></entry><entry><para>Condensed
+</para></entry></row><row><entry><para><literal>bc</literal>
+</para></entry><entry><para>Bold condensed
+</para></entry></row><row><entry><para><literal>bx</literal>
+</para></entry><entry><para>Bold extended
+</para></entry></row></tbody></tgroup></informaltable>
<indexterm role="cp"><primary>weights, of fonts</primary></indexterm>
<para>The possible values for weight, individually, are:
</para>
-<itemizedlist><listitem><para><!-- /@w --> <literal>ul</literal> Ultra light
-</para></listitem><listitem><para><!-- /@w --> <literal>el</literal> Extra light
-</para></listitem><listitem><para><!-- /@w --> <literal>l</literal><literal>&#160;</literal> Light
-</para></listitem><listitem><para><!-- /@w --> <literal>sl</literal> Semi light
-</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal>&#160;</literal> Medium (normal)
-</para></listitem><listitem><para><!-- /@w --> <literal>sb</literal> Semi bold
-</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal>&#160;</literal> Bold
-</para></listitem><listitem><para><!-- /@w --> <literal>eb</literal> Extra bold
-</para></listitem><listitem><para><!-- /@w --> <literal>ub</literal> Ultra bold
-</para></listitem></itemizedlist>
+<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="18*"></colspec><tbody><row><entry><para><literal>ul</literal>
+</para></entry><entry><para>Ultra light
+</para></entry></row><row><entry><para><literal>el</literal>
+</para></entry><entry><para>Extra light
+</para></entry></row><row><entry><para><literal>l</literal>
+</para></entry><entry><para>Light
+</para></entry></row><row><entry><para><literal>sl</literal>
+</para></entry><entry><para>Semi light
+</para></entry></row><row><entry><para><literal>m</literal>
+</para></entry><entry><para>Medium (normal)
+</para></entry></row><row><entry><para><literal>sb</literal>
+</para></entry><entry><para>Semi bold
+</para></entry></row><row><entry><para><literal>b</literal>
+</para></entry><entry><para>Bold
+</para></entry></row><row><entry><para><literal>eb</literal>
+</para></entry><entry><para>Extra bold
+</para></entry></row><row><entry><para><literal>ub</literal>
+</para></entry><entry><para>Ultra bold
+</para></entry></row></tbody></tgroup></informaltable>
<indexterm role="cp"><primary>widths, of fonts</primary></indexterm>
-<para>The possible values for width, individually, are (the percentages
-are just guides and are not followed precisely by all fonts):
-</para>
-<itemizedlist><listitem><para><!-- /@w --> <literal>uc</literal> Ultra condensed, 50%
-</para></listitem><listitem><para><!-- /@w --> <literal>ec</literal> Extra condensed, 62.5%
-</para></listitem><listitem><para><!-- /@w --> <literal>c</literal><literal>&#160;</literal> Condensed, 75%
-</para></listitem><listitem><para><!-- /@w --> <literal>sc</literal> Semi condensed, 87.5%
-</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal>&#160;</literal> Medium, 100%
-</para></listitem><listitem><para><!-- /@w --> <literal>sx</literal> Semi expanded, 112.5%
-</para></listitem><listitem><para><!-- /@w --> <literal>x</literal><literal>&#160;</literal> Expanded, 125%
-</para></listitem><listitem><para><!-- /@w --> <literal>ex</literal> Extra expanded, 150%
-</para></listitem><listitem><para><!-- /@w --> <literal>ux</literal> Ultra expanded, 200%
-</para></listitem></itemizedlist>
+<para>The possible values for width, individually, are (the meaning and
+relationship of these terms varies with individual typefaces):
+</para>
+
+<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="15*"></colspec><tbody><row><entry><para><literal>uc</literal>
+</para></entry><entry><para>Ultra condensed
+</para></entry></row><row><entry><para><literal>ec</literal>
+</para></entry><entry><para>Extra condensed
+</para></entry></row><row><entry><para><literal>c</literal>
+</para></entry><entry><para>Condensed
+</para></entry></row><row><entry><para><literal>sc</literal>
+</para></entry><entry><para>Semi condensed
+</para></entry></row><row><entry><para><literal>m</literal>
+</para></entry><entry><para>Medium
+</para></entry></row><row><entry><para><literal>sx</literal>
+</para></entry><entry><para>Semi expanded
+</para></entry></row><row><entry><para><literal>x</literal>
+</para></entry><entry><para>Expanded
+</para></entry></row><row><entry><para><literal>ex</literal>
+</para></entry><entry><para>Extra expanded
+</para></entry></row><row><entry><para><literal>ux</literal>
+</para></entry><entry><para>Ultra expanded
+</para></entry></row></tbody></tgroup></informaltable>
+
<para>When forming the <replaceable>series</replaceable> string from the weight and width, drop the
<literal>m</literal> that stands for medium weight or medium width, unless both
weight and width are <literal>m</literal>, in which case use just one
@@ -1553,13 +1739,20 @@ weight and width are <literal>m</literal>, in which case use just one
<indexterm role="cp"><primary>shapes, of fonts</primary></indexterm>
<para>Select font shape. Valid shapes are:
</para>
-<itemizedlist><listitem><para><!-- /@w --> <literal>n</literal><literal>&#160;</literal> Upright (normal)
-</para></listitem><listitem><para><!-- /@w --> <literal>it</literal> Italic
-</para></listitem><listitem><para><!-- /@w --> <literal>sl</literal> Slanted (oblique)
-</para></listitem><listitem><para><!-- /@w --> <literal>sc</literal> Small caps
-</para></listitem><listitem><para><!-- /@w --> <literal>ui</literal> Upright italics
-</para></listitem><listitem><para><!-- /@w --> <literal>ol</literal> Outline
-</para></listitem></itemizedlist>
+<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="19*"></colspec><tbody><row><entry><para><literal>n</literal>
+</para></entry><entry><para>Upright (normal)
+</para></entry></row><row><entry><para><literal>it</literal>
+</para></entry><entry><para>Italic
+</para></entry></row><row><entry><para><literal>sl</literal>
+</para></entry><entry><para>Slanted (oblique)
+</para></entry></row><row><entry><para><literal>sc</literal>
+</para></entry><entry><para>Small caps
+</para></entry></row><row><entry><para><literal>ui</literal>
+</para></entry><entry><para>Upright italics
+</para></entry></row><row><entry><para><literal>ol</literal>
+</para></entry><entry><para>Outline
+</para></entry></row></tbody></tgroup></informaltable>
+
<para>The two last shapes are not available for most font families, and
small caps are often missing as well.
</para>
@@ -1580,11 +1773,13 @@ reset every time a size change happens; see <literal>\baselinestretch</literal>,
<para>&latex; multiplies the line spacing by the value of the
<literal>\baselinestretch</literal> parameter; the default factor is 1. A change
takes effect when <literal>\selectfont</literal> (see below) is called. You can
-make line skip changes happen for the entire document by doing
-<literal>\renewcommand{\baselinestretch}{2.0}</literal> in the preamble.
+make a line skip change happen for the entire document, for instance
+doubling it, by doing <literal>\renewcommand{\baselinestretch}{2.0}</literal> in
+the preamble.
</para>
<indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm>
+
<indexterm role="cp"><primary>double spacing</primary></indexterm>
<para>However, the best way to double-space a document is to use the
<filename>setspace</filename> package. In addition to offering a number of spacing
@@ -2024,6 +2219,7 @@ automatically added.
<indexterm role="cp"><primary>here, putting floats</primary></indexterm>
<indexterm role="cp"><primary>package, <literal>float</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>float</literal> package</primary></indexterm>
+
<para>To absolutely force a float to appear &#8220;here&#8221;, you can
<literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it
defines. For further discussion, see the FAQ entry at
@@ -2057,6 +2253,9 @@ use the <filename>afterpage</filename> package and issue
<literal>\afterpage{\clearpage}</literal>. This will wait until the current page
is finished and then flush all outstanding floats.
</para>
+<indexterm role="cp"><primary>package, <literal>flafter</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>flafter</literal> package</primary></indexterm>
+
<para>&latex; can typeset a float before where it appears in the source
(although on the same output page) if there is a <literal>t</literal> specifier in
the <replaceable>placement</replaceable> parameter. If this is not desired, and deleting
@@ -2197,15 +2396,229 @@ command is something like
</screen>
<indexterm role="fn"><primary>secnumdepth counter</primary></indexterm>
<indexterm role="cp"><primary>section numbers, printing</primary></indexterm>
-<para>The <literal>secnumdepth</literal> counter controls printing of section numbers.
+<anchor id="Sectioning_002fsecnumdepth"/><para>The <literal>secnumdepth</literal> counter controls printing of section numbers.
The setting
</para>
<screen>\setcounter{secnumdepth}{<replaceable>level</replaceable>}
</screen>
<para>suppresses heading numbers at any depth <inlineequation><mathphrase>&gt; <replaceable>level</replaceable></mathphrase></inlineequation>, where
-<literal>chapter</literal> is level zero. (See <link linkend="_005csetcounter">\setcounter</link>.)
+<literal>chapter</literal> is level zero. The default <literal>secnumdepth</literal> is 3 in
+&latex;&#8217;s <filename>article</filename> class and 2 in the <filename>book</filename> and
+<filename>report</filename> classes. (See <link linkend="_005csetcounter">\setcounter</link>.)
+</para>
+
+
+<sect1 label="6.1" id="_005c_0040startsection">
+<title><literal>\@startsection</literal></title>
+
+<indexterm role="fn"><primary>\@startsection</primary></indexterm>
+<indexterm role="cp"><primary>section, redefining</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>}
+</screen>
+<para>Used to help redefine the behavior of commands that start sectioning
+divisions such as <literal>\section</literal> or <literal>\subsection</literal>.
+</para>
+<para>Note that the <filename>titlesec</filename> package makes manipulation of sectioning
+easier. Further, while most requirements for sectioning commands can be
+satisfied with <literal>\@startsection</literal>, some cannot. For instance, in
+the standard &latex; <literal>book</literal> and <literal>report</literal> classes the commands
+<literal>\chapter</literal> and <literal>\report</literal> are not constructed in this way. To
+make such a command you may want to use the <literal>\secdef</literal> command.
+<!-- xx define, and make a cross reference to, secdef. -->
+</para>
+<para>Technically, <literal>\@startsection</literal> has the form
+</para><screen>\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>}*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}
+</screen><para>(the star&#160;<literal>*</literal> is optional), so that issuing
+</para><screen>\renewcommand{\section}{\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>}}
+</screen><para>redefines <literal>\section</literal> to have the form
+<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (here too, the
+star&#160;<literal>*</literal> is optional). See <link linkend="Sectioning">Sectioning</link>. This implies that
+when you write a command like <literal>\renewcommand{section}{...}</literal>,
+the <literal>\@startsection{...}</literal> must come last in the definition. See
+the examples below.
+</para>
+<variablelist>
+<varlistentry><term><replaceable>name</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002fname"/><para>Name of the counter used to number the
+sectioning header. This counter must be defined separately. Most
+commonly this is either <literal>section</literal>, <literal>subsection</literal>, or
+<literal>paragraph</literal>. Although in those three cases the counter name is the
+same as the sectioning command itself, using the same name is not
+required.
+</para>
+<para>Then <literal>\the</literal><replaceable>name</replaceable> displays the title number and
+<literal>\</literal><replaceable>name</replaceable><literal>mark</literal> is for the page headers. See the third
+example below.
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>level</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002flevel"/><para>An integer giving the depth of the
+sectioning command: 0 for <literal>chapter</literal> (only applies to the standard
+<literal>book</literal> and <literal>report</literal> classes), 1 for <literal>section</literal>, 2 for
+<literal>subsection</literal>, 3 for <literal>subsubsection</literal>, 4 for <literal>paragraph</literal>,
+and 5 for <literal>subparagraph</literal>. In the <literal>book</literal> and <literal>report</literal>
+classes <literal>part</literal> has level -1, while in the <literal>article</literal> class
+<literal>part</literal> has level 0.
+</para>
+<para>If <replaceable>level</replaceable> is less than or equal to the value of <literal>secnumdepth</literal>
+then the titles for this sectioning command will be numbered. For
+instance, in an <literal>article</literal>, if <literal>secnumdepth</literal> is 1 then a
+<literal>\section{Introduction}</literal> command will produce output like &#8220;1
+Introduction&#8221; while <literal>\subsection{Discussion}</literal> will produce
+output like &#8220;Discussion&#8221;, without the number prefix.
+See <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link>.
+</para>
+<para>If <replaceable>level</replaceable> is less than or equal to the value of <replaceable>tocdepth</replaceable> then
+the table of contents will have an entry for this sectioning unit.
+For instance, in an <literal>article</literal>, if <replaceable>tocdepth</replaceable> is 1 then the table of
+contents will list sections but not subsections.
+<!-- xx add, and cross reference to, tocdepth -->
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>indent</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002findent"/><para>A length giving the indentation of all
+of the title lines with respect to the left margin. To have the title
+flush with the margin use <literal>0pt</literal>. A negative indentation such as
+<literal>-\parindent</literal> will move the title into the left margin.
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>beforeskip</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002fbeforeskip"/><para>The absolute value of this length is
+the amount of vertical space that is inserted before this sectioning
+unit&#8217;s title. This space will be discarded if the sectioning unit
+happens to start at the top of a fresh page. If this number is negative
+then the first paragraph following the header is not indented, if it is
+non-negative then the first paragraph is indented. (Note that the
+negative of <literal>1pt plus 2pt minus 3pt</literal> is <literal>-1pt plus -2pt minus
+-3pt</literal>.)
+</para>
+<para>For example, if <replaceable>beforeskip</replaceable> is <literal>-3.5ex plus -1ex minus -0.2ex</literal>
+then to start the new sectioning unit, &latex; will add about 3.5 times
+the height of a letter x in vertical space, and the first paragraph in
+the section will not be indented. Using a rubber length, with
+<literal>plus</literal> and <literal>minus</literal>, is good practice here since it gives
+&latex; more flexibility in making up the page (see <link linkend="Lengths">Lengths</link>).
+</para>
+<para>The full accounting of the vertical space between the baseline of the
+line prior to this sectioning unit&#8217;s header and the baseline of the
+header is that it is the sum of the <literal>\parskip</literal> of the text font,
+the <literal>\baselineskip</literal> of the title font, and the absolute value of
+the <replaceable>beforeskip</replaceable>. This space is typically rubber so it may stretch
+or shrink. (If the sectioning unit starts on a fresh page so that the
+vertical space is discarded then the baseline of the header text will be
+where &latex; would put the baseline of the first text line on that
+page.)
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>afterskip</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002fafterskip"/><para>This is a length. If <replaceable>afterskip</replaceable>
+is non-negative then this is the vertical space inserted after the
+sectioning unit&#8217;s title header. If it is negative then the title header
+becomes a run-in header, so that it becomes part of the next paragraph.
+In this case the absolute value of the length gives the horizontal space
+between the end of the title and the beginning of the following
+paragraph. (Note that the negative of <literal>1pt plus 2pt minus 3pt</literal> is
+<literal>-1pt plus -2pt minus -3pt</literal>.)
+</para>
+<para>As with <replaceable>beforeskip</replaceable>, using a rubber length, with <literal>plus</literal> and
+<literal>minus</literal> components, is good practice here since it gives &latex;
+more flexibility in putting together the page.
+</para>
+<para>If <literal>afterskip</literal> is non-negative then the full accounting of the
+vertical space between the baseline of the sectioning unit&#8217;s header and
+the baseline of the first line of the following paragraph is that it is
+the sum of the <literal>\parskip</literal> of the title font, the
+<literal>\baselineskip</literal> of the text font, and the value of <replaceable>after</replaceable>.
+That space is typically rubber so it may stretch or shrink. (Note that
+because the sign of <literal>afterskip</literal> changes the sectioning unit
+header&#8217;s from standalone to run-in, you cannot use a negative
+<literal>afterskip</literal> to cancel part of the <literal>\parskip</literal>.)
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>style</replaceable>
+</term><listitem><anchor id="_005c_0040startsection_002fstyle"/><para>Controls the styling of the title. See
+the examples below. Typical commands to use here are <literal>\centering</literal>,
+<literal>\raggedright</literal>, <literal>\normalfont</literal>, <literal>\hrule</literal>, or
+<literal>\newpage</literal>. The last command in <replaceable>style</replaceable> may be one such as
+<literal>\MakeUppercase</literal> or <literal>\fbox</literal> that takes one argument. The
+section title will be supplied as the argument to this command. For
+instance, setting <replaceable>style</replaceable> to <literal>\bfseries\MakeUppercase</literal> would
+produce titles that are bold and upper case.
+</para></listitem></varlistentry></variablelist>
+<para>These are &latex;&#8217;s defaults for the first three sectioning units that
+are defined with <literal>\@startsection</literal>, for the <filename>article</filename>,
+<filename>book</filename>, and <filename>report</filename> classes.
+</para>
+<informaltable><tgroup cols="4"><colspec colwidth="10*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><thead><row><entry></entry><entry><para><literal>section</literal> </para></entry><entry><para><literal>subsection</literal> </para></entry><entry><para><literal>subsubsection</literal>
+</para></entry></row></thead><tbody><row><entry><para><link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link>
+</para></entry><entry><para>section </para></entry><entry><para>subsection </para></entry><entry><para>subsubsection
+</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link>
+</para></entry><entry><para>1 </para></entry><entry><para>2 </para></entry><entry><para>3
+</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link>
+</para></entry><entry><para><literal>0pt</literal> </para></entry><entry><para><literal>0pt</literal> </para></entry><entry><para><literal>0pt</literal>
+</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link>
+</para></entry><entry><para><literal>-3.5ex plus -1ex minus -0.2ex</literal>
+</para></entry><entry><para><literal>-3.25ex plus -1ex minus -0.2ex</literal>
+</para></entry><entry><para><literal>-3.25ex plus -1ex minus -0.2ex</literal>
+</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link>
+</para></entry><entry><para><literal>2.3ex plus 0.2ex</literal>
+</para></entry><entry><para><literal>1.5ex plus 0.2ex</literal>
+</para></entry><entry><para><literal>1.5ex plus 0.2ex</literal>
+</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link>
+</para></entry><entry><para><literal>\normalfont\Large\bfseries</literal>
+</para></entry><entry><para><literal>\normalfont\large\bfseries</literal>
+</para></entry><entry><para><literal>\normalfont\normalsize\bfseries</literal>
+</para></entry></row></tbody></tgroup></informaltable>
+<para>Here are examples. They go either in a package or class file or in the
+preamble of a &latex; document. If you put them in the preamble they
+must go between a <literal>\makeatletter</literal> command and a
+<literal>\makeatother</literal>. (Probably the error message <literal>You can't use
+`\spacefactor' in vertical mode.</literal> means that you forgot this.)
+See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>.
+</para>
+<para>This will put section titles in large boldface type, centered. It says
+<literal>\renewcommand</literal> because &latex;&#8217;s standard classes have already
+defined a <literal>\section</literal>. For the same reason it does not define a
+<literal>section</literal> counter, or the commands <literal>\thesection</literal> and
+<literal>\l@section</literal>.
+</para>
+<screen>\renewcommand\section{%
+ \@startsection{section}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link>
+ {1}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link>
+ {0pt}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link>
+ {-3.5ex plus -1ex minus -.2ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link>
+ {2.3ex plus.2ex}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link>
+ {\centering\normalfont\Large\bfseries}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link>
+ }
+</screen>
+<para>This will put <literal>subsection</literal> titles in small caps type, inline with the paragraph.
</para>
+<screen>\renewcommand\subsection{%
+ \@startsection{subsection}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link>
+ {2}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link>
+ {0em}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link>
+ {-1ex plus 0.1ex minus -0.05ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link>
+ {-1em plus 0.2em}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link>
+ {\scshape}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link>
+ }
+</screen>
+<para>The prior examples redefined existing sectional unit title commands. This defines a new one, illustrating the needed counter and macros to display that counter.
+</para>
+<!-- From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ -->
+<screen>\setcounter{secnumdepth}{6}% show counters this far down
+\newcounter{subsubparagraph}[subparagraph]% counter for numbering
+\renewcommand{\thesubsubparagraph}% how to display
+ {\thesubparagraph.\@arabic\c@subsubparagraph}% numbering
+\newcommand{\subsubparagraph}{\@startsection
+ {subsubparagraph}%
+ {6}%
+ {0em}%
+ {\baselineskip}%
+ {0.5\baselineskip}%
+ {\normalfont\normalsize}}
+\newcommand*\l@subsubparagraph{\@dottedtocline{6}{10em}{5em}}% for toc
+\newcommand{\subsubparagraphmark}[1]{}% for page headers
+</screen>
+</sect1>
</chapter>
<chapter label="7" id="Cross-references">
<title>Cross references</title>
@@ -2395,6 +2808,7 @@ the end. For instance, the input
<indexterm role="fn"><primary>environment, <literal>abstract</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>abstract</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>abstracts</primary></indexterm>
<para>Synopsis:
@@ -2448,6 +2862,7 @@ a more flexible solution, use the package <filename>abstract</filename>).
<indexterm role="fn"><primary>environment, <literal>array</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>array</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>arrays, math</primary></indexterm>
<para>Synopsis:
@@ -2487,6 +2902,9 @@ by
<literal>\arraycolsep</literal>, which gives half the width between columns. The
default for this is &#8216;<literal>5pt</literal>&#8217;.
</para>
+<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm>
+
<para>To obtain arrays with braces the standard is to use the <filename>amsmath</filename>
package. It comes with environments <literal>pmatrix</literal> for an array
surrounded by parentheses&#160;<literal>(...)</literal>, <literal>bmatrix</literal> for an array
@@ -2522,6 +2940,7 @@ preamble:
<indexterm role="fn"><primary>environment, <literal>center</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>center</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>centering text, environment for</primary></indexterm>
<para>Synopsis:
@@ -2611,48 +3030,64 @@ centered.
<indexterm role="fn"><primary>environment, <literal>description</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>description</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>labelled lists, creating</primary></indexterm>
<indexterm role="cp"><primary>description lists, creating</primary></indexterm>
<para>Synopsis:
</para>
<screen>\begin{description}
-\item [<replaceable>first label</replaceable>] text of first item
-\item [<replaceable>second label</replaceable>] text of second item
+\item[<replaceable>label of first item</replaceable>] text of first item
+\item[<replaceable>label of second item</replaceable>] text of second item
...
\end{description}
</screen>
-<para>Environment to make a labelled list of items. Each item&#8217;s <replaceable>label</replaceable>
-is typeset in bold, flush-left. Each item&#8217;s text may contain multiple
-paragraphs. Although the labels on the items are optional there is no
-sensible default, so all items should have labels.
+<para>Environment to make a labeled list of items. Each item&#8217;s <replaceable>label</replaceable> is
+typeset in bold, and is flush left so that long labels continue into the
+first line of the item text. There must be at least one item; having
+none causes the &latex; error &#8216;<literal>Something's wrong--perhaps a
+missing \item</literal>&#8217;.
</para>
+<para>This example shows the environment used for a sequence of definitions.
+The labels &#8216;<literal>lama</literal>&#8217; and &#8216;<literal>llama</literal>&#8217; come out in boldface with their
+left edges aligned on the left margin.
+</para>
+<screen>\begin{definition}
+ \item[lama] A priest.
+ \item[llama] A beast.
+\end{definition}
+</screen>
<indexterm role="fn"><primary>\item</primary></indexterm>
-<para>The list consists of at least one item, created with the <literal>\item</literal>
-command (see <link linkend="_005citem">\item</link>). Having no items causes the &latex; error
-&#8216;<literal>Something's wrong--perhaps a missing \item</literal>&#8217;).
+<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). Use the
+optional labels, as in <literal>\item[Main point]</literal>, because there is
+no sensible default. Following the <literal>\item</literal> is optional text, which
+may contain multiple paragraphs.
</para>
<indexterm role="cp"><primary>bold typewriter, avoiding</primary></indexterm>
<indexterm role="cp"><primary>typewriter labels in lists</primary></indexterm>
<para>Since the labels are in bold style, if the label text calls for a font
-change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will
-come out bold. For instance, if the label text calls for typewriter
-with <literal>\item[\texttt{label text}]</literal> then it will appear in bold
+change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will come
+out bold. For instance, if the label text calls for typewriter with
+<literal>\item[\texttt{label text}]</literal> then it will appear in bold
typewriter, if that is available. The simplest way to get non-bold
typewriter is to use declarative style: <literal>\item[{\tt label
-text}]</literal>. Similarly, to get the standard roman font, use
-<literal>\item[{\rm label text}]</literal>.
+text}]</literal>. Similarly, get the standard roman font with <literal>\item[{\rm
+label text}]</literal>.
</para>
<para>For other major &latex; labelled list environments, see <link linkend="itemize">itemize</link>
-and <link linkend="enumerate">enumerate</link>. For information about customizing list layout, see
-<link linkend="list">list</link>; also, the package <filename>enumitem</filename> is useful for this.
+and <link linkend="enumerate">enumerate</link>. Unlike those environments, nesting
+<literal>description</literal> environments does not change the default label; it is
+boldface and flush left at all levels.
</para>
-<para>This example shows the environment used for a sequence of definitions.
+<para>For information about list layout parameters, including the default
+values, and for information about customizing list layout, see
+<link linkend="list">list</link>. The package <filename>enumitem</filename> is useful for customizing
+lists.
</para>
-<screen>\begin{definition}
- \item[lama] A priest.
- \item[llama] A beast.
-\end{definition}
+<para>This example changes the description labels to small caps.
+</para>
+<screen>\renewcommand{\descriptionlabel}[1]{%
+ {\hspace{\labelsep}\textsc{#1}}}
</screen>
</sect1>
@@ -2662,40 +3097,43 @@ and <link linkend="enumerate">enumerate</link>. For information about customizi
<indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm>
+
<para>Synopsis:
</para>
<screen>\begin{displaymath}
- ... math text ...
+<replaceable>math text</replaceable>
\end{displaymath}
</screen>
<para>Environment to typeset the math text on its own line, in display style
and centered. To make the text be flush-left use the global option
<literal>fleqn</literal>; see <link linkend="Document-class-options">Document class options</link>.
</para>
-<para>&latex; will not break the math text across lines.
-</para>
<para>In the <literal>displaymath</literal> environment no equation number is added to the
math text. One way to get an equation number is to use the
<literal>equation</literal> environment (see <link linkend="equation">equation</link>).
</para>
-<para>Note that the <filename>amsmath</filename> package has extensive displayed equation
-facilities. Those facilities are the best approach for such output in
-new documents. For example, there are a number of options in that
-package for having math text broken across lines.
+<para>&latex; will not break the <replaceable>math text</replaceable> across lines.
+</para>
+<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm>
+
+<para>Note that the <filename>amsmath</filename> 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.
</para>
-<para>The construct <literal>\[..math text..\]</literal> is essentially a synonym for
-<literal>\begin{displaymath}..math text..\end{displaymath}</literal> but the
+<para>The construct <literal>\[<replaceable>math text</replaceable>\]</literal> is essentially a synonym for
+<literal>\begin{displaymath}<replaceable>math text</replaceable>\end{displaymath}</literal> but the
latter is easier to work with in the source file; for instance,
searching for a square bracket may get false positives but the word
-<literal>displaymath</literal> will likely be unique. (The construct <literal>$$..math
-text..$$</literal> from Plain&#160;&tex; is sometimes mistakenly used as a
-synonym for <literal>displaymath</literal>. It is not a synonym, because the
-<literal>displaymath</literal> environment checks that it isn&#8217;t started in math mode
-and that it ends in math mode begun by the matching environment start,
-because the <literal>displaymath</literal> environment has different vertical
-spacing, and because the <literal>displaymath</literal> environment honors the
-<literal>fleqn</literal> option.)
+<literal>displaymath</literal> will likely be unique. (The construct
+<literal>$$<replaceable>math text</replaceable>$$</literal> from Plain&#160;&tex; is sometimes
+mistakenly used as a synonym for <literal>displaymath</literal>. It is not a
+synonym, because the <literal>displaymath</literal> environment checks that it isn&#8217;t
+started in math mode and that it ends in math mode begun by the matching
+environment start, because the <literal>displaymath</literal> environment has
+different vertical spacing, and because the <literal>displaymath</literal>
+environment honors the <literal>fleqn</literal> option.)
</para>
<para>The output from this example is centered and alone on its line.
</para><screen>\begin{displaymath}
@@ -2711,13 +3149,15 @@ spacing, and because the <literal>displaymath</literal> environment honors the
<indexterm role="fn"><primary>environment, <literal>document</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>document</literal> environment</primary></indexterm>
+
<para>The <literal>document</literal> environment encloses the entire body of a document.
It is required in every &latex; document. See <link linkend="Starting-and-ending">Starting and ending</link>.
</para>
-<anchor id="_005cAtBeginDocument"/>
+<sect2 label="8.6.1" id="_005cAtBeginDocument">
+<title><literal>\AtBeginDocument</literal></title>
<indexterm role="fn"><primary>\AtBeginDocument</primary></indexterm>
<indexterm role="cp"><primary>beginning of document hook</primary></indexterm>
@@ -2736,7 +3176,9 @@ the preamble so you cannot do any typesetting with it.
will be executed in the order that you gave them.
</para>
-<anchor id="_005cAtEndDocument"/>
+</sect2>
+<sect2 label="8.6.2" id="_005cAtEndDocument">
+<title><literal>\AtEndDocument</literal></title>
<indexterm role="fn"><primary>\AtEndDocument</primary></indexterm>
<indexterm role="cp"><primary>end of document hook</primary></indexterm>
@@ -2756,44 +3198,54 @@ appropriate point in <replaceable>code</replaceable>.
will be executed in the order that you gave them.
</para>
+</sect2>
</sect1>
<sect1 label="8.7" id="enumerate">
<title><literal>enumerate</literal></title>
<indexterm role="fn"><primary>environment, <literal>enumerate</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>enumerate</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>lists of items, numbered</primary></indexterm>
<para>Synopsis:
</para>
<screen>\begin{enumerate}
-\item [<replaceable>first label</replaceable>] text of first item
-\item [<replaceable>second label</replaceable>] text of second item
+\item[<replaceable>optional label of first item</replaceable>] text of first item
+\item[<replaceable>optional label of second item</replaceable>] text of second item
...
\end{enumerate}
</screen>
<para>Environment to produce a numbered list of items. The format of the
-label numbering depends on whether this environment is nested within
-another; see below.
-</para>
-<indexterm role="fn"><primary>\item</primary></indexterm>
-<para>The list consists of at least one item. Having no items causes the
-&latex; error &#8216;<literal>Something's wrong--perhaps a missing \item</literal>&#8217;. Each
-item is produced with an <literal>\item</literal> command.
+label numbering depends on the nesting level of this environment; see
+below. The default top-level numbering is &#8216;<literal>1.</literal>&#8217;, &#8216;<literal>2.</literal>&#8217;,
+etc. Each <literal>enumerate</literal> list environment must have at least one item;
+having none causes the &latex; error &#8216;<literal>Something's wrong--perhaps a
+missing \item</literal>&#8217;.
</para>
-<para>This example lists the top two finishers in the 1908 Olympic marathon.
+<para>This example gives the first two finishers in the 1908 Olympic marathon.
+As a top-level list the labels would come out as &#8216;<literal>1.</literal>&#8217; and
+&#8216;<literal>2.</literal>&#8217;.
</para>
<screen>\begin{enumerate}
\item Johnny Hayes (USA)
\item Charles Hefferon (RSA)
\end{enumerate}
</screen>
-<para>Enumerations may be nested within a paragraph-making environment,
-including <literal>itemize</literal> (see <link linkend="itemize">itemize</link>), <literal>description</literal>
-(see <link linkend="description">description</link>) and <literal>enumeration</literal>, up to four levels deep.
-The format of the label produced depends on the place in the nesting.
-This gives &latex;&#8217;s default for the format at each nesting level
-(where 1 is the outermost level):
+<indexterm role="fn"><primary>\item</primary></indexterm>
+<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you
+give <literal>\item</literal> an optional argument by following it with square
+brackets, as in <literal>\item[Interstitial label]</literal>, then the next item
+will continue the interrupted sequence (see <link linkend="_005citem">\item</link>). That is, you
+will get labels like &#8216;<literal>1.</literal>&#8217;, then &#8216;<literal>Interstitial label</literal>&#8217;, then
+&#8216;<literal>2.</literal>&#8217;. Following the <literal>\item</literal> is optional text, which may
+contain multiple paragraphs.
+</para>
+<para>Enumerations may be nested within other <literal>enumerate</literal> environments,
+or within any paragraph-making environment such as <literal>itemize</literal>
+(see <link linkend="itemize">itemize</link>), up to four levels deep. This gives &latex;&#8217;s
+default for the format at each nesting level, where 1 is the top level,
+the outermost level.
</para>
<orderedlist numeration="arabic"><listitem><para>arabic number followed by a period: &#8216;<literal>1.</literal>&#8217;, &#8216;<literal>2.</literal>&#8217;,&#160;&#8230;
</para></listitem><listitem><para>lower case letter inside parentheses: &#8216;<literal>(a)</literal>&#8217;, &#8216;<literal>(b)</literal>&#8217;&#160;&#8230;
@@ -2805,9 +3257,13 @@ This gives &latex;&#8217;s default for the format at each nesting level
<indexterm role="fn"><primary>\enumiii</primary></indexterm>
<indexterm role="fn"><primary>\enumiv</primary></indexterm>
<para>The <literal>enumerate</literal> environment uses the counters <literal>\enumi</literal> through
-<literal>\enumiv</literal> counters (see <link linkend="Counters">Counters</link>). If you use the optional
-argument to <literal>\item</literal> then the counter is not incremented for that
-item (see <link linkend="_005citem">\item</link>).
+<literal>\enumiv</literal> (see <link linkend="Counters">Counters</link>).
+</para>
+<para>For other major &latex; labeled list environments, see
+<link linkend="description">description</link> and <link linkend="itemize">itemize</link>. For information about list layout
+parameters, including the default values, and for information about
+customizing list layout, see <link linkend="list">list</link>. The package <filename>enumitem</filename> is
+useful for customizing lists.
</para>
<indexterm role="fn"><primary>\labelenumi</primary></indexterm>
<indexterm role="fn"><primary>\labelenumii</primary></indexterm>
@@ -2817,30 +3273,26 @@ item (see <link linkend="_005citem">\item</link>).
(see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>) on the commands <literal>\labelenumi</literal>
through <literal>\labelenumiv</literal>. For instance, this first level list will be
labelled with uppercase letters, in boldface, and without a trailing
-period:
+period.
</para>
<indexterm role="fn"><primary>\Alph example</primary></indexterm>
<screen>\renewcommand{\labelenumi}{\textbf{\Alph{enumi}}}
\begin{enumerate}
- \item eI
- \item bi:
- \item si:
+ \item Shows as boldface A
+ \item Shows as boldface B
\end{enumerate}
</screen>
-<para>For a list of counter-labelling commands like <literal>\Alph</literal> see
-<link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>.
-</para>
-<para>For more on customizing the layout see <link linkend="list">list</link>. Also, the package
-<filename>enumitem</filename> is useful for this.
+<para>For a list of counter-labeling commands see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic
+\roman \Roman \fnsymbol</link>.
</para>
-
</sect1>
<sect1 label="8.8" id="eqnarray">
<title><literal>eqnarray</literal></title>
<indexterm role="fn"><primary>environment, <literal>eqnarray</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>eqnarray</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>equations, aligning</primary></indexterm>
<indexterm role="cp"><primary>aligning equations</primary></indexterm>
@@ -2911,6 +3363,7 @@ while the third line has not entry on the left side.
<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>equations, environment for</primary></indexterm>
<indexterm role="cp"><primary>formulas, environment for</primary></indexterm>
@@ -2925,6 +3378,10 @@ equation number in the right margin.
</para>
<para>The equation number is generated using the <literal>equation</literal> counter.
</para>
+<para>You should have no blank lines between <literal>\begin{equation}</literal> and
+<literal>\begin{equation}</literal>, or &latex; will tell you that there is a
+missing dollar sign,&#160;$<literal>$</literal>.
+</para>
<para>Note that the <filename>amsmath</filename> package has extensive displayed equation
facilities. Those facilities are the best approach for such output in
new documents.
@@ -2936,6 +3393,7 @@ new documents.
<indexterm role="fn"><primary>environment, <literal>figure</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>figure</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>inserting figures</primary></indexterm>
<indexterm role="cp"><primary>figures, inserting</primary></indexterm>
@@ -2998,8 +3456,10 @@ end of the document, on a page of floats.
<indexterm role="fn"><primary>environment, <literal>filecontents</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>filecontents</literal> environment</primary></indexterm>
+
<indexterm role="fn"><primary>environment, <literal>filecontents*</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>filecontents*</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>external files, writing</primary></indexterm>
<indexterm role="cp"><primary>writing external files</primary></indexterm>
@@ -3058,6 +3518,7 @@ Article by \myname.
<indexterm role="fn"><primary>environment, <literal>flushleft</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>flushleft</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>left-justifying text, environment for</primary></indexterm>
<indexterm role="cp"><primary>ragged right text, environment for</primary></indexterm>
@@ -3100,6 +3561,7 @@ command that ends the paragraph unit.
<indexterm role="fn"><primary>environment, <literal>flushright</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>flushright</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>ragged left text, environment for</primary></indexterm>
<indexterm role="cp"><primary>right-justifying text, environment for</primary></indexterm>
@@ -3142,6 +3604,7 @@ command that ends the paragraph unit.
<indexterm role="fn"><primary>environment, <literal>itemize</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>itemize</literal> environment</primary></indexterm>
+
<indexterm role="fn"><primary>\item</primary></indexterm>
<indexterm role="cp"><primary>lists of items</primary></indexterm>
<indexterm role="cp"><primary>unordered lists</primary></indexterm>
@@ -3150,34 +3613,53 @@ command that ends the paragraph unit.
<para>Synopsis:
</para>
<screen>\begin{itemize}
-\item <replaceable>item1</replaceable>
-\item <replaceable>item2</replaceable>
+\item[<replaceable>optional label of first item</replaceable>] text of first item
+\item[<replaceable>optional label of second item</replaceable>] text of second item
...
\end{itemize}
</screen>
<para>The <literal>itemize</literal> environment produces an &#8220;unordered&#8221;, &#8220;bulleted&#8221;
-list. Itemized lists can be nested within one another, up to four
-levels deep. They can also be nested within other paragraph-making
-environments, such as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>).
+list. The format of the label numbering depends on the nesting level of
+this environment; see below. Each <literal>itemize</literal> list environment must
+have at least one item; having none causes the &latex; error
+&#8216;<literal>Something's wrong--perhaps a missing \item</literal>&#8217;.
</para>
-<para>Each item of an <literal>itemize</literal> list begins with an <literal>\item</literal> command.
-There must be at least one <literal>\item</literal> command within the environment.
+<para>This example gives a two-item list. As a top-level list each label
+would come out as a bullet, &#8226;.
</para>
-<para>By default, the marks at each level look like this:
+<screen>\begin{itemize}
+ \item Pencil and watercolor sketch by Cassandra
+ \item Rice portrait
+\end{itemize}
+</screen>
+<indexterm role="fn"><primary>\item</primary></indexterm>
+<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you
+give <literal>\item</literal> an optional argument by following it with square
+brackets, as in <literal>\item[Optional label]</literal>, then by default it will
+appear in bold and be flush right, so it could extend into the left
+margin. For labels that are flush left see the <link linkend="description">description</link>
+environment. Following the <literal>\item</literal> is optional text, which may
+contain multiple paragraphs.
</para>
-<orderedlist numeration="arabic"><listitem><para>&#8226; (bullet)
-</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash)
-</para></listitem><listitem><para>* (asterisk)
-</para></listitem><listitem><para>. (centered dot, rendered here as a period)
-</para></listitem></orderedlist>
<indexterm role="fn"><primary>\labelitemi</primary></indexterm>
<indexterm role="fn"><primary>\labelitemii</primary></indexterm>
<indexterm role="fn"><primary>\labelitemiii</primary></indexterm>
<indexterm role="fn"><primary>\labelitemiv</primary></indexterm>
-<para>The <literal>itemize</literal> environment uses the commands <literal>\labelitemi</literal>
-through <literal>\labelitemiv</literal> to produce the default label. So, you can
-use <literal>\renewcommand</literal> to change the labels. For instance, to have
-the first level use diamonds:
+<para>Itemized lists can be nested within one another, up to four levels deep.
+They can also be nested within other paragraph-making environments, such
+as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). The <literal>itemize</literal> environment
+uses the commands <literal>\labelitemi</literal> through <literal>\labelitemiv</literal> to
+produce the default label (this also uses the convention of lower case
+roman numerals at the end of the command names that signify the nesting
+level). These are the default marks at each level.
+</para>
+<orderedlist numeration="arabic"><listitem><para>&#8226; (bullet, from <literal>\textbullet</literal>)
+</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash, from <literal>\normalfont\bfseries\textendash</literal>)
+</para></listitem><listitem><para>* (asterisk, from <literal>\textasteriskcentered</literal>)
+</para></listitem><listitem><para>. (centered dot, rendered here as a period, from <literal>\textperiodcentered</literal>)
+</para></listitem></orderedlist>
+<para>Change the labels with <literal>\renewcommand</literal>. For instance, this makes
+the first level use diamonds.
</para>
<screen>\renewcommand{\labelitemi}{$\diamond$}
</screen>
@@ -3188,67 +3670,26 @@ the first level use diamonds:
<indexterm role="fn"><primary>\leftmarginiv</primary></indexterm>
<indexterm role="fn"><primary>\leftmarginv</primary></indexterm>
<indexterm role="fn"><primary>\leftmarginvi</primary></indexterm>
-<para>The <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal> parameters define
-the distance between the left margin of the enclosing environment and
-the left margin of the list. By convention, <literal>\leftmargin</literal> is set
-to the appropriate <literal>\leftmargin<replaceable>N</replaceable></literal> when a new level of
-nesting is entered.
-</para>
-<para>The defaults vary from &#8216;<literal>.5em</literal>&#8217; (highest levels of nesting) to
-&#8216;<literal>2.5em</literal>&#8217; (first level), and are a bit reduced in two-column mode.
-This example greatly reduces the margin space for outermost lists:
+<para>The distance between the left margin of the enclosing environment and
+the left margin of the <literal>itemize</literal> list is determined by the
+parameters <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal>. (Note the
+convention of using lower case roman numerals a the end of the command
+name to denote the nesting level.) The defaults are: <literal>2.5em</literal> in
+level 1 (<literal>2em</literal> in two-column mode), <literal>2.2em</literal> in level 2,
+<literal>1.87em</literal> in level 3, and <literal>1.7em</literal> in level 4, with smaller
+values for more deeply nested levels.
+</para>
+<para>For other major &latex; labeled list environments, see
+<link linkend="description">description</link> and <link linkend="enumerate">enumerate</link>. For information about list
+layout parameters, including the default values, and for information
+about customizing list layout, see <link linkend="list">list</link>. The package
+<filename>enumitem</filename> is useful for customizing lists.
+</para>
+<para>This example greatly reduces the margin space for outermost itemized
+lists.
</para>
<screen>\setlength{\leftmargini}{1.25em} % default 2.5em
</screen>
-<!-- xx should be in its own generic section -->
-<para>Some parameters that affect list formatting:
-</para>
-<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal>
-</term><listitem><para>Extra indentation before each item in a list; default zero.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelsep</primary></indexterm><literal>\labelsep</literal>
-</term><listitem><para>Space between the label and text of an item; default &#8216;<literal>.5em</literal>&#8217;.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelwidth</primary></indexterm><literal>\labelwidth</literal>
-</term><listitem><para>Width of the label; default &#8216;<literal>2em</literal>&#8217;, or &#8216;<literal>1.5em</literal>&#8217; in two-column mode.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\listparindent</primary></indexterm><literal>\listparindent</literal>
-</term><listitem><para>Extra indentation added to second and subsequent paragraphs within a
-list item; default &#8216;<literal>0pt</literal>&#8217;.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightmargin</primary></indexterm><literal>\rightmargin</literal>
-</term><listitem><para>Horizontal distance between the right margin of the list and the
-enclosing environment; default &#8216;<literal>0pt</literal>&#8217;, except in the <literal>quote</literal>,
-<literal>quotation</literal>, and <literal>verse</literal> environments, where it is set equal
-to <literal>\leftmargin</literal>.
-</para>
-</listitem></varlistentry></variablelist>
-<para>Parameters affecting vertical spacing between list items (rather
-loose, by default).
-</para>
-<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemsep</primary></indexterm><literal>\itemsep</literal>
-</term><listitem><para>Vertical space between items. The default is <literal>2pt plus1pt
-minus1pt</literal> for <literal>10pt</literal> documents, <literal>3pt plus2pt minus1pt</literal> for
-<literal>11pt</literal>, and <literal>4.5pt plus2pt minus1pt</literal> for <literal>12pt</literal>.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal>
-</term><listitem><para>Extra vertical space between paragraphs within a list item. Defaults
-are the same as <literal>\itemsep</literal>.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topsep</primary></indexterm><literal>\topsep</literal>
-</term><listitem><para>Vertical space between the first item and the preceding paragraph.
-For top-level lists, the default is <literal>8pt plus2pt minus4pt</literal> for
-<literal>10pt</literal> documents, <literal>9pt plus3pt minus5pt</literal> for <literal>11pt</literal>,
-and <literal>10pt plus4pt minus6pt</literal> for <literal>12pt</literal>. These are reduced
-for nested lists.
-</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal>
-</term><listitem><para>Extra space added to <literal>\topsep</literal> when the list environment starts a
-paragraph. The default is <literal>2pt plus1pt minus1pt</literal> for <literal>10pt</literal>
-documents, <literal>3pt plus1pt minus1pt</literal> for <literal>11pt</literal>, and <literal>3pt
-plus2pt minus2pt</literal> for <literal>12pt</literal>.
-</para>
-</listitem></varlistentry></variablelist>
<indexterm role="fn"><primary>\parskip example</primary></indexterm>
<para>Especially for lists with short items, it may be desirable to elide
space between items. Here is an example defining an <literal>itemize*</literal>
@@ -3270,6 +3711,7 @@ see <link linkend="_005cparskip">\parskip</link>):
<indexterm role="fn"><primary>environment, <literal>letter</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>letter</literal> environment</primary></indexterm>
+
<para>This environment is used for creating letters. See <link linkend="Letters">Letters</link>.
</para>
@@ -3280,54 +3722,329 @@ see <link linkend="_005cparskip">\parskip</link>):
<indexterm role="fn"><primary>environment, <literal>list</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>list</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>lists of items, generic</primary></indexterm>
-<para>The <literal>list</literal> environment is a generic environment which is used for
-defining many of the more specific environments. It is seldom used in
-documents, but often in macros.
+<para>Synopsis:
</para>
<screen>\begin{list}{<replaceable>labeling</replaceable>}{<replaceable>spacing</replaceable>}
-\item <replaceable>item1</replaceable>
-\item <replaceable>item2</replaceable>
+\item[<replaceable>optional label of first item</replaceable>] text of first item
+\item[<replaceable>optional label of second item</replaceable>] text of second item
...
\end{list}
</screen>
-<para>The mandatory <replaceable>labeling</replaceable> argument specifies how items should be
-labelled (unless the optional argument is supplied to <literal>\item</literal>).
-This argument is a piece of text that is inserted in a box to form the
-label. It can and usually does contain other &latex; commands.
+<para>The <literal>list</literal> environment is a generic environment for constructing
+more specialized lists. It is most often used to create lists via the
+<literal>description</literal>, <literal>enumerate</literal>, and <literal>itemize</literal> environments
+(see <link linkend="description">description</link>, <link linkend="enumerate">enumerate</link>, and <link linkend="itemize">itemize</link>).
+</para>
+<para>Also, many standard &latex; environments that are not visually lists
+are constructed using <literal>list</literal>, including <literal>quotation</literal>,
+<literal>quote</literal>, <literal>center</literal>, <literal>verbatim</literal>, and plenty more
+(see <link linkend="quotation-and-quote">quotation and quote</link>, see <link linkend="center">center</link>, see <link linkend="flushright">flushright</link>).
+</para>
+<indexterm role="cp"><primary>package, <literal>enumitem</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>enumitem</literal> package</primary></indexterm>
+
+<para>The third-party package <literal>enumitem</literal> is useful for customizing lists.
+Here, we describe the <literal>list</literal> environment by defining a new custom
+environment.
+</para>
+<screen>\newcounter{namedlistcounter} % number the items
+\newenvironment{named}
+ {\begin{list}
+ {Item~\Roman{namedlistcounter}.} % labeling argument
+ {\usecounter{namedlistcounter} % spacing argument
+ \setlength{\leftmargin}{3.5em}} % still spacing arg
+ }
+ {\end{list}}
+
+\begin{named}
+ \item Shows as ``Item~I.''
+ \item[Special label.] Shows as ``Special label.''
+ \item Shows as ``Item~II.''
+\end{named}
+</screen>
+<para>The <literal>list</literal> environment&#8217;s mandatory first argument,
+<replaceable>labeling</replaceable>, specifies the default labeling of list items. It can
+contain text and &latex; commands, as above where it contains both
+&#8216;<literal>Item</literal>&#8217; and &#8216;<literal>\Roman{...}</literal>&#8217;. &latex; forms the label by
+putting the <replaceable>labeling</replaceable> argument in a box of width
+<literal>\labelwidth</literal>. If the label is wider than that, the additional
+material extends to the right. When making an instance of a list you
+can override the default labeling by giving <literal>\item</literal> an optional
+argument by including square braces and the text, as in the above
+<literal>\item[Special label.]</literal>; see <link linkend="_005citem">\item</link>.
+</para>
+<indexterm role="fn"><primary>\makelabel</primary></indexterm>
+<para>The label box is constructed by the command <literal>\makelabel</literal>. By
+default it positions the contents flush right. It takes one argument,
+the label. It typesets the contents in LR mode. An example of changing
+its definition is that to the above example before the definition of the
+<literal>named</literal> environment add
+<literal>\newcommand{\namedmakelabel}[1]{\textsc{#1}}</literal>, and between
+the <literal>\setlength</literal> command and the parenthesis that closes the
+<replaceable>spacing</replaceable> argument also add <literal>\let\makelabel\namedmakelabel</literal>.
+Then the items will be typeset in small caps. Similarly, changing the
+second code line to <literal>\let\makelabel\fbox</literal> puts the labels inside a
+framed box. Another example is at the bottom of this entry.
+</para>
+<para>The mandatory second argument <replaceable>spacing</replaceable> can have a list of
+commands to redefine the spacing parameters for the list, such as
+<literal>\setlength{\labelwidth}{2em}</literal>. If this argument is empty,
+i.e., <literal>{}</literal>, then the list will have the default spacing given
+below. To number the items using a counter, put
+<literal>\usecounter{<replaceable>countername</replaceable>}</literal> in this argument
+(see <link linkend="_005cusecounter">\usecounter</link>).
+</para>
+<para>Below are the spacing parameters for list formatting. See also the
+figure below. Each is a length (see <link linkend="Lengths">Lengths</link>). The vertical
+spaces are normally rubber lengths, with <literal>plus</literal> and <literal>minus</literal>
+components, to give &tex; flexibility in setting the page. Change
+each with a command such as <literal>\setlength{itemsep}{2pt plus1pt
+minus1pt}</literal>. For some effects these lengths should be zero or
+negative. Default values for derived environments such as
+<literal>itemize</literal> can be changed from the values shown here for the basic
+<literal>list</literal>.
+</para>
+<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal>
+</term><listitem><para>Extra horizontal space indentation, beyond <literal>leftmargin</literal>, of the
+first line each item. Its default value is <literal>0pt</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\itemsep</primary></indexterm><literal>\itemsep</literal>
+</term><listitem><para>Vertical space between items, beyond the <literal>\parsep</literal>. The defaults
+for the first three levels in &latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;,
+and &#8216;<literal>report</literal>&#8217; classes at 10 point size are: <literal>4pt plus2pt
+minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>), and
+<literal>\topsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>). The defaults at
+11 point are: <literal>4.5pt plus2pt minus1pt</literal>, <literal>\parsep</literal> (that is,
+<literal>2pt plus1pt minus1pt</literal>), and <literal>topsep</literal> (that is, <literal>2pt
+plus1pt minus1pt</literal>). The defaults at 12 point are: <literal>5pt plus2.5pt
+minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>), and
+<literal>\topsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>).
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelsep</primary></indexterm><literal>\labelsep</literal>
+</term><listitem><para>Horizontal space between the label and text of an item.
+The default for &latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;,
+and &#8216;<literal>report</literal>&#8217; classes is <literal>0.5em</literal>.
</para>
-<para>The mandatory <replaceable>spacing</replaceable> argument contains commands to change the
-spacing parameters for the list. This argument will most often be
-empty, i.e., <literal>{}</literal>, which leaves the default spacing.
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelwidth</primary></indexterm><literal>\labelwidth</literal>
+</term><listitem><para>Horizontal width. The box containing the label is nominally this wide.
+If <literal>\makelabel</literal> returns text that is wider than this then the first
+line of the item will be indented to make room for this extra material.
+If <literal>\makelabel</literal> returns text of width less than or equal to
+<literal>\labelwidth</literal> then &latex;&#8217;s default is that the label is typeset
+flush right in a box of this width.
+</para>
+<para>The left edge of the label box is
+<literal>\leftmargin</literal>+<literal>\itemindent</literal>-<literal>\labelsep</literal>-<literal>\labelwidth</literal>
+from the left margin of the enclosing environment.
+</para>
+<para>The default for &latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;, and
+&#8216;<literal>report</literal>&#8217; classes at the top level is
+<literal>\leftmargini</literal>-<literal>\labelsep</literal>, (which is <literal>2em</literal> in one column
+mode and <literal>1.5em</literal> in two column mode). At the second level it is
+<literal>\leftmarginii</literal>-<literal>\labelsep</literal>, and at the third level it is
+<literal>\leftmarginiii</literal>-<literal>\labelsep</literal>. These definitions make the
+label&#8217;s left edge coincide with the left margin of the enclosing
+environment.
</para>
-<para>The width used for typesetting the list items is specified by
-<literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page layout parameters</link>).
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftmargin</primary></indexterm><literal>\leftmargin</literal>
+</term><listitem><para>Horizontal space between the left margin of the enclosing environment
+(or the left margin of the page if this is a top-level list), and the
+left margin of this list. It must be non-negative.
+</para>
+<para>In the standard &latex; document classes, a top-level list has this set
+to the value of <literal>\leftmargini</literal>, while a list that is nested inside
+a top-level list has this margin set to <literal>\leftmarginii</literal>. More
+deeply nested lists get the values of <literal>\leftmarginiii</literal> through
+<literal>\leftmarginvi</literal>. (Nesting greater than level five generates the
+error message &#8216;<literal>Too deeply nested</literal>&#8217;.)
+</para>
+<para>The defaults for the first three levels in &latex;&#8217;s &#8216;<literal>article</literal>&#8217;,
+&#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217; classes are: <literal>\leftmargini</literal> is
+<literal>2.5em</literal> (in two column mode, <literal>2em</literal>), <literal>\leftmarginii</literal> is
+<literal>2.2em</literal>, and <literal>\leftmarginiii</literal> is <literal>1.87em</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\listparindent</primary></indexterm><literal>\listparindent</literal>
+</term><listitem><para>Horizontal space of additional line indentation, beyond
+<literal>\leftmargin</literal>, for second and subsequent paragraphs within a list
+item. A negative value makes this an &#8220;outdent&#8221;. Its default value
+is <literal>0pt</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal>
+</term><listitem><para>Vertical space between paragraphs within an item. In the &#8216;<literal>book</literal>&#8217;
+and &#8216;<literal>article</literal>&#8217; classes The defaults for the first three levels in
+&latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217; classes at 10
+point size are: <literal>4pt plus2pt minus1pt</literal>, <literal>2pt plus1pt
+minus1pt</literal>, and <literal>0pt</literal>. The defaults at 11 point size are:
+<literal>4.5pt plus2pt minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and
+<literal>0pt</literal>. The defaults at 12 point size are: <literal>5pt plus2.5pt
+minus1pt</literal>, <literal>2.5pt plus1pt minus1pt</literal>, and <literal>0pt</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal>
+</term><listitem><para>Vertical space added, beyond <literal>\topsep</literal>+<literal>\parskip</literal>, to the top
+and bottom of the entire environment if the list instance is preceded by
+a blank line. (A blank line in the &latex; source before the list
+changes spacing at both the top and bottom of the list; whether the line
+following the list is blank does not matter.)
+</para>
+<para>The defaults for the first three levels in &latex;&#8217;s &#8216;<literal>article</literal>&#8217;,
+&#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217; classes at 10 point size are: <literal>2pt
+plus1 minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt
+minus1pt</literal>. The defaults at 11 point are: <literal>3pt plus1pt minus1pt</literal>,
+<literal>3pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt minus1pt</literal>). The
+defaults at 12 point are: <literal>3pt plus2pt minus3pt</literal>, <literal>3pt plus2pt
+minus2pt</literal>, and <literal>1pt plus0pt minus1pt</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightmargin</primary></indexterm><literal>\rightmargin</literal>
+</term><listitem><para>Horizontal space between the right margin of the list and the right
+margin of the enclosing environment. Its default value is <literal>0pt</literal>.
+It must be non-negative.
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topsep</primary></indexterm><literal>\topsep</literal>
+</term><listitem><para>Vertical space added to both the top and bottom of the list, in addition
+to <literal>\parskip</literal> (see <link linkend="_005cparskip">\parskip</link>). The defaults for the first three
+levels in &latex;&#8217;s &#8216;<literal>article</literal>&#8217;, &#8216;<literal>book</literal>&#8217;, and &#8216;<literal>report</literal>&#8217;
+classes at 10 point size are: <literal>8pt plus2pt minus4pt</literal>, <literal>4pt
+plus2pt minus1pt</literal>, and <literal>2pt plus1pt minus1pt</literal>. The defaults at 11
+point are: <literal>9pt plus3pt minus5pt</literal>, <literal>4.5pt plus2pt minus1pt</literal>,
+and <literal>2pt plus1pt minus1pt</literal>. The defaults at 12 point are:
+<literal>10pt plus4pt minus6pt</literal>, <literal>5pt plus2.5pt minus1pt</literal>, and
+<literal>2.5pt plus1pt minus1pt</literal>.
</para>
+</listitem></varlistentry></variablelist>
+<para>This shows the horizontal and vertical distances.
+</para>
+<informalfigure><mediaobject><imageobject><imagedata fileref="latex2e-figures/list.eps" format="EPS"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.pdf" format="PDF"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.png" format="PNG"></imagedata></imageobject><textobject><literallayout>.......................................................................
+..............Surrounding environment, preceding material.............. -
+ | v0
+ |---h0--|-h1-| |
+ ..Label.. .....First item..................................... -
+ ............................................................
+ ............................................................ -
+ | v1
+ ........First item, second paragraph .................. -
+ |-h2-| | v2
+ |
+ ..Label.. .....Second item.................................... -
+ ............................................................
+ ............................................................ -
+|-h3--|-h4-| |-h5-| |v3
+ |
+..............Surrounding environment, following material.............. -
+.......................................................................</literallayout></textobject></mediaobject></informalfigure>
+
+<para>The lengths shown are listed below. The key relationship is that the
+right edge of the bracket for <replaceable>h1</replaceable> equals the right edge of the
+bracket for <replaceable>h4</replaceable>, so that the left edge of the label box is at
+<replaceable>h3</replaceable>+<replaceable>h4</replaceable>-(<replaceable>h0</replaceable>+<replaceable>h1</replaceable>).
+</para>
+<variablelist><varlistentry><term><replaceable>v0</replaceable>
+</term><listitem><para><inlineequation><mathphrase><literal>\topsep</literal> + <literal>\parskip</literal></mathphrase></inlineequation> if
+the list environment does not start a new paragraph, and
+<literal>\topsep</literal>+<literal>\parskip</literal>+<literal>\partopsep</literal> if it does
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>v1</replaceable>
+</term><listitem><para><literal>\parsep</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>v2</replaceable>
+</term><listitem><para><literal>\itemsep</literal>+<literal>\parsep</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>v3</replaceable>
+</term><listitem><para>Same as <replaceable>v0</replaceable>. (This space is affected by whether a blank line
+appears in the source above the environment; whether a blank line
+appears in the source below the environment does not matter.)
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>h1</replaceable>
+</term><listitem><para><literal>\labelsep</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>h2</replaceable>
+</term><listitem><para><literal>\listparindent</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>h3</replaceable>
+</term><listitem><para><literal>\leftmargin</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>h4</replaceable>
+</term><listitem><para><literal>\itemindent</literal>
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>h5</replaceable>
+</term><listitem><para><literal>\rightmargin</literal>
+</para>
+</listitem></varlistentry></variablelist>
+<para>The list&#8217;s left and right margins, shown above as <replaceable>h3</replaceable> and <replaceable>h5</replaceable>,
+are with respect to the ones provided by the surrounding environment, or
+with respect to the page margins for a top-level list. The line width
+used for typesetting the list items is <literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page
+layout parameters</link>). For instance, set the list&#8217;s left margin to be one
+quarter of the distance between the left and right margins of the
+enclosing environment with
+<literal>\setlength{\leftmargin}{0.25\linewidth}</literal>.
+</para>
+<para>Page breaking in a list structure is controlled by the three
+parameters below. For each, the &latex; default is
+<literal>-\@lowpenalty</literal>, that is, <literal>-51</literal>. Because it is negative,
+it somewhat encourages a page break at each spot. Change it with,
+e.g., <literal>\@beginparpenalty=9999</literal>; a value of 10000 prohibits a
+page break.
+</para>
+<variablelist><varlistentry><term><indexterm role="fn"><primary>\@beginparpenalty</primary></indexterm><literal>\@beginparpenalty</literal>
+</term><listitem><para>The page breaking penalty for breaking before the list (default <literal>-51</literal>).
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@itempenalty</primary></indexterm><literal>\@itempenalty</literal>
+</term><listitem><para>The page breaking penalty for breaking before a list item (default <literal>-51</literal>).
+</para>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@endparpenalty</primary></indexterm><literal>\@endparpenalty</literal>
+</term><listitem><para>The page breaking penalty for breaking after a list (default <literal>-51</literal>).
+</para>
+</listitem></varlistentry></variablelist>
+<para>This example has the labels in red. They are numbered, and the left
+edge of the label lines up with the left edge of the item text.
+</para>
+<screen>\usepackage{color}
+\newcounter{cnt}
+\newcommand{\makeredlabel}[1]{\textcolor{red}{#1.}}
+\newenvironment{redlabel}
+ {\begin{list}
+ {\arabic{cnt}}
+ {\usecounter{cnt}
+ \setlength{\labelwidth}{0em}
+ \setlength{\labelsep}{0.5em}
+ \setlength{\leftmargin}{1.5em}
+ \setlength{\itemindent}{0.5em} % equals \labelwidth+\labelsep
+ \let\makelabel=\makeredlabel
+ }
+ }
+{\end{list} }
+</screen>
<sect2 label="8.16.1" id="_005citem">
-<title><literal>\item</literal>: An entry in a list.</title>
+<title><literal>\item</literal>: An entry in a list</title>
<para>Synopsis:
</para>
<screen>\item text of item
</screen>
<para>or
-</para><screen>\item[<replaceable>optional label</replaceable>] text of item
+</para><screen>\item[<replaceable>optional-label</replaceable>] text of item
</screen>
<para>An entry in a list. The entries are prefixed by a label, whose default
-depends on the list type.
+depends on the list type.
+</para>
+<para>Because the optional label is surrounded by square brackets
+&#8216;<literal>[...]</literal>&#8217;, if you have an item whose text starts with &#8216;<literal>[</literal>&#8217;, you
+have to to hide the bracket inside curly braces, as in: <literal>\item
+{[} is an open square bracket</literal>; otherwise, &latex; will think it
+marks the start of an optional label.
</para>
-<para>Because the optional argument <replaceable>optional label</replaceable> is surrounded by
-square brackets&#160;(<literal>[</literal> and <literal>]</literal>), to use square brackets
-inside the optional argument you must hide them inside curly braces, as
-in <literal>\item[Close square bracket, {]}]</literal>. Similarly, to use an open
-square bracket as first character in the text of the item, also hide it
-inside curly braces. See <link linkend="LaTeX-command-syntax">&latex; command syntax</link>.
+<para>Similarly, if the item does have the optional label and you need a
+close square bracket inside that label, you must hide it in the same
+way: <literal>\item[Close square bracket, {]}]</literal>. See <link linkend="LaTeX-command-syntax">&latex;
+command syntax</link>.
</para>
-<para>In this example the <literal>enumerate</literal> list has two items that use the
-default label and one that uses the optional label.
+<para>In this example the enumerate list has two items that use the default
+label and one that uses the optional label.
</para>
<screen>\begin{enumerate}
\item Moe
@@ -3336,11 +4053,52 @@ default label and one that uses the optional label.
\end{enumerate}
</screen>
<para>The first item is labelled &#8216;<literal>1.</literal>&#8217;, the second item is labelled
-&#8216;<literal>sometimes</literal>&#8217;, and the third item is labelled &#8216;<literal>2.</literal>&#8217; (note that,
-because of the optional label in the second item, the third item does
-not get a &#8216;<literal>3.</literal>&#8217;).
+&#8216;<literal>sometimes</literal>&#8217;, and the third item is labelled &#8216;<literal>2.</literal>&#8217;. Because
+of the optional label in the second item, the third item is not
+labelled&#160;&#8216;<literal>3.</literal>&#8217;.
</para>
+</sect2>
+<sect2 label="8.16.2" id="trivlist">
+<title><literal>trivlist</literal>: A restricted form of <literal>list</literal></title>
+
+<para>Synopsis:
+</para>
+<screen>\begin{trivlist}
+ ...
+\end{trivlist}
+</screen>
+<para>A restricted version of the list environment, in which margins are not
+indented and an <literal>\item</literal> without an optional argument produces no
+text. It is most often used in macros, to define an environment where
+the <literal>\item</literal> command as part of the environment&#8217;s definition. For
+instance, the <literal>center</literal> environment is defined essentially like
+this:
+</para>
+<screen>\newenvironment{center}
+ {\begin{trivlist}\centering\item\relax}
+ {\end{trivlist}}
+</screen>
+<para>Using <literal>trivlist</literal> in this way allows the macro to inherit some
+common code: combining vertical space of two adjacent environments;
+detecting whether the text following the environment should be
+considered a new paragraph or a continuation of the previous one;
+adjusting the left and right margins for possible nested list
+environments.
+</para>
+<para>Specifically, <literal>trivlist</literal> uses the current values of the list
+parameters (see <link linkend="list">list</link>), except that <literal>\parsep</literal> is set to the
+value of <literal>\parskip</literal>, and <literal>\leftmargin</literal>, <literal>\labelwidth</literal>,
+and <literal>\itemindent</literal> are set to zero.
+</para>
+<para>This example outputs the items as two paragraphs, except that (by
+default) they have no paragraph indent and are vertically separated.
+</para>
+<screen>\begin{trivlist}
+\item The \textit{Surprise} is not old; no one would call her old.
+\item She has a bluff bow, lovely lines.
+\end{trivlist}
+</screen>
</sect2>
</sect1>
@@ -3349,6 +4107,7 @@ not get a &#8216;<literal>3.</literal>&#8217;).
<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>in-line formulas</primary></indexterm>
<para>Synopsis:
@@ -3357,8 +4116,8 @@ not get a &#8216;<literal>3.</literal>&#8217;).
<replaceable>math</replaceable>
\end{math}
</screen>
-<para>The <literal>math</literal> environment inserts the given <replaceable>math</replaceable> within the
-running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms.
+<para>The <literal>math</literal> environment inserts given <replaceable>math</replaceable> material within
+the running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms.
See <link linkend="Math-formulas">Math formulas</link>.
</para>
@@ -3368,6 +4127,7 @@ See <link linkend="Math-formulas">Math formulas</link>.
<indexterm role="fn"><primary>environment, <literal>minipage</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>minipage</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>minipage, creating a</primary></indexterm>
<screen>\begin{minipage}[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>}
@@ -3408,6 +4168,7 @@ footnotes; they may wind up at the bottom of the wrong minipage.
<indexterm role="fn"><primary>environment, <literal>picture</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>picture</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>creating pictures</primary></indexterm>
<indexterm role="cp"><primary>pictures, creating</primary></indexterm>
@@ -3432,6 +4193,7 @@ The default value is <literal>1pt</literal>.
</para>
<indexterm role="cp"><primary>package, <literal>picture</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>picture</literal> package</primary></indexterm>
+
<para>The <literal>picture</literal> package redefine the <literal>picture</literal> environment so
that everywhere a number is used in a <replaceable>picture commands</replaceable> to specify
a coordinate, one can use alternatively a length. Be aware however that
@@ -3763,11 +4525,13 @@ values must lie between &#8722;4 and +4, inclusive.
<indexterm role="fn"><primary>environment, <literal>quotation</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>quotation</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>quoted text with paragraph indentation, displaying</primary></indexterm>
<indexterm role="cp"><primary>displaying quoted text with paragraph indentation</primary></indexterm>
<indexterm role="cp"><primary>paragraph indentations in quoted text</primary></indexterm>
<indexterm role="fn"><primary>environment, <literal>quote</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>quote</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>quoted text without paragraph indentation, displaying</primary></indexterm>
<indexterm role="cp"><primary>displaying quoted text without paragraph indentation</primary></indexterm>
<indexterm role="cp"><primary>paragraph indentations in quoted text, omitting</primary></indexterm>
@@ -3813,6 +4577,7 @@ quotations.
<indexterm role="fn"><primary>environment, <literal>tabbing</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>tabbing</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>tab stops, using</primary></indexterm>
<indexterm role="cp"><primary>lining text up using tab stops</primary></indexterm>
<indexterm role="cp"><primary>alignment via tabbing</primary></indexterm>
@@ -3820,23 +4585,69 @@ quotations.
<para>Synopsis:
</para>
<screen>\begin{tabbing}
-<replaceable>row1col1</replaceable> \= <replaceable>row1col2</replaceable> \= <replaceable>row1col3</replaceable> \= <replaceable>row1col4</replaceable> \\
-<replaceable>row2col1</replaceable> \&gt; \&gt; <replaceable>row2col3</replaceable> \\
+<replaceable>row1col1</replaceable> \= <replaceable>row1col2</replaceable> ... \\
+<replaceable>row2col1</replaceable> \&gt; <replaceable>row2col2</replaceable> ... \\
...
\end{tabbing}
</screen>
-<para>The <literal>tabbing</literal> environment provides a way to align text in
-columns. It works by setting tab stops and tabbing to them much as
-was done on an ordinary typewriter. It is best suited for cases where
-the width of each column is constant and known in advance.
+<para>The <literal>tabbing</literal> environment aligns text in columns. It works by
+setting tab stops and tabbing to them much as was done on a typewriter.
+It is best suited for cases where the width of each column is constant
+and known in advance.
</para>
-<para>This environment can be broken across pages, unlike the <literal>tabular</literal>
-environment.
+<para>This example has a first line where the tab stops are set to explicit
+widths, ended by a <literal>\kill</literal> command (which is described below):
</para>
-<para>The following commands can be used inside a <literal>tabbing</literal> environment:
+<screen>\begin{tabbing}
+\hspace{0.75in} \= \hspace{0.40in} \= \hspace{0.40in} \kill
+Ship \&gt; Guns \&gt; Year \\
+\textit{Sophie} \&gt; 14 \&gt; 1800 \\
+\textit{Polychrest} \&gt; 24 \&gt; 1803 \\
+\textit{Lively} \&gt; 38 \&gt; 1804 \\
+\textit{Surprise} \&gt; 28 \&gt; 1805 \\
+\end{tabbing}
+</screen>
+<para>Both the <literal>tabbing</literal> environment and the more widely-used
+<literal>tabular</literal> environment put text in columns. The most important
+distinction is that in <literal>tabular</literal> the width of columns is
+determined automatically by &latex;, while in <literal>tabbing</literal> the user
+sets the tab stops. Another distinction is that <literal>tabular</literal>
+generates a box, but <literal>tabbing</literal> can be broken across pages.
+Finally, while <literal>tabular</literal> can be used in any mode, <literal>tabbing</literal>
+can be used only in paragraph mode and it starts a new paragraph.
+</para>
+<para>A <literal>tabbing</literal> environment always starts a new paragraph, without
+indentation. Moreover, as shown in the example above, there is no need
+to use the starred form of the <literal>\hspace</literal> command at the beginning
+of a tabbed row. The right margin of the <literal>tabbing</literal> environment is
+the end of line, so that the width of the environment is
+<literal>\linewidth</literal>.
+</para>
+<indexterm role="cp"><primary>row, tabbing</primary></indexterm>
+<para>The <literal>tabbing</literal> environment contains a sequence of <firstterm>tabbed
+rows</firstterm>. The first tabbed row begins immediately after
+<literal>\begin{tabbing}</literal> and each row ends with <literal>\\</literal> or
+<literal>\kill</literal>. The last row may omit the <literal>\\</literal> and end with just
+<literal>\end{tabbing}</literal>.
+</para>
+<para>At any point the <literal>tabbing</literal> environment has a current tab stop
+pattern, a sequence of <inlineequation><mathphrase><replaceable>n</replaceable> &gt; 0</mathphrase></inlineequation> tab stops, numbered 0, 1,
+etc. These create <replaceable>n</replaceable> corresponding columns. Tab stop&#160;0 is
+always the left margin, defined by the enclosing environment. Tab
+stop number&#160;<replaceable>i</replaceable> is set if it is assigned a horizontal
+position on the page. Tab stop number&#160;<replaceable>i</replaceable> can only be set if
+all the stops 0, &#8230;, <inlineequation><mathphrase>i-1</mathphrase></inlineequation> have already been set; normally
+later stops are to the right of earlier ones.
+</para>
+<para>By default any text typeset in a <literal>tabbing</literal> environment is typeset
+ragged right and left-aligned on the current tab stop. Typesetting is
+done in LR mode (see <link linkend="Modes">Modes</link>).
+</para>
+<para>The following commands can be used inside a <literal>tabbing</literal> environment.
+They are all fragile (see <link linkend="_005cprotect">\protect</link>).
</para>
<variablelist><varlistentry><term><indexterm role="fn"><primary>\\ (tabbing)</primary></indexterm><literal>\\ (tabbing)</literal>
-</term><listitem><para>End a line.
+</term><listitem><para>End a tabbed line and typeset it.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\= (tabbing)</primary></indexterm><literal>\= (tabbing)</literal>
</term><listitem><para>Sets a tab stop at the current position.
@@ -3859,34 +4670,35 @@ necessary.
following commands one tab stop to the left, beginning tabbed line if
necessary.
</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\&#8217; (tabbing)</primary></indexterm><literal>\' (tabbing)</literal>
-</term><listitem><para>Moves everything that you have typed so far in the
-current column, i.e., everything from the most recent <literal>\&gt;</literal>,
-<literal>\&lt;</literal>, <literal>\'</literal>, <literal>\\</literal>, or <literal>\kill</literal> command, to the right
-of the previous column, flush against the current column&#8217;s tab stop.
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\' (tabbing)</primary></indexterm><literal>\' (tabbing)</literal>
+</term><listitem><para>Moves everything that you have typed so far in the current column, i.e.,
+everything from the most recent <literal>\&gt;</literal>, <literal>\&lt;</literal>, <literal>\'</literal>,
+<literal>\\</literal>, or <literal>\kill</literal> command, to the previous column and aligned
+to the right, flush against the current column&#8217;s tab stop.
</para>
-</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\&#8216; (tabbing)</primary></indexterm><literal>\` (tabbing)</literal>
+</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\` (tabbing)</primary></indexterm><literal>\` (tabbing)</literal>
</term><listitem><para>Allows you to put text flush right against any tab stop, including tab
-stop&#160;0. However, it can&#8217;t move text to the right of the last column
-because there&#8217;s no tab stop there. The <literal>\`</literal> command moves all the
-text that follows it, up to the <literal>\\</literal> or <literal>\end{tabbing}</literal>
-command that ends the line, to the right margin of the tabbing
-environment. There must be no <literal>\&gt;</literal> or <literal>\'</literal> command between
-the <literal>\`</literal> and the command that ends the line.
+stop&#160;0. However, it can&#8217;t move text to the right of the last
+column because there&#8217;s no tab stop there. The <literal>\`</literal> command moves
+all the text that follows it, up to the <literal>\\</literal> or
+<literal>\end{tabbing}</literal> command that ends the line, to the right margin
+of the <literal>tabbing</literal> environment. There must be no <literal>\&gt;</literal> or
+<literal>\'</literal> command between the <literal>\`</literal> and the <literal>\\</literal> or
+<literal>\end{tabbing}</literal> command that ends the line.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\a (tabbing)</primary></indexterm><literal>\a (tabbing)</literal>
-</term><listitem><indexterm role="fn"><primary>\a&#8217; (acute accent in tabbing)</primary></indexterm>
-<indexterm role="fn"><primary>\a&#8216; (grave accent in tabbing)</primary></indexterm>
+</term><listitem><indexterm role="fn"><primary>\a' (acute accent in tabbing)</primary></indexterm>
+<indexterm role="fn"><primary>\a` (grave accent in tabbing)</primary></indexterm>
<indexterm role="fn"><primary>\a= (macron accent in tabbing)</primary></indexterm>
<para>In a <literal>tabbing</literal> environment, the commands <literal>\=</literal>, <literal>\'</literal> and
<literal>\`</literal> do not produce accents as usual (see <link linkend="Accents">Accents</link>). Instead,
-the commands <literal>\a=</literal>, <literal>\a'</literal> and <literal>\a`</literal> are used.
+use the commands <literal>\a=</literal>, <literal>\a'</literal> and <literal>\a`</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\kill</primary></indexterm><literal>\kill</literal>
-</term><listitem><para>Sets tab stops without producing text. Works just like <literal>\\</literal>
-except that it throws away the current line instead of producing
-output for it. The effect of any <literal>\=</literal>, <literal>\+</literal> or <literal>\-</literal>
-commands in that line remain in effect.
+</term><listitem><para>Sets tab stops without producing text. Works just like <literal>\\</literal> except
+that it throws away the current line instead of producing output for it.
+Any <literal>\=</literal>, <literal>\+</literal> or <literal>\-</literal> commands in that line remain in
+effect.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\poptabs</primary></indexterm><literal>\poptabs</literal>
</term><listitem><indexterm role="fn"><primary>\poptabs</primary></indexterm>
@@ -3897,28 +4709,56 @@ commands in that line remain in effect.
tab stop positions in the middle of a <literal>tabbing</literal> environment.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tabbingsep</primary></indexterm><literal>\tabbingsep</literal>
-</term><listitem><para>Distance to left of tab stop moved by <literal>\'</literal>.
+</term><listitem><para>Distance of the text moved by <literal>\'</literal> to left of current tab stop.
</para>
</listitem></varlistentry></variablelist>
-<para>This example typesets a Pascal function in a traditional format:
+<para>This example typesets a Pascal function:
</para>
<screen>\begin{tabbing}
function \= fact(n : integer) : integer;\\
\&gt; begin \= \+ \\
- \&gt; if \= n $&gt;$ 1 then \+ \\
+ \&gt; if \= n &gt; 1 then \+ \\
fact := n * fact(n-1) \- \\
else \+ \\
fact := 1; \-\- \\
end;\\
\end{tabbing}
</screen>
+<para>The output looks like this:
+</para><screen>function fact(n : integer) : integer;
+ begin
+ if n &gt; 1 then
+ fact := n * fact(n-1);
+ else
+ fact := 1;
+ end;
+</screen>
+<indexterm role="cp"><primary>package, <literal>algorithm2e</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>algorithm2e</literal> package</primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm>
+<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm>
+
+<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm>
+
+<para>(The above example is just for illustration of the environment. To
+actually typeset computer code in typewriter like this, a verbatim
+environment (see <link linkend="verbatim">verbatim</link>) would normally suffice. For
+pretty-printed code, there are quite a few packages, including
+<literal>algorithm2e</literal>, <literal>fancyvrb</literal>, <literal>listings</literal>, and
+<literal>minted</literal>.)
+</para>
+
</sect1>
<sect1 label="8.22" id="table">
<title><literal>table</literal></title>
<indexterm role="fn"><primary>environment, <literal>table</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>table</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>tables, creating</primary></indexterm>
<indexterm role="cp"><primary>creating tables</primary></indexterm>
@@ -3970,6 +4810,7 @@ unless it is pushed to a float page at the end.
<indexterm role="fn"><primary>environment, <literal>tabular</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>tabular</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>lines in tables</primary></indexterm>
<indexterm role="cp"><primary>lining text up in tables</primary></indexterm>
@@ -4326,6 +5167,7 @@ is required.
<indexterm role="fn"><primary>environment, <literal>thebibliography</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>thebibliography</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>bibliography, creating (manually)</primary></indexterm>
<para>Synopsis:
@@ -4339,13 +5181,29 @@ is required.
reference list.
</para>
<para>In the <literal>article</literal> class, this reference list is labelled
-&#8220;References&#8221;; in the <literal>report</literal> class, it is labelled
-&#8220;Bibliography&#8221;. You can change the label (in the standard classes)
-by redefining the command <literal>\refname</literal>. For instance, this
-eliminates it entirely:
+&#8216;<literal>References</literal>&#8217; and the label is stored in macro <literal>\refname</literal>; in
+the <literal>report</literal> class, it is labelled &#8216;<literal>Bibliography</literal>&#8217; and the
+label is stored in macro <literal>\bibname</literal>.
+</para>
+<para>You can change the label by redefining the command <literal>\refname</literal> or
+<literal>\bibname</literal>, whichever is applicable depending on the class:
+</para>
+<itemizedlist><listitem><indexterm role="fn"><primary>\bibname</primary></indexterm>
+<para>For standard classes whose top level sectioning is <literal>\chapter</literal>
+(such as <filename>book</filename> and <filename>report</filename>), the label is in the macro
+<literal>\bibname</literal>;
+</para>
+</listitem><listitem><indexterm role="fn"><primary>\refname</primary></indexterm>
+<para>For standard classes whose the top level sectioning is <literal>\section</literal>
+(such as <filename>article</filename>), the label is in macro <literal>\refname</literal>.
+</para></listitem></itemizedlist>
+<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm>
+
+<para>Typically it is neither necessary nor desirable to directly redefine
+<literal>\refname</literal> or <literal>\bibname</literal>; language support packages like
+<filename>babel</filename> do this.
</para>
-<screen>\renewcommand{\refname}{}
-</screen>
<para>The mandatory <replaceable>widest-label</replaceable> argument is text that, when typeset,
is as wide as the widest item label produced by the <literal>\bibitem</literal>
commands. It is typically given as <literal>9</literal> for bibliographies with
@@ -4465,6 +5323,7 @@ Bib&tex; format. Only the entries referred to via <literal>\cite</literal> and
<indexterm role="fn"><primary>environment, <literal>theorem</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>theorem</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>theorems, typesetting</primary></indexterm>
<para>Synopsis:
@@ -4485,6 +5344,7 @@ possibilities for <replaceable>n</replaceable> are described under <literal>\new
<indexterm role="fn"><primary>environment, <literal>titlepage</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>titlepage</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>making a title page</primary></indexterm>
<indexterm role="cp"><primary>title pages, creating</primary></indexterm>
@@ -4531,6 +5391,7 @@ is left to the author.
<indexterm role="fn"><primary>environment, <literal>verbatim</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>verbatim</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>verbatim text</primary></indexterm>
<indexterm role="cp"><primary>simulating typed text</primary></indexterm>
<indexterm role="cp"><primary>typed text, simulating</primary></indexterm>
@@ -4549,7 +5410,8 @@ which &latex; produces exactly what you type in; for instance the
into a typewriter with carriage returns and blanks having the same
effect that they would on a typewriter.
</para>
-<para>The <literal>verbatim</literal> uses a monospaced typewriter-like font (<literal>\tt</literal>).
+<para>The <literal>verbatim</literal> environment uses a monospaced typewriter-like font
+(<literal>\tt</literal>).
</para>
<sect2 label="8.27.1" id="_005cverb">
@@ -4581,6 +5443,7 @@ verbatim text. The delimiter must not appear in <replaceable>literal-text</repl
<indexterm role="fn"><primary>environment, <literal>verse</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>verse</literal> environment</primary></indexterm>
+
<indexterm role="cp"><primary>poetry, an environment for</primary></indexterm>
<para>Synopsis:
@@ -5085,6 +5948,7 @@ sequence with other footnotes.
</screen>
<indexterm role="cp"><primary>package, <literal>footmisc</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>footmisc</literal> package</primary></indexterm>
+
<indexterm role="cp"><primary><literal>stable</literal> option to <literal>footmisc</literal> package</primary></indexterm>
<para>causes the footnote to appear at the bottom of the page where the
section starts, as usual, but also at the bottom of the table of
@@ -5177,6 +6041,7 @@ footnotes. This is &#8216;<literal>6.65pt</literal>&#8217; for &#8216;<literal>
<para>&latex; has support for making new commands of many different kinds.
</para>
<!-- xx everything in this chapter needs examples. -->
+<!-- xx Add DeclareRobustCommand (see clsguide.pdf) -->
@@ -5681,11 +6546,14 @@ characters in each:
<indexterm role="cp"><primary>fragile commands</primary></indexterm>
<indexterm role="cp"><primary>robust commands</primary></indexterm>
-<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>.
-Footnotes, line breaks, any command that has an optional argument, and
-many more, are fragile. A fragile command can break when it is used in
-the argument to certain commands. To prevent such commands from
-breaking one solution is to have them preceded by the command
+<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. A
+fragile command can break when it is used in the argument to certain
+other commands. Commands that contain data that &latex; writes to an
+auxiliary file and re-reads later are fragile. This includes material
+that goes into a table of contents, list of figures, list of tables,
+etc. Fragile commands also include line breaks, any command that has an
+optional argument, and many more. To prevent such commands from
+breaking, one solution is to preceded them with the command
<literal>\protect</literal>.
</para>
<para>For example, when &latex; runs the <literal>\section{<replaceable>section
@@ -5733,6 +6601,87 @@ to <literal>\protect\(..\protect\)</literal>.
</screen>
</sect1>
+<sect1 label="12.10" id="_005cignorespaces-_0026-_005cignorespacesafterend">
+<title><literal>\ignorespaces &amp; \ignorespacesafterend</literal></title>
+
+<indexterm role="fn"><primary>\ignorespaces</primary></indexterm>
+<indexterm role="fn"><primary>\ignorespacesafterend</primary></indexterm>
+<indexterm role="cp"><primary>spaces, ignore around commands</primary></indexterm>
+<indexterm role="cp"><primary>commands, ignore spaces</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\ignorespaces
+</screen>
+<para>or
+</para>
+<screen>\ignorespacesafterend
+</screen>
+<para>Both commands cause &latex; to ignore spaces after the end of the
+command up until the first non-space character. The first is a command
+from Plain &tex;, and the second is &latex;-specific.
+</para>
+<para>The <literal>ignorespaces</literal> is often used when defining commands via
+<literal>\newcommand</literal>, or <literal>\newenvironment</literal>, or <literal>\def</literal>. The
+example below illustrates. It allows a user to show the points values
+for quiz questions in the margin but it is inconvenient because, as
+shown in the <literal>enumerate</literal> list, users must not put any space between
+the command and the question text.
+</para>
+<screen>\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}}
+\begin{enumerate}
+ \item\points{10}no extra space output here
+ \item\points{15} extra space output between the number and the word `extra'
+\end{enumerate}
+</screen>
+<para>The solution is to change to
+<literal>\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}}\ignorespaces}</literal>.
+</para>
+<para>A second example shows spaces being removed from the front of text. The
+commands below allow a user to uniformly attach a title to names. But,
+as given, if a title accidentally starts with a space then
+<literal>\fullname</literal> will reproduce that.
+</para>
+<screen>\makeatletter
+\newcommand{\honorific}[1]{\def\@honorific{#1}} % remember title
+\newcommand{\fullname}[1]{\@honorific~#1} % recall title; put before name
+\makeatother
+\begin{tabular}{|l|}
+\honorific{Mr/Ms} \fullname{Jones} \\ % no extra space here
+\honorific{ Mr/Ms} \fullname{Jones} % extra space before title
+\end{tabular}
+</screen>
+<para>To fix this, change to
+<literal>\newcommand{\fullname}[1]{\ignorespaces\@honorific~#1}</literal>.
+</para>
+<para>The <literal>\ignorespaces</literal> is also often used in a <literal>\newenvironment</literal>
+at the end of the <replaceable>begin</replaceable> clause, that is, as part of the second
+argument, as in <literal>\begin{newenvironment}{<replaceable>env
+name</replaceable>}{... \ignorespaces}{...}</literal>.
+</para>
+<para>To strip spaces off the end of an environment use
+<literal>\ignorespacesafterend</literal>. An example is that this will show a much
+larger vertical space between the first and second environments than
+between the second and third.
+</para>
+<screen>\newenvironment{eq}{\begin{equation}}{\end{equation}}
+\begin{eq}
+e=mc^2
+\end{eq}
+\begin{equation}
+F=ma
+\end{equation}
+\begin{equation}
+E=IR
+\end{equation}
+</screen>
+<para>Putting a comment character&#160;<literal>%</literal> immediately after the
+<literal>\end{eq}</literal> will make the vertical space disappear, but that is
+inconvenient. The solution is to change to
+<literal>\newenvironment{eq}{\begin{equation}}{\end{equation}\ignorespacesafterend}</literal>.
+</para>
+
+</sect1>
</chapter>
<chapter label="13" id="Counters">
<title>Counters</title>
@@ -5802,14 +6751,17 @@ symbols (conventionally used for labeling footnotes). The value of
</para>
<para>Here are the symbols:
</para>
-<informaltable><tgroup cols="3"><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><thead><row><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Equivalent Unicode symbol and/or numeric code point<!-- -->
-</para></entry></row></thead><tbody><row><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!-- -->
+<informaltable><tgroup cols="3"><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><thead><row><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Equivalent Unicode symbol and/or numeric code point<!--
+ -->
+</para></entry></row></thead><tbody><row><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!--
+ -->
</para></entry></row><row><entry><para>dagger</para></entry><entry><para><literal>\dagger</literal></para></entry><entry><para>&#x2020;
</para></entry></row><row><entry><para>ddagger</para></entry><entry><para><literal>\ddagger</literal></para></entry><entry><para>&#x2021;
</para></entry></row><row><entry><para>section-sign</para></entry><entry><para><literal>\S</literal></para></entry><entry><para>&#x00A7;
</para></entry></row><row><entry><para>paragraph-sign</para></entry><entry><para><literal>\P</literal></para></entry><entry><para>&#x00B6;
</para></entry></row><row><entry><para>double-vert</para></entry><entry><para><literal>\parallel</literal></para></entry><entry><para>&#x2016;
-</para></entry></row><row><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!-- -->
+</para></entry></row><row><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!--
+ -->
</para></entry></row><row><entry><para>double-dagger</para></entry><entry><para><literal>\dagger\dagger</literal></para></entry><entry><para>&#x2020;&#x2020;
</para></entry></row><row><entry><para>double-ddagger</para></entry><entry><para><literal>\ddagger\ddagger</literal></para></entry><entry><para>&#x2021;&#x2021;
</para></entry></row></tbody></tgroup></informaltable>
@@ -6323,10 +7275,13 @@ notes from falling off the bottom of the page.
<indexterm role="cp"><primary>math mode, entering</primary></indexterm>
<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm>
+
<indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm>
+
<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm>
<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm>
+
<para>There are three environments that put &latex; in math mode:
</para>
@@ -6614,7 +7569,7 @@ arrow&#160;<literal>\Downarrow</literal>.
arrow&#160;<literal>\downarrow</literal>.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ell</primary></indexterm><literal>\ell</literal>
-</term><listitem><para>&#x2113; Lower-case cursive letter l (ordinary).
+</term><listitem><para>&#x2113; Lowercase cursive letter l (ordinary).
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\emptyset</primary></indexterm><literal>\emptyset</literal>
</term><listitem><para>&#x2205; Empty set symbol (ordinary). The variant form is
@@ -7940,8 +8895,60 @@ space that does not disappear at line breaks use
</para>
</sect1>
-<sect1 label="19.3" id="_005c_0028SPACE_0029-and-_005c_0040">
-<title><literal>\(SPACE)</literal> and \@</title>
+<sect1 label="19.3" id="_005cspacefactor">
+<title><literal>\spacefactor</literal></title>
+
+<para>Synopsis:
+</para>
+<screen>\spacefactor=<replaceable>integer</replaceable>
+</screen>
+<indexterm role="fn"><primary>\spacefactor</primary></indexterm>
+<para>While &latex; is making the page, to give the lines the best appearance
+it may stretch or shrink the gaps between words. The
+<literal>\spacefactor</literal> command (from Plain&#160;&tex;) allows you to
+change the &latex;&#8217;s default behavior.
+</para>
+<para>After &latex; places each character, or rule or other box, it sets a
+parameter called the <firstterm>space factor</firstterm>. If the next thing in the input
+is a space then this parameter affects how much of a horizontal gap
+&latex; will have it span. (This gap is not a character; it is called
+<firstterm>interword glue</firstterm>.) A larger space factor means that the glue gap
+can stretch more and shrink less.
+</para>
+<para>Normally, the space factor is 1000; this value is in effect following
+most characters, and any non-character box or math formula. But it is
+3000 after a period, exclamation mark, or question mark, it is 2000
+after a colon, 1500 after a semicolon, 1250 after a comma, and 0 after a
+right parenthesis or bracket, or closing double quote or single quote.
+Finally, it is 999 after a capital letter.
+</para>
+<para>If the space factor&#160;<replaceable>f</replaceable> is 1000 then the glue gap will be the
+font&#8217;s normal space value (for Computer Modern Roman 10 point this is
+3.3333&#160;points). Otherwise, if the space factor <replaceable>f</replaceable> is greater
+than 2000 then &tex; adds the font&#8217;s extra space value (for Computer
+Modern Roman 10 point this is 1.11111&#160;points), and then the font&#8217;s
+normal stretch value is multiplied by <inlineequation><mathphrase>f /1000</mathphrase></inlineequation> and the normal
+shrink value is multiplied by <inlineequation><mathphrase>1000/f</mathphrase></inlineequation> (for Computer Modern Roman
+10 point these are 1.66666 and 1.11111&#160;points). In short, compared
+to a normal space, such as the space following a word ending in a
+lowercase letter, inter-sentence spacing has a fixed extra space added
+and then the space can stretch 3 times as much and shrink 1/3 as much.
+</para>
+<para>The rules for how &tex; uses space factors are even more complex
+because they play two more roles. In practice, there are two
+consequences. First, if a period or other punctuation is followed by a
+close parenthesis or close double quote then its effect is still in
+place, that is, the following glue will have increased stretch and
+shrink. Second, conversely, if punctuation comes after a capital letter
+then its effect is not in place so you get an ordinary space. For how
+to adjust to this second case, for instance if an abbreviation does not
+end in a capital letter, see <link linkend="_005c_0028SPACE_0029-and-_005c_0040">\(SPACE) and \@</link>.
+</para>
+
+
+
+<sect2 label="19.3.1" id="_005c_0028SPACE_0029-and-_005c_0040">
+<title><literal>\(SPACE)</literal> and <literal>\@</literal></title>
<indexterm role="fn"><primary>\(SPACE)</primary></indexterm>
<indexterm role="fn"><primary>\TAB</primary></indexterm>
@@ -7949,39 +8956,65 @@ space that does not disappear at line breaks use
<indexterm role="fn"><primary>\@</primary></indexterm>
<anchor id="_005cAT"/><!-- old name -->
-<para>Mark a punctuation character, typically a period, as either ending a
-sentence or as ending an abbreviation.
+<para>Here, <literal>\(SPACE)</literal> means a backslash followed by a space. These
+commands mark a punctuation character, typically a period, as either
+ending a sentence or as ending an abbreviation.
</para>
<para>By default, in justifying a line &latex; adjusts the space after a
sentence-ending period (or a question mark, exclamation point, comma, or
-colon) more than the space between words
-(see <link linkend="_005cfrenchspacing">\frenchspacing</link>). &latex; assumes that the period ends a
-sentence unless it is preceded by a capital letter, in which case it
-takes that period for part of an abbreviation. Note that if a
-sentence-ending period is immediately followed by a right parenthesis or
-bracket, or right single or double quote, then the inter-sentence space
-follows that parenthesis or quote.
-</para>
-<para>If you have a period ending an abbreviation whose last letter is not a
-capital letter, and that abbreviation is not the last word in the
+colon) more than the space between words. See <link linkend="_005cspacefactor">\spacefactor</link>. As
+described there, &latex; assumes that the period ends a sentence unless
+it is preceded by a capital letter, in which case it takes that period
+for part of an abbreviation. Note that if a sentence-ending period is
+immediately followed by a right parenthesis or bracket, or right single
+or double quote, then the space effect of that period follows through
+that parenthesis or quote.
+</para>
+<para>So: if you have a period ending an abbreviation whose last letter is not
+a capital letter, and that abbreviation is not the last word in the
sentence, then follow that period with a backslash-space (<literal>\ </literal>) or
-a tie (<literal>~</literal>). Examples are <literal>Nat.\ Acad.\ Science</literal>, and
-<literal>Mr.~Bean</literal>, and <literal>(manure, etc.)\ for sale</literal>.
-</para>
-<para>For another use of <literal>\ </literal>, see <link linkend="_005c_0028SPACE_0029-after-control-sequence">\(SPACE) after control sequence</link>.
+a tie (<literal>~</literal>) or a <literal>\@</literal>. Examples are <literal>Nat.\ Acad.\
+Science</literal>, and <literal>Mr.~Bean</literal>, and <literal>(manure, etc.\@) for sale</literal>
+(note that in the last the <literal>\@</literal> comes before the closing parenthesis).
</para>
<para>In the opposite situation, if you have a capital letter followed by a
-period that ends the sentence, then put <literal>\@</literal> before that period.
-For example, <literal>book by the MAA\@.</literal> will have inter-sentence
-spacing after the period.
+period that does end the sentence, then put <literal>\@</literal> before the
+period. For example, <literal>book by the MAA\@.</literal> will have correct
+inter-sentence spacing after the period.
</para>
-<para>In contrast, putting <literal>\@</literal> after a period tells &tex; that the
-period does not end the sentence. In the example <literal>reserved words
-(if, then, etc.\@) are different</literal>, &tex; will put interword space
-after the closing parenthesis (note that <literal>\@</literal> is before the
-parenthesis).
+<para>For another use of <literal>\(SPACE)</literal>, see <link linkend="_005c_0028SPACE_0029-after-control-sequence">\(SPACE) after control sequence</link>.
</para>
+</sect2>
+<sect2 label="19.3.2" id="_005cfrenchspacing">
+<title><literal>\frenchspacing</literal></title>
+
+<indexterm role="fn"><primary>\frenchspacing</primary></indexterm>
+<indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm>
+<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm>
+
+<para>This declaration (from Plain &tex;) causes &latex; to treat
+inter-sentence spacing in the same way as interword spacing.
+</para>
+<para>In justifying the text in a line, some typographic traditions, including
+English, prefer to adjust the space between sentences (or after other
+punctuation marks) more than the space between words. Following this
+declaration, all spaces are instead treated equally.
+</para>
+<para>Revert to the default behavior by declaring <literal>\nonfrenchspacing</literal>.
+</para>
+
+</sect2>
+<sect2 label="19.3.3" id="_005cnormalsfcodes">
+<title><literal>\normalsfcodes</literal></title>
+
+<indexterm role="fn"><primary>\normalsfcodes</primary></indexterm>
+<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm>
+
+<para>Reset the &latex; space factor values to the default.
+</para>
+
+</sect2>
</sect1>
<sect1 label="19.4" id="_005c_0028SPACE_0029-after-control-sequence">
<title><literal>\ </literal> after control sequence</title>
@@ -8003,31 +9036,13 @@ by a space or by a punctuation mark. Compare:
</screen>
<indexterm role="cp"><primary>package, <literal>xspace</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>xspace</literal> package</primary></indexterm>
+
<para>Some individual commands, notably those defined with the <literal>xspace</literal>,
package do not follow the standard behavior.
</para>
</sect1>
-<sect1 label="19.5" id="_005cfrenchspacing">
-<title><literal>\frenchspacing</literal></title>
-
-<indexterm role="fn"><primary>\frenchspacing</primary></indexterm>
-<indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm>
-<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm>
-
-<para>This declaration (from Plain &tex;) causes &latex; to treat
-inter-sentence spacing in the same way as interword spacing.
-</para>
-<para>In justifying the text in a line, some typographic traditions, including
-English, prefer to adjust the space between sentences (or after other
-punctuation marks) more than the space between words. Following this
-declaration, all spaces are instead treated equally.
-</para>
-<para>Revert to the default behavior by declaring <literal>\nonfrenchspacing</literal>.
-</para>
-
-</sect1>
-<sect1 label="19.6" id="_005cthinspace">
+<sect1 label="19.5" id="_005cthinspace">
<title><literal>\thinspace</literal>: Insert 1/6em</title>
<indexterm role="fn"><primary>\thinspace</primary></indexterm>
@@ -8038,7 +9053,7 @@ quotes, as in &#8217;&#8221;.<!-- Abuse @dmn, which is a thin space in Texinfo.
</para>
</sect1>
-<sect1 label="19.7" id="_005c_002f">
+<sect1 label="19.6" id="_005c_002f">
<title><literal>\/</literal>: Insert italic correction</title>
<indexterm role="fn"><primary>\/</primary></indexterm>
@@ -8071,7 +9086,7 @@ in a different way.
</para>
</sect1>
-<sect1 label="19.8" id="_005chrulefill-_005cdotfill">
+<sect1 label="19.7" id="_005chrulefill-_005cdotfill">
<title><literal>\hrulefill \dotfill</literal></title>
<indexterm role="fn"><primary>\hrulefill</primary></indexterm>
@@ -8100,7 +9115,7 @@ length of 0.33em to 1.00em.
</para>
</sect1>
-<sect1 label="19.9" id="_005caddvspace">
+<sect1 label="19.8" id="_005caddvspace">
<title><literal>\addvspace</literal></title>
<indexterm role="fn"><primary>\addvspace</primary></indexterm>
@@ -8129,7 +9144,7 @@ change that is to precede this command with a <literal>\par</literal> command.
</para>
</sect1>
-<sect1 label="19.10" id="_005cbigskip-_005cmedskip-_005csmallskip">
+<sect1 label="19.9" id="_005cbigskip-_005cmedskip-_005csmallskip">
<title><literal>\bigskip \medskip \smallskip</literal></title>
<para>These commands produce a given amount of space, specified by the
@@ -8157,7 +9172,7 @@ quarter of a line space, with stretch and shrink (the default for the
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="19.11" id="_005cvfill">
+<sect1 label="19.10" id="_005cvfill">
<title><literal>\vfill</literal></title>
<indexterm role="fn"><primary>\vfill</primary></indexterm>
@@ -8189,7 +9204,7 @@ Lost Dog!
</screen>
</sect1>
-<sect1 label="19.12" id="_005cvspace">
+<sect1 label="19.11" id="_005cvspace">
<title><literal>\vspace{<replaceable>length</replaceable>}</literal></title>
<indexterm role="fn"><primary>\vspace</primary></indexterm>
@@ -8270,8 +9285,8 @@ argument. <!-- xxref -->
<indexterm role="fn"><primary>\fboxrule</primary></indexterm>
<indexterm role="fn"><primary>\fboxsep</primary></indexterm>
<para>Both commands produce a rule of thickness <literal>\fboxrule</literal> (default
-&#8216;<literal>.4pt</literal>&#8217;), and leave a space of <literal>\fboxsep</literal> (default
-&#8216;<literal>3pt</literal>&#8217;) between the rule and the contents of the box.
+<literal>0.4pt</literal>), and leave a space of <literal>\fboxsep</literal> (default <literal>3pt</literal>)
+between the rule and the contents of the box.
</para>
<para>See <link linkend="_005cframebox-_0028picture_0029">\framebox (picture)</link>, for the <literal>\framebox</literal> command in the
<literal>picture</literal> environment.
@@ -8335,8 +9350,9 @@ see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link>.
</para>
<screen>\parbox[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>}{<replaceable>text</replaceable>}
</screen>
+<indexterm role="cp"><primary>paragraph mode</primary></indexterm>
<para>The <literal>\parbox</literal> command produces a box whose contents are created
-in <literal>paragraph</literal> mode. It should be used to make a box small
+in <firstterm>paragraph mode</firstterm>. It should be used to make a box small
pieces of text, with nothing fancy inside. In particular, you
shouldn&#8217;t use any paragraph-making environments inside a
<literal>\parbox</literal> argument. For larger pieces of text, including ones
@@ -8444,7 +9460,1130 @@ included in the normal output, it is saved in the box labeled
</sect1>
</chapter>
-<chapter label="21" id="Special-insertions">
+<chapter label="21" id="Color">
+<title>Color</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+
+<para>You can add color to text, rules, etc. You can also have color in a box
+or on an entire page and write text on top of it.
+</para>
+<para>Color support comes as an additional package. So all the commands below
+will only work if your document preamble contains
+<literal>\usepackage{color}</literal>, that brings in the standard package.
+</para>
+<para>Many other packages also supplement &latex;&#8217;s color abilities.
+Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and
+significantly extends the capabilities described here, including adding
+&#8216;<literal>HTML</literal>&#8217; and &#8216;<literal>Hsb</literal>&#8217; color models.
+</para>
+
+
+<sect1 label="21.1" id="Color-package-options">
+<title>Color package options</title>
+
+<indexterm role="cp"><primary>color package options</primary></indexterm>
+<indexterm role="cp"><primary>options, color package</primary></indexterm>
+
+<para>Synopsis (must be in the document preamble):
+</para>
+<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{color}
+</screen>
+<para>When you load the <filename>color</filename> package there are two kinds of available
+options.
+</para>
+<para>The first specifies the <firstterm>printer driver</firstterm>. &latex; doesn&#8217;t contain
+information about different output systems but instead depends on
+information stored in a file. Normally you should not specify the
+driver option in the document, and instead rely on your system&#8217;s
+default. One advantage of this is that it makes the document portable
+across systems. For completeness we include a list of the drivers. The
+currently relevant ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>,
+<filename>dvisvgm</filename>, <filename>luatex</filename>, <filename>pdftex</filename>, <filename>xetex</filename>. The two
+<filename>xdvi</filename> and <filename>oztex</filename> are essentially aliases for <filename>dvips</filename>
+(and <filename>xdvi</filename> is monochrome). Ones that should not be used for new
+systems are: <filename>dvipdf</filename>, <filename>dvipdfm</filename>, <filename>dviwin</filename>,
+<filename>dvipsone</filename>, <filename>emtex</filename>, <filename>pctexps</filename>, <filename>pctexwin</filename>,
+<filename>pctexhp</filename>, <filename>pctex32</filename>, <filename>truetex</filename>, <filename>tcidvi</filename>,
+<filename>vtex</filename> (and <filename>dviwindo</filename> is an alias for <filename>dvipsone</filename>).
+</para>
+<para>The second kind of options, beyond the drivers, are below.
+</para>
+<variablelist>
+<varlistentry><term><literal>monochrome</literal>
+</term><listitem><para>Disable the color commands, so that they do not generate errors but do
+not generate color either.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>dvipsnames</literal>
+</term><listitem><para>Make available a list of 68 color names that are often used,
+particularly in legacy documents. These color names were originally
+provided by the <filename>dvips</filename> driver, giving the option name.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>nodvipsnames</literal>
+</term><listitem><para>Do not load that list of color names, saving &latex; a tiny amount of
+memory space.
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect1>
+<sect1 label="21.2" id="Color-models">
+<title>Color models</title>
+
+<indexterm role="cp"><primary>color models</primary></indexterm>
+
+<para>A <firstterm>color model</firstterm> is a way of representing colors. &latex;&#8217;s
+capabilities depend on the printer driver. However, the <filename>pdftex</filename>,
+<filename>xetex</filename>, and <filename>luatex</filename> printer drivers are today by far the
+most commonly used. The models below work for those drivers. All but
+one of these is also supported by essentially all other printer drivers
+used today.
+</para>
+<para>Note that color combination can be additive or subtractive. Additive
+mixes colors of light, so that for instance combining full intensities
+of red, green, and blue produces white. Subtractive mixes pigments,
+such as with inks, so that combining full intensity of cyan, magenta,
+and yellow makes black.
+</para>
+<variablelist><varlistentry><term><literal>cmyk</literal>
+</term><listitem><para>A comma-separated list with four real numbers between 0 and 1,
+inclusive. The first number is the intensity of cyan, the second is
+magenta, and the others are yellow and black. A number value of 0 means
+minimal intensity, while a 1 is for full intensity. This model is often
+used in color printing. It is a subtractive model.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>gray</literal>
+</term><listitem><para>A single real number between 0 and 1, inclusive. The colors are shades
+of grey. The number 0 produces black while 1 gives white.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>rgb</literal>
+</term><listitem><para>A comma-separated list with three real numbers between 0 and 1,
+inclusive. The first number is the intensity of the red component, the
+second is green, and the third the blue. A number value of 0 means that
+none of that component is added in, while a 1 means full intensity.
+This is an additive model.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>RGB</literal>
+</term><listitem><para>(<filename>pdftex</filename>, <filename>xetex</filename>, <filename>luatex</filename> drivers) A comma-separated
+list with three integers between 0 and 255, inclusive. This model is a
+convenience for using <literal>rgb</literal> since outside of &latex; colors are
+often described in a red-green-blue model using numbers in this range.
+The values entered here are converted to the <literal>rgb</literal> model by
+dividing by 255.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>named</literal>
+</term><listitem><para>Colors are accessed by name, such as &#8216;<literal>PrussianBlue</literal>&#8217;. The list of
+names depends on the driver, but all support the names &#8216;<literal>black</literal>&#8217;,
+&#8216;<literal>blue</literal>&#8217;, &#8216;<literal>cyan</literal>&#8217;, &#8216;<literal>green</literal>&#8217;, &#8216;<literal>magenta</literal>&#8217;, &#8216;<literal>red</literal>&#8217;,
+&#8216;<literal>white</literal>&#8217;, and &#8216;<literal>yellow</literal>&#8217; (See the <literal>dvipsnames</literal> option in
+<link linkend="Color-package-options">Color package options</link>).
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect1>
+<sect1 label="21.3" id="Commands-for-color">
+<title>Commands for color</title>
+
+<indexterm role="cp"><primary>color package commands</primary></indexterm>
+
+<para>These are the commands available with the <filename>color</filename> package.
+</para>
+
+
+<sect2 label="21.3.1" id="Define-colors">
+<title>Define colors</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>define color</primary></indexterm>
+<indexterm role="cp"><primary>color, define</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\definecolor{<replaceable>name</replaceable>}{<replaceable>model</replaceable>}{<replaceable>specification</replaceable>}
+</screen>
+<para>Give the name <replaceable>name</replaceable> to the color. For example, after
+<literal>\definecolor{silver}{rgb}{0.75,0.75,0.74}</literal> you can use that
+color name with <literal>Hi ho, \textcolor{silver}{Silver}!</literal>.
+</para>
+<para>This example gives the color a more abstract name, so it could change and
+not be misleading.
+</para>
+<screen>\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex
+\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}}
+</screen>
+<para>Often a document&#8217;s colors are defined in the preamble, or in the class
+or style, rather than in the document body.
+</para>
+
+</sect2>
+<sect2 label="21.3.2" id="Colored-text">
+<title>Colored text</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored text</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\textcolor{<replaceable>name</replaceable>}{...}
+\textcolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}{...}
+</screen>
+<para>or
+</para>
+<screen>\color{<replaceable>name</replaceable>}
+\color[<replaceable>color model</replaceable>]{<replaceable>specification</replaceable>}
+</screen>
+<para>The affected text gets the color. This line
+</para>
+<screen>\textcolor{magenta}{My name is Ozymandias, king of kings:} Look on my works, ye Mighty, and despair!
+</screen>
+<para>causes the first half to be in magenta while the rest is in black. You
+can use a color declared with <literal>\definecolor</literal> in exactly the same
+way that we just used the builtin color &#8216;<literal>magenta</literal>&#8217;.
+</para>
+<screen>\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0}
+I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}.
+</screen>
+<para>The two <literal>\textcolor</literal> and <literal>\color</literal> differ in that the first is
+a command form, enclosing the text to be colored as an argument. Often
+this form is more convenient, or at least more explicit. The second
+form is a declaration, as in <literal>The moon is made of {\color{green}
+green} cheese</literal>, so it is in effect until the end of the current group
+or environment. This is sometimes useful when writing macros or as
+below where it colors everything inside the <literal>center</literal> environment,
+including the vertical and horizontal lines.
+</para>
+<screen>\begin{center} \color{blue}
+ \begin{tabular}{l|r}
+ UL &amp;UR \\ \hline
+ LL &amp;LR
+ \end{tabular}
+\end{center}
+</screen>
+<para>You can use color in equations. A document might have
+<literal>\definecolor{highlightcolor}{RGB}{225,15,0}</literal> in the
+preamble, and then contain this equation.
+</para>
+<screen>\begin{equation}
+ \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a)
+\end{equation}
+</screen>
+<para>Typically the colors used in a document are declared in a class or style
+but sometimes you want a one-off. Those are the second forms in the
+synopses.
+</para>
+<screen>Colors of \textcolor[rgb]{0.33,0.14,0.47}{Purple} and {\color[rgb]{0.72,0.60,0.37} Gold} for the team
+</screen>
+<para>The format of <replaceable>color specification </replaceable> depends on the color model
+(see <link linkend="Color-models">Color models</link>). For instance, while <literal>rgb</literal> takes three
+numbers, <literal>gray</literal> takes only one.
+</para>
+<screen>The selection was \textcolor[gray]{0.5}{grayed out}.
+</screen>
+<para>Colors inside colors do not combine. Thus
+</para>
+<screen>\textcolor{green}{kind of \textcolor{blue}{blue}}
+</screen>
+<para>has a final word that is blue, not a combination of blue and green.
+</para>
+<!-- xx address coloring a line of a table? -->
+
+
+</sect2>
+<sect2 label="21.3.3" id="Colored-boxes">
+<title>Colored boxes</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored boxes</primary></indexterm>
+<indexterm role="cp"><primary>box, colored</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\colorbox{<replaceable>name</replaceable>}{...}
+\colorbox[<replaceable>model name</replaceable>]{<replaceable>box background color specification</replaceable>}{...}
+</screen>
+<para>or
+</para>
+<screen>\fcolorbox{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...}
+\fcolorbox[<replaceable>model name</replaceable>]{<replaceable>frame color specification</replaceable>}{<replaceable>box background color specification</replaceable>}{...}
+</screen>
+<para>Make a box with the stated background color. The <literal>\fcolorbox</literal>
+command puts a frame around the box. For instance this
+</para>
+<screen>Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}}
+</screen>
+<para>makes a cyan-colored box that is five centimeters long and gets its
+depth and height from the <literal>\strut</literal> (so the depth is
+<literal>-.3\baselineskip</literal> and the height is <literal>\baselineskip</literal>). This
+puts white text on a blue background.
+</para>
+<screen>\colorbox{blue}{\textcolor{white}{Welcome to the machine.}}
+</screen>
+<para>The <literal>\fcolorbox</literal> commands use the same parameters as <literal>\fbox</literal>
+(see <link linkend="_005cfbox-and-_005cframebox">\fbox and \framebox</link>), <literal>\fboxrule</literal> and <literal>\fboxsep</literal>, to
+set the thickness of the rule and the boundary between the box interior
+and the surrounding rule. &latex;&#8217;s defaults are <literal>0.4pt</literal> and
+<literal>3pt</literal>, respectively.
+</para>
+<para>This example changes the thickness of the border to 0.8 points. Note
+that it is surrounded by curly braces so that the change ends at the end
+of the second line.
+</para>
+<screen>{\setlength{\fboxrule}{0.8pt}
+\fcolorbox{black}{red}{Under no circumstances turn this knob.}}
+</screen>
+
+</sect2>
+<sect2 label="21.3.4" id="Colored-pages">
+<title>Colored pages</title>
+
+<indexterm role="cp"><primary>color</primary></indexterm>
+<indexterm role="cp"><primary>colored page</primary></indexterm>
+<indexterm role="cp"><primary>page, colored</primary></indexterm>
+<indexterm role="cp"><primary>background, colored</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\pagecolor{<replaceable>name</replaceable>}
+\pagecolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}
+\nopagecolor
+</screen>
+<para>The first two set the background of the page, and all subsequent pages,
+to the color. For an explanation of the specification in the second
+form see <link linkend="Colored-text">Colored text</link>. The third returns the background to normal,
+which is a transparent background. (If that is not supported use
+<literal>\pagecolor{white}</literal>, although that will make a white background
+rather than the default transparent background.)
+</para>
+<screen> ...
+\pagecolor{cyan}
+ ...
+\nopagecolor
+</screen>
+
+</sect2>
+</sect1>
+</chapter>
+<chapter label="22" id="Graphics">
+<title>Graphics</title>
+
+<indexterm role="cp"><primary>graphics</primary></indexterm>
+<indexterm role="cp"><primary>graphics package</primary></indexterm>
+
+<para>You can use graphics such as PNG or PDF files in your &latex; document.
+You need an additional package, which comes standard with &latex;.
+This example is the short how-to.
+</para>
+<screen>\include{graphicx} % goes in the preamble
+ ...
+\includegraphics[width=0.5\linewidth]{plot.pdf}
+</screen>
+<para>To use the commands described here your document preamble must contain
+either <literal>\usepackage{graphicx}</literal> or
+<literal>\usepackage{graphics}</literal>. Most of the time, <filename>graphicx</filename> is the
+better choice.
+</para>
+<para>Graphics come in two main types, raster and vector. &latex; can use
+both. In raster graphics the file contains an entry for each location
+in an array, describing what color it is. An example is a photograph,
+in JPG format. In vector graphics, the file contains a list of
+instructions such as &#8216;<literal>draw a circle with this radius and that
+center</literal>&#8217;. An example is a line drawing produced by the Asymptote
+program, in PDF format. Generally vector graphics are more useful
+because you can rescale their size without pixelation or other problems,
+and because they often have a smaller size.
+</para>
+<para>There are systems particularly well-suited to make graphics for a
+&latex; document. For example, these allow you to use the same fonts
+as in your document. &latex; comes with a <literal>picture</literal> environment
+(see <link linkend="picture">picture</link>) that has simple capabilities. Besides that, there are
+other ways to include the graphic-making commands in the document. Two
+such systems are the PSTricks and TikZ packages. There are also systems
+external to &latex;, that generate a graphic that you include using the
+commands of this chapter. Two that use a programming language are
+Asymptote and MetaPost. One that uses a graphical interface is Xfig.
+Full description of these systems is outside the scope of this document;
+see their documentation.
+</para>
+
+
+<sect1 label="22.1" id="Graphics-package-options">
+<title>Graphics package options</title>
+
+<indexterm role="cp"><primary>graphics package options</primary></indexterm>
+<indexterm role="cp"><primary>options, graphics package</primary></indexterm>
+
+<para>Synopsis (must be in the document preamble):
+</para>
+<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphics}
+</screen>
+<para>or
+</para>
+<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphicx}
+</screen>
+<para>The <literal>graphicx</literal> package has a format for optional arguments to the
+<literal>\includegraphics</literal> command that is convenient (it is the key-value
+format), so it is the better choice for new documents. When you load
+the <filename>graphics</filename> or <filename>graphicx</filename> package with <literal>\usepackage</literal>
+there are two kinds of available options.
+</para>
+<para>The first is that &latex; does not contain information about different
+output systems but instead depends on information stored in a
+<firstterm>printer driver</firstterm> file. Normally you should not specify the driver
+option in the document, and instead rely on your system&#8217;s default. One
+advantage of this is that it makes the document portable across systems.
+</para>
+<para>For completeness here is a list of the drivers. The currently relevant
+ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>, <filename>dvisvgm</filename>, <filename>luatex</filename>,
+<filename>pdftex</filename>, <filename>xetex</filename>. The two <filename>xdvi</filename> and <filename>oztex</filename> are
+essentially aliases for <filename>dvips</filename> (and <filename>xdvi</filename> is monochrome).
+Ones that should not be used for new systems are: <filename>dvipdf</filename>,
+<filename>dvipdfm</filename>, <filename>dviwin</filename>, <filename>dvipsone</filename>, <filename>emtex</filename>,
+<filename>pctexps</filename>, <filename>pctexwin</filename>, <filename>pctexhp</filename>, <filename>pctex32</filename>,
+<filename>truetex</filename>, <filename>tcidvi</filename>, <filename>vtex</filename> (and <filename>dviwindo</filename> is an
+alias for <filename>dvipsone</filename>). These are stored in files with a
+<filename>.def</filename> extension, such as <filename>pdftex.def</filename>.
+</para>
+<para>The second kind of options are below.
+</para>
+<variablelist><varlistentry><term><literal>demo</literal>
+</term><listitem><para>Instead of an image file, &latex; puts in a 150&#160;pt by 100&#160;pt
+rectangle (unless another size is specified in the
+<literal>\includegraphics</literal> command).
+</para>
+</listitem></varlistentry><varlistentry><term><literal>draft</literal>
+</term><listitem><para>For each graphic file, it is not shown but instead the file name is
+printed in a box of the correct size. In order to determine the size,
+the file must be present.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>final</literal>
+</term><listitem><para>(Default) Override any previous <literal>draft</literal> option, so that the
+document shows the contents of the graphic files.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>hiderotate</literal>
+</term><listitem><para>Do not show rotated text. (This allows for the possibility that a
+previewer does not have the capability to rotate text.)
+<!-- what does it show? -->
+</para>
+</listitem></varlistentry><varlistentry><term><literal>hidescale</literal>
+</term><listitem><para>Do not show scaled text. (This allows for the possibility that a
+previewer does not have the capability to scale.)
+<!-- what does it show? -->
+</para>
+</listitem></varlistentry><varlistentry><term><literal>hiresbb</literal>
+</term><listitem><para>In a PS or EPS file the graphic size may be specified in two ways. The
+<literal>%%BoundingBox</literal> lines describe the graphic size using integer
+multiples of a PostScript point, that is, integer multiples of 1/72
+inch. A later addition to the PostScript language allows decimal
+multiples, such as 1.23, in <literal>%%HiResBoundingBox</literal> lines. This
+option has &latex; to read the size from the latter.
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect1>
+<sect1 label="22.2" id="Graphics-package-configuration">
+<title>Graphics package configuration</title>
+
+<indexterm role="cp"><primary>graphics</primary></indexterm>
+<indexterm role="cp"><primary>graphics package</primary></indexterm>
+<indexterm role="cp"><primary>configuration, graphics package</primary></indexterm>
+<indexterm role="cp"><primary>EPS files</primary></indexterm>
+<indexterm role="cp"><primary>JPEG files</primary></indexterm>
+<indexterm role="cp"><primary>JPG files</primary></indexterm>
+<indexterm role="cp"><primary>PDF graphic files</primary></indexterm>
+<indexterm role="cp"><primary>PNG files</primary></indexterm>
+
+<para>These commands configure the way &latex; searches the file system for
+the graphic.
+</para>
+<para>The behavior of file system search code is necessarily platform
+dependent. In this document we cover Linux, Macintosh, and Windows, as
+those systems are typically configured. For other situations consult
+the documentation in <filename>grfguide.pdf</filename>, or the &latex; source, or your
+&tex; distribution&#8217;s documentation.
+</para>
+
+
+<sect2 label="22.2.1" id="_005cgraphicspath">
+<title><literal>\graphicspath</literal></title>
+
+<indexterm role="fn"><primary>\graphicspath</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\graphicspath{<replaceable>list of dir names inside curly brackets</replaceable>}
+</screen>
+<para>Declare a list of directories to search for graphics files. This allows
+you to later say something like <literal>\includegraphics{lion.png}</literal>
+instead of having to give its path.
+</para>
+<para>&latex; always looks for graphic files first in the current directory.
+The declaration below tells the system to then look in the subdirectory
+<filename>pix</filename>, and then <filename>../pix</filename>.
+</para>
+<screen>\usepackage{graphicx} % or graphics; put in preamble
+ ...
+\graphicspath{ {pix/} {../pix/} }
+</screen>
+<para>The <literal>\graphicspath</literal> declaration is optional. If you don&#8217;t include
+it then &latex;&#8217;s default is to search all of the places that it
+usually looks for a file (it uses &latex;&#8217;s <literal>\input@path</literal>). In
+particular, in this case one of the places it looks is the current
+directory.
+</para>
+<para>Enclose each directory name in curly braces; for example, above it says
+&#8216;<literal><literal>{pix}</literal></literal>&#8217;. Do this even if there is only one directory.
+Each directory name must end in a forward slash, <filename>/</filename>. This is true
+even on Windows, where good practice is to use forward slashes for all
+the directory separators since it makes the document portable to other
+platforms. If you have spaces in your directory name then use double
+quotes, as with <literal>{&quot;my docs/&quot;}</literal>. Getting one of these rules wrong
+will cause &latex; to report <literal>Error: File `<replaceable>filename</replaceable>' not
+found</literal>.
+</para>
+<para>Basically, the algorithm is that with this example, after looking in the
+current directory,
+</para>
+<screen>\graphicspath{ {pix/} {../pix/} }
+...
+\usepackage{lion.png}
+</screen>
+<para>for each of the listed directories, &latex; concatenates it with the
+file name and searches for the result, checking for <filename>pix/lion.png</filename>
+and then <filename>../pix/lion.png</filename>. This algorithm means that the
+<literal>\graphicspath</literal> command does not recursively search subdirectories:
+if you issue <literal>\graphicspath{{a/}}</literal> and the graphic is in
+<filename>a/b/lion.png</filename> then &latex; will not find it. It also means that
+you can use absolute paths such as
+<literal>\graphicspath{{/home/jim/logos/}}</literal> or
+<literal>\graphicspath{{C:/Users/Albert/Pictures/}}</literal>. However, using
+these means that the document is not portable. (You could preserve
+portability by adjusting your &tex; system settings configuration file
+parameter <literal>TEXINPUTS</literal>; see the documentation of your system.)
+</para>
+<para>You can use <literal>\graphicspath</literal> in the preamble or in the document
+body. You can use it more than once. For debugging, show its value
+with <literal>\makeatletter\typeout{\Ginput@path}\makeatother</literal>.
+</para>
+<para>The directories are taken with respect to the base file. That is,
+suppose that you are working on a document based on <filename>book/book.tex</filename>
+and it contains <literal>\include{chapters/chap1}</literal>. If in
+<filename>chap1.tex</filename> you put <literal>\graphicspath{{plots/}}</literal> then
+&latex; will not search for graphics in <filename>book/chapters/plots</filename>, but
+instead in <filename>book/plots</filename>.
+</para>
+
+</sect2>
+<sect2 label="22.2.2" id="_005cDeclareGraphicsExtensions">
+<title><literal>\DeclareGraphicsExtensions</literal></title>
+
+<indexterm role="fn"><primary>\DeclareGraphicsExtensions</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\DeclareGraphicsExtensions{<replaceable>comma-separated list of file extensions</replaceable>}
+</screen>
+<para>Declare the filename extensions to try. This allows you to specify the
+order in which to choose graphic formats when you include graphic files
+by giving the filename without the extension, as in
+<literal>\includegraphics{functionplot}</literal>.
+</para>
+<para>In this example, &latex; will find files in the PNG format before PDF
+files.
+</para>
+<screen>\DeclareGraphicsExtensions{.png,PNG,.pdf,.PDF}
+ ...
+\includegraphics{lion} % will find <filename>lion.png</filename> before <filename>lion.pdf</filename>
+</screen>
+<para>Because the file name <filename>lion</filename> does not have a period, &latex; uses
+the extension list. For each directory in the graphics path
+(see <link linkend="_005cgraphicspath">\graphicspath</link>), &latex; will try the extensions in the order
+given. If it does not find such a file after trying all the directories
+and extensions then it reports &#8216;<literal>! LaTeX Error: File `<filename>lion</filename>'
+not found</literal>&#8217;. Note that you must include the periods at the start of the
+extensions.
+</para>
+<para>Because Linux and Macintosh filenames are case sensitive, the list of
+file extensions is case sensitive on those platforms. The Windows
+platform is not case sensitive.
+</para>
+<para>You are not required to include <literal>\DeclareGraphicsExtensions</literal> in
+your document; the printer driver has a sensible default. For example,
+the most recent <filename>pdftex.def</filename> has the extension list
+&#8216;<literal><literal>.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2</literal></literal>&#8217;.
+</para>
+<para>You can use this command in the preamble or in the document body. You
+can use it more than once. For debugging, show its value with
+<literal>\makeatletter\typeout{\Gin@extensions}\makeatother</literal>.
+</para>
+
+</sect2>
+<sect2 label="22.2.3" id="_005cDeclareGraphicsRule">
+<title><literal>\DeclareGraphicsRule</literal></title>
+
+<indexterm role="fn"><primary>\DeclareGraphicsRule</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\DeclareGraphicsRule{<replaceable>extension</replaceable>}{<replaceable>type</replaceable>}{<replaceable>size-file extension</replaceable>}{<replaceable>command</replaceable>}
+</screen>
+<para>Declare how to handle graphic files whose names end in <replaceable>extension</replaceable>.
+</para>
+<para>This example declares that all files with names have the form
+<filename>filename-without-dot.mps</filename> will be treated as output from MetaPost,
+meaning that the printer driver will use its MetaPost-handling code to
+input the file.
+</para>
+<screen>\DeclareGraphicsRule{.mps}{mps}{.mps}{}
+</screen>
+<para>This
+</para>
+<screen>\DeclareGraphicsRule{*}{mps}{*}{}
+</screen>
+<para>tells &latex; that it should handle as MetaPost output any file with an
+extension not covered by another rule, so it covers <filename>filename.1</filename>,
+<filename>filename.2</filename>, etc.
+</para>
+<para>This describes the four arguments.
+</para>
+<variablelist><varlistentry><term><replaceable>extension</replaceable>
+</term><listitem><para>The file extension to which this rule applies. The extension is anything
+after and including the first dot in the filename. Use the Kleene star,
+<literal>*</literal>, to denote the default behaviour for all undeclared extensions.
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>type</replaceable>
+</term><listitem><para>The type of file involved. This type is a string that must be defined
+in the printer driver. For instance, files with extensions <filename>.ps</filename>,
+<filename>.eps</filename>, or <filename>.ps.gz</filename> may all be classed as type <literal>eps</literal>.
+All files of the same type will be input with the same internal command
+by the printer driver. For example, the file types that <filename>pdftex</filename>
+recognizes are: <literal>jpg</literal>, <literal>jbig2</literal>, <literal>mps</literal>, <literal>pdf</literal>,
+<literal>png</literal>, <literal>tif</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>size-file extension</replaceable>
+</term><listitem><para>The extension of the file to be read to determine the size of the
+graphic, if there is such a file. It may be the same as <replaceable>extension</replaceable>
+but it may be different.
+</para>
+<para>As an example, consider a PostScript graphic. To make it smaller, it
+might be compressed into a <filename>.ps.gz</filename> file. Compressed files are not
+easily read by &latex; so you can put the bounding box information in a
+separate file. If <replaceable>size-file extension</replaceable> is empty then you must
+specify size information in the arguments of <literal>\includegraphics</literal>.
+</para>
+<para>If the driver file has a procedure for reading size files for
+<literal>type</literal> then that will be used, otherwise it will use the procedure
+for reading <filename>.eps</filename> files. (Thus you may specify the size of bitmap
+files in a file with a PostScript style <literal>%%BoundingBox</literal> line if no
+other format is available.)
+</para>
+</listitem></varlistentry><varlistentry><term><replaceable>command</replaceable>
+</term><listitem><para>A command that will be applied to the
+file. This is very often left blank. This command must start with a
+single backward quote. Thus,
+<literal>\DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c
+#1}</literal> specifies that any file with the extension <filename>.eps.gz</filename> should
+be treated as an <literal>eps</literal> file, with the the BoundingBox information
+stored in the file with extension <filename>.eps.bb</filename>, and that the command
+<literal>gunzip -c</literal> will run on your platform to decompresses the file.
+</para>
+<para>Such a command is specific to your platform. In addition, your &tex;
+system must allow you to run external commands; as a security measure
+modern systems restrict running commands unless you explicitly allow it.
+See the documentation for your &tex; distribution.
+</para>
+</listitem></varlistentry></variablelist>
+</sect2>
+</sect1>
+<sect1 label="22.3" id="Commands-for-graphics">
+<title>Commands for graphics</title>
+
+<indexterm role="cp"><primary>graphics package commands</primary></indexterm>
+<indexterm role="cp"><primary>commands, graphics package</primary></indexterm>
+
+<para>These are the commands available with the <filename>graphics</filename> and
+<filename>graphicx</filename> packages.
+</para>
+
+
+<sect2 label="22.3.1" id="_005cincludegraphics">
+<title><literal>\includegraphics</literal></title>
+
+<indexterm role="cp"><primary>graphics</primary></indexterm>
+<indexterm role="cp"><primary>graphics package</primary></indexterm>
+<indexterm role="cp"><primary>including graphics</primary></indexterm>
+<indexterm role="cp"><primary>importing graphics</primary></indexterm>
+<indexterm role="cp"><primary>EPS files</primary></indexterm>
+<indexterm role="cp"><primary>JPEG files</primary></indexterm>
+<indexterm role="cp"><primary>JPG files</primary></indexterm>
+<indexterm role="cp"><primary>PDF graphic files</primary></indexterm>
+<indexterm role="cp"><primary>PNG files</primary></indexterm>
+<indexterm role="fn"><primary>\includegraphics</primary></indexterm>
+
+<para>Synopses for <filename>graphics</filename> package:
+</para>
+<screen>\includegraphics{<replaceable>filename</replaceable>}
+\includegraphics[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>}
+\includegraphics[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>}
+\includegraphics*{<replaceable>filename</replaceable>}
+\includegraphics*[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>}
+\includegraphics*[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>}
+</screen>
+<para>Synopses for <filename>graphicx</filename> package:
+</para>
+<screen>\includegraphics{<replaceable>filename</replaceable>}
+\includegraphics[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>}
+\includegraphics*{<replaceable>filename</replaceable>}
+\includegraphics*[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>}
+</screen>
+<para>Include a graphics file. The starred form <literal>\includegraphics*</literal> will
+clip the graphic to the size specified, while for the unstarred form any
+part of the graphic that is outside the box of the specified size will
+over-print the surrounding area.
+</para>
+<para>This
+</para>
+<screen>\usepackage{graphicx} % in preamble
+ ...
+\begin{center}
+ \includegraphics{plot.pdf}
+\end{center}
+</screen>
+<para>will incorporate into the document the graphic in <filename>plot.pdf</filename>,
+centered and at its nominal size. You can also give a path to the file,
+as with <literal>\includegraphics{graphics/plot.pdf}</literal>. To specify a list
+of locations to search for the file, see <link linkend="_005cgraphicspath">\graphicspath</link>.
+</para>
+<para>If your filename includes spaces then put it in double quotes, as with
+<literal>\includegraphics{&quot;sister picture.jpg&quot;}</literal>.
+</para>
+<para>The <literal>\includegraphics{<replaceable>filename</replaceable>}</literal> command decides on the
+type of graphic by splitting <replaceable>filename</replaceable> on the first dot. You can
+use <replaceable>filename</replaceable> with no dot, as in <literal>\includegraphics{turing}</literal>
+and then &latex; tries a sequence of extensions such as <literal>.png</literal> and
+<literal>.pdf</literal> until it finds a file with that extension
+(see <link linkend="_005cDeclareGraphicsExtensions">\DeclareGraphicsExtensions</link>).
+</para>
+<para>If your file name contains dots before the extension then you can hide
+them with curly braces, as in
+<literal>\includegraphics{{plot.2018.03.12.a}.pdf}</literal>. Or, if you use
+the <filename>graphicx</filename> package then you can use the options <literal>type</literal> and
+<literal>ext</literal>; see below. This and other filename issues are also handled
+with the package <filename>grffile</filename>.
+</para>
+<para>This example puts a graphic in a figure environment so &latex; can
+move it to the next page if fitting it on the current page is awkward
+(see <link linkend="figure">figure</link>).
+</para>
+<screen>\begin{figure}
+ \centering
+ \includegraphics[width=3cm]{lungxray.jpg}
+ \caption{The evidence is overwhelming: don't smoke.} \label{fig:xray}
+\end{figure}
+</screen>
+<para>This places a graphic that will not float, so it is sure to appear at
+this point in the document even if makes &latex; stretch the text or
+resort to blank areas on the page. It will be centered and will have a
+caption.
+</para>
+<screen>\usepackage{caption} % in preamble
+ ...
+\begin{center}
+ \includegraphics{pix/nix.png}
+ \captionof{figure}{The spirit of the night} \label{pix:nix} % if you want a caption
+\end{center}
+</screen>
+<para>This example puts a box with a graphic side by side with one having
+text, with the two vertically centered.
+</para>
+<screen>\newcommand*{\vcenteredhbox}[1]{\begingroup
+ \setbox0=\hbox{#1}\parbox{\wd0}{\box0}\endgroup}
+ ...
+\begin{center}
+ \vcenteredhbox{\includegraphics[width=0.4\textwidth]{plot}}
+ \hspace{1em}
+ \vcenteredhbox{\begin{minipage}{0.4\textwidth}
+ \begin{displaymath}
+ f(x)=x\cdot \sin (1/x)
+ \end{displaymath}
+ \end{minipage}}
+\end{center}
+</screen>
+<para>If you use the <filename>graphics</filename> package then the only options involve the
+size of the graphic (but see <link linkend="_005crotatebox">\rotatebox</link> and <link linkend="_005cscalebox">\scalebox</link>).
+When one optional argument is present then it is
+<literal>[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]</literal> and it gives the coordinates of the top
+right corner of the image, as a pair of &tex; dimensions (see <link linkend="Units-of-length">Units
+of length</link>). If the units are omitted they default to <literal>bp</literal>. In
+this case, the lower left corner of the image is assumed to be at (0,0).
+If two optional arguments are present then the leading one is
+<literal>[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>]</literal>, specifying the coordinates of the image&#8217;s
+lower left. Thus, <literal>\includegraphics[1in,0.618in]{...}</literal> calls for
+the graphic to be placed so it is 1&#160;inch wide and 0.618&#160;inches
+tall and so its origin is at (0,0).
+</para>
+<para>The <filename>graphicx</filename> package gives you many more options. Specify them
+in a key-value form, as here.
+</para>
+<screen>\begin{center}
+ \includegraphics[width=1in,angle=90]{lion}
+ \hspace{2em}
+ \includegraphics[angle=90,width=1in]{lion}
+\end{center}
+</screen>
+<para>The options are read left-to-right. So the first graphic above is made
+one inch wide and then rotated, while the second is rotated and then
+made one inch wide. Thus, unless the graphic is perfectly square, the
+two will end with different widths and heights.
+</para>
+<para>There are many options. The primary ones are listed first.
+</para>
+<para>Note that a graphic is placed by &latex; into a box, which is
+traditionally referred to as its bounding box (distinct from the
+PostScript BoundingBox described below). The graphic&#8217;s printed area may
+go beyond this box, or sit inside this box, but when &latex; makes up a
+page it puts together boxes and this is the box allocated for the
+graphic.
+</para>
+<variablelist><varlistentry><term><literal>width</literal>
+</term><listitem><para>The graphic will be shown so its bounding box is this width. An example
+is <literal>\includegraphics[width=1in]{plot}</literal>. You can use the standard
+&tex; dimensions (see <link linkend="Units-of-length">Units of length</link>) and also convenient is
+<literal>\linewidth</literal>, or in a two-column document, <literal>\columnwidth</literal>
+(see <link linkend="Page-layout-parameters">Page layout parameters</link>). An example is that by using the
+<filename>calc</filename> package you can make the graphic be 1&#160;cm narrow than
+the width of the text with
+<literal>\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>height</literal>
+</term><listitem><para>The graphic will be shown so its bounding box is this height. You can
+use the standard &tex; dimensions (see <link linkend="Units-of-length">Units of length</link>), and also
+convenient are <literal>\pageheight</literal> and <literal>\textheight</literal> (see <link linkend="Page-layout-parameters">Page
+layout parameters</link>). For instance,
+<literal>\includegraphics[height=0.25\textheight]{godel}</literal> will make the
+graphic be a quarter of the height of the text area.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>totalheight</literal>
+</term><listitem><para>The graphic will be shown so its bounding box has this height plus
+depth. This differs from the height if the graphic was rotated. For
+instance, if it has been rotated by -90 then it will have zero height
+but a large depth.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>keepaspectratio</literal>
+</term><listitem><para>If set to <literal>true</literal>, or just specified as with
+<literal>\includegraphics[...,keepaspectratio,...]{...}</literal> and you give as
+options both <literal>width</literal> and <literal>height</literal> (or <literal>totalheight</literal>),
+then &latex; will make the graphic is as large as possible without
+distortion. That is, &latex; will ensure that neither is the graphic
+wider than <literal>width</literal> nor taller than <literal>height</literal> (or
+<literal>totalheight</literal>).
+</para>
+</listitem></varlistentry><varlistentry><term><literal>scale</literal>
+</term><listitem><para>Factor by which to scale the graphic. Specifying
+<literal>\includegraphics[scale=2.0]{...}</literal> makes the graphic twice its
+nominal size. This number may be any value; a number between 1
+and&#160;0 will shrink the graphic and a negative number will reflect
+it.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>angle</literal>
+</term><listitem><para>Rotate the picture. The angle is taken in degrees and counterclockwise.
+The graphic is rotated about its <literal>origin</literal>; see that option. For a
+complete description of how rotated material is typeset,
+see <link linkend="_005crotatebox">\rotatebox</link>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>origin</literal>
+</term><listitem><para>The point of the graphic about which the rotation happens. Possible
+values are any string containing one or two of: <literal>l</literal> for left,
+<literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center, <literal>t</literal>
+for top, and <literal>B</literal> for baseline. Thus,
+<literal>\includegraphics[angle=180,origin=c]{moon}</literal> will turn the
+picture upside down from the center, while
+<literal>\includegraphics[angle=180,origin=lB]{LeBateau}</literal> will turn its
+picture upside down about its left baseline. (The character <literal>c</literal>
+gives the horizontal center in <literal>bc</literal> or <literal>tc</literal>, but gives the
+vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default is <literal>lB</literal>.
+</para>
+<para>To rotate about an arbitrary point, see <link linkend="_005crotatebox">\rotatebox</link>.
+</para>
+</listitem></varlistentry></variablelist>
+<para>These are lesser-used options.
+</para>
+<variablelist><varlistentry><term><literal>viewport</literal>
+</term><listitem><para>Pick out a subregion of the graphic to show. Takes four arguments,
+separated by spaces and given in &tex; dimensions, as with
+<literal>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</literal>. The
+dimensions default to big points,&#160;<literal>bp</literal>. They are taken
+relative to the origin specified by the bounding box. See also the
+<literal>trim</literal> option.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>trim</literal>
+</term><listitem><para>Gives parts of the graphic to not show. Takes four arguments, separated
+by spaces, that are given in &tex; dimensions, as with
+<literal>\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}</literal>.
+These give the amounts of the graphic not to show, that is, &latex;
+will crop the picture by 0&#160;inches on the left, 0.1&#160;inches on
+the bottom, 0.2&#160;inches on the right, and 0.3&#160;inches on the
+top. See also the <literal>viewport</literal> option.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>clip</literal>
+</term><listitem><para>If set to <literal>true</literal>, or just specified as with
+<literal>\includegraphics[...,clip,...]{...}</literal>, then the graphic is
+cropped to the bounding box. You can get this effect by instead using
+the starred form of the command, as
+<literal>\includegraphics*[...]{...}</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>page</literal>
+</term><listitem><para>Give the page number of a multi-page PDF file. The default is
+<literal>page=1</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>pagebox</literal>
+</term><listitem><para>Specifies which bounding box to use for PDF files from among
+<literal>mediabox</literal>, <literal>cropbox</literal>, <literal>bleedbox</literal>, <literal>trimbox</literal>, or
+<literal>artbox</literal>. PDF files do not have the BoundingBox that PostScript
+files have, but may specify up to four predefined rectangles. The
+MediaBox gives the boundaries of the physical medium. The CropBox is the
+region to which the contents of the page are to be clipped when
+displayed. The BleedBox is the region to which the contents of the page
+should be clipped in production. The TrimBox is the intended dimensions
+of the finished page. The ArtBox is the extent of the page&#8217;s meaningful
+content. The driver will set the image size based on CropBox if
+present, otherwise it will not use one of the others, with a
+driver-defined order of preference. MediaBox is always present.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>interpolate</literal>
+</term><listitem><para>Enable or disable interpolation of raster images by the viewer. Can be
+set with <literal>interpolate=true</literal> or just specified as with
+<literal>\includegraphics[...,interpolate,...]{...}</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>quiet</literal>
+</term><listitem><para>Do not write information to the log. You can set it with
+<literal>quiet=true</literal> or just specified it with
+<literal>\includegraphics[...,quite,...]{...}</literal>,
+</para>
+</listitem></varlistentry><varlistentry><term><literal>draft</literal>
+</term><listitem><para>If you set it with <literal>draft=true</literal> or just specified it with
+<literal>\includegraphics[...,draft,...]{...}</literal>, then the graphic will not
+appear in the document, possibly saving color printer ink. Instead,
+&latex; will put an empty box of the correct size with the filename
+printed in it.
+</para>
+</listitem></varlistentry></variablelist>
+<para>These options address the bounding box for Encapsulated PostScript
+graphic files, which have a size specified with a line
+<literal>%%BoundingBox</literal> that appears in the file. It has four values,
+giving the lower <inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, lower <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate, upper
+<inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, and upper <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate. The units are
+PostScript points, equivalent to &tex;&#8217;s big points, 1/72&#160;inch.
+For example, if an <filename>.eps</filename> file has the line <literal>%%BoundingBox 10
+20 40 80</literal> then its natural size is 30/72&#160;inch wide by
+60/72&#160;inch tall.
+</para>
+<variablelist><varlistentry><term><literal>bb</literal>
+</term><listitem><para>Specify the bounding box of the displayed region. The argument is four
+dimensions separated by spaces, as with <literal>\includegraphics[.., bb=
+0in 0in 1in 0.618in]{...}</literal>. Usually <literal>\includegraphics</literal> reads the
+BoundingBox numbers from the EPS file automatically, so this option is
+only useful if the bounding box is missing from that file or if you want
+to change it.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>bbllx, bblly, bburx, bbury</literal>
+</term><listitem><para>Set the bounding box. These four are obsolete, but are retained for
+compatibility with old packages.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>natwidth, natheight</literal>
+</term><listitem><para>An alternative for <literal>bb</literal>. Setting
+<literal>\includegraphics[...,natwidth=1in,natheight=0.618in,...]{...}</literal>
+is the same as setting <literal>bb=0 0 1in 0.618in</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>hiresbb</literal>
+</term><listitem><para>If set to <literal>true</literal>, or just specified as with
+<literal>\includegraphics[...,hiresbb,...]{...}</literal>, then &latex; will look
+for <literal>%%HiResBoundingBox</literal> lines instead of <literal>%%BoundingBox</literal>
+lines. (The <literal>BoundingBox</literal> lines use only natural numbers while the
+<literal>HiResBoundingBox</literal> lines use decimals; both use units equivalent to
+&tex;&#8217;s big points, 1/72&#160;inch.) To override a prior setting of
+<literal>true</literal>, you can set it to <literal>false</literal>.
+</para>
+</listitem></varlistentry></variablelist>
+<para>These following options allow a user to override &latex;&#8217;s method of
+choosing the graphic type based on the filename extension. An example
+is that <literal>\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}</literal>
+will read the file <filename>lion.xxx</filename> as though it were
+<filename>lion.png</filename>. For more on these, see <link linkend="_005cDeclareGraphicsRule">\DeclareGraphicsRule</link>.
+</para>
+<variablelist><varlistentry><term><literal>type</literal>
+</term><listitem><para>Specify the graphics type.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>ext</literal>
+</term><listitem><para>Specify the graphics extension.
+Only use this in conjunction with the option <literal>type</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>read</literal>
+</term><listitem><para>Specify the file extension of the read file.
+Only use this in conjunction with the option <literal>type</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>command</literal>
+</term><listitem><para>Specify a command to be applied to this file.
+Only use this in conjunction with the option <literal>type</literal>.
+<!-- write18 and restricted execution. -->
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect2>
+<sect2 label="22.3.2" id="_005crotatebox">
+<title><literal>\rotatebox</literal></title>
+
+<indexterm role="cp"><primary>rotation</primary></indexterm>
+<indexterm role="cp"><primary>rotating graphics</primary></indexterm>
+<indexterm role="cp"><primary>rotating text</primary></indexterm>
+<indexterm role="fn"><primary>\rotatebox</primary></indexterm>
+
+<para>Synopsis for <filename>graphics</filename> package:
+</para>
+<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>}
+</screen>
+<para>Synopses for <filename>graphicx</filename> package:
+</para>
+<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>}
+\rotatebox[<replaceable>key-value list</replaceable>]{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>}
+</screen>
+<para>Put <replaceable>material</replaceable> in a box and rotate it <replaceable>angle</replaceable> degrees counterclockwise.
+</para>
+<para>This example rotates the table column heads forty five degrees.
+</para>
+<screen>\begin{tabular}{ll}
+ \rotatebox{45}{Character} &amp;\rotatebox{45}{NATO phonetic} \\
+ A &amp;AL-FAH \\
+ B &amp;BRAH-VOH
+\end{tabular}
+</screen>
+<para>The <replaceable>material</replaceable> can be anything that goes in a box, including a graphic.
+</para>
+<screen> \rotatebox[origin=c]{45}{\includegraphics[width=1in]{lion}}
+</screen>
+<para>To place the rotated material, the first step is that &latex; sets
+<replaceable>material</replaceable> in a box, with a reference point on the left baseline.
+The second step is the rotation, by default about the reference point.
+The third step is that &latex; computes a box to bound the rotated
+material. Fourth, &latex; moves this box horizontally so that the left
+edge of this new bounding box coincides with the left edge of the box
+from the first step (they need not coincide vertically). This new
+bounding box, in its new position, is what &latex; uses as the box when
+typesetting this material.
+</para>
+<para>If you use the <filename>graphics</filename> package then the rotation is about the
+reference point of the box. If you use the <filename>graphicx</filename> package then
+then these are the options that can go in the <replaceable>key-value list</replaceable>, but
+note that you can get the same effect without needing this package,
+except for the <literal>x</literal> and <literal>y</literal> options (see <link linkend="_005cincludegraphics">\includegraphics</link>).
+</para>
+<variablelist><varlistentry><term><literal>origin</literal>
+</term><listitem><para>The point of the <replaceable>material</replaceable>&#8217;s box about which the rotation happens.
+Possible values are any string containing one or two of: <literal>l</literal> for
+left, <literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center,
+<literal>t</literal> for top, and <literal>B</literal> for baseline. Thus,
+<literal>\includegraphics[angle=180,origin=c]{moon}</literal> will turn the
+picture upside down from the center, while
+<literal>\includegraphics[angle=180,origin=lB]{LeBateau}</literal> will turn its
+picture upside down about its left baseline. (The character <literal>c</literal>
+gives the horizontal center in <literal>bc</literal> or <literal>tc</literal> but gives the
+vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default is <literal>lB</literal>.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>x, y</literal>
+</term><listitem><para>Specify an arbitrary point of rotation with
+<literal>\rotatebox[x=<replaceable>&tex; dimension</replaceable>,y=<replaceable>&tex;
+dimension</replaceable>]{...}</literal> (see <link linkend="Units-of-length">Units of length</link>). These give the offset
+from the box&#8217;s reference point.
+</para>
+</listitem></varlistentry><varlistentry><term><literal>units</literal>
+</term><listitem><para>This key allows you to change the default of degrees counterclockwise.
+Setting <literal>units=-360</literal> changes the direction to degrees clockwise and
+setting <literal>units=6.283185</literal> changes to radians counterclockwise.
+</para>
+</listitem></varlistentry></variablelist>
+
+</sect2>
+<sect2 label="22.3.3" id="_005cscalebox">
+<title><literal>\scalebox</literal></title>
+
+<indexterm role="cp"><primary>graphics, scaling</primary></indexterm>
+<indexterm role="cp"><primary>graphics, resizing</primary></indexterm>
+<indexterm role="cp"><primary>scaling</primary></indexterm>
+<indexterm role="cp"><primary>resizing</primary></indexterm>
+<indexterm role="cp"><primary>text, scaling</primary></indexterm>
+<indexterm role="cp"><primary>text, resizing</primary></indexterm>
+<indexterm role="fn"><primary>\scalebox</primary></indexterm>
+<indexterm role="fn"><primary>\reflectbox</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\scalebox{<replaceable>horizontal factor</replaceable>}{<replaceable>material</replaceable>}
+\scalebox{<replaceable>horizontal factor</replaceable>}[<replaceable>vertical factor</replaceable>]{<replaceable>material</replaceable>}
+\reflectbox{<replaceable>material</replaceable>}
+</screen>
+<para>Scale the <replaceable>material</replaceable>.
+</para>
+<para>This example halves the size, both horizontally and vertically, of the
+first text and doubles the size of the second.
+</para>
+<screen>\scalebox{0.5}{DRINK ME} and \scalebox{2.0}{Eat Me}
+</screen>
+<para>If you do not specify the optional <replaceable>vertical factor</replaceable> then it
+defaults to the same value as the <replaceable>horizontal factor</replaceable>.
+</para>
+<para>You can use this command to resize a graphic, as with
+<literal>\scalebox{0.5}{\includegraphics{lion}}</literal>. If you use the
+<filename>graphicx</filename> package then you can accomplish the same thing with
+optional arguments to <literal>\includegraphics</literal>
+(see <link linkend="_005cincludegraphics">\includegraphics</link>).
+</para>
+<para>The <literal>\reflectbox</literal> command abbreviates
+<literal>\scalebox{-1}[1]{<replaceable>material</replaceable>}</literal>. Thus, <literal>Able was
+I\reflectbox{Able was I}</literal> will show the phrase &#8216;<literal>Able was I</literal>&#8217;
+immediately followed by its mirror reflection.
+</para>
+
+</sect2>
+<sect2 label="22.3.4" id="_005cresizebox">
+<title><literal>\resizebox</literal></title>
+
+<indexterm role="cp"><primary>graphics, scaling</primary></indexterm>
+<indexterm role="cp"><primary>graphics, resizing</primary></indexterm>
+<indexterm role="cp"><primary>scaling</primary></indexterm>
+<indexterm role="cp"><primary>resizing</primary></indexterm>
+<indexterm role="cp"><primary>text, scaling</primary></indexterm>
+<indexterm role="cp"><primary>text, resizing</primary></indexterm>
+<indexterm role="fn"><primary>\resizebox</primary></indexterm>
+
+<para>Synopses:
+</para>
+<screen>\resizebox{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>}
+\resizebox*{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>}
+</screen>
+<para>Given a size, such as <literal>3cm</literal>, transform <replaceable>material</replaceable> to make it
+that size. If either <replaceable>horizontal length</replaceable> or <replaceable>vertical length</replaceable>
+is an exclamation point&#160;<literal>!</literal> then the other argument is used
+to determine a scale factor for both directions.
+</para>
+<para>This example makes the graphic be a half inch wide and scales it
+vertically by the same factor to keep it from being distorted.
+</para>
+<screen>\resizebox{0.5in}{!}{\includegraphics{lion}}
+</screen>
+<para>The unstarred form <literal>\resizebox</literal> takes <replaceable>vertical length</replaceable> to be
+the box&#8217;s height while the starred form <literal>\resizebox*</literal> takes it to
+be height+depth. For instance, make the text have a height+depth of a
+quarter inch with <literal>\resizebox*{!}{0.25in}{\parbox{1in}{This
+box has both height and depth.}}</literal>.
+</para>
+<para>You can use <literal>\depth</literal>, <literal>\height</literal>, <literal>\totalheight</literal>, and
+<literal>\width</literal> to refer to the original size of the box. Thus, make the
+text two inches wide but keep the original height with
+<literal>\resizebox{2in}{\height}{Two inches}</literal>.
+</para>
+
+</sect2>
+</sect1>
+</chapter>
+<chapter label="23" id="Special-insertions">
<title>Special insertions</title>
<indexterm role="cp"><primary>special insertions</primary></indexterm>
@@ -8455,7 +10594,7 @@ special meaning do not correspond to simple characters you can type.
</para>
-<sect1 label="21.1" id="Reserved-characters">
+<sect1 label="23.1" id="Reserved-characters">
<title>Reserved characters</title>
<indexterm role="cp"><primary>reserved characters</primary></indexterm>
@@ -8502,7 +10641,66 @@ split the lines.
</para>
</sect1>
-<sect1 label="21.2" id="Symbols-by-font-position">
+<sect1 label="23.2" id="Upper-and-lower-case">
+<title>Upper and lower case</title>
+
+<indexterm role="cp"><primary>Upper case</primary></indexterm>
+<indexterm role="cp"><primary>Lower case</primary></indexterm>
+<indexterm role="cp"><primary>characters, case</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\uppercase{<replaceable>text</replaceable>}
+\lowercase{<replaceable>text</replaceable>}
+\MakeUppercase{<replaceable>text</replaceable>}
+\MakeLowercase{<replaceable>text</replaceable>}
+</screen>
+<para>Change the case of characters. The &tex; primitives commands
+<literal>\uppercase</literal> and <literal>\lowercase</literal> only work for American
+characters. The &latex; commands <literal>\MakeUppercase</literal> and
+<literal>\MakeLowercase</literal> commands also change characters accessed by
+commands such as <literal>\ae</literal> or <literal>\aa</literal>. The commands
+<literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> are robust but they have
+moving arguments (see <link linkend="_005cprotect">\protect</link>).
+</para>
+<para>These commands do not change the case of letters used in the name of a
+command within <replaceable>text</replaceable>. But they do change the case of every other
+Latin letter inside the argument <replaceable>text</replaceable>. Thus,
+<literal>\MakeUppercase{Let $y=f(x)$</literal>} produces &#8216;<literal>LET Y=F(X)</literal>&#8217;. Another
+example is that the name of an environment will be changed, so that
+<literal>\MakeUppercase{\begin{tabular} ... \end{tabular}}</literal> will
+produce an error because the first half is changed to
+<literal>\begin{TABULAR}</literal>.
+</para>
+<para>&latex; uses the same fixed table for changing case throughout a
+document, The table used is designed for the font encoding T1; this
+works well with the standard &tex; fonts for all Latin alphabets but
+will cause problems when using other alphabets.
+</para>
+<para>To change the case of text that results from a macro inside <replaceable>text</replaceable>
+you need to do expansion. Here the <literal>\Schoolname</literal> produces
+&#8216;<literal>COLLEGE OF MATHEMATICS</literal>&#8217;.
+</para>
+<screen>\newcommand{\schoolname}{College of Mathematics}
+\newcommand{\Schoolname}{\expandafter\MakeUppercase
+ <!-- /@w -->\expandafter{\schoolname}}
+</screen>
+<indexterm role="cp"><primary>package, <literal>textcase</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>textcase</literal> package</primary></indexterm>
+
+<para>The <filename>textcase</filename> package brings some of the missing feature of the
+standard &latex; commands <literal>\MakeUppercase</literal> and
+<literal>\MakeLowerCase</literal>.
+</para>
+<indexterm role="cp"><primary>package, <literal>mfirstuc</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>mfirstuc</literal> package</primary></indexterm>
+
+<para>To uppercase only the first letter of words, you can use the package
+<filename>mfirstuc</filename>.
+</para>
+
+</sect1>
+<sect1 label="23.3" id="Symbols-by-font-position">
<title>Symbols by font position</title>
<indexterm role="fn"><primary>\symbol</primary></indexterm>
@@ -8521,7 +10719,7 @@ example could also be written as <literal>\symbol{'40}</literal> or
</para>
</sect1>
-<sect1 label="21.3" id="Text-symbols">
+<sect1 label="23.4" id="Text-symbols">
<title>Text symbols</title>
<indexterm role="cp"><primary>text symbols</primary></indexterm>
@@ -8809,7 +11007,7 @@ has the ascender height.
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="21.4" id="Accents">
+<sect1 label="23.5" id="Accents">
<title>Accents</title>
<indexterm role="cp"><primary>accents</primary></indexterm>
@@ -8818,6 +11016,7 @@ has the ascender height.
<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm>
+
<indexterm role="cp"><primary>multilingual support</primary></indexterm>
<para>&latex; has wide support for many of the world&#8217;s scripts and
languages, through the <literal>babel</literal> package and related support. This
@@ -8837,7 +11036,7 @@ capital letters. These are not available with OT1.
</para>
</listitem></varlistentry><varlistentry><term><literal>\'</literal>
</term><term><literal>\capitalacute</literal>
-</term><listitem><indexterm role="fn"><primary>\&#8217; (acute accent)</primary></indexterm>
+</term><listitem><indexterm role="fn"><primary>\' (acute accent)</primary></indexterm>
<indexterm role="fn"><primary>\capitalacute</primary></indexterm>
<indexterm role="cp"><primary>acute accent</primary></indexterm>
<para>Produces an acute accent, as in &#243;. In the <literal>tabbing</literal>
@@ -8869,7 +11068,7 @@ environment, pushes current column to the right of the previous column
</para>
</listitem></varlistentry><varlistentry><term><literal>\`</literal>
</term><term><literal>\capitalgrave</literal>
-</term><listitem><indexterm role="fn"><primary>\&#8216; (grave accent)</primary></indexterm>
+</term><listitem><indexterm role="fn"><primary>\` (grave accent)</primary></indexterm>
<indexterm role="fn"><primary>\capitalgrave</primary></indexterm>
<indexterm role="cp"><primary>grave accent</primary></indexterm>
<para>Produces a grave accent over the following, as in &#242;. In the
@@ -8975,7 +11174,7 @@ See also <literal>\b</literal> above.
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="21.5" id="Additional-Latin-letters">
+<sect1 label="23.6" id="Additional-Latin-letters">
<title>Additional Latin letters</title>
<anchor id="Non_002dEnglish-characters"/><indexterm role="cp"><primary>Latin letters, additional</primary></indexterm>
@@ -9076,7 +11275,7 @@ font encoding, such as T1.
</listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="21.6" id="_005crule">
+<sect1 label="23.7" id="_005crule">
<title><literal>\rule</literal></title>
<indexterm role="fn"><primary>\rule</primary></indexterm>
@@ -9099,7 +11298,7 @@ rectangles. The arguments are:
</para></listitem></varlistentry></variablelist>
</sect1>
-<sect1 label="21.7" id="_005ctoday">
+<sect1 label="23.8" id="_005ctoday">
<title><literal>\today</literal></title>
<indexterm role="fn"><primary>\today</primary></indexterm>
@@ -9124,13 +11323,14 @@ will output &#8216;<literal>4 juillet 1976</literal>&#8217;:
</screen>
<indexterm role="cp"><primary>package, <literal>datetime</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>datetime</literal> package</primary></indexterm>
+
<para>The <literal>datetime</literal> package, among others, can produce a wide variety
of other date formats.
</para>
</sect1>
</chapter>
-<chapter label="22" id="Splitting-the-input">
+<chapter label="24" id="Splitting-the-input">
<title>Splitting the input</title>
<indexterm role="cp"><primary>splitting the input file</primary></indexterm>
@@ -9150,7 +11350,7 @@ external file to be created with the main document.
</para>
-<sect1 label="22.1" id="_005cinclude">
+<sect1 label="24.1" id="_005cinclude">
<title><literal>\include</literal></title>
<indexterm role="fn"><primary>\include</primary></indexterm>
@@ -9174,8 +11374,8 @@ read by another <literal>\include</literal> command.
</para>
</sect1>
-<sect1 label="22.2" id="_005cincludeonly">
-<title>\<literal>includeonly</literal></title>
+<sect1 label="24.2" id="_005cincludeonly">
+<title><literal>\includeonly</literal></title>
<indexterm role="fn"><primary>\includeonly</primary></indexterm>
@@ -9193,7 +11393,7 @@ selection to be effective.
</para>
</sect1>
-<sect1 label="22.3" id="_005cinput">
+<sect1 label="24.3" id="_005cinput">
<title><literal>\input</literal></title>
<indexterm role="fn"><primary>\input</primary></indexterm>
@@ -9214,12 +11414,12 @@ is tried (&#8216;<literal>foo</literal>&#8217; or &#8216;<literal>foo.bar</liter
</sect1>
</chapter>
-<chapter label="23" id="Front_002fback-matter">
+<chapter label="25" id="Front_002fback-matter">
<title>Front/back matter</title>
-<sect1 label="23.1" id="Tables-of-contents">
+<sect1 label="25.1" id="Tables-of-contents">
<title>Tables of contents</title>
<indexterm role="cp"><primary>table of contents, creating</primary></indexterm>
@@ -9251,7 +11451,7 @@ as for the table of contents.
</para>
-<sect2 label="23.1.1" id="_005caddcontentsline">
+<sect2 label="25.1.1" id="_005caddcontentsline">
<title><literal>\addcontentsline</literal></title>
<indexterm role="fn"><primary>\addcontentsline</primary></indexterm>
@@ -9265,7 +11465,7 @@ as for the table of contents.
or table where:
</para>
<variablelist><varlistentry><term><replaceable>ext</replaceable>
-</term><listitem><para>The extension of the file on which information is to be written,
+</term><listitem><para>The filename extension of the file on which information is to be written,
typically one of: <literal>toc</literal> (table of contents), <literal>lof</literal> (list of
figures), or <literal>lot</literal> (list of tables).
</para>
@@ -9293,7 +11493,7 @@ following, matching the value of the <replaceable>ext</replaceable> argument:
</sect2>
-<sect2 label="23.1.2" id="_005caddtocontents">
+<sect2 label="25.1.2" id="_005caddtocontents">
<title><literal>\addtocontents</literal></title>
<indexterm role="fn"><primary>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm>
@@ -9313,7 +11513,7 @@ figures), or <filename>lot</filename> (list of tables).
</sect2>
</sect1>
-<sect1 label="23.2" id="Glossaries">
+<sect1 label="25.2" id="Glossaries">
<title>Glossaries</title>
<indexterm role="cp"><primary>glossaries</primary></indexterm>
@@ -9337,7 +11537,7 @@ glossaries.
</para>
</sect1>
-<sect1 label="23.3" id="Indexes">
+<sect1 label="25.3" id="Indexes">
<title>Indexes</title>
<indexterm role="cp"><primary>indexes</primary></indexterm>
@@ -9381,6 +11581,7 @@ the index.
<indexterm role="fn"><primary>\printindex</primary></indexterm>
<indexterm role="cp"><primary>package, <literal>makeidx</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>makeidx</literal> package</primary></indexterm>
+
<para>The index is usually generated with the <literal>\printindex</literal> command.
This is defined in the <literal>makeidx</literal> package, so
<literal>\usepackage{makeidx}</literal> needs to be in the preamble.
@@ -9392,12 +11593,14 @@ minus3pt</literal>&#8217;.
</para>
<indexterm role="cp"><primary>package, <literal>showidx</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>showidx</literal> package</primary></indexterm>
+
<para>The <literal>showidx</literal> package causes each index entries to be shown in
the margin on the page where the entry appears. This can help in
preparing the index.
</para>
<indexterm role="cp"><primary>package, <literal>multind</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>multind</literal> package</primary></indexterm>
+
<para>The <literal>multind</literal> package supports multiple indexes. See also the
&tex; FAQ entry on this topic,
<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind</ulink>.
@@ -9405,7 +11608,7 @@ preparing the index.
</sect1>
</chapter>
-<chapter label="24" id="Letters">
+<chapter label="26" id="Letters">
<title>Letters</title>
<indexterm role="cp"><primary>letters, writing</primary></indexterm>
@@ -9492,7 +11695,7 @@ I am not interested in entering a business arrangement with you.
</para>
-<sect1 label="24.1" id="_005caddress">
+<sect1 label="26.1" id="_005caddress">
<title><literal>\address</literal></title>
<indexterm role="fn"><primary>\address</primary></indexterm>
@@ -9522,7 +11725,7 @@ formatted as a personal letter.
</screen>
</sect1>
-<sect1 label="24.2" id="_005ccc">
+<sect1 label="26.2" id="_005ccc">
<title><literal>\cc</literal></title>
<indexterm role="fn"><primary>\cc</primary></indexterm>
@@ -9543,7 +11746,7 @@ backslash&#160;<literal>\\</literal>, as in:
</screen>
</sect1>
-<sect1 label="24.3" id="_005cclosing">
+<sect1 label="26.3" id="_005cclosing">
<title><literal>\closing</literal></title>
<indexterm role="fn"><primary>\closing</primary></indexterm>
@@ -9561,7 +11764,7 @@ is a <literal>\closing</literal> (although this command is optional). For examp
</screen>
</sect1>
-<sect1 label="24.4" id="_005cencl">
+<sect1 label="26.4" id="_005cencl">
<title><literal>\encl</literal></title>
<indexterm role="fn"><primary>\encl</primary></indexterm>
@@ -9581,7 +11784,7 @@ Separate multiple lines with a double backslash&#160;<literal>\\</literal>.
</screen>
</sect1>
-<sect1 label="24.5" id="_005clocation">
+<sect1 label="26.5" id="_005clocation">
<title><literal>\location</literal></title>
<indexterm role="fn"><primary>\location</primary></indexterm>
@@ -9595,7 +11798,7 @@ appears if the page style is <literal>firstpage</literal>.
</para>
</sect1>
-<sect1 label="24.6" id="_005cmakelabels">
+<sect1 label="26.6" id="_005cmakelabels">
<title><literal>\makelabels</literal></title>
<indexterm role="fn"><primary>\makelabels</primary></indexterm>
@@ -9623,7 +11826,7 @@ in the argument to the <literal>letter</literal> environment. By default
<!-- xxx TODO, align on latex2e-fr.texi, see https://mail.gna.org/public/latexrefman-discuss/2015-10/msg00000.html -->
</sect1>
-<sect1 label="24.7" id="_005cname">
+<sect1 label="26.7" id="_005cname">
<title><literal>\name</literal></title>
<indexterm role="fn"><primary>\name</primary></indexterm>
@@ -9637,7 +11840,7 @@ return address.
</para>
</sect1>
-<sect1 label="24.8" id="_005copening">
+<sect1 label="26.8" id="_005copening">
<title><literal>\opening</literal></title>
<indexterm role="fn"><primary>\opening</primary></indexterm>
@@ -9655,7 +11858,7 @@ text that starts your letter. For instance:
</screen>
</sect1>
-<sect1 label="24.9" id="_005cps">
+<sect1 label="26.9" id="_005cps">
<title><literal>\ps</literal></title>
<indexterm role="fn"><primary>\ps</primary></indexterm>
<indexterm role="cp"><primary>postscript, in letters</primary></indexterm>
@@ -9671,7 +11874,7 @@ text that starts your letter. For instance:
</screen>
</sect1>
-<sect1 label="24.10" id="_005csignature">
+<sect1 label="26.10" id="_005csignature">
<title><literal>\signature</literal></title>
<para>Synopsis:
@@ -9725,7 +11928,7 @@ preamble).
<!-- -->
<!-- -->
</sect1>
-<sect1 label="24.11" id="_005ctelephone">
+<sect1 label="26.11" id="_005ctelephone">
<title><literal>\telephone</literal></title>
<indexterm role="fn"><primary>\telephone</primary></indexterm>
@@ -9742,7 +11945,7 @@ page.
</sect1>
</chapter>
-<chapter label="25" id="Terminal-input_002foutput">
+<chapter label="27" id="Terminal-input_002foutput">
<title>Terminal input/output</title>
<indexterm role="cp"><primary>input/output, to terminal</primary></indexterm>
@@ -9750,7 +11953,7 @@ page.
-<sect1 label="25.1" id="_005ctypein">
+<sect1 label="27.1" id="_005ctypein">
<title><literal>\typein[<replaceable>cmd</replaceable>]{<replaceable>msg</replaceable>}</literal></title>
<indexterm role="fn"><primary>\typein</primary></indexterm>
@@ -9769,7 +11972,7 @@ redefined to be the typed input.
</para>
</sect1>
-<sect1 label="25.2" id="_005ctypeout">
+<sect1 label="27.2" id="_005ctypeout">
<title><literal>\typeout{<replaceable>msg</replaceable>}</literal></title>
<indexterm role="fn"><primary>\typeout</primary></indexterm>
@@ -9792,7 +11995,7 @@ printed, independent of surrounding spaces. A <literal>^^J</literal> in
</sect1>
</chapter>
-<chapter label="26" id="Command-line">
+<chapter label="28" id="Command-line">
<title>Command line</title>
<indexterm role="cp"><primary>command line</primary></indexterm>
@@ -9807,7 +12010,7 @@ error:
</para>
<screen>latex '\nonstopmode\input foo.tex'
</screen>
-<indexterm role="fn"><primary>&#8211;help command-line option</primary></indexterm>
+<indexterm role="fn"><primary>--help command-line option</primary></indexterm>
<para>With many, but not all, implementations, command-line options can also
be specified in the usual Unix way, starting with &#8216;<literal>-</literal>&#8217; or
&#8216;<literal>--</literal>&#8217;. For a list of those options, try &#8216;<literal>latex --help</literal>&#8217;.