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.dbk887
1 files changed, 518 insertions, 369 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 bc7c6640517..5c203240faa 100644
--- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
+++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk
@@ -4,11 +4,11 @@
<!ENTITY latex "LaTeX">
]>
<book id="latex2e.dbk" lang="en">
-<!-- $Id$ -->
+<!-- $Id: common.texi 701 2018-10-08 14:32:37Z jimhefferon $ -->
<!-- Public domain. -->
-<title>&latex;2e unofficial reference manual (July 2018)</title>
+<title>&latex;2e unofficial reference manual (October 2018)</title>
<!-- %**end of header (This is for running Texinfo on a region.) -->
<!-- latex 2.09 commands should all be present now, -->
@@ -33,6 +33,7 @@
<!-- xx JH \baselineskip https://texfaq.org/FAQ-baselinepar -->
<!-- xx JH \contentsline, \@@dottedtocline? -->
<!-- xx JH more on \write18, beyond what's mentioned in Command line. -->
+<!-- xx JH \numexpr, \dimexpr, \glueexpr, \muexpr -->
<!-- -->
<!-- xx The typeset source2e has an index with all kernel -->
<!-- xx commands, though some are internal and shouldn't be included. -->
@@ -40,10 +41,10 @@
<!-- 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 July 2018.
+document preparation system, version of October 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
+<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
George&#160;D. Greenwade of Sam Houston State University. The
&latex;&#160;2.09 version was written by Stephen Gilmore. The
&latex;2e version was adapted from this by Torsten Martinsen. Karl
@@ -51,8 +52,10 @@ Berry made further updates and additions, and gratefully acknowledges
using <citetitle>Hypertext Help with &latex;</citetitle>, by Sheldon Green, and
<citetitle>&latex; Command Summary</citetitle> (for &latex;&#160;2.09) by
L.&#160;Botway and C.&#160;Biemesderfer (published by the &tex; Users
-Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (no
-text was directly copied).
+Group as <citetitle>&tex;niques</citetitle> number 10), as reference material. We also
+gratefully acknowledge additional material appearing in
+latex2e-reference by Martin Herbert Dietze. (From these references no
+text was directly copied.)
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
2014, 2015, 2016, 2017, 2018 Karl Berry.
@@ -81,10 +84,10 @@ 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 July 2018.
+document preparation system, version of October 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
+<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
George&#160;D. Greenwade of Sam Houston State University. The
&latex;&#160;2.09 version was written by Stephen Gilmore. The
&latex;2e version was adapted from this by Torsten Martinsen. Karl
@@ -92,8 +95,10 @@ Berry made further updates and additions, and gratefully acknowledges
using <citetitle>Hypertext Help with &latex;</citetitle>, by Sheldon Green, and
<citetitle>&latex; Command Summary</citetitle> (for &latex;&#160;2.09) by
L.&#160;Botway and C.&#160;Biemesderfer (published by the &tex; Users
-Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (no
-text was directly copied).
+Group as <citetitle>&tex;niques</citetitle> number 10), as reference material. We also
+gratefully acknowledge additional material appearing in
+latex2e-reference by Martin Herbert Dietze. (From these references no
+text was directly copied.)
</para>
<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013,
2014, 2015, 2016, 2017, 2018 Karl Berry.
@@ -126,7 +131,7 @@ into another language, under the above conditions for modified versions.
<title>&latex;2e: An unofficial reference manual</title>
<para>This document is an unofficial reference manual (version of
-July 2018) for &latex;2e, a document preparation system.
+October 2018) for &latex;2e, a document preparation system.
</para>
@@ -137,10 +142,17 @@ July 2018) for &latex;2e, a document preparation system.
<indexterm role="cp"><primary>home page for manual</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="puszcza.gnu.org.ua/software/latexrefman">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.
+typesetting program (see <link linkend="Overview">Overview</link>).
+</para>
+<para>This document&#8217;s home page is <ulink url="https://puszcza.gnu.org.ua/software/latexrefman">https://puszcza.gnu.org.ua/software/latexrefman</ulink>. There
+you can get the sources, subscribe to the mailing list or read its
+archives, see other infrastructure, and get the current output in
+various formats. In particular, the output comes in two web formats.
+Probably the most convenient one, shown at <ulink url="http://latexref.xyz/">http://latexref.xyz/</ulink>,
+has pages for each topic and so is good for a quick lookup; see also the
+note there about easy-to-remember links. The other, shown at
+<ulink url="http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co">http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co</ulink>,
+has all the information on single page.
</para>
<indexterm role="cp"><primary>&latex; vs. &latex;2e</primary></indexterm>
<para>In this document, we will mostly just use &#8216;&latex;&#8217; rather than
@@ -446,6 +458,12 @@ argument comes last, with no required argument after it, then to make
the first character of the following text be an open square bracket,
hide it inside curly braces.
</para>
+<para>Some of &latex;&#8217;s commands are a <firstterm>declaration</firstterm>. Such a command
+changes the value the meaning of some other command or parameter. For
+instance, the <literal>\mainmatter</literal> declaration changes the typesetting of
+page numbers from roman numerals to arabic (see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter &amp;
+\mainmatter &amp; \backmatter</link>).
+</para>
<para>&latex; has the convention that some commands have a <literal>*</literal> form that
is related to the form without a <literal>*</literal>, such as <literal>\chapter</literal> and
<literal>\chapter*</literal>. The exact difference in behavior varies from command
@@ -455,9 +473,9 @@ to command.
commands it covers (barring unintentional omissions, a.k.a. bugs).
</para>
-
-<sect2 label="2.4.1" id="Environment">
-<title>Environments</title>
+</sect1>
+<sect1 label="2.5" id="Environment">
+<title>Environment</title>
<para>Synopsis:
</para>
@@ -474,7 +492,9 @@ behavior. For instance, for poetry in &latex; put the lines between
...
\end{verse}
</screen>
-<para>See <link linkend="Environments">Environments</link> for a list of environments.
+<para>See <link linkend="Environments">Environments</link> for a list of environments. Particularly notable is
+that every &latex; document must have a <literal>document</literal> environment,
+a <literal>\begin{document} ... \end{document}</literal> pair.
</para>
<para>The <replaceable>environment name</replaceable> at the beginning must exactly match that at
the end. This includes the case where <replaceable>environment name</replaceable> ends in a
@@ -491,143 +511,9 @@ required (it specifies the formatting of columns).
\end{tabular}
</screen>
-</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>
-
-</sect2>
-<sect2 label="2.4.3" id="_005cmakeatletter-_0026-_005cmakeatother">
-<title><literal>\makeatletter</literal> &amp; <literal>\makeatother</literal></title>
-
-<para>Synopsis:
-</para>
-<screen>\makeatletter
- ... definition of commands with @ in their name ..
-\makeatother
-</screen>
-<para>Used to redefine internal &latex; commands. <literal>\makeatletter</literal> makes
-the at-sign character&#160;<literal>@</literal> have the category code of a letter,
-11. <literal>\makeatother</literal> sets the category code of&#160;<literal>@</literal> to 12,
-its original value.
-</para>
-<para>As each character is read by &tex; for &latex;, it is assigned a
-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 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>
-<para>The alteration is needed because many of &latex;&#8217;s commands use
-<literal>@</literal> in their name, to prevent users from accidentally defining a
-command that replaces one of &latex;&#8217;s own. Command names consist of a
-category&#160;0 character, ordinarily backslash, followed by letters,
-category&#160;11 characters (except that a command name can also consist
-of a category&#160;0 character followed by a single non-letter symbol).
-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 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</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>In this example the class file has a command
-<literal>\thesis@universityname</literal> that the user wants to change. These
-three lines should go in the preamble, before the
-<literal>\begin{document}</literal>.
-</para>
-<screen>\makeatletter
-\renewcommand{\thesis@universityname}{Saint Michael's College}
-\makeatother
-</screen>
-
-
-<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>nostar-num-args</replaceable>]{<replaceable>nostar-body</replaceable>}
-\newcommand{\mycmd@star}[<replaceable>star-num-args</replaceable>]{<replaceable>star-body</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-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>).
-</para>
-<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a
-variant <literal>\ciel*</literal>. Both have one required argument. A call to
-<literal>\ciel{night}</literal> will return &quot;starry night sky&quot; while
-<literal>\ciel*{blue}</literal> will return &quot;starry not blue sky&quot;.
-</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 the unstarred one. With this definition, Agent 007&#8217;s
-<literal>``My name is \agentsecret*{Bond},
-\agentsecret{James}{Bond}.''</literal> is equivalent to entering the commands
-<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>
-<sect1 label="2.5" id="CTAN">
-<title>CTAN: Comprehensive &tex; Archive Network</title>
+<sect1 label="2.6" id="CTAN">
+<title>CTAN: the Comprehensive &tex; Archive Network</title>
<indexterm role="cp"><primary>CTAN</primary></indexterm>
@@ -926,10 +812,11 @@ others. For instance, the class <literal>smcmemo</literal> might have commands
<indexterm role="cp"><primary>package options</primary></indexterm>
<para>A class file or package file typically has four parts.
-</para><orderedlist numeration="arabic"><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex;
+</para><orderedlist numeration="arabic"><listitem><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex;
package or class and describes itself, using the <literal>\NeedsTeXFormat</literal>
and <literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands.
-</para><listitem><para>The <firstterm>preliminary declarations part</firstterm> declares some commands and
+</para>
+</listitem><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
@@ -937,13 +824,15 @@ people for the to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, a
therefore needs to define a command
<literal>\newcommand{\setto}[1]{\def\@tolist{#1}}</literal> used in that
file.
-</para></listitem><listitem><para>In the <firstterm>handle options part</firstterm> the class or package declares
+</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.
-</para></listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package usually does
+</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>
@@ -4803,7 +4692,7 @@ 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
+have to hide the bracket inside curly braces, as in: <literal>\item
{[} is an open square bracket</literal>; otherwise, &latex; will think it
marks the start of an optional label.
</para>
@@ -4988,7 +4877,7 @@ default is the value of <replaceable>position</replaceable>).
stretchable space.
</para>
</listitem></varlistentry></variablelist>
-<para>The <replaceable>inner-pos</replaceable> argument makes sense when the <replaceable>height</replaceable> options
+<para>The <replaceable>inner-pos</replaceable> argument makes sense when the <replaceable>height</replaceable> option
is set to a value larger than the <literal>minipage</literal>&#8217;s natural height. To
see the effect of the options, run this example with the various choices
in place of <literal>b</literal>.
@@ -6041,8 +5930,8 @@ ampersand, <literal>&amp;</literal>. The end of each row is marked with a doubl
backslash, <literal>\\</literal>. Put a horizontal rule below a row, after a double
backslash, with <literal>\hline</literal>.
<indexterm role="fn"><primary>\\ for <literal>tabular</literal></primary></indexterm>
-This <literal>\\</literal> is optional after the last row unless an <literal>\hline</literal>
-command follows, to put a rule below the table.
+After the last row the <literal>\\</literal> is optional, unless an <literal>\hline</literal>
+command follows to put a rule below the table.
</para>
<para>The required and optional arguments to <literal>tabular</literal> consist of:
</para>
@@ -6093,9 +5982,9 @@ there.
not insert <literal>\tabcolsep</literal> so you must insert any desired space
yourself, as in <literal>@{\hspace{1em}}</literal>.
</para>
-<para>An empty expression <literal>@{}</literal> will eliminate the space. In
-particular, sometimes you want to eliminate the the space before the
-first column or after the last one, as in the example below where the
+<para>An empty expression <literal>@{}</literal> will eliminate the space. In
+particular, sometimes you want to eliminate the space before the first
+column or after the last one, as in the example below where the
tabular lines need to lie on the left margin.
</para>
<screen>\begin{flushleft}
@@ -6275,10 +6164,10 @@ range en-dash.
Impressionistic &amp;1875 &amp;1925
\end{tabular}
</screen>
-<para>Note that although the <literal>tabular</literal> specification by default puts a
-vertical rule between the first and second columns, because there is no
-vertical bar in the <replaceable>cols</replaceable> of either of the first row&#8217;s
-<literal>\multicolumn</literal> commands, no rule appears in the first row.
+<para>Although the <literal>tabular</literal> specification by default puts a vertical
+rule between the first and second columns, no such vertical rule appears
+in the first row here. That&#8217;s because there is no vertical bar in the
+<replaceable>cols</replaceable> part of the first row&#8217;s first <literal>\multicolumn</literal> command.
</para>
</sect2>
@@ -6521,12 +6410,21 @@ comma-separated list of citation keys (see <link linkend="_005cbibitem">\bibitem
Addison-Wesley, Reading, Massachusetts, 1983.
\end{thebibliography}
</screen>
-<para>produces the output &#8216;<literal>... source is [1]</literal>&#8217;.
+<para>produces output like &#8216;<literal>... source is [1]</literal>&#8217;. (You can change the
+appearance of the citation with bibliography styles. More is in
+<link linkend="Using-BibTeX">Using BibTeX</link>.)
</para>
<para>The optional argument <replaceable>subcite</replaceable> is appended to the citation. For
example, <literal>See 14.3 in \cite[p.~314]{texbook}</literal> might produce
&#8216;<literal>See 14.3 in [1, p.&#160;314]</literal>&#8217;.
</para>
+<para>In addition to what appears in the output, <literal>\cite</literal> writes
+information to the auxiliary file <filename><replaceable>filename</replaceable>.aux</filename>. For
+instance, <literal>\cite{latexdps}</literal> writes &#8216;<literal>\citation{latexdps}</literal>&#8217;
+to that file. This information is used by Bib&tex; to include in your
+reference list only those works that you have actually cited; see
+<link linkend="_005cnocite">\nocite</link> also.
+</para>
<para>If <replaceable>keys</replaceable> is not in your bibliography information then you get
&#8216;<literal>LaTeX Warning: There were undefined references</literal>&#8217;, and in the output
the citation shows as a boldface question mark between square brackets.
@@ -6534,14 +6432,7 @@ There are two possible causes. If you have mistyped something, as in
<literal>\cite{texbok}</literal> then you need to correct the spelling. On the
other hand, if you have just added or modified the bibliographic
information and so changed the <filename>.aux</filename> file (see <link linkend="_005cbibitem">\bibitem</link>) then
-the fix may be to just run &latex; again.
-</para>
-<para>In addition to what appears in the output, <literal>\cite</literal> writes
-information to the auxiliary file <filename><replaceable>filename</replaceable>.aux</filename>. For
-instance, <literal>\cite{latexdps}</literal> writes &#8216;<literal>\citation{latexdps}</literal>&#8217;
-to that file. This information is used by Bib&tex; to include in your
-reference list only those works that you have actually cited; see
-<link linkend="_005cnocite">\nocite</link> also.
+the fix may be to run &latex; again.
</para>
</sect2>
@@ -7971,7 +7862,130 @@ the repeated use of <literal>\providecommand</literal> does not give an error.
</para>
</sect1>
-<sect1 label="12.3" id="_005cnewcounter">
+<sect1 label="12.3" id="_005cmakeatletter-_0026-_005cmakeatother">
+<title><literal>\makeatletter</literal> &amp; <literal>\makeatother</literal></title>
+
+<para>Synopsis:
+</para>
+<screen>\makeatletter
+ ... definition of commands with @ in their name ..
+\makeatother
+</screen>
+<para>Use this pair when you redefine &latex; commands that are named with an
+at-sign character&#160;&#8216;<literal><literal>@</literal></literal>&#8217;. The <literal>\makeatletter</literal>
+declaration makes the at-sign character have the category code of a
+letter, code&#160;11. The <literal>\makeatother</literal> declaration sets the
+category code of the at-sign to code&#160;12, its default value.
+</para>
+<para>As &tex; reads characters, it assigns each one a 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 instance, it assigns the backslash
+character&#160;&#8216;<literal><literal>\</literal></literal>&#8217; the catcode&#160;0. Command names
+consist of a category&#160;0 character, ordinarily backslash, followed
+by letters, category&#160;11 characters (except that a command name can
+also consist of a category&#160;0 character followed by a single
+non-letter symbol).
+</para>
+<para>&latex;&#8217;s source code has the convention that some commands use
+<literal>@</literal> in their name. These commands are mainly intended for package
+or class writers. The convention prevents authors who are just using a
+package or class from accidentally replacing such a command with one of
+their own, because by default the at-sign has catcode&#160;12.
+</para>
+<para>The pair <literal>\makeatletter</literal> and <literal>\makeatother</literal> changes the
+default code and then changes it back. Use them inside a <filename>.tex</filename>
+file, in the preamble, when you are defining or redefining commands
+named with <literal>@</literal>, by having them surround your definition. Don&#8217;t
+use these inside <filename>.sty</filename> or <filename>.cls</filename> files since the
+<literal>\usepackage</literal> and <literal>\documentclass</literal> commands already arrange
+that the at-sign has the character code of a letter, catcode&#160;11.
+</para>
+<indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>macros2e</literal> package</primary></indexterm>
+
+<para>For a comprehensive list of macros with an at-sign in their names see
+<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>.
+</para>
+<para>In this example the class file has a command
+<literal>\thesis@universityname</literal> that the user wants to change. These
+three lines should go in the preamble, before the
+<literal>\begin{document}</literal>.
+</para>
+<screen>\makeatletter
+\renewcommand{\thesis@universityname}{Saint Michael's College}
+\makeatother
+</screen>
+
+</sect1>
+<sect1 label="12.4" 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>nostar-num-args</replaceable>]{<replaceable>nostar-body</replaceable>}
+\newcommand{\mycmd@star}[<replaceable>star-num-args</replaceable>]{<replaceable>star-body</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-_0026-_005cmakeatother">\makeatletter &amp; \makeatother</link>).
+</para>
+<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a
+variant <literal>\ciel*</literal>. Both have one required argument. A call to
+<literal>\ciel{night}</literal> will return &quot;starry night sky&quot; while
+<literal>\ciel*{blue}</literal> will return &quot;starry not blue sky&quot;.
+</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 the unstarred one. With this definition, Agent 007&#8217;s
+<literal>``My name is \agentsecret*{Bond},
+\agentsecret{James}{Bond}.''</literal> is equivalent to entering the commands
+<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>
+
+</sect1>
+<sect1 label="12.5" id="_005cnewcounter">
<title><literal>\newcounter</literal>: Allocating a counter</title>
<indexterm role="fn"><primary>\newcounter</primary></indexterm>
@@ -8020,7 +8034,7 @@ defined.</literal>&#8217;
</para>
</sect1>
-<sect1 label="12.4" id="_005cnewlength">
+<sect1 label="12.6" id="_005cnewlength">
<title><literal>\newlength</literal></title>
<indexterm role="fn"><primary>\newlength</primary></indexterm>
@@ -8051,7 +8065,7 @@ Or name \end... illegal, see p.192 of the manual</literal>&#8217;.
</para>
</sect1>
-<sect1 label="12.5" id="_005cnewsavebox">
+<sect1 label="12.7" id="_005cnewsavebox">
<title><literal>\newsavebox</literal></title>
<indexterm role="fn"><primary>\newsavebox</primary></indexterm>
@@ -8059,15 +8073,16 @@ Or name \end... illegal, see p.192 of the manual</literal>&#8217;.
<para>Synopsis:
</para>
-<screen>\newsavebox{<replaceable>cmd</replaceable>}
+<screen>\newsavebox{\<replaceable>cmd</replaceable>}
</screen>
-<para>Define <literal>\<replaceable>cmd</replaceable></literal> to refer to a new &#8220;bin&#8221; for storing boxes.
-Such a box is for holding typeset material, to use multiple times or to
-measure or manipulate (see <link linkend="Boxes">Boxes</link>). The required bin name
-<literal><replaceable>cmd</replaceable></literal> must start with a backslash, <literal>\</literal>, and must not
-already be defined. This command is fragile (see <link linkend="_005cprotect">\protect</link>).
+<para>Define \<replaceable>cmd</replaceable>, the string consisting of a backslash followed by
+<replaceable>cmd</replaceable>, to refer to a new bin for storing material. These bins hold
+material that has been typeset, to use multiple times or to measure or
+manipulate (see <link linkend="Boxes">Boxes</link>). The bin name \<replaceable>cmd</replaceable> is required, must
+start with a backslash, \, and must not already be a defined command.
+This command is fragile (see <link linkend="_005cprotect">\protect</link>).
</para>
-<para>The first line here sets you up to save the material for later use.
+<para>This allocates a bin and then puts typeset material into it.
</para>
<screen>\newsavebox{\logobox}
\savebox{\logobox}{LoGo}
@@ -8083,7 +8098,7 @@ Our logo is \usebox{\logobox}.
</para>
</sect1>
-<sect1 label="12.6" id="_005cnewenvironment-_0026-_005crenewenvironment">
+<sect1 label="12.8" id="_005cnewenvironment-_0026-_005crenewenvironment">
<title><literal>\newenvironment</literal> &amp; <literal>\renewenvironment</literal></title>
<indexterm role="fn"><primary>\newenvironment</primary></indexterm>
@@ -8229,7 +8244,7 @@ the document, use the environment like this.
</screen>
</sect1>
-<sect1 label="12.7" id="_005cnewtheorem">
+<sect1 label="12.9" id="_005cnewtheorem">
<title><literal>\newtheorem</literal></title>
<indexterm role="fn"><primary>\newtheorem</primary></indexterm>
@@ -8354,7 +8369,7 @@ by &#8216;<literal>Theorem&#160;2.1</literal>&#8217; and &#8216;<literal>Definit
</screen>
</sect1>
-<sect1 label="12.8" id="_005cnewfont">
+<sect1 label="12.10" id="_005cnewfont">
<title><literal>\newfont</literal></title>
<indexterm role="fn"><primary>\newfont</primary></indexterm>
@@ -8375,8 +8390,8 @@ boldface with a roman (see <link linkend="Fonts">Fonts</link>).
<screen>\newfont{\<replaceable>cmd</replaceable>}{<replaceable>font description</replaceable>}
</screen>
<para>Define a command <literal>\<replaceable>cmd</replaceable></literal> that will change the current font.
-The control sequence must must not already be defined. It must begin
-with a backslash, <literal>\</literal>.
+The control sequence must not already be defined. It must begin with a
+backslash, <literal>\</literal>.
</para>
<indexterm role="cp"><primary>at clause, in font definitions</primary></indexterm>
<indexterm role="cp"><primary>design size, in font definitions</primary></indexterm>
@@ -8398,7 +8413,7 @@ relative to the font&#8217;s design size, which is a value defined in the
</screen>
</sect1>
-<sect1 label="12.9" id="_005cprotect">
+<sect1 label="12.11" id="_005cprotect">
<title><literal>\protect</literal></title>
<indexterm role="fn"><primary>\protect</primary></indexterm>
@@ -8460,7 +8475,7 @@ to <literal>\protect\(..\protect\)</literal>.
</screen>
</sect1>
-<sect1 label="12.10" id="_005cignorespaces-_0026-_005cignorespacesafterend">
+<sect1 label="12.12" id="_005cignorespaces-_0026-_005cignorespacesafterend">
<title><literal>\ignorespaces &amp; \ignorespacesafterend</literal></title>
<indexterm role="fn"><primary>\ignorespaces</primary></indexterm>
@@ -8829,27 +8844,32 @@ bogus month value produces no output).
<para>A <firstterm>length</firstterm> is a measure of distance. Many &latex; commands take a
length as an argument.
</para>
-<para>This shows a box of the given length.
+<para>Lengths come in two types. A <firstterm>rigid length</firstterm> such as <literal>10pt</literal>
+does not contain a <literal>plus</literal> or <literal>minus</literal> component. (Plain &tex;
+calls this a <firstterm>dimen</firstterm>.) A <firstterm>rubber length</firstterm> (what Plain &tex;
+calls a <firstterm>skip</firstterm>) such as as with <literal>1cm plus0.05cm minus0.01cm</literal>
+can contain either or both of those components. In that rubber length,
+the <literal>1cm</literal> is the <firstterm>natural length</firstterm> while the other two, the
+<literal>plus</literal> and <literal>minus</literal> components, allow &tex; to stretch or
+shrink the length to optimize placement.
</para>
-<screen>\newcommand{\blackbar}[1]{\rule{#1}{10pt}} % make a bar
-\newcommand{\showhbox}[2]{\fboxsep=0pt\fbox{\hbox to #1{#2}}} % box it
-XXX\showhbox{100pt}{\blackbar{100pt}}YYY
-</screen>
-<para>It produces a black bar 100&#160;points long between &#8216;<literal>XXX</literal>&#8217; and
-&#8216;<literal>YYY</literal>&#8217;.
+<para>The illustrations below use these two commands.
</para>
-<para>Lengths come in two types. A <firstterm>rigid length</firstterm> (what Plain &tex;
-calls a <firstterm>dimen</firstterm>) such as <literal>10pt</literal> does not contain a <literal>plus</literal>
-or <literal>minus</literal> component. The above example shows a rigid length. A
-<firstterm>rubber length</firstterm> (what Plain &tex; calls a <firstterm>skip</firstterm>) can contain
-those components, as with <literal>1cm plus0.05cm minus0.01cm</literal>. Here the
-<literal>1cm</literal> is the <firstterm>natural length</firstterm> while the other two, the
-<literal>plus</literal> and <literal>minus</literal> components, allow the length to stretch or
-shrink.
+<screen>% make a black bar 10pt tall and #1 wide
+\newcommand{\blackbar}[1]{\rule{#1}{10pt}}
+
+% Make a box around #2 that is #1 wide (excluding the border)
+\newcommand{\showhbox}[2]{%
+ \fboxsep=0pt\fbox{\hbox to #1{#2}}}
+</screen>
+<para>This example uses those commands to show a black bar 100&#160;points
+long between &#8216;<literal>XXX</literal>&#8217; and &#8216;<literal>YYY</literal>&#8217;. This length is rigid.
</para>
-<para>Shrinking is simpler: with <literal>1cm minus 0.05cm</literal>, the natural length
-is 1cm but if smaller is needed then &tex; can shrink it down as
-far as 0.95cm. Beyond that, &tex; refuses to shrink any more.
+<screen>XXX\showhbox{100pt}{\blackbar{100pt}}YYY
+</screen>
+<para>As for rubber lengths, shrinking is simpler one: with <literal>1cm minus
+0.05cm</literal>, the natural length is 1cm but &tex; can shrink it down
+as far as 0.95cm. Beyond that, &tex; refuses to shrink any more.
Thus, below the first one works fine, producing a space of
98&#160;points between the two bars.
</para>
@@ -8866,7 +8886,7 @@ wider than the 300pt allocated, as &tex; has refused to shrink
the total to less than 309&#160;points.
</para>
<para>Stretching is like shrinking except that if &tex; is asked to stretch
-beyond the given amount, it won&#8217;t refuse. Here the first line is fine,
+beyond the given amount, it will do it. Here the first line is fine,
producing a space of 110&#160;points between the bars.
</para>
<screen>XXX\showhbox{300pt}{%
@@ -8876,11 +8896,9 @@ XXX\showhbox{300pt}{%
\blackbar{95pt}\hspace{100pt plus 1pt}\blackbar{95pt}}YYY
</screen>
<para>In the second line &tex; needs a stretch of 10&#160;points and only
-1&#160;point was specified. In this situation, &tex; stretches the
-space to the required length, but it complains with a warning like
-&#8216;<literal>Underfull \hbox (badness 10000) detected at line 22</literal>&#8217;. (We won&#8217;t
-discuss badness; the point is that the system was not given as much
-stretch as needed.)
+1&#160;point was specified. &tex; stretches the space to the required
+length but it gives you a warning like &#8216;<literal>Underfull \hbox (badness
+10000) detected at line 22</literal>&#8217;. (We won&#8217;t discuss badness.)
</para>
<para>You can put both stretch and shrink in the same length, as in
<literal>1ex plus 0.05ex minus 0.02ex</literal>.
@@ -8888,15 +8906,16 @@ stretch as needed.)
<para>If &tex; is setting two or more rubber lengths then it allocates the
stretch or shrink in proportion.
</para>
-<screen>XXX\showhbox{300pt}{\blackbar{100pt}% left
+<screen>XXX\showhbox{300pt}{%
+ \blackbar{100pt}% left
\hspace{0pt plus 50pt}\blackbar{80pt}\hspace{0pt plus 10pt}% middle
\blackbar{100pt}}YYY % right
</screen>
-<para>The outside bars take up 100&#160;points, so the middle needs another
-100. In the middle the bar takes up 80&#160;points, so the two
-<literal>\hspace</literal>&#8217;s must stretch 20&#160;points. Because the two say
-<literal>plus 50pt</literal> and <literal>plus 10pt</literal>, &tex; gets 5/6 of the
-stretch from the first space and 1/6 from the second.
+<para>The left and right bars take up 100&#160;points, so the middle needs
+another 100. The middle bar is 80&#160;points so the two
+<literal>\hspace</literal>&#8217;s must stretch 20&#160;points. Because the two are
+<literal>plus 50pt</literal> and <literal>plus 10pt</literal>, &tex; gets 5/6 of the stretch
+from the first space and 1/6 from the second.
</para>
<para>The <literal>plus</literal> or <literal>minus</literal> component of a rubber length can contain
a <firstterm>fill</firstterm> component, as in <literal>1in plus2fill</literal>. This gives the
@@ -8910,10 +8929,10 @@ the page.
\hspace{0pt plus 1fill}
\end{minipage}
</screen>
-<para>&tex; actually has three infinite glue components <literal>fil</literal>,
-<literal>fill</literal>, and <literal>filll</literal>. The later ones are more infinite than
-the earlier ones. Ordinarily document authors only use the middle one
-(see <link linkend="_005chfill">\hfill</link> and see <link linkend="_005cvfill">\vfill</link>).
+<para>&tex; actually has three levels of infinity for glue components:
+<literal>fil</literal>, <literal>fill</literal>, and <literal>filll</literal>. The later ones are more
+infinite than the earlier ones. Ordinarily document authors only use
+the middle one (see <link linkend="_005chfill">\hfill</link> and see <link linkend="_005cvfill">\vfill</link>).
</para>
<para>Multiplying a rubber length by a number turns it into a rigid length, so
that after <literal>\setlength{\ylength}{1in plus 0.2in}</literal> and
@@ -8933,7 +8952,7 @@ math mode.
<variablelist><varlistentry><term><literal>pt</literal>
</term><listitem><indexterm role="fn"><primary>pt</primary></indexterm>
<indexterm role="cp"><primary>Point</primary></indexterm>
-<anchor id="units-of-length-pt"/><para>Point 1/72.27 inch. The conversion to metric units, to two decimal
+<anchor id="units-of-length-pt"/><para>Point, 1/72.27 inch. The conversion to metric units, to two decimal
places, is 1point = 2.85mm = 28.45cm.
</para>
</listitem></varlistentry><varlistentry><term><literal>pc</literal>
@@ -9028,8 +9047,13 @@ while the second will not.
\setlength{\parindent}{0em}
He said stop going to those places.
</screen>
-<para>If there is no such length <replaceable>len</replaceable> then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \praindent</literal>&#8217;.
+<para>If you did not declare <replaceable>len</replaceable> with <literal>\newlength</literal>, for example if
+you mistype the above as
+<literal>\newlength{\specparindent}\setlength{\sepcparindent}{...}</literal>,
+then you get an error like &#8216;<literal>Undefined control sequence. &lt;argument&gt;
+\sepcindent</literal>&#8217;. If you omit the backslash at the start of the length name
+then you get an error like &#8216;<literal>Missing number, treated as zero. &lt;to be
+read again&gt; \relax l.19 \setlength{specparindent}{0.6\parindent}</literal>&#8217;
</para>
</sect1>
@@ -9051,16 +9075,18 @@ length</link>).
</para>
<para>Below, if <literal>\parskip</literal> starts with the value <literal>0pt plus 1pt</literal>
</para>
-<screen>\addtolength{\parskip}{1pt}
-Doctor: how is the boy who swallowed the silver dollar?
+<screen>Doctor: how is the boy who swallowed the silver dollar?
+\addtolength{\parskip}{1pt}
Nurse: no change.
</screen>
<para>then it has the value <literal>1pt plus 1pt</literal> for the second paragraph.
</para>
-<para>If there is no such length <replaceable>len</replaceable> then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \praindent</literal>&#8217;. If you leave
-off the backslash at the start of <replaceable>len</replaceable>, as in
+<para>If you did not declare the length <replaceable>len</replaceable> with <literal>\newlength</literal>, if
+for example you mistype the above as
+<literal>\addtolength{\specparindent}{0.6\praindent}</literal>, then you get
+something like &#8216;<literal>Undefined control sequence. &lt;argument&gt; \praindent</literal>&#8217;.
+If you leave off the backslash at the start of <replaceable>len</replaceable>, as in
<literal>\addtolength{parindent}{1pt}</literal>, then you get something like
&#8216;<literal>You can't use `the letter p' after \advance</literal>&#8217;.
</para>
@@ -9085,9 +9111,10 @@ begin with a backslash, <literal>\</literal>.
\settodepth{\alphabetdepth}{abcdefghijklmnopqrstuvwxyz}
\the\alphabetdepth
</screen>
-<para>If there is no such length <replaceable>len</replaceable> then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \alphabetdepth</literal>&#8217;. If you
-leave the backslash out of <replaceable>len</replaceable>, as in
+<para>If you did not set aside the length <replaceable>len</replaceable>, if for example you
+mistype the above as <literal>\settodepth{\aplhabetdepth}{abc...}</literal>,
+then you get something like &#8216;<literal>Undefined control sequence. &lt;argument&gt;
+\aplhabetdepth</literal>&#8217;. If you leave the backslash out of <replaceable>len</replaceable>, as in
<literal>\settodepth{alphabetdepth}{...}</literal> then you get something like
&#8216;<literal>Missing number, treated as zero. &lt;to be read again&gt; \setbox</literal>&#8217;.
</para>
@@ -9112,9 +9139,11 @@ begin with a backslash, <literal>\</literal>.
\settoheight{\alphabetheight}{abcdefghijklmnopqrstuvwxyz}
\the\alphabetheight
</screen>
-<para>If there is no such length <replaceable>len</replaceable> then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \alphabetheight</literal>&#8217;. If you
-leave the backslash out of <replaceable>len</replaceable>, as in
+<para>If no such length <replaceable>len</replaceable> has been declared with <literal>\newlength</literal>, if
+for example you mistype as
+<literal>\settoheight{\aplhabetheight}{abc...}</literal>, then you get something
+like &#8216;<literal>Undefined control sequence. &lt;argument&gt; \alphabetheight</literal>&#8217;. If
+you leave the backslash out of <replaceable>len</replaceable>, as in
<literal>\settoheight{alphabetheight}{...}</literal> then you get something like
&#8216;<literal>Missing number, treated as zero. &lt;to be read again&gt; \setbox</literal>&#8217;.
</para>
@@ -9139,42 +9168,14 @@ begin with a backslash, <literal>\</literal>.
\settowidth{\alphabetwidth}{abcdefghijklmnopqrstuvwxyz}
\the\alphabetwidth
</screen>
-<para>If there is no such length <replaceable>len</replaceable> then you get something like
-&#8216;<literal>Undefined control sequence. &lt;argument&gt; \alphabetwidth</literal>&#8217;. If you
-leave the backslash out of <replaceable>len</replaceable>, as in
+<para>If no such length <replaceable>len</replaceable> has been set aside, if for example you
+mistype the above as <literal>\settowidth{\aplhabetwidth}{abc...}</literal>,
+then you get something like &#8216;<literal>Undefined control sequence. &lt;argument&gt;
+\aplhabetwidth</literal>&#8217;. If you leave the backslash out of <replaceable>len</replaceable>, as in
<literal>\settoheight{alphabetwidth}{...}</literal> then you get something like
&#8216;<literal>Missing number, treated as zero. &lt;to be read again&gt; \setbox</literal>&#8217;.
</para>
-<!-- @node Predefined lengths -->
-<!-- @section Predefined lengths -->
-
-<!-- @cindex lengths, predefined -->
-<!-- @cindex predefined lengths -->
-
-<!-- @code{\width} -->
-<!-- @findex \width -->
-
-<!-- @code{\height} -->
-<!-- @findex \height -->
-
-<!-- @code{\depth} -->
-<!-- @findex \depth -->
-
-<!-- @code{\totalheight} -->
-<!-- @findex \totalheight -->
-
-<!-- These length parameters can be used in the arguments of the box-making -->
-<!-- commands (@pxref{Boxes}). They specify the natural width, etc., of the -->
-<!-- text in the box. @code{\totalheight} equals -->
-<!-- @math{@code{@backslashchar{}height} + @code{@backslashchar{}depth}}. To -->
-<!-- make a box with the text stretched to double the natural size, e.g., say -->
-
-<!-- @example -->
-<!-- \makebox[2\width]@{Get a stretcher@} -->
-<!-- @end example -->
-
-
</sect1>
</chapter>
<chapter label="15" id="Making-paragraphs">
@@ -9183,9 +9184,9 @@ leave the backslash out of <replaceable>len</replaceable>, as in
<indexterm role="cp"><primary>making paragraphs</primary></indexterm>
<indexterm role="cp"><primary>paragraphs</primary></indexterm>
-<para>Once &latex; has all of a paragraph&#8217;s contents it divides it into
-lines, in a way that is optimized over the entire paragraph (see <link linkend="Line-breaking">Line
-breaking</link>). To end the current paragraph, put an empty line.
+<para>To start a paragraph, just type some text. To end the current
+paragraph, put an empty line. This is three paragraphs, separated by
+two empty lines.
</para>
<screen>It is a truth universally acknowledged, that a single man in possession
of a good fortune, must be in want of a wife.
@@ -9201,6 +9202,10 @@ of some one or other of their daughters.
<para>The separator lines must be empty, including not containing a comment
character, <literal>%</literal>.
</para>
+<para>Once &latex; has gathered all of a paragraph&#8217;s contents it divides that
+content into lines in a way that is optimized over the entire paragraph
+(see <link linkend="Line-breaking">Line breaking</link>).
+</para>
<para>There are places where a new paragraph is not permitted. Don&#8217;t put a
blank line in math mode (see <link linkend="Modes">Modes</link>); here the line before the
<literal>\end{equation}</literal>
@@ -9229,7 +9234,7 @@ complete</literal>&#8217;.
<indexterm role="fn"><primary>\par</primary></indexterm>
<indexterm role="cp"><primary>paragraph, ending</primary></indexterm>
-<para>Synopsis (note that while reading the input &tex;, converts two
+<para>Synopsis (note that while reading the input &tex; converts two
consecutive newlines to a <literal>\par</literal>):
</para>
<screen>\par
@@ -9244,22 +9249,25 @@ readability.
<screen>\newcommand{\syllabusLegalese}{%
\whatCheatingIs\par\whatHappensWhenICatchYou}
</screen>
-<para>The <literal>\par</literal> command does nothing in LR mode or a vertical mode but
-it terminates paragraph mode, bringing &latex; to vertical mode
+<para>In LR mode or a vertical mode the <literal>\par</literal> command does nothing but
+it terminates paragraph mode, switching &latex; to vertical mode
(see <link linkend="Modes">Modes</link>).
</para>
-<para>You cannot use the <literal>\par</literal> command in math mode or in the argument
-of many commands, such as the <literal>\section</literal> command (see <link linkend="Making-paragraphs">Making
-paragraphs</link> and see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp; \renewcommand</link>).
+<para>You cannot use the <literal>\par</literal> command in a math mode. You also cannot
+use it in the argument of many commands, such as the <literal>\section</literal>
+command (see <link linkend="Making-paragraphs">Making paragraphs</link> and <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand &amp;
+\renewcommand</link>).
</para>
-<para>The <literal>\par</literal> command differs from the <literal>\paragraph</literal> command in
-that the latter is, like <literal>\section</literal> or <literal>\subsection</literal>, a
-sectioning unit used by the standard &latex; documents.
+<para>The <literal>\par</literal> command is not the same as the <literal>\paragraph</literal>
+command. The latter is, like <literal>\section</literal> or <literal>\subsection</literal>, a
+sectioning unit used by the standard &latex; documents
+(see <link linkend="_005csubsubsection-_0026-_005cparagraph-_0026-_005csubparagraph">\subsubsection &amp; \paragraph &amp; \subparagraph</link>).
</para>
-<para>The <literal>\par</literal> command differs from <literal>\newline</literal> and the line break
-double backslash, <literal>\\</literal>, in that \par ends the paragraph not just
-the line. It also triggers the addition of the between-paragraph
-vertical space <literal>\parskip</literal> (see <link linkend="_005cparindent-_0026-_005cparskip">\parindent &amp; \parskip</link>).
+<para>The <literal>\par</literal> command is not the same as <literal>\newline</literal> or the line
+break double backslash, <literal>\\</literal>. The difference is that <literal>\par</literal>
+ends the paragraph, not just the line, and also triggers the addition of
+the between-paragraph vertical space <literal>\parskip</literal> (see <link linkend="_005cparindent-_0026-_005cparskip">\parindent
+&amp; \parskip</link>).
</para>
<para>The output from this example
</para>
@@ -9404,9 +9412,9 @@ subsequent marginal notes in the opposite margin to that given in the
prior paragraph. Revert that to the default position with
<literal>\normalmarginpar</literal>.
</para>
-<para>When you specify the optional argument <replaceable>left</replaceable> then it is used for a
-note in the left margin, while the mandatory argument <replaceable>right</replaceable> is
-used for a note in the the right margin.
+<para>When you specify the optional argument <replaceable>left</replaceable> then it is used for
+a note in the left margin, while the mandatory argument <replaceable>right</replaceable> is
+used for a note in the right margin.
</para>
<para>Normally, a note&#8217;s first word will not be hyphenated. You can enable
hyphenation there by beginning <replaceable>left</replaceable> or <replaceable>right</replaceable> with
@@ -9654,7 +9662,7 @@ said otherwise, the commands for these symbols can be used only in math
mode. To redefine a command so that it can be used whatever the current
mode, see <link linkend="_005censuremath">\ensuremath</link>.
</para>
-<!-- xx Add Negation: @code{} for negations of relevant symbols -->
+<!-- xx Add Negation: for negations of relevant symbols -->
<!-- Useful: http://www.w3.org/TR/WD-math-970515/section6.html -->
<variablelist><varlistentry><term><indexterm role="fn"><primary>\|</primary></indexterm><literal>\|</literal>
@@ -11067,6 +11075,144 @@ in both text and math mode.
both text and math mode.
</para></listitem></varlistentry></variablelist>
+
+<sect2 label="16.6.1" id="_005csmash">
+<title><literal>\smash</literal></title>
+
+<indexterm role="cp"><primary>vertical spacing, math mode</primary></indexterm>
+<indexterm role="cp"><primary>math mode, vertical space</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\smash{<replaceable>subformula</replaceable>}
+</screen>
+<para>Typeset <replaceable>subformula</replaceable> as if its height and depth were zero.
+</para>
+<para>In this example the exponential is so tall that without the
+<literal>\smash</literal> command &latex; would separate its line from the line
+above it, and the uneven line spacing might be unsightly.
+</para>
+<screen>To compute the tetration $\smash{2^{2^{2^2}}}$,
+evaluate from the top down, as $2^{2^4}=2^{16}=65536$.
+</screen>
+<para>(Because of the <literal>\smash</literal> the printed expression could run into the
+line above so you may want to wait until the final version of the
+document to make such adjustments.)
+</para>
+<para>This pictures the effect of <literal>\smash</literal> by using <literal>\fbox</literal> to
+surround the box that &latex; will put on the line. The
+<literal>\blackbar</literal> command makes a bar extending from 10&#160;points below
+the baseline to 20&#160;points above.
+</para>
+<screen>\newcommand{\blackbar}{\rule[-10pt]{5pt}{30pt}}
+\fbox{\blackbar}
+\fbox{\smash{\blackbar}}
+</screen>
+<para>The first box that &latex; places is 20&#160;points high and
+10&#160;points deep. But the second box is treated by &latex; as
+having zero height and zero depth, despite that the ink printed on the
+page still extends well above and below the line.
+</para>
+<para>The <literal>\smash</literal> command appears often in mathematics to adjust the
+size of an element that surrounds a subformula. Here the first radical
+extends below the baseline while the second lies just on the baseline.
+</para>
+<screen>\begin{equation}
+\sqrt{\sum_{0\leq k&lt; n} f(k)}
+\sqrt{\vphantom{\sum}\smash{\sum_{0\leq k&lt; n}} f(k)}
+\end{equation}
+</screen>
+<para>Note the use of <literal>\vphantom</literal> to give the <literal>\sqrt</literal> command an
+argument with the height of the <literal>\sum</literal> (see <link linkend="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom">\phantom &amp; \vphantom
+&amp; \hphantom</link>).
+</para>
+<para>While most often used in mathematics, the <literal>\smash</literal> command can
+appear in other contexts. However, it doesn&#8217;t change into horizontal
+mode. So if it starts a paragraph then you should first put a
+<literal>\leavevmode</literal>, as in the bottom line below.
+</para>
+<screen>xxx xxx xxx
+
+\smash{yyy} % no paragraph indent
+
+\leavevmode\smash{zzz} % usual paragraph indent
+</screen>
+<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
+
+<para>The package <literal>mathtools</literal> has operators that provide even finer
+control over smashing a subformula box.
+</para>
+
+</sect2>
+<sect2 label="16.6.2" id="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom">
+<title><literal>\phantom</literal> &amp; <literal>\vphantom</literal> &amp; <literal>\hphantom</literal></title>
+
+<indexterm role="cp"><primary>spacing, math mode</primary></indexterm>
+<indexterm role="cp"><primary>horizontal spacing</primary></indexterm>
+<indexterm role="cp"><primary>vertical spacing</primary></indexterm>
+<indexterm role="cp"><primary>math mode, spacing</primary></indexterm>
+<indexterm role="cp"><primary>invisible character</primary></indexterm>
+<indexterm role="cp"><primary>character, invisible</primary></indexterm>
+
+<para>Synopsis:
+</para>
+<screen>\phantom{<replaceable>subformula</replaceable>}
+</screen>
+<para>or
+</para>
+<screen>\vphantom{<replaceable>subformula</replaceable>}
+</screen>
+<para>or
+</para>
+<screen>\hphantom{<replaceable>subformula</replaceable>}
+</screen>
+<para>The <literal>\phantom</literal> command creates a box with the same height, depth,
+and width as <replaceable>subformula</replaceable>, but empty. That is, this command causes
+&latex; to typeset the box but not its ink. The <literal>\vphantom</literal>
+variant also produces an invisible box with the same height and depth as
+<replaceable>subformula</replaceable>, but it has width zero. And <literal>\hphantom</literal> makes a
+box with the same width as <replaceable>subformula</replaceable> but with height and depth
+zero.
+</para>
+<para>Without the <literal>\vphantom</literal> in this example, the top bars of the two
+square roots would be at different heights.
+</para>
+<screen>\( \sqrt{\vphantom{a^3}a}\cdot\sqrt{a^3} \)
+</screen>
+<para>The <literal>\vphantom{a^3}</literal> causes the first <literal>\sqrt</literal> to have inside
+it a box of the same height as the second <literal>\sqrt</literal>, so &latex;
+makes the bars align.
+</para>
+<para>These commands often are combined with <literal>\smash</literal>. See <link linkend="_005csmash">\smash</link>
+for another example of the use of <literal>\vphantom</literal>.
+</para>
+<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm>
+
+<para>The three phantom commands appear often but note that &latex; provides
+a suite of other commands to work with box sizes that may be more
+convenient, including <literal>\makebox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox &amp; \makebox</link>) as well
+as <literal>\settodepth</literal> (see <link linkend="_005csettodepth">\settodepth</link>), <literal>\settoheight</literal>
+(see <link linkend="_005csettoheight">\settoheight</link>), and <literal>\settowidth</literal> (see <link linkend="_005csettowidth">\settowidth</link>).
+In addition, the <filename>mathtools</filename> package has many commands that offer
+fine-grained control over spacing.
+</para>
+<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm>
+<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm>
+
+<para>All three commands produce an ordinary box, without any special
+mathematics status. So to do something like attaching a superscript you
+should give it such a status, for example with the <literal>\operatorname</literal>
+command from the package <filename>amsmath</filename>.
+</para>
+<para>While most often used in mathematics, these three can appear in other
+contexts. However, they don&#8217;t cause &latex; to change into horizontal
+mode. So if one of these starts a paragraph then you should prefix it
+with <literal>\leavevmode</literal>.
+</para>
+
+</sect2>
</sect1>
<sect1 label="16.7" id="Math-miscellany">
<title>Math miscellany</title>
@@ -11297,7 +11443,7 @@ back to paragraph mode.
</para>
<indexterm role="cp"><primary>inner paragraph mode</primary></indexterm>
<indexterm role="cp"><primary>outer paragraph mode</primary></indexterm>
-<anchor id="modes-inner-paragraph-mode"/><anchor id="modes-outer-paragraph-mode"/><para>Paragraph mode has two subcases. If you use a <literal>\parbox</literal> command or
+<anchor id="modes-inner-paragraph-mode"/><anchor id="modes-outer-paragraph-mode"/><para>Paragraph mode has two subcases. If you use a <literal>\parbox</literal> command
or a <literal>minipage</literal> then &latex; is put into paragraph mode. But it
will not put a page break here. Inside one of these boxes, called a
<firstterm>parbox</firstterm>, &latex; is in <firstterm>inner paragraph mode</firstterm>. Its more usual
@@ -11415,9 +11561,10 @@ To have no date, instead use <literal>\date{}</literal>.
</term><listitem><indexterm role="cp"><primary>thanks, for titlepage</primary></indexterm>
<indexterm role="cp"><primary>credit footnote</primary></indexterm>
<para>Optional. Produce a footnote. You can use it in the author information
-for acknowledgements, as illustrated below, but you can also use it in
-the title, or any place a footnote makes sense. It can be any text so
-you can use it to print an email address, or for any purpose.
+for acknowledgements as illustrated above, but you can also use it in
+the title, or any place a footnote makes sense. It can be any text at
+all so you can use it for any purpose, such as to print an email
+address.
</para>
</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\title{<replaceable>text</replaceable>}</primary></indexterm><literal>\title{<replaceable>text</replaceable>}</literal>
</term><listitem><indexterm role="cp"><primary>title, for titlepage</primary></indexterm>
@@ -11428,11 +11575,11 @@ omit the <literal>\title</literal> declaration then you get &#8216;<literal>LaTe
\title given</literal>&#8217;.
</para>
</listitem></varlistentry></variablelist>
-<para>Many publishers will provide a class to use in place of <literal>article</literal>
-in that example, that formats the title according to their house
-requirements. To make your own, see&#160;<link linkend="titlepage">titlepage</link>. You can
-either create this as a one-off or you can include it as part of a
-renewed <literal>\maketitle</literal> command.
+<para>To make your own title page, see&#160;<link linkend="titlepage">titlepage</link>. You can either
+create this as a one-off or you can include it as part of a renewed
+<literal>\maketitle</literal> command. (Many publishers will provide a class to use
+in place of <literal>article</literal> that formats the title according to their
+house requirements.)
</para>
</sect1>
@@ -11464,7 +11611,7 @@ are numbered &#8216;<literal>1</literal>&#8217;, etc.
also&#160;<link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>).
</para>
<variablelist><varlistentry><term><literal>arabic</literal>
-</term><listitem><para>arabic numerals: 1, 2, &#8230;
+</term><listitem><para>Arabic numerals: 1, 2, &#8230;
</para>
</listitem></varlistentry><varlistentry><term><literal>roman</literal>
</term><listitem><para>lowercase Roman numerals: i, ii, &#8230;
@@ -11617,7 +11764,7 @@ or environments.
</para>
<para>Often the first page of a chapter or section has a different style. For
example, this &latex; book document has the first page of the first
-chapter in in <literal>plain</literal> style, as is the default (see <link linkend="Page-styles">Page
+chapter in <literal>plain</literal> style, as is the default (see <link linkend="Page-styles">Page
styles</link>).
</para>
<screen>\documentclass{book}
@@ -11984,32 +12131,32 @@ backslash followed by a space. Synopsis:
<para>Produce a space. By default it produces white space of length
3.33333pt plus 1.66666pt minus 1.11111pt.
</para>
-<para>A blank is not a space. When you type a blank between words, &latex;
-produces white space. That&#8217;s different from an explicit space. This
-illustrates.
+<para>When you type one or more blanks between words, &latex; produces white
+space. But that is different than an explicit space. This illustrates.
</para>
<screen>\begin{tabular}{l}
+One blank: makes some space \\
Three blanks: in a row \\
Three spaces:\ \ \ in a row \\
\end{tabular}
</screen>
-<para>On the first line &latex; collapses the three blanks to output one
-whitespace (it would be the same with a single blank or, for instance,
-with a blank and an tab and a blank, or a blank and a newline and a
-blank). But the second line asks for three spaces so the white area is
-wider. Thus, the backslash-space command will create some horizontal
-space. (But the best way to create horizontal space is with
-<literal>\hspace</literal>; See <link linkend="_005chspace">\hspace</link>.)
-</para>
-<para>The backslash-space command has two main uses. First, it is often used
-after control sequences to keep them from gobbling the space that
-follows, as in <literal>\TeX\ is nice</literal>. (But the approach of using curly
-parentheses, as in <literal>\TeX{} is nice</literal>, has the advantage of still
-working if the next character is a period.)
-</para>
-<para>The second common use is that
-it mark a period as ending an abbreviation instead of ending
-a sentence, as in <literal>So says Prof.\ Smith</literal> (see <link linkend="_005c_0040">\@</link>).
+<para>On the first line &latex; puts some space after the colon. On the
+second line &latex; collapses the three blanks to output one
+whitespace, so you end with the same space after the colon as in the
+first line. &latex; would similarly collapse a blank followed by a
+tab, or a blank and a newline and a blank. However, the bottom line
+asks for three spaces so the white area is wider. That is, the
+backslash-space command creates a fixed amount of horizontal space.
+(Note that you can define a horizontal space of any width at all with
+<literal>\hspace</literal>; see&#160;<link linkend="_005chspace">\hspace</link>.)
+</para>
+<para>The backslash-space command has two main uses. It is often used after
+control sequences to keep them from gobbling the space that follows, as
+in <literal>\TeX\ is nice</literal>. (But using curly parentheses, as in
+<literal>\TeX{} is best</literal>, has the advantage of still working if the next
+character is a period.) The other common use is that it marks a period
+as ending an abbreviation instead of ending a sentence, as in <literal>So
+says Prof.\ Smith</literal> (see <link linkend="_005c_0040">\@</link>).
</para>
<para>Under normal circumstances, <literal>\</literal><keycap>tab</keycap> and <literal>\</literal><keycap>newline</keycap>
are equivalent to backslash-space, <literal>\ </literal>.
@@ -12357,11 +12504,11 @@ item&#8217;s second line.
\end{enumerate}
\end{minipage}%
</screen>
-<para>The final two lists use <literal>fbox</literal> to show what&#8217;s happening. The third
-list&#8217;s <literal>\parbox</literal> goes only to the bottom of its second &#8216;<literal>test</literal>&#8217;,
-which happens not have any characters that descend below the baseline.
-The fourth list adds the strut that gives the needed extra
-below-baseline space.
+<para>The final two lists use <literal>\fbox</literal> to show what&#8217;s happening. The
+third list&#8217;s <literal>\parbox</literal> goes only to the bottom of its second
+&#8216;<literal>test</literal>&#8217;, which happens not have any characters that descend below
+the baseline. The fourth list adds the strut that gives the needed
+extra below-baseline space.
</para>
<indexterm role="cp"><primary>package, <literal>TikZ</literal></primary></indexterm>
<indexterm role="cp"><primary><literal>TikZ</literal> package</primary></indexterm>
@@ -12551,6 +12698,7 @@ with a <literal>\par</literal> command (see <link linkend="_005cpar">\par</link>
<indexterm role="cp"><primary>boxes</primary></indexterm>
+<!-- xx Expand on boxes and glue, for xref from elsewhere. -->
<para>At its core, &latex; puts things in boxes and then puts the boxes on a
page. So these commands are central.
</para>
@@ -12575,7 +12723,7 @@ One useful adjunct to the commands here is <filename>adjustbox</filename>.
\makebox[<replaceable>width</replaceable>]{<replaceable>text</replaceable>}
\makebox[<replaceable>width</replaceable>][<replaceable>position</replaceable>]{<replaceable>text</replaceable>}
</screen>
-<para>Create a box, a container for material. The <replaceable>text</replaceable> is is typeset in
+<para>Create a box, a container for material. The <replaceable>text</replaceable> is typeset in
LR mode (see <link linkend="Modes">Modes</link>) so it is not broken into lines. The
<literal>\mbox</literal> command is robust, while <literal>\makebox</literal> is fragile
(see <link linkend="_005cprotect">\protect</link>).
@@ -13007,9 +13155,9 @@ robust (see <link linkend="_005cprotect">\protect</link>).
<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>Color support comes as an additional package. So put
+<literal>\usepackage{color}</literal> in your document preamble to use the
+commands described here.
</para>
<para>Many other packages also supplement &latex;&#8217;s color abilities.
Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and
@@ -13629,7 +13777,7 @@ 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
+be treated as an <literal>eps</literal> file, with 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>
@@ -13994,11 +14142,11 @@ external commands.
<indexterm role="cp"><primary>rotating text</primary></indexterm>
<indexterm role="fn"><primary>\rotatebox</primary></indexterm>
-<para>Synopsis for <filename>graphics</filename> package:
+<para>Synopsis if you use the <filename>graphics</filename> package:
</para>
<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>}
</screen>
-<para>Synopses for <filename>graphicx</filename> package:
+<para>Synopses if you use the <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>}
@@ -14029,10 +14177,11 @@ 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>).
+reference point of the box. If you use the <filename>graphicx</filename> package
+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.
@@ -14040,14 +14189,14 @@ Possible value is 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, the first line here
</para>
-<screen>\includegraphics[angle=180,origin=c]{moon}
-\includegraphics[angle=180,origin=lB]{LeBateau}
+<screen>\rotatebox[origin=c]{180}{moon}
+\rotatebox[origin=lB]{180}{LeBateau}
</screen>
<para>will turn the picture upside down from the center while the second 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>.
+the vertical center in <literal>lc</literal> or <literal>rc</literal>, and gives both in
+<literal>c</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
@@ -15670,7 +15819,7 @@ multiple indices and contains a command
<para>The <literal>\index</literal> command writes the indexing information to the file
<filename><replaceable>root-name</replaceable>.idx</filename> file. Specifically, it writes text of the
command
-<literal>\indexentry{<replaceable>index-entry-string</replaceable>}{<replaceable>page-num</replaceable>}</literal>, where
+<literal>\indexentry{<replaceable>index-entry-string</replaceable>}{<replaceable>page-num</replaceable>}</literal>,
where <replaceable>page-num</replaceable> is the value of the <literal>\thepage</literal> counter. On
occasion, when the <literal>\printindex</literal> command is confused, you have to
delete this file to start with a fresh slate.
@@ -15758,7 +15907,7 @@ plus5pt minus3pt</literal>).
<anchor id="makeindex-letheadflag"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lethead_flag</primary></indexterm><literal>lethead_flag</literal>
</term><listitem><para>An integer. It governs what is inserted for a new group or letter. If
it is 0 (which is the default) then other than <literal>group_skip</literal> nothing
-will be inserted before the group. If it is is positive then at a new
+will be inserted before the group. If it is positive then at a new
letter the <literal>lethead_prefix</literal> and <literal>lethead_suffix</literal> will be
inserted, with that letter in uppercase between them. If it is negative
then what will be inserted is the letter in lowercase. The default
@@ -15846,12 +15995,12 @@ roman <literal>R</literal>, and uppercase alphabetic <literal>A</literal>. Defa
</listitem></varlistentry></variablelist>
<indexterm role="fn"><primary>xindy</primary></indexterm>
<indexterm role="cp"><primary><command>xindy</command> program</primary></indexterm>
-<para>There are a number of other programs that do the job <command>makeindex</command>
-does. One is <command>xindy</command>, which does internationalization and can
-process indexes for documents marked up using &latex; and a number of
-other languages. It is is highly configurable, both in markup terms and
-in terms of the collating order of the text. See the documentation on
-CTAN.
+<para>There are a number of other programs that do the job
+<command>makeindex</command> does. One is <command>xindy</command>, which does
+internationalization and can process indexes for documents marked up
+using &latex; and a number of other languages. It is highly
+configurable, both in markup terms and in terms of the collating order
+of the text, as described in its documentation.
</para>
</sect2>
@@ -16614,9 +16763,9 @@ and output file will then be named <filename><replaceable>string</replaceable>.l
<replaceable>argument</replaceable> does not start with a backslash then &tex; considers it
the name of a file to input. Otherwise it waits for the first
<literal>\input</literal> instruction and the name of the input file will be the job
-name. This is used to name the log file the output file. This option
-overrides that process and directly specifies the name. See <link linkend="Command-line-input">Command
-line input</link> for an example of its use.
+name. This is used to name the log file the output file. The
+<literal>jobname</literal> option overrides that process and directly specifies the
+name. See <link linkend="Command-line-input">Command line input</link> for an example of its use.
</para>
<indexterm role="fn"><primary>--output-directory command-line option</primary></indexterm>
</listitem></varlistentry><varlistentry><term><literal>-output-directory=<replaceable>directory</replaceable></literal>
@@ -16626,10 +16775,10 @@ line input</link> for an example of its use.
<indexterm role="fn"><primary>--no-shell-escape command-line option</primary></indexterm>
<indexterm role="fn"><primary>--enable-write18 command-line option</primary></indexterm>
<indexterm role="fn"><primary>--disable-write18 command-line option</primary></indexterm>
-</listitem></varlistentry><varlistentry><term><literal>shell-escape</literal>
-</term><term><literal>no-shell-escape</literal>
-</term><term><literal>enable-write18</literal>
-</term><term><literal>disable-write18</literal>
+</listitem></varlistentry><varlistentry><term><literal>--shell-escape</literal>
+</term><term><literal>--no-shell-escape</literal>
+</term><term><literal>--enable-write18</literal>
+</term><term><literal>--disable-write18</literal>
</term><listitem><para>Enable or disable <literal>\write18{<replaceable>shell command</replaceable>}</literal>. The first two
options are for with &tex; Live or Mac&tex; while the second two are
for MiK&tex;.
@@ -16694,8 +16843,8 @@ PDF.
...
</screen>
<para>Compiling this document <filename>book.tex</filename> with the command line
-<literal>pdflatex test</literal> will give the &#8216;<literal>CTAN</literal>&#8217; link in blue. But
-compiling it with <literal>pdflatex &quot;\def\paperversion{}\input test.tex&quot;</literal>
+<literal>pdflatex book</literal> will give the &#8216;<literal>CTAN</literal>&#8217; link in blue. But
+compiling it with <literal>pdflatex &quot;\def\paperversion{}\input book.tex&quot;</literal>
has the link in black. (Note the use of double quotes to prevent
interpretation of the symbols by the command line shell; your system may
do this differently.)
@@ -16717,7 +16866,7 @@ called <filename>main.pdf</filename> and the second would overwrite the first.
<screen>pdflatex -jobname=aa &quot;\RequirePackage[draft]{graphicx}\input{aa.tex}&quot;
</screen>
<para>so the graphic files are read for their size information but not
-incorporated into the PDF. (The <literal>jobname</literal> option is needed because
+incorporated into the PDF. (The <literal>jobname</literal> option is there because
otherwise the output file would be <filename>graphicx.pdf</filename>, as
<literal>\RequirePackage</literal> does an <literal>\input</literal> of its own.)
</para>
@@ -16761,8 +16910,8 @@ instead of <literal>pdflatex test</literal> you might type <literal>pdflatex tst
(Press Enter to retry, or Control-D to exit)
Please type another input file name:
</screen>
-<para>The simplest thing is to enter <literal>&lt;Contol&gt;</literal> and &#8216;<literal>d</literal>&#8217; (holding
-them down at the same time), and just fix the command line.
+<para>The simplest thing is to enter <literal>&lt;Control&gt;</literal> and &#8216;<literal>d</literal>&#8217; (holding
+them down at the same time), and then retype the correct command line.
</para>
</sect1>