diff options
author | Karl Berry <karl@freefriends.org> | 2015-10-25 22:35:59 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-10-25 22:35:59 +0000 |
commit | f68a915f164bf116f1bb31ab3e1d9f5b94824e29 (patch) | |
tree | 54152ae2daf301e13c0f592129a46d03ee92370f /Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk | |
parent | c4586dcabf84bccd9caaff8f5b8dcb7cffe324a2 (diff) |
latex2e-help-texinfo (25oct15)
git-svn-id: svn://tug.org/texlive/trunk@38709 c570f23f-e606-0410-a88d-b1316a301751
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.dbk | 4950 |
1 files changed, 3579 insertions, 1371 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 960c331c619..dd1f9b3d58a 100644 --- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk +++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk @@ -4,7 +4,7 @@ <!ENTITY latex "LaTeX"> ]> <book id="latex2e.dbk" lang="en"> -<title>&latex;2e unofficial reference manual (May 2015)</title> +<title>&latex;2e unofficial reference manual (October 2015)</title> <!-- %**end of header (This is for running Texinfo on a region.) --> <!-- latex 2.09 commands should all be present now, --> @@ -19,6 +19,8 @@ <!-- xx merge http://mirror.ctan.org/latex2e-reference.tar.gz --> <!-- xx merge permuted-index --> <!-- xx merge latex-manual from savannah --> +<!-- xx merge display style math --> +<!-- xx vertical mode, horizontal mode --> <!-- --> <!-- xx The typeset source2e has an index with all kernel --> <!-- xx commands, though some are internal and shouldn't be included. --> @@ -26,7 +28,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 May 2015. +document preparation system, version of October 2015. </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 @@ -63,7 +65,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 May 2015. +document preparation system, version of October 2015. </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 @@ -99,11 +101,13 @@ into another language, under the above conditions for modified versions. </para> +<!-- 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 -May 2015) for &latex;2e, a document preparation system. +October 2015) for &latex;2e, a document preparation system. </para> @@ -186,7 +190,7 @@ should be formatted. It is implemented as a set of related commands that interface with Donald E. Knuth’s &tex; typesetting program (the technical term is that &latex; is a <firstterm>macro package</firstterm> for the &tex; engine). The user produces the output document by giving that -file to the &tex; engine. +input file to the &tex; engine. </para> <para>The term &latex; is also sometimes used to mean the language in which the document is marked up, that is, to mean the set of commands @@ -205,12 +209,12 @@ sensible, such as in plain text, write it as ‘<literal>LaTeX</literal>R <title>Starting and ending</title> <anchor id="Starting-_0026-ending"/><!-- old name --> -<indexterm role="cp"><primary>starting & ending</primary></indexterm> -<indexterm role="cp"><primary>ending & starting</primary></indexterm> +<indexterm role="cp"><primary>starting and ending</primary></indexterm> +<indexterm role="cp"><primary>ending and starting</primary></indexterm> <indexterm role="cp"><primary>hello, world</primary></indexterm> -<para>&latex; files have a simple global structure, with a standard -starting and ending. Here is a “hello, world” example: +<para>&latex; files have a simple global structure, with a standard beginning +and ending. Here is a “hello, world” example: </para> <screen>\documentclass{article} \begin{document} @@ -229,9 +233,10 @@ array of others are widely available. See <link linkend="Document-classes">Docu This area is called the <firstterm>preamble</firstterm>. </para> <para>The <literal>\begin{document} ... \end{document}</literal> is a so-called +<indexterm role="cp"><primary>environment</primary></indexterm> <firstterm>environment</firstterm>; the ‘<literal>document</literal>’ environment (and no others) is -required in all &latex; documents. &latex; provides many -environments itself, and many more are defined separately. +required in all &latex; documents (see <link linkend="document">document</link>). &latex; +provides many environments itself, and many more are defined separately. See <link linkend="Environments">Environments</link>. </para> <para>The following sections discuss how to produce PDF or other output from @@ -333,7 +338,7 @@ overview of the main programs. </term><listitem><indexterm role="cp"><primary>pdf&tex; engine</primary></indexterm> <indexterm role="fn"><primary>etex command</primary></indexterm> <indexterm role="cp"><primary>e-&tex;</primary></indexterm> -<para>In &tex; Live (<ulink url="http://tug.org/texlive">http://tug.org/texlive</ulink>, if &latex; is invoked +<para>In &tex; Live (<ulink url="http://tug.org/texlive">http://tug.org/texlive</ulink>), if &latex; is invoked via either the system command <command>latex</command> or <command>pdflatex</command>, then the pdf&tex; engine is run (<ulink url="http://ctan.org/pkg/pdftex">http://ctan.org/pkg/pdftex</ulink>). When invoked as <command>latex</command>, the main output is a <filename>.dvi</filename> @@ -342,9 +347,9 @@ file; as <command>pdflatex</command>, the main output is a <filename>.pdf</filen <para>pdf&tex; incorporates the e-&tex; extensions to Knuth’s original program (<ulink url="http://ctan.org/pkg/etex">http://ctan.org/pkg/etex</ulink>), including additional programming features and bi-directional typesetting, and has plenty of -extensions of its own. e-&tex; is available on its own as the +extensions of its own. e-&tex; is available on its own as the system command <command>etex</command>, but this is plain &tex; (and produces -<filename>.dvi</filename>). +<filename>.dvi</filename>). </para> <para>In other &tex; distributions, <command>latex</command> may invoke e-&tex; rather than pdf&tex;. In any case, the e-&tex; extensions can be @@ -365,12 +370,19 @@ but this is rarely used. </listitem></varlistentry><varlistentry><term><literal>xelatex</literal> </term><listitem><indexterm role="fn"><primary>xelatex command</primary></indexterm> <indexterm role="cp"><primary>Xe&tex;</primary></indexterm> +<indexterm role="fn"><primary>.xdv file</primary></indexterm> +<indexterm role="fn"><primary>xdvipdfmx</primary></indexterm> <para>If &latex; is invoked with the system command <command>xelatex</command>, the Xe&tex; engine is run (<ulink url="http://tug.org/xetex">http://tug.org/xetex</ulink>). Like Lua&tex;, -Xe&tex; also natively supports UTF-8 Unicode and TrueType and -OpenType fonts, though the implementation is completely different, -mainly using external libraries instead of internal code. Xe&tex; -produces a <filename>.pdf</filename> file as output; it does not support DVI output. +Xe&tex; natively supports UTF-8 Unicode and TrueType and OpenType +fonts, though the implementation is completely different, mainly using +external libraries instead of internal code. Xe&tex; produces a +<filename>.pdf</filename> file as output; it does not support DVI output. +</para> +<para>Internally, Xe&tex; creates an <literal>.xdv</literal> file, a variant of DVI, +and translates that to PDF using the (<literal>x</literal>)<literal>dvipdfmx</literal> +program, but this process is automatic. The <literal>.xdv</literal> file is only +useful for debugging. </para> </listitem></varlistentry></variablelist> <para>Other variants of &latex; and &tex; exist, e.g., to provide @@ -386,27 +398,76 @@ additional support for Japanese and other languages ([u]p&tex;, <indexterm role="fn"><primary>\ character starting commands</primary></indexterm> <indexterm role="fn"><primary>[...] for optional arguments</primary></indexterm> <indexterm role="fn"><primary>{...} for required arguments</primary></indexterm> -<para>In the &latex; input file, a command name starts with a <literal>\</literal>; the -name itself then consists of either (a) a string of letters or -(b) a single non-letter. +<para>In the &latex; input file, a command name starts with a backslash +character, <literal>\</literal>. The name itself then consists of either +(a) a string of letters or (b) a single non-letter. +</para> +<para>&latex; commands names are case sensitive so that <literal>\pagebreak</literal> +differs from <literal>\Pagebreak</literal> (the latter is not a standard command). +Most commands are lowercase, but in any event you must enter all +commands in the same case as they are defined. +</para> +<para>A command may be followed by zero, one, or more arguments. These +arguments may be either required or optional. Required arguments are +contained in curly braces, <literal>{...}</literal>. Optional arguments are +contained in square brackets, <literal>[...]</literal>. Generally, but not +universally, if the command accepts an optional argument, it comes +first, before any required arguments. +</para> +<para>Inside of an optional argument, to use the character close square +bracket (<literal>]</literal>) hide it inside curly braces, as +in <literal>\item[closing bracket {]}]</literal>. Similarly, if an optional +argument comes last, with no required argument after it, then to make +the first character of the following text be an open square bracket, +hide it inside curly braces. +</para> +<para>&latex; has the convention that some commands have a <literal>*</literal> form that +is related to the form without a <literal>*</literal>, such as <literal>\chapter</literal> and +<literal>\chapter*</literal>. The exact difference in behavior varies from command +to command. </para> -<para>A command may be followed by zero, one, or more arguments, either -required or optional. Required arguments are contained in curly -braces, <literal>{...}</literal>. Optional arguments are contained in square -brackets, <literal>[...]</literal>. Generally, but not universally, if the -command accepts an optional argument, it comes first, before any -required arguments. +<para>This manual describes all accepted options and <literal>*</literal>-forms for the +commands it covers (barring unintentional omissions, a.k.a. bugs). </para> -<para>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>. + + +<anchor id="Environment"/> + +<para>Synopsis: </para> -<para>&latex; commands are case sensitive; neither <literal>\Begin{document}</literal> -nor <literal>\begin{Document}</literal> will work. Most commands are lowercase, -but in any event you must enter all commands in the same case as they -are defined. +<screen>\begin{<replaceable>environment name</replaceable>} + .. +\end{<replaceable>environment name</replaceable>} +</screen> +<para>An area of &latex; source, inside of which there is a distinct +behavior. For instance, for poetry in &latex; put the lines between +<literal>\begin{verse}</literal> and <literal>\end{verse}</literal>. </para> -<para>This manual describes all accepted options and <literal>*</literal>-forms for the -commands it covers (barring unintentional omissions, a.k.a. bugs). +<screen>\begin{verse} + There once was a man from Nantucket \\ + .. +\end{verse} +</screen> +<para>The <replaceable>environment name</replaceable> at the beginning must exactly match that at +the end. This includes the case where <replaceable>environment name</replaceable> ends in a +star (<literal>*</literal>); both the <literal>\begin</literal> and <literal>\end</literal> texts must +include the star. +</para> +<para>Environments may have arguments, including optional arguments. This +example produces a table. The first argument is optional (and causes +the table to be aligned on its top row) while the second argument is +required (it specifies the formatting of columns). +</para> +<screen>\begin{tabular}[t]{r|l} + .. rows of table .. +\end{tabular} +</screen> + +<anchor id="Declaration"/> + +<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> </sect1> @@ -440,6 +501,10 @@ see <link linkend="Overview">Overview</link>.) matter, such as a preface, and back matter, such as an appendix (see <link linkend="Front_002fback-matter">Front/back matter</link>). </para> +</listitem></varlistentry><varlistentry><term><literal>letter</literal> +</term><listitem><para>Mail, optionally including mailing labels +(see <link linkend="Letters">Letters</link>). +</para> </listitem></varlistentry><varlistentry><term><literal>report</literal> </term><listitem><para>For documents of length between an <literal>article</literal> and a <literal>book</literal>, such as technical reports or theses, which may contain several chapters. @@ -485,10 +550,34 @@ options for selecting the typeface size (default is <literal>10pt</literal>): <indexterm role="fn"><primary>legalpaper option</primary></indexterm> <indexterm role="fn"><primary>letterpaper option</primary></indexterm> <para>All of the standard classes accept these options for selecting the paper -size (default is <literal>letterpaper</literal>): +size (these show height by width): +</para> +<variablelist><varlistentry><term><literal>a4paper</literal> +</term><listitem><para>210 by 297 mm (about 8.25 by 11.75 inches) +</para> +</listitem></varlistentry><varlistentry><term><literal>b5paper</literal> +</term><listitem><para>176 by 250 mm (about 7 by 9.875 inches) +</para> +</listitem></varlistentry><varlistentry><term><literal>executivepaper</literal> +</term><listitem><para>7.25 by 10.5 inches +</para> +</listitem></varlistentry><varlistentry><term><literal>legalpaper</literal> +</term><listitem><para>8.5 by 14 inches +</para> +</listitem></varlistentry><varlistentry><term><literal>letterpaper</literal> +</term><listitem><para>8.5 by 11 inches (the default) +</para></listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>\pdfpagewidth</primary></indexterm> +<indexterm role="fn"><primary>\pdfpageheight</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’s preamble. The +<literal>geometry</literal> package provides flexible ways of setting the print +area and physical page size. </para> -<screen>a4paper a5paper b5paper executivepaper legalpaper letterpaper -</screen> <indexterm role="fn"><primary>draft option</primary></indexterm> <indexterm role="fn"><primary>final option</primary></indexterm> <indexterm role="fn"><primary>fleqn option</primary></indexterm> @@ -603,16 +692,17 @@ and a style. The &latex; commands for doing this are described here. <title>Font styles</title> <indexterm role="cp"><primary>font styles</primary></indexterm> -<indexterm role="cp"><primary>typeface styles</primary></indexterm> +<indexterm role="cp"><primary>type styles</primary></indexterm> <indexterm role="cp"><primary>styles of text</primary></indexterm> <para>The following type style commands are supported by &latex;. </para> <para>This first group of commands is typically used with an argument, as in -<literal>\textit{italic text}</literal>. In the table below, the corresponding +<literal>\textit{<replaceable>text</replaceable>}</literal>. In the table below, the corresponding command in parenthesis is the “declaration form”, which takes no -arguments. The scope of the declaration form lasts until the next type -style command or the end of the current group. +arguments, as in <literal>{\itshape <replaceable>text</replaceable>}</literal>. The scope of the +declaration form lasts until the next type style command or the end of +the current group. </para> <para>These commands, in both the argument form and the declaration form, are cumulative; e.g., you can say either <literal>\sffamily\bfseries</literal> or @@ -642,11 +732,6 @@ command argument, such as <literal>\textit{\nocorr text}</literal> or <indexterm role="fn"><primary>\itshape</primary></indexterm> <para>Italics. </para> -</listitem></varlistentry><varlistentry><term><literal>\emph</literal> -</term><listitem><indexterm role="fn"><primary>\emph</primary></indexterm> -<indexterm role="cp"><primary>emphasis</primary></indexterm> -<para>Emphasis (switches between <literal>\textit</literal> and <literal>\textrm</literal>). -</para> </listitem></varlistentry><varlistentry><term><literal>\textmd (\mdseries)</literal> </term><listitem><indexterm role="fn"><primary>\textmd</primary></indexterm> <indexterm role="fn"><primary>\mdseries</primary></indexterm> @@ -660,7 +745,7 @@ command argument, such as <literal>\textit{\nocorr text}</literal> or </listitem></varlistentry><varlistentry><term><literal>\textup (\upshape)</literal> </term><listitem><indexterm role="fn"><primary>\textup</primary></indexterm> <indexterm role="fn"><primary>\upshape</primary></indexterm> -<para>Upright (default). The opposite of slanted. +<para>Upright (default). </para> </listitem></varlistentry><varlistentry><term><literal>\textsl (\slshape)</literal> </term><listitem><indexterm role="fn"><primary>\textsl</primary></indexterm> @@ -687,76 +772,31 @@ command argument, such as <literal>\textit{\nocorr text}</literal> or <indexterm role="fn"><primary>\normalfont</primary></indexterm> <para>Main document font. </para> -</listitem></varlistentry><varlistentry><term><literal>\mathrm</literal> -</term><listitem><indexterm role="fn"><primary>\mathrm</primary></indexterm> -<para>Roman, for use in math mode. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathbf</literal> -</term><listitem><indexterm role="fn"><primary>\mathbf</primary></indexterm> -<para>Boldface, for use in math mode. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathsf</literal> -</term><listitem><indexterm role="fn"><primary>\mathsf</primary></indexterm> -<para>Sans serif, for use in math mode. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathtt</literal> -</term><listitem><indexterm role="fn"><primary>\mathtt</primary></indexterm> -<para>Typewriter, for use in math mode. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathit</literal> -</term><term><literal>(\mit)</literal> -</term><listitem><para>Italics, for use in math mode. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathnormal</literal> -</term><listitem><indexterm role="fn"><primary>\mathnormal</primary></indexterm> -<para>For use in math mode, e.g. inside another type style declaration. -</para> -</listitem></varlistentry><varlistentry><term><literal>\mathcal</literal> -</term><listitem><indexterm role="fn"><primary>\mathcal</primary></indexterm> -<para>‘Calligraphic’ letters, for use in math mode. -</para> </listitem></varlistentry></variablelist> -<indexterm role="fn"><primary>\mathversion</primary></indexterm> -<indexterm role="cp"><primary>math, bold</primary></indexterm> -<indexterm role="cp"><primary>bold math</primary></indexterm> -<para>In addition, the command <literal>\mathversion{bold}</literal> can be used for -switching to bold letters and symbols in -formulas. <literal>\mathversion{normal}</literal> restores the default. -</para> -<indexterm role="fn"><primary>\oldstylenums</primary></indexterm> -<indexterm role="cp"><primary>numerals, old-style</primary></indexterm> -<indexterm role="cp"><primary>old-style numerals</primary></indexterm> -<indexterm role="cp"><primary>lining numerals</primary></indexterm> -<indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm> -<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will -typeset so-called “old-style” numerals, which have differing heights -and depths (and sometimes widths) from the standard “lining” -numerals. &latex;’s default fonts support this, and will respect -<literal>\textbf</literal> (but not other styles; there are no italic old-style -numerals in Computer Modern). Many other fonts have old-style -numerals also; sometimes the <literal>textcomp</literal> package must be loaded, -and sometimes package options are provided to make them the default. -FAQ entry: <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf</ulink>. +<indexterm role="cp"><primary>emphasis</primary></indexterm> +<indexterm role="fn"><primary>\emph</primary></indexterm> +<para>Although it also changes fonts, the <literal>\emph{<replaceable>text</replaceable>}</literal> command +is semantic, for text to be emphasized, and should not be used as a +substitute for <literal>\textit</literal>. For example, <literal>\emph{<replaceable>start +text</replaceable> \emph{<replaceable>middle text</replaceable>} <replaceable>end text</replaceable>}</literal> will result in the +<replaceable>start text</replaceable> and <replaceable>end text</replaceable> in italics, but <replaceable>middle text</replaceable> +will be in roman. </para> <para>&latex; also provides the following commands, which unconditionally switch to the given style, that is, are <emphasis>not</emphasis> cumulative. Also, -they are used differently than the above commands: <literal>{\<replaceable>cmd</replaceable> -...}</literal> instead of <literal>\<replaceable>cmd</replaceable>{...}</literal>. These are two unrelated -constructs. +they are used differently than the above commands: +<literal>{\<replaceable>cmd</replaceable>...}</literal> instead of <literal>\<replaceable>cmd</replaceable>{...}</literal>. These +are two unrelated constructs. </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\bf</primary></indexterm><literal>\bf</literal> </term><listitem><indexterm role="cp"><primary>bold font</primary></indexterm> -<para>Switch to <emphasis role="bold">bold face</emphasis>. +<para>Switch to bold face. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cal</primary></indexterm><literal>\cal</literal> </term><listitem><indexterm role="cp"><primary>script letters for math</primary></indexterm> <indexterm role="cp"><primary>calligraphic letters for math</primary></indexterm> <para>Switch to calligraphic letters for math. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\em</primary></indexterm><literal>\em</literal> -</term><listitem><indexterm role="cp"><primary>emphasis</primary></indexterm> -<para>Emphasis (italics within roman, roman within italics). -</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\it</primary></indexterm><literal>\it</literal> </term><listitem><indexterm role="cp"><primary>italic font</primary></indexterm> <para>Italics. @@ -785,18 +825,78 @@ constructs. <para>Typewriter (monospace, fixed-width). </para> </listitem></varlistentry></variablelist> -<para>Some people consider the unconditional font-switching commands, such -as <literal>\tt</literal>, obsolete and <emphasis>only</emphasis> the cumulative commands -(<literal>\texttt</literal>) should be used. I (Karl) do not agree. There are -perfectly reasonable situations when an unconditional font switch is -precisely what you need to get the desired output; for one example, -see <link linkend="description"><literal>description</literal></link>. Both sets of commands have -their place. +<para>The <literal>\em</literal> command is the unconditional version of <literal>\emph</literal>. +</para> +<para>(Some people consider the unconditional font-switching commands, such +as <literal>\tt</literal>, obsolete and that only the cumulative commands +(<literal>\texttt</literal>) should be used. Others think that both sets of +commands have their place and sometimes an unconditional font switch +is precisely what you want; for one example, +see <link linkend="description"><literal>description</literal></link>.) +</para> +<para>The following commands are for use in math mode. They are not +cumulative, so <literal>\mathbf{\mathit{<replaceable>symbol</replaceable>}}</literal> does not +create a boldface and italic <replaceable>symbol</replaceable>; instead, it will just be in +italics. This is because typically math symbols need consistent +typographic treatment, regardless of the surrounding environment. +</para> +<variablelist><varlistentry><term><literal>\mathrm</literal> +</term><listitem><indexterm role="fn"><primary>\mathrm</primary></indexterm> +<para>Roman, for use in math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathbf</literal> +</term><listitem><indexterm role="fn"><primary>\mathbf</primary></indexterm> +<para>Boldface, for use in math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathsf</literal> +</term><listitem><indexterm role="fn"><primary>\mathsf</primary></indexterm> +<para>Sans serif, for use in math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathtt</literal> +</term><listitem><indexterm role="fn"><primary>\mathtt</primary></indexterm> +<para>Typewriter, for use in math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathit</literal> +</term><term><literal>(\mit)</literal> +</term><listitem><para>Italics, for use in math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathnormal</literal> +</term><listitem><indexterm role="fn"><primary>\mathnormal</primary></indexterm> +<para>For use in math mode, e.g., inside another type style declaration. +</para> +</listitem></varlistentry><varlistentry><term><literal>\mathcal</literal> +</term><listitem><indexterm role="fn"><primary>\mathcal</primary></indexterm> +<para>Calligraphic letters, for use in math mode. +</para> +</listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>\mathversion</primary></indexterm> +<indexterm role="cp"><primary>math, bold</primary></indexterm> +<indexterm role="cp"><primary>bold math</primary></indexterm> +<para>In addition, the command <literal>\mathversion{bold}</literal> can be used for +switching to bold letters and symbols in +formulas. <literal>\mathversion{normal}</literal> restores the default. +</para> +<indexterm role="fn"><primary>\oldstylenums</primary></indexterm> +<indexterm role="cp"><primary>numerals, old-style</primary></indexterm> +<indexterm role="cp"><primary>old-style numerals</primary></indexterm> +<indexterm role="cp"><primary>lining numerals</primary></indexterm> +<indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm> +<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset +so-called “old-style” numerals, which have differing heights and +depths (and sometimes widths) from the standard “lining” numerals, +which all have the same height as upper-case letters. &latex;’s +default fonts support this, and will respect <literal>\textbf</literal> (but not +other styles; there are no italic old-style numerals in Computer +Modern). Many other fonts have old-style numerals also; sometimes the +<literal>textcomp</literal> package must be loaded, and sometimes package options +are provided to make them the default. FAQ entry: +<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf</ulink>. </para> </sect1> <sect1 label="4.2" id="Font-sizes"> <title>Font sizes</title> + <indexterm role="cp"><primary>font sizes</primary></indexterm> <indexterm role="cp"><primary>typeface sizes</primary></indexterm> <indexterm role="cp"><primary>sizes of text</primary></indexterm> @@ -849,160 +949,316 @@ these commands; for instance, <literal>\begin{tiny}...\end{tiny}</literal>. </sect1> <sect1 label="4.3" id="Low_002dlevel-font-commands"> <title>Low-level font commands</title> + <indexterm role="cp"><primary>low-level font commands</primary></indexterm> <indexterm role="cp"><primary>font commands, low-level</primary></indexterm> <para>These commands are primarily intended for writers of macros and packages. The commands listed here are only a subset of the available ones. +<!-- xx but it should be complete --> +<!-- xx something about ultimately reading ENCFAM.fd? --> </para> -<variablelist><varlistentry><term><literal>\fontencoding{enc}</literal> +<variablelist><varlistentry><term><literal>\fontencoding{<replaceable>encoding</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontencoding</primary></indexterm> -<para>Select font encoding. Valid encodings include <literal>OT1</literal> and <literal>T1</literal>. -</para> -</listitem></varlistentry><varlistentry><term><literal>\fontfamily{family}</literal> +<para>Select the font encoding, the encoding of the output font. There are a +large number of valid encodings. The most common are <literal>OT1</literal>, +Knuth’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. +</para> +</listitem></varlistentry><varlistentry><term><literal>\fontfamily{<replaceable>family</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontfamily</primary></indexterm> -<para>Select font family. Valid families include: -</para> -<itemizedlist><listitem><para><literal>cmr</literal> for Computer Modern Roman -</para></listitem><listitem><para><literal>cmss</literal> for Computer Modern Sans Serif -</para></listitem><listitem><para><literal>cmtt</literal> for Computer Modern Typewriter +<indexterm role="cp"><primary>families, of fonts</primary></indexterm> +<indexterm role="cp"><primary>font catalogue</primary></indexterm> +<para>Select the font family. The web page +<ulink url="http://www.tug.dk/FontCatalogue/">http://www.tug.dk/FontCatalogue/</ulink> provides one way to browse +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> </literal> Avant Garde +</para></listitem><listitem><para><!-- /@w --> <literal>fvs</literal><literal> </literal> Bitstream Vera Sans +</para></listitem><listitem><para><!-- /@w --> <literal>pbk</literal><literal> </literal> Bookman +</para></listitem><listitem><para><!-- /@w --> <literal>bch</literal><literal> </literal> Charter +</para></listitem><listitem><para><!-- /@w --> <literal>ccr</literal><literal> </literal> Computer Concrete +</para></listitem><listitem><para><!-- /@w --> <literal>cmr</literal><literal> </literal> Computer Modern +</para></listitem><listitem><para><!-- /@w --> <literal>pcr</literal><literal> </literal> Courier +</para></listitem><listitem><para><!-- /@w --> <literal>phv</literal><literal> </literal> Helvetica +</para></listitem><listitem><para><!-- /@w --> <literal>fi4</literal><literal> </literal> Inconsolata +</para></listitem><listitem><para><!-- /@w --> <literal>lmr</literal><literal> </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> </literal> New Century Schoolbook +</para></listitem><listitem><para><!-- /@w --> <literal>ppl</literal><literal> </literal> Palatino +</para></listitem><listitem><para><!-- /@w --> <literal>ptm</literal><literal> </literal> Times +</para></listitem><listitem><para><!-- /@w --> <literal>uncl</literal> Uncial +</para></listitem><listitem><para><!-- /@w --> <literal>put</literal><literal> </literal> Utopia +</para></listitem><listitem><para><!-- /@w --> <literal>pzc</literal><literal> </literal> Zapf Chancery </para></listitem></itemizedlist> -<para>and numerous others. -</para> -</listitem></varlistentry><varlistentry><term><literal>\fontseries{series}</literal> +</listitem></varlistentry><varlistentry><term><literal>\fontseries{<replaceable>series</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontseries</primary></indexterm> -<para>Select font series. Valid series include: -</para> -<itemizedlist><listitem><para><literal>m</literal> Medium (normal) -</para></listitem><listitem><para><literal>b</literal> Bold -</para></listitem><listitem><para><literal>c</literal> Condensed -</para></listitem><listitem><para><literal>bc</literal> Bold condensed -</para></listitem><listitem><para><literal>bx</literal> Bold extended +<indexterm role="cp"><primary>series, of fonts</primary></indexterm> +<para>Select the font series. A <firstterm>series</firstterm> combines a <firstterm>weight</firstterm> and a +<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> </literal> Medium (normal) +</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal> </literal> Bold +</para></listitem><listitem><para><!-- /@w --> <literal>c</literal><literal> </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> -<para>and various other combinations. -</para> -</listitem></varlistentry><varlistentry><term><literal>\fontshape{shape}</literal> +<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> </literal> Light +</para></listitem><listitem><para><!-- /@w --> <literal>sl</literal> Semi light +</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal> </literal> Medium (normal) +</para></listitem><listitem><para><!-- /@w --> <literal>sb</literal> Semi bold +</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal> </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> +<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> </literal> Condensed, 75% +</para></listitem><listitem><para><!-- /@w --> <literal>sc</literal> Semi condensed, 87.5% +</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal> </literal> Medium, 100% +</para></listitem><listitem><para><!-- /@w --> <literal>sx</literal> Semi expanded, 112.5% +</para></listitem><listitem><para><!-- /@w --> <literal>x</literal><literal> </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>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 +(‘<literal><literal>m</literal></literal>’). +</para> +</listitem></varlistentry><varlistentry><term><literal>\fontshape{<replaceable>shape</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontshape</primary></indexterm> +<indexterm role="cp"><primary>shapes, of fonts</primary></indexterm> <para>Select font shape. Valid shapes are: </para> -<itemizedlist><listitem><para><literal>n</literal> Upright (normal) -</para></listitem><listitem><para><literal>it</literal> Italic -</para></listitem><listitem><para><literal>sl</literal> Slanted (oblique) -</para></listitem><listitem><para><literal>sc</literal> Small caps -</para></listitem><listitem><para><literal>ui</literal> Upright italics -</para></listitem><listitem><para><literal>ol</literal> Outline +<itemizedlist><listitem><para><!-- /@w --> <literal>n</literal><literal> </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> -<para>The two last shapes are not available for most font families. +<para>The two last shapes are not available for most font families, and +small caps are often missing as well. </para> -</listitem></varlistentry><varlistentry><term><literal>\fontsize{size}{skip}</literal> +</listitem></varlistentry><varlistentry><term><literal>\fontsize{<replaceable>size</replaceable>}{<replaceable>skip</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontsize</primary></indexterm> +<indexterm role="cp"><primary>font size</primary></indexterm> <indexterm role="fn"><primary>\baselineskip</primary></indexterm> -<para>Set font size. The first parameter is the font size to switch to and -the second is the line spacing to use; this is stored in a parameter -named <literal>\baselineskip</literal>. The unit of both parameters defaults to -pt. The default <literal>\baselineskip</literal> for the Computer Modern typeface -is 1.2 times the <literal>\fontsize</literal>. +<para>Set the font size and the line spacing. The unit of both parameters +defaults to points (<literal>pt</literal>). The line spacing is the nominal +vertical space between lines, baseline to baseline. It is stored in the +parameter <literal>\baselineskip</literal>. The default <literal>\baselineskip</literal> for +the Computer Modern typeface is 1.2 times the <literal>\fontsize</literal>. +Changing <literal>\baselineskip</literal> directly is inadvisable since its value is +reset every time a size change happens; see <literal>\baselinestretch</literal>, next. +</para> +</listitem></varlistentry><varlistentry><term><literal>\baselinestretch</literal> +</term><listitem><indexterm role="fn"><primary>\baselinestretch</primary></indexterm> +<para>&latex; multiplies the line spacing by the value of the +<literal>\baselinestretch</literal> parameter; the default factor is 1. A change +takes effect when <literal>\selectfont</literal> (see below) is called. You can +make line skip changes happen for the entire document by doing +<literal>\renewcommand{\baselinestretch}{2.0}</literal> in the preamble. </para> -<indexterm role="fn"><primary>\baselinestretch</primary></indexterm> <indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm> <indexterm role="cp"><primary>double spacing</primary></indexterm> -<para>The line spacing is also multiplied by the value of the -<literal>\baselinestretch</literal> parameter when the type size changes; the -default is 1. However, the best way to “double space” a document, -if you should be unlucky enough to have to produce such, is to use the -<literal>setspace</literal> package; see -<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=linespace">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=linespace</ulink>. -</para> -<indexterm role="fn"><primary>\linespread</primary></indexterm> +<para>However, the best way to double-space a document is to use the +<filename>setspace</filename> package. In addition to offering a number of spacing +options, this package keeps the line spacing single-spaced in places +where that is typically desirable, such as footnotes and figure +captions. See the package documentation. +</para> </listitem></varlistentry><varlistentry><term><literal>\linespread{<replaceable>factor</replaceable>}</literal> -</term><listitem><para>Equivalent to +</term><listitem><indexterm role="fn"><primary>\linespread</primary></indexterm> +<para>Equivalent to <literal>\renewcommand{\baselinestretch}{<replaceable>factor</replaceable>}</literal>, and therefore must be followed by <literal>\selectfont</literal> to have any effect. Best specified in the preamble, or use the <literal>setspace</literal> package, as -described just above. +just described. </para> -<indexterm role="fn"><primary>\selectfont</primary></indexterm> -<para>The changes made by calling the font commands described above do -not come into effect until <literal>\selectfont</literal> is called. +</listitem></varlistentry><varlistentry><term><literal>\selectfont</literal> +</term><listitem><indexterm role="fn"><primary>\selectfont</primary></indexterm> +<para>The effects of the font commands described above do not happen until +<literal>\selectfont</literal> is called, as in +<literal>\fontfamily{<replaceable>familyname</replaceable>}\selectfont</literal>. It is often useful +to put this in a macro: + +<literal>\newcommand*{\myfont}{\fontfamily{<replaceable>familyname</replaceable>}\selectfont}</literal> + +(see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>). </para> -</listitem></varlistentry><varlistentry><term><literal>\usefont{enc}{family}{series}{shape}</literal> +</listitem></varlistentry><varlistentry><term><literal>\usefont{<replaceable>enc</replaceable>}{<replaceable>family</replaceable>}{<replaceable>series</replaceable>}{<replaceable>shape</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\usefont</primary></indexterm> <para>The same as invoking <literal>\fontencoding</literal>, <literal>\fontfamily</literal>, <literal>\fontseries</literal> and <literal>\fontshape</literal> with the given parameters, -followed by <literal>\selectfont</literal>. +followed by <literal>\selectfont</literal>. For example: </para> +<screen>\usefont{ot1}{cmr}{m}{n} +</screen> </listitem></varlistentry></variablelist> </sect1> </chapter> <chapter label="5" id="Layout"> <title>Layout</title> + <indexterm role="cp"><primary>layout commands</primary></indexterm> -<para>Miscellaneous commands for controlling the general layout of the page. +<para>Commands for controlling the general page layout. </para> <sect1 label="5.1" id="_005conecolumn"> <title><literal>\onecolumn</literal></title> + <indexterm role="fn"><primary>\onecolumn</primary></indexterm> <indexterm role="cp"><primary>one-column output</primary></indexterm> <para>The <literal>\onecolumn</literal> declaration starts a new page and produces -single-column output. This is the default. +single-column output. If the document is given the class option +<literal>onecolumn</literal> then this is the default behavior (see <link linkend="Document-class-options">Document +class options</link>). +</para> +<para>This command is fragile (see <link linkend="_005cprotect">\protect</link>). </para> </sect1> <sect1 label="5.2" id="_005ctwocolumn"> <title><literal>\twocolumn</literal></title> + <indexterm role="fn"><primary>\twocolumn</primary></indexterm> <indexterm role="cp"><primary>multicolumn text</primary></indexterm> <indexterm role="cp"><primary>two-column output</primary></indexterm> <para>Synopsis: </para> -<screen>\twocolumn[<replaceable>text1col</replaceable>] +<screen>\twocolumn[<replaceable>prelim one column text</replaceable>] </screen> <para>The <literal>\twocolumn</literal> declaration starts a new page and produces -two-column output. If the optional <replaceable>text1col</replaceable> argument is present, -it is typeset in one-column mode before the two-column typesetting -starts. +two-column output. If the document is given the class option +<literal>twocolumn</literal> then this is the default (see <link linkend="Document-class-options">Document class +options</link>). +</para> +<para>If the optional <replaceable>prelim one column text</replaceable> argument +is present, it is typeset in one-column mode before the two-column +typesetting starts. +</para> +<para>This command is fragile (see <link linkend="_005cprotect">\protect</link>). </para> <para>These parameters control typesetting in two-column output: </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\columnsep</primary></indexterm><literal>\columnsep</literal> -</term><listitem><para>The distance between columns (35pt by default). +</term><listitem><para>The distance between columns. The default is 35pt. Change it with a +command such as <literal>\setlength{\columnsep}{40pt}</literal> You must change +it before the two column environment starts; in the preamble is a good +place. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\columnseprule</primary></indexterm><literal>\columnseprule</literal> -</term><listitem><para>The width of the rule between columns; the default is 0pt, so there is no rule. +</term><listitem><para>The width of the rule between columns. The rule appears halfway between +the two columns. The default is 0pt, meaning that there is no rule. +Change it with a command such as +<literal>\setlength{\columnseprule}{0.4pt}</literal>, before the two-column +environment starts. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\columnwidth</primary></indexterm><literal>\columnwidth</literal> -</term><listitem><para>The width of the current column; this is equal to <literal>\textwidth</literal> in -single-column text. +</term><listitem><para>The width of a single column. In one-column mode this is equal to +<literal>\textwidth</literal>. In two-column mode by default &latex; sets the +width of each of the two columns to be half of <literal>\textwidth</literal> minus +<literal>\columnsep</literal>. </para> </listitem></varlistentry></variablelist> -<para>These parameters control float behavior in two-column output: +<para>In a two-column document, the starred environments <literal>table*</literal> and +<literal>figure*</literal> are two columns wide, whereas the unstarred environments +<literal>table</literal> and <literal>figure</literal> take up only one column (see <link linkend="figure">figure</link> +and see <link linkend="table">table</link>). &latex; places starred floats at the top of a page. +The following parameters control float behavior of two-column output. </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\dbltopfraction</primary></indexterm><literal>\dbltopfraction</literal> -</term><listitem><para>Maximum fraction at the top of a two-column page that may be occupied -by floats. Default ‘<literal>.7</literal>’, can be usefully redefined to (say) -‘<literal>.9</literal>’ to avoid going to float pages so soon. +</term><listitem><para>The maximum fraction at the top of a two-column page that may be +occupied by two-column wide floats. The default is 0.7, meaning that +the height of a <literal>table*</literal> or <literal>figure*</literal> environment must not +exceed <literal>0.7\textheight</literal> . If the height of your starred float +environment exceeeds this then you can take one of the following actions +to prevent it from floating all the way to the back of the document: +</para> +<itemizedlist><listitem><para>Use the <literal>[tp]</literal> location specifier to tell LaTeX to try to put +the bulky float on a page by itself, as well as at the top of a page. +</para> +</listitem><listitem><para>Use the <literal>[t!]</literal> location specifier to override the effect of +<literal>\dbltopfraction</literal> for this particular float. +</para> +</listitem><listitem><para>Increase the value of <literal>\dbltopfraction</literal> to a suitably large number, +to avoid going to float pages so soon. +</para></listitem></itemizedlist> +<para>You can redefine it, for instance with +<literal>\renewcommand{\dbltopfraction}{0.9}</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatpagefraction</primary></indexterm><literal>\dblfloatpagefraction</literal> -</term><listitem><para>The minimum fraction of a float page that must be occupied by floats, -for a two-column float page. Default ‘<literal>.5</literal>’. +</term><listitem><para>For a float page of two-column wide floats, this is the minimum fraction +that must be occupied by floats, limiting the amount of blank space. +&latex;’s default is <literal>0.5</literal>. Change it with <literal>\renewcommand</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatsep</primary></indexterm><literal>\dblfloatsep</literal> -</term><listitem><para>Distance between floats at the top or bottom of a two-column float -page. Default ‘<literal>12pt plus2pt minus2pt</literal>’ for ‘<literal>10pt</literal>’ and -‘<literal>11pt</literal>’ documents, ‘<literal>14pt plus2pt minus4pt</literal>’ for ‘<literal>12pt</literal>’. +</term><listitem><para>On a float page of two-column wide floats, this length is the distance +between floats, at both the top and bottom of the page. The default is +<literal>12pt plus2pt minus2pt</literal> for a document set at <literal>10pt</literal> or +<literal>11pt</literal>, and <literal>14pt plus2pt minus4pt</literal> for a document set at +<literal>12pt</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltextfloatsep</primary></indexterm><literal>\dbltextfloatsep</literal> -</term><listitem><para>Distance between a multi-column float at the top or bottom of a page -and the main text. Default ‘<literal>20pt plus2pt minus4pt</literal>’. +</term><listitem><para>This length is the distance between a multi-column float at the top or +bottom of a page and the main text. The default is <literal>20pt plus2pt +minus4pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltopnumber</primary></indexterm><literal>\dbltopnumber</literal> +</term><listitem><para>On a float page of two-column wide floats, this counter gives the +maximum number of floats allowed at the top of the page. The &latex; +default is <literal>2</literal>. </para> </listitem></varlistentry></variablelist> +<!-- From egreg at http://tex.stackexchange.com/a/142232/339 --> +<para>This example shows the use of the optional argument of <literal>\twocolumn</literal> +to create a title that spans the two-column article: +</para> +<screen>\documentclass[twocolumn]{article} +\newcommand{\authormark}[1]{\textsuperscript{#1}} +\begin{document} +\twocolumn[{% inside this optional argument goes one-column text + \centering + \LARGE The Title \\[1.5em] + \large Author One\authormark{1}, + Author Two\authormark{2}, + Author Three\authormark{1} \\[1em] + \normalsize + \begin{tabular}{p{.2\textwidth}@{\hspace{2em}}p{.2\textwidth}} + \authormark{1}Department one &\authormark{2}Department two \\ + School one &School two + \end{tabular}\\[3em] % space below title part +}] + +Two column text here. +</screen> </sect1> <sect1 label="5.3" id="_005cflushbottom"> @@ -1010,23 +1266,39 @@ and the main text. Default ‘<literal>20pt plus2pt minus4pt</literal>̵ <indexterm role="fn"><primary>\flushbottom</primary></indexterm> -<para>The <literal>\flushbottom</literal> declaration makes all text pages the same -height, adding extra vertical space where necessary to fill out the -page. +<para>The <literal>\flushbottom</literal> command can go at any point in the document +body. It makes all later pages the same height, stretching the vertical +space where necessary to fill out the page. +</para> +<para>If &tex; cannot satisfactorily stretch the vertical space in a page +then you get a message like ‘<literal>Underfull \vbox (badness 10000) has +occurred while \output is active</literal>’. You can change to +<literal>\raggedbottom</literal> (see below). Alternatively, you can try to adjust +the <literal>textheight</literal> to be compatible, or you can add some vertical +stretch glue between lines or between paragraphs, as in +<literal>\setlength{\parskip}{0ex plus0.1ex}</literal>. In a final editing +stage you can adjust the height of individual pages +(see <link linkend="_005cenlargethispage">\enlargethispage</link>). </para> -<para>This is the default if <literal>twocolumn</literal> mode is selected -(see <link linkend="Document-class-options">Document class options</link>). +<para>This is the default only if you select the <literal>twoside</literal> document class +option (see <link linkend="Document-class-options">Document class options</link>). </para> </sect1> <sect1 label="5.4" id="_005craggedbottom"> <title><literal>\raggedbottom</literal></title> + <indexterm role="fn"><primary>\raggedbottom</primary></indexterm> <indexterm role="cp"><primary>stretch, omitting vertical</primary></indexterm> -<para>The <literal>\raggedbottom</literal> declaration makes all pages the natural -height of the material on that page. No rubber lengths will be -stretched. +<para>The <literal>\raggedbottom</literal> command can go at any point in the document +body. It makes all later pages the natural height of the material on +that page; no rubber lengths will be stretched. Thus, in a two-sided +document the facing pages may be different heights. See also +<literal>\flushbottom</literal> above. +</para> +<para>This is the default unless you select the <literal>twoside</literal> document class +option (see <link linkend="Document-class-options">Document class options</link>). </para> </sect1> @@ -1040,45 +1312,125 @@ stretched. <indexterm role="cp"><primary>footer, parameters for</primary></indexterm> <indexterm role="cp"><primary>running header and footer</primary></indexterm> -<variablelist><varlistentry><term><indexterm role="fn"><primary>\headheight</primary></indexterm><literal>\headheight</literal> -</term><listitem><para>Height of the box that contains the running head. Default is -‘<literal>30pt</literal>’, except in the <literal>book</literal> class, where it varies with the -type size. +<variablelist><varlistentry><term><indexterm role="fn"><primary>\columnsep</primary></indexterm><literal>\columnsep</literal> +</term><term><indexterm role="fn"><primary>\columnseprule</primary></indexterm><literal>\columnseprule</literal> +</term><term><indexterm role="fn"><primary>\columnwidth</primary></indexterm><literal>\columnwidth</literal> +</term><listitem><indexterm role="fn"><primary>\columnsep</primary></indexterm> +<indexterm role="fn"><primary>\columnseprule</primary></indexterm> +<indexterm role="fn"><primary>\columnwidth</primary></indexterm> +<para>The distance between the two columns, the width of a rule between the +columns, and the width of the columns, when the document class option +<literal>twocolumn</literal> is in effect (see <link linkend="Document-class-options">Document class options</link>). +See <link linkend="_005ctwocolumn">\twocolumn</link>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\headheight</primary></indexterm><literal>\headheight</literal> +</term><listitem><indexterm role="fn"><primary>\headheight</primary></indexterm> +<para>Height of the box that contains the running head. The default in the +<literal>article</literal>, <literal>report</literal>, and <literal>book</literal> classes is ‘<literal>12pt</literal>’, +at all type sizes. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\headsep</primary></indexterm><literal>\headsep</literal> -</term><listitem><para>Vertical distance between the bottom of the header line and the top of -the main text. Default is ‘<literal>25pt</literal>’, except in the <literal>book</literal> -class, where it varies with the type size. +</term><listitem><indexterm role="fn"><primary>\headsep</primary></indexterm> +<para>Vertical distance between the bottom of the header line and the top of +the main text. The default in the <literal>article</literal> and <literal>report</literal> +classes is ‘<literal>25pt</literal>’. In the <literal>book</literal> class the default is: if the +document is set at 10pt then it is ‘<literal>0.25in</literal>’, and at 11pt and 12pt +it is ‘<literal>0.275in</literal>’. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\footskip</primary></indexterm><literal>\footskip</literal> -</term><listitem><para>Distance from the baseline of the last line of text to the baseline of -the page footer. Default is ‘<literal>30pt</literal>’, except in the <literal>book</literal> -class, where it varies with the type size. +</term><listitem><indexterm role="fn"><primary>\footskip</primary></indexterm> +<para>Distance from the baseline of the last line of text to the baseline of +the page footer. The default in the <literal>article</literal> and <literal>report</literal> +classes is ‘<literal>30pt</literal>’. In the <literal>book</literal> class the default is: when +the type size is 10pt the default is ‘<literal>0.35in</literal>’, while at 11pt it is +‘<literal>0.38in</literal>’, and at 12pt it is ‘<literal>30pt</literal>’. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\linewidth</primary></indexterm><literal>\linewidth</literal> -</term><listitem><para>Width of the current line, decreased for each nested <literal>list</literal> -(see <link linkend="list">list</link>). Specifically, it is smaller than <literal>\textwidth</literal> by -the sum of <literal>\leftmargin</literal> and <literal>\rightmargin</literal> -(see <link linkend="itemize">itemize</link>). The default varies with the font size, paper -width, two-column mode, etc. For an <literal>article</literal> document in -‘<literal>10pt</literal>’, it’s set to ‘<literal>345pt</literal>’; in two-column mode, that -becomes ‘<literal>229.5pt</literal>’. +</term><listitem><indexterm role="fn"><primary>\linewidth</primary></indexterm> +<para>Width of the current line, decreased for each nested <literal>list</literal> +(see <link linkend="list">list</link>). That is, the nominal value for <literal>\linewidth</literal> is to +equal <literal>\textwidth</literal> but for each nested list the <literal>\linewidth</literal> +is decreased by the sum of that list’s <literal>\leftmargin</literal> and +<literal>\rightmargin</literal> (see <link linkend="itemize">itemize</link>). +<!-- The default varies with the font size, paper width, two-column mode, --> +<!-- etc. For an @code{article} document set in 10pt, the default is --> +<!-- @samp{345pt}, while in two-column mode that becomes @samp{229.5pt}. --> +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\marginparpush</primary></indexterm><literal>\marginparpush</literal> +</term><term><indexterm role="fn"><primary>\marginsep</primary></indexterm><literal>\marginsep</literal> +</term><term><indexterm role="fn"><primary>\marginparwidth</primary></indexterm><literal>\marginparwidth</literal> +</term><listitem><indexterm role="fn"><primary>\marginparpush</primary></indexterm> +<indexterm role="fn"><primary>\marginsep</primary></indexterm> +<indexterm role="fn"><primary>\marginparwidth</primary></indexterm> +<para>The minimum vertical space between two marginal notes, the horizontal +space between the text body and the marginal notes, and the horizontal +width of the notes. +</para> +<para>Normally marginal notes appear on the outside of the page, but the +declaration <literal>\reversemarginpar</literal> changes that (and +<literal>\normalmarginpar</literal> changes it back). +</para> +<para>The defaults for <literal>\marginparpush</literal> in both <literal>book</literal> and +<literal>article</literal> classes are: ‘<literal>7pt</literal>’ if the document is set at 12pt, +and ‘<literal>5pt</literal>’ if the document is set at 11pt or 10pt. +</para> +<para>For <literal>\marginsep</literal>, in <literal>article</literal> class the default is +‘<literal>10pt</literal>’ except if the document is set at 10pt and in two-column mode +where the default is ‘<literal>11pt</literal>’. +</para> +<para>For <literal>\marginsep</literal> in <literal>book</literal> class the default is ‘<literal>10pt</literal>’ in +two-column mode and ‘<literal>7pt</literal>’ in one-column mode. +</para> +<para>For <literal>\marginparwidth</literal> in both <literal>book</literal> and <literal>article</literal> +classes, in two-column mode the default is 60% of <literal>\paperwidth +− \textwidth</literal>, while in one-column mode it is 50% of that +distance. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\oddsidemargin</primary></indexterm><literal>\oddsidemargin</literal> +</term><term><indexterm role="fn"><primary>\evensidemargin</primary></indexterm><literal>\evensidemargin</literal> +</term><listitem><indexterm role="fn"><primary>\oddsidemargin</primary></indexterm> +<indexterm role="fn"><primary>\evensidemargin</primary></indexterm> +<para>The <literal>\oddsidemargin</literal> is the extra distance between the left side of +the page and the text’s left margin, on odd-numbered pages when the +document class option <literal>twoside</literal> is chosen and on all pages when +<literal>oneside</literal> is in effect. When <literal>twoside</literal> is in effect, on +even-numbered pages the extra distance on the left is +<literal>evensidemargin</literal>. +</para> +<para>&latex;’s default is that <literal>\oddsidemargin</literal> is 40% of the +difference between <literal>\paperwidth</literal> and <literal>\textwidth</literal>, and +<literal>\evensidemargin</literal> is the remainder. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\paperheight</primary></indexterm><literal>\paperheight</literal> +</term><listitem><indexterm role="fn"><primary>\paperheight</primary></indexterm> +<para>The height of the paper, as distinct from the height of the print area. +It is normally set with a document class option, as in +<literal>\documentclass[a4paper]{article}</literal> (see <link linkend="Document-class-options">Document class +options</link>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\paperwidth</primary></indexterm><literal>\paperwidth</literal> +</term><listitem><indexterm role="fn"><primary>\paperwidth</primary></indexterm> +<para>The width of the paper, as distinct from the width of the print area. +It is normally set with a document class option, as in +<literal>\documentclass[a4paper]{article}</literal> (see <link linkend="Document-class-options">Document class +options</link>). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textheight</primary></indexterm><literal>\textheight</literal> -</term><listitem><para>The normal vertical height of the page body; the default varies with -the font size, document class, etc. For an <literal>article</literal> or -<literal>report</literal> document in ‘<literal>10pt</literal>’, it’s set to -‘<literal>43\baselineskip</literal>’; for <literal>book</literal>, it’s ‘<literal>41\baselineskip</literal>’. -For ‘<literal>11pt</literal>’, it’s ‘<literal>38\baselineskip</literal>’ and for ‘<literal>12pt</literal>’, -‘<literal>36\baselineskip</literal>’. +</term><listitem><indexterm role="fn"><primary>\textheight</primary></indexterm> +<para>The normal vertical height of the page body. If the document is set at +a nominal type size of 10pt then for an <literal>article</literal> or <literal>report</literal> +the default is ‘<literal>43\baselineskip</literal>’, while for a <literal>book</literal> it is +‘<literal>41\baselineskip</literal>’. At a type size of 11pt the default is +‘<literal>38\baselineskip</literal>’ for all document classes. At 12pt it is +‘<literal>36\baselineskip</literal>’ for all classes. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textwidth</primary></indexterm><literal>\textwidth</literal> -</term><listitem><para>The full horizontal width of the entire page body; the default varies -as usual. For an <literal>article</literal> or <literal>report</literal> document, it’s -‘<literal>345pt</literal>’ at ‘<literal>10pt</literal>’, ‘<literal>360pt</literal>’ at ‘<literal>11pt</literal>’, and -‘<literal>390pt</literal>’ at ‘<literal>12pt</literal>’. For a <literal>book</literal> document, it’s -‘<literal>4.5in</literal>’ at ‘<literal>10pt</literal>’, and ‘<literal>5in</literal>’ at ‘<literal>11pt</literal>’ or -‘<literal>12pt</literal>’. +</term><listitem><indexterm role="fn"><primary>\textwidth</primary></indexterm> +<para>The full horizontal width of the entire page body. For an +<literal>article</literal> or <literal>report</literal> document, the default is ‘<literal>345pt</literal>’ +when the chosen type size is 10pt, the default is ‘<literal>360pt</literal>’ at 11pt, +and it is ‘<literal>390pt</literal>’ at 12pt. For a <literal>book</literal> document, the default +is ‘<literal>4.5in</literal>’ at a type size of 10pt, and ‘<literal>5in</literal>’ at 11pt or 12pt. </para> <para>In multi-column output, <literal>\textwidth</literal> remains the width of the entire page body, while <literal>\columnwidth</literal> is the width of one column @@ -1094,29 +1446,205 @@ specified width, and revert to their normal values at the end of the <literal>minipage</literal> or <literal>\parbox</literal>. </para> <indexterm role="fn"><primary>\hsize</primary></indexterm> -<para>For completeness: <literal>\hsize</literal> is the &tex; primitive parameter used -when text is broken into lines. It should not be used in normal -&latex; documents. +<indexterm role="fn"><primary>\hsize</primary></indexterm> +<para>This entry is included for completeness: <literal>\hsize</literal> is the &tex; +primitive parameter used when text is broken into lines. It should not +be used in normal &latex; documents. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topmargin</primary></indexterm><literal>\topmargin</literal> -</term><listitem><para>Space between the top of the &tex; page (one inch from the top of the -paper, by default) and the top of the header. The default is computed +</term><listitem><indexterm role="fn"><primary>topmargin</primary></indexterm> +<para>Space between the top of the &tex; page (one inch from the top of the +paper, by default) and the top of the header. The value is computed based on many other parameters: <literal>\paperheight − 2in − -\headheight − \headsep − \textheight − \footskip</literal>, and -then divided by two. +\headheight − \headsep − \textheight − \footskip</literal>, +and then divided by two. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topskip</primary></indexterm><literal>\topskip</literal> -</term><listitem><para>Minimum distance between the top of the page body and the baseline of +</term><listitem><indexterm role="fn"><primary>\topskip</primary></indexterm> +<para>Minimum distance between the top of the page body and the baseline of the first line of text. For the standard classes, the default is the -same as the font size, e.g., ‘<literal>10pt</literal>’ at ‘<literal>10pt</literal>’. +same as the font size, e.g., ‘<literal>10pt</literal>’ at a type size of 10pt. </para> </listitem></varlistentry></variablelist> </sect1> +<sect1 label="5.6" id="Floats"> +<title>Floats</title> + +<para>Some typographic elements, such as figures and tables, cannot be broken +across pages. They must be typeset outside of the normal flow of text, +for instance floating to the top of a later page. +</para> +<para>&latex; can have a number of different classes of floating material. +The default is the two classes, <literal>figure</literal> (see <link linkend="figure">figure</link>) and +<literal>table</literal> (see <link linkend="table">table</link>), but you can create a new class with the +package <filename>float</filename>. +</para> +<para>Within any one float class &latex; always respects the order, so that +the first figure in a document source must be typeset before the second +figure. However, &latex; may mix the classes, so it can happen that +while the first table appears in the source before the first figure, it +appears in the output after it. +</para> +<para>The placement of floats is subject to parameters, given below, that +limit the number of floats that can appear at the top of a page, and the +bottom, etc. If so many floats are queued up that the limits prevent +them all from fitting on a page then &latex; places what it can and +defers the rest to the next page. In this way, floats may be typset far +from their place in the source. In particular, a float that is big can +migrate to the end of the document. But then because all floats in a +class must appear in sequential order, every subsequent float in that +class also appears at the end. +</para> +<indexterm role="cp"><primary>placement of floats</primary></indexterm> +<indexterm role="cp"><primary>specifier, float placement</primary></indexterm> +<para>In addition to changing the parameters, for each float you can tweak +where the float placement algorithm tries to place it by using its +<replaceable>placement</replaceable> argument. The possible values are a sequence of the +letters below. The default for both <literal>figure</literal> and <literal>table</literal>, in +both <literal>article</literal> and <literal>book</literal> classes, is <literal>tbp</literal>. +</para> +<variablelist><varlistentry><term><literal>t</literal> +</term><listitem><para>(Top)—at the top of a text page. +</para> +</listitem></varlistentry><varlistentry><term><literal>b</literal> +</term><listitem><para>(Bottom)—at the bottom of a text page. (However, <literal>b</literal> is not +allowed for full-width floats (<literal>figure*</literal>) with double-column +output. To ameliorate this, use the <filename>stfloats</filename> or +<filename>dblfloatfix</filename> package, but see the discussion at caveats in the +FAQ: <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat</ulink>. +</para> +</listitem></varlistentry><varlistentry><term><literal>h</literal> +</term><listitem><para>(Here)—at the position in the text where the <literal>figure</literal> environment +appears. However, <literal>h</literal> is not allowed by itself; <literal>t</literal> is +automatically added. +</para> +<indexterm role="cp"><primary>here, putting floats</primary></indexterm> +<indexterm role="cp"><primary><literal>float</literal> package</primary></indexterm> +<para>To absolutely force a float to appear “here”, you can +<literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it +defines. For further discussion, see the FAQ entry at +<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere</ulink>. +</para> +</listitem></varlistentry><varlistentry><term><literal>p</literal> +</term><listitem><indexterm role="cp"><primary>float page</primary></indexterm> +<para>(Page of floats)—on a separate <firstterm>float page</firstterm>, which is a page +containing no text, only floats. +</para> +</listitem></varlistentry><varlistentry><term><literal>!</literal> +</term><listitem><para>Used in addition to one of the above; for this float only, &latex; +ignores the restrictions on both the number of floats that can appear +and the relative amounts of float and non-float text on the page. +The <literal>!</literal> specifier does <emphasis>not</emphasis> mean “put the float here”; +see above. +</para> +</listitem></varlistentry></variablelist> +<para>Note: the order in which letters appear in the <replaceable>placement</replaceable> argument +does not change the order in which &latex; tries to place the float; +for instance, <literal>btp</literal> has the same effect as <literal>tbp</literal>. All that +<replaceable>placement</replaceable> does is that if a letter is not present then the +algorithm does not try that location. Thus, &latex;’s default of +<literal>tbp</literal> is to try every location except placing the float where it +occurs in the source. +</para> +<para>To prevent &latex; from moving floats to the end of the document or a +chapter you can use a <literal>\clearpage</literal> command to start a new page and +insert all pending floats. If a pagebreak is undesirable then you can +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> +<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> paramater. If this is not desired, and deleting the +<literal>t</literal> is not acceptable as it keeps the float from being placed at +the top of the next page, then you can prevent it by either using the +<filename>flafter</filename> package or using the command +<indexterm role="fn"><primary>\suppressfloats</primary></indexterm> +<literal>\suppressfloats[t]</literal>, which causes floats for the top position on +this page to moved to the next page. +</para> +<para>Parameters relating to fractions of pages occupied by float and +non-float text (change them with +<literal>\renewcommand{<replaceable>parameter</replaceable>}{<replaceable>decimal between 0 and 1</replaceable>}</literal>): +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\bottomfraction</primary></indexterm><literal>\bottomfraction</literal> +</term><listitem><indexterm role="fn"><primary>\bottomfraction</primary></indexterm> +<para>The maximum fraction of the page allowed to be occupied by floats at +the bottom; default ‘<literal>.3</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\floatpagefraction</primary></indexterm><literal>\floatpagefraction</literal> +</term><listitem><indexterm role="fn"><primary>\floatpagefraction</primary></indexterm> +<para>The minimum fraction of a float page that must be occupied by floats; +default ‘<literal>.5</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textfraction</primary></indexterm><literal>\textfraction</literal> +</term><listitem><indexterm role="fn"><primary>\textfraction</primary></indexterm> +<para>Minimum fraction of a page that must be text; if floats take up too +much space to preserve this much text, floats will be moved to a +different page. The default is ‘<literal>.2</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topfraction</primary></indexterm><literal>\topfraction</literal> +</term><listitem><indexterm role="fn"><primary>\topfraction</primary></indexterm> +<para>Maximum fraction at the top of a page that may be occupied before +floats; default ‘<literal>.7</literal>’. +</para></listitem></varlistentry></variablelist> +<para>Parameters relating to vertical space around floats (change them with +<literal>\setlength{<replaceable>parameter</replaceable>}{<replaceable>length expression</replaceable>}</literal>): +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\floatsep</primary></indexterm><literal>\floatsep</literal> +</term><listitem><indexterm role="fn"><primary>\floatsep</primary></indexterm> +<para>Space between floats at the top or bottom of a page; default +‘<literal>12pt plus2pt minus2pt</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\intextsep</primary></indexterm><literal>\intextsep</literal> +</term><listitem><indexterm role="fn"><primary>\intextsep</primary></indexterm> +<para>Space above and below a float in the middle of the main text; default +‘<literal>12pt plus2pt minus2pt</literal>’ for 10 point and 11 point documents, +and ‘<literal>14pt plus4pt minus4pt</literal>’ for 12 point documents. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textfloatsep</primary></indexterm><literal>\textfloatsep</literal> +</term><listitem><indexterm role="fn"><primary>\textfloatsep</primary></indexterm> +<para>Space between the last (first) float at the top (bottom) of a page; +default ‘<literal>20pt plus2pt minus4pt</literal>’. +</para></listitem></varlistentry></variablelist> +<para>Counters relating to the number of floats on a page (change them with +<literal>\setcounter{<replaceable>ctrname</replaceable>}{<replaceable>natural number</replaceable>}</literal>): +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>bottomnumber</primary></indexterm><literal>bottomnumber</literal> +</term><listitem><indexterm role="fn"><primary>bottomnumber</primary></indexterm> +<para>Maximum number of floats that can appear at the bottom of a text page; +default 1. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>dbltopnumber</primary></indexterm><literal>dbltopnumber</literal> +</term><listitem><indexterm role="fn"><primary>dbltopnumber</primary></indexterm> +<para>Maximum number of full-sized floats that can appear at the top of a +two-column page; default 2. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>topnumber</primary></indexterm><literal>topnumber</literal> +</term><listitem><indexterm role="fn"><primary>topnumber</primary></indexterm> +<para>Maximum number of floats that can appear at the top of a text page; +default 2. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>totalnumber</primary></indexterm><literal>totalnumber</literal> +</term><listitem><indexterm role="fn"><primary>totalnumber</primary></indexterm> +<para>Maximum number of floats that can appear on a text page; default 3. +</para></listitem></varlistentry></variablelist> +<para>The principal &tex; FAQ entry relating to floats +<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats</ulink> contains +suggestions for relaxing &latex;’s default parameters to reduce the +problem of floats being pushed to the end. A full explaination of the +float placement algorithm is Frank Mittelbach’s article “How to +infuence the position of float environments like figure and table in +&latex;?” <ulink url="http://latex-project.org/papers/tb111mitt-float.pdf">http://latex-project.org/papers/tb111mitt-float.pdf</ulink>. +</para> + +</sect1> </chapter> <chapter label="6" id="Sectioning"> <title>Sectioning</title> -<indexterm role="cp"><primary>sectioning</primary></indexterm> + +<indexterm role="cp"><primary>sectioning commands</primary></indexterm> <para>Sectioning commands provide the means to structure your text into units: </para> @@ -1144,7 +1672,7 @@ To handle this, the sectioning commands have an optional argument <replaceable>toctitle</replaceable> that, when given, specifies the text for these other places. </para> -<indexterm role="cp"><primary>*-form of sectioning commands</primary></indexterm> +<indexterm role="cp"><primary><literal>*</literal>-form of sectioning commands</primary></indexterm> <para>Also, all sectioning commands have <literal>*</literal>-forms that print <replaceable>title</replaceable> as usual, but do not include a number and do not make an entry in the table of contents. For instance: @@ -1177,6 +1705,7 @@ The setting </chapter> <chapter label="7" id="Cross-references"> <title>Cross references</title> + <indexterm role="cp"><primary>cross references</primary></indexterm> <para>One reason for numbering things like figures and equations is to refer @@ -1186,6 +1715,7 @@ the reader to them, as in “See Figure 3 for more details.” <sect1 label="7.1" id="_005clabel"> <title><literal>\label</literal></title> + <indexterm role="fn"><primary>\label</primary></indexterm> <para>Synopsis: @@ -1194,15 +1724,33 @@ the reader to them, as in “See Figure 3 for more details.” </screen> <para>A <literal>\label</literal> command appearing in ordinary text assigns to <replaceable>key</replaceable> the number of the current sectional unit; one appearing -inside a numbered environment assigns that number to <replaceable>key</replaceable>. -</para> -<para>A <replaceable>key</replaceable> name can consist of any sequence of letters, digits, or +inside a numbered environment assigns that number to <replaceable>key</replaceable>. The +assigned number can be retrieved with the <literal>\ref{<replaceable>key</replaceable>}</literal> +command (see <link linkend="_005cref">\ref</link>). +</para> +<para>Thus, in the example below the key <literal>sec:test</literal> holds the number of +the current section and the key <literal>fig:test</literal> that of the figure. +(Incidentally, labels must appear after captions in figures and +tables.) +</para> +<screen>\section{section name} +\label{sec:test} +This is Section~\ref{sec:test}. +\begin{figure} + ... + \caption{caption text} + \label{fig:test} +\end{figure} +See Figure~\ref{fig:test}. +</screen> +<para>A key name can consist of any sequence of letters, digits, or common punctuation characters. Upper and lowercase letters are distinguished, as usual. </para> -<para>To avoid accidentally creating two labels with the same name, it is -common to use labels consisting of a prefix and a suffix separated by -a colon or period. Some conventionally-used prefixes: +<para>Although the name can be more or less anything, a common convention is +to use labels consisting of a prefix and a suffix separated by a colon +or period. This helps to avoid accidentally creating two labels with +the same name. Some commonly-used prefixes: </para> <variablelist><varlistentry><term><literal>ch</literal> </term><listitem><para>for chapters @@ -1215,13 +1763,14 @@ a colon or period. Some conventionally-used prefixes: </para></listitem></varlistentry><varlistentry><term><literal>eq</literal> </term><listitem><para>for equations </para></listitem></varlistentry></variablelist> -<para>Thus, a label for a figure would look like <literal>fig:snark</literal> or -<literal>fig.snark</literal>. +<para>Thus, a label for a figure would look like <literal>fig:test</literal> or +<literal>fig.test</literal>. </para> </sect1> <sect1 label="7.2" id="_005cpageref"> <title><literal>\pageref{<replaceable>key</replaceable>}</literal></title> + <indexterm role="fn"><primary>\pageref</primary></indexterm> <indexterm role="cp"><primary>cross referencing with page number</primary></indexterm> <indexterm role="cp"><primary>page number, cross referencing</primary></indexterm> @@ -1238,6 +1787,7 @@ the place in the text where the corresponding </sect1> <sect1 label="7.3" id="_005cref"> <title><literal>\ref{<replaceable>key</replaceable>}</literal></title> + <indexterm role="fn"><primary>\ref</primary></indexterm> <indexterm role="cp"><primary>cross referencing, symbolic</primary></indexterm> <indexterm role="cp"><primary>section number, cross referencing</primary></indexterm> @@ -1259,8 +1809,8 @@ such as the word ‘Section’ or ‘Figure’, just the bare nu </chapter> <chapter label="8" id="Environments"> <title>Environments</title> -<indexterm role="cp"><primary>environments</primary></indexterm> +<indexterm role="cp"><primary>environments</primary></indexterm> <indexterm role="fn"><primary>\begin</primary></indexterm> <indexterm role="fn"><primary>\end</primary></indexterm> @@ -1280,7 +1830,8 @@ Each environment begins and ends in the same manner: <indexterm role="cp"><primary>abstracts</primary></indexterm> <para>Synopsis: -</para><screen>\begin{abstract} +</para> +<screen>\begin{abstract} ... \end{abstract} </screen> @@ -1290,56 +1841,65 @@ Each environment begins and ends in the same manner: </sect1> <sect1 label="8.2" id="array"> <title><literal>array</literal></title> + <indexterm role="fn"><primary>array environment</primary></indexterm> <indexterm role="cp"><primary>arrays, math</primary></indexterm> <para>Synopsis: </para> -<screen>\begin{array}{<replaceable>template</replaceable>} -<replaceable>col1 text</replaceable>&<replaceable>col1 text</replaceable>&<replaceable>coln</replaceable>}\\ +<screen>\begin{array}{<replaceable>cols</replaceable>} +<replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ ... \end{array} </screen> -<para>Math arrays are produced with the <literal>array</literal> environment, normally -within an <literal>equation</literal> environment (see <link linkend="equation">equation</link>). It has a -single mandatory <replaceable>template</replaceable> argument describing the number of -columns and the alignment within them. Each column <replaceable>col</replaceable> is -specified by a single letter that tells how items in each row of that -column should be formatted, as follows: +<para>or </para> -<variablelist><varlistentry><term><literal>c</literal> -</term><listitem><para>centered -</para></listitem></varlistentry><varlistentry><term><literal>l</literal> -</term><listitem><para>flush left -</para></listitem></varlistentry><varlistentry><term><literal>r</literal> -</term><listitem><para>flush right -</para></listitem></varlistentry></variablelist> -<indexterm role="fn"><primary>\\ (for <literal>array</literal>)</primary></indexterm> -<para>Column entries are separated by <literal>&</literal>. Column entries may include -other &latex; commands. Each row of the array is terminated with -<literal>\\</literal>. +<screen>\begin{array}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} +<replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ +... +\end{array} +</screen> +<para>Produce a mathematical array. This environment can only be used in math +mode, and normally appears within a displayed mathematics environment +such as <literal>equation</literal> (see <link linkend="equation">equation</link>). Column entries are +separated by an ampersand (<literal>&</literal>). Rows are terminated with +double-backslashes (<literal>\\</literal>) (see <link linkend="_005c_005c">\\</link>). +</para> +<para>The required argument <replaceable>cols</replaceable> describes the number of columns, their +alignment, and the formatting of the intercolumn regions. See +<link linkend="tabular">tabular</link> for the complete description of <replaceable>cols</replaceable>, and of the +other common features of the two environments, including the optional +<replaceable>pos</replaceable> argument. +</para> +<para>There are two ways that <literal>array</literal> diverges from <literal>tabular</literal>. The +first is that <literal>array</literal> entries are typeset in mathematics mode, in +textstyle (except if the <replaceable>cols</replaceable> definition specifies the column with +<literal>@p{..}</literal>, which causes the entry to be typeset in text mode). +The second is that, instead of <literal>tabular</literal>’s parameter +<literal>\tabcolsep</literal>, &latex;’s intercolumn space in an array is governed +by +<indexterm role="fn"><primary>\arraycolsep</primary></indexterm> +<literal>\arraycolsep</literal> which gives half the width between columns. The +default for this is ‘<literal>5pt</literal>’. </para> -<indexterm role="fn"><primary>@{...}</primary></indexterm> -<para>In the template, the construct <literal>@{<replaceable>text</replaceable>}</literal> puts <replaceable>text</replaceable> -between columns in each row. +<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 <literal>(..)</literal>, <literal>bmatrix</literal> for an array +surrounded by square brackets <literal>[..]</literal>, <literal>Bmatrix</literal> for an +array surrounded by curly braces <literal>{..}</literal>, <literal>vmatrix</literal> for +an array surrounded by vertical bars <literal>|..|</literal>, and +<literal>Vmatrix</literal> for an array surrounded by double vertical +bars <literal>||..||</literal>, along with a number of other array constructs. </para> -<para>Here’s an example: +<para>Here is an example of an array: </para> <screen>\begin{equation} - \begin{array}{lrc} - left1 & right1 & centered1 \\ - left2 & right2 & centered2 \\ + \begin{array}{cr} + \sqrt{y} &12.3 \\ + x^2 &3.4 \end{array} \end{equation} </screen> -<indexterm role="fn"><primary>\arraycolsep</primary></indexterm> -<para>The <literal>\arraycolsep</literal> parameter defines half the width of the space -separating columns; the default is ‘<literal>5pt</literal>’. See <link linkend="tabular">tabular</link>, for other -parameters which affect formatting in <literal>array</literal> environments, -namely <literal>\arrayrulewidth</literal> and <literal>\arraystretch</literal>. -</para> -<para>The <literal>array</literal> environment can only be used in math mode. -</para> </sect1> <sect1 label="8.3" id="center"> @@ -1351,15 +1911,32 @@ namely <literal>\arrayrulewidth</literal> and <literal>\arraystretch</literal>. <para>Synopsis: </para> <screen>\begin{center} -<replaceable>line1</replaceable> \\ -<replaceable>line2</replaceable> \\ + .. text .. \end{center} </screen> +<para>Environment to create a sequence of lines that are centered within the +left and right margins on the current page. If the text in the +environment body is too long to fit on a line, &latex; will insert line +breaks that avoid hyphenation and avoid stretching or shrinking any +interword space. To force a line break at a particular spot use +double-backslash <literal>\\</literal> (see <link linkend="_005c_005c">\\</link>). <indexterm role="fn"><primary>\\ (for <literal>center</literal>)</primary></indexterm> -<para>The <literal>center</literal> environment allows you to create a paragraph -consisting of lines that are centered within the left and right -margins on the current page. Each line is terminated with the -string <literal>\\</literal>. +</para> +<para>This environment inserts space above and below the text body. See +<link linkend="_005ccentering">\centering</link> to avoid such space, for example inside a <literal>figure</literal> +environment. +</para> +<para>In this example, depending on the line width, &latex; may choose a break +for the part before the double backslash, will center the line or two, +then will break at the double backslash, and will center the ending. +</para> +<screen>\begin{center} + My father considered that anyone who went to chapel and didn't drink + alcohol was not to be tolerated.\\ + I grew up in that belief. --Richard Burton +\end{center} +</screen> +<para>A double backslash after the final line is optional. </para> @@ -1369,26 +1946,36 @@ string <literal>\\</literal>. <indexterm role="fn"><primary>\centering</primary></indexterm> <indexterm role="cp"><primary>centering text, declaration for</primary></indexterm> -<para>The <literal>\centering</literal> declaration corresponds to the <literal>center</literal> -environment. This declaration can be used inside an environment such -as <literal>quote</literal> or in a <literal>parbox</literal>. Thus, the text of a figure or -table can be centered on the page by putting a <literal>\centering</literal> -command at the beginning of the figure or table environment. -</para> -<para>Unlike the <literal>center</literal> environment, the <literal>\centering</literal> command -does not start a new paragraph; it simply changes how &latex; formats -paragraph units. To affect a paragraph unit’s format, the scope of -the declaration must contain the blank line or <literal>\end</literal> command (of -an environment such as quote) that ends the paragraph unit. -</para> -<para>Here’s an example: -</para> -<screen>\begin{quote} -\centering -first line \\ -second line \\ -\end{quote} +<para>Declaration that causes material in its scope to be centered. It is +most often used inside an environment such as <literal>figure</literal>, or in a +<literal>parbox</literal>. +</para> +<para>Unlike the <literal>center</literal> environment, the <literal>\centering</literal> command does +not add vertical space above and below the text. +</para> +<para>It also does not start a new paragraph; it simply changes how &latex; +formats paragraph units. If <literal>ww {\centering xx \\ yy} zz</literal> is +surrounded by blank lines then &latex; will create a paragraph whose +first line ‘<literal>ww xx</literal>’ is centered and whose second line, not centered, +contains ‘<literal>yy zz</literal>’. Usually what is desired is for the scope of the +declaration to contain a blank line or the <literal>\end</literal> command of an +environment such as <literal>figure</literal> or <literal>table</literal> that ends the +paragraph unit. Thus, if <literal>{\centering xx \\ yy\par} zz</literal> is +surrounded by blank lines then it makes a new paragraph with two +centered lines ‘<literal>xx</literal>’ and ‘<literal>yy</literal>’, followed by a new paragraph with +‘<literal>zz</literal>’ that is formatted as usual. See also the following example. +</para> +<para>This example’s <literal>\centering</literal> causes the graphic to be horizontally +centered. +</para> +<screen>\begin{figure} + \centering + \includegraphics[width=0.6\textwidth]{ctan_lion.png} + \caption{CTAN Lion} \label{fig:CTANLion} +\end{figure} </screen> +<para>The scope of the <literal>\centering</literal> ends with the <literal>\end{figure}</literal>. +</para> </sect2> </sect1> @@ -1402,51 +1989,91 @@ second line \\ <para>Synopsis: </para> <screen>\begin{description} -\item [<replaceable>label1</replaceable>] <replaceable>item1</replaceable> -\item [<replaceable>label2</replaceable>] <replaceable>item2</replaceable> -... +\item [<replaceable>first label</replaceable>] text of first item +\item [<replaceable>second label</replaceable>] text of second item + ... \end{description} </screen> <indexterm role="fn"><primary>\item</primary></indexterm> -<para>The <literal>description</literal> environment is used to make labelled lists. Each -<replaceable>label</replaceable> is typeset in bold, flush right. The <replaceable>item</replaceable> text may -contain multiple paragraphs. +<para>Environment to make a labelled list of items. Each item’s <replaceable>label</replaceable> +is typeset in bold, flush-left. Each item’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> +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>The list consists of at least one item; see <link linkend="_005citem">\item</link> (having no +items causes the &latex; error ‘<literal>Something's wrong--perhaps a +missing \item</literal>’). Each item is produced with an <literal>\item</literal> command. </para> <indexterm role="cp"><primary>bold typewriter, avoiding</primary></indexterm> <indexterm role="cp"><primary>typewriter labels in lists</primary></indexterm> -<para>Another variation: since the bold style is applied to the labels, if -you typeset a label in typewriter using <literal>\texttt</literal>, you’ll get -bold typewriter: <literal>\item[\texttt{bold and typewriter}]</literal>. This -may be too bold, among other issues. To get just typewriter, use -<literal>\tt</literal>, which resets all other style variations: <literal>\item[{\tt -plain typewriter}]</literal>. -</para> -<para>For details about list spacing, see <link linkend="itemize">itemize</link>. -</para> +<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 +typewriter, if that is available. The simplest way to get non-bolded +typewriter is to use declaritive style <literal>\item[{\tt label text}]</literal>. +Similarly, get normal text use <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. +</para> +<para>This example shows the environment used for a sequence of definitions. +</para> +<screen>\begin{definition} + \item[lama] A priest. + \item[llama] A beast. +\end{definition} +</screen> </sect1> <sect1 label="8.5" id="displaymath"> <title><literal>displaymath</literal></title> +<!-- http://tex.stackexchange.com/questions/40492/what-are-the-differences-between-align-equation-and-displaymath --> <indexterm role="fn"><primary>displaymath environment</primary></indexterm> <para>Synopsis: </para> <screen>\begin{displaymath} -<replaceable>math</replaceable> + .. math text .. \end{displaymath} </screen> -<para>or -</para> -<screen>\[<replaceable>math</replaceable>\] -</screen> -<para>The <literal>displaymath</literal> environment (<literal>\[...\]</literal> is a synonym) -typesets the <replaceable>math</replaceable> text on its own line, centered by default. -The global <literal>fleqn</literal> option makes equations flush left; see -<link linkend="Document-class-options">Document class options</link>. -</para> -<para>No equation number is added to <literal>displaymath</literal> text; to get an -equation number, use the <literal>equation</literal> environment (see <link linkend="equation">equation</link>). +<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> +<para>The construct <literal>\[..math text..\]</literal> is essentially a synonym for +<literal>\begin{displaymath}..math text..\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 &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’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} + \int_1^2 x^2\,dx=7/3 +\end{displaymath} +</screen><para>Also, the integral sign is larger than the inline version +<literal>\( \int_1^2 x^2\,dx=7/3 \)</literal> produces. </para> </sect1> @@ -1455,10 +2082,50 @@ equation number, use the <literal>equation</literal> environment (see <link link <indexterm role="fn"><primary>document environment</primary></indexterm> -<para>The <literal>document</literal> environment encloses the body of a document. +<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"/> + +<indexterm role="fn"><primary>\AtBeginDocument</primary></indexterm> +<indexterm role="cp"><primary>beginning of document hook</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\AtBeginDocument{<replaceable>code</replaceable>} +</screen> +<para>Save <replaceable>code</replaceable> and execute it when <literal>\begin{document}</literal> is +executed, at the very end of the preamble. The code is executed after +the font selection tables have been set up, so the normal font for the +document is the current font. However, the code is executed as part of +the preamble so you cannot do any typesetting with it. +</para> +<para>You can issue this command more than once; the successive code lines +will be executed in the order that you gave them. +</para> + +<anchor id="_005cAtEndDocument"/> + +<indexterm role="fn"><primary>\AtEndDocument</primary></indexterm> +<indexterm role="cp"><primary>end of document hook</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\AtEndDocument{<replaceable>code</replaceable>} +</screen> +<para>Save <replaceable>code</replaceable> and execute it near the end of the document. +Specifically, it is executed when <literal>\end{document}</literal> is executed, +before the final page is finished and before any leftover floating +environments are processed. If you want some of the code to be executed +after these two processes then include a <literal>\clearpage</literal> at the +appropriate point in <replaceable>code</replaceable>. +</para> +<para>You can issue this command more than once; the successive code lines +will be executed in the order that you gave them. +</para> + </sect1> <sect1 label="8.7" id="enumerate"> <title><literal>enumerate</literal></title> @@ -1469,50 +2136,72 @@ It is required in every &latex; document. See <link linkend="Starting-and-endin <para>Synopsis: </para> <screen>\begin{enumerate} -\item <replaceable>item1</replaceable> -\item <replaceable>item2</replaceable> +\item [<replaceable>first label</replaceable>] text of first item +\item [<replaceable>second label</replaceable>] text of second item ... \end{enumerate} </screen> -<para>The <literal>enumerate</literal> environment produces a numbered list. Enumerations -can be nested within one another, up to four levels deep. They can also -be nested within other paragraph-making environments, such as -<literal>itemize</literal> (see <link linkend="itemize">itemize</link>) and <literal>description</literal> -(see <link linkend="description">description</link>). +<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>Each item of an enumerated list begins with an <literal>\item</literal> command. -There must be at least one <literal>\item</literal> command within the environment. +<para>The list consists of at least one item. Having no items causes the +&latex; error ‘<literal>Something's wrong--perhaps a missing \item</literal>’. Each +item is produced with an <literal>\item</literal> command. </para> -<para>By default, the numbering at each level is done like this: +<para>This example lists the top two finishers in the 1908 Olympic marathon. </para> -<orderedlist numeration="arabic"><listitem><para>1., 2., … -</para></listitem><listitem><para>(a), (b), … -</para></listitem><listitem><para>i., ii., … -</para></listitem><listitem><para>A., B., … +<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;’s default for the format at each nesting level +(where 1 is the outermost level): +</para> +<orderedlist numeration="arabic"><listitem><para>arabic number followed by a period: ‘<literal>1.</literal>’, ‘<literal>2.</literal>’, … +</para></listitem><listitem><para>lower case letter inside parentheses: ‘<literal>(a)</literal>’, ‘<literal>(b)</literal>’ … +</para></listitem><listitem><para>lower case roman numeral followed by a period: ‘<literal>i.</literal>’, ‘<literal>ii.</literal>’, … +</para></listitem><listitem><para>upper case letter followed by a period: ‘<literal>A.</literal>’, ‘<literal>B.</literal>’, … </para></listitem></orderedlist> <indexterm role="fn"><primary>\enumi</primary></indexterm> <indexterm role="fn"><primary>\enumii</primary></indexterm> <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 the optional -argument to <literal>\item</literal> is given, the counter is not incremented for -that item. +<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>). </para> <indexterm role="fn"><primary>\labelenumi</primary></indexterm> <indexterm role="fn"><primary>\labelenumii</primary></indexterm> <indexterm role="fn"><primary>\labelenumiii</primary></indexterm> <indexterm role="fn"><primary>\labelenumiv</primary></indexterm> -<para>The <literal>enumerate</literal> environment uses the commands <literal>\labelenumi</literal> -through <literal>\labelenumiv</literal> to produce the default label. So, you can -use <literal>\renewcommand</literal> to change the labels (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & -\renewcommand</link>). For instance, to have the first level use uppercase -letters: +<para>To change the format of the label use <literal>\renewcommand</literal> +(see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \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: </para> <indexterm role="fn"><primary>\Alph example</primary></indexterm> -<screen>\renewcommand{\labelenumi}{\Alph{enumi}} +<screen>\renewcommand{\labelenumi}{\textbf{\Alph{enumi}}} +\begin{enumerate} + \item eI + \item bi: + \item si: +\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> </sect1> @@ -1526,44 +2215,63 @@ letters: <indexterm role="cp"><primary>align environment, from <literal>amsmath</literal></primary></indexterm> <indexterm role="cp"><primary>amsmath package, replacing <literal>eqnarray</literal></primary></indexterm> <indexterm role="cp"><primary>Madsen, Lars</primary></indexterm> -<para>First, a caveat: the <literal>eqnarray</literal> environment has some infelicities -which cannot be overcome; the article “Avoid eqnarray!” by Lars -Madsen describes them in detail -(<ulink url="http://tug.org/TUGboat/tb33-1/tb103madsen.pdf">http://tug.org/TUGboat/tb33-1/tb103madsen.pdf</ulink>). The bottom -line is that it is better to use the <literal>align</literal> environment (and -others) from the <literal>amsmath</literal> package. -</para> -<para>Nevertheless, here is a description of <literal>eqnarray</literal>: -</para> -<screen>\begin{eqnarray} (or <literal>eqnarray*</literal>) -<replaceable>formula1</replaceable> \\ -<replaceable>formula2</replaceable> \\ -... +<para>First, a caveat: the <literal>eqnarray</literal> environment is depreciated. It has +infelicities that cannot be overcome, including spacing that is +inconsistent with other mathematics elements (see the article “Avoid +eqnarray!” by Lars Madsen +<ulink url="http://tug.org/TUGboat/tb33-1/tb103madsen.pdf">http://tug.org/TUGboat/tb33-1/tb103madsen.pdf</ulink>). New documents +should include the <filename>amsmath</filename> package and use the displayed +mathematics environments provided there, such as the <literal>align</literal> +environment. +</para> +<para>Nevertheless, for completeness and for a reference when working with old +documents, a synopsis: +</para> +<screen>\begin{eqnarray} + <replaceable>first formula left</replaceable> &<replaceable>first formula middle</replaceable> &<replaceable>first formula right</replaceable> \\ + ... \end{eqnarray} </screen> +<para>or +</para> +<screen>\begin{eqnarray*} + <replaceable>first formula left</replaceable> &<replaceable>first formula middle</replaceable> &<replaceable>first formula right</replaceable> \\ + ... +\end{eqnarray*} +</screen> <indexterm role="fn"><primary>\\ (for <literal>eqnarray</literal>)</primary></indexterm> -<para>The <literal>eqnarray</literal> environment is used to display a sequence of -equations or inequalities. It is similar to a three-column -<literal>array</literal> environment, with consecutive rows separated by <literal>\\</literal> -and consecutive items within a row separated by an <literal>&</literal>. +<para>Display a sequence of equations or inequalities. The left and right +sides are typeset in display mode, while the middle is typeset in text +mode. </para> +<para>It is similar to a three-column <literal>array</literal> environment, with items +within a row separated by an ampersand (<literal>&</literal>), and with rows +separated by double backslash  <literal>\\</literal>). <indexterm role="fn"><primary>\\* (for <literal>eqnarray</literal>)</primary></indexterm> -<para><literal>\\*</literal> can also be used to separate equations, with its normal -meaning of not allowing a page break at that line. +The starred form of line break (<literal>\\*</literal>) can also be used to separate +equations, and will disallow a page break there (see <link linkend="_005c_005c">\\</link>). </para> <indexterm role="fn"><primary>\nonumber</primary></indexterm> <indexterm role="cp"><primary>equation numbers, omitting</primary></indexterm> -<para>An equation number is placed on every line unless that line has a -<literal>\nonumber</literal> command. Alternatively, The <literal>*</literal>-form of the -environment (<literal>\begin{eqnarray*} ... \end{eqnarray*}</literal>) will -omit equation numbering entirely, while otherwise being the same as -<literal>eqnarray</literal>. +<para>The unstarred form <literal>eqnarray</literal> places an equation number on every +line (using the <literal>equation</literal> counter), unless that line contains a +<literal>\nonumber</literal> command. The starred form <literal>eqnarray*</literal> omits +equation numbering, while otherwise being the same. </para> <indexterm role="fn"><primary>\lefteqn</primary></indexterm> <para>The command <literal>\lefteqn</literal> is used for splitting long formulas across lines. It typesets its argument in display style flush left in a box of zero width. </para> +<para>This example shows three lines. The first two lines make an inequality, +while the third line has not entry on the left side. +</para> +<screen>\begin{eqnarray*} + \lefteqn{x_1+x_2+\cdots+x_n} \\ + &\leq &y_1+y_2+\cdots+y_n \\ + &= &z+y_3+\cdots+y_n +\end{eqnarray*} +</screen> </sect1> <sect1 label="8.9" id="equation"> @@ -1576,196 +2284,141 @@ zero width. <para>Synopsis: </para> <screen>\begin{equation} -<replaceable>math</replaceable> + math text \end{equation} </screen> -<para>The <literal>equation</literal> environment starts a <literal>displaymath</literal> -environment (see <link linkend="displaymath">displaymath</link>), e.g., centering the <replaceable>math</replaceable> text -on the page, and also places an equation number in the right margin. +<para>Make a <literal>displaymath</literal> environment (see <link linkend="displaymath">displaymath</link>) with an +equation number in the right margin. +</para> +<para>The equation number is generated using the <literal>equation</literal> counter. +</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. </para> </sect1> <sect1 label="8.10" id="figure"> <title><literal>figure</literal></title> + <indexterm role="fn"><primary>figure</primary></indexterm> <indexterm role="cp"><primary>inserting figures</primary></indexterm> <indexterm role="cp"><primary>figures, inserting</primary></indexterm> -<screen>\begin{figure[*]}[<replaceable>placement</replaceable>] -<replaceable>figbody</replaceable> +<para>Synopsis: +</para> +<screen>\begin{figure}[<replaceable>placement</replaceable>] + figure body +\caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} \label{<replaceable>label}</replaceable> -\caption[<replaceable>loftitle</replaceable>]{<replaceable>text</replaceable>} \end{figure} </screen> -<para>Figures are objects that are not part of the normal text, and are -instead “floated” to a convenient place, such as the top of a page. -Figures will not be split between two pages. -</para> -<para>When typesetting in double-columns, the starred form produces a -full-width figure (across both columns). -</para> -<indexterm role="cp"><primary>placement of floats</primary></indexterm> -<indexterm role="cp"><primary>specifier, float placement</primary></indexterm> -<para>The optional argument <literal>[placement]</literal> determines where &latex; will try -to place your figure. There are four places where &latex; can possibly -put a float: -</para> -<variablelist><varlistentry><term><literal>t</literal> -</term><listitem><para>(Top)—at the top of a text page. -</para> -</listitem></varlistentry><varlistentry><term><literal>b</literal> -</term><listitem><para>(Bottom)—at the bottom of a text page. However, <literal>b</literal> is not -allowed for full-width floats (<literal>figure*</literal>) with double-column -output. To ameliorate this, use the <literal>stfloats</literal> or -<literal>dblfloatfix</literal> package, but see the discussion at caveats in the -FAQ: <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat</ulink>. -</para> -</listitem></varlistentry><varlistentry><term><literal>h</literal> -</term><listitem><para>(Here)—at the position in the text where the <literal>figure</literal> environment -appears. However, <literal>t</literal> is not allowed by itself; <literal>t</literal> is -automatically added. -</para> -<indexterm role="cp"><primary>here, putting floats</primary></indexterm> -<indexterm role="cp"><primary><literal>float</literal> package</primary></indexterm> -<para>To absolutely force a figure to appear “here”, you can -<literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it -defines. For further discussion, see the FAQ entry at -<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere</ulink>. +<para>or </para> -</listitem></varlistentry><varlistentry><term><literal>p</literal> -</term><listitem><para>(Page of floats)—on a separate float page, which is a page -containing no text, only floats. +<screen>\begin{figure*}[<replaceable>placement</replaceable>] + figure body +\caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} +\label{<replaceable>label}</replaceable> +\end{figure*} +</screen> +<para>A class of floats (see <link linkend="Floats">Floats</link>). Because they cannot be split across +pages, they are not typeset in sequence with the normal text but instead +are “floated” to a convenient place, such as the top of a following +page. </para> -</listitem></varlistentry><varlistentry><term><literal>!</literal> -</term><listitem><para>Used in addition to one of the above; for this float only, &latex; -ignores the restrictions on both the number of floats that can appear -and the relative amounts of float and non-float text on the page. -The <literal>!</literal> specifier does <emphasis>not</emphasis> mean “put the float here”; -see above. +<para>For the possible values of <replaceable>placement</replaceable> and their effect on the +float placement algorithm, see <link linkend="Floats">Floats</link>. </para> -</listitem></varlistentry></variablelist> -<para>The standard <literal>report</literal> and <literal>article</literal> classes use the default placement -<literal>tbp</literal>. +<para>The starred form <literal>figure*</literal> is used when a document is in +double-column mode (see <link linkend="_005ctwocolumn">\twocolumn</link>). It produces a figure that +spans both columns, at the top of the page. To add the possibility of +placing at a page bottom see the discussion of <replaceable>placement</replaceable> <literal>b</literal> +in <link linkend="Floats">Floats</link>. </para> -<para>The body of the figure is made up of whatever text, &latex; commands, -etc. you wish. +<para>The figure body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal> +and so it can contain text, commands, etc. </para> +<para>The label is optional; it is used for cross-references (see <link linkend="Cross-references">Cross +references</link>). <indexterm role="fn"><primary>\caption</primary></indexterm> -<para>The <literal>\caption</literal> command specifies caption <replaceable>text</replaceable> for the -figure. The caption is numbered by default. If <replaceable>loftitle</replaceable> is -present, it is used in the list of figures instead of <replaceable>text</replaceable> -(see <link linkend="Tables-of-contents">Tables of contents</link>). -</para> -<para>Parameters relating to fractions of pages occupied by float and -non-float text: -</para> -<variablelist><indexterm role="fn"><primary>\bottomfraction</primary></indexterm> -<para>The maximum fraction of the page allowed to be occupied by floats at -the bottom; default ‘<literal>.3</literal>’. -</para> -<varlistentry><term><indexterm role="fn"><primary>\floatpagefraction</primary></indexterm><literal>\floatpagefraction</literal> -</term><listitem><para>The minimum fraction of a float page that must be occupied by floats; -default ‘<literal>.5</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textfraction</primary></indexterm><literal>\textfraction</literal> -</term><listitem><para>Minimum fraction of a page that must be text; if floats take up too -much space to preserve this much text, floats will be moved to a -different page. The default is ‘<literal>.2</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topfraction</primary></indexterm><literal>\topfraction</literal> -</term><listitem><para>Maximum fraction at the top of a page that may be occupied before -floats; default ‘<literal>.7</literal>’. -</para></listitem></varlistentry></variablelist> -<para>Parameters relating to vertical space around floats: -</para> -<variablelist><varlistentry><term><indexterm role="fn"><primary>\floatsep</primary></indexterm><literal>\floatsep</literal> -</term><listitem><para>Space between floats at the top or bottom of a page; default -‘<literal>12pt plus2pt minus2pt</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\intextsep</primary></indexterm><literal>\intextsep</literal> -</term><listitem><para>Space above and below a float in the middle of the main text; default -‘<literal>12pt plus2pt minus2pt</literal>’ for ‘<literal>10pt</literal>’ and ‘<literal>11pt</literal>’ styles, -‘<literal>14pt plus4pt minus4pt</literal>’ for ‘<literal>12pt</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textfloatsep</primary></indexterm><literal>\textfloatsep</literal> -</term><listitem><para>Space between the last (first) float at the top (bottom) of a page; -default ‘<literal>20pt plus2pt minus4pt</literal>’. -</para></listitem></varlistentry></variablelist> -<para>Counters relating to the number of floats on a page: -</para> -<variablelist><varlistentry><term><indexterm role="fn"><primary>bottomnumber</primary></indexterm><literal>bottomnumber</literal> -</term><listitem><para>Maximum number of floats that can appear at the bottom of a text page; -default 1. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>dbltopnumber</primary></indexterm><literal>dbltopnumber</literal> -</term><listitem><para>Maximum number of full-sized floats that can appear at the top of a -two-column page; default 2. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>topnumber</primary></indexterm><literal>topnumber</literal> -</term><listitem><para>Maximum number of floats that can appear at the top of a text page; -default 2. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>totalnumber</primary></indexterm><literal>totalnumber</literal> -</term><listitem><para>Maximum number of floats that can appear on a text page; default 3. -</para></listitem></varlistentry></variablelist> -<para>The principal &tex; FAQ entry relating to floats: -<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats</ulink>. -</para> +The optional <literal>\caption</literal> command specifies caption text for the +figure. By default it is numbered. If <replaceable>loftitle</replaceable> is present, it is +used in the list of figures instead of <replaceable>title</replaceable> (see <link linkend="Tables-of-contents">Tables of +contents</link>). +</para> +<para>This example makes a figure out of a graphic. It requires one of the +packages <filename>graphics</filename> or <filename>graphicx</filename>. The graphic, with its +caption, will be placed at the top of a page or, if it is pushed to the +end of the document, on a page of floats. +</para> +<screen>\begin{figure}[t] + \centering + \includegraphics[width=0.5\textwidth]{CTANlion.png} + \caption{The CTAN lion, by Duane Bibby} +\end{figure} +</screen> </sect1> <sect1 label="8.11" id="filecontents"> -<title><literal>filecontents</literal>: Create external files</title> +<title><literal>filecontents</literal>: Write an external file</title> + <indexterm role="fn"><primary>filecontents</primary></indexterm> -<indexterm role="cp"><primary>external files, creating</primary></indexterm> +<indexterm role="cp"><primary>external files, writing</primary></indexterm> <indexterm role="cp"><primary>writing external files</primary></indexterm> <para>Synopsis: </para> <screen>\begin{filecontents}{<replaceable>filename</replaceable>} -<replaceable>contents-of-file</replaceable> + <replaceable>text</replaceable> \end{filecontents} -... -\documentclass{<replaceable>my-document-class</replaceable>} </screen> -<indexterm role="cp"><primary>initial command</primary></indexterm> -<indexterm role="fn"><primary>\documentclass, commands before</primary></indexterm> -<para>The <literal>filecontents</literal> environment is an <firstterm>initial command</firstterm>, -meaning that it can be used only before the <literal>\documentclass</literal> -command, as in the synopsis above. -</para> -<para>&latex; will create a file named <replaceable>filename</replaceable> with the content -<replaceable>contents-of-file</replaceable> preceded by a header comment indicating how and -when the file was generated. If the file already exists then nothing will -happen. -</para> -<para>You can also use the <literal>filecontents</literal> package, which has the -following advantages: +<para>or </para> -<itemizedlist><listitem><para>If the file already exists, then it will be overwritten. +<screen>\begin{filecontents*}{<replaceable>filename</replaceable>} + <replaceable>text</replaceable> +\end{filecontents*} +</screen> +<para>Create a file named <replaceable>filename</replaceable> and fill it with <replaceable>text</replaceable>. The +unstarred version of the environment <literal>filecontents</literal> prefixes the +content of the created file with a header; see the example below. The +starred version <literal>filecontents*</literal> does not include the header. </para> -</listitem><listitem><para>You can use the <literal>filecontents</literal> environment at any point after the -declaration <literal>\usepackage{filecontents}</literal>, not just before -<literal>\documentclass</literal>. +<para>This environment can be used anywhere in the preamble, although it often +appears before the <literal>\documentclass</literal> command. It is typically used +when a source file requires a nonstandard style or class file. The +environment will write that file to the directory containing the source +and thus make the source file self-contained. Another use is to include +<literal>bib</literal> references in the file, again to make it self-contained. </para> -</listitem><listitem><para>The <literal>filecontents</literal> package also provides a <literal>filecontents*</literal> -environment which is used in the same way as the <literal>filecontents</literal> -environment except that it won’t insert any leading comment, so it is -better suited to create files which aren’t in &latex; format. +<para>The environment checks whether a file of that name already exists and if +so, does not do anything. There is a <filename>filecontents</filename> package that +redefines the <literal>filecontents</literal> environment so that instead of doing +nothing in that case, it will overwrite the existing file. </para> -</listitem></itemizedlist> -<para>The <literal>filecontents</literal> environment only creates the file, and is -unrelated to using the created file. So you need to use, for -instance, <literal>\input</literal> or <literal>\usepackage</literal> or <literal>\bibliography</literal> -or whatever is applicable, to use the created file. +<para>For example, this document </para> -<para>This environment is also useful to make a document in a self-contained -file, for example, for a bug report, or to keep the content of a -<filename>.bib</filename> file in the same file as the main document. +<screen>\documentclass{article} +\begin{filecontents}{JH.sty} +\newcommand{\myname}{Jim Hef{}feron} +\end{filecontents} +\usepackage{JH} +\begin{document} +Article by \myname. +\end{document} +</screen> +<para>produces this file <filename>JH.sty</filename>. </para> +<screen>%% LaTeX2e file `JH.sty' +%% generated by the `filecontents' environment +%% from source `test' on 2015/10/12. +%% +\newcommand{\myname}{Jim Hef{}feron} +</screen> </sect1> <sect1 label="8.12" id="flushleft"> <title><literal>flushleft</literal></title> + <indexterm role="fn"><primary>flushleft 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> @@ -1779,12 +2432,13 @@ file, for example, for a bug report, or to keep the content of a <indexterm role="fn"><primary>\\ for <literal>flushleft</literal></primary></indexterm> <para>The <literal>flushleft</literal> environment allows you to create a paragraph consisting of lines that are flush to the left-hand margin and ragged -right Each line must be terminated with the string <literal>\\</literal>. +right. Each line must be terminated with the string <literal>\\</literal>. </para> <sect2 label="8.12.1" id="_005craggedright"> <title><literal>\raggedright</literal></title> + <indexterm role="fn"><primary>\raggedright</primary></indexterm> <indexterm role="cp"><primary>ragged right text</primary></indexterm> <indexterm role="cp"><primary>left-justifying text</primary></indexterm> @@ -1805,6 +2459,7 @@ command that ends the paragraph unit. </sect1> <sect1 label="8.13" id="flushright"> <title><literal>flushright</literal></title> + <indexterm role="fn"><primary>flushright 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> @@ -1818,12 +2473,13 @@ command that ends the paragraph unit. <indexterm role="fn"><primary>\\ (for <literal>flushright</literal>)</primary></indexterm> <para>The <literal>flushright</literal> environment allows you to create a paragraph consisting of lines that are flush to the right-hand margin and ragged -left. Each line must be terminated with the string <literal>\\</literal>. +left. Each line must be terminated with the control sequence <literal>\\</literal>. </para> <sect2 label="8.13.1" id="_005craggedleft"> <title><literal>\raggedleft</literal></title> + <indexterm role="fn"><primary>\raggedleft</primary></indexterm> <indexterm role="cp"><primary>ragged left text</primary></indexterm> <indexterm role="cp"><primary>justification, ragged left</primary></indexterm> @@ -1844,6 +2500,7 @@ command that ends the paragraph unit. </sect1> <sect1 label="8.14" id="itemize"> <title><literal>itemize</literal></title> + <indexterm role="fn"><primary>itemize environment</primary></indexterm> <indexterm role="fn"><primary>\item</primary></indexterm> <indexterm role="cp"><primary>lists of items</primary></indexterm> @@ -1970,7 +2627,8 @@ see <link linkend="_005cparskip">\parskip</link>): </sect1> <sect1 label="8.15" id="letter"> <title><literal>letter</literal> environment: writing letters</title> -<indexterm role="fn"><primary>letter</primary></indexterm> + +<indexterm role="fn"><primary>letter environment</primary></indexterm> <para>This environment is used for creating letters. See <link linkend="Letters">Letters</link>. </para> @@ -1978,6 +2636,7 @@ see <link linkend="_005cparskip">\parskip</link>): </sect1> <sect1 label="8.16" id="list"> <title><literal>list</literal></title> + <indexterm role="fn"><primary>list</primary></indexterm> <indexterm role="cp"><primary>lists of items, generic</primary></indexterm> @@ -2004,6 +2663,42 @@ empty, i.e., <literal>{}</literal>, which leaves the default spacing. <literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page layout parameters</link>). </para> + +<anchor id="_005citem"/> + +<para>Synopsis: +</para> +<screen>\item text of item +</screen> +<para>or +</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. +</para> +<para>Because the optional argument <replaceable>optional label</replaceable> is surrounded by +square brackets (<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> +<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> +<screen>\begin{enumerate} + \item Moe + \item[sometimes] Shemp + \item Larry +\end{enumerate} +</screen> +<para>The first item is labelled ‘<literal>1.</literal>’, the second item is labelled +‘<literal>sometimes</literal>’, and the third item is labelled ‘<literal>2.</literal>’ (note that, +because of the optional label in the second item, the third item does +not get a ‘<literal>3.</literal>’). +</para> + + </sect1> <sect1 label="8.17" id="math"> <title><literal>math</literal></title> @@ -2018,7 +2713,7 @@ empty, i.e., <literal>{}</literal>, which leaves the default spacing. \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. +running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms. See <link linkend="Math-formulas">Math formulas</link>. </para> @@ -2069,7 +2764,7 @@ footnotes; they may wind up at the bottom of the wrong minipage. <indexterm role="cp"><primary>creating pictures</primary></indexterm> <indexterm role="cp"><primary>pictures, creating</primary></indexterm> -<screen>\begin{picture}(width,height)(x offset,y offset) +<screen>\begin{picture}(<replaceable>width</replaceable>,<replaceable>height</replaceable>)(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>) … <replaceable>picture commands</replaceable> … \end{picture} </screen> @@ -2088,22 +2783,23 @@ centimeters. <literal>\setlength</literal> command, outside of a <literal>picture</literal> environment. The default value is <literal>1pt</literal>. </para> -<para>A position is a pair of coordinates, such as <literal>(2.4,-5)</literal>, specifying +<indexterm role="cp"><primary>position, in picture</primary></indexterm> +<para>A <firstterm>position</firstterm> is a pair of coordinates, such as <literal>(2.4,-5)</literal>, specifying the point with x-coordinate <literal>2.4</literal> and y-coordinate <literal>-5</literal>. Coordinates are specified in the usual way with respect to an origin, which is normally at the lower-left corner of the picture. Note that when a position appears as an argument, it is not enclosed in braces; the parentheses serve to delimit the argument. </para> -<para>The <literal>picture</literal> environment has one mandatory argument, which is a -<literal>position</literal>. It specifies the size of the picture. The environment -produces a rectangular box with width and height determined by this -argument’s x- and y-coordinates. +<para>The <literal>picture</literal> environment has one mandatory argument which is a +position (<replaceable>width</replaceable>,<replaceable>height</replaceable>), which specifies the size of the +picture. The environment produces a rectangular box with these +<replaceable>width</replaceable> and <replaceable>height</replaceable>. </para> -<para>The <literal>picture</literal> environment also has an optional <literal>position</literal> -argument, following the <literal>size</literal> argument, that can change the -origin. (Unlike ordinary optional arguments, this argument is not -contained in square brackets.) The optional argument gives the +<para>The <literal>picture</literal> environment also has an optional position argument +(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>), following the size argument, that can +change the origin. (Unlike ordinary optional arguments, this argument +is not contained in square brackets.) The optional argument gives the coordinates of the point at the lower-left corner of the picture (thereby determining the origin). For example, if <literal>\unitlength</literal> has been set to <literal>1mm</literal>, the command @@ -2145,10 +2841,12 @@ be the lower left corner of the box. <sect2 label="8.19.1" id="_005ccircle"> <title><literal>\circle</literal></title> + <indexterm role="fn"><primary>\circle</primary></indexterm> <para>Synopsis: -</para><screen>\circle[*]{<replaceable>diameter</replaceable>} +</para> +<screen>\circle[*]{<replaceable>diameter</replaceable>} </screen> <para>The <literal>\circle</literal> command produces a circle with a diameter as close to the specified one as possible. The <literal>*</literal>-form of the command @@ -2160,10 +2858,12 @@ draws a solid circle. </sect2> <sect2 label="8.19.2" id="_005cmakebox-_0028picture_0029"> <title><literal>\makebox</literal></title> + <indexterm role="fn"><primary>\makebox (for <literal>picture</literal>)</primary></indexterm> <para>Synopsis: -</para><screen>\makebox(<replaceable>width</replaceable>,<replaceable>height</replaceable>)[<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</para> +<screen>\makebox(<replaceable>width</replaceable>,<replaceable>height</replaceable>)[<replaceable>position</replaceable>]{<replaceable>text</replaceable>} </screen> <para>The <literal>\makebox</literal> command for the picture environment is similar to the normal <literal>\makebox</literal> command except that you must specify a @@ -2191,6 +2891,7 @@ your <replaceable>text</replaceable> appears in. You may select up to two of th </sect2> <sect2 label="8.19.3" id="_005cframebox-_0028picture_0029"> <title><literal>\framebox</literal></title> + <indexterm role="fn"><primary>\framebox</primary></indexterm> <para>Synopsis: @@ -2230,6 +2931,7 @@ multiples of the <replaceable>dlen</replaceable>. </sect2> <sect2 label="8.19.5" id="_005cframe"> <title><literal>\frame</literal></title> + <indexterm role="fn"><primary>\frame</primary></indexterm> <para>Synopsis: @@ -2244,6 +2946,7 @@ space is put between the frame and the object. </sect2> <sect2 label="8.19.6" id="_005cline"> <title><literal>\line</literal></title> + <indexterm role="fn"><primary>\line</primary></indexterm> <para>Synopsis: @@ -2264,6 +2967,7 @@ see <literal>pict2e</literal> and many other packages on CTAN. </sect2> <sect2 label="8.19.7" id="_005clinethickness"> <title><literal>\linethickness</literal></title> + <indexterm role="fn"><primary>\linethickness</primary></indexterm> <para>The <literal>\linethickness{<replaceable>dim</replaceable>}</literal> command declares the thickness @@ -2277,6 +2981,7 @@ circles, or the quarter circles drawn by <literal>\oval</literal>. </sect2> <sect2 label="8.19.8" id="_005cthicklines"> <title><literal>\thicklines</literal></title> + <indexterm role="fn"><primary>\thicklines</primary></indexterm> <para>The <literal>\thicklines</literal> command is an alternate line thickness for @@ -2287,6 +2992,7 @@ cf. <link linkend="_005clinethickness">\linethickness</link> and <link link </sect2> <sect2 label="8.19.9" id="_005cthinlines"> <title><literal>\thinlines</literal></title> + <indexterm role="fn"><primary>\thinlines</primary></indexterm> <para>The <literal>\thinlines</literal> command is the default line thickness for @@ -2297,10 +3003,12 @@ cf. <link linkend="_005clinethickness">\linethickness</link> and <link link </sect2> <sect2 label="8.19.10" id="_005cmultiput"> <title><literal>\multiput</literal></title> + <indexterm role="fn"><primary>\multiput</primary></indexterm> <para>Synopsis: -</para><screen>\multiput(<replaceable>x</replaceable>,<replaceable>y</replaceable>)(<replaceable>delta_x</replaceable>,<replaceable>delta_y</replaceable>){<replaceable>n</replaceable>}{<replaceable>obj</replaceable>} +</para> +<screen>\multiput(<replaceable>x</replaceable>,<replaceable>y</replaceable>)(<replaceable>delta_x</replaceable>,<replaceable>delta_y</replaceable>){<replaceable>n</replaceable>}{<replaceable>obj</replaceable>} </screen> <para>The <literal>\multiput</literal> command copies the object <replaceable>obj</replaceable> in a regular pattern across a picture. <replaceable>obj</replaceable> is first placed at position @@ -2311,25 +3019,29 @@ pattern across a picture. <replaceable>obj</replaceable> is first placed at pos </sect2> <sect2 label="8.19.11" id="_005coval"> <title><literal>\oval</literal></title> + <indexterm role="fn"><primary>\oval</primary></indexterm> <para>Synopsis: </para> <screen>\oval(<replaceable>width</replaceable>,<replaceable>height</replaceable>)[<replaceable>portion</replaceable>] </screen> -<para>The <literal>\oval</literal> command produces a rectangle with rounded corners. -The optional argument <replaceable>portion</replaceable> allows you to select part of the +<para>The <literal>\oval</literal> command produces a rectangle with rounded corners. The +optional argument <replaceable>portion</replaceable> allows you to produce only half of the oval via the following: </para> <variablelist><varlistentry><term><literal>t</literal> -</term><listitem><para>selects the top portion; +</term><listitem><para>selects the top half; </para></listitem></varlistentry><varlistentry><term><literal>b</literal> -</term><listitem><para>selects the bottom portion; +</term><listitem><para>selects the bottom half; </para></listitem></varlistentry><varlistentry><term><literal>r</literal> -</term><listitem><para>selects the right portion; +</term><listitem><para>selects the right half; </para></listitem></varlistentry><varlistentry><term><literal>l</literal> -</term><listitem><para>selects the left portion. +</term><listitem><para>selects the left half. </para></listitem></varlistentry></variablelist> +<para>It is also possible to produce only one quarter of the oval by setting +<replaceable>portion</replaceable> to <literal>tr</literal>, <literal>br</literal>, <literal>bl</literal>, or <literal>tl</literal>. +</para> <para>The “corners” of the oval are made with quarter circles with a maximum radius of 20pt, so large “ovals” will look more like boxes with rounded corners. @@ -2338,6 +3050,7 @@ boxes with rounded corners. </sect2> <sect2 label="8.19.12" id="_005cput"> <title><literal>\put</literal></title> + <indexterm role="fn"><primary>\put</primary></indexterm> <para>Synopsis: @@ -2352,6 +3065,7 @@ boxes with rounded corners. </sect2> <sect2 label="8.19.13" id="_005cshortstack"> <title><literal>\shortstack</literal></title> + <indexterm role="fn"><primary>\shortstack</primary></indexterm> <para>Synopsis: @@ -2375,6 +3089,7 @@ positions are: </sect2> <sect2 label="8.19.14" id="_005cvector"> <title><literal>\vector</literal></title> + <indexterm role="fn"><primary>\vector</primary></indexterm> <para>Synopsis: @@ -2388,13 +3103,17 @@ values must lie between −4 and +4, inclusive. </sect2> </sect1> -<sect1 label="8.20" id="quotation"> -<title><literal>quotation</literal></title> +<sect1 label="8.20" id="quotation-and-quote"> +<title><literal>quotation</literal> and <literal>quote</literal></title> <indexterm role="fn"><primary>quotation</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>quote</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> <para>Synopsis: </para> @@ -2402,38 +3121,37 @@ values must lie between −4 and +4, inclusive. <replaceable>text</replaceable> \end{quotation} </screen> -<para>The margins of the <literal>quotation</literal> environment are indented on both -the left and the right. The text is justified at both margins. -Leaving a blank line between text produces a new paragraph. -</para> -<para>Unlike the <literal>quote</literal> environment, each paragraph is indented -normally. -</para> - -</sect1> -<sect1 label="8.21" id="quote"> -<title><literal>quote</literal></title> - -<indexterm role="fn"><primary>quote</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> - -<para>Synopsis: +<para>or </para> <screen>\begin{quote} <replaceable>text</replaceable> \end{quote} </screen> -<para>The margins of the <literal>quote</literal> environment are indented on both the -left and the right. The text is justified at both margins. Leaving a -blank line between text produces a new paragraph. -</para> -<para>Unlike the <literal>quotation</literal> environment, paragraphs are not indented. +<para>Include a quotation. +</para> +<para>In both environments, margins are indented on both sides by +<literal>\leftmargin</literal> and the text is justified at both. As with the main +text, leaving a blank line produces a new paragraph. +</para> +<para>To compare the two: in the <literal>quotation</literal> environment, paragraphs are +indented by 1.5em and the space between paragraphs is small, +<literal>0pt plus 1pt</literal>. In the <literal>quote</literal> environment, paragraphs are +not indented and there is vertical space between paragraphs (it is the +rubber length <literal>\parsep</literal>). Thus, the <literal>quotation</literal> environment +may be more suitable for documents where new paragraphs are marked by an +indent rather than by a vertical separation. In addition, <literal>quote</literal> +may be more suitable for a short quotation or a sequence of short +quotations. </para> +<screen>\begin{quotation} +\it Four score and seven years ago + .. shall not perish from the earth. +\hspace{1em plus 1fill}---Abraham Lincoln +\end{quotation} +</screen> </sect1> -<sect1 label="8.22" id="tabbing"> +<sect1 label="8.21" id="tabbing"> <title><literal>tabbing</literal></title> <indexterm role="fn"><primary>tabbing environment</primary></indexterm> @@ -2485,7 +3203,7 @@ necessary. </para> </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>\></literal>, +current column, i.e., everything from the most recent <literal>\></literal>, <literal>\<</literal>, <literal>\'</literal>, <literal>\\</literal>, or <literal>\kill</literal> command, to the right of the previous column, flush against the current column’s tab stop. </para> @@ -2538,7 +3256,7 @@ function \= fact(n : integer) : integer;\\ </screen> </sect1> -<sect1 label="8.23" id="table"> +<sect1 label="8.22" id="table"> <title><literal>table</literal></title> <indexterm role="fn"><primary>table</primary></indexterm> @@ -2547,79 +3265,114 @@ function \= fact(n : integer) : integer;\\ <para>Synopsis: </para> -<screen> \begin{table}[placement] - - body of the table - - \caption{table title} - \end{table} +<screen>\begin{table}[<replaceable>placement</replaceable>] + table body +\caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} +\label{<replaceable>label}</replaceable> +\end{table} </screen> -<para>Tables are objects that are not part of the normal text, and are -usually “floated” to a convenient place, like the top of a page. -Tables will not be split between two pages. -</para> -<para>The optional argument <literal>[placement]</literal> determines where &latex; will try -to place your table. There are four places where &latex; can possibly put -a float; these are the same as that used with the <literal>figure</literal> -environment, and described there (see <link linkend="figure">figure</link>). +<para>A class of floats (see <link linkend="Floats">Floats</link>). Because they cannot be split across +pages, they are not typeset in sequence with the normal text but instead +are “floated” to a convenient place, such as the top of a following +page. </para> -<para>The standard <literal>report</literal> and <literal>article</literal> classes use the default -placement <literal>[tbp]</literal>. +<para>For the possible values of <replaceable>placement</replaceable> and their effect on the +float placement algorithm, see <link linkend="Floats">Floats</link>. </para> -<para>The body of the table is made up of whatever text, &latex; commands, etc., -you wish. The <literal>\caption</literal> command allows you to title your table. +<para>The table body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal> +and so it can contain text, commands, etc. </para> +<para>The label is optional; it is used for cross-references (see <link linkend="Cross-references">Cross +references</link>). +<indexterm role="fn"><primary>\caption</primary></indexterm> +The optional <literal>\caption</literal> command specifies caption text for the +table. By default it is numbered. If <replaceable>lottitle</replaceable> is present, it is +used in the list of tables instead of <replaceable>title</replaceable> (see <link linkend="Tables-of-contents">Tables of +contents</link>). +</para> +<para>In this example the table and caption will float to the bottom of a page, +unless it is pushed to a float page at the end. +</para> +<screen>\begin{table}[b] + \centering + \begin{tabular}{r|p{2in}} \hline + One &The loneliest number \\ + Two &Can be as sad as one. + It's the loneliest number since the number one. + \end{tabular} + \caption{Cardinal virtues} + \label{tab:CardinalVirtues} +\end{table} +</screen> </sect1> -<sect1 label="8.24" id="tabular"> +<sect1 label="8.23" id="tabular"> <title><literal>tabular</literal></title> + <indexterm role="fn"><primary>tabular environment</primary></indexterm> <indexterm role="cp"><primary>lines in tables</primary></indexterm> <indexterm role="cp"><primary>lining text up in tables</primary></indexterm> <para>Synopsis: </para> -<screen>\begin{tabular}[pos]{cols} -column 1 entry & column 2 entry ... & column n entry \\ -... +<screen>\begin{tabular}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} +column 1 entry &column 2 entry ... &column n entry \\ + ... \end{tabular} </screen> <para>or </para> -<screen>\begin{tabular*}{width}[pos]{cols} -column 1 entry & column 2 entry ... & column n entry \\ -... +<screen>\begin{tabular*}{<replaceable>width</replaceable>}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} +column 1 entry &column 2 entry ... &column n entry \\ + ... \end{tabular*} </screen> -<para>These environments produce a box consisting of a sequence of rows of -items, aligned vertically in columns. -</para> +<para>These environments produce a table, a box consisting of a sequence of +horizontal rows. Each row consists of items that are aligned vertically +in columns. This illustrates many of the features. +</para> +<screen>\begin{tabular}{l|l} + \textit{Player name} &\textit{Career home runs} \\ + \hline + Hank Aaron &755 \\ + Babe Ruth &714 +\end{tabular} +</screen> +<para>The vertical format of two left-aligned columns, with a vertical bar +between them, is specified in <literal>tabular</literal>’s argument <literal>{l|l}</literal>. +<indexterm role="fn"><primary>&</primary></indexterm> +Columns are separated with an ampersand <literal>&</literal>. A horizontal rule +between two rows is created with <literal>\hline</literal>. <indexterm role="fn"><primary>\\ for <literal>tabular</literal></primary></indexterm> -<para><literal>\\</literal> must be used to specify the end of each row of the table, -except for the last, where it is optional—unless an <literal>\hline</literal> -command (to put a rule below the table) follows. -</para> -<para>The mandatory and optional arguments consist of: +The end of each row is marked with a double backslash <literal>\\</literal>. +This <literal>\\</literal> is optional after the last row unless an <literal>\hline</literal> +command follows, to put a rule below the table. </para> -<variablelist><varlistentry><term><literal>width</literal> -</term><listitem><para>Specifies the width of the <literal>tabular*</literal> environment. There must be -rubber space between columns that can stretch to fill out the specified -width. +<para>The required and optional arguments to <literal>tabular</literal> consist of: </para> -</listitem></varlistentry><varlistentry><term><literal>pos</literal> -</term><listitem><para>Specifies the vertical position; default is alignment on the centre of -the environment. -</para> -<variablelist><varlistentry><term><literal>t</literal> -</term><listitem><para>align on top row -</para> -</listitem></varlistentry><varlistentry><term><literal>b</literal> -</term><listitem><para>align on bottom row -</para></listitem></varlistentry></variablelist> -</listitem></varlistentry><varlistentry><term><literal>cols</literal> -</term><listitem><para>Specifies the column formatting. It consists of a sequence of the -following specifiers, corresponding to the sequence of columns and -intercolumn material. +<variablelist><varlistentry><term><replaceable>width</replaceable> +</term><listitem><para>Required for <literal>tabular*</literal>, not allowed for <literal>tabular</literal>. Specifies +the width of the <literal>tabular*</literal> environment. The space between columns +should be rubber, as with <literal>@{\extracolsep{\fill}}</literal>, to allow +the table to stretch or shrink to make the specified width, or else you +are likely to get the <literal>Underfull \hbox (badness 10000) in alignment +..</literal> warning. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>pos</replaceable> +</term><listitem><para>Optional. Specifies the table’s vertical position. The default is to +align the table so its vertical center matches the baseline of the +surrounding text. There are two other possible alignments: <literal>t</literal> +aligns the table so its top row matches the baseline of the surrounding +text, and <literal>b</literal> aligns on the bottom row. +</para> +<para>This only has an effect if there is other text. In the common case of a +<literal>tabular</literal> alone in a <literal>center</literal> environment this option makes +no difference. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>cols</replaceable> +</term><listitem><para>Required. Specifies the formatting of columns. It consists of a +sequence of the following specifiers, corresponding to the types of +column and intercolumn material. </para> <variablelist><varlistentry><term><literal>l</literal> </term><listitem><para>A column of left-aligned items. @@ -2633,134 +3386,284 @@ intercolumn material. </listitem></varlistentry><varlistentry><term><literal>|</literal> </term><listitem><para>A vertical line the full height and depth of the environment. </para> -</listitem></varlistentry><varlistentry><term><literal>@{<replaceable>text</replaceable>}</literal> -</term><listitem><para>This inserts <replaceable>text</replaceable> in every row. An @-expression suppresses the -intercolumn space normally inserted between columns; any desired space -before the adjacent item must be included in <replaceable>text</replaceable>. +</listitem></varlistentry><varlistentry><term><literal>@{<replaceable>text or space</replaceable>}</literal> +</term><listitem><para>This inserts <replaceable>text or space</replaceable> at this location in every row. The +<replaceable>text or space</replaceable> material is typeset in LR mode. This text is +fragile (see <link linkend="_005cprotect">\protect</link>). </para> -<para>To insert commands that are automatically executed before a given -column, you have to load the <literal>array</literal> package and use the -<literal>>{...}</literal> specifier. -<!-- xx should fully explain array, tabularx, and all other base packages... --> +<para>This specifier is optional: unless you put in your own @-expression +then &latex;’s book, article, and report classes will put on either +side of each column a space of length <literal>\tabcolsep</literal>, which by +default is ‘<literal>6pt</literal>’. That is, by default adjacent columns are +separated by 12pt (so <literal>\tabcolsep</literal> is misleadingly-named since it +is not the separation between tabular columns). Also by default a space +of 6pt comes before the first column as well as after the final column, +unless you put a <literal>@{..}</literal> or <literal>|</literal> there. +</para> +<para>If you override the default and use an @-expression then you must +insert any desired space yourself, as in <literal>@{\hspace{1em}}</literal>. +</para> +<para>An empty expression <literal>@{}</literal> will eliminate the space, including +the space at the start or end, as in the example below where the tabular +lines need to lie on the left margin. +</para> +<screen>\begin{flushleft} + \begin{tabular}{@{}l} + .. + \end{tabular} +\end{flushleft} +</screen> +<para>This example shows text, a decimal point, between the columns, arranged +so the numbers in the table are aligned on that decimal point. </para> +<screen>\begin{tabular}{r@{$.$}l} + $3$ &$14$ \\ + $9$ &$80665$ +\end{tabular} +</screen> <indexterm role="fn"><primary>\extracolsep</primary></indexterm> -<para>An <literal>\extracolsep{wd}</literal> command in an @-expression causes an -extra space of width <literal>wd</literal> to appear to the left of all subsequent +<para>An <literal>\extracolsep{<replaceable>wd</replaceable>}</literal> command in an @-expression causes an +extra space of width <replaceable>wd</replaceable> to appear to the left of all subsequent columns, until countermanded by another <literal>\extracolsep</literal> command. -Unlike ordinary intercolumn space, this extra space is not suppressed -by an @-expression. An <literal>\extracolsep</literal> command can be used only -in an @-expression in the <literal>cols</literal> argument. +Unlike ordinary intercolumn space, this extra space is not suppressed by +an @-expression. An <literal>\extracolsep</literal> command can be used only in an +@-expression in the <literal>cols</literal> argument. Below, &latex; inserts the +right amount of intercolumn space to make the entire table 4 inches +wide. +</para> +<screen>\begin{center} + \begin{tabular*}{4in}{l@{\ \ldots\extracolsep{\fill}}l} + Seven times down, eight times up + &such is life! + \end{tabular*} +\end{center} +</screen> +<para>To insert commands that are automatically executed before a given +column, load the <literal>array</literal> package and use the <literal>>{...}</literal> +specifier. +<!-- xx should fully explain array, tabularx, and all other base packages... --> </para> </listitem></varlistentry><varlistentry><term><literal>p{<replaceable>wd</replaceable>}</literal> -</term><listitem><para>Produces a column with each item typeset in a parbox of width -<replaceable>wd</replaceable>, as if it were the argument of a -<literal>\parbox[t]{<replaceable>wd</replaceable>}</literal> command. However, a <literal>\\</literal> may not -appear in the item, except in the following situations: -</para> -<orderedlist numeration="arabic"><listitem><para>inside an environment like <literal>minipage</literal>, <literal>array</literal>, or <literal>tabular</literal>. -</para></listitem><listitem><para>inside an explicit <literal>\parbox</literal>. -</para></listitem><listitem><para>in the scope of a <literal>\centering</literal>, <literal>\raggedright</literal>, or <literal>\raggedleft</literal> -declaration. The latter declarations must appear inside braces or an -environment when used in a <literal>p</literal>-column element. -</para></listitem></orderedlist> +</term><listitem><para>Each item in the column is typeset in a parbox of width <replaceable>wd</replaceable>. +</para> +<para>Note that a line break double backslash <literal>\\</literal> may not appear in the +item, except inside an environment like <literal>minipage</literal>, <literal>array</literal>, +or <literal>tabular</literal>, or inside an explicit <literal>\parbox</literal>, or in the scope +of a <literal>\centering</literal>, <literal>\raggedright</literal>, or <literal>\raggedleft</literal> +declaration (when used in a <literal>p</literal>-column element these declarations +must appear inside braces, as with <literal>{\centering .. \\ +..}</literal>). Otherwise &latex; will misinterpret the double backslash as +ending the row. +</para> </listitem></varlistentry><varlistentry><term><literal>*{<replaceable>num</replaceable>}{<replaceable>cols</replaceable>}</literal> </term><listitem><para>Equivalent to <replaceable>num</replaceable> copies of <replaceable>cols</replaceable>, where <replaceable>num</replaceable> is a -positive integer and <replaceable>cols</replaceable> is any list of column-specifiers, -which may contain another <literal>*-expression</literal>. -</para> +positive integer and <replaceable>cols</replaceable> is a list of specifiers. Thus +<literal>\begin{tabular}{|*{3}{l|r}|}</literal> is equivalent to +<literal>\begin{tabular}{|l|rl|rl|r|}</literal>. Note that <replaceable>cols</replaceable> may +contain another <literal>*-expression</literal>. +</para> </listitem></varlistentry></variablelist></listitem></varlistentry></variablelist> <para>Parameters that control formatting: <!-- xx defaults, own node (xref from array)? --> </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\arrayrulewidth</primary></indexterm><literal>\arrayrulewidth</literal> -</term><listitem><para>Thickness of the rule created by <literal>|</literal>, <literal>\hline</literal>, and -<literal>\vline</literal> in the <literal>tabular</literal> and <literal>array</literal> environments; the -default is ‘<literal>.4pt</literal>’. +</term><listitem><para>A length that is the thickness of the rule created by <literal>|</literal>, +<literal>\hline</literal>, and <literal>\vline</literal> in the <literal>tabular</literal> and <literal>array</literal> +environments. The default is ‘<literal>.4pt</literal>’. Change it as in +<literal>\setlength{\arrayrulewidth}{0.8pt}</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arraystretch</primary></indexterm><literal>\arraystretch</literal> -</term><listitem><para>Scaling of spacing between rows in the <literal>tabular</literal> and <literal>array</literal> -environments; default is ‘<literal>1</literal>’, for no scaling. +</term><listitem><para>A factor by which the spacing between rows in the <literal>tabular</literal> and +<literal>array</literal> environments is multiplied. The default is ‘<literal>1</literal>’, for +no scaling. Change it as <literal>\renewcommand{\arraystretch}{1.2}</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\doublerulesep</primary></indexterm><literal>\doublerulesep</literal> -</term><listitem><para>Horizontal distance between the vertical rules produced by <literal>||</literal> -in the <literal>tabular</literal> and <literal>array</literal> environments; default is ‘<literal>2pt</literal>’. +</term><listitem><para>A length that is the distance between the vertical rules produced by the +<literal>||</literal> specifier. The default is ‘<literal>2pt</literal>’. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tabcolsep</primary></indexterm><literal>\tabcolsep</literal> -</term><listitem><para>Half the width of the space between columns; default is ‘<literal>6pt</literal>’. +</term><listitem><para>A length that is half of the space between columns. The default is +‘<literal>6pt</literal>’. Change it with <literal>\setlength</literal>. </para> </listitem></varlistentry></variablelist> -<para>The following commands can be used inside a <literal>tabular</literal> -environment: +<para>The following commands can be used inside the body of a <literal>tabular</literal> +environment, the first two inside an entry and the second two between +lines: </para> -<sect2 label="8.24.1" id="_005cmulticolumn"> +<sect2 label="8.23.1" id="_005cmulticolumn"> <title><literal>\multicolumn</literal></title> + <indexterm role="fn"><primary>\multicolumn</primary></indexterm> <para>Synopsis: -</para><screen>\multicolumn{<replaceable>cols</replaceable>}{<replaceable>pos</replaceable>}{<replaceable>text</replaceable>} -</screen> -<para>The <literal>\multicolumn</literal> command makes an entry that spans several -columns. The first mandatory argument, <replaceable>cols</replaceable>, specifies the -number of columns to span. The second mandatory argument, <replaceable>pos</replaceable>, -specifies the formatting of the entry; <literal>c</literal> for centered, <literal>l</literal> -for flushleft, <literal>r</literal> for flushright. The third mandatory argument, -<replaceable>text</replaceable>, specifies what text to put in the entry. -</para> -<para>Here’s an example showing two columns separated by an en-dash; -<literal>\multicolumn</literal> is used for the heading: -</para> -<screen>\begin{tabular}{r@{--}l} -\multicolumn{2}{c}{\bf Unicode}\cr - 0x80&0x7FF \cr - 0x800&0xFFFF \cr -0x10000&0x1FFFF \cr +</para> +<screen>\multicolumn{<replaceable>numcols</replaceable>}{<replaceable>cols</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>Make an <literal>array</literal> or <literal>tabular</literal> entry that spans several columns. +The first argument <replaceable>numcols</replaceable> gives the number of columns to span. +The second argument <replaceable>cols</replaceable> specifies the formatting of the entry, +with <literal>c</literal> for centered, <literal>l</literal> for flush left, or <literal>r</literal> for +flush right. The third argument <replaceable>text</replaceable> gives the contents of that +entry. +</para> +<para>In this example, in the first row, the second and third columns are +spanned by the single heading ‘<literal>Name</literal>’. +</para> +<screen>\begin{tabular}{lccl} + \textit{ID} &\multicolumn{2}{c}{\textit{Name}} &\textit{Age} \\ \hline % row one + 978-0-393-03701-2 &O'Brian &Patrick &55 \\ % row two + .. +\end{tabular} +</screen> +<para>What counts as a column is: the column format specifier for the +<literal>array</literal> or <literal>tabular</literal> environment is broken into parts, where +each part (except the first) begins with <literal>l</literal>, <literal>c</literal>, <literal>r</literal>, +or <literal>p</literal>. So from <literal>\begin{tabular}{|r|ccp{1.5in}|}</literal> +the parts are <literal>|r|</literal>, <literal>c</literal>, <literal>c</literal>, +and <literal>p{1.5in}|</literal>. +</para> +<para>The <replaceable>cols</replaceable> argument overrides the <literal>array</literal> or <literal>tabular</literal> +environment’s intercolumn area default adjoining this multicolumn +entry. To affect that area, this argument can contain vertical bars +<literal>|</literal> indicating the placement of vertical rules, and <literal>@{..}</literal> +expressions. Thus if <replaceable>cols</replaceable> is ‘<literal>|c|</literal>’ then this multicolumn +entry will be centered and a vertical rule will come in the intercolumn +area before it and after it. This table details the exact behavior. +</para> +<screen>\begin{tabular}{|cc|c|c|} + \multicolumn{1}{r}{w} % entry one + &\multicolumn{1}{|r|}{x} % entry two + &\multicolumn{1}{|r}{y} % entry three + &z % entry four +\end{tabular} +</screen><para>Before the first entry the output will not have a vertical rule because +the <literal>\multicolumn</literal> has the <replaceable>cols</replaceable> specifier ‘<literal>r</literal>’ with no +initial vertical bar. Between entry one and entry two there will be a +vertical rule; although the first <replaceable>cols</replaceable> does not have an ending +vertical bar, the second <replaceable>cols</replaceable> does have a starting one. Between +entry two and entry three there is a single vertical rule; despite that +the <replaceable>cols</replaceable> in both of the surrounding <literal>multicolumn</literal>’s call for +a vertical rule, you only get one rule. Between entry three and entry +four there is no vertical rule; the default calls for one but the +<replaceable>cols</replaceable> in the entry three <literal>\multicolumn</literal> leaves it out, and +that takes precedence. Finally, following entry four there is a +vertical rule because of the default. +</para> +<para>The number of spanned columns <replaceable>numcols</replaceable> can be 1. Besides giving +the ability to change the horizontal alignment, this also is useful to +override for one row the <literal>tabular</literal> definition’s default intercolumn +area specification, including the placement of vertical rules. +</para> +<para>In the example below, in the <literal>tabular</literal> definition the first column +is specified to default to left justified but in the first row the entry +is centered with <literal>\multicolumn{1}{c}{\textsc{Period}}</literal>. +Also in the first row, the second and third columns are spanned by a +single entry with <literal>\multicolumn{2}{c}{\textsc{Span}}</literal>, +overriding the specification to center those two columns on the page +range en-dash. +</para> +<screen>\begin{tabular}{l|r@{--}l} + \multicolumn{1}{c}{\textsc{Period}} + &multicolumn{2}{c}{\textsc{Span}} \\ \hline + Baroque &1600 &1760 \\ + Classical &1730 &1820 \\ + Romantic &1780 &1910 \\ + Impressionistic &1875 &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’s +<literal>\multicolumn</literal> commands, no rule appears in the first row. +</para> + +</sect2> +<sect2 label="8.23.2" id="_005cvline"> +<title><literal>\vline</literal></title> + +<indexterm role="fn"><primary>\vline</primary></indexterm> + +<para>Draw a vertical line in a <literal>tabular</literal> or <literal>array</literal> environment +extending the full height and depth of an entry’s row. Can also be used +in an @-expression, although its synonym vertical bar <literal>|</literal> is +more common. This command is rarely used; typically a table’s vertical +lines are specified in <literal>tabular</literal>’s <replaceable>cols</replaceable> argument and +overriden as needed with <literal>\multicolumn</literal>. +</para> +<para>This example illustrates some pitfalls. In the first line’s second +entry the <literal>\hfill</literal> moves the <literal>\vline</literal> to the left edge of the +cell. But that is different than putting it halfway between the two +columns, so in that row between the first and second columns there are +two vertical rules, with the one from the <literal>{c|cc}</literal> specifier +coming before the one produced by the <literal>\vline\hfill</literal>. In contrast, +the first line’s third entry shows the usual way to put a vertical bar +between two columns. In the second line, the <literal>ghi</literal> is the widest +entry in its column so in the <literal>\vline\hfill</literal> the <literal>\hfill</literal> has +no effect and the vertical line in that entry appears immediately next +to the <literal>g</literal>, with no whitespace. +</para> +<screen>\begin{tabular}{c|cc} + x &\vline\hfill y &\multicolumn{1}{|r}{z} \\ + abc &def &\vline\hfill ghi \end{tabular} </screen> </sect2> -<sect2 label="8.24.2" id="_005ccline"> +<sect2 label="8.23.3" id="_005ccline"> <title><literal>\cline</literal></title> + <indexterm role="fn"><primary>\cline</primary></indexterm> <para>Synopsis: </para> <screen>\cline{<replaceable>i</replaceable>-<replaceable>j</replaceable>} </screen> -<para>The <literal>\cline</literal> command draws horizontal lines across the columns -specified, beginning in column <replaceable>i</replaceable> and ending in column <replaceable>j</replaceable>, -which are specified in the mandatory argument. -</para> +<para>Draw a horizontal rule in an <literal>array</literal> or <literal>tabular</literal> environment +beginning in column <replaceable>i</replaceable> and ending in column <replaceable>j</replaceable>. The +dash <literal>-</literal> must appear in the mandatory argument. To span a +single column use the number twice. +</para> +<para>This example puts two horizontal lines between the first and second +rows, one line in the first column only, and the other spanning the +third and fourth columns. The two lines are side-by-side, at the same +height. +</para> +<screen>\begin{tabular}{llrr} + a &b &c &d \\ \cline{1-1} \cline{3-4} + e &f &g &h +\end{tabular} +</screen> </sect2> -<sect2 label="8.24.3" id="_005chline"> +<sect2 label="8.23.4" id="_005chline"> <title><literal>\hline</literal></title> + <indexterm role="fn"><primary>\hline</primary></indexterm> -<para>The <literal>\hline</literal> command draws a horizontal line the width of the -enclosing <literal>tabular</literal> or <literal>array</literal> environment. It’s most -commonly used to draw a line at the top, bottom, and between the rows -of a table. +<para>Draws a horizontal line the width of the enclosing <literal>tabular</literal> or +<literal>array</literal> environment. It’s most commonly used to draw a line at the +top, bottom, and between the rows of a table. </para> - -</sect2> -<sect2 label="8.24.4" id="_005cvline"> -<title><literal>\vline</literal></title> -<indexterm role="fn"><primary>\vline</primary></indexterm> - -<para>The <literal>\vline</literal> command will draw a vertical line extending the full -height and depth of its row. An <literal>\hfill</literal> command can be used to -move the line to the edge of the column. It can also be used in an -@-expression. +<para>In this example the top of the table has two horizontal rules, one above +the other, that span both columns. The bottom of the table has a single +rule spanning both columns. Because of the <literal>\hline</literal>, the +<literal>tabular</literal> second row’s line ending double backslash <literal>\\</literal> +is required. </para> +<screen>\begin{tabular}{ll} \hline\hline + Baseball &Red Sox \\ + Basketball &Celtics \\ \hline +\end{tabular} +</screen> </sect2> </sect1> -<sect1 label="8.25" id="thebibliography"> +<sect1 label="8.24" id="thebibliography"> <title><literal>thebibliography</literal></title> -<indexterm role="fn"><primary>thebibliography</primary></indexterm> +<indexterm role="fn"><primary>thebibliography environment</primary></indexterm> <indexterm role="cp"><primary>bibliography, creating (manually)</primary></indexterm> <para>Synopsis: @@ -2788,13 +3691,14 @@ less than 10 references, <literal>99</literal> for ones with less than 100, etc. </para> -<sect2 label="8.25.1" id="_005cbibitem"> +<sect2 label="8.24.1" id="_005cbibitem"> <title><literal>\bibitem</literal></title> <indexterm role="fn"><primary>\bibitem</primary></indexterm> <para>Synopsis: -</para><screen>\bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key</replaceable>} +</para> +<screen>\bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key</replaceable>} </screen> <para>The <literal>\bibitem</literal> command generates an entry labelled by <replaceable>label</replaceable>. If the <replaceable>label</replaceable> argument is missing, a number is @@ -2811,14 +3715,14 @@ associated label. </para> </sect2> -<sect2 label="8.25.2" id="_005ccite"> +<sect2 label="8.24.2" id="_005ccite"> <title><literal>\cite</literal></title> <indexterm role="fn"><primary>\cite</primary></indexterm> <para>Synopsis: </para> -<screen>\cite[<replaceable>subcite</replaceable>]{<replaceable>keys</replaceable> +<screen>\cite[<replaceable>subcite</replaceable>]{<replaceable>keys</replaceable>} </screen> <para>The <replaceable>keys</replaceable> argument is a list of one or more citation keys, separated by commas. This command generates an in-text citation to @@ -2831,18 +3735,19 @@ citation. For example, <literal>\cite[p.~314]{knuth}</literal> might produce </para> </sect2> -<sect2 label="8.25.3" id="_005cnocite"> +<sect2 label="8.24.3" id="_005cnocite"> <title><literal>\nocite</literal></title> + <indexterm role="fn"><primary>\nocite</primary></indexterm> -<para><literal>\nocite{key_list}</literal> +<para><literal>\nocite{<replaceable>keys</replaceable>}</literal> </para> -<para>The <literal>\nocite</literal> command produces no text, but writes <literal>key_list</literal>, -which is a list of one or more citation keys, on the <filename>.aux</filename> file. +<para>The <literal>\nocite</literal> command produces no text, but writes <replaceable>keys</replaceable>, +which is a list of one or more citation keys, to the <filename>.aux</filename> file. </para> </sect2> -<sect2 label="8.25.4" id="Using-BibTeX"> +<sect2 label="8.24.4" id="Using-BibTeX"> <title>Using Bib&tex;</title> <indexterm role="cp"><primary>using Bib&tex;</primary></indexterm> @@ -2889,7 +3794,7 @@ Bib&tex; format. Only the entries referred to via <literal>\cite</literal> and </sect2> </sect1> -<sect1 label="8.26" id="theorem"> +<sect1 label="8.25" id="theorem"> <title><literal>theorem</literal></title> <indexterm role="fn"><primary>theorem environment</primary></indexterm> @@ -2908,7 +3813,7 @@ possibilities for <replaceable>n</replaceable> are described under <literal>\new </para> </sect1> -<sect1 label="8.27" id="titlepage"> +<sect1 label="8.26" id="titlepage"> <title><literal>titlepage</literal></title> <indexterm role="fn"><primary>titlepage environment</primary></indexterm> @@ -2932,7 +3837,7 @@ produce a standard title page without a <literal>titlepage</literal> environment </para> </sect1> -<sect1 label="8.28" id="verbatim"> +<sect1 label="8.27" id="verbatim"> <title><literal>verbatim</literal></title> <indexterm role="fn"><primary>verbatim environment</primary></indexterm> @@ -2957,7 +3862,7 @@ effect that they would on a typewriter. <para>The <literal>verbatim</literal> uses a monospaced typewriter-like font (<literal>\tt</literal>). </para> -<sect2 label="8.28.1" id="_005cverb"> +<sect2 label="8.27.1" id="_005cverb"> <title><literal>\verb</literal></title> <indexterm role="fn"><primary>\verb</primary></indexterm> @@ -2981,7 +3886,7 @@ verbatim text. The delimiter must not appear in <replaceable>literal-text</repl </sect2> </sect1> -<sect1 label="8.29" id="verse"> +<sect1 label="8.28" id="verse"> <title><literal>verse</literal></title> <indexterm role="fn"><primary>verse environment</primary></indexterm> @@ -3009,6 +3914,7 @@ stanzas. </chapter> <chapter label="9" id="Line-breaking"> <title>Line breaking</title> + <indexterm role="cp"><primary>line breaking</primary></indexterm> <indexterm role="cp"><primary>breaking lines</primary></indexterm> @@ -3017,30 +3923,52 @@ translate your input file into a sequence of glyphs and spaces. To produce a printed document, this sequence must be broken into lines (and these lines must be broken into pages). </para> -<para>&latex; usually does the line (and page) breaking for you, but in -some environments, you do the line breaking yourself with the -<literal>\\</literal> command, and you can always manually force breaks. +<para>&latex; usually does the line (and page) breaking in the text body for +you but in some environments you manually force line breaks. </para> <sect1 label="9.1" id="_005c_005c"> -<title><literal>\\</literal>[*][<replaceable>morespace</replaceable>]</title> +<title><literal>\\</literal></title> + <indexterm role="fn"><primary>\\ force line break</primary></indexterm> <indexterm role="cp"><primary>new line, starting</primary></indexterm> <indexterm role="cp"><primary>line break, forcing</primary></indexterm> -<para>The <literal>\\</literal> command tells &latex; to start a new line. It has an -optional argument, <replaceable>morespace</replaceable>, that specifies how much extra -vertical space is to be inserted before the next line. This can be a -negative amount. +<para>Synopsis: </para> -<para>The <literal>\\*</literal> command is the same as the ordinary <literal>\\</literal> command -except that it tells &latex; not to start a new page after the line. +<screen>\\[<replaceable>morespace</replaceable>] +</screen> +<para>or </para> +<screen>\\*[<replaceable>morespace</replaceable>] +</screen> +<para>Start a new line. The optional argument <replaceable>morespace</replaceable> specifies extra +vertical space to be insert before the next line. This can be a +negative length. The text before the break is set at its normal length, +that is, it is not stretched to fill out the line width. +</para> +<para>Explicit line breaks in the text body are unusual in &latex;. In +particular, to start a new paragraph instead leave a blank line. This +command is mostly used outside of the main flow of text such as in +a <literal>tabular</literal> or <literal>array</literal> environment. +</para> +<para>Under ordinary circumstances (e.g., outside of a <literal>p{..}</literal> column +in a <literal>tabular</literal> environment) the <literal>\newline</literal> command is a synonym for +<literal>\\</literal> (see <link linkend="_005cnewline">\newline</link>). +</para> +<para>In addition to starting a new line, the starred form <literal>\\*</literal> tells +&latex; not to start a new page between the two lines, by issuing a +<literal>\nobreak</literal>. +</para> +<screen>\title{My story: \\[0.25in] + a tale of woe} +</screen> </sect1> <sect1 label="9.2" id="_005cobeycr-_0026-_005crestorecr"> <title><literal>\obeycr</literal> & <literal>\restorecr</literal></title> + <indexterm role="fn"><primary>\obeycr</primary></indexterm> <indexterm role="fn"><primary>\restorecr</primary></indexterm> <indexterm role="cp"><primary>new line, output as input</primary></indexterm> @@ -3056,17 +3984,33 @@ in the output. </sect1> <sect1 label="9.3" id="_005cnewline"> <title><literal>\newline</literal></title> + <indexterm role="fn"><primary>\newline</primary></indexterm> <indexterm role="cp"><primary>new line, starting (paragraph mode)</primary></indexterm> -<para>The <literal>\newline</literal> command breaks the line at the present point, with -no stretching of the text before it. It can only be used in paragraph -mode. +<para>In ordinary text this is equivalent to double-backslash (see <link linkend="_005c_005c">\\</link>); it +breaks a line, with no stretching of the text before it. +</para> +<para>Inside a <literal>tabular</literal> or <literal>array</literal> environment, in a column with a +specifier producing a paragraph box, like typically <literal>p{..}</literal>, +<literal>\newline</literal> will insert a line break inside of the column, that is, +it does not break the entire row. To break the entire row use <literal>\\</literal> +or its equivalent <literal>\tabularnewline</literal>. +</para> +<para>This will print ‘<literal>Name:</literal>’ and ‘<literal>Address:</literal>’ as two lines in a +single cell of the table. +</para> +<screen>\begin{tabular}{p{1in}{\hspace{2in}}p{1in}} + Name: \newline Address: &Date: \\ \hline +\end{tabular} +</screen> +<para>The ‘<literal>Date:</literal>’ will be baseline-aligned with ‘<literal>Name:</literal>’. </para> </sect1> <sect1 label="9.4" id="_005c_002d-_0028hyphenation_0029"> <title><literal>\-</literal> (discretionary hyphen)</title> + <indexterm role="fn"><primary>\- (hyphenation)</primary></indexterm> <indexterm role="cp"><primary>hyphenation, forcing</primary></indexterm> @@ -3081,10 +4025,10 @@ hyphenated at those points and not at any of the hyphenation points that &latex; might otherwise have chosen. </para> - </sect1> <sect1 label="9.5" id="_005cfussy"> <title><literal>\fussy</literal></title> + <indexterm role="fn"><primary>\fussy</primary></indexterm> <para>The declaration <literal>\fussy</literal> (which is the default) makes &tex; @@ -3099,6 +4043,8 @@ words, at the cost of an occasional overfull box. <sect1 label="9.6" id="_005csloppy"> <title><literal>\sloppy</literal></title> +<indexterm role="fn"><primary>\sloppy</primary></indexterm> + <para>The declaration <literal>\sloppy</literal> makes &tex; less fussy about line breaking. This will avoid overfull boxes, at the cost of loose interword spacing. @@ -3109,6 +4055,7 @@ interword spacing. </sect1> <sect1 label="9.7" id="_005chyphenation"> <title><literal>\hyphenation</literal></title> + <indexterm role="fn"><primary>\hyphenation</primary></indexterm> <indexterm role="cp"><primary>hyphenation, defining</primary></indexterm> @@ -3129,6 +4076,7 @@ misses the hyphenations in these words): </sect1> <sect1 label="9.8" id="_005clinebreak-_0026-_005cnolinebreak"> <title><literal>\linebreak</literal> & <literal>\nolinebreak</literal></title> + <indexterm role="fn"><primary>\linebreak</primary></indexterm> <indexterm role="fn"><primary>\nolinebreak</primary></indexterm> <indexterm role="cp"><primary>line breaks, forcing</primary></indexterm> @@ -3153,6 +4101,7 @@ from a demand to a request. The <replaceable>priority</replaceable> must be a n </chapter> <chapter label="10" id="Page-breaking"> <title>Page breaking</title> + <indexterm role="cp"><primary>page breaking</primary></indexterm> <indexterm role="cp"><primary>breaking pages</primary></indexterm> @@ -3169,36 +4118,41 @@ but sometimes you may want to influence the breaks. <indexterm role="cp"><primary>starting on a right-hand page</primary></indexterm> <para>The <literal>\cleardoublepage</literal> command ends the current page and causes all -figures and tables that have so far appeared in the input to be printed. -In a two-sided printing style, it also makes the next page a right-hand -(odd-numbered) page, producing a blank page if necessary. +the pending floating figures and tables that have so far appeared in the +input to be printed. In a two-sided printing style, it also makes the +next page a right-hand (odd-numbered) page, producing a blank page if +necessary. </para> </sect1> <sect1 label="10.2" id="_005cclearpage"> <title><literal>\clearpage</literal></title> + <indexterm role="fn"><primary>\clearpage</primary></indexterm> <indexterm role="cp"><primary>flushing floats and starting a page</primary></indexterm> <indexterm role="cp"><primary>starting a new page and clearing floats</primary></indexterm> -<para>The <literal>\clearpage</literal> command ends the current page and causes all -figures and tables that have so far appeared in the input to be printed. +<para>The <literal>\clearpage</literal> command ends the current page and causes all the +pending floating figures and tables that have so far appeared in the +input to be printed. </para> </sect1> <sect1 label="10.3" id="_005cnewpage"> <title><literal>\newpage</literal></title> + <indexterm role="fn"><primary>\newpage</primary></indexterm> <indexterm role="cp"><primary>new page, starting</primary></indexterm> <indexterm role="cp"><primary>starting a new page</primary></indexterm> <para>The <literal>\newpage</literal> command ends the current page, but does not clear -floats (see <literal>\clearpage</literal> above). +floats (see <link linkend="_005cclearpage">\clearpage</link>). </para> </sect1> <sect1 label="10.4" id="_005cenlargethispage"> <title><literal>\enlargethispage</literal></title> + <indexterm role="fn"><primary>\enlargethispage</primary></indexterm> <indexterm role="cp"><primary>enlarge current page</primary></indexterm> @@ -3207,7 +4161,7 @@ floats (see <literal>\clearpage</literal> above). <para><literal>\enlargethispage*{size}</literal> </para> <para>Enlarge the <literal>\textheight</literal> for the current page by the specified -amount; e.g. <literal>\enlargethispage{\baselineskip}</literal> will allow one +amount; e.g., <literal>\enlargethispage{\baselineskip}</literal> will allow one additional line. </para> <para>The starred form tries to squeeze the material together on the page as @@ -3218,6 +4172,7 @@ much as possible. This is normally used together with an explicit </sect1> <sect1 label="10.5" id="_005cpagebreak-_0026-_005cnopagebreak"> <title><literal>\pagebreak</literal> & <literal>\nopagebreak</literal></title> + <indexterm role="fn"><primary>\pagebreak</primary></indexterm> <indexterm role="fn"><primary>\nopagebreak</primary></indexterm> <indexterm role="cp"><primary>page break, forcing</primary></indexterm> @@ -3243,88 +4198,246 @@ insistent the request is. </chapter> <chapter label="11" id="Footnotes"> <title>Footnotes</title> + <indexterm role="cp"><primary>footnotes, creating</primary></indexterm> -<para>Footnotes can be produced in one of two ways. They can be produced -with one command, the <literal>\footnote</literal> command. They can also be -produced with two commands, the <literal>\footnotemark</literal> and the -<literal>\footnotetext</literal> commands. +<para>Place a numbered footnote at the bottom of the current page, as here. +</para> +<screen>Noël Coward quipped that having to read a footnote is like having +to go downstairs to answer the door, while in the midst of making +love.\footnote{I wouldn't know, I don't read footnotes.} +</screen> +<para>You can place multiple footnotes on a page. If the text becomes too long +it will flow to the next page. +</para> +<para>You can also produce footnotes by combining the <literal>\footnotemark</literal> and +the <literal>\footnotetext</literal> commands, which is useful in special +circumstances. +</para> +<para>To make bibliographic references come out as footnotes you need to +include a bibliographic style with that behavior. </para> <sect1 label="11.1" id="_005cfootnote"> <title><literal>\footnote</literal></title> + <indexterm role="fn"><primary>\footnote</primary></indexterm> <para>Synopsis: </para> <screen>\footnote[<replaceable>number</replaceable>]{<replaceable>text</replaceable>} </screen> -<para>The <literal>\footnote</literal> command places the numbered footnote <replaceable>text</replaceable> -at the bottom of the current page. The optional argument <replaceable>number</replaceable> -changes the default footnote number. +<para>Place a numbered footnote <replaceable>text</replaceable> at the bottom of the current page. +</para> +<screen>There are over a thousand footnotes in Gibbon's +\textit{Decline and Fall of the Roman Empire}.\footnote{After +reading an early version with endnotes David Hume complained, +``One is also plagued with his Notes, according to the present Method +of printing the Book'' and suggested that they ``only to be printed +at the Margin or the Bottom of the Page.''} +</screen> +<para>The optional argument <replaceable>number</replaceable> allows you to specify the footnote +number. If you use this option then the footnote number counter is not +incremented, and if you do not use it then the counter is incremented. </para> -<para>This command can only be used in outer paragraph mode; i.e., you -cannot use it in sectioning commands like <literal>\chapter</literal>, in figures, -tables or in a <literal>tabular</literal> environment. (See following sections.) +<indexterm role="cp"><primary>footnotes, symbols instead of numbers</primary></indexterm> +<indexterm role="fn"><primary>\fnsymbol, and footnotes</primary></indexterm> +<indexterm role="fn"><primary>\@fnsymbol</primary></indexterm> +<para>Change how &latex; shows the footnote counter with something like +<literal>\renewcommand{\thefootnote}{\fnsymbol{footnote}}</literal>, which +uses a sequence of symbols (see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman +\fnsymbol</link>). To make this change global put that in the preamble. If +you make the change local then you may want to reset the counter with +<literal>\setcounter{footnote}{0}</literal>. By default &latex; uses arabic +numbers. +</para> +<para>&latex;’s default puts many restrictions on where you can use a +<literal>\footnote</literal>; for instance, you cannot use it in an argument to a +sectioning command such as <literal>\chapter</literal> (it can only be used in outer +paragraph mode). There are some workarounds; see following sections. <!-- xx mention packages that fix this --> </para> +<indexterm role="cp"><primary>Footnotes, in a minipage</primary></indexterm> +<indexterm role="cp"><primary>mpfootnote counter</primary></indexterm> +<para>In a <literal>minipage</literal> environment the <literal>\footnote</literal> +command uses the <literal>mpfootnote</literal> counter instead of the +<literal>footnote</literal> counter, so they are numbered independently. They are +shown at the bottom of the environment, not at the bottom of the page. +And by default they are shown alphabetically. See <link linkend="minipage">minipage</link>. +</para> </sect1> <sect1 label="11.2" id="_005cfootnotemark"> <title><literal>\footnotemark</literal></title> + <indexterm role="fn"><primary>\footnotemark</primary></indexterm> -<para>With no optional argument, the <literal>\footnotemark</literal> command puts the -current footnote number in the text. This command can be used in -inner paragraph mode. You give the text of the footnote separately, -with the <literal>\footnotetext</literal> command. +<para>Synopsis, one of: </para> -<para>This command can be used to produce several consecutive footnote -markers referring to the same footnote with -</para> -<screen>\footnotemark[\value{footnote}] +<screen>\footnotemark +\footnotemark[<replaceable>number</replaceable>] +</screen> +<para>Put the current footnote number in the +text. (See <link linkend="_005cfootnotetext">\footnotetext</link> for giving the text of the footnote +separately.) The version with the optional argument <replaceable>number</replaceable> uses +that number to determine the mark printed. This command can be used in +inner paragraph mode. +</para> +<para>This example gives the same institutional affiliation to both the first +and third authors (<literal>\thanks</literal> is a version of <literal>footnote</literal>). +</para> +<screen>\title{A Treatise on the Binomial Theorem} +\author{J Moriarty\thanks{University of Leeds} + \and A C Doyle\thanks{Durham University} + \and S Holmes\footnotemark[1]} +\begin{document} +\maketitle +</screen> +<para>If you use <literal>\footnotemark</literal> without the optional argument then it +increments the footnote counter but if you use the optional <replaceable>number</replaceable> +then it does not. This produces several consecutive footnote markers +referring to the same footnote. +</para> +<screen>The first theorem\footnote{Due to Gauss.} +and the second theorem\footnotemark[\value{footnote}] +and the third theorem.\footnotemark[\value{footnote}] </screen> -<para>after the first <literal>\footnote</literal> command. -</para> </sect1> <sect1 label="11.3" id="_005cfootnotetext"> <title><literal>\footnotetext</literal></title> + <indexterm role="fn"><primary>\footnotetext</primary></indexterm> -<para>Synopsis: +<para>Synopsis, one of: </para> -<screen>\footnotetext[<replaceable>number</replaceable>]{<replaceable>text</replaceable>} +<screen>\footnotetext{<replaceable>text</replaceable>} +\footnotetext[<replaceable>number</replaceable>]{<replaceable>text</replaceable>} </screen> -<para>The <literal>\footnotetext</literal> command places <replaceable>text</replaceable> at the bottom of -the page as a footnote. This command can come anywhere after the -<literal>\footnotemark</literal> command. The <literal>\footnotetext</literal> command must -appear in outer paragraph mode. +<para>Place <replaceable>text</replaceable> at the bottom of the page as a footnote. This command +can come anywhere after the <literal>\footnotemark</literal> command. The optional +argument <replaceable>number</replaceable> changes the displayed footnote number. The +<literal>\footnotetext</literal> command must appear in outer paragraph mode. </para> -<para>The optional argument <replaceable>number</replaceable> changes the default footnote number. + +</sect1> +<sect1 label="11.4" id="Footnotes-in-a-table"> +<title>Footnotes in a table</title> + +<indexterm role="cp"><primary>Footnotes, in a table</primary></indexterm> + +<para>Inside a <literal>table</literal> environment the <literal>\footnote</literal> command does not +work. For instance, if the code below appears on its own then the +footnote simply disappears; there is a footnote mark in the table cell +but nothing is set at the bottom of the page. </para> +<screen>\begin{center} + \begin{tabular}{l|l} + \textsc{Ship} &\textsc{Book} \\ \hline + \textit{HMS Sophie} &Master and Commander \\ + \textit{HMS Polychrest} &Post Captain \\ + \textit{HMS Lively} &Post Captain \\ + \textit{HMS Surprise} &A number of books\footnote{Starting with HMS Surprise.} + \end{tabular} +\end{center} +</screen> +<para>The solution is to surround the <literal>tabular</literal> environment with a +<literal>minipage</literal> environment, as here (see <link linkend="minipage">minipage</link>). +</para> +<screen>\begin{center} + \begin{minipage}{.5\textwidth} + .. tabular material .. + \end{minipage} +\end{center} +</screen> +<para>The same technique will work inside a floating <literal>table</literal> environment +(see <link linkend="table">table</link>). To get the footnote at the bottom of the page use the +<filename>tablefootnote</filename> package, as illustrated in this example. If you +put <literal>\usepackage{tablefootnote}</literal> in the preamble and use the code +shown then the footnote appears at the bottom and is numbered in +sequence with other footnotes. +</para> +<screen>\begin{table} + \centering + \begin{tabular}{l|l} + \textsc{Date} &\textsc{Campaign} \\ \hline + 1862 &Fort Donelson \\ + 1863 &Vicksburg \\ + 1865 &Army of Northern Virginia\footnote{Ending the war.} + \end{tabular} + \caption{Forces captured by US Grant} +\end{table} +</screen> </sect1> -<sect1 label="11.4" id="Symbolic-footnotes"> -<title>Symbolic footnotes</title> +<sect1 label="11.5" id="Footnotes-in-section-headings"> +<title>Footnotes in section headings</title> -<indexterm role="cp"><primary>footnotes, symbolic instead of numbered</primary></indexterm> -<para>If you want to use symbols for footnotes, rather than increasing -numbers, redefine <literal>\thefootnote</literal> like this: +<para>Putting a footnote in a section heading </para> -<screen>\renewcommand{\thefootnote}{\fnsymbol{footnote}} +<screen>\section{Full sets\protect\footnote{This material is due to R~Jones.}} </screen> -<indexterm role="fn"><primary>\fnsymbol, and footnotes</primary></indexterm> -<indexterm role="fn"><primary>\@fnsymbol</primary></indexterm> -<para>The <literal>\fnsymbol</literal> command produces a predefined series of symbols -(see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>). If you want to -use a different symbol as your footnote mark, you’ll need to also -redefine <literal>\@fnsymbol</literal>. +<para>causes the footnote to appear both at the bottom of the page where the +section starts and at the bottom of the table of contents page. To have +it not appear on the table of contents use the package <filename>footmisc</filename> +with the <literal>stable</literal> option. +</para> +<screen>\usepackage[stable]{footmisc} + .. +\begin{document} + .. +\section{Full sets\footnote{This material is due to R~Jones.}} +</screen> +<para>Note that the <literal>\protect</literal> is gone; putting it in causes the +footnote to reappear on the table of contents. </para> </sect1> -<sect1 label="11.5" id="Footnote-parameters"> +<sect1 label="11.6" id="Footnotes-of-footnotes"> +<title>Footnotes of footnotes</title> + +<para>Particularly in the humanities, authors can have multiple classes of +footnotes, including having footnotes of footnotes. The package +<filename>bigfoot</filename> extends &latex;’s default footnote mechanism in many +ways, including allow these two, as in this example. +</para> +<screen>\usepackage{bigfoot} +\DeclareNewFootnote{Default} +\DeclareNewFootnote{from}[alph] % create class \footnotefrom{} + .. +\begin{document} + .. +The third theorem is a partial converse of the +second.\footnotefrom{First noted in Wilson.\footnote{Second edition only.}} + .. +</screen> + +</sect1> +<sect1 label="11.7" id="Multiple-reference-to-footnotes"> +<title>Multiple references to footnotes</title> + +<para>You can refer to a single footnote more than once. This example +uses the package <filename>cleverref</filename>. +</para> +<!-- from SE user Jake http://tex.stackexchange.com/a/10116/339 --> +<screen>\usepackage{cleveref}[2012/02/15] % this version of package or later +\crefformat{footnote}{#2\footnotemark[#1]#3} + .. +\begin{document} + .. +The theorem is from Evers.\footnote{\label{fn:TE}Tinker and Evers, 1994.} +The corollary is from Chance.\footnote{Evers and Chance, 1990.} +But the key lemma is from Tinker.\cref{fn:TE} + .. +</screen> +<para>This solution will work with the package <filename>hyperref</filename>. +See <link linkend="_005cfootnotemark">\footnotemark</link> for a simpler solution in the common case +of multiple authors with the same affiliation. +</para> + +</sect1> +<sect1 label="11.8" id="Footnote-parameters"> <title>Footnote parameters</title> <indexterm role="cp"><primary>footnote parameters</primary></indexterm> @@ -3349,6 +4462,7 @@ footnotes. This is ‘<literal>6.65pt</literal>’ for ‘<literal> </chapter> <chapter label="12" id="Definitions"> <title>Definitions</title> + <indexterm role="cp"><primary>definitions</primary></indexterm> <para>&latex; has support for making new commands of many different kinds. @@ -3359,40 +4473,55 @@ footnotes. This is ‘<literal>6.65pt</literal>’ for ‘<literal> <sect1 label="12.1" id="_005cnewcommand-_0026-_005crenewcommand"> <title><literal>\newcommand</literal> & <literal>\renewcommand</literal></title> + <indexterm role="fn"><primary>\newcommand</primary></indexterm> <indexterm role="cp"><primary>commands, defining new ones</primary></indexterm> +<indexterm role="cp"><primary>commands, redefining</primary></indexterm> <indexterm role="cp"><primary>defining a new command</primary></indexterm> <indexterm role="cp"><primary>new commands, defining</primary></indexterm> <para><literal>\newcommand</literal> and <literal>\renewcommand</literal> define and redefine a command, respectively. Synopses: </para> -<screen> \newcommand[*]{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargval</replaceable>]{<replaceable>defn</replaceable>} -\renewcommand[*]{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargval</replaceable>]{<replaceable>defn</replaceable>} +<screen> \newcommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} + \newcommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} </screen> -<variablelist><varlistentry><term><replaceable><literal>*</literal></replaceable> -</term><listitem><indexterm role="cp"><primary>*-form of defining new commands</primary></indexterm> -<para>The *-form of these commands requires that the arguments not contain -multiple paragraphs of text (not <literal>\long</literal>, in plain &tex; terms). +<para>The <literal>*</literal>-form of these two commands requires that the arguments +not contain multiple paragraphs of text (not <literal>\long</literal>, in plain +&tex; terms). </para> -</listitem></varlistentry><varlistentry><term><replaceable>cmd</replaceable> -</term><listitem><para>The command name, beginning with <literal>\</literal>. For <literal>\newcommand</literal>, it -must not be already defined and must not begin with <literal>\end</literal>; for -<literal>\renewcommand</literal>, it must already be defined. +<variablelist><varlistentry><term><replaceable>cmd</replaceable> +</term><listitem><para>Required; the command name. It must begin with <literal>\</literal>. For +<literal>\newcommand</literal>, it must not be already defined and must not begin +with <literal>\end</literal>. For <literal>\renewcommand</literal>, it must already be +defined. </para> </listitem></varlistentry><varlistentry><term><replaceable>nargs</replaceable> -</term><listitem><para>An optional integer from 1 to 9 specifying the number of arguments -that the command will take. The default is for the command to have no -arguments. -</para> -</listitem></varlistentry><varlistentry><term><replaceable>optargval</replaceable> -</term><listitem><para>If this optional parameter is present, it means that the first -argument of command <replaceable>cmd</replaceable> is optional and its default value (i.e., -if it is not specified in the call) is <replaceable>optarg</replaceable>. In otherwise, -when calling the macro, if no <literal>[<replaceable>value</replaceable>]</literal> is given after -<literal><replaceable>cmd</replaceable></literal>—which is different from having <literal>[]</literal> for an -empty <replaceable>value</replaceable>—then string ‘<literal><replaceable>optargval</replaceable></literal>’ becomes the -value of <literal>#1</literal> within <replaceable>defn</replaceable> when the macro is expanded. +</term><listitem><para>Optional; an integer from 0 to 9, specifying the number of arguments +that the command will take. If this argument is not present, the +default is for the command to have no arguments. When redefining a +command, the new version can have a different number of arguments than +the old version. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>optargdefault</replaceable> +</term><listitem><para>Optional; if this argument is present then the first argument of defined +command <replaceable>\cmd</replaceable> is optional, with default value <replaceable>optargdefault</replaceable> +(which may be the empty string). If this argument is not present then +<replaceable>\cmd</replaceable> does not take an optional argument. +</para> +<para>That is, if <replaceable>\cmd</replaceable> is used with square brackets following, as in +<literal>\<replaceable>cmd</replaceable>[<replaceable>myval</replaceable>]</literal>, then within <replaceable>defn</replaceable> <literal>#1</literal> expands +<replaceable>myval</replaceable>. While if <replaceable>\cmd</replaceable> is called without square brackets +following, then within <replaceable>defn</replaceable> the <literal>#1</literal> expands to the default +<replaceable>optargdefault</replaceable>. In either case, any required arguments will be +referred to starting with <literal>#2</literal>. +</para> +<para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in the call is different from having the +square brackets with no contents, as in <literal>[]</literal>. The former results +in <literal>#1</literal> expanding to <replaceable>optargdefault</replaceable>; the latter results in +<literal>#1</literal> expanding to the empty string. </para> </listitem></varlistentry><varlistentry><term><replaceable>defn</replaceable> </term><listitem><para>The text to be substituted for every occurrence of <literal>cmd</literal>; a @@ -3400,11 +4529,73 @@ construct of the form <literal>#<replaceable>n</replaceable></literal> in <repla text of the <replaceable>n</replaceable>th argument. </para> </listitem></varlistentry></variablelist> -<!-- xx \providecommand, * form (non-\long) --> +<para>A command with no arguments that is followed in the source by a space +will swallow that space. The solution is to type <literal>{}</literal> after the +command and before the space. +</para> +<para>A simple example of defining a new command: +<literal>\newcommand{\JH}{Jim Hef{}feron}</literal> causes the abbreviation +<literal>\JH</literal> to be replaced by the longer text. +</para> +<para>Redefining a command is basically the same: +<literal>\renewcommand{\qedsymbol}{{\small QED}}</literal>. +</para> +<para>Here’s a command definition that uses arguments: +</para> +<screen>\newcommand{\defreference}[1]{Definition~\ref{#1}} +</screen> +<para>Then, <literal>\defreference{def:basis}</literal> will expand to +something like ‘<literal>Definition~3.14</literal>’. +</para> +<para>An example with two arguments: +<literal>\newcommand{\nbym}[2]{#1\!\times\!#2}</literal> is invoked as +<literal>\nbym{2}{k}</literal>. +</para> +<para>An example with optional arguments: +</para> +<screen>\newcommand{\salutation}[1][Sir or Madam]{Dear #1:} +</screen> +<para>Then, <literal>\salutation</literal> gives ‘<literal>Dear Sir or Madam:</literal>’ while +<literal>\salutation[John]</literal> gives ‘<literal>Dear John:</literal>’. And +<literal>\salutation[]</literal> gives ‘<literal>Dear :</literal>’. +</para> +<para>The braces around <replaceable>defn</replaceable> do not delimit the scope of the result of +expanding <replaceable>defn</replaceable>. So <literal>\newcommand{\shipname}[1]{\it #1}</literal> +is wrong since in the sentence +</para> +<screen>The \shipname{Monitor} met the \shipname{Virginia}. +</screen> +<para>the words ‘<literal>met the</literal>’ will incorrectly be in italics. An +extra pair of braces <literal>\newcommand{\shipname}[1]{{\it #1}}</literal> +fixes it. +</para> + +</sect1> +<sect1 label="12.2" id="_005cprovidecommand"> +<title><literal>\providecommand</literal></title> + +<indexterm role="fn"><primary>\providecommand</primary></indexterm> +<indexterm role="cp"><primary>commands, defining new ones</primary></indexterm> +<indexterm role="cp"><primary>defining a new command</primary></indexterm> +<indexterm role="cp"><primary>new commands, defining</primary></indexterm> + +<para>Defines a command, as long as no command of this name already exists. +Synopses: +</para> +<screen>\providecommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\providecommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +</screen> +<para>If no command of this name already exists then this has the same effect +as <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>). If a +command of this name already exists then this definition does nothing. +This is particularly useful in a style file, or other file that may be +loaded more than once. +</para> </sect1> -<sect1 label="12.2" id="_005cnewcounter"> -<title><literal>\newcounter</literal></title> +<sect1 label="12.3" id="_005cnewcounter"> +<title><literal>\newcounter</literal>: Allocating a counter</title> + <indexterm role="fn"><primary>\newcounter</primary></indexterm> <indexterm role="cp"><primary>counters, defining new</primary></indexterm> @@ -3412,190 +4603,424 @@ text of the <replaceable>n</replaceable>th argument. </para> <screen>\newcounter{<replaceable>countername</replaceable>}[<replaceable>supercounter</replaceable>] </screen> -<para>The <literal>\newcounter</literal> command defines a new counter named <replaceable>countername</replaceable>. -The new counter is initialized to zero. -</para> -<para>Given the optional argument <literal>[<replaceable>super</replaceable>]</literal>, <replaceable>countername</replaceable> -will be reset whenever the counter named <replaceable>supercounter</replaceable> is incremented. +<para>The <literal>\newcounter</literal> command globally defines a new counter named +<replaceable>countername</replaceable>. The name consists of letters only and does not begin +with a backslash (‘<literal>\</literal>’). The name must not already be used by +another counter. The new counter is initialized to zero. +</para> +<para>If the optional argument <literal>[<replaceable>supercounter</replaceable>]</literal> appears, then +<replaceable>countername</replaceable> will be numbered within, or subsidiary to, the +existing counter <replaceable>supercounter</replaceable>. For example, ordinarily +<literal>subsection</literal> is numbered within <literal>section</literal>. Any time +<replaceable>supercounter</replaceable> is incremented with <literal>\stepcounter</literal> +(see <link linkend="_005cstepcounter">\stepcounter</link>) or <literal>\refstepcounter</literal> +(see <link linkend="_005crefstepcounter">\refstepcounter</link>) then <replaceable>countername</replaceable> is reset to zero. </para> <para>See <link linkend="Counters">Counters</link>, for more information about counters. </para> </sect1> -<sect1 label="12.3" id="_005cnewlength"> -<title><literal>\newlength</literal></title> +<sect1 label="12.4" id="_005cnewlength"> +<title><literal>\newlength</literal>: Allocating a length</title> + <indexterm role="fn"><primary>\newlength</primary></indexterm> -<indexterm role="cp"><primary>lengths, defining new</primary></indexterm> +<indexterm role="cp"><primary>lengths, allocating new</primary></indexterm> +<indexterm role="cp"><primary>rubber lengths, defining new</primary></indexterm> +<indexterm role="cp"><primary>skip register, plain &tex;</primary></indexterm> +<indexterm role="cp"><primary>glue register, plain &tex;</primary></indexterm> -<para>Synopsis: +<para>Allocate a new <firstterm>length</firstterm> register. Synopsis: </para> <screen>\newlength{\<replaceable>arg</replaceable>} </screen> -<para>The <literal>\newlength</literal> command defines the mandatory argument as a -<firstterm>length</firstterm> command with a value of zero. The argument must -be a control sequence, as in <literal>\newlength{\foo}</literal>. An error -occurs if <literal>\foo</literal> is already defined. +<para>This command takes one required argument, which must begin with a +backslash (‘<literal>\</literal>’). It creates a new length register named +<literal>\<replaceable>arg</replaceable></literal>, which is a place to hold (rubber) lengths such as +<literal>1in plus.2in minus.1in</literal> (what plain &tex; calls a <literal>skip</literal> +register). The register gets an initial value of zero. The control +sequence <literal>\<replaceable>arg</replaceable></literal> must not already be defined. </para> -<para>See <link linkend="Lengths">Lengths</link>, for how to set the new length to a nonzero value, and -for more information about lengths in general. +<para>See <link linkend="Lengths">Lengths</link>, for more about lengths. </para> </sect1> -<sect1 label="12.4" id="_005cnewsavebox"> -<title><literal>\newsavebox</literal></title> +<sect1 label="12.5" id="_005cnewsavebox"> +<title><literal>\newsavebox</literal>: Allocating a box</title> + <indexterm role="fn"><primary>\newsavebox</primary></indexterm> +<indexterm role="cp"><primary>box, allocating new</primary></indexterm> -<para>Synopsis: +<para>Allocate a “bin” for holding a box. Synopsis: </para> -<screen>\newsavebox{<replaceable>cmd</replaceable>} +<screen>\newsavebox{\<replaceable>cmd</replaceable>} </screen> -<para>Defines <literal>\<replaceable>cmd</replaceable></literal>, which must be a command name not already -defined, to refer to a new bin for storing boxes. +<para>Defines <literal>\<replaceable>cmd</replaceable></literal> to refer to a new bin for storing boxes. +Such a box is for holding typeset material, to use multiple times +(see <link linkend="Boxes">Boxes</link>) or to measure or manipulate. The name +<literal>\<replaceable>cmd</replaceable></literal> must start with a backslash (‘<literal>\</literal>’), and must not +be already defined. +</para> +<para>The allocation of a box is global. This command is fragile +(see <link linkend="_005cprotect">\protect</link>). </para> </sect1> -<sect1 label="12.5" id="_005cnewenvironment-_0026-_005crenewenvironment"> +<sect1 label="12.6" id="_005cnewenvironment-_0026-_005crenewenvironment"> <title><literal>\newenvironment</literal> & <literal>\renewenvironment</literal></title> + <indexterm role="fn"><primary>\newenvironment</primary></indexterm> <indexterm role="fn"><primary>\renewenvironment</primary></indexterm> <indexterm role="cp"><primary>environments, defining</primary></indexterm> <indexterm role="cp"><primary>defining new environments</primary></indexterm> <indexterm role="cp"><primary>redefining environments</primary></indexterm> -<para>Synopses: -</para> -<screen> \newenvironment[*]{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>default</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} -\renewenvironment[*]{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} -</screen> <para>These commands define or redefine an environment <replaceable>env</replaceable>, that is, -<literal>\begin{<replaceable>env</replaceable>} … \end{<replaceable>env</replaceable>}</literal>. -</para> -<variablelist><varlistentry><term><replaceable><literal>*</literal></replaceable> -</term><listitem><indexterm role="cp"><primary>*-form of environment commands</primary></indexterm> -<para>The *-form of these commands requires that the arguments (not the -contents of the environment) not contain multiple paragraphs of text. +<literal>\begin{<replaceable>env</replaceable>} … \end{<replaceable>env</replaceable>}</literal>. Synopses: </para> -</listitem></varlistentry><varlistentry><term><replaceable>env</replaceable> -</term><listitem><para>The name of the environment. For <literal>\newenvironment</literal>, <replaceable>env</replaceable> -must not be an existing environment, and the command <literal>\<replaceable>env</replaceable></literal> -must be undefined. For <literal>\renewenvironment</literal>, <replaceable>env</replaceable> must be -the name of an existing environment. +<screen> \newenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} + \newenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} +\renewenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} +\renewenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} +</screen> +<para>Unlike <literal>\newcommand</literal> and <literal>\renewcommand</literal>, the <literal>*</literal>-forms +<literal>\newenvironment*</literal> and <literal>\renewcommand*</literal> have the same effect +as the forms with no <literal>*</literal>. +</para> +<variablelist><varlistentry><term><replaceable>env</replaceable> +</term><listitem><para>Required; the environment name. It does not begin with backslash +(<literal>\</literal>). It must not begin with the string <literal>end</literal>. For +<literal>\newenvironment</literal>, the name <replaceable>env</replaceable> must not be the name of an +already existing environment, and also the command <literal>\<replaceable>env</replaceable></literal> +must be undefined. For <literal>\renewenvironment</literal>, <replaceable>env</replaceable> must be the +name of an existing environment. </para> </listitem></varlistentry><varlistentry><term><replaceable>nargs</replaceable> -</term><listitem><para>An integer from 1 to 9 denoting the number of arguments of -the newly-defined environment. The default is no arguments. -</para> -</listitem></varlistentry><varlistentry><term><replaceable>default</replaceable> -</term><listitem><para>If this is specified, the first argument is optional, and <replaceable>default</replaceable> -gives the default value for that argument. -</para> -</listitem></varlistentry><varlistentry><term><replaceable>begdef</replaceable> -</term><listitem><para>The text expanded at every occurrence of <literal>\begin{<replaceable>env</replaceable>}</literal>; a -construct of the form <literal>#<replaceable>n</replaceable></literal> in <replaceable>begdef</replaceable> is replaced by -the text of the <replaceable>n</replaceable>th argument. -</para> -</listitem></varlistentry><varlistentry><term><replaceable>enddef</replaceable> -</term><listitem><para>The text expanded at every occurrence of <literal>\end{<replaceable>env</replaceable>}</literal>. It -may not contain any argument parameters. +</term><listitem><para>Optional; an integer from 0 to 9 denoting the number of arguments of +that the environment will take. These arguments appear after the +<literal>\begin</literal>, as in +<literal>\begin{<replaceable>env</replaceable>}{<replaceable>arg1</replaceable>}…{<replaceable>argn</replaceable>}</literal>. If this +argument is not present then the default is for the environment to have +no arguments. When redefining an environment, the new version can have +a different number of arguments than the old version. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>optargdefault</replaceable> +</term><listitem><para>Optional; if this argument is present then the first argument of the +defined environment is optional, with default value <replaceable>optargdefault</replaceable> +(which may be the empty string). If this argument is not present then +the environment does not take an optional argument. +</para> +<para>That is, when <literal>[<replaceable>optargdefault</replaceable>]</literal> is present in the environment +definition, if <literal>\begin{<replaceable>env</replaceable>}</literal> is used with square brackets +following, as in <literal>\begin{<replaceable>env</replaceable>}[<replaceable>myval</replaceable>]</literal>, then within +the environment <literal>#1</literal> expands <replaceable>myval</replaceable>. If +<literal>\begin{<replaceable>env</replaceable>}</literal> is called without square brackets following, +then within the environment the <literal>#1</literal> expands to the default +<replaceable>optargdefault</replaceable>. In either case, any required arguments will be +referred to starting with <literal>#2</literal>. +</para> + +<para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in the call is different from having the +square brackets with no contents, as in <literal>[]</literal>. The former results +in <literal>#1</literal> expanding to <replaceable>optargdefault</replaceable>; the latter results in +<literal>#1</literal> expanding to the empty string. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>begdefn</replaceable> +</term><listitem><para>Required; the text expanded at every occurrence of +<literal>\begin{<replaceable>env</replaceable>}</literal>; a construct of the form <literal>#<replaceable>n</replaceable></literal> in +<replaceable>begdef</replaceable> is replaced by the text of the <replaceable>n</replaceable>th argument. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>enddefn</replaceable> +</term><listitem><para>Required; the text expanded at every occurrence of +<literal>\end{<replaceable>env</replaceable>}</literal>. Note that it may not contain any argument +parameters, so <literal>#<replaceable>n</replaceable></literal> cannot be used here. </para> </listitem></varlistentry></variablelist> +<para>The environment <replaceable>env</replaceable> delimits the scope of the result of expanding +<replaceable>begdefn</replaceable> and <replaceable>enddefn</replaceable>. Thus, in the first example below, the +effect of the <literal>\small</literal> is limited to the quote and does not extend +to material following the environment. +</para> +<para>This example gives an environment like &latex;’s <literal>quotation</literal> except that +it will be set in smaller type. +</para> +<screen>\newenvironment{smallquote}{% + \small\begin{quotation} +}{% + \end{quotation} +} +</screen> +<para>This shows the use of arguments; it gives a quotation environment that +cites the author. +</para> +<screen>\newenvironment{citequote}[1][Shakespeare]{% + \begin{quotation} + \noindent\textit{#1}: +}{% + \end{quotation} +} +</screen> +<para>The author’s name is optional, and defaults to Shakespeare. +In the document, use the environment as here: +</para> +<screen>\begin{citequote}[Lincoln] + .. +\end{citequote} +</screen> +<para>The final example shows how to save the value of an argument to use in +<replaceable>enddefn</replaceable>. +</para> +<screen>\newsavebox{\quoteauthor} +\newenvironment{citequote}[1][Shakespeare]{% + \sbox\quoteauthor{#1}% + \begin{quotation} +}{% + \hspace{1em plus 1fill}---\usebox{\quoteauthor} + \end{quotation} +} +</screen> </sect1> -<sect1 label="12.6" id="_005cnewtheorem"> +<sect1 label="12.7" id="_005cnewtheorem"> <title><literal>\newtheorem</literal></title> + <indexterm role="fn"><primary>\newtheorem</primary></indexterm> <indexterm role="cp"><primary>theorems, defining</primary></indexterm> <indexterm role="cp"><primary>defining new theorems</primary></indexterm> -<screen>\newtheorem{<replaceable>newenv</replaceable>}{<replaceable>label</replaceable>}[<replaceable>within</replaceable>] -\newtheorem{<replaceable>newenv</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>label</replaceable>} +<indexterm role="cp"><primary>theorem-like environment</primary></indexterm> +<indexterm role="cp"><primary>environment, theorem-like</primary></indexterm> +<para>Define a new <firstterm>theorem-like environment</firstterm>. Synopses: +</para> +<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] +\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Both create a theorem-like environment <replaceable>name</replaceable>. Using the first +form, +</para> +<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] </screen> -<para>This command defines a theorem-like environment. Arguments: +<para>with the optional argument after the second required argument, +creates an environment whose counter is subordinate to the existing +counter <replaceable>numbered_within</replaceable>: it will be reset when +<replaceable>numbered_within</replaceable> is reset). +</para> +<para>Using the second form, +</para> +<screen>\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>with the optional argument between the two required +arguments, will create an environment whose counter will share the +previously defined counter <replaceable>numbered_like</replaceable>. +</para> +<para>You can specify one of <replaceable>numbered_within</replaceable> and <replaceable>numbered_like</replaceable>, +or neither, but not both. </para> -<variablelist><varlistentry><term><replaceable>newenv</replaceable> -</term><listitem><para>The name of the environment to be defined; must not be the name of an -existing environment or otherwise defined. +<para>This command creates a counter named <replaceable>name</replaceable>. In addition, unless +the optional argument <replaceable>numbered_like</replaceable> is used, the current +<literal>\ref</literal> value will be that of <literal>\the<replaceable>numbered_within</replaceable></literal> +(see <link linkend="_005cref">\ref</link>). </para> -</listitem></varlistentry><varlistentry><term><replaceable>label</replaceable> +<para>This declaration is global. It is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Arguments: +</para> +<variablelist><varlistentry><term><replaceable>name</replaceable> +</term><listitem><para>The name of the environment. It must not begin with a backslash +(‘<literal>\</literal>’). It must not be the name of an existing environment; indeed, +the command name <literal>\<replaceable>name</replaceable></literal> must not already be defined as anything. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>title</replaceable> </term><listitem><para>The text printed at the beginning of the environment, before the number. For example, ‘<literal>Theorem</literal>’. </para> -</listitem></varlistentry><varlistentry><term><replaceable>numbered_like</replaceable> -</term><listitem><para>(Optional.) The name of an already defined theorem-like environment; -the new environment will be numbered just like <replaceable>numbered_like</replaceable>. +</listitem></varlistentry><varlistentry><term><replaceable>numbered_within</replaceable> +</term><listitem><para>Optional; the name of an already defined counter, usually a sectional +unit such as <literal>chapter</literal> or <literal>section</literal>. When the +<replaceable>numbered_within</replaceable> counter is reset then the <replaceable>name</replaceable> environment’s +counter will also be reset. </para> -</listitem></varlistentry><varlistentry><term><replaceable>within</replaceable> -</term><listitem><para>(Optional.) The name of an already defined counter, a sectional unit. -The new theorem counter will be reset at the same time as the -<replaceable>within</replaceable> counter. +<para>If this optional argument is not used then the command +<literal>\the<replaceable>name</replaceable></literal> is set to <literal>\arabic{<replaceable>name</replaceable>}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>numbered_like</replaceable> +</term><listitem><para>Optional; the name of an already defined theorem-like environment. The +new environment will be numbered in sequence with <replaceable>numbered_like</replaceable>. </para> </listitem></varlistentry></variablelist> -<para>At most one of <replaceable>numbered_like</replaceable> and <replaceable>within</replaceable> can be specified, -not both. +<para>Without any optional arguments the environments are numbered +sequentially. This example has a declaration in the preamble that +results in ‘<literal>Definition 1</literal>’ and ‘<literal>Definition 2</literal>’ in the output. +</para> +<screen>\newtheorem{defn}{Definition} +\begin{document} +\section{...} +\begin{defn} + First def +\end{defn} + +\section{...} +\begin{defn} + Second def +\end{defn} +</screen> +<para>Because this example specifies the optional argument +<replaceable>numbered_within</replaceable> to <literal>\newtheorem</literal> as <literal>section</literal>, the +example, with the same document body, gives ‘<literal>Definition 1.1</literal>’ +and ‘<literal>Definition 2.1</literal>’. </para> +<screen>\newtheorem{defn}{Definition}[section] +\begin{document} +\section{...} +\begin{defn} + First def +\end{defn} + +\section{...} +\begin{defn} + Second def +\end{defn} +</screen> +<para>In this example there are two declarations in the preamble, the second +of which calls for the new <literal>thm</literal> environment to use the same +counter as <literal>defn</literal>. It gives ‘<literal>Definition 1.1</literal>’, followed +by ‘<literal>Theorem 2.1</literal>’ and ‘<literal>Definition 2.2</literal>’. +</para> +<screen>\newtheorem{defn}{Definition}[section] +\newtheorem{thm}[defn]{Theorem} +\begin{document} +\section{...} +\begin{defn} + First def +\end{defn} + +\section{...} +\begin{thm} + First thm +\end{thm} + +\begin{defn} + Second def +\end{defn} +</screen> </sect1> -<sect1 label="12.7" id="_005cnewfont"> -<title><literal>\newfont</literal></title> +<sect1 label="12.8" id="_005cnewfont"> +<title><literal>\newfont</literal>: Define a new font (obsolete)</title> + <indexterm role="fn"><primary>\newfont</primary></indexterm> <indexterm role="cp"><primary>fonts, new commands for</primary></indexterm> <indexterm role="cp"><primary>defining new fonts</primary></indexterm> -<para>Synopsis: +<para><literal>\newfont</literal>, now obsolete, defines a command that will switch fonts. +Synopsis: </para> -<screen>\newfont{<replaceable>cmd</replaceable>}{<replaceable>fontname</replaceable>} +<screen>\newfont{\<replaceable>cmd</replaceable>}{<replaceable>font description</replaceable>} +</screen> +<para>This defines a control sequence <literal>\<replaceable>cmd</replaceable></literal> that will change the +current font. &latex; will look on your system for a file named +<filename><replaceable>fontname</replaceable>.tfm</filename>. The control sequence must must not already +be defined. It must begin with a backslash (‘<literal>\</literal>’). +</para> +<indexterm role="fn"><primary>.fd file</primary></indexterm> +<para>This command is obsolete. It is a low-level command for setting up an +individual font. Today fonts are almost always defined in families +(which allows you to, for example, associate a boldface with a roman) +through the so-called “New Font Selection Scheme”, either by using +<filename>.fd</filename> files or through the use of an engine that can access +system fonts such as Xe&latex; (see <link linkend="TeX-engines">&tex; engines</link>). +<!-- xx explain nfss somewhere --> +</para> +<indexterm role="cp"><primary>at clause, in font definitions</primary></indexterm> +<indexterm role="cp"><primary>design size, in font definitions</primary></indexterm> +<para>But since it is part of &latex;, here is an explanation: the +<replaceable>font description</replaceable> consists of a <replaceable>fontname</replaceable> and an optional +<firstterm>at clause</firstterm>; this can have the form either <literal>at <replaceable>dimen</replaceable></literal> +or <literal>scaled <replaceable>factor</replaceable></literal>, where a <replaceable>factor</replaceable> of ‘<literal>1000</literal>’ +means no scaling. For &latex;’s purposes, all this does is scale all +the character and other font dimensions relative to the font’s design +size, which is a value defined in the <filename>.tfm</filename> file. +</para> +<para>This example defines two equivalent fonts and typesets a few +characters in each: +</para> +<screen>\newfont{\testfontat}{cmb10 at 11pt} +\newfont{\testfontscaled}{cmb10 scaled 11pt} +\testfontat abc +\testfontscaled abc </screen> -<para>Defines a control sequence <literal>\<replaceable>cmd</replaceable></literal>, which must not already -be defined, to make <replaceable>fontname</replaceable> be the current font. The file -looked for on the system is named <filename><replaceable>fontname</replaceable>.tfm</filename>. -</para> -<para>This is a low-level command for setting up to use an individual font. -More commonly, fonts are defined in families through <filename>.fd</filename> files. -</para> </sect1> -<sect1 label="12.8" id="_005cprotect"> +<sect1 label="12.9" id="_005cprotect"> <title><literal>\protect</literal></title> -<indexterm role="fn"><primary>\protect</primary></indexterm> +<indexterm role="fn"><primary>\protect</primary></indexterm> <indexterm role="cp"><primary>fragile commands</primary></indexterm> -<indexterm role="cp"><primary>moving arguments</primary></indexterm> -<para>Footnotes, line breaks, any command that has an optional argument, and -many more are so-called <firstterm>fragile</firstterm> commands. When a fragile -command is used in certain contexts, called <firstterm>moving arguments</firstterm>, it -must be preceded by <literal>\protect</literal>. In addition, any fragile -commands within the arguments must have their own <literal>\protect</literal>. -</para> -<para>Some examples of moving arguments are <literal>\caption</literal> -(see <link linkend="figure">figure</link>), <literal>\thanks</literal> (see <link linkend="_005cmaketitle">\maketitle</link>), and -expressions in <literal>tabular</literal> and <literal>array</literal> environments -(see <link linkend="tabular">tabular</link>). -</para> <indexterm role="cp"><primary>robust commands</primary></indexterm> -<para>Commands which are not fragile are called <firstterm>robust</firstterm>. They must not -be preceded by <literal>\protect</literal>. -</para> -<para>See also: -</para> -<simpara><ulink url="http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/teTeX/latex/latex2e-html/fragile.html">http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/teTeX/latex/latex2e-html/fragile.html</ulink></simpara> -<simpara><ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=protect">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=protect</ulink></simpara> - -<!-- xx really need examples. --> +<indexterm role="cp"><primary>moving arguments</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 they must be preceded by the command <literal>\protect</literal>. +</para> +<para>For example, when &latex; runs the <literal>\section{<replaceable>section +name</replaceable>}</literal> command it writes the <replaceable>section name</replaceable> text to the +<filename>.aux</filename> auxiliary file, moving it there for use elsewhere in the +document such as in the table of contents. Any argument that is +internally expanded by &latex; without typesetting it directly is +referred to as a <firstterm>moving argument</firstterm>. A command is fragile if it can +expand during this process into invalid &tex; code. Some examples of +moving arguments are those that appear in the <literal>\caption{..}</literal> +command (see <link linkend="figure">figure</link>), in the <literal>\thanks{..}</literal> command +(see <link linkend="_005cmaketitle">\maketitle</link>), and in @-expressions in the <literal>tabular</literal> and +<literal>array</literal> environments (see <link linkend="tabular">tabular</link>). +</para> +<para>If you get strange errors from commands used in moving arguments, try +preceding it with <literal>\protect</literal>. Every fragile commands must be +protected with their own <literal>\protect</literal>. +</para> +<para>Although usually a <literal>\protect</literal> command doesn’t hurt, length +commands are robust and should not be preceded by a <literal>\protect</literal> +command. Nor can a <literal>\protect</literal> command be used in the argument to +<literal>\addtocounter</literal> or <literal>\setcounter</literal> command. +</para> +<para>In this example the <literal>caption</literal> command gives a mysterious error +about an extra curly brace. Fix the problem by preceding each +<literal>\raisebox</literal> command with <literal>\protect</literal>. +</para> +<screen>\begin{figure} + .. + \caption{Company headquarters of A\raisebox{1pt}{B}\raisebox{-1pt}{C}} +\end{figure} +</screen> +<para>In the next example the <literal>\tableofcontents</literal> command gives an error +because the <literal>\(..\)</literal> in the section title expands to illegal &tex; +in the <filename>.toc</filename> file. You can solve this by changing <literal>\(..\)</literal> +to <literal>\protect\(..\protect\)</literal>. +</para> +<screen>\begin{document} +\tableofcontents + .. +\section{Einstein's \( e=mc^2 \)} + .. +</screen> </sect1> </chapter> <chapter label="13" id="Counters"> <title>Counters</title> + <indexterm role="cp"><primary>counters, a list of</primary></indexterm> <indexterm role="cp"><primary>variables, a list of</primary></indexterm> <para>Everything &latex; numbers for you has a counter associated with -it. The name of the counter is the same as the name of the environment -or command that produces the number, except with no <literal>\</literal>. -(<literal>enumi</literal>–<literal>enumiv</literal> are used for the nested enumerate -environment.) Below is a list of the counters used in &latex;’s -standard document classes to control numbering. +it. The name of the counter is often the same as the name of the +environment or command associated with the number, except with no +backslash (<literal>\</literal>). Thus the <literal>\chapter</literal> command starts a +chapter and the <literal>chapter</literal> counter keeps track of the chapter +number. Below is a list of the counters used in &latex;’s standard +document classes to control numbering. </para> <screen>part paragraph figure enumi chapter subparagraph table enumii @@ -3603,13 +5028,26 @@ section page footnote enumiii subsection equation mpfootnote enumiv subsubsection </screen> +<para>The <literal>mpfootnote</literal> counter is used by the <literal>\footnote</literal> command +inside of a minipage (see <link linkend="minipage">minipage</link>). +</para> +<para>The <literal>enumi</literal> through <literal>enumiv</literal> counters are used in the +<literal>enumerate</literal> environment, for up to four nested levels +(see <link linkend="enumerate">enumerate</link>). +</para> +<para>New counters are created with <literal>\newcounter</literal>. See <link linkend="_005cnewcounter">\newcounter</link>. +</para> + <sect1 label="13.1" id="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"> <title><literal>\alph \Alph \arabic \roman \Roman \fnsymbol</literal>: Printing counters</title> +<indexterm role="cp"><primary>counters, printing</primary></indexterm> + <para>All of these commands take a single counter as an argument, for -instance, <literal>\alph{enumi}</literal>. +instance, <literal>\alph{enumi}</literal>. Note that the counter name does not +start with a backslash. </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\alph</primary></indexterm><literal>\alph</literal> </term><listitem><para>prints <replaceable>counter</replaceable> using lowercase letters: ‘a’, ‘b’, ... @@ -3635,13 +5073,14 @@ symbols (conventionally used for labeling footnotes). The value of </para> <literallayout>asterisk(*) dagger(‡) ddagger(‡) section-sign(§) paragraph-sign(¶) parallel(∥) -double-asterisk(**) double-dagger(‡‡) double-ddagger(‡‡) +double-asterisk(**) double-dagger(††) double-ddagger(‡‡) </literallayout> </listitem></varlistentry></variablelist> </sect1> <sect1 label="13.2" id="_005cusecounter"> <title><literal>\usecounter{<replaceable>counter</replaceable>}</literal></title> + <indexterm role="fn"><primary>\usecounter</primary></indexterm> <indexterm role="cp"><primary>list items, specifying counter</primary></indexterm> <indexterm role="cp"><primary>numbered items, specifying counter</primary></indexterm> @@ -3650,14 +5089,30 @@ double-asterisk(**) double-dagger(‡‡) double-ddagger(‡  </para> <screen>\usecounter{<replaceable>counter</replaceable>} </screen> -<para>The <literal>\usecounter</literal> command is used in the second argument of the -<literal>list</literal> environment to specify <replaceable>counter</replaceable> to be used to number -the list items. -</para> +<para>In the <literal>list</literal> environment, when used in the second argument, this +command sets up <replaceable>counter</replaceable> to number the list items. It initializes +<replaceable>counter</replaceable> to zero, and arranges that when <literal>\item</literal> is called +without its optional argument then <replaceable>counter</replaceable> is incremented by +<literal>\refstepcounter</literal>, making its value be the current <literal>ref</literal> +value. This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Put in the preamble, this makes a new list environment enumerated with +<replaceable>testcounter</replaceable>: +</para> +<screen>\newcounter{testcounter} +\newenvironment{test}{% + \begin{list}{}{% + \usecounter{testcounter} + } +}{% + \end{list} +} +</screen> </sect1> <sect1 label="13.3" id="_005cvalue"> <title><literal>\value{<replaceable>counter</replaceable>}</literal></title> + <indexterm role="fn"><primary>\value</primary></indexterm> <indexterm role="cp"><primary>counters, getting value of</primary></indexterm> @@ -3665,17 +5120,34 @@ the list items. </para> <screen>\value{<replaceable>counter</replaceable>} </screen> -<para>The <literal>\value</literal> command produces the value of <replaceable>counter</replaceable>. It can -be used anywhere &latex; expects a number, for example: +<para>This command expands to the value of <replaceable>counter</replaceable>. It is often used +in <literal>\setcounter</literal> or <literal>\addtocounter</literal>, but <literal>\value</literal> can +be used anywhere that &latex; expects a number. It must not be +preceded by <literal>\protect</literal> (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>The <literal>\value</literal> command is not used for typesetting the value of the +counter. See <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>. +</para> +<para>This example outputs ‘<literal>Test counter is 6. Other counter +is 5.</literal>’. </para> -<screen>\setcounter{myctr}{3} -\addtocounter{myctr}{1} +<screen>\newcounter{test} \setcounter{test}{5} +\newcounter{other} \setcounter{other}{\value{test}} +\addtocounter{test}{1} + +Test counter is \arabic{test}. +Other counter is \arabic{other}. +</screen> +<para>This example inserts <literal>\hspace{4\parindent}</literal>. +</para> +<screen>\setcounter{myctr}{3} \addtocounter{myctr}{1} \hspace{\value{myctr}\parindent} </screen> </sect1> <sect1 label="13.4" id="_005csetcounter"> <title><literal>\setcounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>}</literal></title> + <indexterm role="fn"><primary>\setcounter</primary></indexterm> <indexterm role="cp"><primary>counters, setting</primary></indexterm> <indexterm role="cp"><primary>setting counters</primary></indexterm> @@ -3684,41 +5156,55 @@ be used anywhere &latex; expects a number, for example: </para> <screen>\setcounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>} </screen> -<para>The <literal>\setcounter</literal> command sets the value of <replaceable>counter</replaceable> to the -<replaceable>value</replaceable> argument. +<para>The <literal>\setcounter</literal> command globally sets the value of <replaceable>counter</replaceable> +to the <replaceable>value</replaceable> argument. Note that the counter name does not start +with a backslash. </para> </sect1> <sect1 label="13.5" id="_005caddtocounter"> <title><literal>\addtocounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>}</literal></title> + <indexterm role="fn"><primary>\addtocounter</primary></indexterm> -<para>The <literal>\addtocounter</literal> command increments <replaceable>counter</replaceable> by the -amount specified by the <replaceable>value</replaceable> argument, which may be negative. +<para>The <literal>\addtocounter</literal> command globally increments <replaceable>counter</replaceable> by +the amount specified by the <replaceable>value</replaceable> argument, which may be negative. </para> </sect1> <sect1 label="13.6" id="_005crefstepcounter"> <title><literal>\refstepcounter{<replaceable>counter</replaceable>}</literal></title> + <indexterm role="fn"><primary>\refstepcounter</primary></indexterm> <para>The <literal>\refstepcounter</literal> command works in the same way as -<literal>\stepcounter</literal> See <link linkend="_005cstepcounter">\stepcounter</link>, except it also defines the -current <literal>\ref</literal> value to be the result of <literal>\thecounter</literal>. +<literal>\stepcounter</literal> (see <link linkend="_005cstepcounter">\stepcounter</link>): it globally increments the +value of <replaceable>counter</replaceable> by one and resets the value of any counter +numbered within it. (For the definition of “counters numbered +within”, see <link linkend="_005cnewcounter">\newcounter</link>.) +</para> +<para>In addition, this command also defines the current <literal>\ref</literal> value +to be the result of <literal>\thecounter</literal>. +</para> +<para>While the counter value is set globally, the <literal>\ref</literal> value is set +locally, i.e., inside the current group. </para> </sect1> <sect1 label="13.7" id="_005cstepcounter"> <title><literal>\stepcounter{<replaceable>counter</replaceable>}</literal></title> + <indexterm role="fn"><primary>\stepcounter</primary></indexterm> -<para>The <literal>\stepcounter</literal> command adds one to <replaceable>counter</replaceable> and -resets all subsidiary counters. +<para>The <literal>\stepcounter</literal> command globally adds one to <replaceable>counter</replaceable> and +resets all counters numbered within it. (For the definition of +“counters numbered within”, see <link linkend="_005cnewcounter">\newcounter</link>.) </para> </sect1> <sect1 label="13.8" id="_005cday-_005cmonth-_005cyear"> <title><literal>\day \month \year</literal>: Predefined counters</title> + <indexterm role="fn"><primary>\day</primary></indexterm> <indexterm role="fn"><primary>\month</primary></indexterm> <indexterm role="fn"><primary>\year</primary></indexterm> @@ -3737,15 +5223,123 @@ current day (see <link linkend="_005ctoday">\today</link>). </chapter> <chapter label="14" id="Lengths"> <title>Lengths</title> + <indexterm role="cp"><primary>lengths, defining and using</primary></indexterm> -<para>A <literal>length</literal> is a measure of distance. Many &latex; commands take a +<para>A <firstterm>length</firstterm> is a measure of distance. Many &latex; commands take a length as an argument. </para> - - -<sect1 label="14.1" id="_005csetlength"> +<para>Lengths come in two types. A <firstterm>rigid length</firstterm> (what Plain &tex; +calls a <firstterm>dimen</firstterm>) such as <literal>10pt</literal> cannot contain a <literal>plus</literal> or +<literal>minus</literal> component. A <firstterm>rubber length</firstterm> (what Plain &tex; calls +a <firstterm>skip</firstterm>) can contain those, as with <literal>1cm plus0.05cm +minus0.01cm</literal>. These give the ability to stretch or shrink; the length +in the prior sentence could appear in the output as long as 1.05 cm +or as short as 0.99 cm, depending on what &tex;’s typesetting +algorithm finds optimum. +</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 +length infinite stretchability or shrinkability, so that the length in +the prior sentence can be set by &tex; to any distance greater than or +equal to 1 inch. &tex; actually provides three infinite glue +components <literal>fil</literal>, <literal>fill</literal>, and <literal>filll</literal>, such that the +later ones overcome the earlier ones, but only the middle value is +ordinarily used. See <link linkend="_005chfill">\hfill</link>, See <link linkend="_005cvfill">\vfill</link>. +</para> +<para>Multiplying an entire rubber length by a number turns it into a rigid +length, so that after <literal>\setlength{\ylength}{1in plus 0.2in}</literal> +and <literal>\setlength{\zlength}{3\ylength}</literal> then the value of +<literal>\zlength</literal> is <literal>3in</literal>. +</para> + + + +<sect1 label="14.1" id="Units-of-length"> +<title>Units of length</title> + +<indexterm role="cp"><primary>units, of length</primary></indexterm> + +<para>&tex; and &latex; know about these units both inside and outside of +math mode. +</para> +<variablelist><varlistentry><term><literal>pt</literal> +</term><listitem><indexterm role="fn"><primary>pt</primary></indexterm> +<indexterm role="cp"><primary>Point</primary></indexterm> +<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> +</term><listitem><indexterm role="cp"><primary>pica</primary></indexterm> +<indexterm role="fn"><primary>pc</primary></indexterm> +<para>Pica, 12 pt +</para> +</listitem></varlistentry><varlistentry><term><literal>in</literal> +</term><listitem><indexterm role="fn"><primary>in</primary></indexterm> +<indexterm role="fn"><primary>inch</primary></indexterm> +<para>Inch, 72.27 pt +</para> +</listitem></varlistentry><varlistentry><term><literal>bp</literal> +</term><listitem><indexterm role="fn"><primary>bp</primary></indexterm> +<indexterm role="cp"><primary>Big point</primary></indexterm> +<para>Big point, 1/72 inch. This length is the definition of a point in +PostScript and many desktop publishing systems. +</para> +</listitem></varlistentry><varlistentry><term><literal>cm</literal> +</term><listitem><indexterm role="cp"><primary>Centimeter</primary></indexterm> +<indexterm role="fn"><primary>cm</primary></indexterm> +<para>Centimeter +</para> +</listitem></varlistentry><varlistentry><term><literal>mm</literal> +</term><listitem><indexterm role="cp"><primary>Millimeter</primary></indexterm> +<indexterm role="fn"><primary>mm</primary></indexterm> +<para>Millimeter +</para> +</listitem></varlistentry><varlistentry><term><literal>dd</literal> +</term><listitem><indexterm role="cp"><primary>Didot point</primary></indexterm> +<indexterm role="fn"><primary>dd</primary></indexterm> +<para>Didot point, 1.07 pt +</para> +</listitem></varlistentry><varlistentry><term><literal>cc</literal> +</term><listitem><indexterm role="cp"><primary>Cicero</primary></indexterm> +<indexterm role="fn"><primary>cc</primary></indexterm> +<para>Cicero, 12 dd +</para> +</listitem></varlistentry><varlistentry><term><literal>sp</literal> +</term><listitem><indexterm role="cp"><primary>Scaled point</primary></indexterm> +<indexterm role="fn"><primary>sp</primary></indexterm> +<para>Scaled point, 1/65536 pt +</para> +</listitem></varlistentry></variablelist> +<indexterm role="cp"><primary>ex</primary></indexterm> +<indexterm role="cp"><primary>x-height</primary></indexterm> +<indexterm role="fn"><primary>ex</primary></indexterm> +<indexterm role="cp"><primary>m-width</primary></indexterm> +<indexterm role="cp"><primary>em</primary></indexterm> +<indexterm role="fn"><primary>em</primary></indexterm> +<para>Two other lengths that are often used are values set by the designer of +the font. The x-height of the current font <firstterm>ex</firstterm>, traditionally the +height of the lower case letter x, is often used for vertical +lengths. Similarly <firstterm>em</firstterm>, traditionally the width of the capital +letter M, is often used for horizontal lengths (there is also +<literal>\enspace</literal>, which is <literal>0.5em</literal>). Use of these can help make a +definition work better across font changes. For example, a definition +of the vertical space between list items given as +<literal>\setlength{\itemsep}{1ex plus 0.05ex minus 0.01ex}</literal> is more +likely to still be reasonable if the font is changed than a definition +given in points. +</para> +<indexterm role="cp"><primary>mu, math unit</primary></indexterm> +<indexterm role="fn"><primary>mu</primary></indexterm> +<para>In math mode, many definitions are expressed in terms of the math unit +<firstterm>mu</firstterm> given by 1 em = 18 mu, where the em is taken from the current +math symbols family. See <link linkend="Spacing-in-math-mode">Spacing in math mode</link>. +</para> + +</sect1> +<sect1 label="14.2" id="_005csetlength"> <title><literal>\setlength{\<replaceable>len</replaceable>}{<replaceable>value</replaceable>}</literal></title> + <indexterm role="fn"><primary>\setlength</primary></indexterm> <indexterm role="cp"><primary>lengths, setting</primary></indexterm> @@ -3756,8 +5350,9 @@ understands, i.e., inches (<literal>in</literal>), millimeters (<literal>mm</lit </para> </sect1> -<sect1 label="14.2" id="_005caddtolength"> -<title>\addtolength{<replaceable>\len</replaceable>}{<replaceable>amount</replaceable>}</title> +<sect1 label="14.3" id="_005caddtolength"> +<title><literal>\addtolength{<replaceable>\len</replaceable>}{<replaceable>amount</replaceable>}</literal></title> + <indexterm role="fn"><primary>\addtolength</primary></indexterm> <indexterm role="cp"><primary>lengths, adding to</primary></indexterm> @@ -3767,8 +5362,9 @@ may be negative. </para> </sect1> -<sect1 label="14.3" id="_005csettodepth"> +<sect1 label="14.4" id="_005csettodepth"> <title><literal>\settodepth</literal></title> + <indexterm role="fn"><primary>\settodepth</primary></indexterm> <para><literal>\settodepth{\gnat}{text}</literal> @@ -3778,8 +5374,9 @@ equal to the depth of the <literal>text</literal> argument. </para> </sect1> -<sect1 label="14.4" id="_005csettoheight"> +<sect1 label="14.5" id="_005csettoheight"> <title><literal>\settoheight</literal></title> + <indexterm role="fn"><primary>\settoheight</primary></indexterm> <para><literal>\settoheight{\gnat}{text}</literal> @@ -3790,8 +5387,9 @@ equal to the height of the <literal>text</literal> argument. </sect1> -<sect1 label="14.5" id="_005csettowidth"> +<sect1 label="14.6" id="_005csettowidth"> <title><literal>\settowidth{\<replaceable>len</replaceable>}{<replaceable>text</replaceable>}</literal></title> + <indexterm role="fn"><primary>\settowidth</primary></indexterm> <para>The <literal>\settowidth</literal> command sets the value of the command <replaceable>\len</replaceable> @@ -3799,8 +5397,9 @@ to the width of the <replaceable>text</replaceable> argument. </para> </sect1> -<sect1 label="14.6" id="Predefined-lengths"> +<sect1 label="14.7" id="Predefined-lengths"> <title>Predefined lengths</title> + <indexterm role="cp"><primary>lengths, predefined</primary></indexterm> <indexterm role="cp"><primary>predefined lengths</primary></indexterm> @@ -3829,6 +5428,7 @@ natural size, e.g., say </chapter> <chapter label="15" id="Making-paragraphs"> <title>Making paragraphs</title> + <indexterm role="cp"><primary>making paragraphs</primary></indexterm> <indexterm role="cp"><primary>paragraphs</primary></indexterm> @@ -3841,14 +5441,14 @@ a sectioning command. <sect1 label="15.1" id="_005cindent"> <title><literal>\indent</literal></title> + <indexterm role="fn"><primary>\indent</primary></indexterm> <indexterm role="fn"><primary>\parindent</primary></indexterm> <indexterm role="cp"><primary>indent, forcing</primary></indexterm> -<para><literal>\indent</literal> produces a horizontal space whose width equals the -width of the <literal>\parindent</literal> length, the normal paragraph -indentation. It is used to add paragraph indentation where it would -otherwise be suppressed. +<para><literal>\indent</literal> produces a horizontal space whose width equals to the +<literal>\parindent</literal> length, the normal paragraph indentation. It is used +to add paragraph indentation where it would otherwise be suppressed. </para> <para>The default value for <literal>\parindent</literal> is <literal>1em</literal> in two-column mode, otherwise <literal>15pt</literal> for <literal>10pt</literal> documents, <literal>17pt</literal> for @@ -3858,17 +5458,27 @@ mode, otherwise <literal>15pt</literal> for <literal>10pt</literal> documents, < </sect1> <sect1 label="15.2" id="_005cnoindent"> <title><literal>\noindent</literal></title> + <indexterm role="fn"><primary>\noindent</primary></indexterm> <indexterm role="cp"><primary>indent, suppressing</primary></indexterm> -<para>When used at the beginning of the paragraph, <literal>\noindent</literal> -suppresses any paragraph indentation. It has no effect when used in -the middle of a paragraph. +<para>When used at the beginning of the paragraph, this command suppresses any +paragraph indentation, as in this example. +</para> +<screen>.. end of the prior paragraph. + +\noindent This paragraph is not indented. +</screen> +<para>It has no effect when used in the middle of a paragraph. +</para> +<para>To eliminate paragraph indentation in an entire document, put +<literal>\setlength{\parindent}{0pt}</literal> in the preamble. </para> </sect1> <sect1 label="15.3" id="_005cparskip"> <title><literal>\parskip</literal></title> + <indexterm role="fn"><primary>\parskip</primary></indexterm> <indexterm role="cp"><primary>vertical space before paragraphs</primary></indexterm> @@ -3879,6 +5489,7 @@ before each paragraph. The default is <literal>0pt plus1pt</literal>. </sect1> <sect1 label="15.4" id="Marginal-notes"> <title>Marginal notes</title> + <indexterm role="cp"><primary>marginal notes</primary></indexterm> <indexterm role="cp"><primary>notes in the margin</primary></indexterm> <indexterm role="cp"><primary>remarks in the margin</primary></indexterm> @@ -3895,9 +5506,9 @@ where the <literal>\marginpar</literal> occurs. <para>When you only specify the mandatory argument <replaceable>right</replaceable>, the text will be placed </para> -<itemizedlist><listitem><para>in the right margin for one-sided layout; -</para></listitem><listitem><para>in the outside margin for two-sided layout; -</para></listitem><listitem><para>in the nearest margin for two-column layout. +<itemizedlist><listitem><para>in the right margin for one-sided layout (option <literal>oneside</literal>, see <link linkend="Document-class-options">Document class options</link>); +</para></listitem><listitem><para>in the outside margin for two-sided layout (option <literal>twoside</literal>, see <link linkend="Document-class-options">Document class options</link>); +</para></listitem><listitem><para>in the nearest margin for two-column layout (option <literal>twocolumn</literal>, see <link linkend="Document-class-options">Document class options</link>). </para></listitem></itemizedlist> <indexterm role="fn"><primary>\reversemarginpar</primary></indexterm> <indexterm role="fn"><primary>\normalmarginpar</primary></indexterm> @@ -3939,13 +5550,14 @@ notes from falling off the bottom of the page. </chapter> <chapter label="16" id="Math-formulas"> <title>Math formulas</title> + <indexterm role="cp"><primary>math formulas</primary></indexterm> <indexterm role="cp"><primary>formulas, math</primary></indexterm> <indexterm role="cp"><primary>math mode, entering</primary></indexterm> - <indexterm role="fn"><primary>math environment</primary></indexterm> <indexterm role="fn"><primary>displaymath environment</primary></indexterm> <indexterm role="fn"><primary>equation environment</primary></indexterm> + <para>There are three environments that put &latex; in math mode: </para> <variablelist><varlistentry><term><literal>math</literal> @@ -3985,8 +5597,9 @@ it too is used <emphasis>outside</emphasis> of math mode. <indexterm role="fn"><primary>\displaystyle</primary></indexterm> <para>The <literal>\displaystyle</literal> declaration forces the size and style of the formula to be that of <literal>displaymath</literal>, e.g., with limits above and -below summations. For example -</para><screen>$\displaystyle \sum_{n=0}^\infty x_n $ +below summations. For example: +</para> +<screen>$\displaystyle \sum_{n=0}^\infty x_n $ </screen> <!-- xx see also \cal, \mathcal --> @@ -3994,668 +5607,925 @@ below summations. For example <sect1 label="16.1" id="Subscripts-_0026-superscripts"> <title>Subscripts & superscripts</title> + <indexterm role="cp"><primary>superscript</primary></indexterm> <indexterm role="cp"><primary>subscript</primary></indexterm> <indexterm role="cp"><primary>exponent</primary></indexterm> <indexterm role="fn"><primary>_</primary></indexterm> <indexterm role="fn"><primary>^</primary></indexterm> -<para>To get an expression <emphasis>exp</emphasis> to appear as a subscript, you just type -<literal>_{</literal><emphasis>exp</emphasis><literal>}</literal>. To get <emphasis>exp</emphasis> to appear as a -superscript, you type <literal>^{</literal><emphasis>exp</emphasis><literal>}</literal>. &latex; handles -superscripted superscripts and all of that stuff in the natural way. -It even does the right thing when something has both a subscript and a -superscript. +<para>In math mode, use the caret character <literal>^</literal> to make the +<replaceable>exp</replaceable> appear as a superscript, ie. type <literal>^{<replaceable>exp</replaceable>}</literal>. +Similarly, in math mode, underscore <literal>_{<replaceable>exp</replaceable>}</literal> makes a +subscript out of <replaceable>exp</replaceable>. +</para> +<para>In this example the <literal>0</literal> and <literal>1</literal> appear as subscripts while the +<literal>2</literal> is a superscript. +</para> +<screen>\( (x_0+x_1)^2 \) +</screen> +<para>To have more than one character in <replaceable>exp</replaceable> use curly braces as in +<literal>e^{-2x}</literal>. +</para> +<para>&latex; handles superscripts on superscripts, and all of that stuff, in +the natural way, so expressions such as <literal>e^{x^2}</literal> and +<literal>x_{a_0}</literal> will look right. It also does the right thing when +something has both a subscript and a superscript. In this example the +<literal>0</literal> appears at the bottom of the integral sign while the <literal>10</literal> +appears at the top. +</para> +<screen>\int_0^{10} x^2 \,dx +</screen> +<para>You can put a superscript or subscript before a symbol with a construct +such as <literal>{}_t K^2</literal> in math mode (the initial <literal>{}</literal> prevents +the prefixed subscript from being attached to any prior symbols in the +expression). +</para> +<para>Outside of math mode, a construct like <literal>A +test$_\textnormal{subscript}$</literal> will produce a subscript typeset in +text mode, not math mode. Note that there are packages specialized for +writing Chemical formulas such as <filename>mhchem</filename>. +<!-- xx display mode --> </para> </sect1> <sect1 label="16.2" id="Math-symbols"> <title>Math symbols</title> + <indexterm role="cp"><primary>math symbols</primary></indexterm> <indexterm role="cp"><primary>symbols, math</primary></indexterm> <indexterm role="cp"><primary>greek letters</primary></indexterm> -<para>&latex; provides almost any mathematical symbol you’re likely to -need. The commands for generating them can be used only in math mode. +<para>&latex; provides almost any mathematical symbol you’re likely to need. For example, if you include <literal>$\pi$</literal> in your source, you will get -the pi symbol (<inlineequation><mathphrase>\pi</mathphrase></inlineequation>) in your output. +the pi symbol π. +</para> +<para>Below is a list of commonly-available symbols. It is by no means an +exhaustive list. Each symbol here is described with a short phrase, and +its symbol class (which determines the spacing around it) is given in +parenthesis. The commands for these symbols can be used only in math +mode. </para> +<!-- xx Add Negation: @code{} 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> -</term><listitem><para><inlineequation><mathphrase>\|</mathphrase></inlineequation> +</term><listitem><para>∥ Parallel (relation). Synonym: <literal>\parallel</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\aleph</primary></indexterm><literal>\aleph</literal> -</term><listitem><para><inlineequation><mathphrase>\aleph</mathphrase></inlineequation> +</term><listitem><para>ℵ Aleph, transfinite cardinal (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\alpha</primary></indexterm><literal>\alpha</literal> -</term><listitem><para><inlineequation><mathphrase>\alpha</mathphrase></inlineequation> +</term><listitem><para>α Lower case Greek letter alpha (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\amalg</primary></indexterm><literal>\amalg</literal> -</term><listitem><para><inlineequation><mathphrase>\amalg</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⨿ Disjoint union (binary) </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\angle</primary></indexterm><literal>\angle</literal> -</term><listitem><para><inlineequation><mathphrase>\angle</mathphrase></inlineequation> +</term><listitem><para>∠ Geometric angle (ordinary). Similar: less-than +sign <literal><</literal> and angle bracket <literal>\langle</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\approx</primary></indexterm><literal>\approx</literal> -</term><listitem><para><inlineequation><mathphrase>\approx</mathphrase></inlineequation> (relation) +</term><listitem><para>≈ Almost equal to (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ast</primary></indexterm><literal>\ast</literal> -</term><listitem><para><inlineequation><mathphrase>\ast</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∗ Asterisk operator, convolution, six-pointed +(binary). Synonym: <literal>*</literal>, which is often a superscript or +subscript, as in the Kleene star. Similar: <literal>\star</literal>, which is +five-pointed, and is sometimes used as a general binary operation, and +sometimes reserved for cross-correlation. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\asymp</primary></indexterm><literal>\asymp</literal> -</term><listitem><para><inlineequation><mathphrase>\asymp</mathphrase></inlineequation> (relation) +</term><listitem><para>≍ Asymptomatically equivalent (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\backslash</primary></indexterm><literal>\backslash</literal> -</term><listitem><para>\ (delimiter) +</term><listitem><para>\ Backslash (ordinary). Similar: set minus <literal>\setminus</literal>, and +<literal>\textbackslash</literal> for backslash outside of math mode. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\beta</primary></indexterm><literal>\beta</literal> -</term><listitem><para><inlineequation><mathphrase>\beta</mathphrase></inlineequation> +</term><listitem><para>β Lower case Greek letter beta (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigcap</primary></indexterm><literal>\bigcap</literal> -</term><listitem><para><inlineequation><mathphrase>\bigcap</mathphrase></inlineequation> +</term><listitem><para>⋂ Variable-sized, or n-ary, intersection (operator). Similar: +binary intersection <literal>\cap</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigcirc</primary></indexterm><literal>\bigcirc</literal> -</term><listitem><para><inlineequation><mathphrase>\bigcirc</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⚪ Circle, larger (binary). Similar: function +composition <literal>\circ</literal>. +<!-- bb Best unicode symbol for this? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigcup</primary></indexterm><literal>\bigcup</literal> -</term><listitem><para><inlineequation><mathphrase>\bigcup</mathphrase></inlineequation> +</term><listitem><para>⋃ Variable-sized, or n-ary, union (operator). Similar: binary +union <literal>\cup</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigodot</primary></indexterm><literal>\bigodot</literal> -</term><listitem><para><inlineequation><mathphrase>\bigodot</mathphrase></inlineequation> +</term><listitem><para>⨀ Variable-sized, or n-ary, circled dot operator (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigoplus</primary></indexterm><literal>\bigoplus</literal> -</term><listitem><para><inlineequation><mathphrase>\bigoplus</mathphrase></inlineequation> +</term><listitem><para>⨁ Variable-sized, or n-ary, circled plus operator (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigotimes</primary></indexterm><literal>\bigotimes</literal> -</term><listitem><para><inlineequation><mathphrase>\bigotimes</mathphrase></inlineequation> +</term><listitem><para>⨂ Variable-sized, or n-ary, circled times operator (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigtriangledown</primary></indexterm><literal>\bigtriangledown</literal> -</term><listitem><para><inlineequation><mathphrase>\bigtriangledown</mathphrase></inlineequation> (binary operation) +</term><listitem><para>▽ Variable-sized, or n-ary, open triangle pointing down +(operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigtriangleup</primary></indexterm><literal>\bigtriangleup</literal> -</term><listitem><para><inlineequation><mathphrase>\bigtriangleup</mathphrase></inlineequation> (binary operation) +</term><listitem><para>△ Variable-sized, or n-ary, open triangle pointing up (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigsqcup</primary></indexterm><literal>\bigsqcup</literal> -</term><listitem><para><inlineequation><mathphrase>\bigsqcup</mathphrase></inlineequation> +</term><listitem><para>⨆ Variable-sized, or n-ary, square union (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\biguplus</primary></indexterm><literal>\biguplus</literal> -</term><listitem><para><inlineequation><mathphrase>\biguplus</mathphrase></inlineequation> +</term><listitem><para>⨄ Variable-sized, or n-ary, union operator with a plus +(operator). (Note that the name has only one p.) </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigcap</primary></indexterm><literal>\bigcap</literal> -</term><listitem><para><inlineequation><mathphrase>\bigvee</mathphrase></inlineequation> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigvee</primary></indexterm><literal>\bigvee</literal> +</term><listitem><para>⋁ Variable-sized, or n-ary, logical-and (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigwedge</primary></indexterm><literal>\bigwedge</literal> -</term><listitem><para><inlineequation><mathphrase>\bigwedge</mathphrase></inlineequation> +</term><listitem><para>⋀ Variable-sized, or n-ary, logical-or (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bot</primary></indexterm><literal>\bot</literal> -</term><listitem><para><inlineequation><mathphrase>\bot</mathphrase></inlineequation> +</term><listitem><para>⊥ Up tack, bottom, least element of a poset, or a contradiction +(ordinary). See also <literal>\top</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bowtie</primary></indexterm><literal>\bowtie</literal> -</term><listitem><para><inlineequation><mathphrase>\bowtie</mathphrase></inlineequation> (relation) +</term><listitem><para>⋈ Natural join of two relations (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Box</primary></indexterm><literal>\Box</literal> -</term><listitem><para>(square open box symbol) <!-- xx not in plain --> +</term><listitem><para>□ Modal operator for necessity; square open box (ordinary). This +is not available in Plain &tex;. In &latex; you need to load the +<filename>amssymb</filename> package. +<!-- bb Best Unicode equivalent? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bullet</primary></indexterm><literal>\bullet</literal> </term><listitem><indexterm role="cp"><primary>bullet symbol</primary></indexterm> -<para><inlineequation><mathphrase>\bullet</mathphrase></inlineequation> (binary operation) +<para>• Bullet (binary). Similar: multiplication +dot <literal>\cdot</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cap</primary></indexterm><literal>\cap</literal> -</term><listitem><para><inlineequation><mathphrase>\cap</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∩ Intersection of two sets (binary). Similar: variable-sized +operator <literal>\bigcap</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cdot</primary></indexterm><literal>\cdot</literal> -</term><listitem><para><inlineequation><mathphrase>\cdot</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⋅ Multiplication (binary). Similar: Bullet +dot <literal>\bullet</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\chi</primary></indexterm><literal>\chi</literal> -</term><listitem><para><inlineequation><mathphrase>\chi</mathphrase></inlineequation> +</term><listitem><para>χ Lower case Greek chi (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\circ</primary></indexterm><literal>\circ</literal> -</term><listitem><para><inlineequation><mathphrase>\circ</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∘ Function composition, ring operator (binary). Similar: +variable-sized operator <literal>\bigcirc</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\clubsuit</primary></indexterm><literal>\clubsuit</literal> -</term><listitem><para><inlineequation><mathphrase>\clubsuit</mathphrase></inlineequation> +</term><listitem><para>♣ Club card suit (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\complement</primary></indexterm><literal>\complement</literal> +</term><listitem><para>∁ Set complement, used as a superscript as in +<literal>$S^\complement$</literal> (ordinary). This is not available in Plain +&tex;. In &latex; you should load the <filename>amssymb</filename> package. Also +used: <literal>$S^{\mathsf{c}}$</literal> or <literal>$\bar{S}$</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cong</primary></indexterm><literal>\cong</literal> -</term><listitem><para><inlineequation><mathphrase>\cong</mathphrase></inlineequation> (relation) +</term><listitem><para>≅ Congruent (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\coprod</primary></indexterm><literal>\coprod</literal> -</term><listitem><para><inlineequation><mathphrase>\coprod</mathphrase></inlineequation> +</term><listitem><para>∐ Coproduct (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cup</primary></indexterm><literal>\cup</literal> -</term><listitem><para><inlineequation><mathphrase>\cup</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∪ Union of two sets (binary). Similar: variable-sized +operator <literal>\bigcup</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dagger</primary></indexterm><literal>\dagger</literal> -</term><listitem><para><inlineequation><mathphrase>\dagger</mathphrase></inlineequation> (binary operation) +</term><listitem><para>† Dagger relation (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dashv</primary></indexterm><literal>\dashv</literal> -</term><listitem><para><inlineequation><mathphrase>\dashv</mathphrase></inlineequation> (relation) +</term><listitem><para>⊣ Dash with vertical, reversed turnstile (relation). Similar: +turnstile <literal>\vdash</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ddagger</primary></indexterm><literal>\ddagger</literal> -</term><listitem><para><inlineequation><mathphrase>\dagger</mathphrase></inlineequation> (binary operation) +</term><listitem><para>‡ Double dagger relation (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Delta</primary></indexterm><literal>\Delta</literal> -</term><listitem><para><inlineequation><mathphrase>\Delta</mathphrase></inlineequation> +</term><listitem><para>Δ Greek upper case delta, used for increment (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\delta</primary></indexterm><literal>\delta</literal> -</term><listitem><para><inlineequation><mathphrase>\delta</mathphrase></inlineequation> +</term><listitem><para>δ Greek lower case delta (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Diamond</primary></indexterm><literal>\Diamond</literal> -</term><listitem><para>bigger <inlineequation><mathphrase>\diamond</mathphrase></inlineequation> <!-- xx not in plain --> +</term><listitem><para>◇ Large diamond operator (ordinary). This is not available in +Plain &tex;. In &latex; you must load the <filename>amssymb</filename> package. +<!-- bb Best Unicode equivalent? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\diamond</primary></indexterm><literal>\diamond</literal> -</term><listitem><para><inlineequation><mathphrase>\diamond</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⋄ Diamond operator, or diamond bullet (binary). Similar: large +diamond <literal>\Diamond</literal>, circle bullet <literal>\bullet</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\diamondsuit</primary></indexterm><literal>\diamondsuit</literal> -</term><listitem><para><inlineequation><mathphrase>\diamondsuit</mathphrase></inlineequation> +</term><listitem><para>♢ Diamond card suit (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\div</primary></indexterm><literal>\div</literal> -</term><listitem><para><inlineequation><mathphrase>\div</mathphrase></inlineequation> (binary operation) +</term><listitem><para>÷ Division sign (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\doteq</primary></indexterm><literal>\doteq</literal> -</term><listitem><para><inlineequation><mathphrase>\doteq</mathphrase></inlineequation> (relation) +</term><listitem><para>≐ Approaches the limit (relation). Similar: geometrically equal +to <literal>\Doteq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\downarrow</primary></indexterm><literal>\downarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\downarrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>↓ Down arrow, converges (relation). Similar: double line down +arrow <literal>\Downarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Downarrow</primary></indexterm><literal>\Downarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Downarrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⇓ Double line down arrow (relation). Similar: single line down +arrow <literal>\downarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ell</primary></indexterm><literal>\ell</literal> -</term><listitem><para><inlineequation><mathphrase>\ell</mathphrase></inlineequation> +</term><listitem><para>ℓ Lower-case cursive letter l (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\emptyset</primary></indexterm><literal>\emptyset</literal> -</term><listitem><para><inlineequation><mathphrase>\emptyset</mathphrase></inlineequation> +</term><listitem><para>∅ Empty set symbol (ordinary). Similar: reversed empty +set <literal>\varnothing</literal>. +<!-- bb Why Unicode has \revemptyset but no \emptyset? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\epsilon</primary></indexterm><literal>\epsilon</literal> -</term><listitem><para><inlineequation><mathphrase>\epsilon</mathphrase></inlineequation> +</term><listitem><para>ϵ Lower case Greek-text letter (ordinary). More widely used in +mathematics is the curly epsilon +<literal>\varepsilon</literal> ε. Related: the set membership relation +<literal>\in</literal> ∈. +<!-- src: David Carlisle http://tex.stackexchange.com/a/98018/339 and --> +<!-- Unicode referenced there asserts varepsilon is much more widely used. --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\equiv</primary></indexterm><literal>\equiv</literal> -</term><listitem><para><inlineequation><mathphrase>\equiv</mathphrase></inlineequation> (relation) +</term><listitem><para>≡ Equivalence (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\eta</primary></indexterm><literal>\eta</literal> -</term><listitem><para><inlineequation><mathphrase>\eta</mathphrase></inlineequation> +</term><listitem><para>η Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\exists</primary></indexterm><literal>\exists</literal> -</term><listitem><para><inlineequation><mathphrase>\exists</mathphrase></inlineequation> +</term><listitem><para>∃ Existential quantifier (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\flat</primary></indexterm><literal>\flat</literal> -</term><listitem><para><inlineequation><mathphrase>\flat</mathphrase></inlineequation> +</term><listitem><para>♭ Musical flat (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\forall</primary></indexterm><literal>\forall</literal> -</term><listitem><para><inlineequation><mathphrase>\forall</mathphrase></inlineequation> +</term><listitem><para>∀ Universal quantifier (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\frown</primary></indexterm><literal>\frown</literal> -</term><listitem><para><inlineequation><mathphrase>\frown</mathphrase></inlineequation> (relation) +</term><listitem><para>⌢ Downward curving arc (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Gamma</primary></indexterm><literal>\Gamma</literal> -</term><listitem><para><inlineequation><mathphrase>\Gamma</mathphrase></inlineequation> +</term><listitem><para>Γ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\gamma</primary></indexterm><literal>\gamma</literal> -</term><listitem><para><inlineequation><mathphrase>\gamma</mathphrase></inlineequation> +</term><listitem><para>γ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ge</primary></indexterm><literal>\ge</literal> -</term><listitem><para><inlineequation><mathphrase>\ge</mathphrase></inlineequation> +</term><listitem><para>≥ Greater than or equal to (relation). This is a synonym +for <literal>\geq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\geq</primary></indexterm><literal>\geq</literal> -</term><listitem><para><inlineequation><mathphrase>\geq</mathphrase></inlineequation> (relation) +</term><listitem><para>≥ Greater than or equal to (relation). This is a synonym +for <literal>\ge</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\gets</primary></indexterm><literal>\gets</literal> -</term><listitem><para><inlineequation><mathphrase>\gets</mathphrase></inlineequation> +</term><listitem><para>← Is assigned the value (relation). +Synonym: <literal>\leftarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\gg</primary></indexterm><literal>\gg</literal> -</term><listitem><para><inlineequation><mathphrase>\gg</mathphrase></inlineequation> (relation) +</term><listitem><para>≫ Much greater than (relation). Similar: much less +than <literal>\ll</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hbar</primary></indexterm><literal>\hbar</literal> -</term><listitem><para><inlineequation><mathphrase>\hbar</mathphrase></inlineequation> +</term><listitem><para>ℏ Planck constant over two pi (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\heartsuit</primary></indexterm><literal>\heartsuit</literal> -</term><listitem><para><inlineequation><mathphrase>\heartsuit</mathphrase></inlineequation> +</term><listitem><para>♡ Heart card suit (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hookleftarrow</primary></indexterm><literal>\hookleftarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\hookleftarrow</mathphrase></inlineequation> +</term><listitem><para>↩ Hooked left arrow (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hookrightarrow</primary></indexterm><literal>\hookrightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\hookrightarrow</mathphrase></inlineequation> +</term><listitem><para>↪ Hooked right arrow (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\iff</primary></indexterm><literal>\iff</literal> -</term><listitem><para><inlineequation><mathphrase>\iff</mathphrase></inlineequation> +</term><listitem><para>⟷ If and only if (relation). It is <literal>\Longleftrightarrow</literal> +with a <literal>\thickmuskip</literal> on either side. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Im</primary></indexterm><literal>\Im</literal> -</term><listitem><para><inlineequation><mathphrase>\Im</mathphrase></inlineequation> +</term><listitem><para>ℑ Imaginary part (ordinary). See: real part <literal>\Re</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\in</primary></indexterm><literal>\in</literal> -</term><listitem><para><inlineequation><mathphrase>\in</mathphrase></inlineequation> (relation) +</term><listitem><para>∈ Set element (relation). See also: lower case Greek letter +epsilon <literal>\epsilon</literal>ϵ and rounded small +epsilon <literal>\varepsilon</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\infty</primary></indexterm><literal>\infty</literal> -</term><listitem><para><inlineequation><mathphrase>\infty</mathphrase></inlineequation> +</term><listitem><para>∞ Infinity (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\int</primary></indexterm><literal>\int</literal> -</term><listitem><para><inlineequation><mathphrase>\int</mathphrase></inlineequation> +</term><listitem><para>∫ Integral (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\iota</primary></indexterm><literal>\iota</literal> -</term><listitem><para><inlineequation><mathphrase>\iota</mathphrase></inlineequation> +</term><listitem><para>ι Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Join</primary></indexterm><literal>\Join</literal> -</term><listitem><para>condensed bowtie symbol (relation) <!-- xx not in plain --> +</term><listitem><para>⨝ Condensed bowtie symbol (relation). Not available in Plain +&tex;. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\kappa</primary></indexterm><literal>\kappa</literal> -</term><listitem><para><inlineequation><mathphrase>\kappa</mathphrase></inlineequation> +</term><listitem><para>κ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Lambda</primary></indexterm><literal>\Lambda</literal> -</term><listitem><para><inlineequation><mathphrase>\Lambda</mathphrase></inlineequation> +</term><listitem><para>Λ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lambda</primary></indexterm><literal>\lambda</literal> -</term><listitem><para><inlineequation><mathphrase>\lambda</mathphrase></inlineequation> +</term><listitem><para>λ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\land</primary></indexterm><literal>\land</literal> -</term><listitem><para><inlineequation><mathphrase>\land</mathphrase></inlineequation> +</term><listitem><para>∧ Logical and (binary). This is a synonym for <literal>\wedge</literal>. +See also logical or <literal>\lor</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\langle</primary></indexterm><literal>\langle</literal> -</term><listitem><para><inlineequation><mathphrase>\langle</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⟨ Left angle, or sequence, bracket (opening). Similar: +less-than <literal><</literal>. Matches <literal>\rangle</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lbrace</primary></indexterm><literal>\lbrace</literal> -</term><listitem><para><inlineequation><mathphrase>\lbrace</mathphrase></inlineequation> (delimiter) +</term><listitem><para>{ Left curly brace +(opening). Synonym: <literal>\{</literal>. Matches <literal>\rbrace</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lbrack</primary></indexterm><literal>\lbrack</literal> -</term><listitem><para><inlineequation><mathphrase>\lbrack</mathphrase></inlineequation> (delimiter) +</term><listitem><para>[ Left square bracket (opening). +Synonym: <literal>[</literal>. Matches <literal>\rbrack</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lceil</primary></indexterm><literal>\lceil</literal> -</term><listitem><para><inlineequation><mathphrase>\lceil</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⌈ Left ceiling bracket, like a square bracket but with the bottom +shaved off (opening). Matches <literal>\rceil</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\le</primary></indexterm><literal>\le</literal> -</term><listitem><para><inlineequation><mathphrase>\le</mathphrase></inlineequation> +</term><listitem><para>≤ Less than or equal to (relation). This is a synonym +for <literal>\leq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leadsto</primary></indexterm><literal>\leadsto</literal> -</term><listitem><!-- xx missing from plain --> - +</term><listitem><para>⇝ Squiggly right arrow (relation). This is not available in +Plain &tex;. In &latex; you should load the <filename>amssymb</filename> package. +To get this symbol outside of math mode you can put +<literal>\newcommand*{\Leadsto}{\ensuremath{\leadsto}}</literal> in the +preamble and then use <literal>\Leadsto</literal> instead. +<!-- bb Best Unicode equivalent? --> +</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Leftarrow</primary></indexterm><literal>\Leftarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Leftarrow</mathphrase></inlineequation> +</term><listitem><para>⇐ Is implied by, double-line left arrow (relation). Similar: +single-line left arrow <literal>\leftarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftarrow</primary></indexterm><literal>\leftarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\leftarrow</mathphrase></inlineequation> +</term><listitem><para>← Single-line left arrow (relation). +Synonym: <literal>\gets</literal>. Similar: double-line left +arrow <literal>\Leftarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftharpoondown</primary></indexterm><literal>\leftharpoondown</literal> -</term><listitem><para><inlineequation><mathphrase>\leftharpoondown</mathphrase></inlineequation> +</term><listitem><para>↽ Single-line left harpoon, barb under bar (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftharpoonup</primary></indexterm><literal>\leftharpoonup</literal> -</term><listitem><para><inlineequation><mathphrase>\leftharpoonup</mathphrase></inlineequation> +</term><listitem><para>↼ Single-line left harpoon, barb over bar (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Leftrightarrow</primary></indexterm><literal>\Leftrightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Leftrightarrow</mathphrase></inlineequation> +</term><listitem><para>⇔ Bi-implication; double-line double-headed arrow (relation). +Similar: single-line double headed arrow <literal>\leftrightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftrightarrow</primary></indexterm><literal>\leftrightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\leftrightarrow</mathphrase></inlineequation> +</term><listitem><para>↔ Single-line double-headed arrow (relation). Similar: +double-line double headed arrow <literal>\Leftrightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leq</primary></indexterm><literal>\leq</literal> -</term><listitem><para><inlineequation><mathphrase>\leq</mathphrase></inlineequation> (relation) +</term><listitem><para>≤ Less than or equal to (relation). This is a synonym +for <literal>\le</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lfloor</primary></indexterm><literal>\lfloor</literal> -</term><listitem><para><inlineequation><mathphrase>\lfloor</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⌊ Left floor bracket (opening). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lhd</primary></indexterm><literal>\lhd</literal> -</term><listitem><para>(left-pointing arrow head) <!-- xx not in plain --> +</term><listitem><para>◁ Arrowhead, that is, triangle, pointing left (binary). This is +not available in Plain &tex;. In &latex; you should load the +<filename>amssymb</filename> package. For the normal subgroup symbol you should load +<filename>amssymb</filename> and use <literal>\vartriangleleft</literal> (which is a relation +and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ll</primary></indexterm><literal>\ll</literal> -</term><listitem><para><inlineequation><mathphrase>\ll</mathphrase></inlineequation> (relation) +</term><listitem><para>≪ Much less than (relation). Similar: much greater +than <literal>\gg</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lnot</primary></indexterm><literal>\lnot</literal> -</term><listitem><para><inlineequation><mathphrase>\lnot</mathphrase></inlineequation> +</term><listitem><para>¬ Logical negation (ordinary). Synonym: <literal>\neg</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\longleftarrow</primary></indexterm><literal>\longleftarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\longleftarrow</mathphrase></inlineequation> +</term><listitem><para>⟵ Long single-line left arrow (relation). Similar: long +double-line left arrow <literal>\Longleftarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\longleftrightarrow</primary></indexterm><literal>\longleftrightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\longleftrightarrow</mathphrase></inlineequation> +</term><listitem><para>⟷ Long single-line double-headed arrow (relation). Similar: long +double-line double-headed arrow <literal>\Longleftrightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\longmapsto</primary></indexterm><literal>\longmapsto</literal> -</term><listitem><para><inlineequation><mathphrase>\longmapsto</mathphrase></inlineequation> +</term><listitem><para>⟼ Long single-line left arrow starting with vertical bar +(relation). Similar: shorter version <literal>\mapsto</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\longrightarrow</primary></indexterm><literal>\longrightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\longrightarrow</mathphrase></inlineequation> +</term><listitem><para>⟶ Long single-line right arrow (relation). Similar: long +double-line right arrow <literal>\Longrightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lor</primary></indexterm><literal>\lor</literal> -</term><listitem><para><inlineequation><mathphrase>\lor</mathphrase></inlineequation> +</term><listitem><para>∨ Logical or (binary). Synonym: wedge <literal>\wedge</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mapsto</primary></indexterm><literal>\mapsto</literal> -</term><listitem><para><inlineequation><mathphrase>\mapsto</mathphrase></inlineequation> +</term><listitem><para>↦ Single-line left arrow starting with vertical bar (relation). +Similar: longer version <literal>\longmapsto</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mho</primary></indexterm><literal>\mho</literal> -</term><listitem><!-- xx not in plain --> - +</term><listitem><para>℧ Conductance, half-circle rotated capital omega (ordinary). +This is not available in Plain &tex;. In &latex; you should load the +<filename>amssymb</filename> package. +</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mid</primary></indexterm><literal>\mid</literal> -</term><listitem><para><inlineequation><mathphrase>\mid</mathphrase></inlineequation> (relation) +</term><listitem><para>∣ Single-line vertical bar (relation). A typical use of +<literal>\mid</literal> is for a set <literal>\{\, x \mid x\geq 5 \,\}</literal>. +</para> +<para>Similar: <literal>\vert</literal> and <literal>|</literal> produce the same single-line +vertical bar symbol but without any spacing (they fall in class +ordinary) and you should not use them as relations but instead only as +ordinals, i.e., footnote symbols. For absolute value, see the entry +for <literal>\vert</literal> and for norm see the entry for <literal>\Vert</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\models</primary></indexterm><literal>\models</literal> -</term><listitem><para><inlineequation><mathphrase>\models</mathphrase></inlineequation> (relation) +</term><listitem><para>⊨ Entails, or satisfies; double turnstile, short double dash +(relation). Similar: long double dash <literal>\vDash</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mp</primary></indexterm><literal>\mp</literal> -</term><listitem><para><inlineequation><mathphrase>\mp</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∓ Minus or plus (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mu</primary></indexterm><literal>\mu</literal> -</term><listitem><para><inlineequation><mathphrase>\mu</mathphrase></inlineequation> +</term><listitem><para>μ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nabla</primary></indexterm><literal>\nabla</literal> -</term><listitem><para><inlineequation><mathphrase>\nabla</mathphrase></inlineequation> +</term><listitem><para>∇ Hamilton’s del, or differential, operator (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\natural</primary></indexterm><literal>\natural</literal> -</term><listitem><para><inlineequation><mathphrase>\natural</mathphrase></inlineequation> +</term><listitem><para>♮ Musical natural notation (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ne</primary></indexterm><literal>\ne</literal> -</term><listitem><para><inlineequation><mathphrase>\ne</mathphrase></inlineequation> +</term><listitem><para>≠ Not equal (relation). Synonym: <literal>\neq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nearrow</primary></indexterm><literal>\nearrow</literal> -</term><listitem><para><inlineequation><mathphrase>\nearrow</mathphrase></inlineequation> +</term><listitem><para>↗ North-east arrow (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\neg</primary></indexterm><literal>\neg</literal> -</term><listitem><para><inlineequation><mathphrase>\neg</mathphrase></inlineequation> +</term><listitem><para>¬ Logical negation (ordinary). +Synonym: <literal>\lnot</literal>. Sometimes instead used for +negation: <literal>\sim</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\neq</primary></indexterm><literal>\neq</literal> -</term><listitem><para><inlineequation><mathphrase>\neq</mathphrase></inlineequation> (relation) +</term><listitem><para>≠ Not equal (relation). Synonym: <literal>\ne</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ni</primary></indexterm><literal>\ni</literal> -</term><listitem><para><inlineequation><mathphrase>\ni</mathphrase></inlineequation> (relation) +</term><listitem><para>∋ Reflected membership epsilon; has the member +(relation). Synonym: <literal>\owns</literal>. Similar: is a member +of <literal>\in</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\not</primary></indexterm><literal>\not</literal> -</term><listitem><para>Overstrike a following operator with a /, as in <inlineequation><mathphrase>\not=</mathphrase></inlineequation>. +</term><listitem><para>  ̸ Long solidus, or slash, used to overstrike a +following operator (relation). +<!-- Need blank space for it to overstrike --> +</para> +<para>Many negated operators that don’t require <literal>\not</literal> are available, +particularly with the <filename>amssymb</filename> package. For example, <literal>\notin</literal> +is probably typographically preferable to <literal>\not\in</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\notin</primary></indexterm><literal>\notin</literal> -</term><listitem><para><inlineequation><mathphrase>\ni</mathphrase></inlineequation> +</term><listitem><para>∉ Not an element of (relation). Similar: not subset +of <literal>\nsubseteq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nu</primary></indexterm><literal>\nu</literal> -</term><listitem><para><inlineequation><mathphrase>\nu</mathphrase></inlineequation> +</term><listitem><para>ν Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nwarrow</primary></indexterm><literal>\nwarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\nwarrow</mathphrase></inlineequation> +</term><listitem><para>↖ North-west arrow (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\odot</primary></indexterm><literal>\odot</literal> -</term><listitem><para><inlineequation><mathphrase>\odot</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊙ Dot inside a circle (binary). Similar: variable-sized +operator <literal>\bigodot</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\oint</primary></indexterm><literal>\oint</literal> -</term><listitem><para><inlineequation><mathphrase>\oint</mathphrase></inlineequation> +</term><listitem><para>∮ Contour integral, integral with circle in the middle (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Omega</primary></indexterm><literal>\Omega</literal> -</term><listitem><para><inlineequation><mathphrase>\Omega</mathphrase></inlineequation> +</term><listitem><para>Ω Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\omega</primary></indexterm><literal>\omega</literal> -</term><listitem><para><inlineequation><mathphrase>\omega</mathphrase></inlineequation> +</term><listitem><para>ω Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ominus</primary></indexterm><literal>\ominus</literal> -</term><listitem><para><inlineequation><mathphrase>\ominus</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊖ Minus sign, or dash, inside a circle (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\oplus</primary></indexterm><literal>\oplus</literal> -</term><listitem><para><inlineequation><mathphrase>\oplus</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊕ Plus sign inside a circle (binary). Similar: variable-sized +operator <literal>\bigoplus</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\oslash</primary></indexterm><literal>\oslash</literal> -</term><listitem><para><inlineequation><mathphrase>\oslash</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊘ Solidus, or slash, inside a circle (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\otimes</primary></indexterm><literal>\otimes</literal> -</term><listitem><para><inlineequation><mathphrase>\otimes</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊗ Times sign, or cross, inside a circle (binary). Similar: +variable-sized operator <literal>\bigotimes</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\owns</primary></indexterm><literal>\owns</literal> -</term><listitem><para><inlineequation><mathphrase>\owns</mathphrase></inlineequation> +</term><listitem><para>∋ Reflected membership epsilon; has the member +(relation). Synonym: <literal>\ni</literal>. Similar: is a member +of <literal>\in</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parallel</primary></indexterm><literal>\parallel</literal> -</term><listitem><para><inlineequation><mathphrase>\parallel</mathphrase></inlineequation> (relation) +</term><listitem><para>∥ Parallel (relation). Synonym: <literal>\|</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partial</primary></indexterm><literal>\partial</literal> -</term><listitem><para><inlineequation><mathphrase>\partial</mathphrase></inlineequation> +</term><listitem><para>∂ Partial differential (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\perp</primary></indexterm><literal>\perp</literal> -</term><listitem><para><inlineequation><mathphrase>\perp</mathphrase></inlineequation> (relation) +</term><listitem><para>⟂ Perpendicular (relation). Similar: <literal>\bot</literal> uses the +same glyph but the spacing is different because it is in the class +ordinary. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\phi</primary></indexterm><literal>\phi</literal> -</term><listitem><para><inlineequation><mathphrase>\phi</mathphrase></inlineequation> +</term><listitem><para>ϕ Lower case Greek letter (ordinary). The variant form is +<literal>\varphi</literal> φ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Pi</primary></indexterm><literal>\Pi</literal> -</term><listitem><para><inlineequation><mathphrase>\Pi</mathphrase></inlineequation> +</term><listitem><para>Π Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pi</primary></indexterm><literal>\pi</literal> -</term><listitem><para><inlineequation><mathphrase>\pi</mathphrase></inlineequation> +</term><listitem><para>π Lower case Greek letter (ordinary). The variant form is +<literal>\varpi</literal> ϖ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pm</primary></indexterm><literal>\pm</literal> -</term><listitem><para><inlineequation><mathphrase>\pm</mathphrase></inlineequation> (binary operation) +</term><listitem><para>± Plus or minus (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prec</primary></indexterm><literal>\prec</literal> -</term><listitem><para><inlineequation><mathphrase>\prec</mathphrase></inlineequation> (relation) +</term><listitem><para>≺ Preceeds (relation). Similar: less than <literal><</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\preceq</primary></indexterm><literal>\preceq</literal> -</term><listitem><para><inlineequation><mathphrase>\preceq</mathphrase></inlineequation> (relation) +</term><listitem><para>⪯ Preceeds or equals (relation). Similar: less than or +equals <literal>\leq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prime</primary></indexterm><literal>\prime</literal> -</term><listitem><para><inlineequation><mathphrase>\prime</mathphrase></inlineequation> +</term><listitem><para>′ Prime, or minute in a time expression (ordinary). Typically +used as a superscript <literal>$A^\prime$</literal>. Note that <literal>$f^\prime$</literal> +and <literal>$f'$</literal> produce the same result. An advantage of the second is +that <literal>$f'''$</literal> produces the the desired symbol, that is, the same +result as <literal>$f^{\prime\prime\prime}$</literal>, but uses somewhat less +typing. Note that you can only use <literal>\prime</literal> in math mode but you +can type right single quote <literal>'</literal> in text mode also, although it +resuts in a different look than in math mode. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prod</primary></indexterm><literal>\prod</literal> -</term><listitem><para><inlineequation><mathphrase>\prod</mathphrase></inlineequation> +</term><listitem><para>∏ Product (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\propto</primary></indexterm><literal>\propto</literal> -</term><listitem><para><inlineequation><mathphrase>\propto</mathphrase></inlineequation> (relation) +</term><listitem><para>∝ Is proportional to (relation) </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Psi</primary></indexterm><literal>\Psi</literal> -</term><listitem><para><inlineequation><mathphrase>\Psi</mathphrase></inlineequation> +</term><listitem><para>Ψ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\psi</primary></indexterm><literal>\psi</literal> -</term><listitem><para><inlineequation><mathphrase>\psi</mathphrase></inlineequation> +</term><listitem><para>ψ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rangle</primary></indexterm><literal>\rangle</literal> -</term><listitem><para><inlineequation><mathphrase>\rangle</mathphrase></inlineequation> (delimiter) +</term><listitem><para>➹ Right angle, or sequence, bracket (closing). Similar: greater +than <literal>></literal>. Matches:<literal>\langle</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rbrace</primary></indexterm><literal>\rbrace</literal> -</term><listitem><para><inlineequation><mathphrase>\rbrace</mathphrase></inlineequation> (delimiter) +</term><listitem><para>} Right curly brace +(closing). Synonym: <literal>\}</literal>. Matches <literal>\lbrace</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rbrack</primary></indexterm><literal>\rbrack</literal> -</term><listitem><para><inlineequation><mathphrase>\rbrack</mathphrase></inlineequation> (delimiter) +</term><listitem><para>] Right square bracket +(closing). Synonym: <literal>]</literal>. Matches <literal>\lbrack</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rceil</primary></indexterm><literal>\rceil</literal> -</term><listitem><para><inlineequation><mathphrase>\rceil</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⌉ Right ceiling bracket (closing). Matches <literal>\lceil</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Re</primary></indexterm><literal>\Re</literal> -</term><listitem><para><inlineequation><mathphrase>\Re</mathphrase></inlineequation> +</term><listitem><para>ℜ Real part, real numbers, cursive capital R (ordinary). Related: +double-line, or blackboard bold, R <literal>\mathbb{R}</literal>; to access +this, load the <filename>amsfonts</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\restriction</primary></indexterm><literal>\restriction</literal> +</term><listitem><para>↾ Restriction of a function +(relation). Synonym: <literal>\upharpoonright</literal>. Not available in +Plain &tex;. In &latex; you should load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rfloor</primary></indexterm><literal>\rfloor</literal> -</term><listitem><para><inlineequation><mathphrase>\rfloor</mathphrase></inlineequation> +</term><listitem><para>⌋ Right floor bracket, a right square bracket with the top cut +off (closing). Matches <literal>\lfloor</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rhd</primary></indexterm><literal>\rhd</literal> -</term><listitem><para>(binary operation) <!-- xx not in plain @math{\rhd} --> +</term><listitem><para>◁ Arrowhead, that is, triangle, pointing right (binary). This is +not available in Plain &tex;. In &latex; you should load the +<filename>amssymb</filename> package. For the normal subgroup symbol you should +instead load <filename>amssymb</filename> and use <literal>\vartriangleright</literal> (which +is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rho</primary></indexterm><literal>\rho</literal> -</term><listitem><para><inlineequation><mathphrase>\rho</mathphrase></inlineequation> +</term><listitem><para>ρ Lower case Greek letter (ordinary). The variant form is +<literal>\varrho</literal> ϱ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Rightarrow</primary></indexterm><literal>\Rightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Rightarrow</mathphrase></inlineequation> +</term><listitem><para>⇒ Implies, right-pointing double line arrow (relation). Similar: +right single-line arrow <literal>\rightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightarrow</primary></indexterm><literal>\rightarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\rightarrow</mathphrase></inlineequation> +</term><listitem><para>→ Right-pointing single line arrow (relation). Synonym: <literal>\to</literal>. Similar: right double line arrow <literal>\Rightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightharpoondown</primary></indexterm><literal>\rightharpoondown</literal> -</term><listitem><para><inlineequation><mathphrase>\rightharpoondown</mathphrase></inlineequation> +</term><listitem><para>⇁ Right-pointing harpoon with barb below the line (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightharpoonup</primary></indexterm><literal>\rightharpoonup</literal> -</term><listitem><para><inlineequation><mathphrase>\rightharpoonup</mathphrase></inlineequation> +</term><listitem><para>⇀ Right-pointing harpoon with barb above the line (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightleftharpoons</primary></indexterm><literal>\rightleftharpoons</literal> -</term><listitem><para><inlineequation><mathphrase>\rightleftharpoons</mathphrase></inlineequation> +</term><listitem><para>⇌ Right harpoon up above left harpoon down (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\searrow</primary></indexterm><literal>\searrow</literal> -</term><listitem><para><inlineequation><mathphrase>\searrow</mathphrase></inlineequation> +</term><listitem><para>↘ Arrow pointing southeast (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\setminus</primary></indexterm><literal>\setminus</literal> -</term><listitem><para><inlineequation><mathphrase>\setminus</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⧵ Set difference, reverse solidus or slash, like \ +(binary). Similar: backslash <literal>\backslash</literal> and also +<literal>\textbackslash</literal> outside of math mode. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sharp</primary></indexterm><literal>\sharp</literal> -</term><listitem><para><inlineequation><mathphrase>\sharp</mathphrase></inlineequation> +</term><listitem><para>♯ Musical sharp (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Sigma</primary></indexterm><literal>\Sigma</literal> -</term><listitem><para><inlineequation><mathphrase>\Sigma</mathphrase></inlineequation> +</term><listitem><para>Σ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sigma</primary></indexterm><literal>\sigma</literal> -</term><listitem><para><inlineequation><mathphrase>\sigma</mathphrase></inlineequation> +</term><listitem><para>σ Lower case Greek letter (ordinary). The variant form is +<literal>\varsigma</literal> ς. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sim</primary></indexterm><literal>\sim</literal> -</term><listitem><para><inlineequation><mathphrase>\sim</mathphrase></inlineequation> (relation) +</term><listitem><para>∼ Similar, in a relation (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\simeq</primary></indexterm><literal>\simeq</literal> -</term><listitem><para><inlineequation><mathphrase>\simeq</mathphrase></inlineequation> (relation) +</term><listitem><para>≃ Similar or equal to, in a relation (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\smallint</primary></indexterm><literal>\smallint</literal> -</term><listitem><para><inlineequation><mathphrase>\smallint</mathphrase></inlineequation> +</term><listitem><para>∫ Integral sign that does not change to a larger size in a +display (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\smile</primary></indexterm><literal>\smile</literal> -</term><listitem><para><inlineequation><mathphrase>\smile</mathphrase></inlineequation> (relation) +</term><listitem><para>⌣ Upward curving arc (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\spadesuit</primary></indexterm><literal>\spadesuit</literal> -</term><listitem><para><inlineequation><mathphrase>\spadesuit</mathphrase></inlineequation> +</term><listitem><para>♠ Spade card suit (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqcap</primary></indexterm><literal>\sqcap</literal> -</term><listitem><para><inlineequation><mathphrase>\sqcap</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊓ Square intersection symbol (binary). Similar: +intersection <literal>cap</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqcup</primary></indexterm><literal>\sqcup</literal> -</term><listitem><para><inlineequation><mathphrase>\sqcup</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊔ Square union symbol (binary). Similar: +union <literal>cup</literal>. Related: variable-sized +operator <literal>\bigsqcup</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubset</primary></indexterm><literal>\sqsubset</literal> -</term><listitem><para>(relation) <!-- not in plain (@math{\sqsubset}) --> +</term><listitem><para>⊏ Square subset symbol (relation). Similar: +subset <literal>\subset</literal>. This is not available in Plain &tex;. In +&latex; you should load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubseteq</primary></indexterm><literal>\sqsubseteq</literal> -</term><listitem><para><inlineequation><mathphrase>\sqsubseteq</mathphrase></inlineequation> (relation) +</term><listitem><para>⊑ Square subset or equal symbol (binary). Similar: subset or +equal to <literal>\subseteq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupset</primary></indexterm><literal>\sqsupset</literal> -</term><listitem><para>(relation) <!-- not in plain (@math{\sqsupset}) --> +</term><listitem><para>⊐ Square superset symbol (relation). Similar: +superset <literal>\supset</literal>. This is not available in Plain &tex;. In +&latex; you should load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupseteq</primary></indexterm><literal>\sqsupseteq</literal> -</term><listitem><para><inlineequation><mathphrase>\sqsupseteq</mathphrase></inlineequation> (relation) +</term><listitem><para>⊒ Square superset or equal symbol (binary). Similar: superset or +equal <literal>\supseteq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\star</primary></indexterm><literal>\star</literal> -</term><listitem><para><inlineequation><mathphrase>\star</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⋆ Five-pointed star, sometimes used as a general binary operation +but sometimes reserved for cross-correlation (binary). Similar: the +synonyms asterisk <literal>*</literal> and <literal>\ast</literal>, which are six-pointed, +and more often appear as a superscript or subscript, as with the Kleene +star. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\subset</primary></indexterm><literal>\subset</literal> -</term><listitem><para><inlineequation><mathphrase>\subset</mathphrase></inlineequation> (relation) +</term><listitem><para>⊂ Subset (occasionally, is implied by) (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\subseteq</primary></indexterm><literal>\subseteq</literal> -</term><listitem><para><inlineequation><mathphrase>\subseteq</mathphrase></inlineequation> (relation) +</term><listitem><para>⊆ Subset or equal to (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\succ</primary></indexterm><literal>\succ</literal> -</term><listitem><para><inlineequation><mathphrase>\succ</mathphrase></inlineequation> (relation) +</term><listitem><para>≻ Comes after, succeeds (relation). Similar: is less +than <literal>></literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\succeq</primary></indexterm><literal>\succeq</literal> -</term><listitem><para><inlineequation><mathphrase>\succeq</mathphrase></inlineequation> (relation) +</term><listitem><para>⪰ Succeeds or is equal to (relation). Similar: less +than or equal to <literal>\leq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sum</primary></indexterm><literal>\sum</literal> -</term><listitem><para><inlineequation><mathphrase>\sum</mathphrase></inlineequation> +</term><listitem><para>∑ Summation (operator). Similar: Greek capital +sigma <literal>\Sigma</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\supset</primary></indexterm><literal>\supset</literal> -</term><listitem><para><inlineequation><mathphrase>\supset</mathphrase></inlineequation> (relation) +</term><listitem><para>⊃ Superset (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\supseteq</primary></indexterm><literal>\supseteq</literal> -</term><listitem><para><inlineequation><mathphrase>\supseteq</mathphrase></inlineequation> (relation) +</term><listitem><para>⊇ Superset or equal to (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\surd</primary></indexterm><literal>\surd</literal> -</term><listitem><para><inlineequation><mathphrase>\surd</mathphrase></inlineequation> +</term><listitem><para>√ Radical symbol (ordinary). The &latex; command +<literal>\sqrt{..}</literal> typesets the square root of the argument, with a bar +that extends to cover the argument. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\swarrow</primary></indexterm><literal>\swarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\swarrow</mathphrase></inlineequation> +</term><listitem><para>↙ Southwest-pointing arrow (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tau</primary></indexterm><literal>\tau</literal> -</term><listitem><para><inlineequation><mathphrase>\tau</mathphrase></inlineequation> +</term><listitem><para>τ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\theta</primary></indexterm><literal>\theta</literal> -</term><listitem><para><inlineequation><mathphrase>\theta</mathphrase></inlineequation> +</term><listitem><para>θ Lower case Greek letter (ordinary). The variant form is +<literal>\vartheta</literal> ϑ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\times</primary></indexterm><literal>\times</literal> -</term><listitem><para><inlineequation><mathphrase>\times</mathphrase></inlineequation> (binary operation) +</term><listitem><para>× Primary school multiplication sign (binary). See +also <literal>\cdot</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\to</primary></indexterm><literal>\to</literal> -</term><listitem><para><inlineequation><mathphrase>\to</mathphrase></inlineequation> +</term><listitem><para>→ Right-pointing single line arrow (relation). +Synonym: <literal>\rightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\top</primary></indexterm><literal>\top</literal> -</term><listitem><para><inlineequation><mathphrase>\top</mathphrase></inlineequation> +</term><listitem><para>⊤ Top, greatest element of a poset (ordinary). See +also <literal>\bot</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangle</primary></indexterm><literal>\triangle</literal> -</term><listitem><para><inlineequation><mathphrase>\triangle</mathphrase></inlineequation> +</term><listitem><para>△ Triangle (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangleleft</primary></indexterm><literal>\triangleleft</literal> -</term><listitem><para><inlineequation><mathphrase>\triangleleft</mathphrase></inlineequation> (binary operation) +</term><listitem><para>◁ Not-filled triangle pointing left +(binary). Similar: <literal>\lhd</literal>. For the normal subgroup symbol you +should load <filename>amssymb</filename> and use <literal>\vartriangleleft</literal> (which +is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangleright</primary></indexterm><literal>\triangleright</literal> -</term><listitem><para><inlineequation><mathphrase>\triangleright</mathphrase></inlineequation> (binary operation) +</term><listitem><para>▷ Not-filled triangle pointing right (binary). For the normal +subgroup symbol you should instead load <filename>amssymb</filename> and +use <literal>\vartriangleright</literal> (which is a relation and so gives +better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unlhd</primary></indexterm><literal>\unlhd</literal> -</term><listitem><para>left-pointing arrowhead with line under (binary operation) <!-- not in plain --> +</term><listitem><para>⊴ Left-pointing not-filled arrowhead, that is, triangle, with a +line under (binary). This is not available in Plain &tex;. In &latex; +you should load the <filename>amssymb</filename> package. For the normal subgroup +symbol load <filename>amssymb</filename> and use <literal>\vartrianglelefteq</literal> (which +is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unrhd</primary></indexterm><literal>\unrhd</literal> -</term><listitem><para>right-pointing arrowhead with line under (binary operation) <!-- not in plain --> +</term><listitem><para>⊵ Right-pointing not-filled arrowhead, that is, triangle, with a +line under (binary). This is not available in Plain &tex;. In &latex; +you should load the <filename>amssymb</filename> package. For the normal subgroup +symbol load <filename>amssymb</filename> and use <literal>\vartrianglerighteq</literal> +(which is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Uparrow</primary></indexterm><literal>\Uparrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Uparrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⇑ Double-line upward-pointing arrow (relation). Similar: +single-line up-pointing arrow <literal>\uparrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\uparrow</primary></indexterm><literal>\uparrow</literal> -</term><listitem><para><inlineequation><mathphrase>\uparrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>↑ Single-line upward-pointing arrow, diverges (relation). Similar: +double-line up-pointing arrow <literal>\Uparrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Updownarrow</primary></indexterm><literal>\Updownarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\Updownarrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>⇕ Double-line upward-and-downward-pointing arrow (relation). Similar: +single-line upward-and-downward-pointing arrow <literal>\updownarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\updownarrow</primary></indexterm><literal>\updownarrow</literal> -</term><listitem><para><inlineequation><mathphrase>\updownarrow</mathphrase></inlineequation> (delimiter) +</term><listitem><para>↕ Single-line upward-and-downward-pointing arrow (relation). Similar: +double-line upward-and-downward-pointing arrow <literal>\Updownarrow</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\upharpoonright</primary></indexterm><literal>\upharpoonright</literal> +</term><listitem><para>↾ Up harpoon, with barb on right side +(relation). Synonym: <literal>\restriction</literal>. Not available in Plain +&tex;. In &latex; you should load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\uplus</primary></indexterm><literal>\uplus</literal> -</term><listitem><para><inlineequation><mathphrase>\uplus</mathphrase></inlineequation> (binary operation) +</term><listitem><para>⊎ Multiset union, a union symbol with a plus symbol in the middle +(binary). Similar: union <literal>\cup</literal>. Related: variable-sized +operator <literal>\biguplus</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Upsilon</primary></indexterm><literal>\Upsilon</literal> -</term><listitem><para><inlineequation><mathphrase>\Upsilon</mathphrase></inlineequation> +</term><listitem><para>Υ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\upsilon</primary></indexterm><literal>\upsilon</literal> -</term><listitem><para><inlineequation><mathphrase>\upsilon</mathphrase></inlineequation> +</term><listitem><para>υ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varepsilon</primary></indexterm><literal>\varepsilon</literal> -</term><listitem><para><inlineequation><mathphrase>\varepsilon</mathphrase></inlineequation> +</term><listitem><para>ε Rounded small epsilon (ordinary). This is more widely used in +mathematics than the non-variant lower case Greek-text letter form +<literal>\epsilon</literal> ϵ. Related: set membership <literal>\in</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varphi</primary></indexterm><literal>\varphi</literal> -</term><listitem><para><inlineequation><mathphrase>\varphi</mathphrase></inlineequation> +</term><listitem><para>φ Variant on the lower case Greek letter (ordinary). The +non-variant form is <literal>\phi</literal> ϕ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varpi</primary></indexterm><literal>\varpi</literal> -</term><listitem><para><inlineequation><mathphrase>\varpi</mathphrase></inlineequation> +</term><listitem><para>ϖ Variant on the lower case Greek letter (ordinary). The +non-variant form is <literal>\pi</literal> π. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varrho</primary></indexterm><literal>\varrho</literal> -</term><listitem><para><inlineequation><mathphrase>\varrho</mathphrase></inlineequation> +</term><listitem><para>ϱ Variant on the lower case Greek letter (ordinary). The +non-variant form is <literal>\rho</literal> ρ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varsigma</primary></indexterm><literal>\varsigma</literal> -</term><listitem><para><inlineequation><mathphrase>\varsigma</mathphrase></inlineequation> +</term><listitem><para>ς Variant on the lower case Greek letter (ordinary). The +non-variant form is <literal>\sigma</literal> σ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vartheta</primary></indexterm><literal>\vartheta</literal> -</term><listitem><para><inlineequation><mathphrase>\vartheta</mathphrase></inlineequation> +</term><listitem><para>ϑ Variant on the lower case Greek letter (ordinary). The +non-variant form is <literal>\theta</literal> θ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vdash</primary></indexterm><literal>\vdash</literal> -</term><listitem><para><inlineequation><mathphrase>\vdash</mathphrase></inlineequation> (relation) +</term><listitem><para>⊢ Provable; turnstile, vertical and a dash (relation). Similar: +turnstile rotated a half-circle <literal>\dashv</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vee</primary></indexterm><literal>\vee</literal> -</term><listitem><para><inlineequation><mathphrase>\vee</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∨ Logical or; a downwards v shape (binary). Related: logical +and <literal>\wedge</literal>. Similar: variable-sized +operator <literal>\bigvee</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Vert</primary></indexterm><literal>\Vert</literal> -</term><listitem><para><inlineequation><mathphrase>\Vert</mathphrase></inlineequation> (delimiter) +</term><listitem><para>‖ Vertical double bar (ordinary). Similar: vertical single +bar <literal>\vert</literal>. +</para> +<para>For a norm you can use the <filename>mathtools</filename> package and add +<literal>\DeclarePairedDelimiter\norm{\lVert}{\rVert}</literal> to your +preamble. This gives you three command variants for double-line vertical +bars that are correctly horizontally spaced: if in the document body you +write the starred version <literal>$\norm*{M^\perp}$</literal> then the height of +the vertical bars will match the height of the argument, whereas with +<literal>\norm{M^\perp}</literal> the bars do not grow with the height of the +argument but instead are the default height, and <literal>\norm[<replaceable>size +command</replaceable>]{M^\perp}</literal> also gives bars that do not grow but are set to +the size given in the <replaceable>size command</replaceable>, e.g., <literal>\Bigg</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vert</primary></indexterm><literal>\vert</literal> -</term><listitem><para><inlineequation><mathphrase>\vert</mathphrase></inlineequation> (delimiter) +</term><listitem><para>| Single line vertical bar (ordinary). Similar: double-line +vertical bar <literal>\Vert</literal>. For such that, as in the definition of a +set, use <literal>\mid</literal> because it is a relation. +</para> +<para>For absolute value you can use the <filename>mathtools</filename> package and add +<literal>\DeclarePairedDelimiter\abs{\lvert}{\rvert}</literal> to your +preamble. This gives you three command variants for single-line vertical +bars that are correctly horizontally spaced: if in the document body you +write the starred version <literal>$\abs*{\frac{22}{7}}$</literal> then the +height of the vertical bars will match the height of the argument, +whereas with <literal>\abs{\frac{22}{7}}</literal> the bars do not grow with +the height of the argument but instead are the default height, and +<literal>\abs[<replaceable>size command</replaceable>]{\frac{22}{7}}</literal> also gives bars +that do not grow but are set to the size given in the <replaceable>size +command</replaceable>, e.g., <literal>\Bigg</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\wedge</primary></indexterm><literal>\wedge</literal> -</term><listitem><para><inlineequation><mathphrase>\wedge</mathphrase></inlineequation> (binary operation) +</term><listitem><para>∧ Logical and (binary). Synonym: <literal>\land</literal>. See also +logical or <literal>\vee</literal>. Similar: variable-sized +operator <literal>\bigwedge</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\wp</primary></indexterm><literal>\wp</literal> -</term><listitem><para><inlineequation><mathphrase>\wp</mathphrase></inlineequation> +</term><listitem><para>℘ Weierstrass p (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\wr</primary></indexterm><literal>\wr</literal> -</term><listitem><para><inlineequation><mathphrase>\wr</mathphrase></inlineequation> (binary operation) +</term><listitem><para>≀ Wreath product (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Xi</primary></indexterm><literal>\Xi</literal> -</term><listitem><para><inlineequation><mathphrase>\Xi</mathphrase></inlineequation> +</term><listitem><para>Ξ Upper case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\xi</primary></indexterm><literal>\xi</literal> -</term><listitem><para><inlineequation><mathphrase>\xi</mathphrase></inlineequation> +</term><listitem><para>ξ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\zeta</primary></indexterm><literal>\zeta</literal> -</term><listitem><para><inlineequation><mathphrase>\zeta</mathphrase></inlineequation> +</term><listitem><para>ζ Lower case Greek letter (ordinary). </para> </listitem></varlistentry></variablelist> </sect1> <sect1 label="16.3" id="Math-functions"> <title>Math functions</title> + <indexterm role="cp"><primary>math functions</primary></indexterm> <indexterm role="cp"><primary>functions, math</primary></indexterm> @@ -4684,10 +6554,10 @@ spacing. </term><listitem><para><inlineequation><mathphrase>\cosh</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cot</primary></indexterm><literal>\cot</literal> -</term><listitem><para><inlineequation><mathphrase>\cos</mathphrase></inlineequation> +</term><listitem><para><inlineequation><mathphrase>\cot</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\coth</primary></indexterm><literal>\coth</literal> -</term><listitem><para><inlineequation><mathphrase>\cosh</mathphrase></inlineequation> +</term><listitem><para><inlineequation><mathphrase>\coth</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\csc</primary></indexterm><literal>\csc</literal> </term><listitem><para><inlineequation><mathphrase>\csc</mathphrase></inlineequation> @@ -4696,7 +6566,7 @@ spacing. </term><listitem><para><inlineequation><mathphrase>\deg</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\det</primary></indexterm><literal>\det</literal> -</term><listitem><para><inlineequation><mathphrase>\deg</mathphrase></inlineequation> +</term><listitem><para><inlineequation><mathphrase>\det</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dim</primary></indexterm><literal>\dim</literal> </term><listitem><para><inlineequation><mathphrase>\dim</mathphrase></inlineequation> @@ -4772,6 +6642,7 @@ spacing. </sect1> <sect1 label="16.4" id="Math-accents"> <title>Math accents</title> + <indexterm role="cp"><primary>math accents</primary></indexterm> <indexterm role="cp"><primary>accents, mathematical</primary></indexterm> @@ -4839,8 +6710,8 @@ in math. These are different from accents in normal text </term><listitem><indexterm role="cp"><primary>wide hat accent, math</primary></indexterm> <para>Math wide hat accent: <inlineequation><mathphrase>\widehat{x+y}</mathphrase></inlineequation>. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\widehat</primary></indexterm><literal>\widehat</literal> -</term><listitem><indexterm role="cp"><primary>wide tile accent, math</primary></indexterm> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\widetilde</primary></indexterm><literal>\widetilde</literal> +</term><listitem><indexterm role="cp"><primary>wide tilde accent, math</primary></indexterm> <para>Math wide tilde accent: <inlineequation><mathphrase>\widetilde{x+y}</mathphrase></inlineequation>. </para> </listitem></varlistentry></variablelist> @@ -4848,36 +6719,69 @@ in math. These are different from accents in normal text </sect1> <sect1 label="16.5" id="Spacing-in-math-mode"> <title>Spacing in math mode</title> + <indexterm role="cp"><primary>spacing within math mode</primary></indexterm> <indexterm role="cp"><primary>math mode, spacing</primary></indexterm> -<para>In a <literal>math</literal> environment, &latex; ignores the spaces you type and -puts in the spacing according to the normal rules for mathematics -texts. If you want different spacing, &latex; provides the following -commands for use in math mode: +<para>In a <literal>math</literal> environment, &latex; ignores the spaces that you use +in the source, and instead puts in the spacing according to the normal +rules for mathematics texts. +</para> +<para>Many math mode spacing definitions are expressed in terms of the math unit +<firstterm>mu</firstterm> given by 1 em = 18 mu, where the em is taken from the current +math symbols family (see <link linkend="Units-of-length">Units of length</link>). +&latex; provides the following commands for use in math mode: </para> <variablelist><varlistentry><term><literal>\;</literal> </term><listitem><indexterm role="fn"><primary>\;</primary></indexterm> -<para>A thick space (<inlineequation><mathphrase>5\over18\,</mathphrase></inlineequation>quad). -</para></listitem></varlistentry><varlistentry><term><literal>\:</literal> +<indexterm role="fn"><primary>\thickspace</primary></indexterm> +<para>Normally <literal>5.0mu plus 5.0mu</literal>. The longer name is +<literal>\thickspace</literal>. Math mode only. +</para> +</listitem></varlistentry><varlistentry><term><literal>\:</literal> </term><term><literal>\></literal> </term><listitem><indexterm role="fn"><primary>\:</primary></indexterm> <indexterm role="fn"><primary>\></primary></indexterm> -<para>Both of these produce a medium space (<inlineequation><mathphrase>2\over9\,</mathphrase></inlineequation>quad). -</para></listitem></varlistentry><varlistentry><term><literal>\,</literal> +<indexterm role="fn"><primary>\medspace</primary></indexterm> +<para>Normally <literal>4.0mu plus 2.0mu minus 4.0mu</literal>. The longer name is +<literal>\medspace</literal>. Math mode only. +</para> +</listitem></varlistentry><varlistentry><term><literal>\,</literal> </term><listitem><indexterm role="fn"><primary>\,</primary></indexterm> -<para>A thin space (<inlineequation><mathphrase>1\over6\,</mathphrase></inlineequation>quad); not restricted to math mode. -</para></listitem></varlistentry><varlistentry><term><literal>\!</literal> -</term><listitem><para>A negative thin space (<inlineequation><mathphrase>-{1\over6}\,</mathphrase></inlineequation>quad). +<indexterm role="fn"><primary>\thinspace</primary></indexterm> +<para>Normally <literal>3mu</literal>. The longer name is <literal>\thinspace</literal>. This can +be used in both math mode and text mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\!</literal> +</term><listitem><indexterm role="fn"><primary>\!</primary></indexterm> +<para>A negative thin space. Normally <literal>-3mu</literal>. Math mode only. +</para> +</listitem></varlistentry><varlistentry><term><literal>\quad</literal> +</term><listitem><indexterm role="cp"><primary>quad</primary></indexterm> +<indexterm role="fn"><primary>\quad</primary></indexterm> +<para>This is 18mu, that is, 1em. This is often used for space +surrounding equations or expressions, for instance for the space between +two equations inside a <literal>displaymath</literal> environment. It is available +in both text and math mode. +</para> +</listitem></varlistentry><varlistentry><term><literal>\qquad</literal> +</term><listitem><indexterm role="fn"><primary>\qquad</primary></indexterm> +<para>A length of 2 quads, that is, 36mu = 2em. It is available in +both text and math mode. </para></listitem></varlistentry></variablelist> +<para>In this example a thinspace separates the function from the +infinitesimal. +</para> +<screen>\int_0^1 f(x)\,dx +</screen> </sect1> <sect1 label="16.6" id="Math-miscellany"> <title>Math miscellany</title> + <indexterm role="cp"><primary>math miscellany</primary></indexterm> -<variablelist> -<varlistentry><term><indexterm role="fn"><primary>\*</primary></indexterm><literal>\*</literal> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\*</primary></indexterm><literal>\*</literal> </term><listitem><indexterm role="cp"><primary>discretionary multiplication</primary></indexterm> <indexterm role="cp"><primary>multiplication symbol, discretionary line break</primary></indexterm> <para>A “discretionary” multiplication symbol, at which a line break is @@ -4937,6 +6841,7 @@ descenders. </chapter> <chapter label="17" id="Modes"> <title>Modes</title> + <indexterm role="cp"><primary>modes</primary></indexterm> <indexterm role="cp"><primary>paragraph mode</primary></indexterm> <indexterm role="cp"><primary>math mode</primary></indexterm> @@ -4984,6 +6889,7 @@ mode, which it starts out in, is called “outer paragraph mode”. </chapter> <chapter label="18" id="Page-styles"> <title>Page styles</title> + <indexterm role="cp"><primary>styles, page</primary></indexterm> <indexterm role="cp"><primary>page styles</primary></indexterm> @@ -4994,6 +6900,7 @@ the page’s head and foot. The page style determines what goes in them. <sect1 label="18.1" id="_005cmaketitle"> <title><literal>\maketitle</literal></title> + <indexterm role="cp"><primary>titles, making</primary></indexterm> <indexterm role="fn"><primary>\maketitle</primary></indexterm> @@ -5034,6 +6941,7 @@ document. Use <literal>\\</literal> to force a line break, as usual. </sect1> <sect1 label="18.2" id="_005cpagenumbering"> <title><literal>\pagenumbering</literal></title> + <indexterm role="fn"><primary>\pagenumbering</primary></indexterm> <indexterm role="cp"><primary>page numbering style</primary></indexterm> @@ -5064,6 +6972,7 @@ the following: </sect1> <sect1 label="18.3" id="_005cpagestyle"> <title><literal>\pagestyle</literal></title> + <indexterm role="fn"><primary>\pagestyle</primary></indexterm> <indexterm role="cp"><primary>header style</primary></indexterm> <indexterm role="cp"><primary>footer style</primary></indexterm> @@ -5109,6 +7018,7 @@ the page. </sect1> <sect1 label="18.4" id="_005cthispagestyle"> <title><literal>\thispagestyle{<replaceable>style</replaceable>}</literal></title> + <indexterm role="fn"><primary>\thispagestyle</primary></indexterm> <para>The <literal>\thispagestyle</literal> command works in the same manner as the @@ -5120,94 +7030,169 @@ changes to <replaceable>style</replaceable> for the current page only. </chapter> <chapter label="19" id="Spaces"> <title>Spaces</title> + <indexterm role="cp"><primary>spaces</primary></indexterm> +<indexterm role="cp"><primary>white space</primary></indexterm> <para>&latex; has many ways to produce white (or filled) space. </para> -<para>Another space-producing command is <literal>\,</literal> to produce a “thin” -space (usually 1/6quad). It can be used in text mode, but is -more often useful in math mode (see <link linkend="Spacing-in-math-mode">Spacing in math mode</link>). -</para> <sect1 label="19.1" id="_005chspace"> <title><literal>\hspace</literal></title> + <indexterm role="fn"><primary>\hspace</primary></indexterm> <para>Synopsis: </para> -<screen>\hspace[*]{<replaceable>length</replaceable>} +<screen>\hspace{<replaceable>length</replaceable>} +\hspace*{<replaceable>length</replaceable>} </screen> -<para>The <literal>\hspace</literal> command adds horizontal space. The <replaceable>length</replaceable> -argument can be expressed in any terms that &latex; understands: -points, inches, etc. It is a rubber length. You can add both -negative and positive space with an <literal>\hspace</literal> command; adding -negative space is like backspacing. +<para>Add the horizontal space given by <replaceable>length</replaceable>. The <replaceable>length</replaceable> is a +rubber length, that is, it may contain a <literal>plus</literal> or <literal>minus</literal> +component, in any unit that &latex; understands (see <link linkend="Lengths">Lengths</link>). +</para> +<para>This command can add both positive and negative space; adding negative +space is like backspacing. </para> -<para>&latex; normally removes horizontal space that comes at the beginning -or end of a line. To preserve this space, use the optional <literal>*</literal> -form. +<para>Normally when &tex; breaks a paragraph into lines it discards white +space (glues and kerns) that would come at the start of a line, so you +get an inter-word space or a line break between words but not both. This +command’s starred version <literal>\hspace*{..}</literal> puts a non-discardable +invisible item in front of the space, so the space appears in the +output. </para> +<para>This example make a one-line paragraph that puts ‘<literal>Name:</literal>’ an inch +from the right margin. +</para> +<screen>\noindent\makebox[\linewidth]{\hspace{\fill}Name:\hspace{1in}} +</screen> </sect1> <sect1 label="19.2" id="_005chfill"> <title><literal>\hfill</literal></title> + <indexterm role="fn"><primary>\hfill</primary></indexterm> <indexterm role="cp"><primary>stretch, infinite horizontal</primary></indexterm> <indexterm role="cp"><primary>infinite horizontal stretch</primary></indexterm> -<para>The <literal>\hfill</literal> fill command produces a “rubber length” which has -no natural space but can stretch or shrink horizontally as far as -needed. +<para>Produce a rubber length which has +no natural space but can stretch horizontally as far as +needed (see <link linkend="Lengths">Lengths</link>). </para> <indexterm role="fn"><primary>\fill</primary></indexterm> -<para>The <literal>\fill</literal> parameter is the rubber length itself (technically, -the glue value ‘<literal>0pt plus1fill</literal>’); thus, <literal>\hspace\fill</literal> is -equivalent to <literal>\hfill</literal>. +<para>The command <literal>\hfill</literal> is equivalent to <literal>\hspace{\fill}</literal>. For +space that does not disappear at line breaks use +<literal>\hspace*{\fill}</literal> instead (see <link linkend="_005chspace">\hspace</link>). </para> </sect1> -<sect1 label="19.3" id="_005cSPACE"> -<title><literal>\SPACE</literal>: Normal interword space</title> -<indexterm role="fn"><primary>\SPACE</primary></indexterm> +<sect1 label="19.3" id="_005c_0028SPACE_0029-and-_005c_0040"> +<title><literal>\(SPACE)</literal> and \@</title> + +<indexterm role="fn"><primary>\(SPACE)</primary></indexterm> <indexterm role="fn"><primary>\TAB</primary></indexterm> <indexterm role="fn"><primary>\NEWLINE</primary></indexterm> +<indexterm role="fn"><primary>\@</primary></indexterm> +<anchor id="_005cAT"/><!-- old name --> -<para>The <literal>\ </literal> (space) command produces a normal interword space. It’s -useful after punctuation which shouldn’t end a sentence. For example, -<literal>the article in Proc.\ Amer.\ Math\. Soc.\ is fundamental</literal>. It -is also often used after control sequences, as in <literal>\TeX\ is a -nice system.</literal> +<para>Mark a punctuation character, typically a period, as either ending a +sentence or as ending an abbreviation. </para> -<para>In normal circumstances, <literal>\</literal><keycap>tab</keycap> and <literal>\</literal><keycap>newline</keycap> -are equivalent to <literal>\ </literal>. +<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 intersentence 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 +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 other use of <literal>\ </literal>, see also <link linkend="_005c_0028SPACE_0029-after-CS">\(SPACE) after CS</link>. +</para> +<para>In the opposite situation, if you have a capital letter followed by a +period that ends the sentence, then put <literal>\@</literal> on the left of that +period. For example, <literal>book by the MAA\@.</literal> will have intersentence +spacing after the period. +</para> +<para>In contrast, putting <literal>\@</literal> on the right of 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> - </sect1> -<sect1 label="19.4" id="_005c_0040"> -<title><literal>\@</literal>: Force sentence-ending punctuation</title> -<indexterm role="fn"><primary>\@</primary></indexterm> -<anchor id="_005cAT"/><!-- old name --> +<sect1 label="19.4" id="_005c_0028SPACE_0029-after-CS"> +<title><literal>\ </literal> after a control sequence</title> -<para>The <literal>\@</literal> command makes the following punctuation character end a -sentence even if it normally would not. This is typically used after -a capital letter. Here are side-by-side examples with and without -<literal>\@</literal>: +<para>The <literal>\ </literal> command is often used after control sequences to keep them +from gobbling the space that follows, as in <literal>\TeX\ is a nice +system.</literal> And, under normal circumstances <literal>\</literal><keycap>tab</keycap> and +<literal>\</literal><keycap>newline</keycap> are equivalent to <literal>\ </literal>. For other use of +<literal>\ </literal>, see also <link linkend="_005c_0028SPACE_0029-and-_005c_0040">\(SPACE) and \@</link>. </para> -<screen>… in C\@. Pascal, though … -… in C. Pascal, though … -</screen> -<para>produces +<para>Some people prefer to use <literal>{}</literal> for the same purpose, as in +<literal>\TeX{} is a nice system.</literal> This has the advantage that you can +always write it the same way, like <literal>\TeX{}</literal>, whether it is +followed by a space or by a punctuation mark. Please compare: </para> -<!-- Texinfo has different commands, but the result is the same. --> -<blockquote><para>… in C. Pascal, though … +<screen>\TeX\ is a nice system. \TeX, a nice system. -… in C. Pascal, though … -</para></blockquote> +\TeX{} is a nice system. \TeX{}, a nice system. +</screen> + +<para>When you define user commands (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>) you +can prevent the space gobbling after the command by using the package +<literal>xspace</literal> and inserting <literal>\xspace</literal> at the end of the definition +For instance: +</para><screen>\documentclass{minimal} +\usepackage{xspace} +\newcommand*{\Loup}{Grand Cric\xspace} +\begin{document} +Que le \Loup me croque ! +\end{document} +</screen> +<para>A quick hack to use <literal>\xspace</literal> for existing command is as follows: +</para><screen>\documentclass{minimal} +\usepackage{xspace} +\newcommand*{\SansXspaceTeX}{} +\let\SansXspaceTeX\TeX +\renewcommand{\TeX}{\SansXspaceTeX\xspace} +\begin{document} +\TeX is a nice system. +\end{document} +</screen> + +</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, intersentence</primary></indexterm> + +<para>This declaration (from Plain &tex;) causes &latex; to treat +intersentence 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.5" id="_005cthinspace"> +<sect1 label="19.6" id="_005cthinspace"> <title><literal>\thinspace</literal>: Insert 1/6em</title> + <indexterm role="fn"><primary>\thinspace</primary></indexterm> <para><literal>\thinspace</literal> produces an unbreakable and unstretchable space that @@ -5216,8 +7201,9 @@ quotes, as in ’”.<!-- Abuse @dmn, which is a thin space in Texinfo. </para> </sect1> -<sect1 label="19.6" id="_005c_002f"> +<sect1 label="19.7" id="_005c_002f"> <title><literal>\/</literal>: Insert italic correction</title> + <indexterm role="fn"><primary>\/</primary></indexterm> <indexterm role="cp"><primary>italic correction</primary></indexterm> @@ -5248,40 +7234,61 @@ in a different way. </para> </sect1> -<sect1 label="19.7" id="_005chrulefill"> -<title><literal>\hrulefill</literal></title> -<indexterm role="fn"><primary>\hrulefill</primary></indexterm> - -<para>The <literal>\hrulefill</literal> fill command produces a “rubber length” which can -stretch or shrink horizontally. It will be filled with a horizontal -rule. -</para> - -</sect1> -<sect1 label="19.8" id="_005cdotfill"> -<title><literal>\dotfill</literal></title> +<sect1 label="19.8" id="_005chrulefill-_005cdotfill"> +<title><literal>\hrulefill \dotfill</literal></title> +<indexterm role="fn"><primary>\hrulefill</primary></indexterm> <indexterm role="fn"><primary>\dotfill</primary></indexterm> -<para>The <literal>\dotfill</literal> command produces a “rubber length” that fills -with dots instead of just white space. +<para>Produce an infinite rubber length (see <link linkend="Lengths">Lengths</link>) filled with a +horizontal rule (that is, a line) or with dots, instead of just white +space. +</para> +<para>When placed between blank lines this example creates a paragraph that is +left and right justified, where the space in the middle is filled with +evenly spaced dots. +</para> +<screen>\noindent Jack Aubrey\dotfill Melbury Lodge +</screen> +<para>To make the rule or dots go to the line’s end use <literal>\null</literal> at the +start or end. +</para> +<para>To change the rule’s thickness, copy the definition and adjust it, as +with <literal>\renewcommand{\hrulefill}{\leavevmode\leaders\hrule height +1pt\hfill\kern\z@}</literal>, which changes the default thickness of +0.4pt to 1pt. Similarly, adjust the dot spacing as with +<literal>\renewcommand{\dotfill}{\leavevmode\cleaders\hb@xt@ +1.00em{\hss .\hss }\hfill\kern\z@}</literal>, which changes the default +length of 0.33em to 1.00em. </para> -<!-- xx undone --> </sect1> <sect1 label="19.9" id="_005caddvspace"> <title><literal>\addvspace</literal></title> + <indexterm role="fn"><primary>\addvspace</primary></indexterm> <indexterm role="cp"><primary>vertical space</primary></indexterm> <indexterm role="cp"><primary>space, inserting vertical</primary></indexterm> -<para><literal>\addvspace{length}</literal> +<para><literal>\addvspace{<replaceable>length</replaceable>}</literal> </para> -<para>The <literal>\addvspace</literal> command normally adds a vertical space of height -length. However, if vertical space has already been added to the same -point in the output by a previous <literal>\addvspace</literal> command, then this -command will not add more space than is needed to make the natural -length of the total vertical space equal to <literal>length</literal>. +<para>Add a vertical space of height <replaceable>length</replaceable>, which is a rubber length +(see <link linkend="Lengths">Lengths</link>). However, if vertical space has already been added to +the same point in the output by a previous <literal>\addvspace</literal> command +then this command will not add more space than what is needed to make +the natural length of the total vertical space equal to <replaceable>length</replaceable>. +</para> +<para>Use this command to adjust the vertical space above or below an +environment that starts a new paragraph. (For instance, a Theorem +environment is defined to begin and end in <literal>\addvspace{..}</literal> so +that two consecutive Theorem’s are separated by one vertical space, not +two.) +</para> +<para>This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>The error ‘<literal>Something's wrong--perhaps a missing \item</literal>’ means that +you were not in vertical mode when you invoked this command; one way to +change that is to precede this command with a <literal>\par</literal> command. </para> </sect1> @@ -5318,32 +7325,66 @@ quarter of a line space, with stretch and shrink (the default for the </sect1> <sect1 label="19.11" id="_005cvfill"> <title><literal>\vfill</literal></title> + <indexterm role="fn"><primary>\vfill</primary></indexterm> <indexterm role="cp"><primary>stretch, infinite vertical</primary></indexterm> <indexterm role="cp"><primary>infinite vertical stretch</primary></indexterm> -<para>The <literal>\vfill</literal> fill command produces a rubber length (glue) which -can stretch or shrink vertically as far as needed. It’s equivalent to -<literal>\vspace{\fill}</literal> (see <link linkend="_005chfill">\hfill</link>). -</para> +<para>End the current paragraph and insert a vertical rubber length +(see <link linkend="Lengths">Lengths</link>) that is infinite, so it can stretch or shrink as far +as needed. +</para> +<para>It is often used in the same way as <literal>\vspace{\fill}</literal>, except that +<literal>\vfill</literal> ends the current paragraph, whereas +<literal>\vspace{\fill}</literal> adds the infinite vertical space below its line +irrespective of the paragraph structure. In both cases that space will +disappear at a page boundary; to circumvent this see <link linkend="_005cvspace">\vspace</link>. +</para> +<para>In this example the page is filled, so the top and bottom lines contain +the text ‘<literal>Lost Dog!</literal>’ and the third ‘<literal>Lost Dog!</literal>’ is exactly +halfway between them. +</para> +<screen>\begin{document} +Lost Dog! +\vfill +Lost Dog! +\vfill +Lost Dog! +\end{document} +</screen> </sect1> <sect1 label="19.12" id="_005cvspace"> -<title><literal>\vspace[*]{<replaceable>length</replaceable>}</literal></title> +<title><literal>\vspace{<replaceable>length</replaceable>}</literal></title> + <indexterm role="fn"><primary>\vspace</primary></indexterm> +<indexterm role="cp"><primary>vertical space</primary></indexterm> +<indexterm role="cp"><primary>space, vertical</primary></indexterm> -<para>Synopsis: +<para>Synopsis, one of these two: </para> -<screen>\vspace[*]{<replaceable>length</replaceable>} +<screen>\vspace{<replaceable>length</replaceable>} +\vspace*{<replaceable>length</replaceable>} </screen> -<para>The <literal>\vspace</literal> command adds the vertical space <replaceable>length</replaceable>, i.e., -a rubber length. <replaceable>length</replaceable> can be negative or positive. +<para>Add the vertical space <replaceable>length</replaceable>. This can be negative or positive, +and is a rubber length (see <link linkend="Lengths">Lengths</link>). +</para> +<para>&latex; removes the vertical space from <literal>\vfill</literal> at a page break, +that is, at the top or bottom of a page. The starred version +<literal>\vspace*{..}</literal> causes the space to stay. </para> -<para>Ordinarily, &latex; removes vertical space added by <literal>\vspace</literal> at -the top or bottom of a page. With the optional <literal>*</literal> argument, the -space is not removed. +<para>In this example the two questions will be evenly spaced vertically on +the page, with at least one inch of space below each. </para> +<screen>\begin{document} +1) Who put the bomp in the bomp bah bomp bah bomp? +\vspace{1in plus 1fill} + +2) Who put the ram in the rama lama ding dong? +\vspace{1in plus 1fill} +\end{document} +</screen> </sect1> </chapter> @@ -5359,6 +7400,7 @@ used in the arguments of the box-making commands. <sect1 label="20.1" id="_005cmbox"> <title><literal>\mbox{<replaceable>text}</replaceable></literal></title> + <indexterm role="fn"><primary>\mbox</primary></indexterm> <indexterm role="cp"><primary>hyphenation, preventing</primary></indexterm> @@ -5400,6 +7442,7 @@ argument. <!-- xxref --> </sect1> <sect1 label="20.3" id="lrbox"> <title><literal>lrbox</literal></title> + <indexterm role="fn"><primary>lrbox</primary></indexterm> <para><literal>\begin{lrbox}{cmd} text \end{lrbox}</literal> @@ -5413,6 +7456,7 @@ must have been declared with <literal>\newsavebox</literal>. </sect1> <sect1 label="20.4" id="_005cmakebox"> <title><literal>\makebox</literal></title> + <indexterm role="fn"><primary>\makebox</primary></indexterm> <para>Synopsis: @@ -5420,7 +7464,7 @@ must have been declared with <literal>\newsavebox</literal>. <screen>\makebox[<replaceable>width</replaceable>][<replaceable>position</replaceable>]{<replaceable>text</replaceable>} </screen> <para>The <literal>\makebox</literal> command creates a box just wide enough to contain -the <replaceable>text</replaceable> specified. The width of the box is specified by the +the <replaceable>text</replaceable> specified. The width of the box can be overridden by the optional <replaceable>width</replaceable> argument. The position of the text within the box is determined by the optional <replaceable>position</replaceable> argument, which may take the following values: @@ -5435,13 +7479,14 @@ the following values: </term><listitem><para>Stretch (justify) across entire <replaceable>width</replaceable>; <replaceable>text</replaceable> must contain stretchable space for this to work. </para></listitem></varlistentry></variablelist> -<para><literal>\makebox</literal> is also used within the picture environment +<para><literal>\makebox</literal> is also used within the <literal>picture</literal> environment see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link>. </para> </sect1> <sect1 label="20.5" id="_005cparbox"> <title><literal>\parbox</literal></title> + <indexterm role="fn"><primary>\parbox</primary></indexterm> <para>Synopsis: @@ -5486,6 +7531,7 @@ for this to work. </sect1> <sect1 label="20.6" id="_005craisebox"> <title><literal>\raisebox</literal></title> + <indexterm role="fn"><primary>\raisebox</primary></indexterm> <para>Synopsis: @@ -5506,6 +7552,7 @@ ignoring its natural height and depth. </sect1> <sect1 label="20.7" id="_005csavebox"> <title><literal>\savebox</literal></title> + <indexterm role="fn"><primary>\savebox</primary></indexterm> <para>Synopsis: @@ -5521,6 +7568,7 @@ declared with <literal>\newsavebox</literal> (see <link linkend="_005cnewsavebox </sect1> <sect1 label="20.8" id="_005csbox"> <title><literal>\sbox{<replaceable>\boxcmd</replaceable>}{<replaceable>text</replaceable>}</literal></title> + <indexterm role="fn"><primary>\sbox</primary></indexterm> <para>Synopsis: @@ -5537,6 +7585,7 @@ included in the normal output, it is saved in the box labeled </sect1> <sect1 label="20.9" id="_005cusebox"> <title><literal>\usebox{<replaceable>\boxcmd</replaceable>}</literal></title> + <indexterm role="fn"><primary>\usebox</primary></indexterm> <para>Synopsis: @@ -5552,6 +7601,9 @@ included in the normal output, it is saved in the box labeled <chapter label="21" id="Special-insertions"> <title>Special insertions</title> +<indexterm role="cp"><primary>special insertions</primary></indexterm> +<indexterm role="cp"><primary>insertions of special characters</primary></indexterm> + <para>&latex; provides commands for inserting characters that have a special meaning do not correspond to simple characters you can type. </para> @@ -5559,6 +7611,7 @@ special meaning do not correspond to simple characters you can type. <sect1 label="21.1" id="Reserved-characters"> <title>Reserved characters</title> + <indexterm role="cp"><primary>reserved characters</primary></indexterm> <indexterm role="cp"><primary>characters, reserved</primary></indexterm> @@ -5610,13 +7663,14 @@ with <literal>"</literal>, so the previous example could also be written as <title>Text symbols</title> <indexterm role="cp"><primary>text symbols</primary></indexterm> +<indexterm role="cp"><primary>symbols, text</primary></indexterm> + <indexterm role="fn"><primary>textcomp package</primary></indexterm> <para>&latex; provides commands to generate a number of non-letter symbols in running text. Some of these, especially the more obscure ones, are not available in OT1; you may need to load the <literal>textcomp</literal> package. </para> -<variablelist> -<varlistentry><term><indexterm role="fn"><primary>\copyright</primary></indexterm><literal>\copyright</literal> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\copyright</primary></indexterm><literal>\copyright</literal> </term><term><indexterm role="fn"><primary>\textcopyright</primary></indexterm><literal>\textcopyright</literal> </term><listitem><indexterm role="cp"><primary>copyright symbol</primary></indexterm> <para>The copyright symbol, ©. @@ -5783,7 +7837,7 @@ has the ascender height. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textendash (or <literal>--</literal>)</primary></indexterm><literal>\textendash (or <literal>--</literal>)</literal> </term><listitem><indexterm role="cp"><primary>e-dash</primary></indexterm> -<para>En-dash: — (for ranges). +<para>En-dash: – (for ranges). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texteuro</primary></indexterm><literal>\texteuro</literal> </term><listitem><indexterm role="cp"><primary>euro symbol</primary></indexterm> @@ -5962,7 +8016,8 @@ environment, pushes current column to the right of the previous column </listitem></varlistentry><varlistentry><term><literal>\b</literal> </term><listitem><indexterm role="fn"><primary>\b (bar-under accent)</primary></indexterm> <indexterm role="cp"><primary>bar-under accent</primary></indexterm> -<para>Produces a bar accent under the following, as in o_. +<para>Produces a bar accent under the following, as in o_. See +also <literal>\underbar</literal> hereinafter. </para> </listitem></varlistentry><varlistentry><term><literal>\c</literal> </term><term><literal>\capitalcedilla</literal> @@ -6036,6 +8091,7 @@ the OT1 encoding. The argument is always processed in horizontal mode. The bar is always a fixed position under the baseline, thus crossing through descenders. See also <literal>\underline</literal> in <link linkend="Math-miscellany">Math miscellany</link>. +See also <literal>\b</literal> above. </para> </listitem></varlistentry><varlistentry><term><literal>\v</literal> </term><term><literal>\capitalcaron</literal> @@ -6060,8 +8116,7 @@ descenders. See also <literal>\underline</literal> in <link linkend="Math-misce <para>Here are the basic &latex; commands for inserting characters commonly used in languages other than English. </para> -<variablelist> -<varlistentry><term><literal>\aa</literal> +<variablelist><varlistentry><term><literal>\aa</literal> </term><term><literal>\AA</literal> </term><listitem><indexterm role="fn"><primary>\aa (å)</primary></indexterm> <indexterm role="fn"><primary>\AA (Å)</primary></indexterm> @@ -6144,6 +8199,7 @@ used in languages other than English. </sect1> <sect1 label="21.5" id="_005crule"> <title><literal>\rule</literal></title> + <indexterm role="fn"><primary>\rule</primary></indexterm> <para>Synopsis: @@ -6166,7 +8222,9 @@ rectangles. The arguments are: </sect1> <sect1 label="21.6" id="_005ctoday"> <title><literal>\today</literal></title> + <indexterm role="fn"><primary>\today</primary></indexterm> +<indexterm role="cp"><primary>date, today’s</primary></indexterm> <para>The <literal>\today</literal> command produces today’s date, in the format ‘<literal><replaceable>month</replaceable> <replaceable>dd</replaceable>, <replaceable>yyyy</replaceable></literal>’; for example, ‘July 4, 1976’. @@ -6183,6 +8241,7 @@ of other date formats. </chapter> <chapter label="22" id="Splitting-the-input"> <title>Splitting the input</title> + <indexterm role="cp"><primary>splitting the input file</primary></indexterm> <indexterm role="cp"><primary>input file</primary></indexterm> @@ -6199,6 +8258,7 @@ external file to be created with the main document. <sect1 label="22.1" id="_005cinclude"> <title><literal>\include</literal></title> + <indexterm role="fn"><primary>\include</primary></indexterm> <para>Synopsis: @@ -6222,6 +8282,7 @@ read by another <literal>\include</literal> command. </sect1> <sect1 label="22.2" id="_005cincludeonly"> <title>\<literal>includeonly</literal></title> + <indexterm role="fn"><primary>\includeonly</primary></indexterm> <para>Synopsis: @@ -6239,7 +8300,8 @@ effective. </sect1> <sect1 label="22.3" id="_005cinput"> -<title>\input</title> +<title><literal>\input</literal></title> + <indexterm role="fn"><primary>\input</primary></indexterm> <para>Synopsis: @@ -6255,6 +8317,7 @@ file at that point. or ‘<literal>foo.bar.tex</literal>’). If that is not found, the original <replaceable>file</replaceable> is tried (‘<literal>foo</literal>’ or ‘<literal>foo.bar</literal>’). </para> + </sect1> </chapter> <chapter label="23" id="Front_002fback-matter"> @@ -6295,7 +8358,8 @@ as for the table of contents. <sect2 label="23.1.1" id="_005caddcontentsline"> -<title>\addcontentsline</title> +<title><literal>\addcontentsline</literal></title> + <indexterm role="fn"><primary>\addcontentsline{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm> <indexterm role="cp"><primary>table of contents entry, manually adding</primary></indexterm> @@ -6331,7 +8395,8 @@ command <literal>\contentsline{<replaceable>unit</replaceable>}{<replaceable>nam </sect2> <sect2 label="23.1.2" id="_005caddtocontents"> -<title>\addtocontents</title> +<title><literal>\addtocontents</literal></title> + <indexterm role="fn"><primary>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm> <para>The <literal>\addtocontents</literal>{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>} command adds text @@ -6351,6 +8416,7 @@ figures), or <filename>lot</filename> (list of tables). </sect1> <sect1 label="23.2" id="Glossaries"> <title>Glossaries</title> + <indexterm role="cp"><primary>glossaries</primary></indexterm> <indexterm role="fn"><primary>\makeglossary</primary></indexterm> @@ -6374,6 +8440,7 @@ glossaries. </sect1> <sect1 label="23.3" id="Indexes"> <title>Indexes</title> + <indexterm role="cp"><primary>indexes</primary></indexterm> <indexterm role="fn"><primary>\makeindex</primary></indexterm> @@ -6438,59 +8505,119 @@ preparing the index. </chapter> <chapter label="24" id="Letters"> <title>Letters</title> -<indexterm role="cp"><primary>letters</primary></indexterm> -<indexterm role="cp"><primary>creating letters</primary></indexterm> -<para>You can use &latex; to typeset letters, both personal and business. The -<literal>letter</literal> document class is designed to make a number of letters at -once, although you can make just one if you so desire. -</para> -<para>Your <filename>.tex</filename> source file has the same minimum commands as the other -document classes, i.e., you must have the following commands as a -minimum: +<indexterm role="cp"><primary>letters, writing</primary></indexterm> +<indexterm role="cp"><primary>writing letters</primary></indexterm> + +<para>Synopsis: </para> -<screen> \documentclass{letter} - \begin{document} - ... letters ... - \end{document} +<screen>\documentclass{letter} +\address{<replaceable>sender address</replaceable>} +\signature{<replaceable>sender name</replaceable>} +\begin{document} +\begin{letter}{<replaceable>recipient address</replaceable>} +\opening{<replaceable>salutation</replaceable>} + <replaceable>letter body</replaceable> +\closing{<replaceable>closing text</replaceable>} +\end{letter} + ... more letters ... +\end{document} </screen> -<para>Each letter is a <literal>letter</literal> environment, whose argument is the name -and address of the recipient. For example, you might have: +<para>Produce one or more letters. +</para> +<para>Each letter is in a separate <literal>letter</literal> environment, whose argument +<replaceable>recipient address</replaceable> often contains multiple lines separated with a +double backslash (<literal>\\</literal>). For example, you might have: </para> -<screen> \begin{letter}{Mr. Joe Smith\\ 2345 Princess St. - \\ Edinburgh, EH1 1AA} +<screen> \begin{letter}{Mr. Joe Smith \\ + 2345 Princess St. \\ + Edinburgh, EH1 1AA} ... \end{letter} </screen> -<para>The letter itself begins with the <literal>\opening</literal> command. The text of -the letter follows. It is typed as ordinary &latex; input. Commands that -make no sense in a letter, like <literal>\chapter</literal>, do not work. The letter -closes with a <literal>\closing</literal> command. +<para>The start of the <literal>letter</literal> environment resets the page number to 1, +and the footnote number to 1 also. +</para> +<para>The <replaceable>sender address</replaceable> and <replaceable>sender name</replaceable> are common to all of the +letters, whether there is one or more, so these are best put in the +preamble. As with the recipient address, often <replaceable>sender address</replaceable> +contains multiple lines separated by a double +backslash (<literal>\\</literal>). &latex; will put the <replaceable>sender name</replaceable> +under the closing, after a vertical space for the traditional +hand-written signature; it also can contain multiple lines. +</para> +<para>Each letter environment begins with a required <literal>\opening</literal> command +such as <literal>\opening{Dear Madam or Sir:}</literal>. The <replaceable>letter body</replaceable> +text is ordinary &latex; so it can contain everything from from +enumerated lists to displayed math, except that commands such as +<literal>\chapter</literal> that make no sense in a letter are turned off. Each +letter environment typically ends with a <literal>\closing</literal> command such as +<literal>\closing{Yours,}</literal>. </para> <indexterm role="fn"><primary>\\ for letters</primary></indexterm> -<para>After the <literal>closing</literal>, you can have additional material. The -<literal>\cc</literal> command produces the usual “cc: …”. There’s also a -similar <literal>\encl</literal> command for a list of enclosures. With both these -commands, use <literal>\\</literal> to separate the items. -</para> +<para>Additional material may come after the <literal>\closing</literal>. You can say who +is receiving a copy of the letter with a command like <literal>\cc{the +Boss \\ the Boss's Boss}</literal>. There’s a similar <literal>\encl</literal> command for +a list of enclosures. And, you can add a postscript with <literal>\ps</literal>. +</para> +<para>&latex;’s default is to indent the signature and the <literal>\closing</literal> +above it by a length of <literal>\longindentation</literal>. By default this is +<literal>0.5\textwidth</literal>. To make them flush left, put +<literal>\setlength{\longindentation}{0em}</literal> in your preamble. +</para> +<para>To set a fixed date use something like +<literal>\renewcommand{\today}{2015-Oct-12}</literal>. If put in your preamble +then it will apply to all the letters. +</para> +<para>This example shows only one <literal>letter</literal> environment. The three lines +marked as optional are typically omitted. +</para> +<screen>\documentclass{letter} +\address{Sender's street \\ Sender's town} +\signature{Sender's name \\ Sender's title} +% optional: \location{Mailbox 13} +% optional: \telephone{(102) 555-0101} +\begin{document} +\begin{letter}{Recipient's name \\ Recipient's address} +\opening{Sir:} +% optional: \thispagestyle{firstpage} +I am not interested in entering a business arrangement with you. +\closing{Your most humble, etc.,} +\end{letter} +\end{document} +</screen> <para>These commands are used with the <literal>letter</literal> class. </para> <sect1 label="24.1" id="_005caddress"> -<title>\address{<replaceable>return-address}</replaceable></title> +<title><literal>\address</literal></title> + <indexterm role="fn"><primary>\address</primary></indexterm> -<para>The <literal>\address</literal> specifies the return address of a letter, as it -should appear on the letter and the envelope. Separate lines of the -address should be separated by <literal>\\</literal> commands. +<para>Synopsis: +</para> +<screen>\address{<replaceable>senders address</replaceable>} +</screen> +<para>Specifies the return address as it appears on the letter and on the +envelope. Separate multiple lines in <replaceable>senders address</replaceable> with a +double backslash <literal>\\</literal>. +</para> +<para>Because it can apply to multiple letters this declaration is often put +in the preamble. However, it can go anywhere, including inside an +individual <literal>letter</literal> environment. </para> -<para>If you do not make an <literal>\address</literal> declaration, then the letter -will be formatted for copying onto your organization’s standard -letterhead. (See <link linkend="Overview">Overview</link>, for details on your local -implementation). If you give an <literal>\address</literal> declaration, then the -letter will be formatted as a personal letter. +<para>This command is optional: without the <literal>\address</literal> declaration the +letter is formatted with some blank space on top, for copying onto +pre-printed letterhead paper. (See <link linkend="Overview">Overview</link>, for details on your +local implementation.) With the <literal>\address</literal> declaration, it is +formatted as a personal letter. </para> +<para>Here is an example. +</para> +<screen>\address{Stephen Maturin \\ + The Grapes of the Savoy} +</screen> </sect1> <sect1 label="24.2" id="_005ccc"> @@ -6501,11 +8628,17 @@ letter will be formatted as a personal letter. <para>Synopsis: </para> -<screen>\cc{<replaceable>name1</replaceable>\\<replaceable>name2</replaceable>} +<screen>\cc{<replaceable>first name</replaceable> \\ + .. } </screen> -<para>Produce a list of <replaceable>name</replaceable>s the letter was copied to. Each name is -printed on a separate line. +<para>Produce a list of names to which copies of the letter were sent. This +command is optional. If it appears then typically it comes after +<literal>\closing</literal>. Separate multiple lines with a double +backslash <literal>\\</literal>. </para> +<screen>\cc{President \\ + Vice President} +</screen> </sect1> <sect1 label="24.3" id="_005cclosing"> @@ -6519,8 +8652,10 @@ printed on a separate line. </para> <screen>\closing{text} </screen> -<para>A letter closes with a <literal>\closing</literal> command, for example, -</para><screen>\closing{Best Regards,} +<para>Usually at the end of a letter, above the handwritten signature, there +is a <literal>\closing</literal> (although this command is optional). For example, +</para> +<screen>\closing{Regards,} </screen> </sect1> @@ -6532,48 +8667,75 @@ printed on a separate line. <para>Synopsis: </para> -<screen>\encl{<replaceable>line1</replaceable>\\<replaceable>line2</replaceable>} +<screen>\encl{<replaceable>first enclosed object</replaceable> \\ + .. } </screen> -<para>Declare a list of one more enclosures. +<para>Produce a list of things included with the letter. This command is +optional; when it is used, it typically is put after <literal>\closing</literal>. +Separate multiple lines with a double backslash <literal>\\</literal>. </para> +<screen>\encl{License \\ + Passport } +</screen> </sect1> <sect1 label="24.5" id="_005clocation"> <title><literal>\location</literal></title> + <indexterm role="fn"><primary>\location</primary></indexterm> -<para><literal>\location{address}</literal> +<para>Synopsis: </para> -<para>This modifies your organization’s standard address. This only appears -if the <literal>firstpage</literal> pagestyle is selected. +<screen>\location{<replaceable>text</replaceable>} +</screen> +<para>The <replaceable>text</replaceable> appears centered at the bottom of the each page. It only +appears if the page style is <literal>firstpage</literal>. </para> </sect1> <sect1 label="24.6" id="_005cmakelabels"> <title><literal>\makelabels</literal></title> + <indexterm role="fn"><primary>\makelabels</primary></indexterm> -<para><literal>\makelabels{number}</literal> +<para>Synopsis: </para> -<para>If you issue this command in the preamble, &latex; will create a sheet of -address labels. This sheet will be output before the letters. +<screen>\makelabels +</screen> +<para>Create a sheet of address labels from the recipient addresses, one for +each letter. This sheet will be output before the letters, with the idea +that you can copy it to a sheet of peel-off labels. This command goes +in the preamble. +</para> +<para>Customize the labels by redefining the commands <literal>\startlabels</literal>, +<literal>\mlabel</literal>, and <literal>\returnaddress</literal> in the preamble. The command +<literal>\startlabels</literal> sets the width, height, number of columns, etc., of +the page onto which the labels are printed. The command +<literal>\mlabel{<replaceable>sender address</replaceable>}{<replaceable>recipient address</replaceable>}</literal> +produces the two labels (or one, if you choose to ignore the <replaceable>sender +address</replaceable>). The <replaceable>sender address</replaceable> is the value returned by the macro +<literal>\returnaddress</literal> while <replaceable>recipient address</replaceable> is the value passed +in the argument to the <literal>letter</literal> environment. By default +<literal>\mlabel</literal> ignores the first argument, the <replaceable>sender address</replaceable>. </para> - - </sect1> <sect1 label="24.7" id="_005cname"> <title><literal>\name</literal></title> + <indexterm role="fn"><primary>\name</primary></indexterm> -<para><literal>\name{June Davenport}</literal> +<para>Synopsis: </para> -<para>Your name, used for printing on the envelope together with the return -address. +<screen>\name{<replaceable>name</replaceable>} +</screen> +<para>Sender’s name, used for printing on the envelope together with the +return address. </para> </sect1> <sect1 label="24.8" id="_005copening"> -<title><literal>\opening{<replaceable>text</replaceable>}</literal></title> +<title><literal>\opening</literal></title> + <indexterm role="fn"><primary>\opening</primary></indexterm> <indexterm role="cp"><primary>letters, starting</primary></indexterm> @@ -6581,11 +8743,11 @@ address. </para> <screen>\opening{<replaceable>text</replaceable>} </screen> -<para>A letter begins with the <literal>\opening</literal> command. The mandatory -argument, <replaceable>text</replaceable>, is whatever text you wish to start your letter. -For instance: +<para>This command is required. It starts a letter, following the +<literal>\begin{letter}{..}</literal>. The mandatory argument <replaceable>text</replaceable> is the +text that starts your letter. For instance: </para> -<screen>\opening{Dear Joe,} +<screen>\opening{Dear John:} </screen> </sect1> @@ -6594,62 +8756,99 @@ For instance: <indexterm role="fn"><primary>\ps</primary></indexterm> <indexterm role="cp"><primary>postscript, in letters</primary></indexterm> -<para>Use the <literal>\ps</literal> command to start a postscript in a letter, after +<para>Synopsis: +</para> +<screen>\ps{<replaceable>text</replaceable>} +</screen> +<para>Add a postscript. This command is optional and usually is used after <literal>\closing</literal>. </para> +<screen>\ps{P.S. After you have read this letter, burn it. Or eat it.} +</screen> </sect1> <sect1 label="24.10" id="_005csignature"> -<title><literal>\signature{<replaceable>text</replaceable>}</literal></title> -<indexterm role="fn"><primary>\signature</primary></indexterm> +<title><literal>\signature</literal></title> -<para>Your name, as it should appear at the end of the letter underneath the -space for your signature. <literal>\\</literal> starts a new line within -<replaceable>text</replaceable> as usual. +<para>Synopsis: </para> +<screen>\signature{<replaceable>first line</replaceable> \\ + .. } +</screen> +<indexterm role="fn"><primary>\signature</primary></indexterm> -</sect1> -<sect1 label="24.11" id="_005cstartbreaks"> -<title><literal>\startbreaks</literal></title> -<indexterm role="fn"><primary>\startbreaks</primary></indexterm> - -<para><literal>\startbreaks</literal> +<para>The sender’s name. This command is optional, although its inclusion is +usual. </para> -<para>Used after a <literal>\stopbreaks</literal> command to allow page breaks again. +<para>The argument text appears at the end of the letter, after the closing +and after a vertical space for the traditional hand-written +signature. Separate multiple lines with a double +backslash <literal>\\</literal>. For example: </para> - -</sect1> -<sect1 label="24.12" id="_005cstopbreaks"> -<title><literal>\stopbreaks</literal></title> -<indexterm role="fn"><primary>\stopbreaks</primary></indexterm> - -<para><literal>\stopbreaks</literal> +<screen>\signature{J Fred Muggs \\ + White House} +</screen> +<para>&latex;’s default for the vertical space from the <literal>\closing</literal> text +down to the <literal>\signature</literal> text is <literal>6\medskipamount</literal>, which is +six times 0.7em. </para> -<para>Inhibit page breaks until a <literal>\startbreaks</literal> command occurs. +<para>This command is usually in the preamble, to apply to all the letters in +the document. To have it apply to one letter only, put it inside a +<literal>letter</literal> environment and before the <literal>\closing</literal>. </para> +<para>You can include a graphic in the signature, for instance with +<literal>\signature{\vspace{-6\medskipamount}\includegraphics{sig.png}\\ +My name}</literal> (this requires writing <literal>\usepackage{graphicx}</literal> in the +preamble). +</para> + +<!-- I think this is not a user-level command; it is used to keep from breaking --> +<!-- the page between the closing and the signature --> +<!-- @node \stopbreaks and \startbreaks --> +<!-- @section @code{\stopbreaks} and @code{\startbreaks} --> + +<!-- @findex \startbreak --> +<!-- @findex \stopbreaks --> +<!-- @example --> +<!-- @code{\stopbreaks} --> +<!-- text --> +<!-- @code{\startbreaks} --> +<!-- @end example --> + +<!-- The @code{\stopbreaks} inhibits page breaking. The @code{\startbreaks} resumes --> +<!-- normal page breaking. --> +<!-- --> +<!-- --> </sect1> -<sect1 label="24.13" id="_005ctelephone"> +<sect1 label="24.11" id="_005ctelephone"> <title><literal>\telephone</literal></title> + <indexterm role="fn"><primary>\telephone</primary></indexterm> -<para><literal>\telephone{number}</literal> +<para>Synopsis: </para> -<para>This is your telephone number. This only appears if the -<literal>firstpage</literal> pagestyle is selected. +<screen>\telephone{<replaceable>number</replaceable>} +</screen> +<para>The sender’s telephone number. This is typically in the preamble, where +it applies to all letters. This only appears if the <literal>firstpage</literal> +pagestyle is selected. If so, it appears on the lower right of the +page. </para> </sect1> </chapter> <chapter label="25" id="Terminal-input_002foutput"> <title>Terminal input/output</title> -<indexterm role="cp"><primary>input/output</primary></indexterm> + +<indexterm role="cp"><primary>input/output, to terminal</primary></indexterm> <indexterm role="cp"><primary>terminal input/output</primary></indexterm> <sect1 label="25.1" id="_005ctypein"> <title><literal>\typein[<replaceable>cmd</replaceable>]{<replaceable>msg</replaceable>}</literal></title> + <indexterm role="fn"><primary>\typein</primary></indexterm> <para>Synopsis: @@ -6668,6 +8867,7 @@ redefined to be the typed input. </sect1> <sect1 label="25.2" id="_005ctypeout"> <title><literal>\typeout{<replaceable>msg</replaceable>}</literal></title> + <indexterm role="fn"><primary>\typeout</primary></indexterm> <para>Synopsis: @@ -6690,6 +8890,7 @@ printed, independent of surrounding spaces. A <literal>^^J</literal> in </chapter> <chapter label="26" id="Command-line"> <title>Command line</title> + <indexterm role="cp"><primary>command line</primary></indexterm> <indexterm role="fn"><primary>.tex, default extension</primary></indexterm> @@ -6720,7 +8921,9 @@ be specified in the usual Unix way, starting with ‘<literal>-</literal> </chapter> <appendix label="A" id="Document-templates"> <title>Document templates</title> + <indexterm role="cp"><primary>document templates</primary></indexterm> +<indexterm role="cp"><primary>templates, document</primary></indexterm> <para>Although not reference material, perhaps these document templates will be useful. Additional template resources are listed at @@ -6732,6 +8935,8 @@ be useful. Additional template resources are listed at <title><literal>beamer</literal> template</title> <indexterm role="cp"><primary><literal>beamer</literal> template and class</primary></indexterm> +<indexterm role="cp"><primary>template, <literal>beamer</literal></primary></indexterm> + <para>The <literal>beamer</literal> class creates presentation slides. It has a vast array of features, but here is a basic template: </para> @@ -6765,6 +8970,8 @@ array of features, but here is a basic template: <sect1 label="A.2" id="book-template"> <title><literal>book</literal> template</title> +<indexterm role="cp"><primary>template, <literal>book</literal></primary></indexterm> + <screen>\documentclass{book} \title{Book Class Template} \author{Alex Author} @@ -6787,6 +8994,7 @@ The end. <sect1 label="A.3" id="tugboat-template"> <title><literal>tugboat</literal> template</title> +<indexterm role="cp"><primary>template, TUGboat</primary></indexterm> <indexterm role="cp"><primary>TUGboat template</primary></indexterm> <indexterm role="cp"><primary><literal>ltugboat</literal> class</primary></indexterm> |