diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/latex2e-help-texinfo/latex2e.dbk |
Initial commit
Diffstat (limited to 'info/latex2e-help-texinfo/latex2e.dbk')
-rw-r--r-- | info/latex2e-help-texinfo/latex2e.dbk | 17174 |
1 files changed, 17174 insertions, 0 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.dbk b/info/latex2e-help-texinfo/latex2e.dbk new file mode 100644 index 0000000000..5c203240fa --- /dev/null +++ b/info/latex2e-help-texinfo/latex2e.dbk @@ -0,0 +1,17174 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + <!ENTITY tex "TeX"> + <!ENTITY latex "LaTeX"> +]> +<book id="latex2e.dbk" lang="en"> +<!-- $Id: common.texi 701 2018-10-08 14:32:37Z jimhefferon $ --> +<!-- Public domain. --> + + +<title>&latex;2e unofficial reference manual (October 2018)</title> +<!-- %**end of header (This is for running Texinfo on a region.) --> + +<!-- latex 2.09 commands should all be present now, --> +<!-- xx but latex2e stuff is missing. --> +<!-- xx random list of a few of the missing items is at the end of this file --> +<!-- --> +<!-- xx ctan, distributions, components of TeX --> +<!-- xx classes and packages - required, additional, useful; oberdiek; fonts --> +<!-- --> +<!-- xx merge permuted-index --> +<!-- xx merge latex-manual from savannah --> +<!-- xx merge display style math --> +<!-- xx JH explain nfss somewhere --> +<!-- xx JH expand BiBTeX --> +<!-- xx JH expand theorem, AMS math --> +<!-- xx JH something on code listings --> +<!-- xx JH ligatures --> +<!-- xx JH \xspace --> +<!-- xx JH \stretch --> +<!-- xx JH \mathstrut --> +<!-- xx JH \phantom https://tex.stackexchange.com/questions/4519/how-do-i-create-an-invisible-character --> +<!-- xx JH \baselineskip https://texfaq.org/FAQ-baselinepar --> +<!-- xx JH \contentsline, \@@dottedtocline? --> +<!-- xx JH more on \write18, beyond what's mentioned in Command line. --> +<!-- xx JH \numexpr, \dimexpr, \glueexpr, \muexpr --> +<!-- --> +<!-- xx The typeset source2e has an index with all kernel --> +<!-- xx commands, though some are internal and shouldn't be included. --> +<!-- xx classes.dtx et al. define additional commands. --> +<!-- 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 October 2018. +</para> +<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the +VMS Help Library. The pre-translation version was written by +George D. Greenwade of Sam Houston State University. The +&latex; 2.09 version was written by Stephen Gilmore. The +&latex;2e version was adapted from this by Torsten Martinsen. Karl +Berry made further updates and additions, and gratefully acknowledges +using <citetitle>Hypertext Help with &latex;</citetitle>, by Sheldon Green, and +<citetitle>&latex; Command Summary</citetitle> (for &latex; 2.09) by +L. Botway and C. Biemesderfer (published by the &tex; Users +Group as <citetitle>&tex;niques</citetitle> number 10), as reference material. We also +gratefully acknowledge additional material appearing in +latex2e-reference by Martin Herbert Dietze. (From these references no +text was directly copied.) +</para> +<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, +2014, 2015, 2016, 2017, 2018 Karl Berry. + +Copyright 1988, 1994, 2007 Stephen Gilmore. + +Copyright 1994, 1995, 1996 Torsten Martinsen. +</para> +<!-- start of License --> +<para>Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +</para> + +<para>Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. +</para> +<para>Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +<!-- end of License --> +</para></legalnotice></bookinfo> +<!-- Merge into one index (arbitrarily chosen to be the concept index). --> + + + +<para>This document is an unofficial reference manual for &latex;, a +document preparation system, version of October 2018. +</para> +<para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the +VMS Help Library. The pre-translation version was written by +George D. Greenwade of Sam Houston State University. The +&latex; 2.09 version was written by Stephen Gilmore. The +&latex;2e version was adapted from this by Torsten Martinsen. Karl +Berry made further updates and additions, and gratefully acknowledges +using <citetitle>Hypertext Help with &latex;</citetitle>, by Sheldon Green, and +<citetitle>&latex; Command Summary</citetitle> (for &latex; 2.09) by +L. Botway and C. Biemesderfer (published by the &tex; Users +Group as <citetitle>&tex;niques</citetitle> number 10), as reference material. We also +gratefully acknowledge additional material appearing in +latex2e-reference by Martin Herbert Dietze. (From these references no +text was directly copied.) +</para> +<para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, +2014, 2015, 2016, 2017, 2018 Karl Berry. + +Copyright 1988, 1994, 2007 Stephen Gilmore. + +Copyright 1994, 1995, 1996 Torsten Martinsen. +</para> +<!-- start of License --> +<para>Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +</para> + +<para>Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. +</para> +<para>Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +<!-- end of License --> +</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 +October 2018) for &latex;2e, a document preparation system. +</para> + + +</chapter> +<chapter label="1" id="About-this-document"> +<title>About this document</title> + +<indexterm role="cp"><primary>home page for manual</primary></indexterm> +<para>This is an unofficial reference manual for the &latex;2e document +preparation system, which is a macro package for the &tex; +typesetting program (see <link linkend="Overview">Overview</link>). +</para> +<para>This document’s home page is <ulink url="https://puszcza.gnu.org.ua/software/latexrefman">https://puszcza.gnu.org.ua/software/latexrefman</ulink>. There +you can get the sources, subscribe to the mailing list or read its +archives, see other infrastructure, and get the current output in +various formats. In particular, the output comes in two web formats. +Probably the most convenient one, shown at <ulink url="http://latexref.xyz/">http://latexref.xyz/</ulink>, +has pages for each topic and so is good for a quick lookup; see also the +note there about easy-to-remember links. The other, shown at +<ulink url="http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co">http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co</ulink>, +has all the information on single page. +</para> +<indexterm role="cp"><primary>&latex; vs. &latex;2e</primary></indexterm> +<para>In this document, we will mostly just use ‘&latex;’ rather than +‘&latex;2e’, since the previous version of &latex; (2.09) was +frozen decades ago. +</para> +<indexterm role="cp"><primary>unofficial nature of this manual</primary></indexterm> +<indexterm role="cp"><primary>&latex; Project team</primary></indexterm> +<indexterm role="fn"><primary><email>latexrefman@tug.org</email> email address</primary></indexterm> +<para>&latex; is currently maintained by a group of volunteers +(<ulink url="http://latex-project.org">http://latex-project.org</ulink>). The official documentation written by +the &latex; project is available from their web site. This document is +completely unofficial and has not been reviewed by the &latex; +maintainers. +<indexterm role="cp"><primary>bug reporting</primary></indexterm> +<indexterm role="cp"><primary>reporting bugs</primary></indexterm> +Do not send bug reports or anything else about this document to them. +Instead, please send all comments to <email>latexrefman@tug.org</email>. +</para> +<para>This document is a reference. There is a vast array of other sources +of information about &latex;, at all levels. Here are a few +introductions. +</para> +<variablelist><varlistentry><term><ulink url="http://ctan.org/pkg/latex-doc-ptr">http://ctan.org/pkg/latex-doc-ptr</ulink> +</term><listitem><indexterm role="fn"><primary>latex-doc-ptr document</primary></indexterm> +<para>Two pages of recommended references to &latex; documentation. +</para> +</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/first-latex-doc">http://ctan.org/pkg/first-latex-doc</ulink> +</term><listitem><indexterm role="fn"><primary>first-latex-doc document</primary></indexterm> +<para>Writing your first document, with a bit of both text and math. +</para> +</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/usrguide">http://ctan.org/pkg/usrguide</ulink> +</term><listitem><indexterm role="fn"><primary>usrguide official documentation</primary></indexterm> +<para>The guide for document authors that is maintained as part of &latex;. +Many other guides by many other people are also available, independent +of &latex; itself; one such is the next item: +</para> +</listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/lshort">http://ctan.org/pkg/lshort</ulink> +</term><listitem><indexterm role="fn"><primary>lshort document</primary></indexterm> +<para>A short introduction to &latex;, translated to many languages. +</para> +</listitem></varlistentry><varlistentry><term><ulink url="http://tug.org/begin.html">http://tug.org/begin.html</ulink> +</term><listitem><para>Introduction to the &tex; system, including &latex;, with further +references. +</para> +</listitem></varlistentry></variablelist> + +</chapter> +<chapter label="2" id="Overview"> +<title>Overview of &latex;</title> + +<indexterm role="cp"><primary>overview of &latex;</primary></indexterm> +<indexterm role="cp"><primary>basics of &latex;</primary></indexterm> +<indexterm role="cp"><primary>Knuth, Donald E.</primary></indexterm> +<indexterm role="cp"><primary>Lamport, Leslie</primary></indexterm> +<indexterm role="cp"><primary>&latex; overview</primary></indexterm> + +<para>&latex; is a system for typesetting documents. It was originally +created by Leslie Lamport and is now maintained by a group of volunteers +(<ulink url="http://latex-project.org">http://latex-project.org</ulink>). It is widely used, particularly for +complex and technical documents, such as those involving mathematics. +</para> +<indexterm role="cp"><primary>macro package, &latex; as</primary></indexterm> +<para>A &latex; user writes an input file containing text along with +interspersed commands, for instance commands describing how the text +should be formatted. It is implemented as a set of related commands +that interface with Donald 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 +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 +available to a &latex; user. +</para> +<indexterm role="cp"><primary>Lamport &tex;</primary></indexterm> +<indexterm role="cp"><primary>pronunciation</primary></indexterm> +<para>The name &latex; is short for “Lamport &tex;”. It is pronounced +LAH-teck or LAY-teck, or sometimes LAY-tecks. Inside a document, +produce the logo with <literal>\LaTeX</literal>. Where use of the logo is not +sensible, such as in plain text, write it as ‘<literal>LaTeX</literal>’. +</para> + + +<sect1 label="2.1" id="Starting-and-ending"> +<title>Starting and ending</title> + +<anchor id="Starting-_0026-ending"/><!-- old name --> +<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 beginning +and ending. This is a small example. +</para> +<screen>\documentclass{article} +\begin{document} +Hello, \LaTeX\ world. +\end{document} +</screen> +<para>Every &latex; document has a <literal>\begin{document}</literal> line and an +<literal>\end{document}</literal> line. +</para> +<indexterm role="cp"><primary>document class, defined</primary></indexterm> +<para>Here, the ‘<literal>article</literal>’ is the <firstterm>document class</firstterm>. It is implemented +in a file <filename>article.cls</filename>. You can use any document class on your +system. A few document classes are defined by &latex; itself, and vast +array of others are widely available. See <link linkend="Document-classes">Document classes</link>. +</para> +<indexterm role="cp"><primary>preamble, defined</primary></indexterm> +<para>You can include other &latex; commands between the +<literal>\documentclass</literal> and the <literal>\begin{document}</literal> commands. +This area is called the <firstterm>preamble</firstterm>. +</para> +<para>The <literal>\begin{document}</literal>, <literal>\end{document}</literal> pair defines an +<indexterm role="cp"><primary>environment</primary></indexterm> +<firstterm>environment</firstterm>; the ‘<literal>document</literal>’ environment (and no others) is +required in all &latex; documents (see <link linkend="document">document</link>). &latex; make +available to you many environments that are documented here +(see <link linkend="Environments">Environments</link>). Many more are available to you from external +packages, most importantly those available at CTAN (see <link linkend="CTAN">CTAN</link>). +</para> +<para>The following sections discuss how to produce PDF or other output from +a &latex; input file. +</para> + +</sect1> +<sect1 label="2.2" id="Output-files"> +<title>Output files</title> + +<para>&latex; produces a main output file and at least two auxiliary files. +The main output file’s name ends in either <filename>.dvi</filename> or <filename>.pdf</filename>. +</para> +<variablelist><varlistentry><term><literal>.dvi</literal> +</term><listitem><indexterm role="fn"><primary>.dvi file</primary></indexterm> +<indexterm role="fn"><primary>latex command</primary></indexterm> +<indexterm role="fn"><primary>xdvi command</primary></indexterm> +<indexterm role="fn"><primary>dvips command</primary></indexterm> +<indexterm role="fn"><primary>dvipdfmx command</primary></indexterm> +<indexterm role="fn"><primary>dvitype command</primary></indexterm> +<anchor id="output-files-dvi"/><para>If &latex; is invoked with the system command <command>latex</command> then it +produces a DeVice Independent file, with extension <filename>.dvi</filename>. You +can view this file with a command such as <command>xdvi</command>, or convert +it to a PostScript <literal>.ps</literal> file with <command>dvips</command> or to a +Portable Document Format <literal>.pdf</literal> file with <command>dvipdfmx</command>. +The contents of the file can be dumped in human-readable form with +<command>dvitype</command>. A vast array of other DVI utility programs are +available (<ulink url="http://mirror.ctan.org/dviware">http://mirror.ctan.org/dviware</ulink>). +</para> +</listitem></varlistentry><varlistentry><term><literal>.pdf</literal> +</term><listitem><indexterm role="fn"><primary>.pdf file</primary></indexterm> +<indexterm role="cp"><primary>pdf&tex;</primary></indexterm> +<indexterm role="fn"><primary>pdflatex command</primary></indexterm> +<anchor id="output-files-pdf"/><para>If &latex; is invoked via the system command <command>pdflatex</command>, +among other commands (see <link linkend="TeX-engines">&tex; engines</link>), then the main output is +a Portable Document Format (PDF) file. Typically this is a +self-contained file, with all fonts and images included. +</para> +</listitem></varlistentry></variablelist> +<para>&latex; also produces at least two additional files. +</para> +<variablelist><varlistentry><term><literal>.log</literal> +</term><listitem><indexterm role="cp"><primary>transcript file</primary></indexterm> +<indexterm role="cp"><primary>log file</primary></indexterm> +<indexterm role="fn"><primary>.log file</primary></indexterm> +<anchor id="output-files-log"/><para>This transcript file contains summary information such as a list of +loaded packages. It also includes diagnostic messages and perhaps +additional information for any errors. +</para> +</listitem></varlistentry><varlistentry><term><literal>.aux</literal> +</term><listitem><indexterm role="cp"><primary>auxiliary file</primary></indexterm> +<indexterm role="fn"><primary>.aux file</primary></indexterm> +<indexterm role="cp"><primary>cross references, resolving</primary></indexterm> +<indexterm role="cp"><primary>forward references, resolving</primary></indexterm> +<indexterm role="cp"><primary>references, resolving forward</primary></indexterm> +<anchor id="output-files-aux"/><para>Auxiliary information is used by &latex; for things such as +cross references. For example, the first time that &latex; finds a +forward reference—a cross reference to something that has not yet +appeared in the source—it will appear in the output as a doubled +question mark <literal>??</literal>. When the referred-to spot does eventually +appear in the source then &latex; writes its location information to +this <literal>.aux</literal> file. On the next invocation, &latex; reads the +location information from this file and uses it to resolve the +reference, replacing the double question mark with the remembered +location. +</para> +</listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>.lof file</primary></indexterm> +<indexterm role="cp"><primary>list of figures file</primary></indexterm> +<indexterm role="fn"><primary>.lot file</primary></indexterm> +<indexterm role="cp"><primary>list of tables file</primary></indexterm> +<indexterm role="fn"><primary>.toc file</primary></indexterm> +<indexterm role="cp"><primary>table of contents file</primary></indexterm> +<indexterm role="cp"><primary>contents file</primary></indexterm> +<para>&latex; may produce yet more files, characterized by the filename +ending. These include a <literal>.lof</literal> file that is used to make a list of +figures, a <literal>.lot</literal> file used to make a list of tables, and a +<literal>.toc</literal> file used to make a table of contents (see <link linkend="Table-of-contents-etc_002e">Table of +contents etc.</link>). A particular class may create others; the list is +open-ended. +</para> + +</sect1> +<sect1 label="2.3" id="TeX-engines"> +<title>&tex; engines</title> + +<indexterm role="cp"><primary>engines, &tex;</primary></indexterm> +<indexterm role="cp"><primary>implementations of &tex;</primary></indexterm> +<indexterm role="cp"><primary>UTF-8</primary></indexterm> +<indexterm role="cp"><primary>Unicode input, native</primary></indexterm> +<indexterm role="cp"><primary>TrueType fonts</primary></indexterm> +<indexterm role="cp"><primary>OpenType fonts</primary></indexterm> + +<para>&latex; is defined to be a set of commands that are run by a &tex; +implementation (see <link linkend="Overview">Overview</link>). This section gives a terse +overview of the main programs (see also <link linkend="Command-line">Command line</link>). +</para> +<variablelist><varlistentry><term><literal>latex</literal> +</term><term><literal>pdflatex</literal> +</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> +<anchor id="tex-engines-latex"/><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> +file; as <command>pdflatex</command>, the main output is a <filename>.pdf</filename> file. +</para> +<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 system +command <command>etex</command>, but this is plain &tex; (and produces +<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 +assumed to be available in &latex;. +</para> +</listitem></varlistentry><varlistentry><term><literal>lualatex</literal> +</term><listitem><indexterm role="fn"><primary>lualatex command</primary></indexterm> +<indexterm role="cp"><primary>Lua&tex;</primary></indexterm> +<anchor id="tex-engines-lualatex"/><para>If &latex; is invoked via the system command <command>lualatex</command>, the +Lua&tex; engine is run (<ulink url="http://ctan.org/pkg/luatex">http://ctan.org/pkg/luatex</ulink>). This +program allows code written in the scripting language Lua +(<ulink url="http://luatex.org">http://luatex.org</ulink>) to interact with &tex;’s typesetting. +Lua&tex; handles UTF-8 Unicode input natively, can handle OpenType +and TrueType fonts, and produces a <filename>.pdf</filename> file by default. +There is also <command>dvilualatex</command> to produce a <filename>.dvi</filename> file, +but this is rarely used. +</para> +</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> +<anchor id="tex-engines-xelatex"/><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; 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 +additional support for Japanese and other languages ([u]p&tex;, +<ulink url="http://ctan.org/pkg/ptex">http://ctan.org/pkg/ptex</ulink>, <ulink url="http://ctan.org/pkg/uptex">http://ctan.org/pkg/uptex</ulink>). +</para> + +</sect1> +<sect1 label="2.4" id="LaTeX-command-syntax"> +<title>&latex; command syntax</title> + +<indexterm role="cp"><primary>command syntax</primary></indexterm> +<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 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>Some of &latex;’s commands are a <firstterm>declaration</firstterm>. Such a command +changes the value the meaning of some other command or parameter. For +instance, the <literal>\mainmatter</literal> declaration changes the typesetting of +page numbers from roman numerals to arabic (see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter & +\mainmatter & \backmatter</link>). +</para> +<para>&latex; has the convention that some commands have a <literal>*</literal> form that +is related to the form without a <literal>*</literal>, such as <literal>\chapter</literal> and +<literal>\chapter*</literal>. The exact difference in behavior varies from command +to command. +</para> +<para>This manual describes all accepted options and <literal>*</literal>-forms for the +commands it covers (barring unintentional omissions, a.k.a. bugs). +</para> + +</sect1> +<sect1 label="2.5" id="Environment"> +<title>Environment</title> + +<para>Synopsis: +</para> +<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> +<screen>\begin{verse} + There once was a man from Nantucket \\ + ... +\end{verse} +</screen> +<para>See <link linkend="Environments">Environments</link> for a list of environments. Particularly notable is +that every &latex; document must have a <literal>document</literal> environment, +a <literal>\begin{document} ... \end{document}</literal> pair. +</para> +<para>The <replaceable>environment name</replaceable> at the beginning must exactly match that at +the end. This includes the case where <replaceable>environment name</replaceable> ends in a +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> + +</sect1> +<sect1 label="2.6" id="CTAN"> +<title>CTAN: the Comprehensive &tex; Archive Network</title> + +<indexterm role="cp"><primary>CTAN</primary></indexterm> + +<para>The Comprehensive &tex; Archive Network, CTAN, is the &tex; and +&latex; community’s repository of free material. It is a set of +Internet sites around the world that offer material related to &latex; +for download. Visit CTAN on the web at <ulink url="https://ctan.org">https://ctan.org</ulink>. +</para> +<para>This material is organized into packages, discrete bundles that +typically offer some coherent functionality and are maintained by one +person or a small number of people. For instance, many publishers have +a package that allows authors to format papers to that publisher’s +specifications. +</para> +<para>In addition to the massive holdings, the web site offers features such +as search by name or by functionality. +</para> +<indexterm role="cp"><primary>DANTE e.V.</primary></indexterm> +<indexterm role="cp"><primary>mirrors of CTAN</primary></indexterm> +<para>CTAN is not a single site, but instead is a set of sites. One of the +sites is the core. This site actively manages the material, for +instance, by accepting uploads of new or updated packages. It is +hosted by the German &tex; group DANTE e.V. Other sites around the +world help out by mirroring, that is, automatically syncing their +collections with the core site and then in turn making their copies +publicly available. This gives users close to their location better +access and relieves the load on the core site. The list of mirrors is +at <ulink url="https://ctan.org/mirrors">https://ctan.org/mirrors</ulink>. +</para> + +</sect1> +</chapter> +<chapter label="3" id="Document-classes"> +<title>Document classes</title> + +<indexterm role="cp"><primary>document classes</primary></indexterm> +<indexterm role="cp"><primary>classes of documents</primary></indexterm> +<indexterm role="fn"><primary>\documentclass</primary></indexterm> + +<para>The document’s overall class is defined with this command, which is +normally the first command in a &latex; source file. +</para> +<screen>\documentclass[<replaceable>options</replaceable>]{<replaceable>class</replaceable>} +</screen> +<indexterm role="fn"><primary>article class</primary></indexterm> +<indexterm role="fn"><primary>report class</primary></indexterm> +<indexterm role="fn"><primary>book class</primary></indexterm> +<indexterm role="fn"><primary>letter class</primary></indexterm> +<indexterm role="fn"><primary>slides class</primary></indexterm> +<para>The following document <replaceable>class</replaceable> names are built into &latex;. +(Many other document classes are available as separate packages; +see <link linkend="Overview">Overview</link>.) +</para> +<variablelist><varlistentry><term><literal>article</literal> +</term><listitem><anchor id="document-classes-article"/><para>For a journal article, a presentation, and miscellaneous general use. +</para> +</listitem></varlistentry><varlistentry><term><literal>book</literal> +</term><listitem><anchor id="document-classes-book"/><para>Full-length books, including chapters and possibly including front +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><anchor id="document-classes-letter"/><para>Mail, optionally including mailing labels +(see <link linkend="Letters">Letters</link>). +</para> +</listitem></varlistentry><varlistentry><term><literal>report</literal> +</term><listitem><anchor id="document-classes-report"/><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. +</para> +</listitem></varlistentry><varlistentry><term><literal>slides</literal> +</term><listitem><anchor id="document-classes-slides"/><para>For slide presentations—rarely used today. In its place the +<literal>beamer</literal> package is perhaps the most prevalent (see <link linkend="beamer-template">beamer +template</link>). +</para> +</listitem></varlistentry></variablelist> +<para>Standard <replaceable>options</replaceable> are described in the next section. +</para> + + +<sect1 label="3.1" id="Document-class-options"> +<title>Document class options</title> + +<indexterm role="cp"><primary>document class options</primary></indexterm> +<indexterm role="cp"><primary>options, document class</primary></indexterm> +<indexterm role="cp"><primary>class options</primary></indexterm> +<indexterm role="cp"><primary>global options</primary></indexterm> + +<para>You can specify <firstterm>global options</firstterm> or <firstterm>class options</firstterm> to the +<literal>\documentclass</literal> command by enclosing them in square brackets. To +specify more than one <replaceable>option</replaceable>, separate them with a comma. +</para> +<screen>\documentclass[<replaceable>option1</replaceable>,<replaceable>option2</replaceable>,...]{<replaceable>class</replaceable>} +</screen> +<para>Here is the list of the standard class options. +</para> +<indexterm role="fn"><primary>10pt option</primary></indexterm> +<indexterm role="fn"><primary>11pt option</primary></indexterm> +<indexterm role="fn"><primary>12pt option</primary></indexterm> +<para>All of the standard classes except <literal>slides</literal> accept the following +options for selecting the typeface size (default is <literal>10pt</literal>): +</para> +<screen>10pt 11pt 12pt +</screen> +<indexterm role="fn"><primary>a4paper option</primary></indexterm> +<indexterm role="fn"><primary>a5paper option</primary></indexterm> +<indexterm role="fn"><primary>b5paper option</primary></indexterm> +<indexterm role="fn"><primary>executivepaper option</primary></indexterm> +<indexterm role="fn"><primary>legalpaper option</primary></indexterm> +<indexterm role="fn"><primary>letterpaper option</primary></indexterm> +<para>All of the standard classes accept these options for selecting the paper +size (these show height by width): +</para> +<variablelist><varlistentry><term><literal>a4paper</literal> +</term><listitem><para>210 by 297mm (about 8.25 by 11.75 inches) +</para> +</listitem></varlistentry><varlistentry><term><literal>a5paper</literal> +</term><listitem><para>148 by 210mm (about 5.8 by 8.3 inches) +</para> +</listitem></varlistentry><varlistentry><term><literal>b5paper</literal> +</term><listitem><para>176 by 250mm (about 6.9 by 9.8 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>package, <literal>geometry</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm> + +<para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex; +(see <link linkend="TeX-engines">&tex; engines</link>), options other than <literal>letterpaper</literal> set +the print area but you must also set the physical paper size. One way +to do that is to put <literal>\pdfpagewidth=\paperwidth</literal> and +<literal>\pdfpageheight=\paperheight</literal> in your document’s preamble. +<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm> +</para> +<para>The <literal>geometry</literal> package provides flexible ways of setting the print +area and physical page size. +</para> +<indexterm role="fn"><primary>draft option</primary></indexterm> +<indexterm role="fn"><primary>final option</primary></indexterm> +<indexterm role="fn"><primary>fleqn option</primary></indexterm> +<indexterm role="fn"><primary>landscape option</primary></indexterm> +<indexterm role="fn"><primary>leqno option</primary></indexterm> +<indexterm role="fn"><primary>openbib option</primary></indexterm> +<indexterm role="fn"><primary>titlepage option</primary></indexterm> +<indexterm role="fn"><primary>notitlepage option</primary></indexterm> +<para>Miscellaneous other options: +</para> +<variablelist><varlistentry><term><literal>draft</literal> +</term><term><literal>final</literal> +</term><listitem><indexterm role="cp"><primary>black boxes, omitting</primary></indexterm> +<para>Mark (<literal>draft</literal>) or do not mark (<literal>final</literal>) overfull boxes with a +black box in the margin; default is <literal>final</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>fleqn</literal> +</term><listitem><indexterm role="cp"><primary>flush left equations</primary></indexterm> +<indexterm role="cp"><primary>centered equations</primary></indexterm> +<indexterm role="cp"><primary>equations, flush left vs. centered</primary></indexterm> +<para>Put displayed formulas flush left; default is centered. +</para> +</listitem></varlistentry><varlistentry><term><literal>landscape</literal> +</term><listitem><indexterm role="cp"><primary>landscape orientation</primary></indexterm> +<indexterm role="cp"><primary>portrait orientation</primary></indexterm> +<para>Selects landscape format; default is portrait. +</para> +</listitem></varlistentry><varlistentry><term><literal>leqno</literal> +</term><listitem><indexterm role="cp"><primary>left-hand equation numbers</primary></indexterm> +<indexterm role="cp"><primary>right-hand equation numbers</primary></indexterm> +<indexterm role="cp"><primary>equation numbers, left vs. right</primary></indexterm> +<para>Put equation numbers on the left side of equations; default is the right side. +</para> +</listitem></varlistentry><varlistentry><term><literal>openbib</literal> +</term><listitem><indexterm role="cp"><primary>bibliography format, open</primary></indexterm> +<para>Use “open” bibliography format. +</para> +</listitem></varlistentry><varlistentry><term><literal>titlepage</literal> +</term><term><literal>notitlepage</literal> +</term><listitem><indexterm role="cp"><primary>title page, separate or run-in</primary></indexterm> +<para>Specifies whether there is a separate page for the title information and +for the abstract also, if there is one. The default for the +<literal>report</literal> class is <literal>titlepage</literal>, for the other classes it is +<literal>notitlepage</literal>. +</para></listitem></varlistentry></variablelist> +<para>The following options are not available with the <literal>slides</literal> class. +</para> +<indexterm role="fn"><primary>onecolumn option</primary></indexterm> +<indexterm role="fn"><primary>twocolumn option</primary></indexterm> +<indexterm role="fn"><primary>oneside option</primary></indexterm> +<indexterm role="fn"><primary>twoside option</primary></indexterm> +<indexterm role="fn"><primary>openright option</primary></indexterm> +<indexterm role="fn"><primary>openany option</primary></indexterm> +<variablelist><varlistentry><term><literal>onecolumn</literal> +</term><term><literal>twocolumn</literal> +</term><listitem><para>Typeset in one or two columns; default is <literal>onecolumn</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>oneside</literal> +</term><term><literal>twoside</literal> +</term><listitem><indexterm role="fn"><primary>\evensidemargin</primary></indexterm> +<indexterm role="fn"><primary>\oddsidemargin</primary></indexterm> +<para>Selects one- or two-sided layout; default is <literal>oneside</literal>, except +that in the <literal>book</literal> class the default is <literal>twoside</literal>. +</para> +<para>For one-sided printing, the text is centered on the page. For two-sided +printing, the <literal>\evensidemargin</literal> (<literal>\oddsidemargin</literal>) parameter +determines the distance on even (odd) numbered pages between the left +side of the page and the text’s left margin, with <literal>\oddsidemargin</literal> +being 40% of the difference between <literal>\paperwidth</literal> and +<literal>\textwidth</literal>, and <literal>\evensidemargin</literal> is the remainder. +</para> +</listitem></varlistentry><varlistentry><term><literal>openright</literal> +</term><term><literal>openany</literal> +</term><listitem><para>Determines if a chapter should start on a right-hand page; default is +<literal>openright</literal> for <literal>book</literal>, and <literal>openany</literal> for <literal>report</literal>. +</para></listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>clock option to <literal>slides</literal> class</primary></indexterm> +<para>The <literal>slides</literal> class offers the option <literal>clock</literal> for printing +the time at the bottom of each note. +</para> + +</sect1> +<sect1 label="3.2" id="Additional-packages"> +<title>Additional packages</title> + +<indexterm role="cp"><primary>loading additional packages</primary></indexterm> +<indexterm role="cp"><primary>packages, loading additional</primary></indexterm> +<indexterm role="cp"><primary>additional packages, loading</primary></indexterm> +<indexterm role="fn"><primary>\usepackage</primary></indexterm> +<para>Load a package <replaceable>pkg</replaceable>, with the package options given in the comma-separated +list <replaceable>options</replaceable>, as here. +</para> +<screen>\usepackage[<replaceable>options</replaceable>]{<replaceable>pkg</replaceable>}. +</screen> +<para>To specify more than one package you can separate them with a comma, +as in <literal>\usepackage{<replaceable>pkg1</replaceable>,<replaceable>pkg2</replaceable>,...}</literal>, or use multiple +<literal>\usepackage</literal> commands. +</para> +<indexterm role="cp"><primary>global options</primary></indexterm> +<indexterm role="cp"><primary>options, global</primary></indexterm> +<para>Any options given in the <literal>\documentclass</literal> command that are unknown +to the selected document class are passed on to the packages loaded with +<literal>\usepackage</literal>. +</para> + +</sect1> +<sect1 label="3.3" id="Class-and-package-construction"> +<title>Class and package construction</title> + +<indexterm role="cp"><primary>document class commands</primary></indexterm> +<indexterm role="cp"><primary>commands, document class</primary></indexterm> +<indexterm role="cp"><primary>new class commands</primary></indexterm> + +<para>You can create new document classes and new packages. For instance, if +your memos must satisfy some local requirements, such as a +standard header for each page, then you could create a new class +<literal>smcmemo.cls</literal> and begin your documents with +<literal>\documentclass{smcmemo}</literal>. +</para> +<para>What separates a package from a document class is that the commands in a +package are useful across classes while those in a document class are +specific to that class. Thus, a command to set page headers is for a +package while a command to make the page headers say <literal>Memo from the +SMC Math Department</literal> is for a class. +<indexterm role="cp"><primary>class and package difference</primary></indexterm> +<indexterm role="cp"><primary>difference between class and package</primary></indexterm> +</para> +<para>Inside of a class or package file you can use the at-sign <literal>@</literal> as a +character in command names without having to surround the code +containing that command with <literal>\makeatletter</literal> and +<literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter & \makeatother</link>. This allow +you to create commands that users will not accidentally redefine. +Another technique is to preface class- or package-specific commands with +some string to prevent your class or package from interfering with +others. For instance, the class <literal>smcmemo</literal> might have commands +<literal>\smc@tolist</literal>, <literal>\smc@fromlist</literal>, etc. +</para> + + + +<sect2 label="3.3.1" id="Class-and-package-structure"> +<title>Class and package structure</title> + +<indexterm role="cp"><primary>class and package structure</primary></indexterm> +<indexterm role="cp"><primary>class file layout</primary></indexterm> +<indexterm role="cp"><primary>package file layout</primary></indexterm> +<indexterm role="cp"><primary>options, document class</primary></indexterm> +<indexterm role="cp"><primary>options, package</primary></indexterm> +<indexterm role="cp"><primary>class options</primary></indexterm> +<indexterm role="cp"><primary>package options</primary></indexterm> + +<para>A class file or package file typically has four parts. +</para><orderedlist numeration="arabic"><listitem><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex; +package or class and describes itself, using the <literal>\NeedsTeXFormat</literal> +and <literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands. +</para> +</listitem><listitem><para>The <firstterm>preliminary declarations part</firstterm> declares some commands and +can also load other files. Usually these commands will be those needed +for the code used in the next part. For example, an <literal>smcmemo</literal> +class might be called with an option to read in a file with a list of +people for the to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and +therefore needs to define a command +<literal>\newcommand{\setto}[1]{\def\@tolist{#1}}</literal> used in that +file. +</para> +</listitem><listitem><para>In the <firstterm>handle options part</firstterm> the class or package declares +and processes its options. Class options allow a user to start their +document as <literal>\documentclass[<replaceable>option list</replaceable>]{<replaceable>class +name</replaceable>}</literal>, to modify the behavior of the class. An example is when you +declare <literal>\documentclass[11pt]{article}</literal> to set the default +document font size. +</para> +</listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package usually does +most of its work: declaring new variables, commands and fonts, and +loading other files. +</para></listitem></orderedlist> +<para>Here is a starting class file, which should be saved as <filename>stub.cls</filename> +where &latex; can find it, for example in the same directory as the +<filename>.tex</filename> file. +</para> +<screen>\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{stub}[2017/07/06 stub to start building classes from] +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions\relax +\LoadClass{article} +</screen><indexterm role="cp"><primary>class file example</primary></indexterm> + +<para>It identifies itself, handles the class options via the default of +passing them all to the <literal>article</literal> class, and then loads the +<literal>article</literal> class to provide the basis for this class’s code. +</para> +<para>For more, see the official guide for class and package writers, the +Class Guide, at +<ulink url="http://www.latex-project.org/help/documentation/clsguide.pdf">http://www.latex-project.org/help/documentation/clsguide.pdf</ulink> (much +of the descriptions here derive from this document), or the tutorial +<ulink url="https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf">https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf</ulink>. +</para> + +</sect2> +<sect2 label="3.3.2" id="Class-and-package-commands"> +<title>Class and package commands</title> +<indexterm role="cp"><primary>class and package commands</primary></indexterm> +<indexterm role="cp"><primary>commands, class and package</primary></indexterm> + +<para>These are the commands designed to help writers of classes or packages. +</para> +<variablelist><varlistentry><term><literal>\AtBeginDvi{specials}</literal> +</term><listitem><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm> +<para>Save in a box register things that are written to the <filename>.dvi</filename> file +at the beginning of the shipout of the first page of the document. +</para> +</listitem></varlistentry><varlistentry><term><literal>\AtEndOfClass{<replaceable>code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\AtEndOfPackage{<replaceable>code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\AtEndOfClass</primary></indexterm> +<indexterm role="fn"><primary>\AtEndOfPackage</primary></indexterm> +<para>Hook to insert <replaceable>code</replaceable> to be executed when &latex; finishes +processing the current class or package. You can use these hooks +multiple times; the <literal>code</literal> will be executed in the order that you +called it. See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\CheckCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\CheckCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\CheckCommand</primary></indexterm> +<indexterm role="fn"><primary>\CheckCommand*</primary></indexterm> +<indexterm role="cp"><primary>new command, check</primary></indexterm> +<para>Like <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>) but does +not define <replaceable>cmd</replaceable>; instead it checks that the current definition of +<replaceable>cmd</replaceable> is exactly as given by <replaceable>definition</replaceable> and is or is not +<indexterm role="cp"><primary>long command</primary></indexterm> +<firstterm>long</firstterm> as expected. A long command is a command that accepts +<literal>\par</literal> within an argument. The <replaceable>cmd</replaceable> command is expected to be +long with the unstarred version of <literal>\CheckCommand</literal>. Raises an +error when the check fails. This allows you to check before you start +redefining <literal>cmd</literal> yourself that no other package has already +redefined this command. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageWarning{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassWarningNoLine{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageWarningNoLine{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassInfo{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageInfo{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassInfoNoLine{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageInfoNoLine{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\ClassError</primary></indexterm> +<indexterm role="fn"><primary>\PackageError</primary></indexterm> +<indexterm role="fn"><primary>\ClassWarning</primary></indexterm> +<indexterm role="fn"><primary>\PackageWarning</primary></indexterm> +<indexterm role="fn"><primary>\ClassWarningNoLine</primary></indexterm> +<indexterm role="fn"><primary>\PackageWarningNoLine</primary></indexterm> +<indexterm role="fn"><primary>\ClassInfo</primary></indexterm> +<indexterm role="fn"><primary>\PackageInfo</primary></indexterm> +<indexterm role="fn"><primary>\ClassInfoNoLine</primary></indexterm> +<indexterm role="fn"><primary>\PackageInfoNoLine</primary></indexterm> +<para>Produce an error message, or warning or informational messages. +</para> +<para>For <literal>\ClassError</literal> and <literal>\PackageError</literal> the message is +<replaceable>error text</replaceable>, followed by &tex;’s <literal>?</literal> error prompt. If the +user then asks for help by typing <literal>h</literal>, they see the <replaceable>help +text</replaceable>. +</para> +<para>The four warning commands are similar except that they write +<replaceable>warning text</replaceable> on the screen with no error prompt. The four info +commands write <replaceable>info text</replaceable> only in the transcript file. The +<literal>NoLine</literal> versions do not show the number of the line generating the +message, while the other versions do show that number. +</para> +<para>To format the messages, including the <replaceable>help text</replaceable>: use +<literal>\protect</literal> to stop a command from expanding, get a line break with +<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal> when a space +character does not allow it, like after a command. Note that &latex; +appends a period to the messages. +</para> +</listitem></varlistentry><varlistentry><term><literal>\CurrentOption</literal> +</term><listitem><indexterm role="fn"><primary>\CurrentOption</primary></indexterm> +<para>Expands to the name of the currently-being-processed option. Can only +be used within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> +or <literal>\DeclareOption*</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\DeclareOption</primary></indexterm> +<indexterm role="fn"><primary>\DeclareOption*</primary></indexterm> +<indexterm role="cp"><primary>class options</primary></indexterm> +<indexterm role="cp"><primary>package options</primary></indexterm> +<indexterm role="cp"><primary>options, class</primary></indexterm> +<indexterm role="cp"><primary>options, package</primary></indexterm> +<para>Make an option available to a user to invoke in their +<literal>\documentclass</literal> command. For example, the <literal>smcmemo</literal> class +could have an option <literal>\documentclass[logo]{smcmemo}</literal> allowing +users to put the institutional logo on the first page. The class file +must contain <literal>\DeclareOption{logo}{<replaceable>code</replaceable>}</literal> (and later, +<literal>\ProcessOptions</literal>). +</para> +<para>If you request an option that has not been declared, by default this +will produce a warning like <literal>Unused global option(s): [badoption].</literal> +Change this behaviour with the starred version +<literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>. For example, many classes extend +an existing class, using a declaration such as +<literal>\LoadClass{article}</literal>, and for passing extra options to the +underlying class use code such as this. +</para> +<screen>\DeclareOption*{% +\PassOptionsToClass{\CurrentOption}{article}% +} +</screen> +<para>Another example is that the class <literal>smcmemo</literal> may allow users to keep +lists of memo recipients in external files. Then the user could invoke +<literal>\documentclass[math]{smcmemo}</literal> and it will read the file +<literal>math.memo</literal>. This code handles the file if it exists and otherwise +passes the option to the <literal>article</literal> class. +</para> +<screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{% + \PassOptionsToClass{\CurrentOption}{article}}} +</screen> +</listitem></varlistentry><varlistentry><term><literal>\DeclareRobustCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\DeclareRobustCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\DeclareRobustCommand</primary></indexterm> +<indexterm role="fn"><primary>\DeclareRobustCommand*</primary></indexterm> +<indexterm role="cp"><primary>new command, definition</primary></indexterm> +<para>Like <literal>\newcommand</literal> and <literal>\newcommand*</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & +\renewcommand</link>) but these declare a robust command, even if some code +within the <replaceable>definition</replaceable> is fragile. (For a discussion of robust and +fragile commands see <link linkend="_005cprotect">\protect</link>.) Use this command to define new +robust commands or to redefine existing commands and make them +robust. Unlike <literal>\newcommand</literal> these do not give an error if macro +<replaceable>cmd</replaceable> already exists; instead, a log message is put into the +transcript file if a command is redefined. +</para> +<para>Commands defined this way are a bit less efficient than those defined +using <literal>\newcommand</literal> so unless the command’s data is fragile and the +command is used within a moving argument, use <literal>\newcommand</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>etoolbox</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>etoolbox</literal> package</primary></indexterm> +<para>The <filename>etoolbox</filename> package offers the commands +<literal>\newrobustcmd</literal>, <literal>\newrobustcmd*</literal>, as well as the commands +<literal>\renewrobustcmd</literal>, <literal>\renewrobustcmd*</literal>, and the commands +<literal>\providerobustcmd</literal>, and <literal>\providerobustcmd*</literal>. These are +similar to <literal>\newcommand</literal>, <literal>\newcommand*</literal>, +<literal>\renewcommand</literal>, <literal>\renewcommand*</literal>, <literal>\providecommand</literal>, and +<literal>\providecommand*</literal>, but define a robust <replaceable>cmd</replaceable> with two +advantages as compared to <literal>\DeclareRobustCommand</literal>: +</para><orderedlist numeration="arabic"><listitem><para>They use the low-level e-&tex; protection mechanism rather than the +higher level &latex; <literal>\protect</literal> mechanism, so they do not incur +the slight loss of performance mentioned above, and +</para></listitem><listitem><para>They make the same distinction between <literal>\new…</literal>, +<literal>\renew…</literal>, and <literal>\provide…</literal>, as the standard +commands, so they do not just make a log message when you redefine +<replaceable>cmd</replaceable> that already exists, in that case you need to use either +<literal>\renew…</literal> or <literal>\provide…</literal> or you get an error. +</para></listitem></orderedlist> + +</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\IfFileExists</primary></indexterm> +<indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm> +<para>Execute <replaceable>true code</replaceable> if &latex; finds the file <filename><replaceable>file +name</replaceable></filename> or <replaceable>false code</replaceable> otherwise. In the first case it executing +<replaceable>true code</replaceable> and then inputs the file. Thus the command +</para> +<screen>\IfFileExists{img.pdf}{% + \includegraphics{img.pdf}}{\typeout{!! img.pdf not found} +</screen> +<para>will include the graphic <filename>img.pdf</filename> if it is found and otherwise +give a warning. +</para> +<para>This command looks for the file in all search paths that &latex; uses, +not only in the current directory. To look only in the current +directory do something like <literal>\IfFileExists{./filename}{<replaceable>true +code</replaceable>}{<replaceable>false code</replaceable>}</literal>. If you ask for a filename without a +<literal>.tex</literal> extension then &latex; will first look for the file by +appending the <literal>.tex</literal>; for more on how &latex; handles file +extensions see <link linkend="_005cinput">\input</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\LoadClass[<replaceable>options list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\LoadClassWithOptions{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\LoadClass</primary></indexterm> +<indexterm role="fn"><primary>\LoadClassWithOptions</primary></indexterm> +<para>Load a class, as with <literal>\documentclass[<replaceable>options +list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release info</replaceable>]</literal>. An example is +<literal>\LoadClass[twoside]{article}</literal>. +</para> +<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The +<replaceable>release date</replaceable> is optional. If present it must have the form +<replaceable>YYYY/MM/DD</replaceable>. +<!-- BTW, there are at-macros documented in macros2e.pdf to check the version --> +<!-- and do some actions conditionnally on version later or not to some --> +<!-- date. --> +</para> +<para>If you request a <replaceable>release date</replaceable> and the date of the package +installed on your system is earlier, then you get a warning on the +screen and in the log like this. +</para> +<screen>You have requested, on input line 4, version `2038/01/19' of +document class article, but only version `2014/09/29 v1.4h +Standard LaTeX document class' is available. +</screen> +<para>The command version <literal>\LoadClassWithOptions</literal> uses the list of +options for the current class. This means it ignores any options passed +to it via <literal>\PassOptionsToClass</literal>. This is a convenience command +that lets you build classes on existing ones, such as the standard +<literal>article</literal> class, without having to track which options were passed. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ExecuteOptions{<replaceable>options-list</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm> +<para>For each option <replaceable>option</replaceable> in the <replaceable>options-list</replaceable>, in order, this command +executes the command <literal>\ds@<replaceable>option</replaceable></literal>. If this command is not +defined then that option is silently ignored. +</para> +<para>It can be used to provide a default option list before +<literal>\ProcessOptions</literal>. For example, if in a class file you want the +default to be 11pt fonts then you could specify +<literal>\ExecuteOptions{11pt}\ProcessOptions\relax</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm> +<para>Specifies the format that this class must be run under. Often issued +as the first line of a class file, and most often used as: +<literal>\NeedsTeXFormat{LaTeX2e}</literal>. When a document using that class is +processed, the format name given here must match the format that is +actually being run (including that the <replaceable>format</replaceable> string is case +sensitive). If it does not match then execution stops with an error +like ‘<literal>This file needs format `LaTeX2e' but this is `xxx'.</literal>’ +</para> +<para>To specify a version of the format that you know to have certain +features, include the optional <replaceable>format date</replaceable> on which those features +were implemented. If present it must be in the form <literal>YYYY/MM/DD</literal>. +If the format version installed on your system is earlier than +<replaceable>format date</replaceable> then you get a warning like this. +</para> +<screen>You have requested release `2038/01/20' of LaTeX, but only +release `2016/02/01' is available. +</screen> +</listitem></varlistentry><varlistentry><term><literal>\OptionNotUsed</literal> +</term><listitem><indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm> +<para>Adds the current option to the list of unused options. Can only be used +within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> or +<literal>\DeclareOption*</literal>. +</para> +<!-- I cannot reproduce this behavior as it is documented in clsguide. --> +<!-- In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues --> +<!-- on the console a warning like @code{LaTeX Warning: Unused global --> +<!-- option(s): [unusedoption].} with the list of not-used options when it --> +<!-- reaches @code{\begin@{document@}}. --> + +</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>option list</replaceable>}{<replaceable>class name</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>option list</replaceable>}{<replaceable>package name</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm> +<indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm> +<para>Adds the options in the comma-separated list <replaceable>option list</replaceable> to the +options used by any future <literal>\RequirePackage</literal> or <literal>\usepackage</literal> +command for package <replaceable>package name</replaceable> or the class <replaceable>class name</replaceable>. +</para> +<para>The reason for these commands is: you may load a package any number of +times with no options but if you want options then you may only supply +them when you first load the package. Loading a package with options +more than once will get you an error like <literal>Option clash for package +foo.</literal> (&latex; throws an error even if there is no conflict between the +options.) +</para> +<para>If your own code is bringing in a package twice then you can collapse +that to once, for example replacing the two +<literal>\RequirePackage[landscape]{geometry}</literal> and +<literal>\RequirePackage[margins=1in]{geometry}</literal> with the single command +<literal>\RequirePackage[landscape,margins=1in]{geometry}</literal>. +</para> +<para>However, imagine that you are loading <filename>firstpkg</filename> and inside that +package it loads <filename>secondpkg</filename>, and you need the second package to be +loaded with option <literal>draft</literal>. Then before doing the first package +you must queue up the options for the second package, like this. +</para> +<screen>\PassOptionsToPackage{draft}{secondpkg} +\RequirePackage{firstpkg} +</screen> +<para>(If <literal>firstpkg.sty</literal> loads an option in conflict with what you want +then you may have to alter its source.) +</para> +<para>These commands are useful for general users as well as class and package +writers. For instance, suppose a user wants to load the <literal>graphicx</literal> +package with the option <literal>draft</literal> and also wants to use a class +<literal>foo</literal> that loads the <literal>graphicx</literal> package, but without that +option. The user could start their &latex; file with +<literal>\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ProcessOptions</literal> +</term></varlistentry><varlistentry><term><literal>\ProcessOptions*<replaceable>\@options</replaceable></literal> +</term><listitem><indexterm role="fn"><primary>\ProcessOptions</primary></indexterm> +<indexterm role="fn"><primary>\ProcessOptions*</primary></indexterm> +<para>Execute the code for each option that the user has invoked. Include it +in the class file as <literal>\ProcessOptions\relax</literal> (because of the +existence of the starred command). +</para> +<para>Options come in two types. <firstterm>Local options</firstterm> have been specified for this +particular package in the <replaceable>options</replaceable> argument of +<literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>, +<literal>\usepackage[<replaceable>options</replaceable>]</literal>, or +<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. <firstterm>Global options</firstterm> are those given +by the class user in <literal>\documentclass[<replaceable>options</replaceable>]</literal> (If an option +is specified both locally and globally then it is local.) +</para> +<para>When <literal>\ProcessOptions</literal> is called for a package <filename>pkg.sty</filename>, the +following happens: +</para><orderedlist numeration="arabic"><listitem><para>For each option <replaceable>option</replaceable> so far declared +with <literal>\DeclareOption</literal>, it looks to see if that option is either a +global or a local option for <literal>pkg</literal>. If so then it executes the +declared code. This is done in the order in which these options were +given in <filename>pkg.sty</filename>. +</para></listitem><listitem><para>For each remaining local option, it executes the command +<literal>\ds@</literal><replaceable>option</replaceable> if it has been defined somewhere (other than by +a <literal>\DeclareOption</literal>); otherwise, it executes the default option code +given in <literal>\DeclareOption*</literal>. If no default option code has been +declared then it gives an error message. This is done in the order in +which these options were specified. +</para></listitem></orderedlist> +<para>When <literal>\ProcessOptions</literal> is called for a class it works in the same +way except that all options are local, and the default <replaceable>code</replaceable> for +<literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error. +</para> +<para>The starred version <literal>\ProcessOptions*</literal> executes the +options in the order specified in the calling commands, rather than in +the order of declaration in the class or package. For a package this +means that the global options are processed first. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm> +<indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm> +<para>Identifies the class or package, printing a message to the screen and +the log file. +</para> +<para>When you load a class or package, for example with +<literal>\documentclass{smcmemo}</literal> or <literal>\usepackage{test}</literal>, &latex; +inputs a file. If the name of the file does not match the class or +package name declared in it then you get a warning. Thus, if you invoke +<literal>\documentclass{smcmemo}</literal>, and the file <filename>smcmemo.cls</filename> has +the statement <literal>\ProvidesClass{xxx}</literal> then you get a warning like +<literal>You have requested document class `smcmemo', but the document +class provides 'xxx'.</literal> This warning does not prevent &latex; from +processing the rest of the class file normally. +</para> +<para>If you include the optional argument then you must include a date, +before any spaces, of the form <literal>YYYY/MM/DD</literal>. The rest of the +optional argument is free-form, although it traditionally identifies the +class, and is written to the screen during compilation and to the log +file. Thus, if your file <filename>smcmemo.cls</filename> contains the line +<literal>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</literal> and +your document’s first line is <literal>\documentclass{smcmemo}</literal> then you +will see <literal>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</literal>. +</para> +<para>The date in the optional argument allows class and package users to ask +to be warned if the version of the class or package is earlier than +<replaceable>release date</replaceable>. For instance, a user could enter +<literal>\documentclass{smcmemo}[2018/10/12]</literal> or +<literal>\usepackage{foo}[[2017/07/07]]</literal> to require a class or package +with certain features by specifying that it must be released no earlier +than the given date. (Although, in practice package users only rarely +include a date, and class users almost never do.) +</para> +</listitem></varlistentry><varlistentry><term><literal>\ProvidesFile{<replaceable>file name</replaceable>}[<replaceable>additional information</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\ProvidesFile</primary></indexterm> +<para>Declare a file other than the main class and package files, such as +configuration files or font definition files. Put this command in that +file and you get in the log a string like <literal>File: test.config +2017/10/12 config file for test.cls</literal> for <replaceable>file name</replaceable> equal to +‘<literal>test.config</literal>’ and <replaceable>additional information</replaceable> equal to +‘<literal>2017/10/12 config file for test.cls</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>option list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\RequirePackageWithOptions{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\RequirePackage</primary></indexterm> +<indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm> +<para>Load a package, like the command <literal>\usepackage</literal> (see <link linkend="Additional-packages">Additional +packages</link>). The &latex; development team strongly recommends use of +these commands over Plain &tex;’s <literal>\input</literal>; see the Class +Guide. An example is +<literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>. +</para> +<para>The <replaceable>option list</replaceable>, if present, is a comma-separated list. The +<replaceable>release date</replaceable>, if present, must have the form <replaceable>YYYY/MM/DD</replaceable>. If +the release date of the package as installed on your system is earlier +than <replaceable>release date</replaceable> then you get a warning like <literal>You have +requested, on input line 9, version `2017/07/03' of package jhtest, but +only version `2000/01/01' is available</literal>. +</para> +<para>The <literal>\RequirePackageWithOptions</literal> version uses the list of options +for the current class. This means it ignores any options passed to it +via <literal>\PassOptionsToClass</literal>. This is a convenience command to allow +easily building classes on existing ones without having to track which +options were passed. +</para> +<para>The difference between <literal>\usepackage</literal> and <literal>\RequirePackage</literal> is +small. The <literal>\usepackage</literal> command is intended for the document file +while <literal>\RequirePackage</literal> is intended for package and class files. +Thus, using <literal>\usepackage</literal> before the <literal>\documentclass</literal> command +causes &latex; to give error like <literal>\usepackage before +\documentclass</literal>, but you can use <literal>\RequirePackage</literal> there. +</para></listitem></varlistentry></variablelist> + +</sect2> +</sect1> +</chapter> +<chapter label="4" id="Fonts"> +<title>Fonts</title> +<anchor id="Typefaces"/><!-- old name --> + +<indexterm role="cp"><primary>typefaces</primary></indexterm> +<indexterm role="cp"><primary>fonts</primary></indexterm> + +<para>Two important aspects of selecting a <firstterm>font</firstterm> are specifying a size +and a style. The &latex; commands for doing this are described here. +</para> + + +<sect1 label="4.1" id="Font-styles"> +<title>Font styles</title> + +<indexterm role="cp"><primary>font 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>In the table below the listed commands, the <literal>\text...</literal> commands, +is used with an argument, as in <literal>\textit{<replaceable>text</replaceable>}</literal>. This is +the preferred form. But shown after it, in parenthesis, is the +corresponding declaration form, which is sometimes useful. This form +takes no arguments, as in <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. In addition, each has an environment form such as +<literal>\begin{itshape}...\end{itshape}</literal>. +</para> +<para>These commands, in both the argument form and the declaration form, are +cumulative; for instance you can get bold sans serif by saying either of +<literal>\sffamily\bfseries</literal> or <literal>\bfseries\sffamily</literal>. +</para> +<indexterm role="fn"><primary>\nocorrlist</primary></indexterm> +<indexterm role="fn"><primary>\nocorr</primary></indexterm> +<para>One advantage of these commands is that they automatically insert italic +corrections if needed (see <link linkend="_005c_002f">\/</link>). Specifically, they insert the +italic correction unless the following character is in the list +<literal>\nocorrlist</literal>, which by default consists of a period and a comma. +To suppress the automatic insertion of italic correction, use +<literal>\nocorr</literal> at the start or end of the command argument, such as +<literal>\textit{\nocorr text}</literal> or <literal>\textsc{text \nocorr}</literal>. +</para> +<variablelist><varlistentry><term><literal>\textrm (\rmfamily)</literal> +</term><listitem><indexterm role="fn"><primary>\textrm</primary></indexterm> +<indexterm role="fn"><primary>\rmfamily</primary></indexterm> +<para>Roman. +</para> +</listitem></varlistentry><varlistentry><term><literal>\textit (\itshape)</literal> +</term><listitem><indexterm role="fn"><primary>\textit</primary></indexterm> +<indexterm role="fn"><primary>\itshape</primary></indexterm> +<para>Italics. +</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> +<para>Medium weight (default). +</para> +</listitem></varlistentry><varlistentry><term><literal>\textbf (\bfseries)</literal> +</term><listitem><indexterm role="fn"><primary>\textbf</primary></indexterm> +<indexterm role="fn"><primary>\bfseries</primary></indexterm> +<para>Boldface. +</para> +</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). +</para> +</listitem></varlistentry><varlistentry><term><literal>\textsl (\slshape)</literal> +</term><listitem><indexterm role="fn"><primary>\textsl</primary></indexterm> +<indexterm role="fn"><primary>\slshape</primary></indexterm> +<para>Slanted. +</para> +</listitem></varlistentry><varlistentry><term><literal>\textsf (\sffamily)</literal> +</term><listitem><indexterm role="fn"><primary>\textsf</primary></indexterm> +<indexterm role="fn"><primary>\sffamily</primary></indexterm> +<para>Sans serif. +</para> +</listitem></varlistentry><varlistentry><term><literal>\textsc (\scshape)</literal> +</term><listitem><indexterm role="fn"><primary>\textsc</primary></indexterm> +<indexterm role="fn"><primary>\scshape</primary></indexterm> +<para>Small caps. +</para> +</listitem></varlistentry><varlistentry><term><literal>\texttt (\ttfamily)</literal> +</term><listitem><indexterm role="fn"><primary>\texttt</primary></indexterm> +<indexterm role="fn"><primary>\ttfamily</primary></indexterm> +<para>Typewriter. +</para> +</listitem></varlistentry><varlistentry><term><literal>\textnormal (\normalfont)</literal> +</term><listitem><indexterm role="fn"><primary>\textnormal</primary></indexterm> +<indexterm role="fn"><primary>\normalfont</primary></indexterm> +<para>Main document font. +</para> +</listitem></varlistentry></variablelist> +<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. They are +used as declarations: <literal>{\<replaceable>cmd</replaceable>...}</literal> instead of +<literal>\<replaceable>cmd</replaceable>{...}</literal>. +</para> +<para>(The unconditional commands below are an older version of font +switching. The earlier commands are an improvement in most +circumstances. But sometimes an unconditional font switch is precisely +what you want.) +</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 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>\it</primary></indexterm><literal>\it</literal> +</term><listitem><indexterm role="cp"><primary>italic font</primary></indexterm> +<para>Italics. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rm</primary></indexterm><literal>\rm</literal> +</term><listitem><indexterm role="cp"><primary>roman font</primary></indexterm> +<para>Roman. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sc</primary></indexterm><literal>\sc</literal> +</term><listitem><indexterm role="cp"><primary>small caps font</primary></indexterm> +<para>Small caps. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sf</primary></indexterm><literal>\sf</literal> +</term><listitem><indexterm role="cp"><primary>sans serif font</primary></indexterm> +<para>Sans serif. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sl</primary></indexterm><literal>\sl</literal> +</term><listitem><indexterm role="cp"><primary>slanted font</primary></indexterm> +<indexterm role="cp"><primary>oblique font</primary></indexterm> +<para>Slanted (oblique). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tt</primary></indexterm><literal>\tt</literal> +</term><listitem><indexterm role="cp"><primary>typewriter font</primary></indexterm> +<indexterm role="cp"><primary>monospace font</primary></indexterm> +<indexterm role="cp"><primary>fixed-width font</primary></indexterm> +<para>Typewriter (monospace, fixed-width). +</para> +</listitem></varlistentry></variablelist> +<para>The <literal>\em</literal> command is the unconditional version of <literal>\emph</literal>. +</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>package, <literal>textcomp</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm> + +<para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset +so-called “old-style” numerals, which have differing heights and +depths (and sometimes widths) from the standard “lining” numerals, +which all have the same height as uppercase letters. &latex;’s +default fonts support this, and will respect <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> + +<para>The following standard type size commands are supported by &latex;. +The table shows the command name and the corresponding actual font +size used (in points) with the ‘<literal>10pt</literal>’, ‘<literal>11pt</literal>’, and +‘<literal>12pt</literal>’ document size options, respectively (see <link linkend="Document-class-options">Document class +options</link>). +</para> +<indexterm role="fn"><primary>\tiny</primary></indexterm> +<indexterm role="fn"><primary>\scriptsize</primary></indexterm> +<indexterm role="fn"><primary>\footnotesize</primary></indexterm> +<indexterm role="fn"><primary>\small</primary></indexterm> +<indexterm role="fn"><primary>\normalsize</primary></indexterm> +<indexterm role="fn"><primary>\large</primary></indexterm> +<indexterm role="fn"><primary>\Large</primary></indexterm> +<indexterm role="fn"><primary>\LARGE</primary></indexterm> +<indexterm role="fn"><primary>\huge</primary></indexterm> +<indexterm role="fn"><primary>\Huge</primary></indexterm> + +<informaltable><tgroup cols="4"><colspec colwidth="23*"></colspec><colspec colwidth="7*"></colspec><colspec colwidth="7*"></colspec><colspec colwidth="5*"></colspec><thead><row><entry><para>Command </para></entry><entry><para><literal>10pt</literal> </para></entry><entry><para><literal>11pt</literal> </para></entry><entry><para><literal>12pt</literal> +</para></entry></row></thead><tbody><row><entry><para><literal>\tiny</literal> +</para></entry><entry><para>5 </para></entry><entry><para>6 </para></entry><entry><para>6 +</para></entry></row><row><entry><para><literal>\scriptsize</literal> +</para></entry><entry><para>7 </para></entry><entry><para>8 </para></entry><entry><para>8 +</para></entry></row><row><entry><para><literal>\footnotesize</literal> +</para></entry><entry><para>8 </para></entry><entry><para>9 </para></entry><entry><para>10 +</para></entry></row><row><entry><para><literal>\small</literal> +</para></entry><entry><para>9 </para></entry><entry><para>10 </para></entry><entry><para>10.95 +</para></entry></row><row><entry><para><literal>\normalsize</literal> (default) +</para></entry><entry><para>10 </para></entry><entry><para>10.95 </para></entry><entry><para>12 +</para></entry></row><row><entry><para><literal>\large</literal> +</para></entry><entry><para>12 </para></entry><entry><para>12 </para></entry><entry><para>14.4 +</para></entry></row><row><entry><para><literal>\Large</literal> +</para></entry><entry><para>14.4 </para></entry><entry><para>14.4 </para></entry><entry><para>17.28 +</para></entry></row><row><entry><para><literal>\LARGE</literal> +</para></entry><entry><para>17.28 </para></entry><entry><para>17.28 </para></entry><entry><para>20.74 +</para></entry></row><row><entry><para><literal>\huge</literal> +</para></entry><entry><para>20.74 </para></entry><entry><para>20.74 </para></entry><entry><para>24.88 +</para></entry></row><row><entry><para><literal>\Huge</literal> +</para></entry><entry><para>24.88 </para></entry><entry><para>24.88 </para></entry><entry><para>24.88 +</para></entry></row></tbody></tgroup></informaltable> +<para>The commands are listed here in declaration forms. You use them by +declaring them, as with this example. +</para> +<screen>\begin{quotation} \small + The Tao that can be named is not the eternal Tao. +\end{quotation} +</screen> +<para>The scope of the <literal>\small</literal> lasts until the end of the +<literal>quotation</literal> environment. It would also end at the next type style +command or the end of the current group, so you could enclose it in +extra curly braces <literal>{\small We are here, we are here, we are +here!}</literal>. You can instead use the environment form of these commands; +for instance, <literal>\begin{tiny}...\end{tiny}</literal>. +</para> + +</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><anchor id="low-level-font-commands-fontencoding"/><varlistentry><term><literal>\fontencoding{<replaceable>encoding</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\fontencoding</primary></indexterm> +<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. For more, see +<ulink url="https://ctan.org/pkg/encguide">https://ctan.org/pkg/encguide</ulink>. +</para> +<anchor id="low-level-font-commands-fontfamily"/></listitem></varlistentry><varlistentry><term><literal>\fontfamily{<replaceable>family</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\fontfamily</primary></indexterm> +<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> +<informaltable><tgroup cols="2"><colspec colwidth="4*"></colspec><colspec colwidth="37*"></colspec><tbody><row><entry><para><literal>pag</literal> +</para></entry><entry><para>Avant Garde +</para></entry></row><row><entry><para><literal>fvs</literal> +</para></entry><entry><para>Bitstream Vera Sans +</para></entry></row><row><entry><para><literal>pbk</literal> +</para></entry><entry><para>Bookman +</para></entry></row><row><entry><para><literal>bch</literal> +</para></entry><entry><para>Charter +</para></entry></row><row><entry><para><literal>ccr</literal> +</para></entry><entry><para>Computer Concrete +</para></entry></row><row><entry><para><literal>cmr</literal> +</para></entry><entry><para>Computer Modern +</para></entry></row><row><entry><para><literal>cmss</literal> +</para></entry><entry><para>Computer Modern Sans Serif +</para></entry></row><row><entry><para><literal>cmtt</literal> +</para></entry><entry><para>Computer Modern Typewriter +</para></entry></row><row><entry><para><literal>pcr</literal> +</para></entry><entry><para>Courier +</para></entry></row><row><entry><para><literal>phv</literal> +</para></entry><entry><para>Helvetica +</para></entry></row><row><entry><para><literal>fi4</literal> +</para></entry><entry><para>Inconsolata +</para></entry></row><row><entry><para><literal>lmr</literal> +</para></entry><entry><para>Latin Modern +</para></entry></row><row><entry><para><literal>lmss</literal> +</para></entry><entry><para>Latin Modern Sans +</para></entry></row><row><entry><para><literal>lmtt</literal> +</para></entry><entry><para>Latin Modern Typewriter +</para></entry></row><row><entry><para><literal>pnc</literal> +</para></entry><entry><para>New Century Schoolbook +</para></entry></row><row><entry><para><literal>ppl</literal> +</para></entry><entry><para>Palatino +</para></entry></row><row><entry><para><literal>ptm</literal> +</para></entry><entry><para>Times +</para></entry></row><row><entry><para><literal>uncl</literal> +</para></entry><entry><para>Uncial +</para></entry></row><row><entry><para><literal>put</literal> +</para></entry><entry><para>Utopia +</para></entry></row><row><entry><para><literal>pzc</literal> +</para></entry><entry><para>Zapf Chancery +</para></entry></row></tbody></tgroup></informaltable> + +<anchor id="low-level-font-commands-fontseries"/></listitem></varlistentry><varlistentry><term><literal>\fontseries{<replaceable>series</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\fontseries</primary></indexterm> +<indexterm role="cp"><primary>series, of fonts</primary></indexterm> +<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> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="17*"></colspec><tbody><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium (normal) +</para></entry></row><row><entry><para><literal>b</literal> +</para></entry><entry><para>Bold +</para></entry></row><row><entry><para><literal>c</literal> +</para></entry><entry><para>Condensed +</para></entry></row><row><entry><para><literal>bc</literal> +</para></entry><entry><para>Bold condensed +</para></entry></row><row><entry><para><literal>bx</literal> +</para></entry><entry><para>Bold extended +</para></entry></row></tbody></tgroup></informaltable> +<indexterm role="cp"><primary>weights, of fonts</primary></indexterm> +<para>The possible values for weight, individually, are: +</para> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="18*"></colspec><tbody><row><entry><para><literal>ul</literal> +</para></entry><entry><para>Ultra light +</para></entry></row><row><entry><para><literal>el</literal> +</para></entry><entry><para>Extra light +</para></entry></row><row><entry><para><literal>l</literal> +</para></entry><entry><para>Light +</para></entry></row><row><entry><para><literal>sl</literal> +</para></entry><entry><para>Semi light +</para></entry></row><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium (normal) +</para></entry></row><row><entry><para><literal>sb</literal> +</para></entry><entry><para>Semi bold +</para></entry></row><row><entry><para><literal>b</literal> +</para></entry><entry><para>Bold +</para></entry></row><row><entry><para><literal>eb</literal> +</para></entry><entry><para>Extra bold +</para></entry></row><row><entry><para><literal>ub</literal> +</para></entry><entry><para>Ultra bold +</para></entry></row></tbody></tgroup></informaltable> +<indexterm role="cp"><primary>widths, of fonts</primary></indexterm> +<para>The possible values for width, individually, are (the meaning and +relationship of these terms varies with individual typefaces): +</para> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="15*"></colspec><tbody><row><entry><para><literal>uc</literal> +</para></entry><entry><para>Ultra condensed +</para></entry></row><row><entry><para><literal>ec</literal> +</para></entry><entry><para>Extra condensed +</para></entry></row><row><entry><para><literal>c</literal> +</para></entry><entry><para>Condensed +</para></entry></row><row><entry><para><literal>sc</literal> +</para></entry><entry><para>Semi condensed +</para></entry></row><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium +</para></entry></row><row><entry><para><literal>sx</literal> +</para></entry><entry><para>Semi expanded +</para></entry></row><row><entry><para><literal>x</literal> +</para></entry><entry><para>Expanded +</para></entry></row><row><entry><para><literal>ex</literal> +</para></entry><entry><para>Extra expanded +</para></entry></row><row><entry><para><literal>ux</literal> +</para></entry><entry><para>Ultra expanded +</para></entry></row></tbody></tgroup></informaltable> +<para>When forming the <replaceable>series</replaceable> string from the weight and width, drop the +<literal>m</literal> that stands for medium weight or medium width, unless both +weight and width are <literal>m</literal>, in which case use just one +(‘<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> +<anchor id="low-level-font-commands-fontshape"/><para>Select font shape. Valid shapes are: +</para> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="19*"></colspec><tbody><row><entry><para><literal>n</literal> +</para></entry><entry><para>Upright (normal) +</para></entry></row><row><entry><para><literal>it</literal> +</para></entry><entry><para>Italic +</para></entry></row><row><entry><para><literal>sl</literal> +</para></entry><entry><para>Slanted (oblique) +</para></entry></row><row><entry><para><literal>sc</literal> +</para></entry><entry><para>Small caps +</para></entry></row><row><entry><para><literal>ui</literal> +</para></entry><entry><para>Upright italics +</para></entry></row><row><entry><para><literal>ol</literal> +</para></entry><entry><para>Outline +</para></entry></row></tbody></tgroup></informaltable> +<para>The two last shapes are not available for most font families, and +small caps are often missing as well. +</para> +<anchor id="low-level-font-commands-fontsize"/></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 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> +<anchor id="low-level-font-commands-baselinestretch"/></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 a line skip change happen for the entire document, for instance +doubling it, by doing <literal>\renewcommand{\baselinestretch}{2.0}</literal> in +the preamble. +</para> +<indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>double spacing</primary></indexterm> +<para>However, the best way to double-space a document is to use the +<filename>setspace</filename> package. In addition to offering a number of spacing +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> +<anchor id="low-level-font-commands-linespread"/></listitem></varlistentry><varlistentry><term><literal>\linespread{<replaceable>factor</replaceable>}</literal> +</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 +just described. +</para> +<anchor id="low-level-font-commands-selectfont"/></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> +<anchor id="low-level-font-commands-usefont"/></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>. 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>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>Synopsis: +</para> +<screen>\onecolumn +</screen> +<para>Start a new page and produce 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>). 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>Synopses: +</para> +<screen>\twocolumn +\twocolumn[<replaceable>prelim one column text</replaceable>] +</screen> +<para>Start a new page and produce 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>). This command is fragile +(see <link linkend="_005cprotect">\protect</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>These parameters control typesetting in two-column output: +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\columnsep</primary></indexterm><literal>\columnsep</literal> +</term><listitem><anchor id="twocolumn-columnsep"/><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><anchor id="twocolumn-columnseprule"/><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><anchor id="twocolumn-columnwidth"/><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>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><anchor id="twocolumn-dbltopfraction"/><varlistentry><term><indexterm role="fn"><primary>\dbltopfraction</primary></indexterm><literal>\dbltopfraction</literal> +</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 exceeds this then you can take one of the following actions +to prevent it from floating all the way to the back of the document: +</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, as with +<literal>\renewcommand{\dbltopfraction}{0.9}</literal>. +</para> +<anchor id="twocolumn-dblfloatpagefraction"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatpagefraction</primary></indexterm><literal>\dblfloatpagefraction</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> +<anchor id="twocolumn-dblfloatsep"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dblfloatsep</primary></indexterm><literal>\dblfloatsep</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> +<anchor id="twocolumn-dbltextfloatsep"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dbltextfloatsep</primary></indexterm><literal>\dbltextfloatsep</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> +<anchor id="twocolumn-dbltopnumber"/></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 uses <literal>\twocolumn</literal>’s optional argument of 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"> +<title><literal>\flushbottom</literal></title> + +<indexterm role="fn"><primary>\flushbottom</primary></indexterm> + +<para>Make all pages in the documents after this declaration have the same +height, by stretching the vertical space where necessary to fill out the +page. This is most often used when making two-sided documents since the +differences in facing pages can be glaring. +</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>’. If you get that, one option is to +change to <literal>\raggedbottom</literal> (see <link linkend="_005craggedbottom">\raggedbottom</link>). Alternatively, +you can adjust the <literal>textheight</literal> to make compatible pages, or you +can add some vertical stretch glue between lines or between paragraphs, +as in <literal>\setlength{\parskip}{0ex plus0.1ex}</literal>. Your last option +is to, in a final editing stage, adjust the height of individual pages +(see <link linkend="_005cenlargethispage">\enlargethispage</link>). +</para> +<para>The <literal>\flushbottom</literal> state 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>Make all later pages the natural height of the material on that page; no +rubber vertical lengths will be stretched. Thus, in a two-sided +document the facing pages may be different heights. This command can go +at any point in the document body. See <link linkend="_005cflushbottom">\flushbottom</link>. +</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> +<sect1 label="5.5" id="Page-layout-parameters"> +<title>Page layout parameters</title> + +<indexterm role="cp"><primary>page layout parameters</primary></indexterm> +<indexterm role="cp"><primary>parameters, page layout</primary></indexterm> +<indexterm role="cp"><primary>layout, page parameters for</primary></indexterm> +<indexterm role="cp"><primary>header, parameters for</primary></indexterm> +<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>\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> +<anchor id="page-layout-parameters-columnsep"/><anchor id="page-layout-parameters-columnseprule"/><anchor id="page-layout-parameters-columnwidth"/><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> +<anchor id="page-layout-parameters-headheight"/><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><indexterm role="fn"><primary>\headsep</primary></indexterm> +<anchor id="page-layout-parameters-headsep"/><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><indexterm role="fn"><primary>\footskip</primary></indexterm> +<anchor id="page-layout-parameters-footskip"/><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><indexterm role="fn"><primary>\linewidth</primary></indexterm> +<anchor id="page-layout-parameters-linewidth"/><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> +<anchor id="page-layout-parameters-marginparpush"/><anchor id="page-layout-parameters-marginsep"/><anchor id="page-layout-parameters-marginparwidth"/><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> +<anchor id="page-layout-parameters-oddsidemargin"/><anchor id="page-layout-parameters-evensidemargin"/><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> +<anchor id="page-layout-parameters-paperheight"/><para>The height of the paper, as distinct from the height of the print area. +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> +<anchor id="page-layout-parameters-paperwidth"/><para>The width of the paper, as distinct from the width of the print area. +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><indexterm role="fn"><primary>\textheight</primary></indexterm> +<anchor id="page-layout-parameters-textheight"/><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><indexterm role="fn"><primary>\textwidth</primary></indexterm> +<anchor id="page-layout-parameters-textwidth"/><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 +(see <link linkend="_005ctwocolumn">\twocolumn</link>). +</para> +<para>In lists (see <link linkend="list">list</link>), <literal>\textwidth</literal> remains the width of the +entire page body (and <literal>\columnwidth</literal> the width of the entire +column), while <literal>\linewidth</literal> may decrease for nested lists. +</para> +<para>Inside a minipage (see <link linkend="minipage">minipage</link>) or <literal>\parbox</literal> +(see <link linkend="_005cparbox">\parbox</link>), all the width-related parameters are set to the +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> +<anchor id="page-layout-parameters-hsize"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hsize</primary></indexterm><literal>\hsize</literal> +</term><listitem><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><indexterm role="fn"><primary>topmargin</primary></indexterm> +<anchor id="page-layout-parameters-topmargin"/><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. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topskip</primary></indexterm><literal>\topskip</literal> +</term><listitem><indexterm role="fn"><primary>\topskip</primary></indexterm> +<anchor id="page-layout-parameters-topskip"/><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 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 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 end up +being typeset far from their place in the source. In particular, a +float that is big may migrate to the end of the document. In which +event, because all floats in a class must appear in sequential order, +every following 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>package, <literal>float</literal></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> +<indexterm role="cp"><primary>package, <literal>flafter</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>flafter</literal> package</primary></indexterm> + +<para>&latex; can typeset a float before where it appears in the source +(although on the same output page) if there is a <literal>t</literal> specifier in +the <replaceable>placement</replaceable> parameter. If this is not desired, and deleting +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> +<anchor id="floats-bottomfraction"/><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> +<anchor id="floats-floatpagefraction"/><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> +<anchor id="floats-textfraction"/><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> +<anchor id="floats-topfraction"/><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 a +command of the form <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> +<anchor id="floats-floatsep"/><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> +<anchor id="floats-intextsep"/><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> +<anchor id="floats-textfloatsep"/><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 a +command of the form <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> +<anchor id="floats-bottomnumber"/><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> +<anchor id="floats-dbltopnumber"/><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> +<anchor id="floats-topnumber"/><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> +<anchor id="floats-totalnumber"/><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 explanation of the +float placement algorithm is in Frank Mittelbach’s article “How to +influence the position of float environments like figure and table in +&latex;?” +(<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 commands</primary></indexterm> +<indexterm role="cp"><primary>part</primary></indexterm> +<indexterm role="cp"><primary>chapter</primary></indexterm> +<indexterm role="cp"><primary>section</primary></indexterm> +<indexterm role="cp"><primary>subsection</primary></indexterm> +<indexterm role="cp"><primary>paragraph</primary></indexterm> +<indexterm role="cp"><primary>subparagraph</primary></indexterm> +<indexterm role="fn"><primary>\part</primary></indexterm> +<indexterm role="fn"><primary>\chapter</primary></indexterm> +<indexterm role="fn"><primary>\section</primary></indexterm> +<indexterm role="fn"><primary>\subsection</primary></indexterm> +<indexterm role="fn"><primary>\paragraph</primary></indexterm> +<indexterm role="fn"><primary>\subparagraph</primary></indexterm> + +<para>Structure your text into divisions: parts, chapters, sections, etc. All +sectioning commands have the same form, one of: +</para> +<screen><replaceable>sectioning-command</replaceable>{<replaceable>title</replaceable>} +<replaceable>sectioning-command</replaceable>*{<replaceable>title</replaceable>} +<replaceable>sectioning-command</replaceable>[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>For instance, declare the start of a subsection as with +<literal>\subsection{Motivation}</literal>. +</para> +<para>The table has each <replaceable>sectioning-command</replaceable> in &latex;. All are +available in all of &latex;’s standard document classes <literal>book</literal>, +<literal>report</literal>, and <literal>article</literal>, except that <literal>\chapter</literal> is +not available in <literal>article</literal>. +</para> +<informaltable><tgroup cols="3"><colspec colwidth="25*"></colspec><colspec colwidth="25*"></colspec><colspec colwidth="40*"></colspec><thead><row><entry><para>Sectioning unit </para></entry><entry><para>Command </para></entry><entry><para>Level +</para></entry></row></thead><tbody><row><entry><para>Part +</para></entry><entry><para><literal>\part</literal> </para></entry><entry><para>-1 (<literal>book</literal>, <literal>report</literal>), 0 (<literal>article</literal>) +</para></entry></row><row><entry><para>Chapter +</para></entry><entry><para><literal>\chapter</literal> </para></entry><entry><para>0 +</para></entry></row><row><entry><para>Section +</para></entry><entry><para><literal>\section</literal> </para></entry><entry><para>1 +</para></entry></row><row><entry><para>Subsection +</para></entry><entry><para><literal>\subsection</literal> </para></entry><entry><para>2 +</para></entry></row><row><entry><para>Subsubsection +</para></entry><entry><para><literal>\subsubsection</literal> </para></entry><entry><para>3 +</para></entry></row><row><entry><para>Paragraph +</para></entry><entry><para><literal>\paragraph</literal> </para></entry><entry><para>4 +</para></entry></row><row><entry><para>Subparagraph +</para></entry><entry><para><literal>\subparagraph</literal> </para></entry><entry><para>5 +</para></entry></row></tbody></tgroup></informaltable> +<indexterm role="cp"><primary><literal>*</literal>-form of sectioning commands</primary></indexterm> +<para>All these commands have a <literal>*</literal>-form that prints <replaceable>title</replaceable> as usual +but is not numbered and does not make an entry in the table of contents. +An example of using this is for an appendix in an <literal>article</literal> . The +input <literal>\appendix\section{Appendix}</literal> gives the output ‘<literal>A +Appendix</literal>’ (see <link linkend="_005cappendix">\appendix</link>). You can lose the numbering ‘<literal>A</literal>’ +by instead entering <literal>\section*{Appendix}</literal> (articles often omit a +table of contents and have simple page headers so the other differences +from the <literal>\section</literal> command may not matter). +</para> +<para>The section title <replaceable>title</replaceable> provides the heading in the main text, but +it may also appear in the table of contents and in the running head or +foot (see <link linkend="Page-styles">Page styles</link>). You may not want the same text in these +places as in the main text. All of these commands have an optional +argument <replaceable>toc-title</replaceable> for these other places. +</para> +<para>The level number in the table above determines which sectional units are +numbered, and which appear in the table of contents. If the sectioning +command’s <replaceable>level</replaceable> is less than or equal to the value of the counter +<literal>secnumdepth</literal> then the titles for this sectioning command will be +numbered (see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link>). And, if <replaceable>level</replaceable> is less +than or equal to the value of the counter <literal>tocdepth</literal> then the table +of contents will have an entry for this sectioning unit +(see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<para>&latex; expects that before you have a <literal>\subsection</literal> you will have +a <literal>\section</literal> and, in a book, that before a <literal>\section</literal> you will +have a <literal>\chapter</literal>. Otherwise you can get a something like a +subsection numbered ‘<literal>3.0.1</literal>’. +</para> +<para>Two counters relate to the appearance of sectioning commands. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>secnumdepth</primary></indexterm><literal>secnumdepth</literal> +</term><listitem><indexterm role="fn"><primary>secnumdepth counter</primary></indexterm> +<indexterm role="cp"><primary>section numbers, printing</primary></indexterm> +<anchor id="sectioning-secnumdepth"/><anchor id="Sectioning_002fsecnumdepth"/><para>Controls which sectioning commands are +numbered. Suppress numbering of sectioning at any depth greater than +<replaceable>level</replaceable> <literal>\setcounter{secnumdepth}{<replaceable>level</replaceable>}</literal> +(see <link linkend="_005csetcounter">\setcounter</link>). See the above table for the level numbers. For +instance, if the <literal>secnumdepth</literal> is 1 in an <literal>article</literal> then a +<literal>\section{Introduction}</literal> command will produce output like ‘<literal>1 +Introduction</literal>’ while <literal>\subsection{Discussion}</literal> will produce output +like ‘<literal>Discussion</literal>’, without the number. &latex;’s default +<literal>secnumdepth</literal> is 3 in <filename>article</filename> class and  2 in the +<filename>book</filename> and <filename>report</filename> classes. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>tocdepth</primary></indexterm><literal>tocdepth</literal> +</term><listitem><indexterm role="fn"><primary>tocdepth counter</primary></indexterm> +<indexterm role="cp"><primary>table of contents, sectioning numbers printed</primary></indexterm> +<anchor id="sectioning-tocdepth"/><anchor id="Sectioning_002ftocdepth"/><para>Controls which sectioning units are listed in the table of contents. +The setting <literal>\setcounter{tocdepth}{<replaceable>level</replaceable>}</literal> makes the +sectioning units at <replaceable>level</replaceable> be the smallest ones listed +(see <link linkend="_005csetcounter">\setcounter</link>). See the above table for the level numbers. For +instance, if <literal>tocdepth</literal> is 1 then the table of contents will +list sections but not subsections. &latex;’s default +<literal>secnumdepth</literal> is 3 in <filename>article</filename> class and  2 in the +<filename>book</filename> and <filename>report</filename> classes. +</para> +</listitem></varlistentry></variablelist> + + +<sect1 label="6.1" id="_005cpart"> +<title><literal>\part</literal></title> + +<indexterm role="fn"><primary>\part</primary></indexterm> +<indexterm role="cp"><primary>part</primary></indexterm> +<indexterm role="cp"><primary>sectioning, part</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\part{<replaceable>title</replaceable>} +\part*{<replaceable>title</replaceable>} +\part[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Start a document part. The standard &latex; classes <literal>book</literal>, +<literal>report</literal>, and <literal>article</literal>, all have this command. +</para> +<para>This produces a document part, in a book. +</para> +<screen>\part{VOLUME I \\ + PERSONAL MEMOIRS OF U.\ S.\ GRANT} +\chapter{ANCESTRY--BIRTH--BOYHOOD.} +My family is American, and has been for generations, +in all its branches, direct and collateral. +</screen> +<para>In each standard class the <literal>\part</literal> command outputs a part number +such as ‘<literal>Part I</literal>’, alone on its line, in boldface, and in large +type. Then &latex; outputs <replaceable>title</replaceable>, also alone on its line, in +bold and in even larger type. In class <literal>book</literal>, the &latex; +default puts each part alone on its own page. If the book is two-sided +then &latex; will skip a page if needed to have the new part on an +odd-numbered page. In <literal>report</literal> it is again alone on a page, but +&latex; won’t force it onto an odd-numbered page. In an <literal>article</literal> +&latex; does not put it on a fresh page, but instead outputs the part +number and part title onto the main document page. +</para> +<para>The <literal>*</literal> form shows <replaceable>title</replaceable> +but it does not show the part number, does not increment the +<literal>part</literal> counter, and produces no table of contents entry. +</para> +<para>The optional argument <replaceable>toc-title</replaceable> will appear as the part title in +the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>) and in running +headers (see <link linkend="Page-styles">Page styles</link>). If it is not present then <replaceable>title</replaceable> +will be there. This example puts a line break in <replaceable>title</replaceable> but leaves +out the break in the table of contents. +</para> +<screen>\part[Up from the bottom; my life]{Up from the bottom\\ my life} +</screen> +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a part is -1 +(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>In the class <literal>article</literal>, if a paragraph immediately follows the part +title then it is not indented. To get an indent you can use the package +<filename>indentfirst</filename>. +</para> +<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm> + +<para>One package to change the behavior of <literal>\part</literal> is <filename>titlesec</filename>. +See its documentation on CTAN. +</para> + +</sect1> +<sect1 label="6.2" id="_005cchapter"> +<title><literal>\chapter</literal></title> + +<indexterm role="fn"><primary>\chapter</primary></indexterm> +<indexterm role="cp"><primary>chapter</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\chapter{<replaceable>title</replaceable>} +\chapter*{<replaceable>title</replaceable>} +\chapter[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Start a chapter. The standard &latex; classes <literal>book</literal> and +<literal>report</literal> have this command but <literal>article</literal> does not. +</para> +<para>This produces a chapter. +</para> +<screen>\chapter{Loomings} +Call me Ishmael. +Some years ago---never mind how long precisely---having little or no +money in my purse, and nothing particular to interest me on shore, I +thought I would sail about a little and see the watery part of +the world. +</screen> +<para>The &latex; default starts each chapter on a fresh page, an +odd-numbered page if the document is two-sided. It produces a chapter +number such as ‘<literal>Chapter 1</literal>’ in large boldface type (the size is +<literal>\huge</literal>). It then puts <replaceable>title</replaceable> on a fresh line, in boldface +type that is still larger (size <literal>\Huge</literal>). It also increments the +<literal>chapter</literal> counter, adds an entry to the table of contents +(see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>), and sets the running header +information (see <link linkend="Page-styles">Page styles</link>). +</para> +<para>The <literal>*</literal> form shows <replaceable>title</replaceable> on a fresh line, in boldface. +But it does not show the chapter number, does not increment the +<literal>chapter</literal> counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +<literal>headings</literal> in a two-sided document then the header will be from the +prior chapter.) This example illustrates. +</para> +<screen>\chapter*{Preamble} +</screen> +<para>The optional argument <replaceable>toc-title</replaceable> will appear as the chapter title +in the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>) and in +running headers (see <link linkend="Page-styles">Page styles</link>). If it is not present then +<replaceable>title</replaceable> will be there. This shows the full name in the chapter +title, +</para> +<screen>\chapter[Weyl]{Hermann Klaus Hugo (Peter) Weyl (1885--1955)} +</screen> +<para>but only ‘<literal>Weyl</literal>’ on the contents page. This puts a line break in +the title but that doesn’t work well with running headers so it omits +the break in the contents +</para> +<screen>\chapter[Given it all\\ my story]{Given it all\\ my story} +</screen> +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a chapter is 0 +(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>The paragraph that follows the chapter title is not indented, as is a +standard typographical practice. To get an indent use the package +<filename>indentfirst</filename>. +</para> +<para>You can change what is shown for the chapter number. To change it to +something like ‘<literal>Lecture 1</literal>’, put in the preamble either +<literal>\renewcommand{\chaptername}{Lecture}</literal> or this +(see <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter & \makeatother</link>). +</para> +<screen>\makeatletter +\renewcommand{\@chapapp}{Lecture} +\makeatother +</screen> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<para>To make this change because of the primary language for +the document, see the package <filename>babel</filename>. +</para> +<para>In a two-sided document &latex; puts a chapter on odd-numbered page, if +necessary leaving an even-numbered page that is blank except for any +running headers. To make that page completely blank, +see <link linkend="_005cclearpage-_0026-_005ccleardoublepage">\clearpage & \cleardoublepage</link>. +</para> +<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm> + +<para>To change the behavior of the <literal>\chapter</literal> command, you can copy its +definition from the &latex; format file and make adjustments. But +there are also many packages on CTAN that address this. One is +<filename>titlesec</filename>. See its documentation, but the example below gives a +sense of what it can do. +</para> +<screen>\usepackage{titlesec} % in preamble +\titleformat{\chapter} + {\Huge\bfseries} % format of title + {} % label, such as 1.2 for a subsection + {0pt} % length of separation between label and title + {} % before-code hook +</screen> +<para>This omits the chapter number ‘<literal>Chapter 1</literal>’ from the page but unlike +<literal>\chapter*</literal> it keeps the chapter in the table of contents and the +running headers. +</para> + +</sect1> +<sect1 label="6.3" id="_005csection"> +<title><literal>\section</literal></title> + +<indexterm role="fn"><primary>\section</primary></indexterm> +<indexterm role="cp"><primary>section</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\section{<replaceable>title</replaceable>} +\section*{<replaceable>title</replaceable>} +\section[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Start a section. The standard &latex; classes <literal>article</literal>, +<literal>book</literal>, and <literal>report</literal> all have this command. +</para> +<para>This produces a section. +</para> +<screen>In this Part we tend to be more interested in the function, +in the input-output behavior, +than in the details of implementing that behavior. + +\section{Turing machines} +Despite this desire to downplay implementation, +we follow the approach of A~Turing that the +first step toward defining the set of computable functions +is to reflect on the details of what mechanisms can do. +</screen> +<para>For the standard &latex; classes <literal>book</literal> and <literal>report</literal> the +default output is like ‘<literal>1.2 <replaceable>title</replaceable></literal>’ (for chapter 1, +section 2), alone on its line and flush left, in boldface and a +larger type (the type size is <literal>\Large</literal>). The same holds in +<literal>article</literal> except that there are no chapters in that class so it +looks like ‘<literal>2 <replaceable>title</replaceable></literal>’. +</para> +<para>The <literal>*</literal> form shows <replaceable>title</replaceable>. +But it does not show the section number, does not increment the +<literal>section</literal> counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +<literal>headings</literal> in a two-sided document then the header will be from the +prior section.) +</para> +<para>The optional argument <replaceable>toc-title</replaceable> will appear as the section title +in the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>) and in +running headers (see <link linkend="Page-styles">Page styles</link>). If it is not present then +<replaceable>title</replaceable> will be there. This shows the full name in the title of the +section, +</para> +<screen>\section[Elizabeth~II]{Elizabeth the Second, + by the Grace of God of the United Kingdom, + Canada and Her other Realms and Territories Queen, + Head of the Commonwealth, Defender of the Faith.} +</screen> +<para>but only ‘<literal>Elizabeth II</literal>’ on the contents page and in the headers. +This has a line break in <replaceable>title</replaceable> but that does not work with headers +so it is omitted from the contents and headers. +</para> +<screen>\section[Truth is, I cheated; my life story]{Truth is, + I cheated\\my life story} +</screen> +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a section is 1 +(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>The paragraph that follows the section title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package <filename>indentfirst</filename>. +</para> +<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm> + +<para>In general, to change the behavior of the <literal>\section</literal> command, there +are a number of options. One is the <literal>\@startsection</literal> command +(see <link linkend="_005c_0040startsection">\@startsection</link>). There are also many packages on CTAN that +address this, including <filename>titlesec</filename>. See the documentation but the +example below gives a sense of what they can do. +</para> +<!-- credit: egreg https://groups.google.com/forum/#!topic/comp.text.tex/tvc8oM5P4y4 --> +<screen>\usepackage{titlesec} % in preamble +\titleformat{\section} + {\normalfont\Large\bfseries} % format of title + {\makebox[1pc][r]{\thesection\hspace{1pc}}} % label + {0pt} % length of separation between label and title + {} % before-code hook +\titlespacing*{\section} + {-1pc}{18pt}{10pt}[10pc] +</screen> +<para>That puts the section number in the margin. +</para> + +</sect1> +<sect1 label="6.4" id="_005csubsection"> +<title><literal>\subsection</literal></title> + +<indexterm role="fn"><primary>\subsection</primary></indexterm> +<indexterm role="cp"><primary>subsection</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\subsection{<replaceable>title</replaceable>} +\subsection*{<replaceable>title</replaceable>} +\subsection[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Start a subsection. The standard &latex; classes <literal>article</literal>, +<literal>book</literal>, and <literal>report</literal> all have this command. +</para> +<para>This produces a subsection. +</para> +<screen>We will show that there are more functions than Turing machines and that +therefore some functions have no associated machine. + +\subsection{Cardinality} We will begin with two paradoxes that +dramatize the challenge to our intuition posed by comparing the sizes of +infinite sets. +</screen> +<para>For the standard &latex; classes <literal>book</literal> and <literal>report</literal> the +default output is like ‘<literal>1.2.3 <replaceable>title</replaceable></literal>’ (for chapter 1, +section 2, subsection 3), alone on its line and flush left, in +boldface and a larger type (the type size is <literal>\large</literal>). The same +holds in <literal>article</literal> except that there are no chapters in that class +so it looks like ‘<literal>2.3 <replaceable>title</replaceable></literal>’. +</para> +<para>The <literal>*</literal> form shows <replaceable>title</replaceable>. +But it does not show the section number, does not increment the +<literal>section</literal> counter, and produces no table of contents entry. +</para> +<para>The optional argument <replaceable>toc-title</replaceable> will appear as the section title +in the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>). If it is +not present then <replaceable>title</replaceable> will be there. This shows the full name in +the title of the section, +</para> +<screen>\subsection[$\alpha,\beta,\gamma$ paper]{\textit{The Origin of + Chemical Elements} by R.A.~Alpher, H.~Bethe, and G.~Gamow} +</screen> +<para>but only ‘<literal>α,β,γ +paper</literal>’ on the contents page. +</para> +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a subsection is 2 +(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>The paragraph that follows the subsection title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package <filename>indentfirst</filename>. +</para> +<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm> + +<para>There are a number of ways to change the behavior of the +<literal>\subsection</literal> command. One is the <literal>\@startsection</literal> command +(see <link linkend="_005c_0040startsection">\@startsection</link>). There are also many packages on CTAN that +address this, including <filename>titlesec</filename>. See the documentation but the +example below gives a sense of what they can do. +</para> +<screen>\usepackage{titlesec} % in preamble +\titleformat{\subsection}[runin] + {\normalfont\normalsize\bfseries} % format of the title + {\thesubsection} % label + {0.6em} % space between label and title + {} % before-code hook +</screen> +<para>That puts the subsection number and <replaceable>title</replaceable> in the first line of +text. +</para> + +</sect1> + +<sect1 label="6.5" id="_005csubsubsection-_0026-_005cparagraph-_0026-_005csubparagraph"> +<title><literal>\subsubsection</literal>, <literal>\paragraph</literal>, <literal>\subparagraph</literal></title> + +<indexterm role="fn"><primary>\subsubsection</primary></indexterm> +<indexterm role="cp"><primary>subsubsection</primary></indexterm> +<indexterm role="fn"><primary>\paragraph</primary></indexterm> +<indexterm role="cp"><primary>paragraph</primary></indexterm> +<indexterm role="fn"><primary>\subparagraph</primary></indexterm> +<indexterm role="cp"><primary>subparagraph</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\subsubsection{<replaceable>title</replaceable>} +\subsubsection*{<replaceable>title</replaceable>} +\subsubsection[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>or one of: +</para> +<screen>\paragraph{<replaceable>title</replaceable>} +\paragraph*{<replaceable>title</replaceable>} +\paragraph[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>or one of: +</para> +<screen>\subparagraph{<replaceable>title</replaceable>} +\subparagraph*{<replaceable>title</replaceable>} +\subparagraph[<replaceable>toc-title</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Start a subsubsection, paragraph, or subparagraph. The standard +&latex; classes <literal>article</literal>, <literal>book</literal>, and <literal>report</literal> all have +these commands, although they are not commonly used. +</para> +<para>This produces a subsubsection. +</para> +<screen>\subsubsection{Piston ring compressors: structural performance} +Provide exterior/interior wall cladding assemblies +capable of withstanding the effects of load and stresses from +consumer-grade gasoline engine piston rings. +</screen> +<para>The default output of each of the three does not change over the +standard &latex; classes <literal>article</literal>, <literal>book</literal>, and +<literal>report</literal>. For <literal>\subsubsection</literal> the <replaceable>title</replaceable> is alone on +its line, in boldface and normal size type. For <literal>\paragraph</literal> the +<replaceable>title</replaceable> is inline with the text, not indented, in boldface and +normal size type. For <literal>\subparagraph</literal> the <replaceable>title</replaceable> is inline +with the text, with a paragraph indent, in boldface and normal size type +(Because an <literal>article</literal> has no chapters its subsubsections are +numbered and so it looks like ‘<literal>1.2.3 <replaceable>title</replaceable></literal>’, for +section 1, subsection 2, and subsubsection 3. The other +two divisions are not numbered.) +</para> +<para>The <literal>*</literal> form shows <replaceable>title</replaceable>. But it does not increment the +associated counter and produces no table of contents entry (and does not +show the number for <literal>\subsubsection</literal>). +</para> +<para>The optional argument <replaceable>toc-title</replaceable> will appear as the division title +in the table of contents (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</link>). If it is +not present then <replaceable>title</replaceable> will be there. +</para> +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a subsubsection is 3, of +a paragraph is 4, and of a subparagraph is 5 +(see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link> and see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>The paragraph that follows the subsubsection title is not indented, as is a +standard typographical practice. One way to get an indent is to use the +package <filename>indentfirst</filename>. +</para> +<indexterm role="cp"><primary>package, <literal>titlesec</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>titlesec</literal> package</primary></indexterm> + +<para>There are a number of ways to change the behavior of the these commands. +One is the <literal>\@startsection</literal> command (see <link linkend="_005c_0040startsection">\@startsection</link>). +There are also many packages on CTAN that address this, including +<filename>titlesec</filename>. See the documentation on CTAN. +</para> + +</sect1> + +<sect1 label="6.6" id="_005cappendix"> +<title><literal>\appendix</literal></title> + +<indexterm role="fn"><primary>\appendix</primary></indexterm> +<indexterm role="cp"><primary>appendix</primary></indexterm> +<indexterm role="cp"><primary>appendices</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\appendix +</screen> +<para>This does not directly produce any output. But in a book or report it +declares that subsequent <literal>\chapter</literal> commands start an appendix. In +an article it does the same, for <literal>\section</literal> commands. It also +resets the <literal>chapter</literal> and <literal>section</literal> counters to 0 in a +book or report, and in an article resets the <literal>section</literal> and +<literal>subsection</literal> counters. +</para> +<para>In this book +</para> +<screen>\chapter{One} ... +\chapter{Two} ... + ... +\appendix +\chapter{Three} ... +\chapter{Four} ... +</screen> +<para>the first two will generate output numbered ‘<literal>Chapter 1</literal>’ and +‘<literal>Chapter 2</literal>’. After the <literal>\appendix</literal> the numbering will be +‘<literal>Appendix A</literal>’ and ‘<literal>Appendix B</literal>’. See <link linkend="Larger-book-template">Larger book template</link> +for another example. +</para> +<indexterm role="cp"><primary>package, <literal>appendix</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>appendix</literal> package</primary></indexterm> +<para>The <filename>appendix</filename> package adds the command +<literal>\appendixpage</literal> to put a separate ‘<literal>Appendices</literal>’ in the document +body before the first appendix, and the command <literal>\addappheadtotoc</literal> +to do the same in the table of contents. You can reset the name +‘<literal>Appendix</literal>’ with a command like +<literal>\renewcommand{\appendixname}{Specification}</literal>, as well as a +number of other features. See the documentation on CTAN. +</para> + +</sect1> + +<sect1 label="6.7" id="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter"> +<title><literal>\frontmatter</literal>, <literal>\mainmatter</literal>, <literal>\backmatter</literal></title> + +<indexterm role="fn"><primary>\frontmatter</primary></indexterm> +<indexterm role="cp"><primary>book, front matter</primary></indexterm> +<indexterm role="fn"><primary>\mainmatter</primary></indexterm> +<indexterm role="cp"><primary>book, main matter</primary></indexterm> +<indexterm role="fn"><primary>\backmatter</primary></indexterm> +<indexterm role="cp"><primary>book, back matter</primary></indexterm> +<indexterm role="cp"><primary>book, end matter</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\frontmatter +\mainmatter +\backmatter +</screen> +<para>Format a <literal>book</literal> class document differently according to which part +of the document is being produced. All three commands are optional. +</para> +<para>Traditionally, a book’s front matter contains such things as the title +page, an abstract, a table of contents, a preface, a list of notations, +a list of figures, and a list of tables. (Some of these front matter +pages, such as the title page, are traditionally not numbered.) The +back matter may contain such things as a glossary, notes, a +bibliography, and an index. +</para> +<para>The <literal>\frontmatter</literal> declaration makes the pages numbered in +lowercase roman, and makes chapters not numbered, although each +chapter’s title appears in the table of contents; if you use other +sectioning commands here, use the <literal>*</literal>-version (see <link linkend="Sectioning">Sectioning</link>). +The <literal>\mainmatter</literal> changes the behavior back to the expected +version, and resets the page number. The <literal>\backmatter</literal> leaves the +page numbering alone but switches the chapters back to being not +numbered. See <link linkend="Larger-book-template">Larger book template</link> for an example using the three. +</para> + +</sect1> +<sect1 label="6.8" id="_005c_0040startsection"> +<title><literal>\@startsection</literal></title> + +<indexterm role="fn"><primary>\@startsection</primary></indexterm> +<indexterm role="cp"><primary>section, redefining</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>} +</screen> +<para>Used to help redefine the behavior of commands that start sectioning +divisions such as <literal>\section</literal> or <literal>\subsection</literal>. +</para> +<para>Note that the <filename>titlesec</filename> package makes manipulation of sectioning +easier. Further, while most requirements for sectioning commands can be +satisfied with <literal>\@startsection</literal>, some cannot. For instance, in +the standard &latex; <literal>book</literal> and <literal>report</literal> classes the commands +<literal>\chapter</literal> and <literal>\report</literal> are not constructed in this way. To +make such a command you may want to use the <literal>\secdef</literal> command. +<!-- xx define, and make a cross reference to, secdef. --> +</para> +<para>Technically, <literal>\@startsection</literal> has the form +</para> +<screen>\@startsection{<replaceable>name</replaceable>} + {<replaceable>level</replaceable>} + {<replaceable>indent</replaceable>} + {<replaceable>beforeskip</replaceable>} + {<replaceable>afterskip</replaceable>} + {<replaceable>style</replaceable>}*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>so that issuing +</para> +<screen>\renewcommand{\section}{\@startsection{<replaceable>name</replaceable>} + {<replaceable>level</replaceable>} + {<replaceable>indent</replaceable>} + {<replaceable>beforeskip</replaceable>} + {<replaceable>afterskip</replaceable>} + {<replaceable>style</replaceable>}} +</screen> +<para>redefines <literal>\section</literal> to have the form +<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (here too, the +star <literal>*</literal> is optional). See <link linkend="Sectioning">Sectioning</link>. This implies that +when you write a command like <literal>\renewcommand{section}{...}</literal>, +the <literal>\@startsection{...}</literal> must come last in the definition. See +the examples below. +</para> +<variablelist> +<varlistentry><term><replaceable>name</replaceable> +</term><listitem><anchor id="startsection-name"/><anchor id="_005c_0040startsection_002fname"/><para>Name of the counter used to number the sectioning header. This counter +must be defined separately. Most commonly this is either +<literal>section</literal>, <literal>subsection</literal>, or <literal>paragraph</literal>. Although in +those cases the counter name is the same as the sectioning command +itself, you don’t have to use the same name. +</para> +<para>Then <literal>\the</literal><replaceable>name</replaceable> displays the title number and +<literal>\</literal><replaceable>name</replaceable><literal>mark</literal> is for the page headers. See the third +example below. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>level</replaceable> +</term><listitem><anchor id="startsection-level"/><anchor id="_005c_0040startsection_002flevel"/><para>An integer giving the depth of the sectioning command. +See <link linkend="Sectioning">Sectioning</link> for the list of standard level numbers. +</para> +<para>If <replaceable>level</replaceable> is less than or equal to the value of the counter +<literal>secnumdepth</literal> then titles for this sectioning command will be +numbered (see <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link>). For instance, if +<literal>secnumdepth</literal> is 1 in an <literal>article</literal> then the command +<literal>\section{Introduction}</literal> will produce output like “1 +Introduction” while <literal>\subsection{Discussion}</literal> will produce +output like “Discussion”, without the number prefix. +</para> +<para>If <replaceable>level</replaceable> is less than or equal to the value of the counter +<replaceable>tocdepth</replaceable> then the table of contents will have an entry for this +sectioning unit (see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>). For instance, in an +<literal>article</literal>, if <replaceable>tocdepth</replaceable> is 1 then the table of contents will +list sections but not subsections. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>indent</replaceable> +</term><listitem><anchor id="startsection-indent"/><anchor id="_005c_0040startsection_002findent"/><para>A length giving the indentation of all of the title lines with respect +to the left margin. To have the title flush with the margin use +<literal>0pt</literal>. A negative indentation such as <literal>-\parindent</literal> will move +the title into the left margin. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>beforeskip</replaceable> +</term><listitem><anchor id="startsection-beforeskip"/><anchor id="_005c_0040startsection_002fbeforeskip"/><para>The absolute value of this length is the amount of vertical space that +is inserted before this sectioning unit’s title. This space will be +discarded if the sectioning unit happens to start at the top of a fresh +page. If this number is negative then the first paragraph following the +header is not indented, if it is non-negative then the first paragraph +is indented. (Note that the negative of <literal>1pt plus 2pt minus 3pt</literal> +is <literal>-1pt plus -2pt minus -3pt</literal>.) +</para> +<para>For example, if <replaceable>beforeskip</replaceable> is <literal>-3.5ex plus -1ex minus -0.2ex</literal> +then to start the new sectioning unit, &latex; will add about 3.5 times +the height of a letter x in vertical space, and the first paragraph in +the section will not be indented. Using a rubber length, with +<literal>plus</literal> and <literal>minus</literal>, is good practice here since it gives +&latex; more flexibility in making up the page (see <link linkend="Lengths">Lengths</link>). +</para> +<para>The full accounting of the vertical space between the baseline of the +line prior to this sectioning unit’s header and the baseline of the +header is that it is the sum of the <literal>\parskip</literal> of the text font, +the <literal>\baselineskip</literal> of the title font, and the absolute value of +the <replaceable>beforeskip</replaceable>. This space is typically rubber so it may stretch +or shrink. (If the sectioning unit starts on a fresh page so that the +vertical space is discarded then the baseline of the header text will be +where &latex; would put the baseline of the first text line on that +page.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>afterskip</replaceable> +</term><listitem><anchor id="startsection-afterskip"/><anchor id="_005c_0040startsection_002fafterskip"/><para>This is a length. If <replaceable>afterskip</replaceable> is non-negative then this is the +vertical space inserted after the sectioning unit’s title header. If it +is negative then the title header becomes a run-in header, so that it +becomes part of the next paragraph. In this case the absolute value of +the length gives the horizontal space between the end of the title and +the beginning of the following paragraph. (Note that the negative of +<literal>1pt plus 2pt minus 3pt</literal> is <literal>-1pt plus -2pt minus -3pt</literal>.) +</para> +<para>As with <replaceable>beforeskip</replaceable>, using a rubber length, with <literal>plus</literal> and +<literal>minus</literal> components, is good practice here since it gives &latex; +more flexibility in putting together the page. +</para> +<para>If <literal>afterskip</literal> is non-negative then the full accounting of the +vertical space between the baseline of the sectioning unit’s header and +the baseline of the first line of the following paragraph is that it is +the sum of the <literal>\parskip</literal> of the title font, the +<literal>\baselineskip</literal> of the text font, and the value of <replaceable>after</replaceable>. +That space is typically rubber so it may stretch or shrink. (Note that +because the sign of <literal>afterskip</literal> changes the sectioning unit +header’s from standalone to run-in, you cannot use a negative +<literal>afterskip</literal> to cancel part of the <literal>\parskip</literal>.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>style</replaceable> +</term><listitem><anchor id="startsection-style"/><anchor id="_005c_0040startsection_002fstyle"/><para>Controls the styling of the title. See the examples below. Typical +commands to use here are <literal>\centering</literal>, <literal>\raggedright</literal>, +<literal>\normalfont</literal>, <literal>\hrule</literal>, or <literal>\newpage</literal>. The last command +in <replaceable>style</replaceable> may be one that takes one argument, such as +<literal>\MakeUppercase</literal> or <literal>\fbox</literal> that takes one argument. The +section title will be supplied as the argument to this command. For +instance, setting <replaceable>style</replaceable> to <literal>\bfseries\MakeUppercase</literal> would +produce titles that are bold and uppercase. +</para></listitem></varlistentry></variablelist> +<para>These are &latex;’s defaults for the first three sectioning units that +are defined with <literal>\@startsection</literal>, for the <filename>article</filename>, +<filename>book</filename>, and <filename>report</filename> classes. For section, the <replaceable>level</replaceable> is +1, the <replaceable>indent</replaceable> is 0pt, the <replaceable>beforeskip</replaceable> is <literal>-3.5ex +plus -1ex minus -0.2ex</literal>, the <replaceable>afterskip</replaceable> is <literal>2.3ex plus 0.2ex</literal>, +and the <replaceable>style</replaceable> is <literal>\normalfont\Large\bfseries</literal>. For +subsection, the <replaceable>level</replaceable> is 2, the <replaceable>indent</replaceable> is 0pt, the +<replaceable>beforeskip</replaceable> is <literal>-3.25ex plus -1ex minus -0.2ex</literal>, the +<replaceable>afterskip</replaceable> is <literal>1.5ex plus 0.2ex</literal>, and the <replaceable>style</replaceable> is +<literal>\normalfont\large\bfseries</literal>. For subsubsection, the <replaceable>level</replaceable> +is 3, the <replaceable>indent</replaceable> is 0pt, the <replaceable>beforeskip</replaceable> is +<literal>-3.25ex plus -1ex minus -0.2ex</literal>, the <replaceable>afterskip</replaceable> is +<literal>1.5ex plus 0.2ex</literal>, and the <replaceable>style</replaceable> is +<literal>\normalfont\normalsize\bfseries</literal>. +</para> +<para>Here are examples. They go either in a package or class file or in the +preamble of a &latex; document. If you put them in the preamble they +must go between a <literal>\makeatletter</literal> command and a +<literal>\makeatother</literal>. (Probably the error message <literal>You can't use +`\spacefactor' in vertical mode.</literal> means that you forgot this.) +See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter & \makeatother</link>. +</para> +<para>This will put section titles in large boldface type, centered. It says +<literal>\renewcommand</literal> because &latex;’s standard classes have already +defined a <literal>\section</literal>. For the same reason it does not define a +<literal>section</literal> counter, or the commands <literal>\thesection</literal> and +<literal>\l@section</literal>. +</para> +<screen>\renewcommand\section{% + \@startsection{section}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link> + {1}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link> + {0pt}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link> + {-3.5ex plus -1ex minus -.2ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link> + {2.3ex plus.2ex}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link> + {\centering\normalfont\Large\bfseries}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link> + } +</screen> +<para>This will put <literal>subsection</literal> titles in small caps type, inline with the paragraph. +</para> +<screen>\renewcommand\subsection{% + \@startsection{subsection}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link> + {2}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link> + {0em}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link> + {-1ex plus 0.1ex minus -0.05ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link> + {-1em plus 0.2em}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link> + {\scshape}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link> + } +</screen> +<para>The prior examples redefined existing sectional unit title commands. +This defines a new one, illustrating the needed counter and macros to +display that counter. +</para> +<!-- From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ --> +<screen>\setcounter{secnumdepth}{6}% show counters this far down +\newcounter{subsubparagraph}[subparagraph]% counter for numbering +\renewcommand{\thesubsubparagraph}% how to display + {\thesubparagraph.\@arabic\c@subsubparagraph}% numbering +\newcommand{\subsubparagraph}{\@startsection + {subsubparagraph}% + {6}% + {0em}% + {\baselineskip}% + {0.5\baselineskip}% + {\normalfont\normalsize}} +\newcommand*\l@subsubparagraph{\@dottedtocline{6}{10em}{5em}}% for toc +\newcommand{\subsubparagraphmark}[1]{}% for page headers +</screen> + +</sect1> +</chapter> +<chapter label="7" id="Cross-references"> +<title>Cross references</title> + +<indexterm role="cp"><primary>cross references</primary></indexterm> + +<indexterm role="cp"><primary>label</primary></indexterm> +<para>We often want something like ‘<literal>See Theorem~31</literal>’. But by-hand typing +the 31 is poor practice. Instead you should write a <firstterm>label</firstterm> such as +<literal>\label{eq:GreensThm}</literal> and then <firstterm>reference</firstterm> it, as with +<literal>See equation~\ref{eq:GreensThm}</literal>. &latex; will automatically +work out the number, put it into the output, and will change that number +later if needed. +</para> +<screen>We will see this with Theorem~\ref{th:GreensThm}. % forward reference +... +\begin{theorem} \label{th:GreensThm} + ... +\end{theorem} +... +See Theorem~\ref{th:GreensThm} on page~\pageref{th:GreensThm}. +</screen> +<para>&latex; tracks cross reference information in a file having the +extension <filename>.aux</filename> and with the same base name as the file containing +the <literal>\label</literal>. So if <literal>\label</literal> is in <filename>calculus.tex</filename> then +the information is in <filename>calculus.aux</filename>. &latex; puts the +information in that file every time it runs across a <literal>\label</literal>. +</para> +<indexterm role="cp"><primary>forward reference</primary></indexterm> +<indexterm role="cp"><primary>reference, forward</primary></indexterm> +<para>The behavior described in the prior paragraph results in a quirk that +happens when your document has a <firstterm>forward reference</firstterm>, a <literal>\ref</literal> +that appears before the associated <literal>\label</literal>. If this is the first +time that you are compiling the document then you will get ‘<literal>LaTeX +Warning: Label(s) may have changed. Rerun to get cross references right</literal>’ +and in the output the forward reference will appear as two question +marks ‘<literal>??</literal>’, in boldface. A similar thing happens if you +change some things so the references changes; you get the same warning +and the output contains the old reference information. In both cases, +resolve this by compiling the document a second time. +</para> +<indexterm role="cp"><primary>package, <literal>cleveref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>cleveref</literal> package</primary></indexterm> +<para>The <literal>cleveref</literal> package enhances &latex;’s +cross referencing features. You can arrange that if you enter +<literal>\begin{thm}\label{th:Nerode}...\end{thm}</literal> then +<literal>\cref{th:Nerode}</literal> will output ‘<literal>Theorem 3.21</literal>’, without you +having to enter the “Theorem.” +</para> + + +<sect1 label="7.1" id="_005clabel"> +<title><literal>\label</literal></title> + +<indexterm role="fn"><primary>\label</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\label{<replaceable>key</replaceable>} +</screen> +<para>Assign a reference number to <replaceable>key</replaceable>. In ordinary text +<literal>\label{<replaceable>key</replaceable>}</literal> assigns to <replaceable>key</replaceable> the number of the +current sectional unit. Inside an environment with numbering, such as a +<literal>table</literal> or <literal>theorem</literal> environment, <literal>\label{<replaceable>key</replaceable>}</literal> +assigns to <replaceable>key</replaceable> the number of that environment. Retrieve the +assigned number with the <literal>\ref{<replaceable>key</replaceable>}</literal> command +(see <link linkend="_005cref">\ref</link>). +</para> +<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>A common convention is to use labels consisting of a prefix and a suffix +separated by a colon or period. Thus, <literal>\label{fig:Post}</literal> is a +label for a figure with a portrait of Emil Post. This helps to avoid +accidentally creating two labels with the same name, and makes your +source more readable. Some commonly-used prefixes: +</para> +<variablelist><varlistentry><term><literal>ch</literal> +</term><listitem><para>for chapters +</para> +</listitem></varlistentry><varlistentry><term><literal>sec</literal> +</term><term><literal>subsec</literal> +</term><listitem><para>for lower-level sectioning commands +</para> +</listitem></varlistentry><varlistentry><term><literal>fig</literal> +</term><listitem><para>for figures +</para> +</listitem></varlistentry><varlistentry><term><literal>tab</literal> +</term><listitem><para>for tables +</para> +</listitem></varlistentry><varlistentry><term><literal>eq</literal> +</term><listitem><para>for equations +</para></listitem></varlistentry></variablelist> +<para>In the auxiliary file the reference information is kept as the text of +a command of the form +<literal>\newlabel{<replaceable>label</replaceable>}{{<replaceable>currentlabel</replaceable>}{<replaceable>pagenumber</replaceable>}}</literal>. +Here <replaceable>currentlabel</replaceable> is the current value of the macro +<literal>\@currentlabel</literal> that is usually updated whenever you call +<literal>\refstepcounter{<replaceable>counter</replaceable>}</literal>. +</para> +<para>Below, the key <literal>sec:test</literal> will get the number of the current +section and the key <literal>fig:test</literal> will get the number of the figure. +(Incidentally, put labels 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> + +</sect1> +<sect1 label="7.2" id="_005cpageref"> +<title><literal>\pageref</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> + +<para>Synopsis: +</para> +<screen>\pageref{<replaceable>key</replaceable>} +</screen> +<para>Produce the page number of the place in the text where the corresponding +<literal>\label</literal>{<replaceable>key</replaceable>} command appears. +</para> +<para>If there is no <literal>\label{<replaceable>key</replaceable>}</literal> then you get something like +‘<literal>LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.</literal>’ +</para> +<para>Below, the <literal>\label{eq:main}</literal> is used both for the formula number +and for the page number. (Note that the two references are forward +references so this document would need to be compiled twice to resolve +those.) +</para> +<screen>The main result is formula~\ref{eq:main} on page~\pageref{eq:main}. + ... +\begin{equation} \label{eq:main} + \mathbf{P}=\mathbf{NP} +\end{equation} +</screen> + +</sect1> +<sect1 label="7.3" id="_005cref"> +<title><literal>\ref</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> +<indexterm role="cp"><primary>equation number, cross referencing</primary></indexterm> +<indexterm role="cp"><primary>figure number, cross referencing</primary></indexterm> +<indexterm role="cp"><primary>footnote number, cross referencing</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\ref{<replaceable>key</replaceable>} +</screen> +<para>Produces the number of the sectional unit, +equation, footnote, figure, …, of the corresponding +<literal>\label</literal> command (see <link linkend="_005clabel">\label</link>). It does not produce any text, +such as the word ‘Section’ or ‘Figure’, just the bare number itself. +</para> +<para>If there is no <literal>\label{<replaceable>key</replaceable>}</literal> then you get something like +‘<literal>LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.</literal>’ +</para> +<para>In this example the <literal>\ref{popular}</literal> produces ‘<literal>2</literal>’. Note that +it is a forward reference since it comes before <literal>\label{popular}</literal> +so this document would have to be compiled twice. +</para> +<screen>The most widely-used format is item number~\ref{popular}. +\begin{enumerate} +\item Plain \TeX +\item \label{popular} \LaTeX +\item Con\TeX t +\end{enumerate} +</screen> +<indexterm role="cp"><primary>package, <literal>cleveref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>cleveref</literal> package</primary></indexterm> + +<para>The <filename>cleveref</filename> package includes text such as ‘<literal>Theorem</literal>’ in the +reference. See the documentation on CTAN. +</para> + +</sect1> +</chapter> +<chapter label="8" id="Environments"> +<title>Environments</title> + +<indexterm role="cp"><primary>environments</primary></indexterm> +<indexterm role="fn"><primary>\begin</primary></indexterm> +<indexterm role="fn"><primary>\end</primary></indexterm> + +<para>&latex; provides many environments for delimiting certain behavior. +An environment begins with <literal>\begin</literal> and ends with <literal>\end</literal>, +like this: +</para> +<screen>\begin{<replaceable>environment-name</replaceable>} + ... +\end{<replaceable>environment-name</replaceable>} +</screen> +<para>The <replaceable>environment-name</replaceable> at the beginning must exactly match that at +the end. For instance, the input +<literal>\begin{table*}...\end{table}</literal> will cause an error like: +‘<literal>! LaTeX Error: \begin{table*} on input line 5 ended by +\end{table}.</literal>’ +</para> +<indexterm role="cp"><primary>group, and environments</primary></indexterm> +<para>Environments are executed within a group. +</para> + + +<sect1 label="8.1" id="abstract"> +<title><literal>abstract</literal></title> + +<indexterm role="fn"><primary>environment, <literal>abstract</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>abstract</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>abstracts</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{abstract} +... +\end{abstract} +</screen> +<para>Produce an abstract, possibly of multiple paragraphs. This environment +is only defined in the <literal>article</literal> and <literal>report</literal> document classes +(see <link linkend="Document-classes">Document classes</link>). +</para> +<para>Using the example below in the <literal>article</literal> class produces a displayed +paragraph. Document class option <literal>titlepage</literal> causes the abstract +to be on a separate page (see <link linkend="Document-class-options">Document class options</link>); this is the +default only in the <literal>report</literal> class. +</para> +<screen>\begin{abstract} + We compare all known accounts of the proposal made by Porter Alexander + to Robert E Lee at the Appomattox Court House that the army continue + in a guerrilla war, which Lee refused. +\end{abstract} +</screen> +<para>The next example produces a one column abstract in a two column document (for +a more flexible solution, use the package <filename>abstract</filename>). +</para> +<!-- Adopted from http://www.tex.ac.uk/FAQ-onecolabs.html --> +<screen>\documentclass[twocolumn]{article} + ... +\begin{document} +\title{Babe Ruth as Cultural Progenitor: a Atavistic Approach} +\author{Smith \\ Jones \\ Robinson\thanks{Railroad tracking grant.}} +\twocolumn[ + \begin{@twocolumnfalse} + \maketitle + \begin{abstract} + Ruth was not just the Sultan of Swat, he was the entire swat + team. + \end{abstract} + \end{@twocolumnfalse} + ] +{ % by-hand insert a footnote at page bottom + \renewcommand{\thefootnote}{\fnsymbol{footnote}} + \footnotetext[1]{Thanks for all the fish.} +} +</screen> + +</sect1> +<sect1 label="8.2" id="array"> +<title><literal>array</literal></title> + +<indexterm role="fn"><primary>environment, <literal>array</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>array</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>arrays, math</primary></indexterm> + +<para>Synopsis: +</para> +<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>or: +</para> +<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>). Inside of each row the +column entries are separated by an ampersand, (<literal>&</literal>). Rows are +terminated with double-backslashes (see <link linkend="_005c_005c">\\</link>). +</para> +<para>This example shows a three by three array. +</para> +<screen>\begin{equation*} + \chi(x) = + \left| % vertical bar fence + \begin{array}{ccc} + x-a &-b &-c \\ + -d &x-e &-f \\ + -g &-h &x-i + \end{array} + \right| +\end{equation*} +</screen> +<para>The required argument <replaceable>cols</replaceable> describes the number of columns, their +alignment, and the formatting of the intercolumn regions. For instance, +<literal>\begin{array}{rcl}...\end{array}</literal> gives three columns: the +first flush right, the second centered, and the third flush left. 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 math mode, in +textstyle (see <link linkend="Modes">Modes</link>) 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 <literal>array</literal> 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>’ so that between two columns comes +10pt of space. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>To obtain arrays with braces the standard is to use the <filename>amsmath</filename> +package. It comes with environments <literal>pmatrix</literal> for an array +surrounded by parentheses <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> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>The next example uses the <filename>amsmath</filename> package. +</para> +<screen>\usepackage{amsmath} % in preamble + +\begin{equation} + \begin{vmatrix}{cc} % array with vert lines + a &b \\ + c &d + \end{vmatrix}=ad-bc +\end{equation} +</screen> +<indexterm role="cp"><primary>package, <literal>array (package)</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>array (package)</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>dcolumn</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>dcolumn</literal> package</primary></indexterm> + +<para>There are many packages concerning arrays. The <filename>array</filename> package has +many useful extensions, including more column types. The <filename>dcolumn</filename> +package adds a column type to center on a decimal point. For both see +the documentation on CTAN. +</para> + +</sect1> +<sect1 label="8.3" id="center"> +<title><literal>center</literal></title> + +<indexterm role="fn"><primary>environment, <literal>center</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>center</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>centering text, environment for</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{center} + <replaceable>line1</replaceable> \\ + <replaceable>line2</replaceable> \\ + ... +\end{center} +</screen> +<para>Create a new paragraph consisting of a sequence of lines that are +centered within the left and right margins. Use +double-backslash, <literal>\\</literal>, to get a line break (see <link linkend="_005c_005c">\\</link>). +<indexterm role="fn"><primary>\\ (for <literal>center</literal>)</primary></indexterm> +If some text is too long to fit on a line then &latex; will insert line +breaks that avoid hyphenation and avoid stretching or shrinking any +interword space. +</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>This example produces three centered lines. There is extra vertical +space between the last two lines. +</para> +<screen>\begin{center} + A Thesis Submitted in Partial Fufillment \\ + of the Requirements of \\[0.5ex] + the School of Environmental Engineering +\end{center} +</screen> +<para>In this example, depending on the page’s line width, &latex; may choose +a line break for the part before the double backslash. If so, it will +center each of the two lines and if not it will center the single line. +Then &latex; 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. If present it +doesn’t add any vertical space. +</para> +<para>In a two-column document the text is centered in a column, not in the +entire page. +</para> + + +<sect2 label="8.3.1" id="_005ccentering"> +<title><literal>\centering</literal></title> + +<indexterm role="fn"><primary>\centering</primary></indexterm> +<indexterm role="cp"><primary>centering text, declaration for</primary></indexterm> + + +<para>Synopsis: +</para> +<screen>{\centering ... } +</screen> +<para>or +</para> +<screen>\begin{group} + \centering ... +\end{group} +</screen> +<para>Center the material in its scope. It is most often used inside an +environment such as <literal>figure</literal>, or in a <literal>parbox</literal>. +</para> +<para>This example’s <literal>\centering</literal> declaration 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 this <literal>\centering</literal> ends with the <literal>\end{figure}</literal>. +</para> +<para>Unlike the <literal>center</literal> environment, the <literal>\centering</literal> command does +not add vertical space above and below the text. That’s its advantage +in the above example; there is not an excess of space. +</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. +</para> + +</sect2> +</sect1> +<sect1 label="8.4" id="description"> +<title><literal>description</literal></title> + +<indexterm role="fn"><primary>environment, <literal>description</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>description</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>labelled lists, creating</primary></indexterm> +<indexterm role="cp"><primary>description lists, creating</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{description} + \item[<replaceable>label of first item</replaceable>] <replaceable>text of first item</replaceable> + \item[<replaceable>label of second item</replaceable>] <replaceable>text of second item</replaceable> + ... +\end{description} +</screen> +<para>Environment to make a list of labeled items. Each item’s <replaceable>label</replaceable> is +typeset in bold and is flush left, so that long labels continue into the +first line of the item text. There must be at least one item; having +none causes the &latex; error ‘<literal>Something's wrong--perhaps a +missing \item</literal>’. +</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> +<para>The labels ‘<literal>lama</literal>’ and ‘<literal>llama</literal>’ are output in boldface, with the +left edge on the left margin. +</para> +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). Use the +optional labels, as in <literal>\item[Main point]</literal>, because there is +no sensible default. Following the <literal>\item</literal> is optional text, which +may contain multiple paragraphs. +</para> +<indexterm role="cp"><primary>bold typewriter, avoiding</primary></indexterm> +<indexterm role="cp"><primary>typewriter labels in lists</primary></indexterm> +<para>Since the labels are in bold style, if the label text calls for a font +change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will come +out bold. For instance, if the label text calls for typewriter with +<literal>\item[\texttt{label text}]</literal> then it will appear in bold +typewriter, if that is available. The simplest way around this, in this +example to get non-bold typewriter, is to use declarative style: +<literal>\item[{\tt label text}]</literal>. Similarly, get the standard roman +font with <literal>\item[{\rm label text}]</literal>. +</para> +<para>For other major &latex; labelled list environments, see <link linkend="itemize">itemize</link> +and <link linkend="enumerate">enumerate</link>. Unlike those environments, nesting +<literal>description</literal> environments does not change the default label; it is +boldface and flush left at all levels. +</para> +<para>For information about list layout parameters, including the default +values, and for information about customizing list layout, see +<link linkend="list">list</link>. The package <filename>enumitem</filename> is useful for customizing +lists. +</para> +<para>This example changes the description labels to small caps. +</para> +<screen>\renewcommand{\descriptionlabel}[1]{% + {\hspace{\labelsep}\textsc{#1}}} +</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>environment, <literal>displaymath</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> + + +<para>Synopsis: +</para> +<screen>\begin{displaymath} + <replaceable>mathematical text</replaceable> +\end{displaymath} +</screen> +<para>Environment to typeset the math text on its own line, in display style +and centered. To make the text be flush-left use the global option +<literal>fleqn</literal>; see <link linkend="Document-class-options">Document class options</link>. +</para> +<para>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>&latex; will not break the <replaceable>math text</replaceable> across lines. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>Note that the <filename>amsmath</filename> package has significantly more extensive +displayed equation facilities. For example, there are a number of +ways in that package for having math text broken across lines. +</para> +<para>The construct <literal>\[<replaceable>math text</replaceable>\]</literal> is essentially a synonym for +<literal>\begin{displaymath}<replaceable>math text</replaceable>\end{displaymath}</literal> but the +latter is easier to work with in the source file; for instance, +searching for a square bracket may get false positives but the word +<literal>displaymath</literal> will likely be unique. (The construct +<literal>$$<replaceable>math text</replaceable>$$</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> +<sect1 label="8.6" id="document"> +<title><literal>document</literal></title> + +<indexterm role="fn"><primary>environment, <literal>document</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>document</literal> environment</primary></indexterm> + + +<para>The <literal>document</literal> environment encloses the entire body of a document. +It is required in every &latex; document. See <link linkend="Starting-and-ending">Starting and ending</link>. +</para> + + +<sect2 label="8.6.1" id="_005cAtBeginDocument"> +<title><literal>\AtBeginDocument</literal></title> + +<indexterm role="fn"><primary>\AtBeginDocument</primary></indexterm> +<indexterm role="cp"><primary>beginning of document hook</primary></indexterm> + +<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> + +</sect2> +<sect2 label="8.6.2" id="_005cAtEndDocument"> +<title><literal>\AtEndDocument</literal></title> + +<indexterm role="fn"><primary>\AtEndDocument</primary></indexterm> +<indexterm role="cp"><primary>end of document hook</primary></indexterm> + +<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> + +</sect2> +</sect1> +<sect1 label="8.7" id="enumerate"> +<title><literal>enumerate</literal></title> + +<indexterm role="fn"><primary>environment, <literal>enumerate</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>enumerate</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>lists of items, numbered</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{enumerate} + \item[<replaceable>optional label of first item</replaceable>] <replaceable>text of first item</replaceable> + \item[<replaceable>optional label of second item</replaceable>] <replaceable>text of second item</replaceable> + ... +\end{enumerate} +</screen> +<para>Environment to produce a numbered list of items. The format of the +label numbering depends on the nesting level of this environment; see +below. The default top-level numbering is ‘<literal>1.</literal>’, ‘<literal>2.</literal>’, +etc. Each <literal>enumerate</literal> list environment must have at least one item; +having none causes the &latex; error ‘<literal>Something's wrong--perhaps a +missing \item</literal>’. +</para> +<para>This example gives the first two finishers in the 1908 Olympic marathon. +As a top-level list the labels would come out as ‘<literal>1.</literal>’ and +‘<literal>2.</literal>’. +</para> +<screen>\begin{enumerate} + \item Johnny Hayes (USA) + \item Charles Hefferon (RSA) +\end{enumerate} +</screen> +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you +give <literal>\item</literal> an optional argument by following it with square +brackets, as in <literal>\item[Interstitial label]</literal>, then the next item +will continue the interrupted sequence (see <link linkend="_005citem">\item</link>). That is, you +will get labels like ‘<literal>1.</literal>’, then ‘<literal>Interstitial label</literal>’, then +‘<literal>2.</literal>’. Following the <literal>\item</literal> is optional text, which may +contain multiple paragraphs. +</para> +<para>Enumerations may be nested within other <literal>enumerate</literal> environments, +or within any paragraph-making environment such as <literal>itemize</literal> +(see <link linkend="itemize">itemize</link>), up to four levels deep. This gives &latex;’s +default for the format at each nesting level, where 1 is the top level, +the outermost level. +</para> +<orderedlist numeration="arabic"><listitem><para>arabic number followed by a period: ‘<literal>1.</literal>’, ‘<literal>2.</literal>’, … +</para></listitem><listitem><para>lowercase letter inside parentheses: ‘<literal>(a)</literal>’, ‘<literal>(b)</literal>’ … +</para></listitem><listitem><para>lowercase roman numeral followed by a period: ‘<literal>i.</literal>’, ‘<literal>ii.</literal>’, … +</para></listitem><listitem><para>uppercase 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> +<anchor id="enumerate-enumi"/><anchor id="enumerate-enumii"/><anchor id="enumerate-enumiii"/><anchor id="enumerate-enumiv"/><para>The <literal>enumerate</literal> environment uses the counters <literal>\enumi</literal> through +<literal>\enumiv</literal> (see <link linkend="Counters">Counters</link>). +</para> +<para>For other major &latex; labeled list environments, see +<link linkend="description">description</link> and <link linkend="itemize">itemize</link>. For information about list layout +parameters, including the default values, and for information about +customizing list layout, see <link linkend="list">list</link>. The package <filename>enumitem</filename> is +useful for customizing lists. +</para> +<indexterm role="fn"><primary>\labelenumi</primary></indexterm> +<indexterm role="fn"><primary>\labelenumii</primary></indexterm> +<indexterm role="fn"><primary>\labelenumiii</primary></indexterm> +<indexterm role="fn"><primary>\labelenumiv</primary></indexterm> +<anchor id="enumerate-labelenumi"/><anchor id="enumerate-labelenumii"/><anchor id="enumerate-labelenumiii"/><anchor id="enumerate-labelenumiv"/><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}{\textbf{\Alph{enumi}}} +\begin{enumerate} + \item Shows as boldface A + \item Shows as boldface B +\end{enumerate} +</screen> +<para>For a list of counter-labeling commands see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic +\roman \Roman \fnsymbol</link>. +</para> + +</sect1> +<sect1 label="8.8" id="eqnarray"> +<title><literal>eqnarray</literal></title> + +<indexterm role="fn"><primary>environment, <literal>eqnarray</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>eqnarray</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>equations, aligning</primary></indexterm> +<indexterm role="cp"><primary>aligning equations</primary></indexterm> + +<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>The <literal>eqnarray</literal> environment is obsolete. It has infelicities, +including spacing that is inconsistent with other mathematics elements. +(See “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. We include a description only for completeness and for +working with old documents. +</para> +<para>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>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> +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>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"> +<title><literal>equation</literal></title> + +<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>equations, environment for</primary></indexterm> +<indexterm role="cp"><primary>formulas, environment for</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{equation} + <replaceable>mathematical text</replaceable> +\end{equation} +</screen> +<para>The same as a <literal>displaymath</literal> environment (see <link linkend="displaymath">displaymath</link>) +except that &latex; puts an equation number flush to the right margin. +The equation number is generated using the <literal>equation</literal> counter. +</para> +<para>You should have no blank lines between <literal>\begin{equation}</literal> and +<literal>\begin{equation}</literal>, or &latex; will tell you that there is a +missing dollar sign. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>The package <filename>amsmath</filename> package has extensive displayed equation +facilities. New documents should include this package. +</para> + +</sect1> +<sect1 label="8.10" id="figure"> +<title><literal>figure</literal></title> + +<indexterm role="fn"><primary>environment, <literal>figure</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>figure</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>inserting figures</primary></indexterm> +<indexterm role="cp"><primary>figures, inserting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{figure}[<replaceable>placement</replaceable>] + <replaceable>figure body</replaceable> + \caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} % optional + \label{<replaceable>label}</replaceable> % optional +\end{figure} +</screen> +<para>or: +</para> +<screen>\begin{figure*}[<replaceable>placement</replaceable>] + <replaceable>figure body</replaceable> + \caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} % optional + \label{<replaceable>label}</replaceable> % optional +\end{figure*} +</screen> +<para>Figures are for material that is not part of the normal text. An +example is material that you cannot have split between two pages, such +as a graphic. Because of this, &latex; does not typeset figures in +sequence with normal text but instead “floats” them to a convenient +place, such as the top of a following page (see <link linkend="Floats">Floats</link>). +</para> +<para>The <replaceable>figure body</replaceable> can consist of imported graphics +(see <link linkend="Graphics">Graphics</link>), or text, &latex; commands, etc. It is typeset in a +<literal>parbox</literal> of width <literal>\textwidth</literal>. +</para> +<para>The possible values of <replaceable>placement</replaceable> are <literal>h</literal> for ‘<literal>here</literal>’, +<literal>t</literal> for ‘<literal>top</literal>’, <literal>b</literal> for ‘<literal>bottom</literal>’, and <literal>p</literal> for +‘<literal>on a separate page of floats</literal>’. For the effect of these options on +the float placement algorithm, see <link linkend="Floats">Floats</link>. +</para> +<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 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 +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="Table-of-contents-etc_002e">Table of +contents etc.</link>). +</para> +<para>This example makes a figure out of a graphic. &latex; will place that +graphic and its caption at the top of a page or, if it is pushed to the +end of the document, on a page of floats. +</para> +<screen>\usepackage{graphicx} % in preamble + ... +\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>: Write an external file</title> + +<indexterm role="fn"><primary>environment, <literal>filecontents</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>filecontents</literal> environment</primary></indexterm> + +<indexterm role="fn"><primary>environment, <literal>filecontents*</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>filecontents*</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>external files, writing</primary></indexterm> +<indexterm role="cp"><primary>writing external files</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{filecontents}{<replaceable>filename</replaceable>} + <replaceable>text</replaceable> +\end{filecontents} +</screen> +<para>or +</para> +<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> +<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> +<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> +<para>For example, this document +</para> +<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>environment, <literal>flushleft</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>flushleft</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>left-justifying text, environment for</primary></indexterm> +<indexterm role="cp"><primary>ragged right text, environment for</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{flushleft} + <replaceable>line1</replaceable> \\ + <replaceable>line2</replaceable> \\ + ... +\end{flushleft} +</screen> +<indexterm role="fn"><primary>\\ for <literal>flushleft</literal></primary></indexterm> +<para>An environment that creates a paragraph whose lines are flush to the +left-hand margin, and ragged right. If you have lines that are too long +then &latex; will linebreak them in a way that avoids hyphenation and +stretching or shrinking spaces. To force a new line use a double +backslash, <literal>\\</literal>. For the declaration form +see <link linkend="_005craggedright">\raggedright</link>. +</para> +<para>This creates a box of text that is at most 3 inches wide, with the text +flush left and ragged right. +</para> +<screen>\noindent\begin{minipage}{3in} +\begin{flushleft} + A long sentence that will be broken by \LaTeX{} + at a convenient spot. \\ + And, a fresh line forced by the double backslash. +\end{flushleft} +\end{minipage} +</screen> + + + +<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> +<indexterm role="cp"><primary>justification, ragged right</primary></indexterm> + +<para>Synopses: +</para> +<screen>{\raggedright ... } +</screen> +<para>or +</para> +<screen>\begin{<replaceable>environment</replaceable>} \raggedright + ... +\end{<replaceable>environment</replaceable>} +</screen> +<para>A declaration which causes lines to be flush to the left margin and +ragged right. It can be used inside an environment such as <literal>quote</literal> +or in a <literal>parbox</literal>. For the environment form +see <link linkend="flushleft">flushleft</link>. +</para> +<para>Unlike the <literal>flushleft</literal> environment, the <literal>\raggedright</literal> +command does not start a new paragraph; it only 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 that ends the paragraph unit. +</para> +<para>Here <literal>\raggedright</literal> in each second column keeps &latex; from doing +very awkward typesetting to fit the text into the narrow column. Note +that <literal>\raggedright</literal> is inside the curly braces <literal>{...}</literal> to +delimit its effect. +</para> +<screen>\begin{tabular}{rp{2in}} + Team alpha &{\raggedright This team does all the real work.} \\ + Team beta &{\raggedright This team ensures that the water + cooler is never empty.} \\ +\end{tabular} +</screen> + +</sect2> +</sect1> +<sect1 label="8.13" id="flushright"> +<title><literal>flushright</literal></title> + +<indexterm role="fn"><primary>environment, <literal>flushright</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>flushright</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>ragged left text, environment for</primary></indexterm> +<indexterm role="cp"><primary>right-justifying text, environment for</primary></indexterm> + +<screen>\begin{flushright} + <replaceable>line1</replaceable> \\ + <replaceable>line2</replaceable> \\ + ... +\end{flushright} +</screen> +<indexterm role="fn"><primary>\\ (for <literal>flushright</literal>)</primary></indexterm> +<para>An environment that creates a paragraph whose lines are flush to the +right-hand margin and ragged left. If you have lines that are too long +to fit the margins then &latex; will linebreak them in a way that +avoids hyphenation and stretching or shrinking spaces. To force a new +line use a double backslash, <literal>\\</literal>. For the declaration form +see <link linkend="_005craggedleft">\raggedleft</link>. +</para> +<para>For an example related to this environment, see <link linkend="flushleft">flushleft</link>. +</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> +<indexterm role="cp"><primary>right-justifying text</primary></indexterm> + +<para>Synopses: +</para> +<screen>{\raggedleft ... } +</screen> +<para>or +</para> +<screen>\begin{<replaceable>environment</replaceable>} \raggedleft + ... +\end{<replaceable>environment</replaceable>} +</screen> +<para>A declaration which causes lines to be flush to the right margin and +ragged left. It can be used inside an environment such as <literal>quote</literal> +or in a <literal>parbox</literal>. For the environment form +see <link linkend="flushright">flushright</link>. +</para> +<para>Unlike the <literal>flushright</literal> environment, the <literal>\raggedleft</literal> +command does not start a new paragraph; it only changes how &latex; +formats paragraph units. To affect a paragraph unit’s format, the +scope of the declaration must contain the blank line or <literal>\end</literal> +command that ends the paragraph unit. +</para> +<para>For an example related to this environment, see <link linkend="_005craggedright">\raggedright</link>. +</para> + +</sect2> +</sect1> +<sect1 label="8.14" id="itemize"> +<title><literal>itemize</literal></title> + +<indexterm role="fn"><primary>environment, <literal>itemize</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>itemize</literal> environment</primary></indexterm> + +<indexterm role="fn"><primary>\item</primary></indexterm> +<indexterm role="cp"><primary>lists of items</primary></indexterm> +<indexterm role="cp"><primary>unordered lists</primary></indexterm> +<indexterm role="cp"><primary>bulleted lists</primary></indexterm> +<indexterm role="cp"><primary>bullet lists</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{itemize} + \item[<replaceable>optional label of first item</replaceable>] <replaceable>text of first item</replaceable> + \item[<replaceable>optional label of second item</replaceable>] <replaceable>text of second item</replaceable> + ... +\end{itemize} +</screen> +<para>Produce a list that is unordered, sometimes called a bullet list. The +environment must have at least one <literal>\item</literal>; having none causes the +&latex; error ‘<literal>Something's wrong--perhaps a missing \item</literal>’. +</para> +<para>This gives a two-item list. +</para> +<screen>\begin{itemize} + \item Pencil and watercolor sketch by Cassandra + \item Rice portrait +\end{itemize} +</screen> +<para>As a top-level list each label would come out as a bullet, •. +The format of the labeling depends on the nesting level; see below. +</para> +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you +give <literal>\item</literal> an optional argument by following it with square +brackets, as in <literal>\item[Optional label]</literal>, then by default it will +appear in bold and be flush right, so it could extend into the left +margin. For labels that are flush left see the <link linkend="description">description</link> +environment. Following the <literal>\item</literal> is optional text, which may +contain multiple paragraphs. +</para> +<indexterm role="fn"><primary>\labelitemi</primary></indexterm> +<indexterm role="fn"><primary>\labelitemii</primary></indexterm> +<indexterm role="fn"><primary>\labelitemiii</primary></indexterm> +<indexterm role="fn"><primary>\labelitemiv</primary></indexterm> +<anchor id="itemize-labelitemi"/><anchor id="itemize-labelitemii"/><anchor id="itemize-labelitemiii"/><anchor id="itemize-labelitemiv"/><para>Itemized lists can be nested within one another, up to four levels deep. +They can also be nested within other paragraph-making environments, such +as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). The <literal>itemize</literal> environment +uses the commands <literal>\labelitemi</literal> through <literal>\labelitemiv</literal> to +produce the default label (this also uses the convention of lowercase +roman numerals at the end of the command names that signify the nesting +level). These are the default marks at each level. +</para> +<orderedlist numeration="arabic"><listitem><para>• (bullet, from <literal>\textbullet</literal>) +</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash, from <literal>\normalfont\bfseries\textendash</literal>) +</para></listitem><listitem><para>* (asterisk, from <literal>\textasteriskcentered</literal>) +</para></listitem><listitem><para>. (centered dot, rendered here as a period, from <literal>\textperiodcentered</literal>) +</para></listitem></orderedlist> +<para>Change the labels with <literal>\renewcommand</literal>. For instance, this makes +the first level use diamonds. +</para> +<screen>\renewcommand{\labelitemi}{$\diamond$} +</screen> +<indexterm role="fn"><primary>\leftmargin</primary></indexterm> +<indexterm role="fn"><primary>\leftmargini</primary></indexterm> +<indexterm role="fn"><primary>\leftmarginii</primary></indexterm> +<indexterm role="fn"><primary>\leftmarginiii</primary></indexterm> +<indexterm role="fn"><primary>\leftmarginiv</primary></indexterm> +<indexterm role="fn"><primary>\leftmarginv</primary></indexterm> +<indexterm role="fn"><primary>\leftmarginvi</primary></indexterm> +<anchor id="itemize-leftmargin"/><anchor id="itemize-leftmargini"/><anchor id="itemize-leftmarginii"/><anchor id="itemize-leftmarginiii"/><anchor id="itemize-leftmarginiv"/><anchor id="itemize-leftmarginv"/><anchor id="itemize-leftmarginvi"/><para>The distance between the left margin of the enclosing environment and +the left margin of the <literal>itemize</literal> list is determined by the +parameters <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal>. (Note the +convention of using lowercase roman numerals a the end of the command +name to denote the nesting level.) The defaults are: <literal>2.5em</literal> in +level 1 (<literal>2em</literal> in two-column mode), <literal>2.2em</literal> in level 2, +<literal>1.87em</literal> in level 3, and <literal>1.7em</literal> in level 4, with smaller +values for more deeply nested levels. +</para> +<para>For other major &latex; labeled list environments, see +<link linkend="description">description</link> and <link linkend="enumerate">enumerate</link>. For information about list +layout parameters, including the default values, and for information +about customizing list layout, see <link linkend="list">list</link>. The package +<filename>enumitem</filename> is useful for customizing lists. +</para> +<para>This example greatly reduces the margin space for outermost itemized +lists. +</para> +<screen>\setlength{\leftmargini}{1.25em} % default 2.5em +</screen> +<indexterm role="fn"><primary>\parskip example</primary></indexterm> +<para>Especially for lists with short items, it may be desirable to elide +space between items. Here is an example defining an <literal>itemize*</literal> +environment with no extra spacing between items, or between paragraphs +within a single item (<literal>\parskip</literal> is not list-specific, +see <link linkend="_005cparindent-_0026-_005cparskip">\parindent & \parskip</link>): +</para> +<screen>\newenvironment{itemize*}% + {\begin{itemize}% + \setlength{\itemsep}{0pt}% + \setlength{\parsep}{0pt}}% + \setlength{\parskip}{0pt}}% + {\end{itemize}} +</screen> + +</sect1> +<sect1 label="8.15" id="letter"> +<title><literal>letter</literal> environment: writing letters</title> + +<indexterm role="fn"><primary>environment, <literal>letter</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>letter</literal> environment</primary></indexterm> + + +<para>This environment is used for creating letters. See <link linkend="Letters">Letters</link>. +</para> + +</sect1> +<sect1 label="8.16" id="list"> +<title><literal>list</literal></title> + +<indexterm role="fn"><primary>environment, <literal>list</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>list</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>lists of items, generic</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{list}{<replaceable>labeling</replaceable>}{<replaceable>spacing</replaceable>} + \item[<replaceable>optional label of first item</replaceable>] <replaceable>text of first item</replaceable> + \item[<replaceable>optional label of second item</replaceable>] <replaceable>text of second item</replaceable> + ... +\end{list} +</screen> +<para>An environment for constructing lists. +</para> +<para>Note that this environment does not typically appear in the document +body. Most lists created by &latex; authors are the ones that come +standard: the <literal>description</literal>, <literal>enumerate</literal>, and <literal>itemize</literal> +environments (see <link linkend="description">description</link>, <link linkend="enumerate">enumerate</link>, and <link linkend="itemize">itemize</link>). +</para> +<para>Instead, the <literal>list</literal> environment is most often used in macros. For +example, many standard &latex; environments that do not immediately +appear to be lists are in fact constructed using <literal>list</literal>, including +<literal>quotation</literal>, <literal>quote</literal>, and <literal>center</literal> (see <link linkend="quotation-_0026-quote">quotation & +quote</link>, see <link linkend="center">center</link>). +</para> +<para>This uses the <literal>list</literal> environment to define a new custom +environment. +</para> +<screen>\newcounter{namedlistcounter} % number the items +\newenvironment{named} + {\begin{list} + {Item~\Roman{namedlistcounter}.} % labeling + {\usecounter{namedlistcounter} % set counter + \setlength{\leftmargin}{3.5em}} % set spacing + } + {\end{list}} + +\begin{named} + \item Shows as ``Item~I.'' + \item[Special label.] Shows as ``Special label.'' + \item Shows as ``Item~II.'' +\end{named} +</screen> +<para>The mandatory first argument <replaceable>labeling</replaceable> specifies the default +labeling of list items. It can contain text and &latex; commands, as +above where it contains both ‘<literal>Item</literal>’ and ‘<literal>\Roman{...}</literal>’. +&latex; forms the label by putting the <replaceable>labeling</replaceable> argument in a box +of width <literal>\labelwidth</literal>. If the label is wider than that, the +additional material extends to the right. When making an instance of a +list you can override the default labeling by giving <literal>\item</literal> an +optional argument by including square braces and the text, as in the +above <literal>\item[Special label.]</literal>; see <link linkend="_005citem">\item</link>. +</para> +<para>The mandatory second argument <replaceable>spacing</replaceable> has a list of commands. +This list can be empty. A command that can go in here is +<literal>\usecounter{<replaceable>countername</replaceable>}</literal> (see <link linkend="_005cusecounter">\usecounter</link>). Use this +to tell &latex; to number the items using the given counter. The +counter will be reset to zero each time &latex; enters the environment, +and the counter is incremented by one each time &latex; encounters an +<literal>\item</literal> that does not have an optional argument. +</para> +<indexterm role="fn"><primary>\makelabel</primary></indexterm> +<anchor id="list-makelabel"/><para>Another command that can go in <replaceable>spacing</replaceable> is +<literal>\makelabel</literal>, which constructs the label box. By default it puts +the contents flush right. Its only argument is the label, which it +typesets in LR mode (see <link linkend="Modes">Modes</link>). One example of changing its +definition is that to the above <literal>named</literal> example, before the +definition of the environment add +<literal>\newcommand{\namedmakelabel}[1]{\textsc{#1}}</literal>, and between +the <literal>\setlength</literal> command and the parenthesis that closes the +<replaceable>spacing</replaceable> argument also add <literal>\let\makelabel\namedmakelabel</literal>. +Then the items will be typeset in small caps. Similarly, changing the +second code line to <literal>\let\makelabel\fbox</literal> puts the labels inside a +framed box. Another example of the <literal>\makelabel</literal> command is below, +in the definition of the <literal>redlabel</literal> environment. +</para> +<para>Also often in <replaceable>spacing</replaceable> are commands to redefine the spacing for the +list. Below are the spacing parameters with their default values. +(Default values for derived environments such as <literal>itemize</literal> can be +different than the values shown here.) See also the figure that follows +the list. Each is a length (see <link linkend="Lengths">Lengths</link>). The vertical spaces are +normally rubber lengths, with <literal>plus</literal> and <literal>minus</literal> components, +to give &tex; flexibility in setting the page. Change each with a +command such as <literal>\setlength{itemsep}{2pt plus1pt minus1pt}</literal>. +For some effects these lengths should be zero or negative. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal> +</term><listitem><anchor id="list-itemindent"/><para>Extra horizontal space indentation, beyond <literal>leftmargin</literal>, of the +first line each item. Its default value is <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\itemsep</primary></indexterm><literal>\itemsep</literal> +</term><listitem><anchor id="list-itemsep"/><para>Vertical space between items, beyond the <literal>\parsep</literal>. The defaults +for the first three levels in &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, +and ‘<literal>report</literal>’ classes at 10 point size are: <literal>4pt plus2pt +minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>), and +<literal>\topsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>). The defaults at +11 point are: <literal>4.5pt plus2pt minus1pt</literal>, <literal>\parsep</literal> (that is, +<literal>2pt plus1pt minus1pt</literal>), and <literal>topsep</literal> (that is, <literal>2pt +plus1pt minus1pt</literal>). The defaults at 12 point are: <literal>5pt plus2.5pt +minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>), and +<literal>\topsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelsep</primary></indexterm><literal>\labelsep</literal> +</term><listitem><anchor id="list-labelsep"/><para>Horizontal space between the label and text of an item. +The default for &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, +and ‘<literal>report</literal>’ classes is <literal>0.5em</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelwidth</primary></indexterm><literal>\labelwidth</literal> +</term><listitem><anchor id="list-labelwidth"/><para>Horizontal width. The box containing the label is nominally this wide. +If <literal>\makelabel</literal> returns text that is wider than this then the first +line of the item will be indented to make room for this extra material. +If <literal>\makelabel</literal> returns text of width less than or equal to +<literal>\labelwidth</literal> then &latex;’s default is that the label is typeset +flush right in a box of this width. +</para> +<para>The left edge of the label box is +<literal>\leftmargin</literal>+<literal>\itemindent</literal>-<literal>\labelsep</literal>-<literal>\labelwidth</literal> +from the left margin of the enclosing environment. +</para> +<para>The default for &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and +‘<literal>report</literal>’ classes at the top level is +<literal>\leftmargini</literal>-<literal>\labelsep</literal>, (which is <literal>2em</literal> in one column +mode and <literal>1.5em</literal> in two column mode). At the second level it is +<literal>\leftmarginii</literal>-<literal>\labelsep</literal>, and at the third level it is +<literal>\leftmarginiii</literal>-<literal>\labelsep</literal>. These definitions make the +label’s left edge coincide with the left margin of the enclosing +environment. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftmargin</primary></indexterm><literal>\leftmargin</literal> +</term><listitem><anchor id="list-leftmargin"/><para>Horizontal space between the left margin of the enclosing environment +(or the left margin of the page if this is a top-level list), and the +left margin of this list. It must be non-negative. +</para> +<para>In the standard &latex; document classes, a top-level list has this set +to the value of <literal>\leftmargini</literal>, while a list that is nested inside +a top-level list has this margin set to <literal>\leftmarginii</literal>. More +deeply nested lists get the values of <literal>\leftmarginiii</literal> through +<literal>\leftmarginvi</literal>. (Nesting greater than level five generates the +error message ‘<literal>Too deeply nested</literal>’.) +</para> +<para>The defaults for the first three levels in &latex;’s ‘<literal>article</literal>’, +‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes are: <literal>\leftmargini</literal> is +<literal>2.5em</literal> (in two column mode, <literal>2em</literal>), <literal>\leftmarginii</literal> is +<literal>2.2em</literal>, and <literal>\leftmarginiii</literal> is <literal>1.87em</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\listparindent</primary></indexterm><literal>\listparindent</literal> +</term><listitem><anchor id="list-listparindent"/><para>Horizontal space of additional line indentation, beyond +<literal>\leftmargin</literal>, for second and subsequent paragraphs within a list +item. A negative value makes this an “outdent”. Its default value +is <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal> +</term><listitem><anchor id="list-parsep"/><para>Vertical space between paragraphs within an item. In the ‘<literal>book</literal>’ +and ‘<literal>article</literal>’ classes The defaults for the first three levels in +&latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes at 10 +point size are: <literal>4pt plus2pt minus1pt</literal>, <literal>2pt plus1pt +minus1pt</literal>, and <literal>0pt</literal>. The defaults at 11 point size are: +<literal>4.5pt plus2pt minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and +<literal>0pt</literal>. The defaults at 12 point size are: <literal>5pt plus2.5pt +minus1pt</literal>, <literal>2.5pt plus1pt minus1pt</literal>, and <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal> +</term><listitem><anchor id="list-partopsep"/><para>Vertical space added, beyond <literal>\topsep</literal>+<literal>\parskip</literal>, to the top +and bottom of the entire environment if the list instance is preceded by +a blank line. (A blank line in the &latex; source before the list +changes spacing at both the top and bottom of the list; whether the line +following the list is blank does not matter.) +</para> +<para>The defaults for the first three levels in &latex;’s ‘<literal>article</literal>’, +‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes at 10 point size are: <literal>2pt +plus1 minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt +minus1pt</literal>. The defaults at 11 point are: <literal>3pt plus1pt minus1pt</literal>, +<literal>3pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt minus1pt</literal>). The +defaults at 12 point are: <literal>3pt plus2pt minus3pt</literal>, <literal>3pt plus2pt +minus2pt</literal>, and <literal>1pt plus0pt minus1pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightmargin</primary></indexterm><literal>\rightmargin</literal> +</term><listitem><anchor id="list-rightmargin"/><para>Horizontal space between the right margin of the list and the right +margin of the enclosing environment. Its default value is <literal>0pt</literal>. +It must be non-negative. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topsep</primary></indexterm><literal>\topsep</literal> +</term><listitem><anchor id="list-topsep"/><para>Vertical space added to both the top and bottom of the list, in addition +to <literal>\parskip</literal> (see <link linkend="_005cparindent-_0026-_005cparskip">\parindent & \parskip</link>). The defaults for +the first three levels in &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and +‘<literal>report</literal>’ classes at 10 point size are: <literal>8pt plus2pt minus4pt</literal>, +<literal>4pt plus2pt minus1pt</literal>, and <literal>2pt plus1pt minus1pt</literal>. The +defaults at 11 point are: <literal>9pt plus3pt minus5pt</literal>, <literal>4.5pt +plus2pt minus1pt</literal>, and <literal>2pt plus1pt minus1pt</literal>. The defaults at 12 +point are: <literal>10pt plus4pt minus6pt</literal>, <literal>5pt plus2.5pt minus1pt</literal>, +and <literal>2.5pt plus1pt minus1pt</literal>. +</para> +</listitem></varlistentry></variablelist> +<para>This shows the horizontal and vertical distances. +</para> +<informalfigure><mediaobject><imageobject><imagedata fileref="latex2e-figures/list.eps" format="EPS"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.pdf" format="PDF"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.png" format="PNG"></imagedata></imageobject><textobject><literallayout>....................................................................... +..............Surrounding environment, preceding material.............. - + | v0 + |---h0--|-h1-| | + ..Label.. .....First item..................................... - + ............................................................ + ............................................................ - + | v1 + ........First item, second paragraph .................. - + |-h2-| | v2 + | + ..Label.. .....Second item.................................... - + ............................................................ + ............................................................ - +|-h3--|-h4-| |-h5-| |v3 + | +..............Surrounding environment, following material.............. - +.......................................................................</literallayout></textobject></mediaobject></informalfigure> + +<para>The lengths shown are listed below. The key relationship is that the +right edge of the bracket for <replaceable>h1</replaceable> equals the right edge of the +bracket for <replaceable>h4</replaceable>, so that the left edge of the label box is at +<replaceable>h3</replaceable>+<replaceable>h4</replaceable>-(<replaceable>h0</replaceable>+<replaceable>h1</replaceable>). +</para> +<variablelist><varlistentry><term><replaceable>v0</replaceable> +</term><listitem><para><inlineequation><mathphrase><literal>\topsep</literal> + <literal>\parskip</literal></mathphrase></inlineequation> if +the list environment does not start a new paragraph, and +<literal>\topsep</literal>+<literal>\parskip</literal>+<literal>\partopsep</literal> if it does +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v1</replaceable> +</term><listitem><para><literal>\parsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v2</replaceable> +</term><listitem><para><literal>\itemsep</literal>+<literal>\parsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v3</replaceable> +</term><listitem><para>Same as <replaceable>v0</replaceable>. (This space is affected by whether a blank line +appears in the source above the environment; whether a blank line +appears in the source below the environment does not matter.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h0</replaceable> +</term><listitem><para><literal>\labelwidth</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h1</replaceable> +</term><listitem><para><literal>\labelsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h2</replaceable> +</term><listitem><para><literal>\listparindent</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h3</replaceable> +</term><listitem><para><literal>\leftmargin</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h4</replaceable> +</term><listitem><para><literal>\itemindent</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h5</replaceable> +</term><listitem><para><literal>\rightmargin</literal> +</para> +</listitem></varlistentry></variablelist> +<para>The list’s left and right margins, shown above as <replaceable>h3</replaceable> and <replaceable>h5</replaceable>, +are with respect to the ones provided by the surrounding environment, or +with respect to the page margins for a top-level list. The line width +used for typesetting the list items is <literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page +layout parameters</link>). For instance, set the list’s left margin to be one +quarter of the distance between the left and right margins of the +enclosing environment with +<literal>\setlength{\leftmargin}{0.25\linewidth}</literal>. +</para> +<para>Page breaking in a list structure is controlled by the three +parameters below. For each, the &latex; default is +<literal>-\@lowpenalty</literal>, that is, <literal>-51</literal>. Because it is negative, +it somewhat encourages a page break at each spot. Change it with, +e.g., <literal>\@beginparpenalty=9999</literal>; a value of 10000 prohibits a +page break. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\@beginparpenalty</primary></indexterm><literal>\@beginparpenalty</literal> +</term><listitem><anchor id="list-beginparpenalty"/><para>The page breaking penalty for breaking before the list (default <literal>-51</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@itempenalty</primary></indexterm><literal>\@itempenalty</literal> +</term><listitem><anchor id="list-itempenalty"/><para>The page breaking penalty for breaking before a list item (default <literal>-51</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@endparpenalty</primary></indexterm><literal>\@endparpenalty</literal> +</term><listitem><anchor id="list-endparpenalty"/><para>The page breaking penalty for breaking after a list (default <literal>-51</literal>). +</para> +</listitem></varlistentry></variablelist> +<indexterm role="cp"><primary>package, <literal>enumitem</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>enumitem</literal> package</primary></indexterm> + +<para>The package <literal>enumitem</literal> is useful for customizing lists. +</para> +<para>This example has the labels in red. They are numbered, and the left +edge of the label lines up with the left edge of the item text. +See <link linkend="_005cusecounter">\usecounter</link>. +</para> +<screen>\usepackage{color} +\newcounter{cnt} +\newcommand{\makeredlabel}[1]{\textcolor{red}{#1.}} +\newenvironment{redlabel} + {\begin{list} + {\arabic{cnt}} + {\usecounter{cnt} + \setlength{\labelwidth}{0em} + \setlength{\labelsep}{0.5em} + \setlength{\leftmargin}{1.5em} + \setlength{\itemindent}{0.5em} % equals \labelwidth+\labelsep + \let\makelabel=\makeredlabel + } + } +{\end{list} } +</screen> + + +<sect2 label="8.16.1" id="_005citem"> +<title><literal>\item</literal>: An entry in a list</title> + +<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 label is surrounded by square brackets +‘<literal>[...]</literal>’, if you have an item whose text starts with ‘<literal>[</literal>’, you +have to hide the bracket inside curly braces, as in: <literal>\item +{[} is an open square bracket</literal>; otherwise, &latex; will think it +marks the start of an optional label. +</para> +<para>Similarly, if the item does have the optional label and you need a +close square bracket inside that label, you must hide it in the same +way: <literal>\item[Close square bracket, {]}]</literal>. See <link linkend="LaTeX-command-syntax">&latex; +command syntax</link>. +</para> +<para>In this example the enumerate 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>’. Because +of the optional label in the second item, the third item is not +labelled ‘<literal>3.</literal>’. +</para> + +</sect2> +<sect2 label="8.16.2" id="trivlist"> +<title><literal>trivlist</literal>: A restricted form of <literal>list</literal></title> + +<para>Synopsis: +</para> +<screen>\begin{trivlist} + ... +\end{trivlist} +</screen> +<para>A restricted version of the list environment, in which margins are not +indented and an <literal>\item</literal> without an optional argument produces no +text. It is most often used in macros, to define an environment where +the <literal>\item</literal> command as part of the environment’s definition. For +instance, the <literal>center</literal> environment is defined essentially like +this: +</para> +<screen>\newenvironment{center} + {\begin{trivlist}\centering\item\relax} + {\end{trivlist}} +</screen> +<para>Using <literal>trivlist</literal> in this way allows the macro to inherit some +common code: combining vertical space of two adjacent environments; +detecting whether the text following the environment should be +considered a new paragraph or a continuation of the previous one; +adjusting the left and right margins for possible nested list +environments. +</para> +<para>Specifically, <literal>trivlist</literal> uses the current values of the list +parameters (see <link linkend="list">list</link>), except that <literal>\parsep</literal> is set to the +value of <literal>\parskip</literal>, and <literal>\leftmargin</literal>, <literal>\labelwidth</literal>, +and <literal>\itemindent</literal> are set to zero. +</para> +<para>This example outputs the items as two paragraphs, except that (by +default) they have no paragraph indent and are vertically separated. +</para> +<screen>\begin{trivlist} +\item The \textit{Surprise} is not old; no one would call her old. +\item She has a bluff bow, lovely lines. +\end{trivlist} +</screen> + +</sect2> +</sect1> +<sect1 label="8.17" id="math"> +<title><literal>math</literal></title> + +<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>in-line formulas</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{math} +<replaceable>math</replaceable> +\end{math} +</screen> +<para>The <literal>math</literal> environment inserts given <replaceable>math</replaceable> material within +the running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms. +See <link linkend="Math-formulas">Math formulas</link>. +</para> + +</sect1> +<sect1 label="8.18" id="minipage"> +<title><literal>minipage</literal></title> + +<indexterm role="fn"><primary>environment, <literal>minipage</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>minipage</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>minipage, creating a</primary></indexterm> + +<para>Synopses: +</para> +<screen>\begin{minipage}{<replaceable>width</replaceable>} + <replaceable>contents</replaceable> +\end{minipage} +</screen> +<para>or +</para> +<screen>\begin{minipage}[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>} + <replaceable>contents</replaceable> +\end{minipage} +</screen> +<para>Put <replaceable>contents</replaceable> into a box that is <replaceable>width</replaceable> wide. This is like a +small version of a page; it can contain its own footnotes, itemized +lists, etc. (There are some restrictions, including that it cannot have +floats.) This box will not be broken across pages. So <literal>minipage</literal> +is similar to <literal>\parbox</literal> (see <link linkend="_005cparbox">\parbox</link>) but here you can have +paragraphs. +</para> +<para>This example will be 3 inches wide, and has two paragraphs. +</para> +<screen>\begin{minipage}{3in} + Stephen Kleene was a founder of the Theory of Computation. + + He was a student of Church, wrote three influential texts, + was President of the Association for Symbolic Logic, + and won the National Medal of Science. +\end{minipage} +</screen> +<para>See below for a discussion of the paragraph indent inside a +<literal>minipage</literal>. +</para> +<para>The required argument <replaceable>width</replaceable> is a rigid length (see <link linkend="Lengths">Lengths</link>). +It gives the width of the box into which <replaceable>contents</replaceable> are typeset. +</para> +<para>There are three optional arguments, <replaceable>position</replaceable>, <replaceable>height</replaceable>, and +<replaceable>inner-pos</replaceable>. You need not include all three. For example, get the +default <replaceable>position</replaceable> and set the <replaceable>height</replaceable> with +<literal>\begin{minipage}[c][2.54cm] <replaceable>contents</replaceable> \end{minipage}</literal>. +(Get the natural height with an empty argument, <literal>[]</literal>.) +</para> +<para>The optional argument <replaceable>position</replaceable> governs how the <literal>minipage</literal> +vertically aligns with the surrounding material. +</para> +<variablelist><varlistentry><term><literal>c</literal> +</term><listitem><para>(synonym <literal>m</literal>) Default. Positions the <literal>minipage</literal> so its +vertical center lines up with the center of the adjacent text line (what +Plain &tex; calls <literal>\vcenter</literal>). +</para> +</listitem></varlistentry><varlistentry><term><literal>t</literal> +</term><listitem><para>Match the top line in the <literal>minipage</literal> with the baseline of the +surrounding text (Plain &tex;’s <literal>\vtop</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>b</literal> +</term><listitem><para>Match the bottom line in the <literal>minipage</literal> with the baseline of the +surrounding text (Plain &tex;’s <literal>\vbox</literal>. +</para></listitem></varlistentry></variablelist> +<para>To see the effects of these, contrast running this +</para> +<screen>---\begin{minipage}[c]{0.25in} + first\\ second\\ third +\end{minipage} +</screen> +<para>with the results of changing <literal>c</literal> to <literal>b</literal> or <literal>t</literal>. +</para> +<para>The optional argument <replaceable>height</replaceable> is a rigid length (see <link linkend="Lengths">Lengths</link>). +It sets the height of the <literal>minipage</literal>. You can enter any value +larger than, or equal to, or smaller than the <literal>minipage</literal>’s natural +height and &latex; will not give an error or warning. You can also set +it to a height of zero or a negative value. +</para> +<para>The final optional argument <replaceable>inner-pos</replaceable> controls the placement of +<replaceable>content</replaceable> inside the box. These are the possible values are (the +default is the value of <replaceable>position</replaceable>). +</para> +<variablelist><varlistentry><term><literal>t</literal> +</term><listitem><para>Place <replaceable>content</replaceable> at the top of the box. +</para> +</listitem></varlistentry><varlistentry><term><literal>c</literal> +</term><listitem><para>Place it in the vertical center. +</para> +</listitem></varlistentry><varlistentry><term><literal>b</literal> +</term><listitem><para>Place it at the box bottom. +</para> +</listitem></varlistentry><varlistentry><term><literal>s</literal> +</term><listitem><para>Stretch <replaceable>contents</replaceable> out vertically; it must contain vertically +stretchable space. +</para> +</listitem></varlistentry></variablelist> +<para>The <replaceable>inner-pos</replaceable> argument makes sense when the <replaceable>height</replaceable> option +is set to a value larger than the <literal>minipage</literal>’s natural height. To +see the effect of the options, run this example with the various choices +in place of <literal>b</literal>. +</para> +<screen>Text before +\begin{center} + ---\begin{minipage}[c][3in][b]{0.25\textwidth} + first\\ second\\ third + \end{minipage} +\end{center} +Text after +</screen> +<indexterm role="cp"><primary>indentation of paragraphs, in minipage</primary></indexterm> +<indexterm role="cp"><primary>paragraph indentation, in minipage</primary></indexterm> +<indexterm role="fn"><primary>\parindent</primary></indexterm> +<para>By default paragraphs are not indented in a <literal>minipage</literal>. Change +that with a command such as <literal>\setlength{\parindent}{1pc}</literal> at +the start of <replaceable>contents</replaceable>. +</para> +<indexterm role="cp"><primary>footnotes in figures</primary></indexterm> +<indexterm role="cp"><primary>figures, footnotes in</primary></indexterm> +<para>Footnotes in a <literal>minipage</literal> environment are handled in a way that is +particularly useful for putting footnotes in figures or tables. A +<literal>\footnote</literal> or <literal>\footnotetext</literal> command puts the footnote at +the bottom of the minipage instead of at the bottom of the page, and it +uses the <literal>\mpfootnote</literal> counter instead of the ordinary +<literal>footnote</literal> counter (see <link linkend="Counters">Counters</link>). +</para> +<para>This puts the footnote at the bottom of the table, not the bottom of the +page. +</para> +<screen>\begin{center} % center the minipage on the line +\begin{minipage}{2.5in} + \begin{center} % center the table inside the minipage + \begin{tabular}{ll} + \textsc{Monarch} &\textsc{Reign} \\ \hline + Elizabeth II &63 years\footnote{to date} \\ + Victoria &63 years \\ + George III &59 years + \end{tabular} + \end{center} +\end{minipage} +\end{center} +</screen> +<para>If you nest minipages then there is an oddness when using footnotes. +Footnotes appear at the bottom of the text ended by the next +<literal>\end{minipage}</literal> which may not be their logical place. +</para> +<para>This puts a table containing data side by side with a map graphic. They +are vertically centered. +</para> +<screen>\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}} + ... +\begin{center} + \vcenteredhbox{\includegraphics[width=0.3\textwidth]{nyc.png}} + \hspace{0.1\textwidth} + \begin{minipage}{0.5\textwidth} + \begin{tabular}{r|l} + \multicolumn{1}{r}{Borough} &Pop (million) \\ \hline + The Bronx &$1.5$ \\ + Brooklyn &$2.6$ \\ + Manhattan &$1.6$ \\ + Queens &$2.3$ \\ + Staten Island &$0.5$ + \end{tabular} + \end{minipage} +\end{center} +</screen> + +</sect1> +<sect1 label="8.19" id="picture"> +<title><literal>picture</literal></title> + +<indexterm role="fn"><primary>environment, <literal>picture</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>picture</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>creating pictures</primary></indexterm> +<indexterm role="cp"><primary>pictures, creating</primary></indexterm> + +<para>Synopses: +</para><screen>\begin{picture}(<replaceable>width</replaceable>,<replaceable>height</replaceable>) + <replaceable>picture commands</replaceable> +\end{picture} +</screen> +<para>or +</para> +<screen>\begin{picture}(<replaceable>width</replaceable>,<replaceable>height</replaceable>)(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>) + <replaceable>picture commands</replaceable> +\end{picture} +</screen> +<para>An environment to create simple pictures containing lines, arrows, +boxes, circles, and text. Note that while this environment is not +obsolete, new documents typically use much more powerful graphics +creation systems, such as <literal>TikZ</literal>, <literal>PSTricks</literal>, <literal>MetaPost</literal>, +or <literal>Asymptote</literal>. These are not covered in this document; see CTAN. +</para> +<para>This shows the parallelogram law for adding vectors. +</para> +<indexterm role="fn"><primary>\unitlength</primary></indexterm> +<screen>\setlength{\unitlength}{1cm} +\begin{picture}(6,6) % picture box will be 6cm wide by 6cm tall + \put(0,0){\vector(2,1){4}} % for every 2 over this vector goes 1 up + \put(2,1){\makebox(0,0)[l]{\ first leg}} + \put(4,2){\vector(1,2){2}} + \put(5,4){\makebox(0,0)[l]{\ second leg}} + \put(0,0){\line(1,1){6}} + \put(3,3){\makebox(0,0)[r]{sum\ }} +\end{picture} +</screen> +<para>You can also use this environment to place arbitrary material at an +exact location. +</para> +<screen>\usepackage{color,graphicx} % in preamble + ... +\begin{center} +\setlength{\unitlength}{\textwidth} +\begin{picture}(1,1) % leave space, \textwidth wide and tall + \put(0,0){\includegraphics[width=\textwidth]{desertedisland.jpg}} + \put(0.25,0.35){\textcolor{red}{X Treasure here}} +\end{picture} +\end{center} +</screen> +<para>The red X will be precisely a quarter of the <literal>\linewidth</literal> from +the left margin, and <literal>0.35\linewidth</literal> up from the bottom. Another +example of this usage is to put similar code in the page header to get +repeat material on each of a document’s pages. +</para> +<para>The <literal>picture</literal> environment has one required argument, a pair of +numbers (<replaceable>width</replaceable>,<replaceable>height</replaceable>). Multiply these by the value +<literal>\unitlength</literal> to get the nominal size of the output, the space that +&latex; reserves on the output page. This nominal size need not be how +large the picture really is; &latex; will draw things from the picture +outside the picture’s box. +</para> +<para>This environment also has an optional argument +(<replaceable>xoffset</replaceable>,<replaceable>yoffset</replaceable>). It is used to shift the origin. Unlike +most optional arguments, this one is not contained in square brackets. +As with the required argument, it consists of two real numbers. +Multiply these by <literal>\unitlength</literal> to get the point at the lower-left +corner of the picture. +</para> +<para>For example, if <literal>\unitlength</literal> has been set to <literal>1mm</literal>, the +command +</para> +<screen>\begin{picture}(100,200)(10,20) +</screen> +<para>produces a box of width 100 millimeters and height 200 millimeters. The +picture’s origin is the point (10mm,20mm) and so the lower-left corner +is there, and the upper-right corner is at (110mm,220mm). When you +first draw a picture you typically omit the optional argument, leaving +the origin at the lower-left corner. If you then want to modify your +picture by shifting everything, you can just add the appropriate +optional argument. +</para> +<indexterm role="cp"><primary>position, in picture</primary></indexterm> +<para>Each <replaceable>picture command</replaceable> tells &latex; where to put something by +naming its position. A <firstterm>position</firstterm> is a pair such as <literal>(2.4,-5)</literal> +giving the x- and y-coordinates. A <firstterm>coordinate</firstterm> is a not a length, +it is a real number (it may have a decimal point or a minus sign). It +specifies a length in multiples of the unit length <literal>\unitlength</literal>, +so if <literal>\unitlength</literal> has been set to <literal>1cm</literal>, then the coordinate +2.54 specifies a length of 2.54 centimeters. +</para> +<para>&latex;’s default for <literal>\unitlength</literal> is <literal>1pt</literal>. it is a rigid +length (see <link linkend="Lengths">Lengths</link>). Change it with the <literal>\setlength</literal> command +(see <link linkend="_005csetlength">\setlength</link>). Make this change only outside of a <literal>picture</literal> +environment. +</para> +<para>Coordinates are given 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, as with <literal>\put(1,2){...}</literal>, it is not enclosed in +braces since the parentheses serve to delimit the argument. Also, +unlike in some computer graphics systems, larger y-coordinates are +further up the page. +</para> +<para>There are four ways to put things in a picture: <literal>\put</literal>, +<literal>\multiput</literal>, <literal>\qbezier</literal>, and <literal>\graphpaper</literal>. The most +often used is <literal>\put</literal>. This +</para> +<screen>\put(11.3,-0.3){...} +</screen> +<para>places the object with its reference point at coordinates +<inlineequation><mathphrase>(11.3,-0.3)</mathphrase></inlineequation>. The reference points for various objects will be +described below. +<indexterm role="fn"><primary>LR box</primary></indexterm> +The <literal>\put</literal> command creates an <firstterm>LR box</firstterm> (see <link linkend="Modes">Modes</link>). +Anything that can go in an <literal>\mbox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link>) can +go in the text argument of the <literal>\put</literal> command. The reference point +will be the lower left corner of the box. In this picture +</para> +<screen>\setlength{\unitlength}{1cm} +...\begin{picture}(1,1) + \put(0,0){\line(1,0){1}} + \put(0,0){\line(1,1){1}} +\end{picture} +</screen> +<para>the three dots are just slightly left of the point of the angle formed +by the two lines. (Also, <literal>\line(1,1){1}</literal> does not call for a +line of length one; rather the line has a change in the x coordinate of +1.) +</para> +<para>The <literal>\multiput</literal>, <literal>qbezier</literal>, and <literal>graphpaper</literal> commands are +described below. +</para> +<para>This draws a rectangle with a wavy top, using <literal>\qbezier</literal> for +that curve. +</para> +<screen>\begin{picture}(3,1.5) + \put(0,0){\vector(1,0){8}} % x axis + \put(0,0){\vector(0,1){4}} % y axis + \put(2,0){\line(0,1){3}} % left side rectangle + \put(4,0){\line(0,1){3.5}} % right side + \qbezier(2,3)(2.5,2.9)(3,3.25) + \qbezier(3,3.25)(3.5,3.6)(4,3.5) + \thicklines % below here, lines are twice as thick + \put(2,3){\line(4,1){2}} + \put(4.5,2.5){\framebox{Trapezoidal Rule}} +\end{picture} +</screen> + + +<sect2 label="8.19.1" id="_005cput"> +<title><literal>\put</literal></title> + +<indexterm role="fn"><primary>\put</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\put(<replaceable>xcoord</replaceable>,<replaceable>ycoord</replaceable>){<replaceable>content</replaceable>} +</screen> +<para>Place <replaceable>content</replaceable> at the coordinate (<replaceable>xcoord</replaceable>,<replaceable>ycoord</replaceable>). See +the discussion of coordinates and <literal>\unitlength</literal> in <link linkend="picture">picture</link>. +The <replaceable>content</replaceable> is processed in LR mode (see <link linkend="Modes">Modes</link>) so it cannot +contain line breaks. +</para> +<para>This includes the text into the <literal>picture</literal>. +</para> +<screen>\put(4.5,2.5){Apply the \textit{unpoke} move} +</screen> +<para>The reference point, the location (4.5,2.5), is the lower left of the +text, at the bottom left of the ‘<literal>A</literal>’. +</para> + +</sect2> +<sect2 label="8.19.2" 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>num-copies</replaceable>}{<replaceable>obj</replaceable>} +</screen> +<para>Copy <replaceable>obj</replaceable> a total of <replaceable>num-copies</replaceable> times, with an increment of +<replaceable>delta_x,delta_y</replaceable>. The <replaceable>obj</replaceable> first appears at position +<inlineequation><mathphrase>(x,y)</mathphrase></inlineequation>, then at <inlineequation><mathphrase>(x+\delta_x,y+\delta_y)</mathphrase></inlineequation>, and so on. +</para> +<para>This draws a simple grid with every fifth line in bold (see also +<link linkend="_005cgraphpaper">\graphpaper</link>). +</para> +<screen>\begin{picture}(10,10) + \linethickness{0.05mm} + \multiput(0,0)(1,0){10}{\line(0,1){10}} + \multiput(0,0)(0,1){10}{\line(1,0){10}} + \linethickness{0.5mm} + \multiput(0,0)(5,0){3}{\line(0,1){10}} + \multiput(0,0)(0,5){3}{\line(1,0){10}} +\end{picture} +</screen> + +</sect2> +<sect2 label="8.19.3" id="_005cqbezier"> +<title><literal>\qbezier</literal></title> + +<indexterm role="fn"><primary>\qbezier</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\qbezier(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)(<replaceable>x3</replaceable>,<replaceable>y3</replaceable>) +\qbezier[<replaceable>num</replaceable>](<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)(<replaceable>x3</replaceable>,<replaceable>y3</replaceable>) +</screen> +<para>Draw a quadratic Bezier curve whose control points are given by the +three required arguments <literal>(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)</literal>, +<literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>, and <literal>(<replaceable>x3</replaceable>,<replaceable>y3</replaceable>)</literal>. That is, +the curve runs from <replaceable>(x1,y1)</replaceable> to <replaceable>(x3,y3)</replaceable>, is quadratic, and is +such that the tangent line at <replaceable>(x1,y1)</replaceable> passes through +<replaceable>(x2,y2)</replaceable>, as does the tangent line at <replaceable>(x3,y3)</replaceable>. +</para> +<para>This draws a curve from the coordinate (1,1) to (1,0). +</para> +<screen>\qbezier(1,1)(1.25,0.75)(1,0) +</screen> +<para>The curve’s tangent line at (1,1) contains (1.25,0.75), as does the +curve’s tangent line at (1,0). +</para> +<para>The optional argument <replaceable>num</replaceable> gives the number of calculated +intermediate points. The default is to draw a smooth curve whose +maximum number of points is <literal>\qbeziermax</literal> (change this value with +<literal>\renewcommand</literal>). +</para> + +</sect2> +<sect2 label="8.19.4" id="_005cgraphpaper"> +<title><literal>\graphpaper</literal></title> + +<indexterm role="fn"><primary>\graphpaper</primary></indexterm> +<para>Synopsis: +</para> +<screen>\graphpaper(<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)(<replaceable>x_dimen</replaceable>,<replaceable>y_dimen</replaceable>) +\graphpaper[<replaceable>spacing</replaceable>](<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)(<replaceable>x_dimen</replaceable>,<replaceable>y_dimen</replaceable>) +</screen> +<para>Draw a coordinate grid. Requires the <literal>graphpap</literal> package. +The grid’s origin is <literal>(<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>)</literal>. +Grid lines come every <replaceable>spacing</replaceable> units (the default is 10). +The grid extends <replaceable>x_dimen</replaceable> units to the right and <replaceable>y_dimen</replaceable> units up. +All arguments must be positive integers. +</para> +<para>This make a grid with seven vertical lines and eleven horizontal lines. +</para> +<screen>\usepackage{graphpap} % in preamble + ... +\begin{picture}(6,20) % in document body + \graphpaper[2](0,0)(12,20) +\end{picture} +</screen> +<para>The lines are numbered every ten units. +</para> + +</sect2> +<sect2 label="8.19.5" id="_005cline"> +<title><literal>\line</literal></title> + +<indexterm role="fn"><primary>\line</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\line(<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>){<replaceable>travel</replaceable>} +</screen> +<para>Draw a line. It slopes such that it vertically rises <replaceable>y_rise</replaceable> for +every horizontal <replaceable>x_run</replaceable>. The <replaceable>travel</replaceable> is the total horizontal +change — it is not the length of the vector, it is the change in +<inlineequation><mathphrase>x</mathphrase></inlineequation>. In the special case of vertical lines, where +(<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>)=(0,1), the <replaceable>travel</replaceable> gives the change in +<inlineequation><mathphrase>y</mathphrase></inlineequation>. +</para> +<para>This draws a line starting at coordinates (1,3). +</para> +<screen>\put(1,3){\line(2,5){4}} +</screen> +<para>For every over 2, this line will go up 5. Because <replaceable>travel</replaceable> +specifies that this goes over 4, it must go up 10. Thus its +endpoint is <inlineequation><mathphrase>(1,3)+(4,10)=(5,13)</mathphrase></inlineequation>. In particular, note that +<inlineequation><mathphrase><replaceable>travel</replaceable>=4</mathphrase></inlineequation> is not the length of the line, it is the change in +<inlineequation><mathphrase>x</mathphrase></inlineequation>. +</para> +<para>The arguments <replaceable>x_run</replaceable> and <replaceable>y_rise</replaceable> are integers that can be +positive, negative, or zero. (If both are 0 then &latex; treats the +second as 1.) With +<literal>\put(<replaceable>x_init</replaceable>,<replaceable>y_init</replaceable>){\line(<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>){<replaceable>travel</replaceable>}}</literal>, +if <replaceable>x_run</replaceable> is negative then the line’s ending point has a first +coordinate that is less than <replaceable>x_init</replaceable>. If <replaceable>y_rise</replaceable> is negative +then the line’s ending point has a second coordinate that is less than +<replaceable>y_init</replaceable>. +</para> +<para>If <replaceable>travel</replaceable> is negative then you get <literal>LaTeX Error: Bad \line or +\vector argument.</literal> +</para> +<indexterm role="cp"><primary><literal>pict2e</literal> package</primary></indexterm> +<indexterm role="cp"><primary>graphics packages</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>pict2e</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>pict2e</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>TikZ</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>TikZ</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>PSTricks</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>PSTricks</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>MetaPost</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>MetaPost</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>Asymptote</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>Asymptote</literal> package</primary></indexterm> + +<para>Standard &latex; can only draw lines with a limited range of slopes +because these lines are made by putting together line segments from +pre-made fonts. The two numbers <replaceable>x_run</replaceable> and <replaceable>y_rise</replaceable> must have +integer values from −6 through 6. Also, they must be +relatively prime, so that <replaceable>(x_run,y_rise)</replaceable> can be (2,1) but not +(4,2) (if you choose the latter then instead of lines you get sequences +of arrowheads; the solution is to switch to the former). To get lines +of arbitrary slope and plenty of other shapes in a system like +<literal>picture</literal>, see the package <filename>pict2e</filename> on CTAN. Another solution +is to use a full-featured graphics system such as <filename>TikZ</filename>, or +<filename>PSTricks</filename>, or <filename>MetaPost</filename>, or <filename>Asymptote</filename> +</para> + +</sect2> +<sect2 label="8.19.6" id="_005clinethickness"> +<title><literal>\linethickness</literal></title> + +<indexterm role="fn"><primary>\linethickness</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\linethickness{<replaceable>dim</replaceable>} +</screen> +<para>Declares the thickness of subsequent horizontal and vertical lines in a +picture to be <replaceable>dim</replaceable>, which must be a positive length +(see <link linkend="Lengths">Lengths</link>). It differs from <literal>\thinlines</literal> and +<literal>\thicklines</literal> in that it does not affect the thickness of slanted +lines, circles, or ovals. +</para> + +</sect2> +<sect2 label="8.19.7" id="_005cthinlines"> +<title><literal>\thinlines</literal></title> + +<indexterm role="fn"><primary>\thinlines</primary></indexterm> + +<para>Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.4pt. This is the default +thickness, so this command is unnecessary unless the thickness has been +changed with either <link linkend="_005clinethickness">\linethickness</link> or <link linkend="_005cthicklines">\thicklines</link>. +</para> + +</sect2> +<sect2 label="8.19.8" id="_005cthicklines"> +<title><literal>\thicklines</literal></title> + +<indexterm role="fn"><primary>\thicklines</primary></indexterm> + +<para>Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.8pt. See also +<link linkend="_005clinethickness">\linethickness</link> and <link linkend="_005cthinlines">\thinlines</link>. This command is illustrated +in the Trapezoidal Rule example of <link linkend="picture">picture</link>. +</para> + +</sect2> +<sect2 label="8.19.9" id="_005ccircle"> +<title><literal>\circle</literal></title> + +<indexterm role="fn"><primary>\circle</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\circle{<replaceable>diameter</replaceable>} +\circle*{<replaceable>diameter</replaceable>} +</screen> +<para>Produces a circle with a diameter as close as possible to the specified +one. The <literal>*</literal> form produces a filled-in circle. +</para> +<para>This draws a circle of radius 6, centered at <literal>(5,7)</literal>. +</para> +<screen>\put(5,7){\circle{6}} +</screen> +<para>The available radii for <literal>circle</literal> are, in points, the even +numbers from 2 to 20, inclusive. For <literal>circle*</literal> they are all the +integers from 1 to 15. +</para> + +</sect2> +<sect2 label="8.19.10" 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>) +\oval(<replaceable>width</replaceable>,<replaceable>height</replaceable>)[<replaceable>portion</replaceable>] +</screen> +<para>Produce a rectangle with rounded corners. The optional argument +<replaceable>portion</replaceable> allows you to produce only half or a quarter of the oval. +For half an oval take <replaceable>portion</replaceable> to be one of these. +</para> +<variablelist><varlistentry><term><literal>t</literal> +</term><listitem><para>top half +</para></listitem></varlistentry><varlistentry><term><literal>b</literal> +</term><listitem><para>bottom half +</para></listitem></varlistentry><varlistentry><term><literal>r</literal> +</term><listitem><para>right half +</para></listitem></varlistentry><varlistentry><term><literal>l</literal> +</term><listitem><para>left half +</para></listitem></varlistentry></variablelist> +<para>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>This draws the top half of an oval that is 3 wide and 7 tall. +</para> +<screen>\put(5,7){\oval(3,7)[t]} +</screen> +<para>The (5,7) is the center of the entire oval, not just the center of the +top half. +</para> +<para>These shapes are not ellipses. They are rectangles whose corners are +made with quarter circles. These circles have a maximum radius of +20pt (see <link linkend="_005ccircle">\circle</link> for the sizes). Thus large ovals are just +boxes with a small amount of corner rounding. +</para> + +</sect2> +<sect2 label="8.19.11" id="_005cshortstack"> +<title><literal>\shortstack</literal></title> + +<indexterm role="fn"><primary>\shortstack</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\shortstack[<replaceable>position</replaceable>]{<replaceable>line 1</replaceable> \\ ... } +</screen> +<para>Produce a vertical stack of objects. +</para> +<para>This labels the <inlineequation><mathphrase>y</mathphrase></inlineequation> axis. +</para> +<screen>\put(0,0){\vector(1,0){4}} % x axis +\put(0,0){\vector(0,1){2}} % y +\put(-0.25,2){\makebox[0][r]{\shortstack[r]{$y$\\ axis}}} +</screen> +<para>For a short stack, the reference point is the lower left of the stack. +In the above example the <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link> puts the stack flush +right in a zero width box so in total the short stack sits slightly to +the left of the <inlineequation><mathphrase>y</mathphrase></inlineequation> axis. +</para> +<para>The valid positions are: +</para> +<variablelist><varlistentry><term><literal>r</literal> +</term><listitem><para>Make objects flush right +</para></listitem></varlistentry><varlistentry><term><literal>l</literal> +</term><listitem><para>Make objects flush left +</para></listitem></varlistentry><varlistentry><term><literal>c</literal> +</term><listitem><para>Center objects (default) +</para></listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>\\ (for <literal>\shortstack</literal> objects)</primary></indexterm> +<para>Separate objects into lines with <literal>\\</literal>. These stacks are short in +that, unlike in a <literal>tabular</literal> or <literal>array</literal> environment, here the +rows are not spaced out to be of even heights. Thus, in +<literal>\shortstack{X\\o\\o\\X}</literal> the first and last rows are taller than +the middle two. You can adjust row heights either by putting in the +usual interline spacing with <literal>\shortstack{X\\ \strut o\\o\\X}</literal>, +or by hand, via an explicit zero-width box <literal>\shortstack{X \\ +\rule{0pt}{12pt} o\\o\\X}</literal> or by using <literal>\\</literal>’s optional +argument <literal>\shortstack{X\\[2pt] o\\o\\X}</literal>. +</para> +<para>The <literal>\shortstack</literal> command is also available outside the +<literal>picture</literal> environment. +</para> + +</sect2> +<sect2 label="8.19.12" id="_005cvector"> +<title><literal>\vector</literal></title> + +<indexterm role="fn"><primary>\vector</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\vector(<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>){<replaceable>travel</replaceable>} +</screen> +<para>Draw a line ending in an arrow. The slope of that line is: it +vertically rises <replaceable>y_rise</replaceable> for every horizontal <replaceable>x_run</replaceable>. The +<replaceable>travel</replaceable> is the total horizontal change — it is not the +length of the vector, it is the change in <inlineequation><mathphrase>x</mathphrase></inlineequation>. In the special case +of vertical vectors, if (<replaceable>x_run</replaceable>,<replaceable>y_rise</replaceable>)=(0,1), then +<replaceable>travel</replaceable> gives the change in <inlineequation><mathphrase>y</mathphrase></inlineequation>. +</para> +<para>For an example see <link linkend="picture">picture</link>. +</para> +<para>For elaboration on <replaceable>x_run</replaceable> and <replaceable>y_rise</replaceable> see <link linkend="_005cline">\line</link>. As +there, the values of <replaceable>x_run</replaceable> and <replaceable>y_rise</replaceable> are limited. For +<literal>\vector</literal> you must chooses integers between −4 and 4, +inclusive. Also, the two you choose must be relatively prime. Thus, +<literal>\vector(2,1){4}</literal> is acceptable but <literal>\vector(4,2){4}</literal> is +not (if you use the latter then you get a sequence of arrowheads). +</para> + +</sect2> +<sect2 label="8.19.13" id="_005cmakebox-_0028picture_0029"> +<title><literal>\makebox</literal> (picture)</title> + +<indexterm role="fn"><primary>\makebox (for <literal>picture</literal>)</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\makebox(<replaceable>rec-width</replaceable>,<replaceable>rec-height</replaceable>){<replaceable>text</replaceable>} +\makebox(<replaceable>rec-width</replaceable>,<replaceable>rec-height</replaceable>)[<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Make a box to hold <replaceable>text</replaceable>. This command fits with the +<literal>picture</literal> environment, although you can use it outside of there, +because <replaceable>rec-width</replaceable> and <replaceable>rec-height</replaceable> are numbers specifying +distances in terms of the <literal>\unitlength</literal> (see <link linkend="picture">picture</link>). This +command is similar to the normal <literal>\makebox</literal> command (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & +\makebox</link>) except here that you must specify the width and height. This +command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This makes a box of length 3.5 times <literal>\unitlength</literal> and height 4 +times <literal>\unitlength</literal>. +</para> +<screen>\put(1,2){\makebox(3.5,4){...}} +</screen> +<para>The optional argument <literal><replaceable>position</replaceable></literal> specifies where in the box +the <replaceable>text</replaceable> appears. The default is to center it, both horizontally +and vertically. To place it somewhere else, use a string with one or +two of these letters. +</para> +<variablelist><varlistentry><term><literal>t</literal> +</term><listitem><para>Puts <replaceable>text</replaceable> the top of the box. +</para> +</listitem></varlistentry><varlistentry><term><literal>b</literal> +</term><listitem><para>Put <replaceable>text</replaceable> at the bottom. +</para> +</listitem></varlistentry><varlistentry><term><literal>l</literal> +</term><listitem><para>Put <replaceable>text</replaceable> on the left. +</para> +</listitem></varlistentry><varlistentry><term><literal>r</literal> +</term><listitem><para>Put <replaceable>text</replaceable> on the right. +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="8.19.14" id="_005cframebox-_0028picture_0029"> +<title><literal>\framebox</literal> (picture)</title> + +<indexterm role="fn"><primary>\framebox</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\framebox(<replaceable>rec-width</replaceable>,<replaceable>rec-height</replaceable>){<replaceable>text</replaceable>} +\framebox(<replaceable>rec-width</replaceable>,<replaceable>rec-height</replaceable>)[<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>This is the same as <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link> except that it puts a frame +around the outside of the box that it creates. The reference point is +the bottom left corner of the frame. This command fits with the +<literal>picture</literal> environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +<literal>\unitlength</literal> (see <link linkend="picture">picture</link>). This command is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This example creates a frame 2.5 inches by 3 inches and puts +the text in the center. +</para> +<screen>\setlength{\unitlength}{1in} +\framebox(2.5,3){test text} +</screen> +<para>The required arguments are that the rectangle has overall width +<replaceable>rect-width</replaceable> units and height <replaceable>rect-height</replaceable> units. +</para> +<para>The optional argument <replaceable>position</replaceable> specifies the position of +<replaceable>text</replaceable>; see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link> for the values that it can +take. +</para> +<indexterm role="fn"><primary>\fboxrule</primary></indexterm> +<indexterm role="fn"><primary>\fboxsep</primary></indexterm> +<para>The rule has thickness <literal>\fboxrule</literal> and there is a blank space +<literal>\fboxsep</literal> between the frame and the contents of the box. +</para> +<para>For this command, you must specify the <replaceable>width</replaceable> and <replaceable>height</replaceable>. If +you want to just put a frame around some contents whose dimension is +determined in some other way then either use <literal>\fbox</literal> (see <link linkend="_005cfbox-_0026-_005cframebox">\fbox +& \framebox</link>) or <literal>\frame</literal> (see <link linkend="_005cframe">\frame</link>). +</para> + +</sect2> +<sect2 label="8.19.15" id="_005cframe"> +<title><literal>\frame</literal></title> + +<indexterm role="fn"><primary>\frame</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\frame{<replaceable>contents</replaceable>} +</screen> +<para>Puts a rectangular frame around <replaceable>contents</replaceable>. The reference point is +the bottom left corner of the frame. In contrast to <literal>\framebox</literal> +(see <link linkend="_005cframebox-_0028picture_0029">\framebox (picture)</link>), this command puts no extra space is put +between the frame and the object. It is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> + +</sect2> +<sect2 label="8.19.16" id="_005cdashbox"> +<title><literal>\dashbox</literal></title> + +<indexterm role="fn"><primary>\dashbox</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\dashbox{<replaceable>dash-len</replaceable>}(<replaceable>rect-width</replaceable>,<replaceable>rect-height</replaceable>){<replaceable>text</replaceable>} +\dashbox{<replaceable>dash-len</replaceable>}(<replaceable>rect-width</replaceable>,<replaceable>rect-height</replaceable>)[<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Create a dashed rectangle around <replaceable>text</replaceable>. This command fits with the +<literal>picture</literal> environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +<literal>\unitlength</literal> (see <link linkend="picture">picture</link>). +</para> +<para>The required arguments are: dashes are <replaceable>dash-len</replaceable> units long, with +the same length gap, and the rectangle has overall width +<replaceable>rect-width</replaceable> units and height <replaceable>rect-height</replaceable> units. +</para> +<para>The optional argument <replaceable>position</replaceable> specifies the position of +<replaceable>text</replaceable>; see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link> for the values that it can +take. +</para> +<para>This shows that you can use non-integer value for <replaceable>dash-len</replaceable>. +</para> +<screen>\put(0,0){\dashbox{0.1}(5,0.5){My hovercraft is full of eels.}} +</screen> +<para>Each dash will be <literal>0.1\unitlength</literal> long, the box’s width is +<literal>5\unitlength</literal> and its height is <literal>0.5\unitlength</literal>. +</para> +<para>As in that example, a dashed box looks best when <replaceable>rect-width</replaceable> and +<replaceable>rect-height</replaceable> are multiples of the <replaceable>dash-len</replaceable>. +</para> + +</sect2> +</sect1> +<sect1 label="8.20" id="quotation-_0026-quote"> +<title><literal>quotation</literal> & <literal>quote</literal></title> + +<indexterm role="fn"><primary>environment, <literal>quotation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>quotation</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>quoted text with paragraph indentation, displaying</primary></indexterm> +<indexterm role="cp"><primary>displaying quoted text with paragraph indentation</primary></indexterm> +<indexterm role="cp"><primary>paragraph indentations in quoted text</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>quote</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>quote</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>quoted text without paragraph indentation, displaying</primary></indexterm> +<indexterm role="cp"><primary>displaying quoted text without paragraph indentation</primary></indexterm> +<indexterm role="cp"><primary>paragraph indentations in quoted text, omitting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{quotation} + <replaceable>text</replaceable> +\end{quotation} +</screen> +<para>or +</para> +<screen>\begin{quote} + <replaceable>text</replaceable> +\end{quote} +</screen> +<para>Include a quotation. Both environments indent margins on both sides by +<literal>\leftmargin</literal> and the text is right-justified. +</para> +<para>They differ in how they treat paragraphs. 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>). +</para> +<screen>\begin{quotation} \small\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.21" id="tabbing"> +<title><literal>tabbing</literal></title> + +<indexterm role="fn"><primary>environment, <literal>tabbing</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>tabbing</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>tab stops, using</primary></indexterm> +<indexterm role="cp"><primary>lining text up using tab stops</primary></indexterm> +<indexterm role="cp"><primary>alignment via tabbing</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{tabbing} +<replaceable>row1col1</replaceable> \= <replaceable>row1col2</replaceable> ... \\ +<replaceable>row2col1</replaceable> \> <replaceable>row2col2</replaceable> ... \\ +... +\end{tabbing} +</screen> +<para>Align text in columns, by setting tab stops and tabbing to them much as +was done on a typewriter. This is less often used than the environments +<literal>tabular</literal> (see <link linkend="tabular">tabular</link>) or <literal>array</literal> (see <link linkend="array">array</link>) because +in those the width of each column need not be constant and need not be +known in advance. +</para> +<para>This example has a first line where the tab stops are set to explicit +widths, ended by a <literal>\kill</literal> command (which is described below): +</para> +<screen>\begin{tabbing} +\hspace{0.75in} \= \hspace{0.40in} \= \hspace{0.40in} \kill +Ship \> Guns \> Year \\ +\textit{Sophie} \> 14 \> 1800 \\ +\textit{Polychrest} \> 24 \> 1803 \\ +\textit{Lively} \> 38 \> 1804 \\ +\textit{Surprise} \> 28 \> 1805 \\ +\end{tabbing} +</screen> +<para>Both the <literal>tabbing</literal> environment and the more widely-used +<literal>tabular</literal> environment put text in columns. The most important +distinction is that in <literal>tabular</literal> the width of columns is +determined automatically by &latex;, while in <literal>tabbing</literal> the user +sets the tab stops. Another distinction is that <literal>tabular</literal> +generates a box, but <literal>tabbing</literal> can be broken across pages. +Finally, while <literal>tabular</literal> can be used in any mode, <literal>tabbing</literal> +can be used only in paragraph mode and it starts a new paragraph. +</para> +<para>A <literal>tabbing</literal> environment always starts a new paragraph, without +indentation. Moreover, as shown in the example above, there is no need +to use the starred form of the <literal>\hspace</literal> command at the beginning +of a tabbed row. The right margin of the <literal>tabbing</literal> environment is +the end of line, so that the width of the environment is +<literal>\linewidth</literal>. +</para> +<indexterm role="cp"><primary>row, tabbing</primary></indexterm> +<para>The <literal>tabbing</literal> environment contains a sequence of <firstterm>tabbed +rows</firstterm>. The first tabbed row begins immediately after +<literal>\begin{tabbing}</literal> and each row ends with <literal>\\</literal> or +<literal>\kill</literal>. The last row may omit the <literal>\\</literal> and end with just +<literal>\end{tabbing}</literal>. +</para> +<para>At any point the <literal>tabbing</literal> environment has a current tab stop +pattern, a sequence of <inlineequation><mathphrase><replaceable>n</replaceable> > 0</mathphrase></inlineequation> tab stops, numbered 0, 1, +etc. These create <replaceable>n</replaceable> corresponding columns. Tab stop 0 is +always the left margin, defined by the enclosing environment. Tab +stop number <replaceable>i</replaceable> is set if it is assigned a horizontal +position on the page. Tab stop number <replaceable>i</replaceable> can only be set if +all the stops 0, …, <inlineequation><mathphrase>i-1</mathphrase></inlineequation> have already been set; normally +later stops are to the right of earlier ones. +</para> +<para>By default any text typeset in a <literal>tabbing</literal> environment is typeset +ragged right and left-aligned on the current tab stop. Typesetting is +done in LR mode (see <link linkend="Modes">Modes</link>). +</para> +<para>The following commands can be used inside a <literal>tabbing</literal> environment. +They are all fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\\ (tabbing)</primary></indexterm><literal>\\ (tabbing)</literal> +</term><listitem><para>End a tabbed line and typeset it. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\= (tabbing)</primary></indexterm><literal>\= (tabbing)</literal> +</term><listitem><para>Sets a tab stop at the current position. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\> (tabbing)</primary></indexterm><literal>\> (tabbing)</literal> +</term><listitem><indexterm role="fn"><primary>\></primary></indexterm> +<para>Advances to the next tab stop. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\<</primary></indexterm><literal>\<</literal> +</term><listitem><para>Put following text to the left of the local margin (without changing +the margin). Can only be used at the start of the line. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\+</primary></indexterm><literal>\+</literal> +</term><listitem><para>Moves the left margin of the next and all the +following commands one tab stop to the right, beginning tabbed line if +necessary. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\-</primary></indexterm><literal>\-</literal> +</term><listitem><para>Moves the left margin of the next and all the +following commands one tab stop to the left, beginning tabbed line if +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>, <literal>\<</literal>, <literal>\'</literal>, +<literal>\\</literal>, or <literal>\kill</literal> command, to the previous column and aligned +to the right, flush against the current column’s tab stop. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\` (tabbing)</primary></indexterm><literal>\` (tabbing)</literal> +</term><listitem><para>Allows you to put text flush right against any tab stop, including tab +stop 0. However, it can’t move text to the right of the last +column because there’s no tab stop there. The <literal>\`</literal> command moves +all the text that follows it, up to the <literal>\\</literal> or +<literal>\end{tabbing}</literal> command that ends the line, to the right margin +of the <literal>tabbing</literal> environment. There must be no <literal>\></literal> or +<literal>\'</literal> command between the <literal>\`</literal> and the <literal>\\</literal> or +<literal>\end{tabbing}</literal> command that ends the line. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\a (tabbing)</primary></indexterm><literal>\a (tabbing)</literal> +</term><listitem><indexterm role="fn"><primary>\a' (acute accent in tabbing)</primary></indexterm> +<indexterm role="fn"><primary>\a` (grave accent in tabbing)</primary></indexterm> +<indexterm role="fn"><primary>\a= (macron accent in tabbing)</primary></indexterm> +<para>In a <literal>tabbing</literal> environment, the commands <literal>\=</literal>, <literal>\'</literal> and +<literal>\`</literal> do not produce accents as usual (see <link linkend="Accents">Accents</link>). Instead, +use the commands <literal>\a=</literal>, <literal>\a'</literal> and <literal>\a`</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\kill</primary></indexterm><literal>\kill</literal> +</term><listitem><para>Sets tab stops without producing text. Works just like <literal>\\</literal> except +that it throws away the current line instead of producing output for it. +Any <literal>\=</literal>, <literal>\+</literal> or <literal>\-</literal> commands in that line remain in +effect. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\poptabs</primary></indexterm><literal>\poptabs</literal> +</term><listitem><indexterm role="fn"><primary>\poptabs</primary></indexterm> +<para>Restores the tab stop positions saved by the last <literal>\pushtabs</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pushtabs</primary></indexterm><literal>\pushtabs</literal> +</term><listitem><para>Saves all current tab stop positions. Useful for temporarily changing +tab stop positions in the middle of a <literal>tabbing</literal> environment. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tabbingsep</primary></indexterm><literal>\tabbingsep</literal> +</term><listitem><para>Distance of the text moved by <literal>\'</literal> to left of current tab stop. +</para> +</listitem></varlistentry></variablelist> +<para>This example typesets a Pascal function: +</para> +<screen>\begin{tabbing} +function \= fact(n : integer) : integer;\\ + \> begin \= \+ \\ + \> if \= n > 1 then \+ \\ + fact := n * fact(n-1) \- \\ + else \+ \\ + fact := 1; \-\- \\ + end;\\ +\end{tabbing} +</screen> +<para>The output looks like this. +</para> +<screen>function fact(n : integer) : integer; + begin + if n > 1 then + fact := n * fact(n-1); + else + fact := 1; + end; +</screen> +<indexterm role="cp"><primary>package, <literal>algorithm2e</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>algorithm2e</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm> + +<para>This example is just for illustration of the environment. To actually +typeset computer code in typewriter like this, a verbatim environment +(see <link linkend="verbatim">verbatim</link>) would normally be best. For pretty-printed code, +there are quite a few packages, including <literal>algorithm2e</literal>, +<literal>fancyvrb</literal>, <literal>listings</literal>, and <literal>minted</literal>. +</para> + +</sect1> +<sect1 label="8.22" id="table"> +<title><literal>table</literal></title> + +<indexterm role="fn"><primary>environment, <literal>table</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>table</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>tables, creating</primary></indexterm> +<indexterm role="cp"><primary>creating tables</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{table}[<replaceable>placement</replaceable>] + <replaceable>table body</replaceable> + \caption[<replaceable>loftitle</replaceable>]{<replaceable>title</replaceable>} % optional + \label{<replaceable>label}</replaceable> % also optional +\end{table} +</screen> +<para>A class of floats (see <link linkend="Floats">Floats</link>). They cannot be split across pages +and so 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>This example <literal>table</literal> environment contains a <literal>tabular</literal> +</para> +<screen>\begin{table} + \centering\small + \begin{tabular}{ll} + \multicolumn{1}{c}{\textit{Author}} + &\multicolumn{1}{c}{\textit{Piece}} \\ \hline + Bach &Cello Suite Number 1 \\ + Beethoven &Cello Sonata Number 3 \\ + Brahms &Cello Sonata Number 1 + \end{tabular} + \caption{Top cello pieces} + \label{tab:cello} +\end{table} +</screen> +<para>but you can put many different kinds of content in a <literal>table</literal>, +including text, &latex; commands, etc. +</para> +<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 table body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal>. +It can contain text, commands, graphics, 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 <literal>\caption</literal> command is also optional. It specifies caption text +for the table. By default it is numbered. If its optional +<replaceable>lottitle</replaceable> is present then that text is used in the list of tables +instead of <replaceable>title</replaceable> (see <link linkend="Table-of-contents-etc_002e">Table of contents etc.</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.23" id="tabular"> +<title><literal>tabular</literal></title> + +<indexterm role="fn"><primary>environment, <literal>tabular</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>tabular</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>lines in tables</primary></indexterm> +<indexterm role="cp"><primary>lining text up in tables</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{tabular}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} + <replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ + ... +\end{tabular} +</screen> +<para>or +</para> +<screen>\begin{tabular*}{<replaceable>width</replaceable>}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} + <replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ + ... +\end{tabular*} +</screen> +<para>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 output will have two left-aligned columns with a vertical bar +between them. This is specified in <literal>tabular</literal>’s argument +<literal>{l|l}</literal>. +<indexterm role="fn"><primary>&</primary></indexterm> +Put the entries into different columns by separating them with an +ampersand, <literal>&</literal>. The end of each row is marked with a double +backslash, <literal>\\</literal>. Put a horizontal rule below a row, after a double +backslash, with <literal>\hline</literal>. +<indexterm role="fn"><primary>\\ for <literal>tabular</literal></primary></indexterm> +After the last row the <literal>\\</literal> is optional, unless an <literal>\hline</literal> +command follows to put a rule below the table. +</para> +<para>The required and optional arguments to <literal>tabular</literal> consist of: +</para> +<variablelist><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. +</para> +</listitem></varlistentry><varlistentry><term><literal>r</literal> +</term><listitem><para>A column of right-aligned items. +</para> +</listitem></varlistentry><varlistentry><term><literal>c</literal> +</term><listitem><para>A column of centered items. +</para> +</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 or space</replaceable>}</literal> +</term><listitem><para>Insert <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>If between two columns there is no @-expression then &latex;’s +<literal>book</literal>, <literal>article</literal>, and <literal>report</literal> classes will put on +either side of each column a space of length <literal>\tabcolsep</literal>, which by +default is 6pt. That is, by default adjacent columns are +separated by 12pt (so <literal>\tabcolsep</literal> is misleadingly named +since it is only half of the separation between tabular columns). In +addition, a space of 6pt also comes before the first column and +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 &latex; does +not insert <literal>\tabcolsep</literal> so you must insert any desired space +yourself, as in <literal>@{\hspace{1em}}</literal>. +</para> +<para>An empty expression <literal>@{}</literal> will eliminate the space. In +particular, sometimes you want to eliminate the space before the first +column or after the last one, as in the example below where the +tabular lines need to lie on the left margin. +</para> +<screen>\begin{flushleft} + \begin{tabular}{@{}l} + ... + \end{tabular} +\end{flushleft} +</screen> +<para>The next example shows text, a decimal point between the columns, +arranged so the numbers in the table are aligned on it. +</para> +<screen>\begin{tabular}{r@{$.$}l} + $3$ &$14$ \\ + $9$ &$80665$ +\end{tabular} +</screen> +<indexterm role="fn"><primary>\extracolsep</primary></indexterm> +<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>. 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{tabular*}{4in}{l@{\extracolsep{\fill}}l} + Seven times down, eight times up \ldots + &such is life! +\end{tabular*} +</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>Each item in the column is typeset in a parbox of width <replaceable>wd</replaceable>, as if +it were the argument of a <literal>\parbox[t]{wd}{...}</literal> command. +</para> +<para>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. Instead, to get a line break in there use +<literal>\newline</literal> (see <link linkend="_005cnewline">\newline</link>). +</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 a list of specifiers. Thus the +specifier <literal>\begin{tabular}{|*{3}{l|r}|}</literal> is equivalent to +the specifier <literal>\begin{tabular}{|l|rl|rl|r|}</literal>. Note that +<replaceable>cols</replaceable> may contain another <literal>*</literal>-expression. +</para> +</listitem></varlistentry></variablelist> +</listitem></varlistentry><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></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><anchor id="tabular-arrayrulewidth"/><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><anchor id="tabular-arraystrech"/><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><anchor id="tabular-doublerulesep"/><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><anchor id="tabular-tabcolsep"/><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 the body of a <literal>tabular</literal> +environment, the first two inside an entry and the second two between +lines: +</para> + + +<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>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 + 978-0-393-03701-2 &O'Brian &Patrick &55 \\ + ... +\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>Although the <literal>tabular</literal> specification by default puts a vertical +rule between the first and second columns, no such vertical rule appears +in the first row here. That’s because there is no vertical bar in the +<replaceable>cols</replaceable> part of the first row’s first <literal>\multicolumn</literal> command. +</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 in the +body of a table; typically a table’s vertical lines are specified in +<literal>tabular</literal>’s <replaceable>cols</replaceable> argument and overridden as needed with +<literal>\multicolumn</literal> (see <link linkend="tabular">tabular</link>). +</para> +<para>The example below illustrates some pitfalls. In the first row’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 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 row’s +third entry shows the usual way to put a vertical bar between two +columns. In the second row, 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} \\ % row 1 + abc &def &\vline\hfill ghi % row 2 +\end{tabular} +</screen> + +</sect2> +<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>In an <literal>array</literal> or <literal>tabular</literal> environment, draw a horizontal rule +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, as with <literal>\cline{2-2}</literal>. +</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.23.4" id="_005chline"> +<title><literal>\hline</literal></title> + +<indexterm role="fn"><primary>\hline</primary></indexterm> + +<para>Draw 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> +<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.24" id="thebibliography"> +<title><literal>thebibliography</literal></title> + +<indexterm role="fn"><primary>environment, <literal>thebibliography</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>thebibliography</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>bibliography, creating (manually)</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{thebibliography}{<replaceable>widest-label</replaceable>} + \bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key}</replaceable> + ... +\end{thebibliography} +</screen> +<para>Produce a bibliography or reference list. There are two ways to produce +bibliographic lists. This environment is suitable when you have only a +few references and can maintain the list by hand. See <link linkend="Using-BibTeX">Using BibTeX</link> +for a more sophisticated approach. +</para> +<para>This shows the environment with two entries. +</para> +<screen>This work is based on \cite{latexdps}. +Together they are \cite{latexdps, texbook}. + ... +\begin{thebibliography}{9} +\bibitem{latexdps} + Leslie Lamport. + \textit{\LaTeX{}: a document preparation system}. + Addison-Wesley, Reading, Massachusetts, 1993. +\bibitem{texbook} + Donald Ervin Knuth. + \textit{The \TeX book}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end{thebibliography} +</screen> +<para>This styles the first reference as ‘<literal>[1] Leslie ...</literal>’, and so that +<literal>\cite{latexdps}</literal> produces the matching ‘<literal>... based on [1]</literal>’. +The second <literal>\cite</literal> produces ‘<literal>[1, 2]</literal>’. You must compile the +document twice to resolve these references. +</para> +<para>The mandatory argument <replaceable>widest-label</replaceable> is text that, when typeset, is +as wide as the widest item label produced by the <literal>\bibitem</literal> +commands. The tradition is to use <literal>9</literal> for bibliographies with less +than 10 references, <literal>99</literal> for ones with less than 100, etc. +</para> +<para>The bibliographic list is headed by a title such as ‘<literal>Bibliography</literal>’. +To change it there are two cases. In the <filename>book</filename> and <filename>report</filename> +classes, where the top level sectioning is <literal>\chapter</literal> and the +default title is ‘<literal>Bibliography</literal>’, that title is in the macro +<literal>\bibname</literal>. For <filename>article</filename>, where the class’s top level +sectioning is <literal>\section</literal> and the default is ‘<literal>References</literal>’, the +title is in macro <literal>\refname</literal>. Change it by redefining the command, +as with <literal>\renewcommand{\refname}{Cited references}</literal> after +<literal>\begin{document}</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<para>Language support packages such as <filename>babel</filename> will automatically +redefine <literal>\refname</literal> or <literal>\bibname</literal> to fit the selected +language. +</para> + + +<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>cite_key</replaceable>} +</screen> +<para>or +</para> +<screen>\bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key</replaceable>} +</screen> +<para>Generate an entry labeled by <replaceable>label</replaceable>. The default is for &latex; to +generates a number using the <literal>enumi</literal> counter. The <firstterm>citation key</firstterm> +<indexterm role="cp"><primary>citation key</primary></indexterm> +<replaceable>cite_key</replaceable> is a string of +letters, numbers, and punctuation symbols (but not comma). +</para> +<para>See <link linkend="thebibliography">thebibliography</link> for an example. +</para> +<para>The optional <replaceable>label</replaceable> changes the default label from an integer to the +given string. With this +</para> +<screen>\begin{thebibliography} +\bibitem[Lamport 1993]{latexdps} + Leslie Lamport. + \textit{\LaTeX{}: a document preparation system}. + Addison-Wesley, Reading, Massachusetts, 1993. +\bibitem{texbook} + Donald Ervin Knuth. + \textit{The \TeX book}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end{thebibliography} +</screen> +<para>the first entry will be styled as ‘<literal>[Lamport 1993] Leslie ...</literal>’ (The +amount of horizontal space that &latex; leaves for the label depends on +the <replaceable>widest-label</replaceable> argument of the <literal>thebibliography</literal> +environment; see <link linkend="thebibliography">thebibliography</link>.) Similarly, <literal>... based on +\cite{latexdps}</literal> will produce ‘<literal>... based on [Lamport 1994]</literal>’. +</para> +<para>If you mix <literal>\bibitem</literal> entries having a <replaceable>label</replaceable> with those that +do not then &latex; will number the unlabelled ones sequentially. In +the example above the <literal>texbook</literal> entry will appear as ‘<literal>[1] +Donald ...</literal>’, despite that it is the second entry. +</para> +<para>If you use the same <replaceable>cite_key</replaceable> twice then you get ‘<literal>LaTeX +Warning: There were multiply-defined labels</literal>’. +</para> +<para>Under the hood, &latex; remembers the <replaceable>cite_key</replaceable> and <replaceable>label</replaceable> +information because <literal>\bibitem</literal> writes it to the auxiliary file +<filename><replaceable>filename</replaceable>.aux</filename>. For instance, the above example causes +<literal>\bibcite{latexdps}{Lamport, 1993}</literal> and +<literal>\bibcite{texbook}{1}</literal> to appear in that file. The <filename>.aux</filename> +file is read by the <literal>\begin{document}</literal> command and then the +information is available for <literal>\cite</literal> commands. This explains why +you need to run &latex; twice to resolve references: once to write it +out and once to read it in. +</para> +<para>Because of this two-pass algorithm, when you add a <literal>\bibitem</literal> or +change its <replaceable>cite_key</replaceable> you may get ‘<literal>LaTeX Warning: Label(s) may +have changed. Rerun to get cross-references right</literal>’. Fix it by +recompiling. +</para> + +</sect2> +<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>keys</replaceable>} +</screen> +<para>or +</para> +<screen>\cite[<replaceable>subcite</replaceable>]{<replaceable>keys</replaceable>} +</screen> +<para>Generate as output a citation to the references associated with +<replaceable>keys</replaceable>. The mandatory <replaceable>keys</replaceable> is a citation key, or a +comma-separated list of citation keys (see <link linkend="_005cbibitem">\bibitem</link>). +</para> +<para>This +</para> +<screen>The ultimate source is \cite{texbook}. + ... +\begin{thebibliography} +\bibitem{texbook} + Donald Ervin Knuth. + \textit{The \TeX book}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end{thebibliography} +</screen> +<para>produces output like ‘<literal>... source is [1]</literal>’. (You can change the +appearance of the citation with bibliography styles. More is in +<link linkend="Using-BibTeX">Using BibTeX</link>.) +</para> +<para>The optional argument <replaceable>subcite</replaceable> is appended to the citation. For +example, <literal>See 14.3 in \cite[p.~314]{texbook}</literal> might produce +‘<literal>See 14.3 in [1, p. 314]</literal>’. +</para> +<para>In addition to what appears in the output, <literal>\cite</literal> writes +information to the auxiliary file <filename><replaceable>filename</replaceable>.aux</filename>. For +instance, <literal>\cite{latexdps}</literal> writes ‘<literal>\citation{latexdps}</literal>’ +to that file. This information is used by Bib&tex; to include in your +reference list only those works that you have actually cited; see +<link linkend="_005cnocite">\nocite</link> also. +</para> +<para>If <replaceable>keys</replaceable> is not in your bibliography information then you get +‘<literal>LaTeX Warning: There were undefined references</literal>’, and in the output +the citation shows as a boldface question mark between square brackets. +There are two possible causes. If you have mistyped something, as in +<literal>\cite{texbok}</literal> then you need to correct the spelling. On the +other hand, if you have just added or modified the bibliographic +information and so changed the <filename>.aux</filename> file (see <link linkend="_005cbibitem">\bibitem</link>) then +the fix may be to run &latex; again. +</para> + +</sect2> +<sect2 label="8.24.3" id="_005cnocite"> +<title><literal>\nocite</literal></title> + +<indexterm role="fn"><primary>\nocite</primary></indexterm> + +<para>Synopsis: +</para> +<screen><literal>\nocite{<replaceable>keys</replaceable>}</literal> +</screen> +<para>Produces no output but writes <replaceable>keys</replaceable> to the auxiliary file +<filename><replaceable>doc-filename</replaceable>.aux</filename>. +</para> +<para>The mandatory argument <replaceable>keys</replaceable> is a comma-separated list of one or +more citation keys (see <link linkend="_005cbibitem">\bibitem</link>). This information is used by +Bib&tex; to include these works in your reference list even though you +have not cited them (see <link linkend="_005ccite">\cite</link>). +</para> + +</sect2> +<sect2 label="8.24.4" id="Using-BibTeX"> +<title>Using Bib&tex;</title> + +<indexterm role="cp"><primary>using Bib&tex;</primary></indexterm> +<indexterm role="cp"><primary>bib&tex;, using</primary></indexterm> +<indexterm role="cp"><primary>bibliography, creating (automatically)</primary></indexterm> +<indexterm role="fn"><primary>\bibliographystyle</primary></indexterm> +<indexterm role="fn"><primary>\bibliography</primary></indexterm> + +<para>As described in <literal>thebibliography</literal> (see <link linkend="thebibliography">thebibliography</link>), a +sophisticated approach to managing bibliographies is provided by the +Bib&tex; program. This is only an introduction; see the full +documentation on CTAN. +</para> +<para>With Bib&tex;, you don’t use <literal>thebibliography</literal> +(see <link linkend="thebibliography">thebibliography</link>). Instead, include these lines. +</para> +<screen>\bibliographystyle{<replaceable>bibstyle</replaceable>} +\bibliography{<replaceable>bibfile1</replaceable>, <replaceable>bibfile2</replaceable>, ...} +</screen> +<para>The <replaceable>bibstyle</replaceable> refers to a file <filename><replaceable>bibstyle</replaceable>.bst</filename>, which +defines how your citations will look. The standard <replaceable>bibstyle</replaceable>’s +distributed with Bib&tex; are: +</para> +<variablelist><varlistentry><term><literal>alpha</literal> +</term><listitem><para>Labels are formed from name of author and year of publication. +The bibliographic items are sorted alphabetically. +</para></listitem></varlistentry><varlistentry><term><literal>plain</literal> +</term><listitem><para>Labels are integers. +Sort the bibliographic items alphabetically. +</para></listitem></varlistentry><varlistentry><term><literal>unsrt</literal> +</term><listitem><para>Like <literal>plain</literal>, but entries are in order of citation. +</para></listitem></varlistentry><varlistentry><term><literal>abbrv</literal> +</term><listitem><para>Like <literal>plain</literal>, but more compact labels. +</para></listitem></varlistentry></variablelist> +<para>Many, many other Bib&tex; style files exist, +tailored to the demands of various publications. See CTAN’s listing +<ulink url="http://mirror.ctan.org/biblio/bibtex/contrib">http://mirror.ctan.org/biblio/bibtex/contrib</ulink>. +</para> +<para>The <literal>\bibliography</literal> command is what actually produces the +bibliography. Its argument is a comma-separated list, referring to +files named <filename><replaceable>bibfile1</replaceable>.bib</filename>, <filename><replaceable>bibfile2</replaceable>.bib</filename>, +… These contain your database in Bib&tex; format. This shows a +typical couple of entries in that format. +</para> +<screen>@book{texbook, + title = {The {{\TeX}}book}, + author = {D.E. Knuth}, + isbn = {0201134489}, + series = {Computers \& typesetting}, + year = {1983}, + publisher = {Addison-Wesley} +} +@book{sexbook, + author = {W.H. Masters and V.E. Johnson}, + title = {Human Sexual Response}, + year = {1966}, + publisher = {Bantam Books} +} +</screen> +<para>Only the bibliographic entries referred to via <literal>\cite</literal> and +<literal>\nocite</literal> will be listed in the document’s bibliography. Thus you +can keep all your sources together in one file, or a small number of +files, and rely on Bib&tex; to include in this document only those that +you used. +</para> + +</sect2> +</sect1> +<sect1 label="8.25" id="theorem"> +<title><literal>theorem</literal></title> + +<indexterm role="fn"><primary>environment, <literal>theorem</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>theorem</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>theorems, typesetting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{theorem} + <replaceable>theorem body</replaceable> +\end{theorem} +</screen> +<para>Produces ‘<literal>Theorem <replaceable>n</replaceable></literal>’ in boldface followed by <replaceable>theorem +body</replaceable> in italics. The numbering possibilities for <replaceable>n</replaceable> are described under +<literal>\newtheorem</literal> (see <link linkend="_005cnewtheorem">\newtheorem</link>). +</para> +<screen>\newtheorem{lem}{Lemma} % in preamble +\newtheorem{thm}{Theorem} + ... +\begin{lem} % in document body + text of lemma +\end{lem} + +The next result follows immediately. +\begin{thm}[Gauss] % put `Gauss' in parens after theorem head + text of theorem +\end{thm} +</screen> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>amsthm</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsthm</literal> package</primary></indexterm> + +<para>Most new documents use the packages <literal>amsthm</literal> and <literal>amsmath</literal> +from the American Mathematical Society. Among other things these +packages include a large number of options for theorem environments, +such as styling options. +</para> + +</sect1> +<sect1 label="8.26" id="titlepage"> +<title><literal>titlepage</literal></title> + +<indexterm role="fn"><primary>environment, <literal>titlepage</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>titlepage</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>making a title page</primary></indexterm> +<indexterm role="cp"><primary>title pages, creating</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{titlepage} + ... text and spacing ... +\end{titlepage} +</screen> +<para>Create a title page, a page with no printed page number or heading and +with succeeding pages numbered starting with page one. +</para> +<para>In this example all formatting, including vertical spacing, is left to +the author. +</para> +<screen>\begin{titlepage} +\vspace*{\stretch{1}} +\begin{center} + {\huge\bfseries Thesis \\[1ex] + title} \\[6.5ex] + {\large\bfseries Author name} \\ + \vspace{4ex} + Thesis submitted to \\[5pt] + \textit{University name} \\[2cm] + in partial fulfilment for the award of the degree of \\[2cm] + \textsc{\Large Doctor of Philosophy} \\[2ex] + \textsc{\large Mathematics} \\[12ex] + \vfill + Department of Mathematics \\ + Address \\ + \vfill + \today +\end{center} +\vspace{\stretch{2}} +\end{titlepage} +</screen> +<para>To instead produce a standard title page without a <literal>titlepage</literal> +environment, use <literal>\maketitle</literal> (see <link linkend="_005cmaketitle">\maketitle</link>). +</para> + +</sect1> +<sect1 label="8.27" id="verbatim"> +<title><literal>verbatim</literal></title> + +<indexterm role="fn"><primary>environment, <literal>verbatim</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>verbatim</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>verbatim text</primary></indexterm> +<indexterm role="cp"><primary>simulating typed text</primary></indexterm> +<indexterm role="cp"><primary>typed text, simulating</primary></indexterm> +<indexterm role="cp"><primary>code, typesetting</primary></indexterm> +<indexterm role="cp"><primary>computer programs, typesetting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{verbatim} +<replaceable>literal-text</replaceable> +\end{verbatim} +</screen> +<para>A paragraph-making environment in which &latex; produces as output +exactly what you type as input. For instance inside <replaceable>literal-text</replaceable> +the backslash <literal>\</literal> character does not start commands, it +produces a printed ‘<literal>\</literal>’, and carriage returns and blanks are taken +literally. The output appears in a monospaced typewriter-like font +(<literal>\tt</literal>). +</para> +<screen>\begin{verbatim} +Symbol swearing: %&$#?!. +\end{verbatim} +</screen> +<para>The only restriction on <literal>literal-text</literal> is that it cannot include +the string <literal>\end{verbatim}</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>cprotect</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>cprotect</literal> package</primary></indexterm> + +<para>You cannot use the verbatim environment in the argument to macros, for +instance in the argument to a <literal>\section</literal>. This is not the same as +commands being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot appear +there. (But the <literal>cprotect</literal> package can help with this.) +</para> +<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm> + +<para>One common use of verbatim input is to typeset computer code. There are +packages that are an improvement the <literal>verbatim</literal> environment. For +instance, one improvement is to allow the verbatim inclusion of external +files, or parts of those files. Such packages include <literal>listings</literal>, +and <literal>minted</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>verbatimbox</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>verbatimbox</literal> package</primary></indexterm> + +<para>A package that provides many more options for verbatim environments is +<literal>fancyvrb</literal>. Another is <literal>verbatimbox</literal>. +</para> +<para>For a list of all the relevant packages, see CTAN. +</para> + + +<sect2 label="8.27.1" id="_005cverb"> +<title><literal>\verb</literal></title> + +<indexterm role="fn"><primary>\verb</primary></indexterm> +<indexterm role="cp"><primary>verbatim text, inline</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\verb <replaceable>char</replaceable> <replaceable>literal-text</replaceable> <replaceable>char</replaceable> +\verb* <replaceable>char</replaceable> <replaceable>literal-text</replaceable> <replaceable>char</replaceable> +</screen> +<para>Typeset <replaceable>literal-text</replaceable> as it is input, including special characters +and spaces, using the typewriter (<literal>\tt</literal>) font. +</para> +<para>This example shows two different invocations of <literal>\verb</literal>. +</para> +<screen>This is \verb!literally! the biggest pumpkin ever. +And this is the best squash, \verb+literally!+ +</screen> +<para>The first <literal>\verb</literal> has its <replaceable>literal-text</replaceable> surrounded with +exclamation point, <literal>!</literal>. The second instead uses plus, <literal>+</literal>, +because the exclamation point is part of <literal>literal-text</literal>. +</para> +<para>The single-character delimiter <replaceable>char</replaceable> surrounds +<replaceable>literal-text</replaceable> — it must be the same character before and +after. No spaces come between <literal>\verb</literal> or <literal>\verb*</literal> and +<replaceable>char</replaceable>, or between <replaceable>char</replaceable> and <replaceable>literal-text</replaceable>, or between +<replaceable>literal-text</replaceable> and the second occurrence of <replaceable>char</replaceable> (the synopsis +shows a space only to distinguish one component from the other). The +delimiter must not appear in <replaceable>literal-text</replaceable>. The <replaceable>literal-text</replaceable> +cannot include a line break. +</para> +<indexterm role="cp"><primary>visible space</primary></indexterm> +<para>The <literal>*</literal>-form differs only in that spaces are printed with a visible +space character. +</para> +<para>The output from this will include a character showing the spaces. +</para> +<screen>The commands's first argument is \verb*!filename with extension! and ... +</screen> +<indexterm role="cp"><primary>package, <literal>url</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>url</literal> package</primary></indexterm> + +<para>For typesetting Internet addresses, urls, the package <literal>url</literal> +provides an option that is better than the <literal>\verb</literal> command, since +it allows line breaks. +</para> +<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm> + +<para>For computer code there are many packages with advantages over +<literal>\verb</literal>. One is <filename>listings</filename>, another is <filename>minted</filename>. +</para> +<indexterm role="cp"><primary>package, <literal>cprotect</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>cprotect</literal> package</primary></indexterm> + +<para>You cannot use <literal>\verb</literal> in the argument to a macro, for instance in +the argument to a <literal>\section</literal>. It is not a question of <literal>\verb</literal> +being fragile (see <link linkend="_005cprotect">\protect</link>), instead it just cannot appear there. +(But the <literal>cprotect</literal> package can help with this.) +</para> + +</sect2> +</sect1> +<sect1 label="8.28" id="verse"> +<title><literal>verse</literal></title> + +<indexterm role="fn"><primary>environment, <literal>verse</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>verse</literal> environment</primary></indexterm> + +<indexterm role="cp"><primary>poetry, an environment for</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{verse} + <replaceable>line1</replaceable> \\ + <replaceable>line2</replaceable> \\ + ... +\end{verse} +</screen> +<para>An environment for poetry. +</para> +<para>Here are two lines from Shakespeare’s Romeo and Juliet. +</para> +<screen>Then plainly know my heart's dear love is set \\ +On the fair daughter of rich Capulet. +</screen> +<indexterm role="fn"><primary>\\ for <literal>verse</literal></primary></indexterm> +<para>Separate the lines of each stanza with <literal>\\</literal>, and use one or more +blank lines to separate the stanzas. +</para> +<screen>\begin{verse} +\makebox[\linewidth][c]{\textit{Shut Not Your Doors} ---Walt Whitman} + \\[1\baselineskip] +Shut not your doors to me proud libraries, \\ +For that which was lacking on all your well-fill'd shelves, \\ +\qquad yet needed most, I bring, \\ +Forth from the war emerging, a book I have made, \\ +The words of my book nothing, the drift of it every thing, \\ +A book separate, not link'd with the rest nor felt by the intellect, \\ +But you ye untold latencies will thrill to every page. +\end{verse} +</screen> +<para>The output has margins indented on the left and the right, paragraphs +are not indented, and the text is not right-justified. +</para> + +</sect1> +</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> + +<para>The first thing &latex; does when processing ordinary text is to +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 in the text body for +you but in some environments you manually force line breaks. +</para> +<para>A common workflow is to get a final version of the document content +before taking a final pass through and considering line breaks (and page +breaks). This differs from word processing, where you are formatting +text as you input it. Putting these off until the end prevents a lot of +fiddling with breaks that will change anyway. +</para> + + +<sect1 label="9.1" id="_005c_005c"> +<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>Synopsis, one of: +</para> +<screen>\\ +\\[<replaceable>morespace</replaceable>] +</screen> +<para>or one of: +</para> +<screen>\\* +\\*[<replaceable>morespace</replaceable>] +</screen> +<para>End the current line. The optional argument <replaceable>morespace</replaceable> specifies +extra vertical space to be inserted before the next line. This is a +rubber length (see <link linkend="Lengths">Lengths</link>) and can be negative. The text before +the line break is set at its normal length, that is, it is not stretched +to fill out the line width. This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>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> +<para>Explicit line breaks in the main text body are unusual in &latex;. In +particular, don’t start new paragraphs with <literal>\\</literal>. Instead leave a +blank line between the two paragraphs. And don’t put in a sequence of +<literal>\\</literal>’s to make vertical space. Instead use +<literal>\vspace{<replaceable>length</replaceable>}</literal>, or +<literal>\leavevmode\vspace{<replaceable>length</replaceable>}</literal>, or +<literal>\vspace*{<replaceable>length</replaceable>}</literal> if you want the space to not be thrown +out at the top of a new page (see <link linkend="_005cvspace">\vspace</link>). +</para> +<para>The <literal>\\</literal> command is mostly used outside of the main flow of text +such as in a <literal>tabular</literal> or <literal>array</literal> environment or in an +equation environment. +</para> +<para>The <literal>\\</literal> command is a synonym for <literal>\newline</literal> +(see <link linkend="_005cnewline">\newline</link>) under ordinary circumstances (an example of an +exception is the <literal>p{...}</literal> column in a <literal>tabular</literal> +environment; see <link linkend="tabular">tabular</link>). +</para> +<!-- credit: David Carlisle https://tex.stackexchange.com/a/82666 --> +<para>The <literal>\\</literal> command is a macro, and its definition changes by context +so that its definition in normal text, a <literal>center</literal> environment, a +<literal>flushleft</literal> environment, and a <literal>tabular</literal> are all different. +In normal text when it forces a linebreak it is essentially a shorthand +for <literal>\newline</literal>. It does not end horizontal mode or end the +paragraph, it just inserts some glue and penalties so that when the +paragraph does end a linebreak will occur at that point, with the short +line padded with white space. +</para> +<para>You get ‘<literal>LaTeX Error: There's no line here to end</literal>’ if you use +<literal>\\</literal> to ask for a new line, rather than to end the current line. +An example is if you have <literal>\begin{document}\\</literal> or, more likely, +something like this. +</para> +<screen>\begin{center} + \begin{minipage}{0.5\textwidth} + \\ + In that vertical space put your mark. + \end{minipage} +\end{center} +</screen> +<para>Fix it by replacing the double backslash with something like +<literal>\vspace{\baselineskip}</literal>. +</para> + +</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> + +<para>The <literal>\obeycr</literal> command makes a return in the input file (‘<literal>^^M</literal>’, +internally) the same as <literal>\\</literal>, followed by <literal>\relax</literal>. So each +new line in the input will also be a new line in the output. The +<literal>\restorecr</literal> command restores normal line-breaking behavior. +</para> +<para>This is not the way to show verbatim text or computer code. +See <link linkend="verbatim">verbatim</link> instead. +</para> +<para>With &latex;’s usual defaults, this +</para> +<screen>aaa +bbb + +\obeycr +ccc +ddd + eee + +\restorecr +fff +ggg + +hhh +iii +</screen> +<para>produces output like this. +</para> +<screen> aaa bbb + ccc +ddd +eee + +fff ggg + hhh iii +</screen> +<para>The indents are paragraph indents. +</para> + +</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>In ordinary text, this ends a line in a way that does not right-justify +the line, so the prior text is not stretched. That is, in paragraph mode +(see <link linkend="Modes">Modes</link>), the <literal>\newline</literal> command is equivalent to +double-backslash (see <link linkend="_005c_005c">\\</link>). This command is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>However, the two commands are different inside a <literal>tabular</literal> or +<literal>array</literal> environment. In a column with a specifier producing a +paragraph box such as typically <literal>p{...}</literal>, <literal>\newline</literal> will +insert a line end inside of the column; that is, it does not break the +entire tabular 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> + +<para>Tell &latex; that it may hyphenate the word at that point. When you +insert <literal>\-</literal> commands in a word, the word will only be hyphenated at +those points and not at any of the hyphenation points that &latex; +might otherwise have chosen. This command is robust (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>&latex; is good at hyphenating and usually finds most of the correct +hyphenation points, while almost never using an incorrect one. The +<literal>\-</literal> command is for exceptional cases. +</para> +<para>For example, &latex; does not ordinarily hyphenate words containing a +hyphen. Below, the long and hyphenated word means &latex; has to put +in unacceptably large spaces to set the narrow column. +</para> +<screen>\begin{tabular}{rp{1.75in}} + Isaac Asimov &The strain of + anti-intellectualism + % an\-ti-in\-tel\-lec\-tu\-al\-ism + has been a constant thread winding its way through our + political and cultural life, nurtured by + the false notion that democracy means that + `my ignorance is just as good as your knowledge'. +\end{tabular} +</screen> +<para>Commenting out the third line and uncommenting the fourth makes a much +better fit. +</para> +<para>The <literal>\-</literal> command only allows &latex; to break there, it does not +require that it break there. You can insist on a split with something +like <literal>Hef-\linebreak feron</literal>. Of course, if you later change the +text then this forced break may look very odd, so this approach requires +care. +</para> + +</sect1> +<sect1 label="9.5" id="_005cdiscretionary"> +<title><literal>\discretionary</literal> (generalized hyphenation point)</title> +<indexterm role="cp"><primary>hyphenation, discretionary</primary></indexterm> +<indexterm role="cp"><primary>discretionary hyphenation</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\discretionary{<replaceable>pre-break</replaceable>}{<replaceable>post-break</replaceable>}{<replaceable>no-break</replaceable>} +</screen> +<para>Handle word changes around hyphens. This command is not often used in +&latex; documents. +</para> +<para>If a line break occurs at the point where <literal>\discretionary</literal> appears +then &tex; puts <replaceable>pre-break</replaceable> at the end of the current line and puts +<replaceable>post-break</replaceable> at the start of the next line. If there is no line +break here then &tex; puts <replaceable>no-break</replaceable> +</para> +<para>In ‘<literal>difficult</literal>’ the three letters <literal>ffi</literal> form a ligature. But +&tex; can nonetheless break between the two f’s with this. +</para> +<screen>di\discretionary{f-}{fi}{ffi}cult +</screen> +<para>Note that users do not have to do this. It is typically handled +automatically by &tex;’s hyphenation algorithm. +</para> + +</sect1> +<sect1 label="9.6" id="_005cfussy-_0026-_005csloppy"> +<title><literal>\fussy</literal> & <literal>\sloppy</literal></title> + +<indexterm role="fn"><primary>\fussy</primary></indexterm> +<indexterm role="fn"><primary>\sloppy</primary></indexterm> +<indexterm role="cp"><primary>line breaks, changing</primary></indexterm> + +<para>Declarations to make &tex; more picky or less picky about line +breaking. Declaring <literal>\fussy</literal> usually avoids too much space between +words, at the cost of an occasional overfull box. Conversely, +<literal>\sloppy</literal> avoids overfull boxes while suffering loose interword +spacing. +</para> +<para>The default is <literal>\fussy</literal>. Line breaking in a paragraph is +controlled by whichever declaration is current at the blank line, or +<literal>\par</literal>, or displayed equation ending that paragraph. So to affect +the line breaks, include that paragraph-ending material in the scope of +the command. +</para> + + +<sect2 label="9.6.1" id="sloppypar"> +<title><literal>sloppypar</literal></title> + +<indexterm role="fn"><primary>sloppypar</primary></indexterm> +<indexterm role="cp"><primary>sloppypar environment</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{sloppypar} + ... paragraphs ... +\end{sloppypar} +</screen> +<para>Typeset the paragraphs with <literal>\sloppy</literal> in effect (see <link linkend="_005cfussy-_0026-_005csloppy">\fussy & +\sloppy</link>). Use this to locally adjust line breaking, to avoid +‘<literal>Overfull box</literal>’ or ‘<literal>Underfull box</literal>’ errors. +</para> +<para>The example is simple. +</para> +<screen>\begin{sloppypar} + Her plan for the morning thus settled, she sat quietly down to her + book after breakfast, resolving to remain in the same place and the + same employment till the clock struck one; and from habitude very + little incommoded by the remarks and ejaculations of Mrs.\ Allen, + whose vacancy of mind and incapacity for thinking were such, that + as she never talked a great deal, so she could never be entirely + silent; and, therefore, while she sat at her work, if she lost her + needle or broke her thread, if she heard a carriage in the street, + or saw a speck upon her gown, she must observe it aloud, whether + there were anyone at leisure to answer her or not. +\end{sloppypar} +</screen> + +</sect2> +</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> + +<para>Synopsis: +</para> +<screen>\hyphenation{<replaceable>word1</replaceable> ...} +</screen> +<para>Declares allowed hyphenation points within the words in the list. The +words in that list are separated by spaces. Show permitted points for +hyphenation with a dash character, <literal>-</literal>. +</para> +<para>Here is an example: +</para> +<screen>\hyphenation{hat-er il-lit-e-ra-ti tru-th-i-ness} +</screen> +<para>Use lowercase letters. &tex; will only hyphenate if the word matches +exactly. Multiple <literal>\hyphenation</literal> commands accumulate. +</para> + +</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> +<indexterm role="cp"><primary>line breaks, preventing</primary></indexterm> + +<para>Synopses, one of: +</para> +<screen>\linebreak +\linebreak[<replaceable>zero-to-four</replaceable>] +</screen> +<para>or one of these. +</para> +<screen>\nolinebreak +\nolinebreak[<replaceable>zero-to-four</replaceable>] +</screen> +<para>Encourage or discourage a line break. The optional <replaceable>zero-to-four</replaceable> +is an integer that allows you to soften the instruction. The default is +4, so that without the optional argument these commands entirely force +or prevent the break. But for instance, <literal>\nolinebreak[1]</literal> is a +suggestion that another place may be better. The higher the number, the +more insistent the request. Both commands are fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Here we tell &latex; that a good place to put a linebreak is after the +standard legal text. +</para> +<screen>\boilerplatelegal{} \linebreak[2] +We especially encourage applications from members of traditionally +underrepresented groups. +</screen> +<para>When you issue <literal>\linebreak</literal>, the spaces in the line are stretched +out so that it extends to the right margin. See <link linkend="_005c_005c">\\</link> +and <link linkend="_005cnewline">\newline</link> to have the spaces not stretched out. +</para> + + +</sect1> +</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> + +<para>Ordinarily &latex; automatically takes care of breaking output into +pages with its usual aplomb. But if you are writing commands, or +tweaking the final version of a document, then you may need to +understand how to influence its actions. +</para> +<!-- credit: H Vogt https://tex.stackexchange.com/a/115563 --> +<para>&latex;’s algorithm for splitting a document into pages is more complex +than just waiting until there is enough material to fill a page and +outputting the result. Instead, &latex; typesets more material than +would fit on the page and then chooses a break that is optimal in some +way (it has the smallest badness). An example of the advantage of this +approach is that if the page has some vertical space that can be +stretched or shrunk, such as with rubber lengths between paragraphs, +then &latex; can use that to avoid widow lines (where a new page starts +with the last line of a paragraph; &latex; can squeeze the extra line +onto the first page) and orphans (where the first line of paragraph is +at the end of a page; &latex; can stretch the material of the first +page so the extra line falls on the second page). Another example is +where &latex; uses available vertical shrinkage to fit on a page not +just the header for a new section but also the first two lines of that +section. +</para> +<para>But &latex; does not optimize over the entire document’s set of page +breaks. So it can happen that the first page break is great but the +second one is lousy; to break the current page &latex; doesn’t look as +far ahead as the next page break. So occasionally you may want to +influence page breaks while preparing a final version of a document. +</para> +<para>See <link linkend="Layout">Layout</link> for more material that is relevant to page breaking. +</para> + + +<sect1 label="10.1" id="_005cclearpage-_0026-_005ccleardoublepage"> +<title><literal>\clearpage</literal> & <literal>\cleardoublepage</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> +<indexterm role="fn"><primary>\cleardoublepage</primary></indexterm> +<indexterm role="cp"><primary>starting on a right-hand page</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\clearpage +</screen> +<para>or +</para> +<screen>\cleardoublepage +</screen> +<para>End the current page and output all of the pending floating figures and +tables (see <link linkend="Floats">Floats</link>). If there are too many floats to fit on the +page then &latex; will put in extra pages containing only floats. In +two-sided printing, <literal>\cleardoublepage</literal> also makes the next page of +content a right-hand page, an odd-numbered page, if necessary inserting +a blank page. The <literal>\clearpage</literal> command is robust while +<literal>\cleardoublepage</literal> is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>&latex;’s page breaks are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. +</para> +<!-- credit: https://www.tex.ac.uk/FAQ-reallyblank.html --> +<para>The <literal>\cleardoublepage</literal> command will put in a blank page, but it +will have the running headers and footers. To get a really blank +page, use this command. +</para> +<screen>\let\origdoublepage\cleardoublepage +\newcommand{\clearemptydoublepage}{% + \clearpage + {\pagestyle{empty}\origdoublepage}% +} +</screen> +<para>If you want &latex;’s standard <literal>\chapter</literal> command to do this then +add the line <literal>\let\cleardoublepage\clearemptydoublepage</literal>. +</para> +<para>The command <literal>\newpage</literal> (see <link linkend="_005cnewpage">\newpage</link>) also ends the current +page, but without clearing pending floats. And, if &latex; is in +two-column mode then <literal>\newpage</literal> ends the current column while +<literal>\clearpage</literal> and <literal>\cleardoublepage</literal> end the current page. +</para> + + +</sect1> +<sect1 label="10.2" 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>Synopsis: +</para> +<screen>\newpage +</screen> +<para>End the current page. This command is robust (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>&latex;’s page breaks are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. +</para> +<para>While the commands <literal>\clearpage</literal> and <literal>\cleardoublepage</literal> also +end the current page, in addition they clear pending floats +(see <link linkend="_005cclearpage-_0026-_005ccleardoublepage">\clearpage & \cleardoublepage</link>). And, if &latex; is in +two-column mode then <literal>\clearpage</literal> and <literal>\cleardoublepage</literal> end +the current page, possibly leaving an empty column, while +<literal>\newpage</literal> only ends the current column. +</para> +<para>In contrast with <literal>\pagebreak</literal> (see <link linkend="_005cpagebreak-_0026-_005cnopagebreak">\pagebreak & \nopagebreak</link>), +the <literal>\newpage</literal> command will cause the new page to start right where +requested. This +</para> +<screen>Four score and seven years ago our fathers brought forth on this +continent, +\newpage +\noindent a new nation, conceived in Liberty, and dedicated to the +proposition that all men are created equal. +</screen> +<para>makes a new page start after ‘<literal>continent,</literal>’ and the cut-off line is +not right justified. In addition, <literal>\newpage</literal> does not vertically +stretch out the page, as <literal>\pagebreak</literal> does. +</para> + +</sect1> +<sect1 label="10.3" id="_005cenlargethispage"> +<title><literal>\enlargethispage</literal></title> + +<indexterm role="fn"><primary>\enlargethispage</primary></indexterm> +<indexterm role="cp"><primary>enlarge current page</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\enlargethispage{size} +\enlargethispage*{size} +</screen> +<para>Enlarge the <literal>\textheight</literal> for the current page. The required +argument <replaceable>size</replaceable> must be a rigid length (see <link linkend="Lengths">Lengths</link>). It may be +positive or negative. This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>A common strategy is to wait until you have the final text of a +document, and then pass through it tweaking line and page breaks. This +command allows you some page size leeway. +</para> +<para>This will allow one extra line on the current page. +</para> +<screen>\enlargethispage{\baselineskip} +</screen> +<para>The starred form <literal>\enlargesthispage*</literal> tries to squeeze the material +together on the page as much as possible, for the common use case of +getting one more line on the page. This is often used together with an +explicit <literal>\pagebreak</literal>. +</para> + +</sect1> +<sect1 label="10.4" 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> +<indexterm role="cp"><primary>page break, preventing</primary></indexterm> + +<para>Synopses: +</para> +<screen>\pagebreak +\pagebreak[<replaceable>zero-to-four</replaceable>] +</screen> +<para>or +</para> +<screen>\nopagebreak +\nopagebreak[<replaceable>zero-to-four</replaceable>] +</screen> +<para>Encourage or discourage a page break. The optional <replaceable>zero-to-four</replaceable> +is an integer that allows you to soften the request. The default is 4, +so that without the optional argument these commands entirely force or +prevent the break. But for instance <literal>\nopagebreak[1]</literal> suggests to +&latex; that another spot might be preferable. The higher the number, +the more insistent the request. Both commands are fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>&latex;’s page endings are optimized so ordinarily you only use this +command in a document body to polish the final version, or inside +commands. +</para> +<para>If you use these inside a paragraph, they apply to the point following +the line in which they appear. So this +</para> +<screen>Four score and seven years ago our fathers brought forth on this +continent, +\pagebreak +a new nation, conceived in Liberty, and dedicated to the proposition +that all men are created equal. +</screen> +<para>does not give a page break at ‘<literal>continent,</literal>’ but instead at +‘<literal>nation,</literal>’ since that is where &latex; breaks that line. In +addition, with <literal>\pagebreak</literal> the vertical space on the page is +stretched out where possible so that it extends to the normal bottom +margin. This can look strange, and if <literal>\flushbottom</literal> is in effect +this can cause you to get ‘<literal>Underfull \vbox (badness 10000) has +occurred while \output is active</literal>’. See <link linkend="_005cnewpage">\newpage</link> for a command that +does not have these effects. +</para> + +</sect1> +</chapter> +<chapter label="11" id="Footnotes"> +<title>Footnotes</title> + +<indexterm role="cp"><primary>footnotes, creating</primary></indexterm> + +<para>Place a 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 put multiple footnotes on a page. If the footnote text becomes +too long then 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 (see <link linkend="Using-BibTeX">Using BibTeX</link>). +</para> + + +<sect1 label="11.1" id="_005cfootnote"> +<title><literal>\footnote</literal></title> + +<indexterm role="fn"><primary>\footnote</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\footnote{<replaceable>text</replaceable>} +\footnote[<replaceable>number</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Place a footnote <replaceable>text</replaceable> at the bottom of the current page. +</para> +<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 number of +the footnote. If you use this then &latex; does not increment the +<literal>footnote</literal> counter. +</para> +<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>By default, &latex; uses arabic numbers as footnote markers. Change +this 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>. +</para> +<para>&latex; determines the spacing of footnotes with two parameters. +</para> +<indexterm role="cp"><primary>footnote parameters</primary></indexterm> +<indexterm role="cp"><primary>parameters, for footnotes</primary></indexterm> + +<variablelist><varlistentry><term><indexterm role="fn"><primary>\footnoterule</primary></indexterm><literal>\footnoterule</literal> +</term><listitem><anchor id="footnote-footnoterule"/><para>Produces the rule separating the main text on a page from the page’s +footnotes. Default dimensions in the standard document classes (except +<literal>slides</literal>, where it does not appear) is: vertical thickness of +<literal>0.4pt</literal>, and horizontal size of <literal>0.4\columnwidth</literal> long. +Change the rule with something like this. +</para> +<!-- Credit egreg: https://tex.stackexchange.com/a/21917 --> +<screen>\renewcommand{\footnoterule}{% Kerns avoid vertical space + \kern -3pt % This -3 is negative + \hrule width \textwidth height 1pt % of the sum of this 1 + \kern 2pt} % and this 2 +</screen> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\footnotesep</primary></indexterm><literal>\footnotesep</literal> +</term><listitem><anchor id="footnote-footnotesep"/><para>The height of the strut placed at the beginning of the footnote +(see <link linkend="_005cstrut">\strut</link>). By default, this is set to the normal strut for +<literal>\footnotesize</literal> fonts (see <link linkend="Font-sizes">Font sizes</link>), therefore there is no +extra space between footnotes. This is ‘<literal>6.65pt</literal>’ for ‘<literal>10pt</literal>’, +‘<literal>7.7pt</literal>’ for ‘<literal>11pt</literal>’, and ‘<literal>8.4pt</literal>’ for ‘<literal>12pt</literal>’. Change +it as with <literal>\setlength{\footnotesep}{11pt}</literal>. +</para> +</listitem></varlistentry></variablelist> +<para>The <literal>\footnote</literal> command is fragile (see <link linkend="_005cprotect">\protect</link>). +</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; see <link linkend="Modes">Modes</link>). There are some workarounds; see +following sections. +</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> and <link linkend="Footnotes-in-a-table">Footnotes in a table</link>. +</para> + +</sect1> +<sect1 label="11.2" id="_005cfootnotemark"> +<title><literal>\footnotemark</literal></title> + +<indexterm role="fn"><primary>\footnotemark</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\footnotemark +\footnotemark[<replaceable>number</replaceable>] +</screen> +<para>Put the current footnote mark in the text. To specify associated text +for the footnote see <link linkend="_005cfootnotetext">\footnotetext</link>. The optional argument +<replaceable>number</replaceable> causes the command to use that number to determine the +footnote mark. This command can be used in inner paragraph mode +(see <link linkend="Modes">Modes</link>). +</para> +<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. The next example 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>If there are intervening footnotes then you must remember the value of the +common mark. This example gives the same institutional affiliation to +both the first and third authors (<literal>\thanks</literal> is a version of +<literal>footnote</literal>), by-hand giving the number of the footnote. +</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>This uses a counter to remember the footnote number. The third sentence +is followed by the same footnote marker as the first. +</para> +<screen>\newcounter{footnoteValueSaver} +All babies are illogical.\footnote{% + Lewis Carroll.}\setcounter{footnoteValueSaver}{\value{footnote}} +Nobody is despised who can manage a crocodile.\footnote{% + Captain Hook.} +Illogical persons are despised.\footnotemark[\value{footnoteValueSaver}] +Therefore, anyone who can manage a crocodile is not a baby. +</screen> +<indexterm role="cp"><primary>package, <literal>cleveref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>cleveref</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm> + +<para>This example accomplishes the same by using the package <filename>cleveref</filename>. +</para> +<!-- from SE user Jake http://tex.stackexchange.com/a/10116/339 --> +<screen>\usepackage{cleveref}[2012/02/15] % in preamble +\crefformat{footnote}{#2\footnotemark[#1]#3} +... +The theorem is from Evers.\footnote{\label{fn:TE}Tinker, Evers, 1994.} +The corollary is from Chance.\footnote{Evers, Chance, 1990.} +But the key lemma is from Tinker.\cref{fn:TE} +</screen> +<indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm> + +<para>It will work with the package <filename>hyperref</filename>. +</para> + +</sect1> +<sect1 label="11.3" id="_005cfootnotetext"> +<title><literal>\footnotetext</literal></title> + +<indexterm role="fn"><primary>\footnotetext</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\footnotetext{<replaceable>text</replaceable>} +\footnotetext[<replaceable>number</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Place <replaceable>text</replaceable> at the bottom of the page as a footnote. It pairs with +<literal>\footnotemark</literal> (see <link linkend="_005cfootnotemark">\footnotemark</link>) and can come anywhere after +that command, but must appear in outer paragraph mode (see <link linkend="Modes">Modes</link>). +The optional argument <replaceable>number</replaceable> changes the number of the footnote +mark. +</para> +<para>See <link linkend="_005cfootnotemark">\footnotemark</link> and <link linkend="Footnotes-in-a-table">Footnotes in a table</link> for usage +examples. +</para> + +</sect1> +<sect1 label="11.4" id="Footnotes-in-section-headings"> +<title>Footnotes in section headings</title> + +<indexterm role="cp"><primary>footnote, in section headings</primary></indexterm> +<indexterm role="cp"><primary>table of contents, avoiding footnotes</primary></indexterm> + +<para>Putting a footnote in a section heading, as in: +</para> +<screen>\section{Full sets\protect\footnote{This material due to ...}} +</screen> +<para>causes the footnote to appear at the bottom of the page where the +section starts, as usual, but also at the bottom of the table of +contents, where it is not likely to be desired. The simplest way +to have it not appear on the table of contents is to use the optional +argument to <literal>\section</literal> +</para> +<screen>\section[Please]{Please\footnote{% + Don't footnote in chapter and section headers!}} +</screen> +<para>No <literal>\protect</literal> is needed in front of <literal>\footnote</literal> here because +what gets moved to the table of contents is the optional argument. +</para> + +</sect1> +<sect1 label="11.5" id="Footnotes-in-a-table"> +<title>Footnotes in a table</title> + +<indexterm role="cp"><primary>footnote, in a table</primary></indexterm> + +<para>Inside a <literal>tabular</literal> or <literal>array</literal> environment the <literal>\footnote</literal> +command does not work; there is a footnote mark in the table cell but +the footnote text does not appear. The solution is to use a +<literal>minipage</literal> environment as here (see <link linkend="minipage">minipage</link>). +</para> +<screen>\begin{center} + \begin{minipage}{\textwidth} \centering + \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{minipage} +\end{center} +</screen> +<para>Inside a <literal>minipage</literal>, footnote marks are lowercase letters. Change +that with something like +<literal>\renewcommand{\thempfootnote}{\arabic{mpfootnote}}</literal> +(see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>). +</para> +<para>The footnotes in the prior example appear at the bottom of the +<literal>minipage</literal>. To have them appear at the bottom of the main page, as +part of the regular footnote sequence, use the <literal>\footnotemark</literal> and +<literal>\footnotetext</literal> pair and make a new counter. +</para> +<screen>\newcounter{mpFootnoteValueSaver} +\begin{center} + \begin{minipage}{\textwidth} + \setcounter{mpFootnoteValueSaver}{\value{footnote}} \centering + \begin{tabular}{l|l} + \textsc{Woman} &\textsc{Relationship} \\ \hline + Mona &Attached\footnotemark \\ + Diana Villiers &Eventual wife \\ + Christine Hatherleigh Wood &Fiance\footnotemark + \end{tabular} + \end{minipage}% percent sign keeps footnote text close to minipage + \stepcounter{mpFootnoteValueSaver}% + \footnotetext[\value{mpFootnoteValueSaver}]{% + Little is known other than her death.}% + \stepcounter{mpFootnoteValueSaver}% + \footnotetext[\value{mpFootnoteValueSaver}]{% + Relationship is unresolved in XXI.} +\end{center} +</screen> +<para>For a floating <literal>table</literal> environment (see <link linkend="table">table</link>), use the +<filename>tablefootnote</filename> package. +</para> +<screen>\usepackage{tablefootnote} % in preamble + ... +\begin{table} + \centering + \begin{tabular}{l|l} + \textsc{Date} &\textsc{Campaign} \\ \hline + 1862 &Fort Donelson \\ + 1863 &Vicksburg \\ + 1865 &Army of Northern Virginia\tablefootnote{% + Ending the war.} + \end{tabular} + \caption{Forces captured by US Grant} +\end{table} +</screen> +<para>The footnote appears at the page bottom and is numbered in sequence with +other footnotes. +</para> + +</sect1> +<sect1 label="11.6" id="Footnotes-of-footnotes"> +<title>Footnotes of footnotes</title> + +<indexterm role="cp"><primary>footnote, of a footnote</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>bigfoot</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>bigfoot</literal> package</primary></indexterm> + +<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} % in preamble +\DeclareNewFootnote{Default} +\DeclareNewFootnote{from}[alph] % create class \footnotefrom{} + ... +The third theorem is a partial converse of the +second.\footnotefrom{% + First noted in Wilson.\footnote{Second edition only.}} +</screen> + +</sect1> +</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. +</para> + + +<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>Synopses, one of: +</para> +<screen>\newcommand{\<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>} +\newcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\newcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\newcommand*{\<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>} +\newcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\newcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +</screen> +<para>or one of these. +</para> +<screen>\renewcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand*{\<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>} +\renewcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +</screen> +<para>Define or redefine a command. See also the discussion of +<literal>\DeclareRobustCommand</literal> in <link linkend="Class-and-package-commands">Class and package commands</link>. +<indexterm role="cp"><primary>starred form, defining new commands</primary></indexterm> +<indexterm role="cp"><primary>*-form, defining new commands</primary></indexterm> +The starred form of these two requires that the arguments not contain +multiple paragraphs of text (in plain &tex; terms that it not be +<literal>\long</literal>). +</para> +<para>These are the parameters: +</para> +<variablelist><varlistentry><term><replaceable>cmd</replaceable> +</term><listitem> +<para>Required; the command name. It must begin with a backslash, <literal>\</literal>, +and must not begin with the four letter string <literal>\end</literal>. For +<literal>\newcommand</literal>, it must not be already defined. For +<literal>\renewcommand</literal>, this name must already be defined. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>nargs</replaceable> +</term><listitem><para>Optional; an integer from 0 to 9, specifying the number of arguments +that the command takes, including any optional argument. Omitting this +argument is the same as specifying 0, meaning that the command has no +arguments. If you redefine 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 +<literal>\<replaceable>cmd</replaceable></literal> is optional, with default value <replaceable>optargdefault</replaceable> +(which may be the empty string). If this argument is not present then +<literal>\<replaceable>cmd</replaceable></literal> does not take an optional argument. +</para> +<indexterm role="cp"><primary>positional parameter</primary></indexterm> +<para>That is, if <literal>\<replaceable>cmd</replaceable></literal> is used with square brackets, as in +<literal>\<replaceable>cmd</replaceable>[<replaceable>optval</replaceable>]{...}...</literal>, then within <replaceable>defn</replaceable> the +parameter <literal>#1</literal> is set to the value of <replaceable>optval</replaceable>. On the +other hand, if <literal>\<replaceable>cmd</replaceable></literal> is called without the square brackets +then within <replaceable>defn</replaceable> the parameter <literal>#1</literal> is set to the value of +<replaceable>optargdefault</replaceable>. In either case, the required arguments start with +<literal>#2</literal>. +</para> +<para>Omitting <literal>[<replaceable>optargdefault</replaceable>]</literal> is different from having the +square brackets with no contents, as in <literal>[]</literal>. The former sets +<literal>#1</literal> to the value of <replaceable>optargdefault</replaceable>; the latter sets <literal>#1</literal> +to the empty string. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>defn</replaceable> +</term><listitem><para>Required; the text to be substituted for every occurrence of +<literal>\<replaceable>cmd</replaceable></literal>. The parameters <literal>#1</literal>, <literal>#2</literal>, +... <literal>#<replaceable>nargs</replaceable></literal> are replaced by the values that you supply when +you call the command (or by the default value if there is an optional +argument and you don’t exercise the option). +</para> +</listitem></varlistentry></variablelist> +<para>&tex; ignores spaces in the source following an alphabetic control +sequence, as in ‘<literal>\cmd </literal>’. If you actually want a space there, one +solution is to type <literal>{}</literal> after the command (‘<literal>\cmd{} </literal>’, and +another solution is to use an explicit control space (‘<literal>\cmd\ </literal>’). +</para> +<para>A simple example of defining a new command: +<literal>\newcommand{\RS}{Robin Smith}</literal> results in <literal>\RS</literal> being +replaced by the longer text. Redefining an existing command is similar: +<literal>\renewcommand{\qedsymbol}{{\small QED}}</literal>. +</para> +<para>If you try to define a command and the name has already been used then +you get something like ‘<literal>LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual</literal>’. If you try +to redefine a command and the name has not yet been used then you get +something like ‘<literal>LaTeX Error: \hank undefined</literal>’. +</para> +<para>Here the first command definition has no arguments, and the second has +one required argument. +</para> +<screen>\newcommand{\student}{Ms~O'Leary} +\newcommand{\defref}[1]{Definition~\ref{#1}} +</screen> +<para>Use the first as in <literal>I highly recommend \student{} to you</literal>. The +second has a variable, so that <literal>\defref{def:basis}</literal> expands to +<literal>Definition~\ref{def:basis}</literal>, which ultimately expands to +something like ‘<literal>Definition~3.14</literal>’. +</para> +<para>Similarly, but with two required arguments: +<literal>\newcommand{\nbym}[2]{$#1 \times #2$}</literal> is invoked as +<literal>\nbym{2}{k}</literal>. +</para> +<para>This example has an optional argument. +</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>This example has an optional argument and two required arguments. +</para> +<screen>\newcommand{\lawyers}[3][company]{#2, #3, and~#1} +I employ \lawyers[Howe]{Dewey}{Cheatem}. +</screen> +<para>The output is ‘<literal>I employ Dewey, Cheatem, and Howe</literal>’. The optional +argument, the <literal>Howe</literal>, is associated with <literal>#1</literal>, while +<literal>Dewey</literal> and <literal>Cheatem</literal> are associated with <literal>#2</literal> +and <literal>#3</literal>. Because of the optional argument, +<literal>\lawyers{Dewey}{Cheatem}</literal> will give the output ‘<literal>I employ +Dewey, Cheatem, and company</literal>’. +</para> +<para>The braces around <replaceable>defn</replaceable> do not define a group, that is, they do not +delimit the scope of the result of expanding <replaceable>defn</replaceable>. For example, +with <literal>\newcommand{\shipname}[1]{\it #1}</literal>, in this sentence, +</para> +<screen>The \shipname{Monitor} met the \shipname{Merrimac}. +</screen> +<para>the words ‘<literal>met the</literal>’ would incorrectly be in italics. The solution +is to put another pair of braces inside the definition: +<literal>\newcommand{\shipname}[1]{{\it #1}}</literal>. +</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>Synopses, one of: +</para> +<screen>\providecommand{<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>} +\providecommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\providecommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\providecommand*{<replaceable>cmd</replaceable>}{<replaceable>defn</replaceable>} +\providecommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>defn</replaceable>} +\providecommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +</screen> +<para>Defines a command, as long as no command of this name already exists. +If no command of this name already exists then this has the same effect +as <literal>\newcommand</literal>. If a command of this name already exists then +this definition does nothing. This is particularly useful in a file +that may be loaded more than once, such as a style file. +See <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link> for the description of the arguments. +</para> +<para>This example +</para> +<screen>\providecommand{\myaffiliation}{Saint Michael's College} +\providecommand{\myaffiliation}{Saint Michael's College} +From \myaffiliation. +</screen> +<para>outputs ‘<literal>From Saint Michael's College</literal>’. Unlike <literal>\newcommand</literal>, +the repeated use of <literal>\providecommand</literal> does not give an error. +</para> + +</sect1> +<sect1 label="12.3" id="_005cmakeatletter-_0026-_005cmakeatother"> +<title><literal>\makeatletter</literal> & <literal>\makeatother</literal></title> + +<para>Synopsis: +</para> +<screen>\makeatletter + ... definition of commands with @ in their name .. +\makeatother +</screen> +<para>Use this pair when you redefine &latex; commands that are named with an +at-sign character ‘<literal><literal>@</literal></literal>’. The <literal>\makeatletter</literal> +declaration makes the at-sign character have the category code of a +letter, code 11. The <literal>\makeatother</literal> declaration sets the +category code of the at-sign to code 12, its default value. +</para> +<para>As &tex; reads characters, it assigns each one a category code, or +<indexterm role="cp"><primary>catcode</primary></indexterm> +<indexterm role="cp"><primary>character category code</primary></indexterm> +<indexterm role="cp"><primary>category code, character</primary></indexterm> +<firstterm>catcode</firstterm>. For instance, it assigns the backslash +character ‘<literal><literal>\</literal></literal>’ the catcode 0. Command names +consist of a category 0 character, ordinarily backslash, followed +by letters, category 11 characters (except that a command name can +also consist of a category 0 character followed by a single +non-letter symbol). +</para> +<para>&latex;’s source code has the convention that some commands use +<literal>@</literal> in their name. These commands are mainly intended for package +or class writers. The convention prevents authors who are just using a +package or class from accidentally replacing such a command with one of +their own, because by default the at-sign has catcode 12. +</para> +<para>The pair <literal>\makeatletter</literal> and <literal>\makeatother</literal> changes the +default code and then changes it back. Use them inside a <filename>.tex</filename> +file, in the preamble, when you are defining or redefining commands +named with <literal>@</literal>, by having them surround your definition. Don’t +use these inside <filename>.sty</filename> or <filename>.cls</filename> files since the +<literal>\usepackage</literal> and <literal>\documentclass</literal> commands already arrange +that the at-sign has the character code of a letter, catcode 11. +</para> +<indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>macros2e</literal> package</primary></indexterm> + +<para>For a comprehensive list of macros with an at-sign in their names see +<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. +</para> +<para>In this example the class file has a command +<literal>\thesis@universityname</literal> that the user wants to change. These +three lines should go in the preamble, before the +<literal>\begin{document}</literal>. +</para> +<screen>\makeatletter +\renewcommand{\thesis@universityname}{Saint Michael's College} +\makeatother +</screen> + +</sect1> +<sect1 label="12.4" id="_005c_0040ifstar"> +<title><literal>\@ifstar</literal></title> + +<indexterm role="fn"><primary>\@ifstar</primary></indexterm> +<indexterm role="cp"><primary>commands, star-variants</primary></indexterm> +<indexterm role="cp"><primary>star-variants, commands</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}} +\newcommand{\mycmd@nostar}[<replaceable>nostar-num-args</replaceable>]{<replaceable>nostar-body</replaceable>} +\newcommand{\mycmd@star}[<replaceable>star-num-args</replaceable>]{<replaceable>star-body</replaceable>} +</screen> +<para>Many standard &latex; environments or commands have a variant with the +same name but ending with a star character <literal>*</literal>, an asterisk. +Examples are the <literal>table</literal> and <literal>table*</literal> environments and the +<literal>\section</literal> and <literal>\section*</literal> commands. +</para> +<para>When defining environments, following this pattern is straightforward +because <literal>\newenvironment</literal> and <literal>\renewenvironment</literal> allow the +environment name to contain a star. For commands the situation is more +complex. As in the synopsis above, there will be a user-called command, +given above as <literal>\mycmd</literal>, which peeks ahead to see if it is followed +by a star. For instance, &latex; does not really have a +<literal>\section*</literal> command; instead, the <literal>\section</literal> command peeks +ahead. This command does not accept arguments but instead expands to +one of two commands that do accept arguments. In the synopsis these two +are <literal>\mycmd@nostar</literal> and <literal>\mycmd@star</literal>. They could take the +same number of arguments or a different number, or no arguments at all. +As always, in a &latex; document a command using at-sign <literal>@</literal> +must be enclosed inside a <literal>\makeatletter ... \makeatother</literal> block +(see <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter & \makeatother</link>). +</para> +<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a +variant <literal>\ciel*</literal>. Both have one required argument. A call to +<literal>\ciel{night}</literal> will return "starry night sky" while +<literal>\ciel*{blue}</literal> will return "starry not blue sky". +</para> +<screen>\newcommand*{\ciel@unstarred}[1]{starry #1 sky} +\newcommand*{\ciel@starred}[1]{starry not #1 sky} +\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}} +</screen> +<para>In the next example, the starred variant takes a different number of +arguments than the unstarred one. With this definition, Agent 007’s +<literal>``My name is \agentsecret*{Bond}, +\agentsecret{James}{Bond}.''</literal> is equivalent to entering the commands +<literal>``My name is \textsc{Bond}, \textit{James} textsc{Bond}.''</literal> +</para> +<screen>\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}} +\newcommand*{\agentsecret@starred}[1]{\textsc{#1}} +\newcommand*{\agentsecret}{% + \@ifstar{\agentsecret@starred}{\agentsecret@unstarred}} +</screen> +<para>There are two sometimes more convenient ways to accomplish the work of +<literal>\@ifstar</literal>. The <filename>suffix</filename> package allows the construct +<literal>\newcommand\mycommand{<replaceable>unstarred version</replaceable>}</literal> followed by +<literal>\WithSuffix\newcommand\mycommand*{<replaceable>starred version</replaceable>}</literal>. And +&latex;3 has the <filename>xparse</filename> package that allows this code. +</para> +<screen>\NewDocumentCommand\foo{s}{\IfBooleanTF#1 + {<replaceable>starred version</replaceable>}% + {<replaceable>unstarred version</replaceable>}% + } +</screen> + +</sect1> +<sect1 label="12.5" id="_005cnewcounter"> +<title><literal>\newcounter</literal>: Allocating a counter</title> + +<indexterm role="fn"><primary>\newcounter</primary></indexterm> +<indexterm role="cp"><primary>counters, defining new</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\newcounter{<replaceable>countername</replaceable>} +\newcounter{<replaceable>countername</replaceable>}[<replaceable>supercounter</replaceable>] +</screen> +<para>Globally defines a new counter named <replaceable>countername</replaceable> and initialize it +to zero (see <link linkend="Counters">Counters</link>). +</para> +<para>The name <replaceable>countername</replaceable> must consist of letters only. It does not +begin with a backslash. This name must not already be in use by another +counter. +</para> +<para>When you use the optional argument <literal>[<replaceable>supercounter</replaceable>]</literal> then the +counter <replaceable>countername</replaceable> will be reset to zero whenever +<replaceable>supercounter</replaceable> is incremented. For example, ordinarily +<literal>subsection</literal> is numbered within <literal>section</literal> so that any time you +increment <replaceable>section</replaceable>, either with <literal>\stepcounter</literal> +(see <link linkend="_005cstepcounter">\stepcounter</link>) or <literal>\refstepcounter</literal> +(see <link linkend="_005crefstepcounter">\refstepcounter</link>), then &latex; will reset <replaceable>subsection</replaceable> to +zero. +</para> +<para>This example +</para> +<screen>\newcounter{asuper} \setcounter{asuper}{1} +\newcounter{asub}[asuper] \setcounter{asub}{3} % Note `asuper' +The value of asuper is \arabic{asuper} and of asub is \arabic{asub}. +\stepcounter{asuper} +Now asuper is \arabic{asuper} while asub is \arabic{asub}. +</screen> +<para>produces ‘<literal>The value of asuper is 1 and that of asub is 3</literal>’ and +‘<literal>Now asuper is 2 while asub is 0</literal>’. +</para> +<para>If the counter already exists, for instance by entering <literal>asuper</literal> +twice, then you get something like ‘<literal>LaTeX Error: Command \c@asuper +already defined. Or name \end... illegal, see p.192 of the manual.</literal>’. +</para> +<para>If you use the optional argument then the super counter must already +exist. Entering <literal>\newcounter{jh}[lh]</literal> when <literal>lh</literal> is not a +defined counter will get you ‘<literal>LaTeX Error: No counter 'lh' +defined.</literal>’ +</para> + +</sect1> +<sect1 label="12.6" id="_005cnewlength"> +<title><literal>\newlength</literal></title> + +<indexterm role="fn"><primary>\newlength</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> +<screen>\newlength{<replaceable>arg</replaceable>} +</screen> +<para>Allocate a new length register (see <link linkend="Lengths">Lengths</link>). The required argument +<replaceable>arg</replaceable> must begin with a backslash, <literal>\</literal>. The new register holds +rubber lengths such as <literal>72.27pt</literal> or <literal>1in plus.2in minus.1in</literal> +(a &latex; length register is what plain &tex; calls a <literal>skip</literal> +register). The initial value is zero. The control sequence +<literal>\<replaceable>arg</replaceable></literal> must not be already defined. +</para> +<para>An example: +</para> +<screen>\newlength{\graphichgt} +</screen> +<para>If you forget the backslash then you get ‘<literal>Missing control sequence +inserted</literal>’. If the command sequence already exists then you get +something like ‘<literal>LaTeX Error: Command \graphichgt already defined. +Or name \end... illegal, see p.192 of the manual</literal>’. +</para> + +</sect1> +<sect1 label="12.7" id="_005cnewsavebox"> +<title><literal>\newsavebox</literal></title> + +<indexterm role="fn"><primary>\newsavebox</primary></indexterm> +<indexterm role="cp"><primary>box, allocating new</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\newsavebox{\<replaceable>cmd</replaceable>} +</screen> +<para>Define \<replaceable>cmd</replaceable>, the string consisting of a backslash followed by +<replaceable>cmd</replaceable>, to refer to a new bin for storing material. These bins hold +material that has been typeset, to use multiple times or to measure or +manipulate (see <link linkend="Boxes">Boxes</link>). The bin name \<replaceable>cmd</replaceable> is required, must +start with a backslash, \, and must not already be a defined command. +This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This allocates a bin and then puts typeset material into it. +</para> +<screen>\newsavebox{\logobox} +\savebox{\logobox}{LoGo} +Our logo is \usebox{\logobox}. +</screen> +<para>The output is ‘<literal>Our logo is LoGo</literal>’. +</para> +<para>If there is an already defined bin then you get something like +‘<literal>LaTeX Error: Command \logobox already defined. Or name +\end... illegal, see p.192 of the manual</literal>’. +</para> +<para>The allocation of a box is global. +</para> + +</sect1> +<sect1 label="12.8" 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, one of: +</para> +<screen>\newenvironment{<replaceable>env</replaceable>}{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\newenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\newenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\newenvironment*{<replaceable>env</replaceable>}{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\newenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\newenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +</screen> +<para>or one of these. +</para> +<screen>\renewenvironment{<replaceable>env</replaceable>}{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\renewenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\renewenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\renewenvironment*{<replaceable>env</replaceable>}{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\renewenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +\renewenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdef</replaceable>}{<replaceable>enddef</replaceable>} +</screen> +<para>Define or redefine the environment <replaceable>env</replaceable>, that is, create the +construct <literal>\begin{<replaceable>env</replaceable>} ... <replaceable>body</replaceable> ... \end{<replaceable>env</replaceable>}</literal>. +</para> +<indexterm role="cp"><primary><literal>*</literal>-form of environment commands</primary></indexterm> +<para>The starred form of these commands requires that the arguments not +contain multiple paragraphs of text. However, the body of these +environments can contain multiple paragraphs. +</para> +<variablelist><varlistentry><term><replaceable>env</replaceable> +</term><listitem><para>Required; the environment name. It consists only of letters or the +<literal>*</literal> character, and thus 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>Optional; an integer from 0 to 9 denoting the number of arguments of +that the environment takes. When you use the environment these +arguments appear after the <literal>\begin</literal>, as in +<literal>\begin{<replaceable>env</replaceable>}{<replaceable>arg1</replaceable>} ... {<replaceable>argn</replaceable>}</literal>. Omitting +this is equivalent to setting it to 0; the environment will 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 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 is not in the definition then the +environment does not take an optional argument. +</para> +<para>That is, when <replaceable>optargdefault</replaceable> is present in the definition of the +environment then you can start the environment with square brackets, as +in <literal>\begin{<replaceable>env</replaceable>}[<replaceable>optval</replaceable>]{...} ... \end{<replaceable>env</replaceable>}</literal>. +In this case, within <replaceable>begdefn</replaceable> the parameter <literal>#1</literal> is set to the +value of <replaceable>optval</replaceable>. If you call <literal>\begin{<replaceable>env</replaceable>}</literal> without +square brackets, then within <replaceable>begdefn</replaceable> the parameter <literal>#1</literal> is +set to the value of the default <replaceable>optargdefault</replaceable>. In either case, +any required arguments start with <literal>#2</literal>. +</para> +<para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in the call is different than 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>begdef</replaceable> +</term><listitem><para>Required; the text expanded at every occurrence of +<literal>\begin{<replaceable>env</replaceable>}</literal>. Within <replaceable>begdef</replaceable>, the parameters +<literal>#1</literal>, <literal>#2</literal>, ... <literal>#<replaceable>nargs</replaceable></literal>, are replaced by the +values that you supply when you call the environment; see the examples +below. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>enddef</replaceable> +</term><listitem><para>Required; the text expanded at every occurrence of +<literal>\end{<replaceable>env</replaceable>}</literal>. This may not contain any parameters, that is, +you cannot use <literal>#1</literal>, <literal>#2</literal>, etc., here (but see the final +example below). +</para> +</listitem></varlistentry></variablelist> +<para>All environments, that is to say the <replaceable>begdef</replaceable> code, the environment +body, and the <replaceable>enddef</replaceable> code, are processed within a group. 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>If you try to define an environment and the name has already been used +then you get something like ‘<literal>LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual</literal>’. If you try +to redefine an environment and the name has not yet been used then you +get something like ‘<literal>LaTeX Error: Environment hank undefined.</literal>’. +</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 has an argument, which is set in boldface at the start of a +paragraph. +</para> +<screen>\newenvironment{point}[1]{% + \noindent\textbf{#1} +}{% +} +</screen> +<para>This one shows the use of a optional argument; 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 ‘<literal>Shakespeare</literal>’. In +the document, use the environment like this. +</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>enddef</replaceable>, in this case in a box (see <link linkend="_005csbox-_0026-_005csavebox">\sbox & \savebox</link>). +</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.9" 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> + +<indexterm role="cp"><primary>theorem-like environment</primary></indexterm> +<indexterm role="cp"><primary>environment, theorem-like</primary></indexterm> +<para>Synopses: +</para> +<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>} +\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] +\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>} +</screen> +<para>Define a new theorem-like environment. You can specify one of +<replaceable>numbered_within</replaceable> and <replaceable>numbered_like</replaceable>, or neither, but not both. +</para> +<para>The first form, <literal>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}</literal>, creates +an environment that will be labelled with <replaceable>title</replaceable>; see the first +example below. +</para> +<para>The second form, +<literal>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>]</literal>, +creates an environment whose counter is subordinate to the existing +counter <replaceable>numbered_within</replaceable>, so this counter will be reset when +<replaceable>numbered_within</replaceable> is reset. See the second example below. +</para> +<para>The third form +<literal>\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>}</literal>, +with optional argument between the two required arguments, creates an +environment whose counter will share the previously defined counter +<replaceable>numbered_like</replaceable>. See the third example. +</para> +<para>This command creates a counter named <replaceable>name</replaceable>. In addition, unless +the optional argument <replaceable>numbered_like</replaceable> is used, inside of the +theorem-like environment the current <literal>\ref</literal> value will be that of +<literal>\the<replaceable>numbered_within</replaceable></literal> (see <link linkend="_005cref">\ref</link>). +</para> +<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 is a string of letters. It must not +begin with a backslash, <literal>\</literal>. It must not be the name of an +existing environment, and the command name <literal>\<replaceable>name</replaceable></literal> must not +already be defined. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>title</replaceable> +</term><listitem><para>The text to be printed at the beginning of the environment, before the +number. For example, ‘<literal>Theorem</literal>’. +</para> +</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> +<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>Without any optional arguments the environments are numbered +sequentially. The example below 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>This example has the same document body as the prior one. But here +<literal>\newtheorem</literal>’s optional argument <replaceable>numbered_within</replaceable> is given as +<literal>section</literal>, so the output is like ‘<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 the next 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.10" id="_005cnewfont"> +<title><literal>\newfont</literal></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> + +<!-- @findex .fd @r{file} --> +<para>This command is obsolete. This description is here only to help with old +documents. New documents should define fonts in families through the +New Font Selection Scheme which allows you to, for example, associate a +boldface with a roman (see <link linkend="Fonts">Fonts</link>). +<!-- This is done either by using --> +<!-- @file{.fd} files or through the use of an engine that can access system --> +<!-- fonts such as Xe@LaTeX{} (@pxref{@TeX{} engines}). --> +</para> +<para>Synopsis: +</para> +<screen>\newfont{\<replaceable>cmd</replaceable>}{<replaceable>font description</replaceable>} +</screen> +<para>Define a command <literal>\<replaceable>cmd</replaceable></literal> that will change the current font. +The control sequence must not already be defined. It must begin with a +backslash, <literal>\</literal>. +</para> +<indexterm role="cp"><primary>at clause, in font definitions</primary></indexterm> +<indexterm role="cp"><primary>design size, in font definitions</primary></indexterm> +<para>The <replaceable>font description</replaceable> consists of a <replaceable>fontname</replaceable> and an optional +<firstterm>at clause</firstterm>. &latex; will look on your system for a file named +<filename><replaceable>fontname</replaceable>.tfm</filename>. The at clause 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 defines two equivalent fonts and typesets a few characters in each. +</para> +<screen>\newfont{\testfontat}{cmb10 at 11pt} +\newfont{\testfontscaled}{cmb10 scaled 1100} +\testfontat abc +\testfontscaled abc +</screen> + +</sect1> +<sect1 label="12.11" id="_005cprotect"> +<title><literal>\protect</literal></title> + +<indexterm role="fn"><primary>\protect</primary></indexterm> +<indexterm role="cp"><primary>fragile commands</primary></indexterm> +<indexterm role="cp"><primary>robust commands</primary></indexterm> + +<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. A +fragile command can break when it is used in the argument to certain +other commands. Commands that contain data that &latex; writes to an +auxiliary file and re-reads later are fragile. This includes material +that goes into a table of contents, list of figures, list of tables, +etc. Fragile commands also include line breaks, any command that has an +optional argument, and many more. To prevent such commands from +breaking, one solution is to preceded them with the command +<literal>\protect</literal>. +</para> +<para>For example, when &latex; runs the <literal>\section{<replaceable>section +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 +<indexterm role="cp"><primary>moving arguments</primary></indexterm> +<firstterm>moving argument</firstterm>. A command is fragile if it can +expand during this process into invalid &tex; code. Some examples of +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> +<sect1 label="12.12" id="_005cignorespaces-_0026-_005cignorespacesafterend"> +<title><literal>\ignorespaces & \ignorespacesafterend</literal></title> + +<indexterm role="fn"><primary>\ignorespaces</primary></indexterm> +<indexterm role="fn"><primary>\ignorespacesafterend</primary></indexterm> +<indexterm role="cp"><primary>spaces, ignore around commands</primary></indexterm> +<indexterm role="cp"><primary>commands, ignore spaces</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\ignorespaces +</screen> +<para>or +</para> +<screen>\ignorespacesafterend +</screen> +<para>Both commands cause &latex; to ignore spaces after the end of the +command up until the first non-space character. The first is a command +from Plain &tex;, and the second is &latex;-specific. +</para> +<para>The <literal>ignorespaces</literal> is often used when defining commands via +<literal>\newcommand</literal>, or <literal>\newenvironment</literal>, or <literal>\def</literal>. The +example below illustrates. It allows a user to show the points values +for quiz questions in the margin but it is inconvenient because, as +shown in the <literal>enumerate</literal> list, users must not put any space between +the command and the question text. +</para> +<screen>\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}} +\begin{enumerate} + \item\points{10}no extra space output here + \item\points{15} extra space between the number and the `extra' +\end{enumerate} +</screen> +<para>The solution is to change to this. +</para> +<screen>\newcommand{\points}[1]{% + \makebox[0pt]{\makebox[10em][l]{#1~pts}}\ignorespaces} +</screen> +<para>A second example shows spaces being removed from the front of text. The +commands below allow a user to uniformly attach a title to names. But, +as given, if a title accidentally starts with a space then +<literal>\fullname</literal> will reproduce that. +</para> +<screen>\makeatletter +\newcommand{\honorific}[1]{\def\@honorific{#1}} % remember title +\newcommand{\fullname}[1]{\@honorific~#1} % put title before name +\makeatother +\begin{tabular}{|l|} +\honorific{Mr/Ms} \fullname{Jones} \\ % no extra space here +\honorific{ Mr/Ms} \fullname{Jones} % extra space before title +\end{tabular} +</screen> +<para>To fix this, change to +<literal>\newcommand{\fullname}[1]{\ignorespaces\@honorific~#1}</literal>. +</para> +<para>The <literal>\ignorespaces</literal> is also often used in a <literal>\newenvironment</literal> +at the end of the <replaceable>begin</replaceable> clause, that is, as part of the second +argument, as in <literal>\begin{newenvironment}{<replaceable>env +name</replaceable>}{... \ignorespaces}{...}</literal>. +</para> +<para>To strip spaces off the end of an environment use +<literal>\ignorespacesafterend</literal>. An example is that this will show a much +larger vertical space between the first and second environments than +between the second and third. +</para> +<screen>\newenvironment{eq}{\begin{equation}}{\end{equation}} +\begin{eq} +e=mc^2 +\end{eq} +\begin{equation} +F=ma +\end{equation} +\begin{equation} +E=IR +\end{equation} +</screen> +<para>Putting a comment character <literal>%</literal> immediately after the +<literal>\end{eq}</literal> will make the vertical space disappear, but that is +inconvenient. The solution is to change to +<literal>\newenvironment{eq}{\begin{equation}}{\end{equation}\ignorespacesafterend}</literal>. +</para> + +</sect1> +</chapter> +<chapter label="13" id="Counters"> +<title>Counters</title> + +<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 often the same as the name of the +environment or command associated with the number, except that the +counter’s name has no backslash <literal>\</literal>. Thus, associated with +the <literal>\chapter</literal> command is the <literal>chapter</literal> counter that keeps +track of the chapter number. +</para> +<para>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 +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>). The counters <literal>enumi</literal> +through <literal>enumiv</literal> are used in the <literal>enumerate</literal> environment, for +up to four levels of nesting (see <link linkend="enumerate">enumerate</link>). +</para> +<para>Counters can have any integer value but they are typically positive. +</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>Print the value of a counter, in a specified style. For instance, if +the counter <replaceable>counter</replaceable> has the value 1 then a +<literal>\alph{<replaceable>counter</replaceable>}</literal> in your source will result in a lowercase +letter a appearing in the output. +</para> +<para>All of these commands take a single counter as an argument, for +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{<replaceable>counter</replaceable>}</primary></indexterm><literal>\alph{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print the value of <replaceable>counter</replaceable> in lowercase letters: ‘a’, ‘b’, +... If the counter’s value is less than 1 or more than 26 then +you get ‘<literal>LaTeX Error: Counter too large.</literal>’ +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Alph{<replaceable>counter</replaceable>}</primary></indexterm><literal>\Alph{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in uppercase letters: ‘A’, ‘B’, ... If the counter’s value +is less than 1 or more than 26 then you get ‘<literal>LaTeX Error: Counter +too large.</literal>’ +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arabic{<replaceable>counter</replaceable>}</primary></indexterm><literal>\arabic{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in Arabic numbers such as ‘<literal>5</literal>’ or ‘<literal>-2</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\roman{<replaceable>counter</replaceable>}</primary></indexterm><literal>\roman{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in lowercase roman numerals: ‘i’, ‘ii’, ... If the +counter’s value is less than 1 then you get no warning or error but +&latex; does not print anything in the output. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Roman{<replaceable>counter</replaceable>}</primary></indexterm><literal>\Roman{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in uppercase roman numerals: ‘I’, ‘II’, ... If the +counter’s value is less than 1 then you get no warning or error but +&latex; does not print anything in the output. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\fnsymbol{<replaceable>counter</replaceable>}</primary></indexterm><literal>\fnsymbol{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Prints the value of <replaceable>counter</replaceable> using a sequence of nine symbols that +are traditionally used for labeling footnotes. The value of +<replaceable>counter</replaceable> should be between 1 and 9, inclusive. If the +counter’s value is less than 0 or more than 9 then you get ‘<literal>LaTeX +Error: Counter too large</literal>’, while if it is 0 then you get no error or +warning but &latex; does not output anything. +</para> +<para>Here are the symbols: +</para> +<informaltable><tgroup cols="4"><colspec colwidth="10*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><thead><row><entry><para>Number</para></entry><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Symbol +</para></entry></row></thead><tbody><row><entry><para>1</para></entry><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!-- --> +</para></entry></row><row><entry><para>2</para></entry><entry><para>dagger</para></entry><entry><para><literal>\dagger</literal></para></entry><entry><para>† +</para></entry></row><row><entry><para>3</para></entry><entry><para>ddagger</para></entry><entry><para><literal>\ddagger</literal></para></entry><entry><para>‡ +</para></entry></row><row><entry><para>4</para></entry><entry><para>section-sign</para></entry><entry><para><literal>\S</literal></para></entry><entry><para>§ +</para></entry></row><row><entry><para>5</para></entry><entry><para>paragraph-sign</para></entry><entry><para><literal>\P</literal></para></entry><entry><para>¶ +</para></entry></row><row><entry><para>6</para></entry><entry><para>double-vert</para></entry><entry><para><literal>\parallel</literal></para></entry><entry><para>‖ +</para></entry></row><row><entry><para>7</para></entry><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!-- --> +</para></entry></row><row><entry><para>8</para></entry><entry><para>double-dagger</para></entry><entry><para><literal>\dagger\dagger</literal></para></entry><entry><para>†† +</para></entry></row><row><entry><para>9</para></entry><entry><para>double-ddagger</para></entry><entry><para><literal>\ddagger\ddagger</literal></para></entry><entry><para>‡‡ +</para></entry></row></tbody></tgroup></informaltable> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="13.2" id="_005cusecounter"> +<title><literal>\usecounter</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> + +<para>Synopsis: +</para> +<screen>\usecounter{<replaceable>counter</replaceable>} +</screen> +<para>Used in the second argument of the <literal>list</literal> environment +(see <link linkend="list">list</link>), this declares that list items will be numbered by +<replaceable>counter</replaceable>. 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 (see <link linkend="_005cref">\ref</link>). This command is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Put in the document preamble, this example 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</literal></title> + +<indexterm role="fn"><primary>\value</primary></indexterm> +<indexterm role="cp"><primary>counters, getting value of</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\value{<replaceable>counter</replaceable>} +</screen> +<para>Expands to the value of the counter <replaceable>counter</replaceable>. (Note that the name +of a counter does not begin with a backslash.) +</para> +<para>This example outputs ‘<literal>Test counter is 6. Other counter +is 5.</literal>’. +</para> +<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>The <literal>\value</literal> command is not used for typesetting the value of the +counter. For that, see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>. +</para> +<para>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, such +as in <literal>\hspace{\value{foo}\parindent}</literal>. It must not be +preceded by <literal>\protect</literal> (see <link linkend="_005cprotect">\protect</link>). +</para> +<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</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> + +<para>Synopsis: +</para> +<screen>\setcounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable>} +</screen> +<para>Globally set the counter <replaceable>counter</replaceable> to have the value of the +<replaceable>value</replaceable> argument, which must be an integer. Thus, you can set a +counter’s value as <literal>\setcounter{section}{5}</literal>. Note that the +counter name does not start with a backslash. +</para> +<para>In this example if the counter <literal>theorem</literal> has value 12 then the +second line will print ‘<literal>XII</literal>’. +</para> +<screen>\setcounter{exercise}{\value{theorem}} +Here it is in Roman: \Roman{exercise}. +</screen> + +</sect1> +<sect1 label="13.5" id="_005caddtocounter"> +<title><literal>\addtocounter</literal></title> + +<indexterm role="fn"><primary>\addtocounter</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\addtocounter{<replaceable>counter</replaceable>}{<replaceable>value</replaceable> </screen> +<para>Globally increment <replaceable>counter</replaceable> by the amount specified by the +<replaceable>value</replaceable> argument, which may be negative. +</para> +<para>In this example the section value appears as ‘<literal>VII</literal>’. +</para> +<screen>\setcounter{section}{5} +\addtocounter{section}{2} +Here it is in Roman: \Roman{section}. +</screen> + +</sect1> +<sect1 label="13.6" id="_005crefstepcounter"> +<title><literal>\refstepcounter</literal></title> + +<indexterm role="fn"><primary>\refstepcounter</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\refstepcounter{<replaceable>counter</replaceable>} +</screen> +<para>Globally increments the value of <replaceable>counter</replaceable> by one, as does +<literal>\stepcounter</literal> (see <link linkend="_005cstepcounter">\stepcounter</link>). The difference is that this +command 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</literal></title> + +<indexterm role="fn"><primary>\stepcounter</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\stepcounter{<replaceable>counter</replaceable>} +</screen> +<para>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> +<para>This command differs from <literal>\refstepcounter</literal> in that this one does +not influence references — it does not define the current +<literal>\ref</literal> value to be the result of <literal>\thecounter</literal> +(see <link linkend="_005crefstepcounter">\refstepcounter</link>). +</para> + +</sect1> +<sect1 label="13.8" id="_005cday-_0026-_005cmonth-_0026-_005cyear"> +<title><literal>\day</literal> & <literal>\month</literal> & <literal>\year</literal></title> + +<indexterm role="fn"><primary>\day</primary></indexterm> +<indexterm role="fn"><primary>\month</primary></indexterm> +<indexterm role="fn"><primary>\year</primary></indexterm> + +<para>&latex; defines the counter <literal>\day</literal> for the day of the month +(nominally with value between 1 and 31), <literal>\month</literal> for the month of +the year (nominally with value between 1 and 12), and year <literal>\year</literal>. +When &tex; starts up, they are set from the current values on the +system. The related command <literal>\today</literal> produces a string +representing the current day (see <link linkend="_005ctoday">\today</link>). +</para> +<para>They counters are not updated as the job progresses so in principle they +could be incorrect by the end. In addition, &tex; does no sanity +check: +</para> +<screen>\day=-2 \month=13 \year=-4 \today +</screen> +<para>gives no error or warning and results in the output ‘<literal>-2, -4</literal>’ (the +bogus month value produces no output). +</para> + +</sect1> +</chapter> +<chapter label="14" id="Lengths"> +<title>Lengths</title> + +<indexterm role="cp"><primary>lengths, defining and using</primary></indexterm> + +<para>A <firstterm>length</firstterm> is a measure of distance. Many &latex; commands take a +length as an argument. +</para> +<para>Lengths come in two types. A <firstterm>rigid length</firstterm> such as <literal>10pt</literal> +does not contain a <literal>plus</literal> or <literal>minus</literal> component. (Plain &tex; +calls this a <firstterm>dimen</firstterm>.) A <firstterm>rubber length</firstterm> (what Plain &tex; +calls a <firstterm>skip</firstterm>) such as as with <literal>1cm plus0.05cm minus0.01cm</literal> +can contain either or both of those components. In that rubber length, +the <literal>1cm</literal> is the <firstterm>natural length</firstterm> while the other two, the +<literal>plus</literal> and <literal>minus</literal> components, allow &tex; to stretch or +shrink the length to optimize placement. +</para> +<para>The illustrations below use these two commands. +</para> +<screen>% make a black bar 10pt tall and #1 wide +\newcommand{\blackbar}[1]{\rule{#1}{10pt}} + +% Make a box around #2 that is #1 wide (excluding the border) +\newcommand{\showhbox}[2]{% + \fboxsep=0pt\fbox{\hbox to #1{#2}}} +</screen> +<para>This example uses those commands to show a black bar 100 points +long between ‘<literal>XXX</literal>’ and ‘<literal>YYY</literal>’. This length is rigid. +</para> +<screen>XXX\showhbox{100pt}{\blackbar{100pt}}YYY +</screen> +<para>As for rubber lengths, shrinking is simpler one: with <literal>1cm minus +0.05cm</literal>, the natural length is 1cm but &tex; can shrink it down +as far as 0.95cm. Beyond that, &tex; refuses to shrink any more. +Thus, below the first one works fine, producing a space of +98 points between the two bars. +</para> +<screen>XXX\showhbox{300pt}{% + \blackbar{101pt}\hspace{100pt minus 2pt}\blackbar{101pt}}YYY + +XXX\showhbox{300pt}{% + \blackbar{105pt}\hspace{100pt minus 1pt}\blackbar{105pt}}YYY +</screen> +<para>But the second one gets a warning like ‘<literal>Overfull \hbox (1.0pt too +wide) detected at line 17</literal>’. In the output the first ‘<literal>Y</literal>’ is +overwritten by the end of the black bar, because the box’s material is +wider than the 300pt allocated, as &tex; has refused to shrink +the total to less than 309 points. +</para> +<para>Stretching is like shrinking except that if &tex; is asked to stretch +beyond the given amount, it will do it. Here the first line is fine, +producing a space of 110 points between the bars. +</para> +<screen>XXX\showhbox{300pt}{% + \blackbar{95pt}\hspace{100pt plus 10pt}\blackbar{95pt}}YYY + +XXX\showhbox{300pt}{% + \blackbar{95pt}\hspace{100pt plus 1pt}\blackbar{95pt}}YYY +</screen> +<para>In the second line &tex; needs a stretch of 10 points and only +1 point was specified. &tex; stretches the space to the required +length but it gives you a warning like ‘<literal>Underfull \hbox (badness +10000) detected at line 22</literal>’. (We won’t discuss badness.) +</para> +<para>You can put both stretch and shrink in the same length, as in +<literal>1ex plus 0.05ex minus 0.02ex</literal>. +</para> +<para>If &tex; is setting two or more rubber lengths then it allocates the +stretch or shrink in proportion. +</para> +<screen>XXX\showhbox{300pt}{% + \blackbar{100pt}% left + \hspace{0pt plus 50pt}\blackbar{80pt}\hspace{0pt plus 10pt}% middle + \blackbar{100pt}}YYY % right +</screen> +<para>The left and right bars take up 100 points, so the middle needs +another 100. The middle bar is 80 points so the two +<literal>\hspace</literal>’s must stretch 20 points. Because the two are +<literal>plus 50pt</literal> and <literal>plus 10pt</literal>, &tex; gets 5/6 of the stretch +from the first space and 1/6 from the second. +</para> +<para>The <literal>plus</literal> or <literal>minus</literal> component of a rubber length can contain +a <firstterm>fill</firstterm> component, as in <literal>1in plus2fill</literal>. This gives the +length infinite stretchability or shrinkability so that &tex; could set +it to any distance. Here the two figures will be equal-spaced across +the page. +</para> +<screen>\begin{minipage}{\linewidth} + \hspace{0pt plus 1fill}\includegraphics{godel.png}% + \hspace{0pt plus 1fill}\includegraphics{einstein.png}% + \hspace{0pt plus 1fill} +\end{minipage} +</screen> +<para>&tex; actually has three levels of infinity for glue components: +<literal>fil</literal>, <literal>fill</literal>, and <literal>filll</literal>. The later ones are more +infinite than the earlier ones. Ordinarily document authors only use +the middle one (see <link linkend="_005chfill">\hfill</link> and see <link linkend="_005cvfill">\vfill</link>). +</para> +<para>Multiplying a rubber length by a number turns it into a rigid length, so +that after <literal>\setlength{\ylength}{1in plus 0.2in}</literal> and +<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> +<anchor id="units-of-length-pt"/><para>Point, 1/72.27 inch. The conversion to metric units, to two decimal +places, is 1point = 2.85mm = 28.45cm. +</para> +</listitem></varlistentry><varlistentry><term><literal>pc</literal> +</term><listitem><indexterm role="cp"><primary>pica</primary></indexterm> +<indexterm role="fn"><primary>pc</primary></indexterm> +<anchor id="units-of-length-pc"/><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> +<anchor id="units-of-length-in"/><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> +<anchor id="units-of-length-bp"/><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> +<anchor id="units-of-length-cm"/><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> +<anchor id="units-of-length-mm"/><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> +<anchor id="units-of-length-dd"/><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> +<anchor id="units-of-length-cc"/><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> +<anchor id="units-of-length-sp"/><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> +<anchor id="Lengths_002fem"/><anchor id="Lengths_002fen"/><anchor id="Lengths_002fex"/><anchor id="units-of-length-em"/><anchor id="units-of-length-en"/><anchor id="units-of-length-ex"/><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 lowercase 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</literal></title> + +<indexterm role="fn"><primary>\setlength</primary></indexterm> +<indexterm role="cp"><primary>lengths, setting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\setlength{<replaceable>len</replaceable>}{<replaceable>amount</replaceable>} +</screen> +<para>Set the length <replaceable>len</replaceable> to <replaceable>amount</replaceable>. The length name <replaceable>len</replaceable> +must begin with a backslash, <literal>\</literal>. The <literal>amount</literal> can be a +rubber length (see <link linkend="Lengths">Lengths</link>). It can be positive, negative or zero, +and can be in any units that &latex; understands (see <link linkend="Units-of-length">Units of +length</link>). +</para> +<para>Below, with &latex;’s defaults the first paragraph will be indented +while the second will not. +</para> +<screen>I told the doctor I broke my leg in two places. + +\setlength{\parindent}{0em} +He said stop going to those places. +</screen> +<para>If you did not declare <replaceable>len</replaceable> with <literal>\newlength</literal>, for example if +you mistype the above as +<literal>\newlength{\specparindent}\setlength{\sepcparindent}{...}</literal>, +then you get an error like ‘<literal>Undefined control sequence. <argument> +\sepcindent</literal>’. If you omit the backslash at the start of the length name +then you get an error like ‘<literal>Missing number, treated as zero. <to be +read again> \relax l.19 \setlength{specparindent}{0.6\parindent}</literal>’ +</para> + +</sect1> +<sect1 label="14.3" id="_005caddtolength"> +<title><literal>\addtolength</literal></title> + +<indexterm role="fn"><primary>\addtolength</primary></indexterm> +<indexterm role="cp"><primary>lengths, adding to</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\addtolength{<replaceable>len</replaceable>}{<replaceable>amount</replaceable>} +</screen> +<para>Increment the length <replaceable>len</replaceable> by <replaceable>amount</replaceable>. The length name +<replaceable>len</replaceable> begins with a backslash, <literal>\</literal>. The <literal>amount</literal> is a +rubber length (see <link linkend="Lengths">Lengths</link>). It can be positive, negative or zero, +and can be in any units that &latex; understands (see <link linkend="Units-of-length">Units of +length</link>). +</para> +<para>Below, if <literal>\parskip</literal> starts with the value <literal>0pt plus 1pt</literal> +</para> +<screen>Doctor: how is the boy who swallowed the silver dollar? +\addtolength{\parskip}{1pt} + +Nurse: no change. +</screen> +<para>then it has the value <literal>1pt plus 1pt</literal> for the second paragraph. +</para> +<para>If you did not declare the length <replaceable>len</replaceable> with <literal>\newlength</literal>, if +for example you mistype the above as +<literal>\addtolength{\specparindent}{0.6\praindent}</literal>, then you get +something like ‘<literal>Undefined control sequence. <argument> \praindent</literal>’. +If you leave off the backslash at the start of <replaceable>len</replaceable>, as in +<literal>\addtolength{parindent}{1pt}</literal>, then you get something like +‘<literal>You can't use `the letter p' after \advance</literal>’. +</para> + +</sect1> +<sect1 label="14.4" id="_005csettodepth"> +<title><literal>\settodepth</literal></title> + +<indexterm role="fn"><primary>\settodepth</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\settodepth{<replaceable>len</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>Set the length <replaceable>len</replaceable> to the depth of box that &latex; gets on +typesetting the <replaceable>text</replaceable> argument. The length name <replaceable>len</replaceable> must +begin with a backslash, <literal>\</literal>. +</para> +<para>This will show how low the character descenders go. +</para> +<screen>\newlength{\alphabetdepth} +\settodepth{\alphabetdepth}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetdepth +</screen> +<para>If you did not set aside the length <replaceable>len</replaceable>, if for example you +mistype the above as <literal>\settodepth{\aplhabetdepth}{abc...}</literal>, +then you get something like ‘<literal>Undefined control sequence. <argument> +\aplhabetdepth</literal>’. If you leave the backslash out of <replaceable>len</replaceable>, as in +<literal>\settodepth{alphabetdepth}{...}</literal> then you get something like +‘<literal>Missing number, treated as zero. <to be read again> \setbox</literal>’. +</para> + +</sect1> +<sect1 label="14.5" id="_005csettoheight"> +<title><literal>\settoheight</literal></title> + +<indexterm role="fn"><primary>\settoheight</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\settoheight{<replaceable>len</replaceable>}{text} +</screen> +<para>Sets the length <replaceable>len</replaceable> to the height of box that &latex; gets on +typesetting the <literal>text</literal> argument. The length name <replaceable>len</replaceable> must +begin with a backslash, <literal>\</literal>. +</para> +<para>This will show how high the characters go. +</para> +<screen>\newlength{\alphabetheight} +\settoheight{\alphabetheight}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetheight +</screen> +<para>If no such length <replaceable>len</replaceable> has been declared with <literal>\newlength</literal>, if +for example you mistype as +<literal>\settoheight{\aplhabetheight}{abc...}</literal>, then you get something +like ‘<literal>Undefined control sequence. <argument> \alphabetheight</literal>’. If +you leave the backslash out of <replaceable>len</replaceable>, as in +<literal>\settoheight{alphabetheight}{...}</literal> then you get something like +‘<literal>Missing number, treated as zero. <to be read again> \setbox</literal>’. +</para> + +</sect1> +<sect1 label="14.6" id="_005csettowidth"> +<title><literal>\settowidth</literal></title> + +<indexterm role="fn"><primary>\settowidth</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\settowidth{<replaceable>len</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>Set the length <replaceable>len</replaceable> to the width of the box that &latex; gets on +typesetting the <replaceable>text</replaceable> argument. The length name <replaceable>len</replaceable> must +begin with a backslash, <literal>\</literal>. +</para> +<para>This measures the width of the lowercase ASCII alphabet. +</para> +<screen>\newlength{\alphabetwidth} +\settowidth{\alphabetwidth}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetwidth +</screen> +<para>If no such length <replaceable>len</replaceable> has been set aside, if for example you +mistype the above as <literal>\settowidth{\aplhabetwidth}{abc...}</literal>, +then you get something like ‘<literal>Undefined control sequence. <argument> +\aplhabetwidth</literal>’. If you leave the backslash out of <replaceable>len</replaceable>, as in +<literal>\settoheight{alphabetwidth}{...}</literal> then you get something like +‘<literal>Missing number, treated as zero. <to be read again> \setbox</literal>’. +</para> + +</sect1> +</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> + +<para>To start a paragraph, just type some text. To end the current +paragraph, put an empty line. This is three paragraphs, separated by +two empty lines. +</para> +<screen>It is a truth universally acknowledged, that a single man in possession +of a good fortune, must be in want of a wife. + +However little known the feelings or views of such a man may be on his +first entering a neighbourhood, this truth is so well fixed in the minds +of the surrounding families, that he is considered the rightful property +of some one or other of their daughters. + +``My dear Mr. Bennet,'' said his lady to him one day, +``have you heard that Netherfield Park is let at last?'' +</screen> +<para>The separator lines must be empty, including not containing a comment +character, <literal>%</literal>. +</para> +<para>Once &latex; has gathered all of a paragraph’s contents it divides that +content into lines in a way that is optimized over the entire paragraph +(see <link linkend="Line-breaking">Line breaking</link>). +</para> +<para>There are places where a new paragraph is not permitted. Don’t put a +blank line in math mode (see <link linkend="Modes">Modes</link>); here the line before the +<literal>\end{equation}</literal> +</para> +<screen>\begin{equation} + 2^{|S|} > |S| + +\end{equation} +</screen> +<para>will get you the error ‘<literal>Missing $ inserted</literal>’. Similarly, the blank +line in this <literal>section</literal> argument +</para> +<screen>\section{aaa + +bbb} +</screen> +<para>gets ‘<literal>Runaway argument? {aaa ! Paragraph ended before \@sect was +complete</literal>’. +</para> + + + +<sect1 label="15.1" id="_005cpar"> +<title><literal>\par</literal></title> + +<indexterm role="fn"><primary>\par</primary></indexterm> +<indexterm role="cp"><primary>paragraph, ending</primary></indexterm> + +<para>Synopsis (note that while reading the input &tex; converts two +consecutive newlines to a <literal>\par</literal>): +</para> +<screen>\par +</screen> +<para>End the current paragraph. The usual way to separate paragraphs is with +a blank line but the <literal>\par</literal> command is entirely equivalent. This +command is robust (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This example uses <literal>\par</literal> rather than a blank line simply for +readability. +</para> +<screen>\newcommand{\syllabusLegalese}{% + \whatCheatingIs\par\whatHappensWhenICatchYou} +</screen> +<para>In LR mode or a vertical mode the <literal>\par</literal> command does nothing but +it terminates paragraph mode, switching &latex; to vertical mode +(see <link linkend="Modes">Modes</link>). +</para> +<para>You cannot use the <literal>\par</literal> command in a math mode. You also cannot +use it in the argument of many commands, such as the <literal>\section</literal> +command (see <link linkend="Making-paragraphs">Making paragraphs</link> and <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & +\renewcommand</link>). +</para> +<para>The <literal>\par</literal> command is not the same as the <literal>\paragraph</literal> +command. The latter is, like <literal>\section</literal> or <literal>\subsection</literal>, a +sectioning unit used by the standard &latex; documents +(see <link linkend="_005csubsubsection-_0026-_005cparagraph-_0026-_005csubparagraph">\subsubsection & \paragraph & \subparagraph</link>). +</para> +<para>The <literal>\par</literal> command is not the same as <literal>\newline</literal> or the line +break double backslash, <literal>\\</literal>. The difference is that <literal>\par</literal> +ends the paragraph, not just the line, and also triggers the addition of +the between-paragraph vertical space <literal>\parskip</literal> (see <link linkend="_005cparindent-_0026-_005cparskip">\parindent +& \parskip</link>). +</para> +<para>The output from this example +</para> +<screen>xyz + +\setlength{\parindent}{3in} +\setlength{\parskip}{5in} +\noindent test\indent test1\par test2 +</screen> +<para>is: after ‘<literal>xyz</literal>’ there is a vertical skip of 5 inches and then +‘<literal>test</literal>’ appears, aligned with the left margin. On the same line, +there is an empty horizontal space of 3 inches and then +‘<literal>test1</literal>’ appears. Finally. there is a vertical space of +5 inches, followed by a fresh paragraph with a paragraph indent of +3 inches, and then &latex; puts the text ‘<literal>test2</literal>’. +</para> + +</sect1> +<sect1 label="15.2" id="_005cindent-_0026-_005cnoindent"> +<title><literal>\indent</literal> & <literal>\noindent</literal></title> + +<indexterm role="fn"><primary>\indent</primary></indexterm> +<indexterm role="fn"><primary>\noindent</primary></indexterm> +<indexterm role="fn"><primary>\parindent</primary></indexterm> +<indexterm role="cp"><primary>indent, forcing</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\indent +</screen> +<para>or +</para> +<screen>\noindent +</screen> +<para>Go into horizontal mode (see <link linkend="Modes">Modes</link>). The <literal>\indent</literal> command +first outputs an empty box whose width is <literal>\parindent</literal>. These +commands are robust (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Ordinarily you create a new paragraph by putting in a blank line. +See <link linkend="_005cpar">\par</link> for the difference between this command and <literal>\par</literal>. To +start a paragraph without an indent, or to continue an interrupted +paragraph, use <literal>\noindent</literal>. +</para> +<para>In the middle of a paragraph the <literal>\noindent</literal> command has no effect, +because &latex; is already in horizontal mode there. The +<literal>\indent</literal> command’s only effect is to output a space. +</para> +<para>This example starts a fresh paragraph. +</para> +<screen>... end of the prior paragraph. + +\noindent This paragraph is not indented. +</screen> +<para>and this continues an interrupted paragraph. +</para> +<screen>The data + +\begin{center} + \begin{tabular}{rl} ... \end{tabular} +\end{center} + +\noindent shows this clearly. +</screen> +<para>To omit indentation in the entire document put +<literal>\setlength{\parindent}{0pt}</literal> in the preamble. If you do that, +you may want to also set the length of spaces between paragraphs, +<literal>\parskip</literal> (see <link linkend="_005cparindent-_0026-_005cparskip">\parindent & \parskip</link>). +</para> +<indexterm role="cp"><primary>package, <literal>indentfirst</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>indentfirst</literal> package</primary></indexterm> + +<para>Default &latex; styles have the first paragraph after a section that is +not indented, as is traditional typesetting in English. To change that, +look on CTAN for the package <literal>indentfirst</literal>. +</para> + +</sect1> +<sect1 label="15.3" id="_005cparindent-_0026-_005cparskip"> +<title><literal>\parindent</literal> & <literal>\parskip</literal></title> + +<indexterm role="fn"><primary>\parindent</primary></indexterm> +<indexterm role="fn"><primary>\parskip</primary></indexterm> +<indexterm role="cp"><primary>paragraph indentation</primary></indexterm> +<indexterm role="cp"><primary>vertical space before paragraphs</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\setlength{\parskip}{<replaceable>horizontal len</replaceable>} +\setlength{\parinden}{<replaceable>vertical len</replaceable>} +</screen> +<para>Both are a rubber lengths (see <link linkend="Lengths">Lengths</link>). They give the indentation +of ordinary paragraphs, not paragraphs inside minipages +(see <link linkend="minipage">minipage</link>), and the vertical space between paragraphs. +</para> +<para>This, put in the preamble, +</para> +<screen>\setlength{\parindent}{0em} +\setlength{\parskip}{1ex} +</screen> +<para>arranges that the document will have paragraphs that are not indented, +but instead are vertically separated by about the height of a lowercase +‘<literal>x</literal>’. +</para> +<para>In standard &latex; documents, the default value for <literal>\parindent</literal> +in one-column documents is <literal>15pt</literal> when the default text size is +<literal>10pt</literal> , <literal>17pt</literal> for <literal>11pt</literal>, and <literal>1.5em</literal> for +<literal>12pt</literal>. In two-column documents it is <literal>1em</literal>. The default +value for <literal>\parskip</literal> in &latex;’s standard document styles is +<literal>0pt plus1pt</literal>. +</para> + +</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> +<indexterm role="fn"><primary>\marginpar</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\marginpar{<replaceable>right</replaceable>} +\marginpar[<replaceable>left</replaceable>]{<replaceable>right</replaceable>} +</screen> +<para>Create a note in the margin. The first line of the note will have the +same baseline as the line in the text where the <literal>\marginpar</literal> +occurs. +</para> +<para>The margin that &latex; uses for the note depends on the current layout +(see <link linkend="Document-class-options">Document class options</link>) and also on <literal>\reversemarginpar</literal> +(see below). If you are using one-sided layout (document option +<literal>oneside</literal>) then it goes in the right margin. If you are using +two-sided layout (document option <literal>twoside</literal>) then it goes in the +outside margin. If you are in two-column layout (document option +<literal>twocolumn</literal>) then it goes in the nearest margin. +</para> +<indexterm role="fn"><primary>\reversemarginpar</primary></indexterm> +<indexterm role="fn"><primary>\normalmarginpar</primary></indexterm> +<para>If you declare <literal>\reversemarginpar</literal> then &latex; will place +subsequent marginal notes in the opposite margin to that given in the +prior paragraph. Revert that to the default position with +<literal>\normalmarginpar</literal>. +</para> +<para>When you specify the optional argument <replaceable>left</replaceable> then it is used for +a note in the left margin, while the mandatory argument <replaceable>right</replaceable> is +used for a note in the right margin. +</para> +<para>Normally, a note’s first word will not be hyphenated. You can enable +hyphenation there by beginning <replaceable>left</replaceable> or <replaceable>right</replaceable> with +<literal>\hspace{0pt}</literal>. +</para> +<para>These parameters affect the formatting of the note: +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\marginparpush</primary></indexterm><literal>\marginparpush</literal> +</term><listitem><anchor id="marginal-notes-marginparpush"/><para>Minimum vertical space between notes; default ‘<literal>7pt</literal>’ for +‘<literal>12pt</literal>’ documents, ‘<literal>5pt</literal>’ else. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\marginparsep</primary></indexterm><literal>\marginparsep</literal> +</term><listitem><anchor id="marginal-notes-marginparsep"/><para>Horizontal space between the main text and the note; default +‘<literal>11pt</literal>’ for ‘<literal>10pt</literal>’ documents, ‘<literal>10pt</literal>’ else. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\marginparwidth</primary></indexterm><literal>\marginparwidth</literal> +</term><listitem><anchor id="marginal-notes-marginparwidth"/><para>Width of the note itself; default for a one-sided ‘<literal>10pt</literal>’ document +is ‘<literal>90pt</literal>’, ‘<literal>83pt</literal>’ for ‘<literal>11pt</literal>’, and ‘<literal>68pt</literal>’ for +‘<literal>12pt</literal>’; ‘<literal>17pt</literal>’ more in each case for a two-sided document. +In two column mode, the default is ‘<literal>48pt</literal>’. +</para> +</listitem></varlistentry></variablelist> +<para>The standard &latex; routine for marginal notes does not prevent +notes from falling off the bottom of the page. +<!-- @TeX{} FAQ entry on this topic (xx when there): --> +<!-- @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=marginparside}. --> +<!-- (+marginfix) --> +</para> + +</sect1> +</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>environment, <literal>math</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> + +<indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> + +<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> + + +<para>Produce mathematical text by putting &latex; into math mode or display +math mode (see <link linkend="Modes">Modes</link>). This example shows both. +</para> +<screen>The wave equation for \( u \) is +\begin{displaymath} + \frac{\partial^2u}{\partial t^2} = c^2\nabla^2u +\end{displaymath} +where \( \nabla^2 \) is the spatial Laplacian and \( c \) is constant. +</screen> +<para>Math mode is for inline mathematics. In the above example it is invoked +by the starting <literal>\(</literal> and finished by the matching ending <literal>\)</literal>. +Display math mode is for displayed equations and here is invoked by the +<literal>displaymath</literal> environment. Note that any mathematical text +whatever, including mathematical text consisting of just one character, +is handled in math mode. +</para> +<para>When in math mode or display math mode, &latex; handles many aspects of +your input text differently than in other text modes. For example, +</para> +<screen>contrast x+y with \( x+y \) +</screen> +<para>in math mode the letters are in italics and the spacing around the plus +sign is different. +</para> +<para>There are three ways to make inline formulas, to put &latex; in math +mode. +</para> +<screen>\( <replaceable>mathematical material</replaceable> \) +$ <replaceable>mathematical material</replaceable> $ +\begin{math} <replaceable>mathematical material</replaceable> \end{math} +</screen> +<para>The first form is preferred and the second is quite common, but the +third form is rarely used. You can sometimes use one and sometimes +another, as in <literal>\(x\) and $y$</literal>. You can use these in paragraph +mode or in LR mode (see <link linkend="Modes">Modes</link>). +</para> +<para>To make displayed formulas, put &latex; into display math mode with +either: +</para> +<screen>\begin{displaymath} + <replaceable>mathematical material</replaceable> +\end{displaymath} +</screen> +<para>or +</para> +<screen>\begin{equation} + <replaceable>mathematical material</replaceable> +\end{equation} +</screen> +<para>(see <link linkend="displaymath">displaymath</link>, see <link linkend="equation">equation</link>). The only difference is that +with the <literal>equation</literal> environment, &latex; puts a formula number +alongside the formula. The construct <literal>\[ <replaceable>math</replaceable> \]</literal> is +equivalent to <literal>\begin{displaymath} <replaceable>math</replaceable> +\end{displaymath}</literal>. These environments can only be used in paragraph +mode (see <link linkend="Modes">Modes</link>). +</para> +<indexterm role="fn"><primary>\displaystyle</primary></indexterm> +<para>The two mathematics modes are similar, but there are some differences. +One involves the placement of subscripts and superscripts; in display +math mode they are further apart and in inline math mode they are closer +together. +</para> +<para>Sometimes you want the display math typographical treatment to happen in +the inline math mode. For this, the <literal>\displaystyle</literal> declaration +forces the size and style of the formula to be that of +<literal>displaymath</literal>. Thus <literal>\(\displaystyle \sum_{n=0}^\infty +x_n\)</literal> will have the limits above and below the summation sign, not next +to it. Another example is that +</para> +<screen>\begin{tabular}{r|cc} + \textsc{Name} &\textsc{Series} &\textsc{Sum} \\ \hline + Arithmetic &\( a+(a+b)+(a+2b)+\cdots+(a+(n-1)b) \) + &\( na+(n-1)n\cdot\frac{b}{2}\) \\ + Geometric &\( a+ab+ab^2+\cdots+ab^{n-1} \) + &\(\displaystyle a\cdot\frac{1-b^n}{1-b}\) \\ +\end{tabular} +</screen> +<para>because it has no <literal>\displaystyle</literal>, the ‘<literal>Arithmetic</literal>’ line’s +fraction will be scrunched. But, because of its <literal>\displaystyle</literal>, +the ‘<literal>Geometric</literal>’ line’s fraction will be easy to read, with +characters the same size as in the rest of the line. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>amsfonts</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsfonts</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm> + +<para>The American Mathematical Society has made freely available a set of +packages that greatly expand your options for writing mathematics, +<filename>amsmath</filename> and <filename>amssymb</filename> (also be aware of the <filename>mathtools</filename> +package that is an extension to, and loads, <filename>amsmath</filename>). New +documents that will have mathematical text should use these packages. +Descriptions of these packages is outside the scope of this document; +see their documentation on CTAN. +</para> + + +<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>Synopsis (in math mode or display math mode), one of: +</para> +<screen><replaceable>base</replaceable>^<replaceable>exp</replaceable> +<replaceable>base</replaceable>^{<replaceable>exp</replaceable>} +</screen> +<para>or, one of: +</para> +<screen><replaceable>base</replaceable>_<replaceable>exp</replaceable> +<replaceable>base</replaceable>_{<replaceable>exp</replaceable>} +</screen> +<para>Make <replaceable>exp</replaceable> appear as a superscript of <replaceable>base</replaceable> (with the caret +character, <literal>^</literal>) or a subscript (with +underscore, <literal>_</literal>). +</para> +<para>In this example the <literal>0</literal>’s and <literal>1</literal>’s are subscripts while the +<literal>2</literal>’s are superscripts. +</para> +<screen>\( (x_0+x_1)^2 \leq (x_0)^2+(x_1)^2 \) +</screen> +<para>To have the subscript or superscript contain more than one character, +surround the expression with curly braces, as in <literal>e^{-2x}</literal>. +This example’s fourth line shows curly braces used to group an expression +for the exponent. +</para> +<screen>\begin{displaymath} + (3^3)^3=27^3=19\,683 + \qquad + 3^{(3^3)}=3^{27}=7\,625\,597\,484\,987 +\end{displaymath} +</screen> +<para>&latex; knows how to handle a superscript on a superscript, or a +subscript on a subscript, or supers on subs, or subs on supers. So, +expressions such as <literal>e^{x^2}</literal> and <literal>x_{i_0}</literal> give correct +output. Note the use in those expressions of curly braces to give the +<replaceable>base</replaceable> a determined <replaceable>exp</replaceable>. If you enter <literal>\(3^3^3\)</literal> then +you get ‘<literal>Double superscript</literal>’. +</para> +<para>&latex; does the right thing when something has both a subscript and a +superscript. In this example the integral has both. They come out in +the correct place without any author intervention. +</para> +<screen>\begin{displaymath} + \int_{x=a}^b f'(x)\,dx = f(b)-f(a) +\end{displaymath} +</screen> +<para>Note the parentheses around <literal>x=a</literal> to make the entire expression a +subscript. +</para> +<para>To put a superscript or subscript before a symbol, use a construct like +<literal>{}_t K^2</literal>. The empty curly braces <literal>{}</literal> give the +subscript something to attach to and keeps it from accidentally +attaching to a prior symbols. +</para> +<para>Using the subscript or superscript command outside of math mode or +display math mode, as in <literal>the expression x^2</literal>, will get you +the error ‘<literal>Missing $ inserted</literal>’. +</para> +<indexterm role="cp"><primary>package, <literal>mhchem</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mhchem</literal> package</primary></indexterm> + +<para>A common reason to want subscripts outside of a mathematics mode is to +typeset chemical formulas. There are packages for that such as +<filename>mhchem</filename>; see CTAN. +</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> + +<indexterm role="cp"><primary>package, <literal>symbols</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>symbols</literal> package</primary></indexterm> + + +<para>&latex; provides almost any mathematical or technical symbol that +anyone uses. For example, if you include <literal>$\pi$</literal> in your source, +you will get the pi symbol π. See the <filename>Comprehensive +&latex; Symbol List</filename> at +<ulink url="https://ctan.org/tex-archive/info/symbols/comprehensive/">https://ctan.org/tex-archive/info/symbols/comprehensive/</ulink>. +</para> +<para>Here is a list of commonly-used symbols. It is by no means exhaustive. +Each symbol is described with a short phrase, and its symbol class, +which determines the spacing around it, is given in parenthesis. Unless +said otherwise, the commands for these symbols can be used only in math +mode. To redefine a command so that it can be used whatever the current +mode, see <link linkend="_005censuremath">\ensuremath</link>. +</para> +<!-- xx Add Negation: 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>∥ Parallel (relation). Synonym: <literal>\parallel</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\aleph</primary></indexterm><literal>\aleph</literal> +</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>α Lowercase Greek letter alpha (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\amalg</primary></indexterm><literal>\amalg</literal> +</term><listitem><para>⨿ Disjoint union (binary) +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\angle</primary></indexterm><literal>\angle</literal> +</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>≈ Almost equal to (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ast</primary></indexterm><literal>\ast</literal> +</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>≍ Asymptotically equivalent (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\backslash</primary></indexterm><literal>\backslash</literal> +</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>β Lowercase Greek letter beta (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bigcap</primary></indexterm><literal>\bigcap</literal> +</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>⚪ 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>⋃ 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>⨀ 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>⨁ 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>⨂ 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>▽ 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>△ 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>⨆ 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>⨄ 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>\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>⋀ 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>⊥ Up tack, bottom, least element of a partially ordered +set, 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>⋈ Natural join of two relations (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Box</primary></indexterm><literal>\Box</literal> +</term><listitem><para>□ Modal operator for necessity; square open box +(ordinary). 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>• 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>∩ 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>⋅ 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>χ Lowercase Greek chi (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\circ</primary></indexterm><literal>\circ</literal> +</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>♣ 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). Not available in plain &tex;. In &latex; you need to 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>≅ Congruent (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\coprod</primary></indexterm><literal>\coprod</literal> +</term><listitem><para>∐ Coproduct (operator). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cup</primary></indexterm><literal>\cup</literal> +</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>† Dagger relation (binary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dashv</primary></indexterm><literal>\dashv</literal> +</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>‡ Double dagger relation (binary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Delta</primary></indexterm><literal>\Delta</literal> +</term><listitem><para>Δ Greek uppercase delta, used for increment (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\delta</primary></indexterm><literal>\delta</literal> +</term><listitem><para>δ Greek lowercase delta (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Diamond</primary></indexterm><literal>\Diamond</literal> +</term><listitem><para>◇ Large diamond operator (ordinary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\diamond</primary></indexterm><literal>\diamond</literal> +</term><listitem><para>⋄ Diamond operator (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>♢ Diamond card suit (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\div</primary></indexterm><literal>\div</literal> +</term><listitem><para>÷ Division sign (binary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\doteq</primary></indexterm><literal>\doteq</literal> +</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>↓ Down arrow, converges (relation). Similar: +<literal>\Downarrow</literal> double line down arrow. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Downarrow</primary></indexterm><literal>\Downarrow</literal> +</term><listitem><para>⇓ Double line down arrow (relation). Similar: +<literal>\downarrow</literal> single line down arrow. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ell</primary></indexterm><literal>\ell</literal> +</term><listitem><para>ℓ Lowercase cursive letter l (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\emptyset</primary></indexterm><literal>\emptyset</literal> +</term><listitem><para>∅ Empty set symbol (ordinary). The variant form is +<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>ϵ Lowercase lunate epsilon (ordinary). Similar to +Greek text letter. More widely used in mathematics is the script small +letter 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>≡ Equivalence (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\eta</primary></indexterm><literal>\eta</literal> +</term><listitem><para>η Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\exists</primary></indexterm><literal>\exists</literal> +</term><listitem><para>∃ Existential quantifier (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\flat</primary></indexterm><literal>\flat</literal> +</term><listitem><para>♭ Musical flat (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\forall</primary></indexterm><literal>\forall</literal> +</term><listitem><para>∀ Universal quantifier (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\frown</primary></indexterm><literal>\frown</literal> +</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>Γ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\gamma</primary></indexterm><literal>\gamma</literal> +</term><listitem><para>γ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ge</primary></indexterm><literal>\ge</literal> +</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>≥ 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>← 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>≫ 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>ℏ Planck constant over two pi (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\heartsuit</primary></indexterm><literal>\heartsuit</literal> +</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>↩ Hooked left arrow (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hookrightarrow</primary></indexterm><literal>\hookrightarrow</literal> +</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>⟷ 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>ℑ Imaginary part (ordinary). See: real part <literal>\Re</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\imath</primary></indexterm><literal>\imath</literal> +</term><listitem><indexterm role="cp"><primary>dotless i, math</primary></indexterm> +<para>Dotless i; used when you are putting an accent on an i (see <link linkend="Math-accents">Math +accents</link>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\in</primary></indexterm><literal>\in</literal> +</term><listitem><para>∈ Set element (relation). See also: lowercase lunate +epsilon <literal>\epsilon</literal>ϵ and small letter script +epsilon <literal>\varepsilon</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\infty</primary></indexterm><literal>\infty</literal> +</term><listitem><para>∞ Infinity (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\int</primary></indexterm><literal>\int</literal> +</term><listitem><para>∫ Integral (operator). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\iota</primary></indexterm><literal>\iota</literal> +</term><listitem><para>ι Lowercase 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). Not available in Plain +&tex;. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\jmath</primary></indexterm><literal>\jmath</literal> +</term><listitem><indexterm role="cp"><primary>dotless j, math</primary></indexterm> +<para>Dotless j; used when you are putting an accent on a j (see <link linkend="Math-accents">Math +accents</link>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\kappa</primary></indexterm><literal>\kappa</literal> +</term><listitem><para>κ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Lambda</primary></indexterm><literal>\Lambda</literal> +</term><listitem><para>Λ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lambda</primary></indexterm><literal>\lambda</literal> +</term><listitem><para>λ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\land</primary></indexterm><literal>\land</literal> +</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>⟨ 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>{ 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>[ 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>⌈ 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>≤ 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><para>⇝ Squiggly right arrow (relation). Not available in plain &tex;. In &latex; you need to 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>⇐ 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>← 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>↽ 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>↼ 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>⇔ 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>↔ 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>≤ 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>⌊ Left floor bracket (opening). Matches: <literal>\floor</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lhd</primary></indexterm><literal>\lhd</literal> +</term><listitem><para>◁ Arrowhead, that is, triangle, pointing left (binary). +Not available in plain &tex;. In &latex; you need to 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>≪ 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>¬ 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>⟵ 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>⟷ 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>⟼ 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>⟶ 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>∨ 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>↦ 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><para>℧ Conductance, half-circle rotated capital omega (ordinary). +Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mid</primary></indexterm><literal>\mid</literal> +</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>⊨ 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>∓ Minus or plus (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mu</primary></indexterm><literal>\mu</literal> +</term><listitem><para>μ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nabla</primary></indexterm><literal>\nabla</literal> +</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>♮ Musical natural notation (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ne</primary></indexterm><literal>\ne</literal> +</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>↗ North-east arrow (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\neg</primary></indexterm><literal>\neg</literal> +</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>≠ 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>∋ 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><!-- the "@ "s put in spaces so the not slash doesn't hit the next char. --> +<para>     Long solidus, or slash, used to overstrike a +following operator (relation). +</para> +<para>Many negated operators are available that don’t require <literal>\not</literal>, +particularly with the <filename>amssymb</filename> package. For example, <literal>\notin</literal> +is 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>∉ 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>ν Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\nwarrow</primary></indexterm><literal>\nwarrow</literal> +</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>⊙ 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>∮ 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>Ω uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\omega</primary></indexterm><literal>\omega</literal> +</term><listitem><para>ω Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ominus</primary></indexterm><literal>\ominus</literal> +</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>⊕ 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>⊘ 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>⊗ 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>∋ 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>∥ Parallel (relation). Synonym: <literal>\|</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partial</primary></indexterm><literal>\partial</literal> +</term><listitem><para>∂ Partial differential (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\perp</primary></indexterm><literal>\perp</literal> +</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>ϕ Lowercase 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>Π uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pi</primary></indexterm><literal>\pi</literal> +</term><listitem><para>π Lowercase 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>± Plus or minus (binary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prec</primary></indexterm><literal>\prec</literal> +</term><listitem><para>≺ Precedes (relation). Similar: less than <literal><</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\preceq</primary></indexterm><literal>\preceq</literal> +</term><listitem><para>⪯ Precedes 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>′ Prime, or minute in a time expression (ordinary). +Typically used as a superscript: <literal>$f^\prime$</literal>; <literal>$f^\prime$</literal> +and <literal>$f'$</literal> produce the same result. An advantage of the second +is that <literal>$f'''$</literal> produces the desired symbol, that is, the same +result as <literal>$f^{\prime\prime\prime}$</literal>, but uses rather less +typing. You can only use <literal>\prime</literal> in math mode. Using the right +single quote <literal>'</literal> in text mode produces a different character +(apostrophe). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prod</primary></indexterm><literal>\prod</literal> +</term><listitem><para>∏ Product (operator). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\propto</primary></indexterm><literal>\propto</literal> +</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>Ψ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\psi</primary></indexterm><literal>\psi</literal> +</term><listitem><para>ψ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rangle</primary></indexterm><literal>\rangle</literal> +</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>} 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>] 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>⌉ 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>ℜ 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 need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\revemptyset</primary></indexterm><literal>\revemptyset</literal> +</term><listitem><para>⦰ Reversed empty set symbol (ordinary). Related: +<literal>\varnothing</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>stix</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rfloor</primary></indexterm><literal>\rfloor</literal> +</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>◁ Arrowhead, that is, triangle, pointing right (binary). +Not available in plain &tex;. In &latex; you need to 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>ρ Lowercase 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>⇒ 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>→ 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>⇁ 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>⇀ 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>⇌ 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>↘ Arrow pointing southeast (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\setminus</primary></indexterm><literal>\setminus</literal> +</term><listitem><para>⧵ Set difference, reverse solidus or reverse 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>♯ Musical sharp (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Sigma</primary></indexterm><literal>\Sigma</literal> +</term><listitem><para>Σ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sigma</primary></indexterm><literal>\sigma</literal> +</term><listitem><para>σ Lowercase 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>∼ Similar, in a relation (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\simeq</primary></indexterm><literal>\simeq</literal> +</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>∫ 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>⌣ Upward curving arc, smile (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\spadesuit</primary></indexterm><literal>\spadesuit</literal> +</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>⊓ 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>⊔ 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>⊏ Square subset symbol (relation). Similar: +subset <literal>\subset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubseteq</primary></indexterm><literal>\sqsubseteq</literal> +</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>⊐ Square superset symbol (relation). Similar: +superset <literal>\supset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupseteq</primary></indexterm><literal>\sqsupseteq</literal> +</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>⋆ 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>⊂ Subset (occasionally, is implied by) (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\subseteq</primary></indexterm><literal>\subseteq</literal> +</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>≻ 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>⪰ 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>∑ 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>⊃ Superset (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\supseteq</primary></indexterm><literal>\supseteq</literal> +</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>√ 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>↙ Southwest-pointing arrow (relation). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tau</primary></indexterm><literal>\tau</literal> +</term><listitem><para>τ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\theta</primary></indexterm><literal>\theta</literal> +</term><listitem><para>θ Lowercase 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>× 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>→ 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>⊤ Top, greatest element of a partially ordered set +(ordinary). See also <literal>\bot</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangle</primary></indexterm><literal>\triangle</literal> +</term><listitem><para>△ Triangle (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangleleft</primary></indexterm><literal>\triangleleft</literal> +</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>▷ 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 not-filled underlined arrowhead, that is, +triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to 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 not-filled underlined arrowhead, that is, +triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to 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>⇑ 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>↑ 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>⇕ 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>↕ 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 need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\uplus</primary></indexterm><literal>\uplus</literal> +</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>Υ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\upsilon</primary></indexterm><literal>\upsilon</literal> +</term><listitem><para>υ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varepsilon</primary></indexterm><literal>\varepsilon</literal> +</term><listitem><para>ε Small letter script epsilon (ordinary). This is +more widely used in mathematics than the non-variant lunate epsilon form +<literal>\epsilon</literal> ϵ. Related: set +membership <literal>\in</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vanothing</primary></indexterm><literal>\vanothing</literal> +</term><listitem><para>∅ Empty set symbol. Similar: <literal>\emptyset</literal>. Related: +<literal>\revemptyset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varphi</primary></indexterm><literal>\varphi</literal> +</term><listitem><para>φ Variant on the lowercase 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>ϖ Variant on the lowercase 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>ϱ Variant on the lowercase 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>ς Variant on the lowercase 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>ϑ Variant on the lowercase 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>⊢ 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>∨ 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>‖ Vertical double bar (ordinary). Similar: vertical single +bar <literal>\vert</literal>. +</para> +<para>For a norm symbol, you can use the <filename>mathtools</filename> package and put in +your preamble +<literal>\DeclarePairedDelimiter\norm{\lVert}{\rVert}</literal>. 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>| 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 in your +preamble put +<literal>\DeclarePairedDelimiter\abs{\lvert}{\rvert}</literal>. 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>∧ 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>℘ Weierstrass p (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\wr</primary></indexterm><literal>\wr</literal> +</term><listitem><para>≀ Wreath product (binary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Xi</primary></indexterm><literal>\Xi</literal> +</term><listitem><para>Ξ uppercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\xi</primary></indexterm><literal>\xi</literal> +</term><listitem><para>ξ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\zeta</primary></indexterm><literal>\zeta</literal> +</term><listitem><para>ζ Lowercase Greek letter (ordinary). +</para> +</listitem></varlistentry></variablelist> +<para>The following symbols are most often used in plain text but &latex; +provides versions to use in mathematical text. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\mathdollar</primary></indexterm><literal>\mathdollar</literal> +</term><listitem><para>Dollar sign in math mode: $. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathparagraph</primary></indexterm><literal>\mathparagraph</literal> +</term><listitem><para>Paragraph sign (pilcrow) in math mode, ¶. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathsection</primary></indexterm><literal>\mathsection</literal> +</term><listitem><para>Section sign in math mode §. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathsterling</primary></indexterm><literal>\mathsterling</literal> +</term><listitem><para>Sterling sign in math mode: £. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathunderscore</primary></indexterm><literal>\mathunderscore</literal> +</term><listitem><para>Underscore in math mode: _. +</para> +</listitem></varlistentry></variablelist> + + +<sect2 label="16.2.1" id="Blackboard-bold"> +<title>Blackboard bold</title> + +<indexterm role="cp"><primary>blackboard bold</primary></indexterm> +<indexterm role="cp"><primary>doublestruck</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\usepackage{amssymb} % in preamble + ... +\mathbb{<replaceable>uppercase-letter</replaceable>} +</screen> +<para>Provide blackboard bold symbols, sometimes also known as doublestruck +letters, used to denote number sets such as the natural numbers, the +integers, etc. +</para> +<para>Here +</para> +<screen>\( \forall n \in \mathbb{N}, n^2 \geq 0 \) +</screen> +<para>the <literal>\mathbb{N}</literal> gives blackboard bold symbol ℕ +representing the natural numbers. +</para> +<para>If you use other than an uppercase letter then you do not get an error +but you get strange results, including unexpected characters. +</para> +<para>There are packages that give access to symbols other than just the +capital letters; look on CTAN. +</para> + +</sect2> +<sect2 label="16.2.2" id="Calligraphic"> +<title>Calligraphic</title> + +<indexterm role="cp"><primary>calligraphic fonts</primary></indexterm> +<indexterm role="cp"><primary>script fonts</primary></indexterm> +<indexterm role="cp"><primary>fonts, script</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\mathcal{<replaceable>uppercase-letters</replaceable>} +</screen> +<para>Use a script-like font. +</para> +<para>In this example the graph identifier is output in a cursive font. +</para> +<screen>Let the graph be \( \mathcal{G} \). +</screen> +<para>If you use something other than an uppercase letter then you do not get +an error. Instead you get unexpected output. For instance, +<literal>\mathcal{g}</literal> outputs a close curly brace symbol, while +<literal>\mathcal{+}</literal> outputs a plus sign. +</para> + +</sect2> +<sect2 label="16.2.3" id="_005cboldmath-_0026-_005cunboldmath"> +<title><literal>\boldmath</literal> & <literal>\unboldmath</literal></title> + +<indexterm role="cp"><primary>boldface mathematics</primary></indexterm> +<indexterm role="cp"><primary>symbols, boldface</primary></indexterm> +<indexterm role="fn"><primary>\boldmath</primary></indexterm> +<indexterm role="fn"><primary>\unboldmath</primary></indexterm> + +<para>Synopsis (used in paragraph mode or LR mode): +</para> +<screen>\boldmath \( <replaceable>math</replaceable> \) +</screen> +<para>or +</para> +<screen>\unboldmath \( <replaceable>math</replaceable> \) +</screen> +<indexterm role="fn"><primary>\boldmath</primary></indexterm> +<indexterm role="fn"><primary>\unboldmath</primary></indexterm> +<para>Declarations to change the letters and symbols in <replaceable>math</replaceable> to be in +a bold font, or to countermand that and bring back the regular +(non-bold) default. They must be used when not in math mode or display +math mode (see <link linkend="Modes">Modes</link>). Both commands are fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>In this example each <literal>\boldmath</literal> command takes place inside an +<literal>\mbox</literal>, +</para> +<screen>we have $\mbox{\boldmath \( v \)} = 5\cdot\mbox{\boldmath \( u \)$}$ +</screen> +<para>which means <literal>\boldmath</literal> is only called in a text mode, here LR +mode, and explains why &latex; must switch to math mode to set <literal>v</literal> +and <literal>u</literal>. +</para> +<para>If you use either command inside math mode, as with <literal>Trouble: \( +\boldmath x \)</literal>, then you get something like ‘<literal>LaTeX Font Warning: +Command \boldmath invalid in math mode on input line 11</literal>’ and ‘<literal>LaTeX +Font Warning: Command \mathversion invalid in math mode on input line +11</literal>’. +</para> +<indexterm role="cp"><primary>package, <literal>bm</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>bm</literal> package</primary></indexterm> + +<para>There are many issues with <literal>\boldmath</literal>. New documents should use +the <filename>bm</filename> package provided by the &latex; Project team. A complete +description is outside the scope of this document (see the full +documentation on CTAN) but even this small example +</para> +<screen>\usepackage{bm} % in preamble +... +we have $\bm{v} = 5\cdot\bm{u}$ +</screen> +<para>shows that it is an improvement over <literal>\boldmath</literal>. +</para> + +</sect2> +<sect2 label="16.2.4" id="Dots"> +<title>Dots, horizontal or vertical</title> + +<indexterm role="cp"><primary>ellipses</primary></indexterm> +<indexterm role="cp"><primary>dots</primary></indexterm> + +<para>Ellipses are the three dots (usually three) indicating that a pattern +continues. +</para> +<screen>\begin{array}{cccc} + a_{0,0} &a_{0,1} &a_{0,2} &\ldots \\ + a_{1,0} &\ddots \\ + \vdots +\end{array} +</screen> +<para>&latex; provides these. +</para> +<variablelist><anchor id="ellipses-cdots"/><varlistentry><term><indexterm role="fn"><primary>\cdots</primary></indexterm><literal>\cdots</literal> +</term><listitem><para>Horizontal ellipsis with the dots raised to the center of the line, as +in ⋯. Used as: <literal>\( a_0\cdot a_1\cdots a_{n-1} +\)</literal>. +</para> +<anchor id="ellipses-ddots"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ddots</primary></indexterm><literal>\ddots</literal> +</term><listitem><para>Diagonal ellipsis, ⋱. See the above array example for a +usage. +</para> +<anchor id="ellipses-ldots"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ldots</primary></indexterm><literal>\ldots</literal> +</term><listitem><para>Ellipsis on the baseline, …. Used as: <literal>\( +x_0,\ldots x_{n-1} \)</literal>. Another example is the above array example. A +synonym is <literal>\mathellipsis</literal>. A synonym from the <filename>amsmath</filename> +package is <literal>\hdots</literal>. +</para> +<para>You can also use this command outside of mathematical text, as in +<literal>The gears, brakes, \ldots{} are all broken</literal>. (In a paragraph +mode or LR mode a synonym for <literal>\ldots</literal> is <literal>\dots</literal>.) +</para> +<anchor id="ellipses-vdots"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vdots</primary></indexterm><literal>\vdots</literal> +</term><listitem><para>Vertical ellipsis, ⋮. See the above array example for a +usage. +</para> +</listitem></varlistentry></variablelist> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>The <filename>amsmath</filename> package has the command <literal>\dots</literal> to semantically +mark up ellipses. This example produces two different-looking outputs +for the first two uses of the <literal>\dots</literal> command. +</para> +<screen>\usepackage{amsmath} % in preamble + ... +Suppose that \( p_0, p_1, \dots, p_{n-1} \) lists all of the primes. +Observe that \( p_0\cdot p_1 \dots \cdot p_{n-1} +1 \) is not a + multiple of any \( p_i \). +Conclusion: there are infinitely many primes \( p_0, p_1, \dotsc \). +</screen> +<para>In the first line &latex; looks to the comma following <literal>\dots</literal> to +determine that it should output an ellipsis on the baseline. The second +line has a <literal>\cdot</literal> following <literal>\dots</literal> so &latex; outputs an +ellipsis that is on the math axis, vertically centered. However, the +third usage has no follow-on character so you have to tell &latex; what +to do. You can use one of the commands: <literal>\dotsc</literal> if you need the +ellipsis appropriate for a comma following, <literal>\dotsb</literal> if you need +the ellipses that fits when the dots are followed by a binary operator +or relation symbol, <literal>\dotsi</literal> for dots with integrals, or +<literal>\dotso</literal> for others. +</para> + +</sect2> +</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> + +<para>These commands produce roman function names in math mode with proper +spacing. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\arccos</primary></indexterm><literal>\arccos</literal> +</term><listitem><para>Inverse cosine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arcsin</primary></indexterm><literal>\arcsin</literal> +</term><listitem><para>Inverse sine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arctan</primary></indexterm><literal>\arctan</literal> +</term><listitem><para>Inverse tangent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arg</primary></indexterm><literal>\arg</literal> +</term><listitem><para>Angle between the real axis and a point in the complex plane +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bmod</primary></indexterm><literal>\bmod</literal> +</term><listitem><para>Binary modulo operator, used as in <literal>\( 5\bmod 3=2 \)</literal> +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cos</primary></indexterm><literal>\cos</literal> +</term><listitem><para>Cosine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cosh</primary></indexterm><literal>\cosh</literal> +</term><listitem><para>Hyperbolic cosine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cot</primary></indexterm><literal>\cot</literal> +</term><listitem><para>Cotangent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\coth</primary></indexterm><literal>\coth</literal> +</term><listitem><para>Hyperbolic cotangent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\csc</primary></indexterm><literal>\csc</literal> +</term><listitem><para>Cosecant +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\deg</primary></indexterm><literal>\deg</literal> +</term><listitem><para>Degrees +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\det</primary></indexterm><literal>\det</literal> +</term><listitem><para>Determinant +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dim</primary></indexterm><literal>\dim</literal> +</term><listitem><para>Dimension +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\exp</primary></indexterm><literal>\exp</literal> +</term><listitem><para>Exponential +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\gcd</primary></indexterm><literal>\gcd</literal> +</term><listitem><para>Greatest common divisor +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hom</primary></indexterm><literal>\hom</literal> +</term><listitem><para>Homomorphism +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\inf</primary></indexterm><literal>\inf</literal> +</term><listitem><para>Infinum +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ker</primary></indexterm><literal>\ker</literal> +</term><listitem><para>Kernel +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lg</primary></indexterm><literal>\lg</literal> +</term><listitem><para>Base 2 logarithm +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lim</primary></indexterm><literal>\lim</literal> +</term><listitem><para>Limit +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\liminf</primary></indexterm><literal>\liminf</literal> +</term><listitem><para>Limit inferior +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\limsup</primary></indexterm><literal>\limsup</literal> +</term><listitem><para>Limit superior +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ln</primary></indexterm><literal>\ln</literal> +</term><listitem><para>Natural logarithm +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\log</primary></indexterm><literal>\log</literal> +</term><listitem><para>Logarithm +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\max</primary></indexterm><literal>\max</literal> +</term><listitem><para>Maximum +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\min</primary></indexterm><literal>\min</literal> +</term><listitem><para>Minimum +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pmod</primary></indexterm><literal>\pmod</literal> +</term><listitem><para>Parenthesized modulus, as used in <literal>\( 5\equiv 2\pmod 3 \)</literal> +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Pr</primary></indexterm><literal>\Pr</literal> +</term><listitem><para>Probability +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sec</primary></indexterm><literal>\sec</literal> +</term><listitem><para>Secant +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sin</primary></indexterm><literal>\sin</literal> +</term><listitem><para>Sine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sinh</primary></indexterm><literal>\sinh</literal> +</term><listitem><para>Hyperbolic sine +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sup</primary></indexterm><literal>\sup</literal> +</term><listitem><para>sup +<!-- don't try to use \sup with dvi/pdf output since that turned into a --> +<!-- Texinfo command and it's not worth hassling with different versions --> +<!-- when it's just three roman letters anyway. --> +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tan</primary></indexterm><literal>\tan</literal> +</term><listitem><para>Tangent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tanh</primary></indexterm><literal>\tanh</literal> +</term><listitem><para>Hyperbolic tangent +</para> +</listitem></varlistentry></variablelist> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>The <filename>amsmath</filename> package adds improvements on some of these, and also +allows you to define your own. The full documentation is on CTAN, but +briefly, you can define an identity operator with +<literal>\DeclareMathOperator{\identity}{id}</literal> that is like the ones +above but prints as ‘<literal>id</literal>’. The starred form +<literal>\DeclareMathOperator*{\op}{op}</literal> sets any limits above and +below, as is traditional with <literal>\lim</literal>, <literal>\sup</literal>, or <literal>\max</literal>. +</para> + +</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> + +<para>&latex; provides a variety of commands for producing accented letters +in math. These are different from accents in normal text +(see <link linkend="Accents">Accents</link>). +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\acute</primary></indexterm><literal>\acute</literal> +</term><listitem><indexterm role="cp"><primary>acute accent, math</primary></indexterm> +<para>Math acute accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bar</primary></indexterm><literal>\bar</literal> +</term><listitem><indexterm role="cp"><primary>bar-over accent, math</primary></indexterm> +<indexterm role="cp"><primary>macron accent, math</primary></indexterm> +<para>Math bar-over accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\breve</primary></indexterm><literal>\breve</literal> +</term><listitem><indexterm role="cp"><primary>breve accent, math</primary></indexterm> +<para>Math breve accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\check</primary></indexterm><literal>\check</literal> +</term><listitem><indexterm role="cp"><primary>check accent, math</primary></indexterm> +<indexterm role="cp"><primary>háček accent, math</primary></indexterm> +<para>Math háček (check) accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ddot</primary></indexterm><literal>\ddot</literal> +</term><listitem><indexterm role="cp"><primary>double dot accent, math</primary></indexterm> +<para>Math dieresis accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dot</primary></indexterm><literal>\dot</literal> +</term><listitem><indexterm role="cp"><primary>overdot accent, math</primary></indexterm> +<indexterm role="cp"><primary>dot over accent, math</primary></indexterm> +<para>Math dot accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\grave</primary></indexterm><literal>\grave</literal> +</term><listitem><indexterm role="cp"><primary>grave accent, math</primary></indexterm> +<para>Math grave accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\hat</primary></indexterm><literal>\hat</literal> +</term><listitem><indexterm role="cp"><primary>hat accent, math</primary></indexterm> +<indexterm role="cp"><primary>circumflex accent, math</primary></indexterm> +<para>Math hat (circumflex) accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathring</primary></indexterm><literal>\mathring</literal> +</term><listitem><indexterm role="cp"><primary>ring accent, math</primary></indexterm> +<para>Math ring accent <!-- don't bother implementing in texinfo --> +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tilde</primary></indexterm><literal>\tilde</literal> +</term><listitem><indexterm role="cp"><primary>tilde accent, math</primary></indexterm> +<para>Math tilde accent +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vec</primary></indexterm><literal>\vec</literal> +</term><listitem><indexterm role="cp"><primary>vector symbol, math</primary></indexterm> +<para>Math vector symbol +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\widehat</primary></indexterm><literal>\widehat</literal> +</term><listitem><indexterm role="cp"><primary>wide hat accent, math</primary></indexterm> +<para>Math wide hat accent +</para> +</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 +</para> +</listitem></varlistentry></variablelist> +<para>When you are putting an accent on an i or a j, the tradition is to use +one without a dot, <literal>\imath</literal> or <literal>jmath</literal> (see <link linkend="Math-symbols">Math symbols</link>). +</para> + +</sect1> +<sect1 label="16.5" id="Over_002d-and-Underlining"> +<title>Over- and Underlining</title> + +<indexterm role="cp"><primary>overlining</primary></indexterm> +<indexterm role="cp"><primary>underlining</primary></indexterm> + +<para>&latex; provides commands for making overlines or underlines, or +putting braces over or under some material. +</para> +<variablelist> +<varlistentry><term><indexterm role="fn"><primary>\underline{<replaceable>text</replaceable>}</primary></indexterm><literal>\underline{<replaceable>text</replaceable>}</literal> +</term><listitem><para>Underline <replaceable>text</replaceable>. Works inside math mode, and outside. +The line is always completely below the text, taking account of +descenders, so in <literal>\(\underline{y}\)</literal> the line is lower than in +<literal>\(\underline{x}\)</literal>. This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<indexterm role="cp"><primary>package, <literal>ulem</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>ulem</literal> package</primary></indexterm> + +<para>Note that the package <filename>ulem</filename> does text mode underlining and allows +line breaking as well as a number of other features. See the +documentation on CTAN. See also <link linkend="_005chrulefill-_0026-_005cdotfill">\hrulefill & \dotfill</link> for +producing a line, for such things as a signature. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overline{<replaceable>text</replaceable>}</primary></indexterm><literal>\overline{<replaceable>text</replaceable>}</literal> +</term><listitem><para>Put a horizontal line over <replaceable>text</replaceable>. Works inside math mode, and +outside. For example, <literal>\overline{x+y}</literal>. +Note that this differs from the command <literal>\bar</literal> (see <link linkend="Math-accents">Math +accents</link>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\underbrace{<replaceable>math</replaceable>}</literal> +</term><listitem><para>Put a brace under <replaceable>math</replaceable>. For example, this +<literal>(1-\underbrace{1/2)+(1/2}-1/3)</literal> emphasizes the telescoping part. +Attach text to the brace by using subscript, <literal>_</literal>, or superscript, +<literal>^</literal>, as here. +</para> +<screen>\begin{displaymath} + 1+1/2+\underbrace{1/3+1/4}_{>1/2}+ + \underbrace{1/5+1/6+1/7+1/8}_{>1/2}+\cdots +\end{displaymath} +</screen> +<para>The superscript appears on top of the expression, and so can look +unconnected to the underbrace. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\overbrace{<replaceable>math</replaceable>}</literal> +</term><listitem><para>Put a brace over <replaceable>math</replaceable>, as with +<literal>\overbrace{x+x+\cdots+x}^{\mbox{\(k\) times}}</literal>. See also +<literal>\underbrace</literal>. +</para> +</listitem></varlistentry></variablelist> +<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm> + +<para>The package <filename>mathtools</filename> adds an over- and underbrace, as well as +some improvements on the braces. See the documentation on CTAN. +</para> + +</sect1> +<sect1 label="16.6" 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>When typesetting mathematics, &latex; puts in spacing according to the +normal rules for mathematics texts. If you enter <literal>y=m x</literal> then +&latex; ignores the space and in the output the m is next to the x, +as <inlineequation><mathphrase>y=mx</mathphrase></inlineequation>. +</para> +<para>But &latex;’s rules sometimes need tweaking. For example, in an +integral the tradition is to put a small extra space between the +<literal>f(x)</literal> and the <literal>dx</literal>, here done with the <literal>\,</literal> command. +</para> +<screen>\int_0^1 f(x)\,dx +</screen> +<para>&latex; provides the commands that follow for use in math mode. Many +of these spacing definitions are expressed in terms of the math unit +<firstterm>mu</firstterm>. It is defined as 1/18em, where the em is taken from the +current math symbols family (see <link linkend="Units-of-length">Units of length</link>). Thus, a +<literal>\thickspace</literal> is something like 5/18 times the width of +a ‘<literal>M</literal>’. +</para> +<variablelist><varlistentry><term><literal>\;</literal> +</term><listitem><indexterm role="fn"><primary>\;</primary></indexterm> +<indexterm role="fn"><primary>\thickspace</primary></indexterm> +<anchor id="spacing-in-math-mode-thickspace"/><para>Synonym: <literal>\thickspace</literal>. Normally <literal>5.0mu plus 5.0mu</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> +<indexterm role="fn"><primary>\medspace</primary></indexterm> +<anchor id="spacing-in-math-mode-medspace"/><para>Synonym: <literal>\medspace</literal>. Normally <literal>4.0mu plus 2.0mu minus 4.0mu</literal>. +Math mode only. +</para> +</listitem></varlistentry><varlistentry><term><literal>\,</literal> +</term><listitem><indexterm role="fn"><primary>\,</primary></indexterm> +<indexterm role="fn"><primary>\thinspace</primary></indexterm> +<indexterm role="cp"><primary>thin space</primary></indexterm> +<anchor id="Spacing-in-math-mode_002f_005cthinspace"/><anchor id="spacing-in-math-mode-thinspace"/><para>Synonym: <literal>\thinspace</literal>. Normally <literal>3mu</literal>, which is 1/6em. +Can be used in both math mode and text mode (see <link linkend="_005cthinspace-_0026-_005cnegthinspace">\thinspace & +\negthinspace</link>). +</para> +<para>This space is widely used, for instance between the function and the +infinitesimal in an integral <literal>\int f(x)\,dx</literal> and, if an author does +this, before punctuation in a displayed equation. +</para> +<screen>The antiderivative is +\begin{equation} + 3x^{-1/2}+3^{1/2}\,. +\end{equation} +</screen> +</listitem></varlistentry><varlistentry><term><literal>\!</literal> +</term><listitem><indexterm role="fn"><primary>\!</primary></indexterm> +<indexterm role="fn"><primary>\negthinspace</primary></indexterm> +<indexterm role="cp"><primary>thin space, negative</primary></indexterm> +<anchor id="spacing-in-math-mode-negthinspace"/><para>A negative thin space. Normally <literal>-3mu</literal>. The <literal>\!</literal> command is +math mode only but the <literal>\negthinspace</literal> command is available for +text mode (see <link linkend="_005cthinspace-_0026-_005cnegthinspace">\thinspace & \negthinspace</link>). +</para> +</listitem></varlistentry><varlistentry><term><literal>\quad</literal> +</term><listitem><indexterm role="cp"><primary>quad</primary></indexterm> +<indexterm role="fn"><primary>\quad</primary></indexterm> +<anchor id="spacing-in-math-mode-quad"/><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> +<anchor id="spacing-in-math-mode-qquad"/><para>A length of 2 quads, that is, 36mu = 2em. It is available in +both text and math mode. +</para></listitem></varlistentry></variablelist> + + +<sect2 label="16.6.1" id="_005csmash"> +<title><literal>\smash</literal></title> + +<indexterm role="cp"><primary>vertical spacing, math mode</primary></indexterm> +<indexterm role="cp"><primary>math mode, vertical space</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\smash{<replaceable>subformula</replaceable>} +</screen> +<para>Typeset <replaceable>subformula</replaceable> as if its height and depth were zero. +</para> +<para>In this example the exponential is so tall that without the +<literal>\smash</literal> command &latex; would separate its line from the line +above it, and the uneven line spacing might be unsightly. +</para> +<screen>To compute the tetration $\smash{2^{2^{2^2}}}$, +evaluate from the top down, as $2^{2^4}=2^{16}=65536$. +</screen> +<para>(Because of the <literal>\smash</literal> the printed expression could run into the +line above so you may want to wait until the final version of the +document to make such adjustments.) +</para> +<para>This pictures the effect of <literal>\smash</literal> by using <literal>\fbox</literal> to +surround the box that &latex; will put on the line. The +<literal>\blackbar</literal> command makes a bar extending from 10 points below +the baseline to 20 points above. +</para> +<screen>\newcommand{\blackbar}{\rule[-10pt]{5pt}{30pt}} +\fbox{\blackbar} +\fbox{\smash{\blackbar}} +</screen> +<para>The first box that &latex; places is 20 points high and +10 points deep. But the second box is treated by &latex; as +having zero height and zero depth, despite that the ink printed on the +page still extends well above and below the line. +</para> +<para>The <literal>\smash</literal> command appears often in mathematics to adjust the +size of an element that surrounds a subformula. Here the first radical +extends below the baseline while the second lies just on the baseline. +</para> +<screen>\begin{equation} +\sqrt{\sum_{0\leq k< n} f(k)} +\sqrt{\vphantom{\sum}\smash{\sum_{0\leq k< n}} f(k)} +\end{equation} +</screen> +<para>Note the use of <literal>\vphantom</literal> to give the <literal>\sqrt</literal> command an +argument with the height of the <literal>\sum</literal> (see <link linkend="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom">\phantom & \vphantom +& \hphantom</link>). +</para> +<para>While most often used in mathematics, the <literal>\smash</literal> command can +appear in other contexts. However, it doesn’t change into horizontal +mode. So if it starts a paragraph then you should first put a +<literal>\leavevmode</literal>, as in the bottom line below. +</para> +<screen>xxx xxx xxx + +\smash{yyy} % no paragraph indent + +\leavevmode\smash{zzz} % usual paragraph indent +</screen> +<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm> + +<para>The package <literal>mathtools</literal> has operators that provide even finer +control over smashing a subformula box. +</para> + +</sect2> +<sect2 label="16.6.2" id="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom"> +<title><literal>\phantom</literal> & <literal>\vphantom</literal> & <literal>\hphantom</literal></title> + +<indexterm role="cp"><primary>spacing, math mode</primary></indexterm> +<indexterm role="cp"><primary>horizontal spacing</primary></indexterm> +<indexterm role="cp"><primary>vertical spacing</primary></indexterm> +<indexterm role="cp"><primary>math mode, spacing</primary></indexterm> +<indexterm role="cp"><primary>invisible character</primary></indexterm> +<indexterm role="cp"><primary>character, invisible</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\phantom{<replaceable>subformula</replaceable>} +</screen> +<para>or +</para> +<screen>\vphantom{<replaceable>subformula</replaceable>} +</screen> +<para>or +</para> +<screen>\hphantom{<replaceable>subformula</replaceable>} +</screen> +<para>The <literal>\phantom</literal> command creates a box with the same height, depth, +and width as <replaceable>subformula</replaceable>, but empty. That is, this command causes +&latex; to typeset the box but not its ink. The <literal>\vphantom</literal> +variant also produces an invisible box with the same height and depth as +<replaceable>subformula</replaceable>, but it has width zero. And <literal>\hphantom</literal> makes a +box with the same width as <replaceable>subformula</replaceable> but with height and depth +zero. +</para> +<para>Without the <literal>\vphantom</literal> in this example, the top bars of the two +square roots would be at different heights. +</para> +<screen>\( \sqrt{\vphantom{a^3}a}\cdot\sqrt{a^3} \) +</screen> +<para>The <literal>\vphantom{a^3}</literal> causes the first <literal>\sqrt</literal> to have inside +it a box of the same height as the second <literal>\sqrt</literal>, so &latex; +makes the bars align. +</para> +<para>These commands often are combined with <literal>\smash</literal>. See <link linkend="_005csmash">\smash</link> +for another example of the use of <literal>\vphantom</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>mathtools</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mathtools</literal> package</primary></indexterm> + +<para>The three phantom commands appear often but note that &latex; provides +a suite of other commands to work with box sizes that may be more +convenient, including <literal>\makebox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link>) as well +as <literal>\settodepth</literal> (see <link linkend="_005csettodepth">\settodepth</link>), <literal>\settoheight</literal> +(see <link linkend="_005csettoheight">\settoheight</link>), and <literal>\settowidth</literal> (see <link linkend="_005csettowidth">\settowidth</link>). +In addition, the <filename>mathtools</filename> package has many commands that offer +fine-grained control over spacing. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>All three commands produce an ordinary box, without any special +mathematics status. So to do something like attaching a superscript you +should give it such a status, for example with the <literal>\operatorname</literal> +command from the package <filename>amsmath</filename>. +</para> +<para>While most often used in mathematics, these three can appear in other +contexts. However, they don’t cause &latex; to change into horizontal +mode. So if one of these starts a paragraph then you should prefix it +with <literal>\leavevmode</literal>. +</para> + +</sect2> +</sect1> +<sect1 label="16.7" id="Math-miscellany"> +<title>Math miscellany</title> + +<indexterm role="cp"><primary>math miscellany</primary></indexterm> + +<para>&latex; contains a wide variety of mathematics facilities. Here are +some that don’t fit into other categories. +</para> + + +<sect2 label="16.7.1" id="Colon-character-_0026-_005ccolon"> +<title>Colon character <literal>:</literal> & <literal>\colon</literal></title> + +<indexterm role="cp"><primary>:</primary></indexterm> +<indexterm role="cp"><primary>colon character</primary></indexterm> +<indexterm role="fn"><primary>:</primary></indexterm> +<indexterm role="fn"><primary>\colon</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>: +\colon +</screen> +<para>In mathematics, the colon character, <literal>:</literal>, is a relation. +</para> +<screen>With side ratios \( 3:4 \) and \( 4:5 \), the triangle is right. +</screen> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>Ordinary &latex; defines <literal>\colon</literal> to produce the colon character +with the spacing appropriate for punctuation, as in set-builder notation +<literal>\{x\colon 0\leq x<1\}</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>But the widely-used <filename>amsmath</filename> package defines <literal>\colon</literal> for use +in the definition of functions <literal>f\colon D\to C</literal>. So if you want +the colon character as a punctuation then use <literal>\mathpunct{:}</literal>. +</para> + +</sect2> +<sect2 label="16.7.2" id="_005c_002a"> +<title><literal>\*</literal></title> + +<indexterm role="cp"><primary>multiplication, discretionary</primary></indexterm> +<indexterm role="cp"><primary>breaks, multiplication discretionary</primary></indexterm> +<indexterm role="cp"><primary>line breaks, multiplication discretionary</primary></indexterm> +<indexterm role="cp"><primary>discretionary breaks, multiplication</primary></indexterm> +<indexterm role="fn"><primary>\*</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\* +</screen> +<para>A multiplication symbol that allows a line break. If there is a break +then &latex; puts a <literal>\times</literal> symbol, ×, before +that break. +</para> +<para>In <literal>\( A_1\* A_2\* A_3\* A_4 \)</literal>, if there is no line break then +&latex; outputs it as though it were <literal>\( A_1 A_2 A_3 A_4 \)</literal>. If +a line break does happen, for example between the two middle ones, then +&latex; sets it like <literal>\( A_1 A_2 \times \)</literal>, followed by the +break, followed by <literal>\( A_3 A_4 \)</literal>. +</para> + +</sect2> +<sect2 label="16.7.3" id="_005cfrac"> +<title><literal>\frac</literal></title> + +<indexterm role="cp"><primary>fraction</primary></indexterm> +<indexterm role="fn"><primary>\frac</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\frac{<replaceable>numerator</replaceable>}{<replaceable>denominator</replaceable>} +</screen> +<para>Produces the fraction. Used as: <literal>\begin{displaymath} +\frac{1}{\sqrt{2\pi\sigma}} \end{displaymath}</literal>. In inline math +mode it comes out small; see the discussion of <literal>\displaystyle</literal> +(see <link linkend="Math-formulas">Math formulas</link>). +</para> + +</sect2> +<sect2 label="16.7.4" id="_005cleft-_0026-_005cright"> +<title><literal>\left</literal> & <literal>\right</literal></title> + +<indexterm role="cp"><primary>delimiters, paired</primary></indexterm> +<indexterm role="cp"><primary>paired delimiters</primary></indexterm> +<indexterm role="cp"><primary>matching parentheses</primary></indexterm> +<indexterm role="cp"><primary>matching brackets</primary></indexterm> +<indexterm role="cp"><primary>null delimiter</primary></indexterm> +<indexterm role="fn"><primary>\left</primary></indexterm> +<indexterm role="fn"><primary>\right</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\left <replaceable>delimiter1</replaceable> ... \right <replaceable>delimiter2</replaceable> +</screen> +<para>Make matching parentheses, braces, or other delimiters. The delimiters +are sized according to the math they enclose. This makes a unit vector +surrounded by appropriate-height parentheses. +</para> +<screen>\begin{equation} + \left(\begin{array}{c} + 1 \\ + 0 \\ + \end{array}\right) +</screen> +<para>Every <literal>\left</literal> must have a matching <literal>\right</literal>. Leaving out the +<literal>\left(</literal> in the above gets ‘<literal>Extra \right</literal>’. Leaving off the +<literal>\right)</literal> gets ‘<literal>You can't use `\eqno' in math mode</literal>’. +</para> +<para>However, the two delimiters <replaceable>delimiter1</replaceable> and <replaceable>delimiter2</replaceable> need +not match. A common case is that you want an unmatched brace, as +below. Use a period, ‘<literal>.</literal>’, as a null delimiter. +</para> +<screen>\begin{equation} + f(n)=\left\{\begin{array}{ll} + 1 &\mbox{--if \(n=0\)} \\ + f(n-1)+3n^2 &\mbox{--else} + \end{array}\right. +\end{equation} +</screen> +<para>Note that to get a curly brace as a delimiter you must prefix it with a +backslash, <literal>\{</literal>. +</para> + +</sect2> +<sect2 label="16.7.5" id="_005csqrt"> +<title><literal>\sqrt</literal></title> + +<indexterm role="cp"><primary>square root</primary></indexterm> +<indexterm role="cp"><primary>roots</primary></indexterm> +<indexterm role="cp"><primary>radical</primary></indexterm> +<indexterm role="fn"><primary>\sqrt</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\sqrt{<replaceable>arg</replaceable>} +\sqrt[<replaceable>root-number</replaceable>]{<replaceable>arg</replaceable>} +</screen> +<para>The square root, or optionally other roots, of <replaceable>arg</replaceable>. The optional +argument <replaceable>root-number</replaceable> gives the root, i.e., enter the cube root of +<literal>x+y</literal> as <literal>\sqrt[3]{x+y}</literal>. +The radical grows with the size of <replaceable>arg</replaceable> (as the height of the +radical grows, the angle on the leftmost part gets steeper, until for +a large enough <literal>arg</literal>, it is vertical). +</para> +<para>&latex; has a separate <literal>\surd</literal> character (see <link linkend="Math-symbols">Math symbols</link>). +</para> + +</sect2> +<sect2 label="16.7.6" id="_005cstackrel"> +<title><literal>\stackrel</literal></title> + +<indexterm role="cp"><primary>stack math</primary></indexterm> +<indexterm role="cp"><primary>relation, text above</primary></indexterm> +<indexterm role="fn"><primary>\stackrel</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\stackrel{<replaceable>text</replaceable>}{<replaceable>relation</replaceable>} +</screen> +<para>Put <replaceable>text</replaceable> above <replaceable>relation</replaceable>. To put a function name above an +arrow enter <literal>\stackrel{f}{\longrightarrow}</literal>. +</para> + +</sect2> +</sect1> +</chapter> +<chapter label="17" id="Modes"> +<title>Modes</title> + +<indexterm role="cp"><primary>modes</primary></indexterm> + +<para>As &latex; processes your document, at any point it is in one of six +modes. They fall into three categories of two each, the horizontal +modes, the math modes, and the vertical modes. Some commands only work +in one mode or another (in particular, many commands only work in one of +the math modes), and error messages will refer to these. +</para> +<itemizedlist><listitem><anchor id="modes-paragraph-mode"/><indexterm role="cp"><primary>paragraph mode</primary></indexterm> +<para><firstterm>Paragraph mode</firstterm> is what &latex; is in when processing ordinary +text. It breaks the input text into lines and breaks the lines into +pages. This is the mode &latex; is in most of the time. +</para> +<indexterm role="cp"><primary>left-to-right mode</primary></indexterm> +<indexterm role="cp"><primary>LR mode</primary></indexterm> +<anchor id="modes-lr-mode"/><para><firstterm>LR mode</firstterm> (for left-to-right mode; in plain &tex; this is called +<firstterm>restricted horizontal mode</firstterm>) is in effect when &latex; starts +making a box with an <literal>\mbox</literal> command. As in paragraph mode, +&latex;’s output is a string of words with spaces between them. Unlike +in paragraph mode, in LR mode &latex; never starts a new line, it just +keeps going from left to right. (Although &latex; will not complain +that the LR box is too long, when it is finished and next tries to put +that box into a line, it could very well complain that the finished LR +box won’t fit there.) +</para> +</listitem><listitem><indexterm role="cp"><primary>math mode</primary></indexterm> +<anchor id="modes-math-mode"/><para><firstterm>Math mode</firstterm> is when &latex; is generating +an inline mathematical formula. +</para> +<indexterm role="cp"><primary>display math mode</primary></indexterm> +<para><firstterm>Display math mode</firstterm> is when &latex; is generating a displayed +mathematical formula. (Displayed formulas differ somewhat from inline +ones. One example is that the placement of the subscript on <literal>\int</literal> +differs in the two situations.) +</para> +</listitem><listitem><indexterm role="cp"><primary>vertical mode</primary></indexterm> +<anchor id="modes-vertical-mode"/><para><firstterm>Vertical mode</firstterm> is when &latex; is building the list of lines and +other material making the output page. This is the mode &latex; is in +when it starts a document. +</para> +<indexterm role="cp"><primary>internal vertical mode</primary></indexterm> +<anchor id="modes-internal-vertical-mode"/><para><firstterm>Internal vertical mode</firstterm> is in effect when &latex; starts making a +<literal>\vbox</literal>. This is the vertical analogue of LR mode. +</para> +</listitem></itemizedlist> +<para>For instance, if you begin a &latex; article with ‘<literal>Let \( x \) be +...</literal>’ then these are the modes: first &latex; starts every document in +vertical mode, then it reads the ‘<literal>L</literal>’ and switches to paragraph +mode, then the next switch happens at the ‘<literal>\(</literal>’ where &latex; +changes to math mode, and then when it leaves the formula it pops +back to paragraph mode. +</para> +<indexterm role="cp"><primary>inner paragraph mode</primary></indexterm> +<indexterm role="cp"><primary>outer paragraph mode</primary></indexterm> +<anchor id="modes-inner-paragraph-mode"/><anchor id="modes-outer-paragraph-mode"/><para>Paragraph mode has two subcases. If you use a <literal>\parbox</literal> command +or a <literal>minipage</literal> then &latex; is put into paragraph mode. But it +will not put a page break here. Inside one of these boxes, called a +<firstterm>parbox</firstterm>, &latex; is in <firstterm>inner paragraph mode</firstterm>. Its more usual +situation, where it can put page breaks, is <firstterm>outer paragraph mode</firstterm> +(see <link linkend="Page-breaking">Page breaking</link>). +</para> + +<sect1 label="17.1" id="_005censuremath"> +<title><literal>\ensuremath</literal></title> + +<para>Synopsis: +</para> +<screen>\ensuremath{<replaceable>formula</replaceable>} +</screen> +<para>Ensure that <replaceable>formula</replaceable> is typeset in math mode. +</para> +<para>For instance, you can redefine commands that ordinarily can be used only +in math mode, so that they can be used both in math and in plain text. +</para> +<screen>\newcommand{\dx}{\ensuremath{dx}} +In $\int f(x)\, \dx$, the \dx{} is an infinitesimal. +</screen> +<para>Caution: the <literal>\ensuremath</literal> command is useful but not a panacea. +</para> +<screen>\newcommand{\alf}{\ensuremath{\alpha}} +You get an alpha in text mode: \alf. +But compare the correct spacing in $\alf+\alf$ with that in \alf+\alf. +</screen> +<para>Best is to typeset math things in a math mode. +</para> + +</sect1> +</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> + +<para>The style of a page determines where &latex; places the components of +that page, such as headers and footers, and the text body. This +includes pages in the main part of the document but also includes +special pages such as the title page of a book, a page from an index, or +the first page of an article. +</para> +<indexterm role="cp"><primary>package, <literal>fancyhdr</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>fancyhdr</literal> package</primary></indexterm> + +<para>The package <filename>fancyhdr</filename> is very helpful for constructing page +styles. See its documentation on CTAN. +</para> + + +<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> + +<para>Synopsis: +</para> +<screen>\maketitle +</screen> +<para>Generate a title. In the standard classes the title appears on a +separate page, except in the <literal>article</literal> class where it is at the top +of the first page. (See <link linkend="Document-class-options">Document class options</link> for information about +the <literal>titlepage</literal> document class option.) +</para> +<para>This example shows <literal>\maketitle</literal> appearing in its usual place, +immediately after <literal>\begin{document}</literal>. +</para> +<screen>\documentclass{article} +\title{Constructing a Nuclear Reactor Using Only Coconuts} +\author{Jonas Grumby\thanks{% + With the support of a Ginger Grant from the Roy Hinkley Society.} \\ + Skipper, \textit{Minnow} + \and + Willy Gilligan\thanks{% + Thanks to the Mary Ann Summers foundation + and to Thurston and Lovey Howell.} \\ + Mate, \textit{Minnow} + } +\date{1964-Sep-26} +\begin{document} +\maketitle +Just sit right back and you'll hear a tale, a tale of a fateful trip. +That started from this tropic port, aboard this tiny ship. The mate was +a mighty sailin' man, the Skipper brave and sure. Five passengers set +sail that day for a three hour tour. A three hour tour. + ... +</screen> +<para>You tell &latex; the information used to produce the title by making +the following declarations. These must come before the +<literal>\maketitle</literal>, either in the preamble or in the document body. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\author{<replaceable>name1</replaceable> \and <replaceable>name2</replaceable> \and ...}</primary></indexterm><literal>\author{<replaceable>name1</replaceable> \and <replaceable>name2</replaceable> \and ...}</literal> +</term><listitem><indexterm role="cp"><primary>author, for titlepage</primary></indexterm> +<indexterm role="fn"><primary>\\ for <literal>\author</literal></primary></indexterm> +<indexterm role="fn"><primary>\and for <literal>\author</literal></primary></indexterm> +<para>Required. Declare the document author or authors. The argument is a +list of authors separated by <literal>\and</literal> commands. To separate lines +within a single author’s entry, for instance to give the author’s +institution or address, use a double backslash, <literal>\\</literal>. If you omit +the <literal>\author</literal> declaration then you get ‘<literal>LaTeX Warning: No +\author given</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\date{<replaceable>text</replaceable>}</primary></indexterm><literal>\date{<replaceable>text</replaceable>}</literal> +</term><listitem><indexterm role="cp"><primary>date, for titlepage</primary></indexterm> +<para>Optional. Declare <replaceable>text</replaceable> to be the document’s date. The <replaceable>text</replaceable> +doesn’t need to be in a date format; it can be any text at all. If you +omit <literal>\date</literal> then &latex; uses the current date (see <link linkend="_005ctoday">\today</link>). +To have no date, instead use <literal>\date{}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\thanks{<replaceable>text</replaceable>}</primary></indexterm><literal>\thanks{<replaceable>text</replaceable>}</literal> +</term><listitem><indexterm role="cp"><primary>thanks, for titlepage</primary></indexterm> +<indexterm role="cp"><primary>credit footnote</primary></indexterm> +<para>Optional. Produce a footnote. You can use it in the author information +for acknowledgements as illustrated above, but you can also use it in +the title, or any place a footnote makes sense. It can be any text at +all so you can use it for any purpose, such as to print an email +address. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\title{<replaceable>text</replaceable>}</primary></indexterm><literal>\title{<replaceable>text</replaceable>}</literal> +</term><listitem><indexterm role="cp"><primary>title, for titlepage</primary></indexterm> +<indexterm role="fn"><primary>\\ for <literal>\title</literal></primary></indexterm> +<para>Required. Declare <replaceable>text</replaceable> to be the title of the document. Get line +breaks inside <replaceable>text</replaceable> with a double backslash, <literal>\\</literal>. If you +omit the <literal>\title</literal> declaration then you get ‘<literal>LaTeX Error: No +\title given</literal>’. +</para> +</listitem></varlistentry></variablelist> +<para>To make your own title page, see <link linkend="titlepage">titlepage</link>. You can either +create this as a one-off or you can include it as part of a renewed +<literal>\maketitle</literal> command. (Many publishers will provide a class to use +in place of <literal>article</literal> that formats the title according to their +house requirements.) +</para> + +</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> + +<para>Synopsis: +</para> +<screen>\pagenumbering{<replaceable>number-style</replaceable>} +</screen> +<para>Specifies the style of page numbers, and resets the page number. The +numbering style is reflected on the page, and also in the table of +contents and other page references. This declaration has global scope +so its effect is not delimited by braces or environments. +</para> +<para>In this example, before the Main section the pages are numbered +‘<literal>a</literal>’, etc. Starting on the page containing that section, the pages +are numbered ‘<literal>1</literal>’, etc. +</para> +<screen>\begin{document}\pagenumbering{alph} + ... +\section{Main}\pagenumbering{arabic} + ... +</screen> +<para>The argument <replaceable>number-style</replaceable> is one of the following (see +also <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>). +</para> +<variablelist><varlistentry><term><literal>arabic</literal> +</term><listitem><para>Arabic numerals: 1, 2, … +</para> +</listitem></varlistentry><varlistentry><term><literal>roman</literal> +</term><listitem><para>lowercase Roman numerals: i, ii, … +</para> +</listitem></varlistentry><varlistentry><term><literal>Roman</literal> +</term><listitem><para>uppercase Roman numerals: I, II, … +</para> +</listitem></varlistentry><varlistentry><term><literal>alph</literal> +</term><listitem><para>lowercase letters: a, b, … If you have more than 26 pages then you +get ‘<literal>LaTeX Error: Counter too large</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><literal>Alph</literal> +</term><listitem><para>uppercase letters: A, B, … If you have more than 26 pages then you +get ‘<literal>LaTeX Error: Counter too large</literal>’. +</para> +</listitem></varlistentry><varlistentry><term><literal>gobble</literal> +</term><listitem><indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm> +<para>&latex; does not output a page number, although it +does get reset. References to that page also are blank. (This does not +work with the popular package <filename>hyperref</filename> so to have the page number +not appear you may want to instead use <literal>\pagestyle{empty}</literal> or +<literal>\thispagestyle{empty}</literal>.) +</para> +</listitem></varlistentry></variablelist> +<para>Traditionally, if a document has front matter—preface, table of +contents, etc.—then it is numbered with lowercase Roman numerals. The +main matter of a document uses arabic. See <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter & \mainmatter +& \backmatter</link>. +</para> +<para>If you want to address where the page number appears on the page, +see <link linkend="_005cpagestyle">\pagestyle</link>. If you want to change the value of page +number then you will manipulate the <literal>page</literal> counter +(see <link linkend="Counters">Counters</link>). +</para> + +</sect1> +<sect1 label="18.3" id="_005cpagestyle"> +<title><literal>\pagestyle</literal></title> + +<indexterm role="fn"><primary>\pagestyle</primary></indexterm> +<indexterm role="cp"><primary>header style</primary></indexterm> +<indexterm role="cp"><primary>footer style</primary></indexterm> +<indexterm role="cp"><primary>running header and footer style</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\pagestyle{<replaceable>style</replaceable>} +</screen> +<para>Declaration that specifies how the page headers and footers are typeset, +from the current page onwards. +</para> +<indexterm role="cp"><primary>package, <literal>fancyhdr</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>fancyhdr</literal> package</primary></indexterm> + +<para>A discussion with an example is below. Note first that the package +<filename>fancyhdr</filename> is now the standard way to manipulate headers and +footers. New documents that need to do anything other than one of the +standard options below should use this package. See its documentation +on CTAN. +</para> +<para>Values for <replaceable>style</replaceable>: +</para> +<variablelist><varlistentry><term><literal>plain</literal> +</term><listitem><para>The header is empty. The footer contains only a page number, centered. +</para> +</listitem></varlistentry><varlistentry><term><literal>empty</literal> +</term><listitem><para>The header and footer is empty. +</para> +</listitem></varlistentry><varlistentry><term><literal>headings</literal> +</term><listitem><para>Put running headers and footers on each page. The document style +specifies what goes in there; see the discussion below. +</para> +</listitem></varlistentry><varlistentry><term><literal>myheadings</literal> +</term><listitem><para>Custom headers, specified via the <literal>\markboth</literal> or the +<literal>\markright</literal> commands. +</para> +</listitem></varlistentry></variablelist> +<para>Some discussion of the motivation for &latex;’s mechanism will help you +work with the options <literal>headings</literal> or <literal>myheadings</literal>. The +document source below produces an article, two-sided, with the pagestyle +<literal>headings</literal>. On this document’s left hand pages, &latex; wants (in +addition to the page number) the title of the current section. On its +right hand pages &latex; wants the title of the current subsection. +When it makes up a page, &latex; gets this information from the +commands <literal>\leftmark</literal> and <literal>\rightmark</literal>. So it is up to +<literal>\section</literal> and <literal>\subsection</literal> to store that information there. +</para> +<screen>\documentclass[twoside]{article} +\pagestyle{headings} +\begin{document} + ... \section{Section 1} ... \subsection{Subsection 1.1} ... +\section{Section 2} + ... +\subsection{Subsection 2.1} + ... +\subsection{Subsection 2.2} + ... +</screen> +<para>Suppose that the second section falls on a left page. Although when the +page starts it is in the first section, &latex; will put +‘<literal>Section 2</literal>’ in the left page header. As to the right header, +if no subsection starts before the end of the right page then &latex; +blanks the right hand header. If a subsection does appear before the +right page finishes then there are two cases. If at least one +subsection starts on the right hand page then &latex; will put in the +right header the title of the first subsection starting on that right +page. If at least one of 2.1, 2.2, …, starts on the left page but +none starts on the right then &latex; puts in the right hand header the +title of the last subsection to start, that is, the one in effect during +the right hand page. +</para> +<para>To accomplish this, in a two-sided article, &latex; has <literal>\section</literal> +issue a command <literal>\markboth</literal>, setting <literal>\leftmark</literal> +to ‘<literal>Section 2</literal>’ and setting <literal>\rightmark</literal> to blank. +And, &latex; has <literal>\subsection</literal> issue a command <literal>\markright</literal>, +setting <literal>\rightmark</literal> to ‘<literal>Subsection 2.1</literal>’, etc. +</para> +<para>Here are the descriptions of <literal>\markboth</literal> and <literal>\markright</literal>: +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\markboth{<replaceable>left-head</replaceable>}{<replaceable>right-head</replaceable>}</primary></indexterm><literal>\markboth{<replaceable>left-head</replaceable>}{<replaceable>right-head</replaceable>}</literal> +</term><listitem><para>Sets both the right hand and left hand heading information for either a +page style of <literal>headings</literal> or <literal>myheadings</literal>. A left hand page +heading <replaceable>left-head</replaceable> is generated by the last <literal>\markboth</literal> +command before the end of the page. A right hand page heading +<replaceable>right-head</replaceable> is generated by the first <literal>\markboth</literal> or +<literal>\markright</literal> that comes on the page if there is one, otherwise by +the last one that came before that page. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\markright{<replaceable>right</replaceable>}</primary></indexterm><literal>\markright{<replaceable>right</replaceable>}</literal> +</term><listitem><para>Sets the right hand page heading, leaving the left unchanged. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="18.4" id="_005cthispagestyle"> +<title><literal>\thispagestyle</literal></title> + +<indexterm role="fn"><primary>\thispagestyle</primary></indexterm> +<indexterm role="cp"><primary>page style, this page</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\thispagestyle{<replaceable>style</replaceable>} +</screen> +<para>Works in the same way as the <literal>\pagestyle</literal> (see <link linkend="_005cpagestyle">\pagestyle</link>), +except that it changes to <replaceable>style</replaceable> for the current page only. This +declaration has global scope, so its effect is not delimited by braces +or environments. +</para> +<para>Often the first page of a chapter or section has a different style. For +example, this &latex; book document has the first page of the first +chapter in <literal>plain</literal> style, as is the default (see <link linkend="Page-styles">Page +styles</link>). +</para> +<screen>\documentclass{book} +\pagestyle{headings} +\begin{document} +\chapter{First chapter} + ... +\chapter{Second chapter}\thispagestyle{empty} + ... +</screen> +<para>The <literal>plain</literal> style has a page number on it, centered in the footer. +To make the page entirely empty, the command +<literal>\thispagestyle{empty}</literal> immediately follows the second +<literal>\chapter</literal>. +</para> + +</sect1> +</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. Some of +these are best suited to mathematical text; see <link linkend="Spacing-in-math-mode">Spacing in +math mode</link>. Some spacing commands are suitable for both regular text +and mathematical text; versions of some of these commands are in this +chapter. +</para> + + +<sect1 label="19.1" id="_005censpace-_0026-_005cquad-_0026-_005cqquad"> +<title><literal>\enspace</literal> & <literal>\quad</literal> & <literal>\qquad</literal></title> + +<indexterm role="fn"><primary>\enspace</primary></indexterm> +<indexterm role="fn"><primary>\quad</primary></indexterm> +<indexterm role="fn"><primary>\qquad</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\enspace +\quad +\qquad +</screen> +<para>Insert a horizontal space of 1/2em, 1em, or 2em. The +em is a length defined by a font designer, often thought of as being the +width of a capital M. One advantage of describing space in ems is +that it can be more portable across documents than an absolute +measurement such as points (see <link linkend="Lengths_002fem">Lengths/em</link>). +</para> +<para>This puts a suitable gap between two graphics. +</para> +<screen>\begin{center} + \includegraphics{womensmile.png}% + \qquad\includegraphics{mensmile.png} +\end{center} +</screen> +<para>See <link linkend="Spacing-in-math-mode">Spacing in math mode</link> for <literal>\quad</literal> and <literal>\qquad</literal>. These +are lengths from centuries of typesetting and so may be a better choice +in many circumstances than arbitrary lengths, such as you get with +<literal>\hspace</literal>. +</para> + +</sect1> +<sect1 label="19.2" id="_005chspace"> +<title><literal>\hspace</literal></title> + +<indexterm role="fn"><primary>\hspace</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\hspace{<replaceable>length</replaceable>} +\hspace*{<replaceable>length</replaceable>} +</screen> +<para>Insert the horizontal space <replaceable>length</replaceable>. The <replaceable>length</replaceable> can be +positive, negative, or zero; adding negative space is like backspacing. +It is a rubber length, that is, it may contain a <literal>plus</literal> or +<literal>minus</literal> component, or both (see <link linkend="Lengths">Lengths</link>). Because the space is +stretchable and shrinkable, it is sometimes called <firstterm>glue</firstterm>. +</para> +<para>This makes a line with ‘<literal>Name:</literal>’ an inch from the right margin. +</para> +<screen>\noindent\makebox[\linewidth][r]{Name:\hspace{1in}} +</screen> +<para>The <literal>*</literal>-version inserts horizontal space that non-discardable. +More precisely, when &tex; breaks a paragraph into lines any white +space—glues and kerns—that come at a line break are discarded. The +<literal>*</literal>-version avoids that (technically, it adds a non-discardable +invisible item in front of the space). +</para> +<para>In this example +</para> +<screen>\parbox{0.8\linewidth}{% + Fill in each blank: Four \hspace*{1in} and seven years ago our + fathers brought forth on this continent, a new \hspace*{1in}, + conceived in \hspace*{1in}, and dedicated to the proposition + that all men are created \hspace*{1in}.} +</screen> +<para>the 1 inch blank following ‘<literal>conceived in</literal>’ falls at the start +of a line. If you erase the <literal>*</literal> then &latex; discards the blank. +</para> +<para>Here, the <literal>\hspace</literal> separates the three graphics. +</para> +<screen>\begin{center} + \includegraphics{lion.png}% comment keeps out extra space + \hspace{1cm minus 0.25cm}\includegraphics{tiger.png}% + \hspace{1cm minus 0.25cm}\includegraphics{bear.png} +\end{center} +</screen> +<para>Because the argument to each <literal>\hspace</literal> has <literal>minus 0.25cm</literal>, +each can shrink a little if the three figures are too wide. But each +space won’t shrink more than 0.25cm (see <link linkend="Lengths">Lengths</link>). +</para> + +</sect1> +<sect1 label="19.3" 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>Synopsis: +</para> +<screen>\hfill +</screen> +<para>Produce a rubber length which has no natural space but that can stretch +horizontally as far as needed (see <link linkend="Lengths">Lengths</link>). +</para> +<para>This creates a one-line paragraph with ‘<literal>Name:</literal>’ on the left side +of the page and ‘<literal>Quiz One</literal>’ on the right. +</para> +<screen>\noindent Name:\hfill Quiz One +</screen> +<indexterm role="fn"><primary>\fill</primary></indexterm> +<para>The <literal>\hfill</literal> command is equivalent to <literal>\hspace{\fill}</literal> and +so the space can be discarded at line breaks. To avoid that instead use +<literal>\hspace*{\fill}</literal> (see <link linkend="_005chspace">\hspace</link>). +</para> +<para>Here the graphs are evenly spaced in the middle of the figure. +</para> +<screen>\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}} + ... +\begin{figure} + \hspace*{\fill}% + \vcenteredhbox{\includegraphics{graph0.png}}% + \hfill\vcenteredhbox{\includegraphics{graph1.png}}% + \hspace*{\fill}% + \caption{Comparison of two graphs} \label{fig:twographs} +\end{figure} +</screen> +<para>Note the <literal>\hspace*</literal>’s where the space could otherwise be dropped. +</para> + +</sect1> +<sect1 label="19.4" id="_005chss"> +<title><literal>\hss</literal></title> + +<indexterm role="fn"><primary>\hss</primary></indexterm> +<indexterm role="cp"><primary>horizontal space</primary></indexterm> +<indexterm role="cp"><primary>horizontal space, stretchable</primary></indexterm> +<indexterm role="cp"><primary>space, inserting horizontal</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\hss +</screen> +<para>Produce a horizontal space that is infinitely shrinkable as well as +infinitely stretchable (this command is a &tex; primitive). &latex; +authors should reach first for the <literal>\makebox</literal> command to get the +effects of <literal>\hss</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link>). +</para> +<para>Here, the first line’s <literal>\hss</literal> makes the Z stick out to the right, +overwriting the Y. In the second line the Z sticks out to the left, +overwriting the X. +</para> +<screen>X\hbox to 0pt{Z\hss}Y +X\hbox to 0pt{\hss Z}Y +</screen> +<para>Without the <literal>\hss</literal> you get something like ‘<literal>Overfull \hbox +(6.11111pt too wide) detected at line 20</literal>’. +</para> + +</sect1> +<sect1 label="19.5" id="_005cspacefactor"> +<title><literal>\spacefactor</literal></title> + +<para>Synopsis: +</para> +<screen>\spacefactor=<replaceable>integer</replaceable> +</screen> +<indexterm role="fn"><primary>\spacefactor</primary></indexterm> +<para>Influence &latex;’s glue stretch and shrink behavior. Most user-level +documents do not use this command. +</para> +<para>While &latex; is laying out the material, it may stretch or shrink the +gaps between words. (This space is not a character; it is called the +<firstterm>interword glue</firstterm>; see <link linkend="_005chspace">\hspace</link>). The <literal>\spacefactor</literal> command +(from Plain &tex;) allows you to, for instance, have the space +after a period stretch more than the space after a word-ending letter. +</para> +<para>After &latex; places each character, or rule or other box, it sets a +parameter called the <firstterm>space factor</firstterm>. If the next thing in the input +is a space then this parameter affects how much stretching or shrinking +can happen. A space factor that is larger than the normal value means +that the glue can stretch more and shrink less. Normally, the space +factor is 1000. This value is in effect following most characters, and +any non-character box or math formula. But it is 3000 after a period, +exclamation mark, or question mark, it is 2000 after a colon, 1500 after +a semicolon, 1250 after a comma, and 0 after a right parenthesis or +bracket, or closing double quote or single quote. Finally, it is 999 +after a capital letter. +</para> +<para>If the space factor <replaceable>f</replaceable> is 1000 then the glue gap will be the +font’s normal space value (for Computer Modern Roman 10 point this is +3.3333 points). Otherwise, if the space factor <replaceable>f</replaceable> is greater +than 2000 then &tex; adds the font’s extra space value (for Computer +Modern Roman 10 point this is 1.11111 points), and then the font’s +normal stretch value is multiplied by <inlineequation><mathphrase>f /1000</mathphrase></inlineequation> and the normal +shrink value is multiplied by <inlineequation><mathphrase>1000/f</mathphrase></inlineequation> (for Computer Modern Roman +10 point these are 1.66666 and 1.11111 points). +</para> +<para>For example, consider the period ending <literal>A man's best friend is his +dog.</literal> After it, &tex; puts in a fixed extra space, and also allows the +glue to stretch 3 times as much and shrink 1/3 as much, as the glue +after <literal>friend</literal>, which does not end in a period. +</para> +<para>The rules for space factors are even more complex because they play +additional roles. In practice, there are two consequences. First, if a +period or other punctuation is followed by a right parenthesis or +bracket, or right single or double quote then the spacing effect of that +period carries through those characters (that is, the following glue +will have increased stretch and shrink). Second, if +punctuation comes after a capital letter then its effect is not in place +so you get an ordinary space. This second case also affects abbreviations +that do not end in a capital letter (see <link linkend="_005c_0040">\@</link>). +</para> +<para>You can only use <literal>\spacefactor</literal> in paragraph mode or LR mode +(see <link linkend="Modes">Modes</link>). You can see the current value with +<literal>\the\spacefactor</literal> or <literal>\showthe\spacefactor</literal>. +</para> +<para>(Comment, not really related to <literal>\spacefactor</literal>: if you get errors +like ‘<literal>You can't use `\spacefactor' in vertical mode</literal>’, or ‘<literal>You +can't use `\spacefactor' in math mode.</literal>’, or ‘<literal>Improper \spacefactor</literal>’ +then you have probably tried to redefine an internal command. +See <link linkend="_005cmakeatletter-_0026-_005cmakeatother">\makeatletter & \makeatother</link>.) +</para> + + + +<sect2 label="19.5.1" id="_005c_0040"> +<title><literal>\@</literal></title> + +<indexterm role="fn"><primary>\@</primary></indexterm> +<indexterm role="fn"><primary>at-sign</primary></indexterm> +<indexterm role="cp"><primary>period, sentence-ending</primary></indexterm> +<indexterm role="cp"><primary>period, abbreviation-ending</primary></indexterm> +<indexterm role="cp"><primary>period, spacing after</primary></indexterm> +<anchor id="_005cAT"/><!-- old name --> + +<para>Synopsis: +</para> +<screen><replaceable>capital-letter</replaceable>\@. +</screen> +<para>Treat a period as sentence-ending, where &latex; would otherwise think +it is part of an abbreviation. &latex; thinks that a period ends an +abbreviation if the period comes after a capital letter, and otherwise +thinks the period ends the sentence. By default, in justifying a line +&latex; adjusts the space after a sentence-ending period (or a question +mark, exclamation point, comma, or colon) more than it adjusts the space +between words (see <link linkend="_005cspacefactor">\spacefactor</link>). +</para> +<para>This example shows the two cases to remember. +</para> +<screen>The songs \textit{Red Guitar}, etc.\ are by Loudon Wainwright~III\@. +</screen> +<para>The second period ends the sentence, despite that it is preceded by a +capital. We tell &latex; that it ends the sentence by putting +<literal>\@</literal> before it. The first period ends the abbreviation +‘<literal>etc.</literal>’ but not the sentence. The backslash-space, <literal>\ </literal>, +produces a mid-sentence space. +</para> +<para>So: if you have a capital letter followed by a period that ends the +sentence, then put <literal>\@</literal> before the period. This holds even if +there is an intervening right parenthesis or bracket, or right single or +double quote, because the spacing effect of that period carries through +those characters. For example, this +</para> +<screen>Use the \textit{Instructional Practices Guide}, +(a book by the MAA)\@. +</screen> +<para>will have correct inter-sentence spacing after the period. +</para> +<para>The <literal>\@</literal> command is only for a text mode. If you use it outside of +a text mode then you get ‘<literal>You can't use `\spacefactor' in vertical +mode</literal>’ (see <link linkend="Modes">Modes</link>). +</para> +<para>Comment: the converse case is a period ending an abbreviation whose last +letter is not a capital letter, and that abbreviation is not the last +word in the sentence. For that case follow the period with a +backslash-space, (<literal>\ </literal>), or a tie, (<literal>~</literal>), or <literal>\@</literal>. +Examples are <literal>Nat.\ Acad.\ Science</literal>, and <literal>Mr.~Bean</literal>, and +<literal>(manure, etc.\@) for sale</literal> (note in the last one that the +<literal>\@</literal> comes before the closing parenthesis). +</para> + +</sect2> +<sect2 label="19.5.2" id="_005cfrenchspacing"> +<title><literal>\frenchspacing</literal></title> + +<indexterm role="fn"><primary>\frenchspacing</primary></indexterm> +<indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm> +<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\frenchspacing +\nonfrenchspacing +</screen> +<para>The first declaration causes &latex; to treat spacing between sentences +in the same way as spacing between words in the middle of a sentence. +The second causes spacing between sentences to stretch or shrink more +(see <link linkend="_005cspacefactor">\spacefactor</link>); this is the default. +</para> +<para>Some typographic traditions, including English, prefer to adjust the +space between sentences (or spaces following a question mark, +exclamation point, comma, or colon) more than the space between words +that are in the middle of a sentence. Declaring <literal>\frenchspacing</literal> +(the command is from Plain &tex;) switches to the tradition that all +spaces are treated equally. +</para> + +</sect2> +<sect2 label="19.5.3" id="_005cnormalsfcodes"> +<title><literal>\normalsfcodes</literal></title> + +<indexterm role="fn"><primary>\normalsfcodes</primary></indexterm> +<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\normalsfcodes +</screen> +<para>Reset the &latex; space factor values to the default +(see <link linkend="_005cspacefactor">\spacefactor</link>). +</para> + +</sect2> +</sect1> +<sect1 label="19.6" id="_005c_0028SPACE_0029"> +<title>Backslash-space, <literal>\ </literal></title> + +<indexterm role="cp"><primary>\NEWLINE</primary></indexterm> +<indexterm role="cp"><primary>\SPACE</primary></indexterm> +<indexterm role="cp"><primary>\TAB</primary></indexterm> + +<para>This section refers to the command consisting of two characters, a +backslash followed by a space. Synopsis: +</para> +<screen>\ +</screen> +<para>Produce a space. By default it produces white space of length +3.33333pt plus 1.66666pt minus 1.11111pt. +</para> +<para>When you type one or more blanks between words, &latex; produces white +space. But that is different than an explicit space. This illustrates. +</para> +<screen>\begin{tabular}{l} +One blank: makes some space \\ +Three blanks: in a row \\ +Three spaces:\ \ \ in a row \\ +\end{tabular} +</screen> +<para>On the first line &latex; puts some space after the colon. On the +second line &latex; collapses the three blanks to output one +whitespace, so you end with the same space after the colon as in the +first line. &latex; would similarly collapse a blank followed by a +tab, or a blank and a newline and a blank. However, the bottom line +asks for three spaces so the white area is wider. That is, the +backslash-space command creates a fixed amount of horizontal space. +(Note that you can define a horizontal space of any width at all with +<literal>\hspace</literal>; see <link linkend="_005chspace">\hspace</link>.) +</para> +<para>The backslash-space command has two main uses. It is often used after +control sequences to keep them from gobbling the space that follows, as +in <literal>\TeX\ is nice</literal>. (But using curly parentheses, as in +<literal>\TeX{} is best</literal>, has the advantage of still working if the next +character is a period.) The other common use is that it marks a period +as ending an abbreviation instead of ending a sentence, as in <literal>So +says Prof.\ Smith</literal> (see <link linkend="_005c_0040">\@</link>). +</para> +<para>Under normal circumstances, <literal>\</literal><keycap>tab</keycap> and <literal>\</literal><keycap>newline</keycap> +are equivalent to backslash-space, <literal>\ </literal>. +</para> +<!-- @PkgIndex{xspace} --> +<!-- Some individual commands, notably those defined with the @code{xspace}, --> +<!-- package do not follow the standard behavior. --> + + +</sect1> +<sect1 label="19.7" id="_007e"> +<title><literal>~</literal></title> + +<indexterm role="fn"><primary>~</primary></indexterm> +<indexterm role="cp"><primary>tie</primary></indexterm> +<indexterm role="cp"><primary>space, hard</primary></indexterm> +<indexterm role="cp"><primary>space, unbreakable</primary></indexterm> +<indexterm role="cp"><primary>NBSP</primary></indexterm> + +<para>Synopsis: +</para> +<screen><replaceable>before</replaceable>~<replaceable>after</replaceable> +</screen> +<para>The tie character, <literal>~</literal>, produces a space between <replaceable>before</replaceable> and +<replaceable>after</replaceable> at which the line will not be broken. By default the white +space has length 3.33333pt plus 1.66666pt minus +1.11111pt (see <link linkend="Lengths">Lengths</link>). +</para> +<para>Here &latex; will not break the line between the final two words. +</para> +<screen>Thanks to Prof.~Lerman. +</screen> +<para>In addition, despite the period, &latex; does not use the +end-of-sentence spacing (see <link linkend="_005c_0040">\@</link>). +</para> +<para>Ties prevent the end of line separation of things where that could cause +confusion. But they also reduce &latex;’s options when it breaks lines +into paragraphs, so you can use too many. They are also matters of +taste, sometimes alarmingly dogmatic taste, among readers. Nevertheless, +here are some usage models, many of them from the &tex;book. +</para> +<itemizedlist><listitem><para>Between an enumerator and its item, such as in references: +<literal>Chapter~12</literal>, or <literal>Theorem~\ref{th:Wilsons}</literal>, or +<literal>Figure~\ref{fig:KGraph}</literal>. When cases are enumerated inline: +<literal>(b)~Show that $f(x)$ is (1)~continuous, and (2)~bounded</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>siunitx</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>siunitx</literal> package</primary></indexterm> + +</listitem><listitem><para>Between a number and its unit: <literal>$745.7.8$~watts</literal> (the +<filename>siunitx</filename> package has a special facility for this) or +<literal>144~eggs</literal>. This includes between a month and a date: +<literal>October~12</literal> or <literal>12~Oct</literal>. In general, in any expressions where +numbers and abbreviations or symbols are separated by a space: +<literal>AD~565</literal>, or <literal>2:50~pm</literal>, or <literal>Boeing~747</literal>, or +<literal>268~Plains Road</literal>, or <literal>\$$1.4$~billion</literal>. +</para> +</listitem><listitem><para>When mathematical phrases are rendered in words: <literal>equals~$n$</literal>, or +<literal>less than~$\epsilon$</literal>, or <literal>given~$X$</literal>, or <literal>modulo~$p^e$ +for all large~$n$</literal> (but compare <literal>is~$15$</literal> with <literal>is $15$~times +the height</literal>). Between mathematical symbols in apposition with nouns: +<literal>dimension~$d$</literal> or <literal>function~$f(x)$</literal> (but compare <literal>with +length $l$~or more</literal>). When a symbol is a tightly bound object of a +preposition: <literal>of~$x$</literal>, or <literal>from $0$ to~$1$</literal>, or <literal>in +common with~$m$</literal>. +</para> +</listitem><listitem><para>Between symbols in series: <literal>$1$,~$2$, or~$3$</literal> or <literal>$1$,~$2$, +\ldots,~$n$</literal>. +</para> +</listitem><listitem><para>Between a person’s forenames and between multiple surnames: +<literal>Donald~E. Knuth</literal>, or <literal>Luis~I. Trabb~Pardo</literal>, or +<literal>Charles~XII</literal> (but you must give TeX places to break the line so +you may do <literal>Charles Louis Xavier~Joseph de~la Vall\'ee~Poussin</literal>). +</para> +</listitem><listitem><para>Before a dash: <literal>pages 12~--14</literal> or <literal>it is~--- it must be +said~--- plausible</literal>. +</para> +</listitem></itemizedlist> + +</sect1> +<sect1 label="19.8" id="_005cthinspace-_0026-_005cnegthinspace"> +<title><literal>\thinspace</literal> & <literal>\negthinspace</literal></title> + +<indexterm role="fn"><primary>\thinspace</primary></indexterm> +<indexterm role="fn"><primary>\negthinspace</primary></indexterm> +<indexterm role="cp"><primary>thin space</primary></indexterm> +<indexterm role="cp"><primary>space, thin</primary></indexterm> +<indexterm role="cp"><primary>thin space, negative</primary></indexterm> +<indexterm role="cp"><primary>space, negative thin</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\thinspace +\negthinspace +</screen> +<para>Produce an unbreakable and unstretchable space of 1/6em and +-1/6em. These are the text mode equivalents of <literal>\,</literal> and +<literal>\!</literal> (see <link linkend="Spacing-in-math-mode_002f_005cthinspace">Spacing in math mode/\thinspace</link>). You can use +<literal>\,</literal> as a synonym for <literal>\thinspace</literal> in text mode. +</para> +<para>The <literal>\negthinspace</literal> command is used in text mode mostly for +fiddling with spaces. One common use of <literal>\thinspace</literal> is as the +space between nested quotes. +</para> +<screen>Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace'' +</screen> +<para>Another use is that some style guides call for a <literal>\thinspace</literal> +between an ellipsis and a sentence ending period (other style guides, +though, think the three dots are quite enough already). Still another +use is between initials, as in <literal>D.\thinspace E.\ Knuth</literal>. +</para> + +</sect1> +<sect1 label="19.9" id="_005c_002f"> +<title><literal>\/</literal></title> + +<indexterm role="fn"><primary>\/</primary></indexterm> +<indexterm role="cp"><primary>italic correction</primary></indexterm> + +<para>Synopsis: +</para> +<screen><replaceable>before-character</replaceable>\/<replaceable>after-character</replaceable> +</screen> +<para>Insert an <firstterm>italic correction</firstterm>, a small space defined by the font +designer for each character, to avoid the character colliding with +whatever follows. When you use <literal>\/</literal>, &latex; takes the correction +from the font metric file, scales it by any scaling that has been +applied to the font, and then inserts that much horizontal space. +</para> +<para>Here, were it not for the <literal>\/</literal>, the <replaceable>before-character</replaceable> +italic f would hit the <replaceable>after-character</replaceable> roman H +</para> +<screen>\newcommand{\companylogo}{{\it f}\/H} +</screen> +<para>because the italic letter leans far to the right. +</para> +<para>If <replaceable>after-character</replaceable> is a period or comma then don’t insert an +italic correction since those punctuation symbols have a very small +height. However, with semicolons or colons as well as with normal +letters, the italic correction can help. +</para> +<para>When you use commands such as <literal>\textit</literal> or <literal>\itshape</literal> to +change fonts, &latex; will automatically insert any needed italic +correction (see <link linkend="Font-styles">Font styles</link>). +</para> +<para>Roman characters can also have an italic correction. An example is in +the name <literal>pdf\/\TeX</literal>. +</para> +<para>There is no concept of italic correction in math mode; spacing is done +in a different way. +</para> + +</sect1> +<sect1 label="19.10" id="_005chrulefill-_0026-_005cdotfill"> +<title><literal>\hrulefill</literal> & <literal>\dotfill</literal></title> + +<indexterm role="fn"><primary>\hrulefill</primary></indexterm> +<indexterm role="fn"><primary>\dotfill</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\hrulefill +\dotfill +</screen> +<para>Produce an infinite horizontal rubber length (see <link linkend="Lengths">Lengths</link>) that +&latex; fills with a rule (that is, a line) or with dots, instead of +white space. +</para> +<para>This outputs a line 2 inches long. +</para> +<screen>Name:~\makebox[2in]{\hrulefill} +</screen> +<para>This example, when placed between blank lines, creates a paragraph that +is left and right justified and where the middle is filled with evenly +spaced dots. +</para> +<screen>\noindent John Aubrey, RN \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 +here +</para> +<screen>\renewcommand{\hrulefill}{% + \leavevmode\leaders\hrule height 1pt\hfill\kern\z@} +</screen> +<para>which changes the default thickness of 0.4pt to 1pt. +Similarly, adjust the dot spacing as with +</para> +<screen>\renewcommand{\dotfill}{% + \leavevmode\cleaders\hb@xt@1.00em{\hss .\hss }\hfill\kern\z@} +</screen> +<para>which changes the default length of 0.33em to 1.00em. +</para> +<para>This example produces a line for a signature. +</para> +<screen>\begin{minipage}{4cm} + \centering + \hrulefill\\ + Signed +\end{minipage} +</screen> +<para>The line is 4cm long. +</para> + +</sect1> +<sect1 label="19.11" id="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip"> +<title><literal>\bigskip</literal> & <literal>\medskip</literal> & <literal>\smallskip</literal></title> + +<para>Synopsis, one of: +</para> +<screen>\bigskip +\medskip +\smallskip +</screen> +<para>Produce an amount of vertical space, large or medium-sized or +small. These commands are fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Here the skip suggests the passage of time (from <emphasis>The Golden Ocean</emphasis> by +O’Brian). +</para> +<screen>Mr Saumarez would have something rude to say to him, no doubt: he +was at home again, and it was delightful. + +\bigskip +``A hundred and fifty-seven miles and one third, in twenty-four hours,'' +said Peter. +</screen> +<para>Each command is associated with a length defined in the document class +file. +</para> +<variablelist><anchor id="bigskip"/><varlistentry><term><indexterm role="fn"><primary>\bigskip</primary></indexterm><literal>\bigskip</literal> +</term><listitem><indexterm role="fn"><primary>\bigskipamount</primary></indexterm> +<para>The same as <literal>\vspace{\bigskipamount}</literal>, ordinarily about one line +space, with stretch and shrink. The default for the <literal>book</literal> and +<literal>article</literal> classes is <literal>12pt plus 4pt minus 4pt</literal>. +</para> +<anchor id="medskip"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\medskip</primary></indexterm><literal>\medskip</literal> +</term><listitem><indexterm role="fn"><primary>\medskipamount</primary></indexterm> +<para>The same as <literal>\vspace{\medskipamount}</literal>, ordinarily about half of a +line space, with stretch and shrink. The default for the <literal>book</literal> +and <literal>article</literal> classes is <literal>6pt plus 2pt minus 2pt</literal>. +</para> +<anchor id="smallskip"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\smallskip</primary></indexterm><literal>\smallskip</literal> +</term><listitem><indexterm role="fn"><primary>\smallskipamount</primary></indexterm> +<para>The same as <literal>\vspace{\smallskipamount}</literal>, ordinarily about a +quarter of a line space, with stretch and shrink. The default for the +<literal>book</literal> and <literal>article</literal> classes is <literal>3pt plus 1pt minus 1pt</literal>. +</para> +</listitem></varlistentry></variablelist> +<para>Because each command is a <literal>\vspace</literal>, if you use on in mid-paragraph +then it will insert its vertical space between the line in which you use +it and the next line, not necessarily at the place that you use it. So +these are best between paragraphs. +</para> +<para>The commands <literal>\bigbreak</literal>, <literal>\medbreak</literal>, and <literal>\smallbreak</literal> +are similar but also suggest to &latex; that this is a good place to +put a page break (see <link linkend="_005cbigbreak-_0026-_005cmedbreak-_0026-_005csmallbreak">\bigbreak & \medbreak & \smallbreak</link>. +</para> + +</sect1> +<sect1 label="19.12" id="_005cbigbreak-_0026-_005cmedbreak-_0026-_005csmallbreak"> +<title><literal>\bigbreak</literal> & <literal>\medbreak</literal> & <literal>\smallbreak</literal></title> + +<para>Synopsis, one of: +</para> +<screen>\bigbreak +\medbreak +\smallbreak +</screen> +<para>Produce a vertical space that is big or medium-sized or small, and +suggest to &latex; that this is a good place to break the page. (The +associated penalties are -200, -100, and -50.) +</para> +<para>See <link linkend="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip">\bigskip & \medskip & \smallskip</link>, for more. These commands +produce the same vertical space but differ in that they also remove a +preceding vertical space if it is less than what they would insert (as +with <literal>\addvspace</literal>). In addition, they terminate a paragraph where +they are used: this example +</para> +<screen>abc\bigbreak def ghi + +jkl mno pqr +</screen> +<para>will output three paragraphs, the first ending in ‘<literal>abc</literal>’ and the +second starting, after an extra vertical space and a paragraph indent, +with ‘<literal>def</literal>’. +</para> + +</sect1> +<sect1 label="19.13" id="_005cstrut"> +<title><literal>\strut</literal></title> + +<indexterm role="fn"><primary>\strut</primary></indexterm> +<indexterm role="cp"><primary>strut</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\strut +</screen> +<para>Ensure that the current line has height at least <literal>0.7\baselineskip</literal> +and depth at least <literal>0.3\baselineskip</literal>. Essentially, &latex; +inserts into the line a rectangle having zero width, +<literal>\rule[-0.3\baselineskip]{0pt}{\baselineskip}</literal> (see <link linkend="_005crule">\rule</link>). +The <literal>\baselineskip</literal> changes with the current font and fontsize. +</para> +<para>In this example the <literal>\strut</literal> keeps the box inside the frame from +having zero height. +</para> +<screen>\setlength{\fboxsep}{0pt}\framebox[2in]{\strut} +</screen> +<para>This example has four lists. In the first there is a much bigger gap +between items 2 and 3 than there is between items 1 and 2. +The second list fixes that with a <literal>\strut</literal> at the end of its first +item’s second line. +</para> +<screen>\setlength{\fboxsep}{0pt} +\noindent\begin{minipage}[t]{0.2\linewidth} +\begin{enumerate} + \item \parbox[t]{15pt}{test \\ test} + \item test + \item test +\end{enumerate} +\end{minipage}% +\begin{minipage}[t]{0.2\linewidth} +\begin{enumerate} + \item \parbox[t]{15pt}{test \\ test\strut} + \item test + \item test +\end{enumerate} +\end{minipage}% +\begin{minipage}[t]{0.2\linewidth} +\begin{enumerate} + \item \fbox{\parbox[t]{15pt}{test \\ test}} + \item \fbox{test} + \item \fbox{test} +\end{enumerate} +\end{minipage}% +\begin{minipage}[t]{0.2\linewidth} +\begin{enumerate} + \item \fbox{\parbox[t]{15pt}{test \\ test\strut}} + \item \fbox{test} + \item \fbox{test} +\end{enumerate} +\end{minipage}% +</screen> +<para>The final two lists use <literal>\fbox</literal> to show what’s happening. The +third list’s <literal>\parbox</literal> goes only to the bottom of its second +‘<literal>test</literal>’, which happens not have any characters that descend below +the baseline. The fourth list adds the strut that gives the needed +extra below-baseline space. +</para> +<indexterm role="cp"><primary>package, <literal>TikZ</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>TikZ</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>Asymptote</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>Asymptote</literal> package</primary></indexterm> + +<para>The <literal>\strut</literal> command is often useful in graphics, such as in +<filename>TikZ</filename> or <filename>Asymptote</filename>. For instance, you may have a command +such as <literal>\graphnode{<replaceable>node-name</replaceable>}</literal> that fits a circle around +<replaceable>node-name</replaceable>. However, unless you are careful the <replaceable>node-name</replaceable>’s +‘<literal>x</literal>’ and ‘<literal>y</literal>’ will produce different-diameter circles because +the characters are different sizes. A careful <literal>\graphnode</literal> might +insert a <literal>\strut</literal>, then <replaceable>node-name</replaceable>, and then draw the circle. +</para> +<para>The general approach of using a zero width <literal>\rule</literal> is useful in +many circumstances. In this table, the zero-width rule keeps the top of +the first integral from hitting the <literal>\hline</literal>. Similarly, the +second rule keeps the second integral from hitting the first. +</para> +<screen>\begin{tabular}{rl} + \textsc{Integral} &\textsc{Value} \\ + \hline + $\int_0^x t\, dt$ &$x^2/2$ \rule{0em}{2.5ex} \\ + $\int_0^x t^2\, dt$ &$x^3/3$ \rule{0em}{2.5ex} +\end{tabular} +</screen> +<para>(Although the line-ending double backslash command has an available +optional argument to put in more vertical room, that won’t work here. +Changing the first double backslash to something like <literal>\\[2.5ex]</literal> +will put the room between the header line and the <literal>\hline</literal>, and the +integral would still hit the line.) +</para> + +</sect1> +<sect1 label="19.14" id="_005cvspace"> +<title><literal>\vspace</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, one of: +</para> +<screen>\vspace{<replaceable>length</replaceable>} +\vspace*{<replaceable>length</replaceable>} +</screen> +<para>Add the vertical space <replaceable>length</replaceable>. The <replaceable>length</replaceable> can be positive, +negative, or zero. It is a rubber length—it may contain a <literal>plus</literal> +or <literal>minus</literal> component (see <link linkend="Lengths">Lengths</link>). +</para> +<para>This puts space between the two paragraphs. +</para> +<screen>And I slept. + +\vspace{1ex plus 0.5ex} +The new day dawned cold. +</screen> +<para>(See <link linkend="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip">\bigskip & \medskip & \smallskip</link> for common inter-paragraph +spaces.) +</para> +<para>The <literal>*</literal>-version inserts vertical space that non-discardable. More +precisely, &latex; discards vertical space at a page break and the +<literal>*</literal>-version causes the space to stay. This example leaves space +between the two questions. +</para> +<screen>Question: Find the integral of \( 5x^4+5 \). + +\vspace*{2cm plus 0.5cm} +Question: Find the derivative of \( x^5+5x+9 \). +</screen> +<para>That space will be present even if the page break happens to fall +between the questions. +</para> +<para>If you use <literal>\vspace</literal> in the middle of a paragraph (i.e., in +horizontal mode) then the space is inserted after the line containing +the <literal>\vspace</literal> command; it does not start a new paragraph at the +<literal>\vspace</literal> command. +</para> +<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> +<sect1 label="19.15" 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>Synopsis: +</para> +<screen>\vfill +</screen> +<para>End the current paragraph and insert a vertical rubber length that is +infinite, so it can stretch or shrink as far as needed +(see <link linkend="Lengths">Lengths</link>). +</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 the starred option +in <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 second ‘<literal>Lost Dog!</literal>’ is exactly +halfway between them. +</para> +<screen>\begin{document} +Lost Dog! +\vfill +Lost Dog! % perfectly in the middle +\vfill +Lost Dog! +\end{document} +</screen> + +</sect1> +<sect1 label="19.16" 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>Synopsis: +</para> +<screen>\addvspace{<replaceable>vert-length</replaceable>} +</screen> +<para>Add a vertical space of <replaceable>vert-length</replaceable>. However, if there are two or +more <literal>\addvspace</literal>’s in a sequence then together they only add the +space needed to make the natural length equal to the maximum of the +<replaceable>vert-length</replaceable>’s in that sequence. This command is fragile +(see <link linkend="_005cprotect">\protect</link>). The <replaceable>vert-length</replaceable> is a rubber length +(see <link linkend="Lengths">Lengths</link>). +</para> +<para>This example illustrates. The <literal>picture</literal> draws a scale. In a +standard &latex; article the length <literal>\baselineskip</literal> is 12pt. +The two rules here are 22pt apart: the sum of the +<literal>\baselineskip</literal> and the 10pt from the first <literal>addvspace</literal>. +</para> +<screen>\documentclass{article} +\usepackage{color} +\begin{document} +\setlength{\unitlength}{2pt}% +\noindent\begin{picture}(0,0)% + \multiput(0,0)(0,-1){25}{{\color{blue}\line(1,0){1}}} + \multiput(0,0)(0,-5){6}{{\color{red}\line(1,0){2}}} +\end{picture}% +\rule{0.25\linewidth}{0.1pt}% +\par\addvspace{10pt}% \addvspace{20pt}% +\par\noindent\rule{0.25\linewidth}{0.1pt}% +\end{document} +</screen> +<para>Now uncomment the second <literal>\addvspace</literal>. It does not make the gap +20pt longer; instead the gap is the sum of <literal>\baselineskip</literal> +and 20pt. So <literal>\addvspace</literal> in a sense does the opposite of +its name — it makes sure that multiple vertical spaces do not +accumulate, but instead that only the largest one is used. +</para> +<para>&latex; uses this command to adjust the vertical space above or below +an environment that starts a new paragraph. For instance, a +<literal>theorem</literal> environment begins and ends with <literal>\addvspace</literal> so +that two consecutive <literal>theorem</literal>’s are separated by one vertical +space, not two. +</para> +<para>A error ‘<literal>Something's wrong--perhaps a missing \item</literal>’ pointing to an +<literal>\addvspace</literal> means that you were not in vertical mode when you hit +this command. One way to change that is to precede <literal>\addvspace</literal> +with a <literal>\par</literal> command (see <link linkend="_005cpar">\par</link>), as in the above example. +</para> + +</sect1> +</chapter> +<chapter label="20" id="Boxes"> +<title>Boxes</title> + +<indexterm role="cp"><primary>boxes</primary></indexterm> + +<!-- xx Expand on boxes and glue, for xref from elsewhere. --> +<para>At its core, &latex; puts things in boxes and then puts the boxes on a +page. So these commands are central. +</para> +<para>There are many packages on CTAN that are useful for manipulating boxes. +One useful adjunct to the commands here is <filename>adjustbox</filename>. +</para> + + +<sect1 label="20.1" id="_005cmbox-_0026-_005cmakebox"> +<title><literal>\mbox</literal> & <literal>\makebox</literal></title> + +<indexterm role="fn"><primary>\mbox</primary></indexterm> +<indexterm role="fn"><primary>\makebox</primary></indexterm> +<indexterm role="cp"><primary>box</primary></indexterm> +<indexterm role="cp"><primary>make a box</primary></indexterm> +<indexterm role="cp"><primary>hyphenation, preventing</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\mbox{<replaceable>text</replaceable>} +\makebox{<replaceable>text</replaceable>} +\makebox[<replaceable>width</replaceable>]{<replaceable>text</replaceable>} +\makebox[<replaceable>width</replaceable>][<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Create a box, a container for material. The <replaceable>text</replaceable> is typeset in +LR mode (see <link linkend="Modes">Modes</link>) so it is not broken into lines. The +<literal>\mbox</literal> command is robust, while <literal>\makebox</literal> is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>Because <literal>text</literal> is not broken into lines, you can use <literal>\mbox</literal> +to prevent hyphenation. In this example, &latex; will not hyphenate +the table name, ‘<literal>T-4</literal>’. +</para> +<screen>See Table~\mbox{T-4} +</screen> +<para>The first two command versions, <literal>\mbox</literal> and <literal>\makebox</literal>, are +roughly equivalent. They create a box just wide enough to contain the +<replaceable>text</replaceable>. (They are like plain &tex;’s <literal>\hbox</literal>.) +</para> +<para>In the third version the optional argument <replaceable>width</replaceable> specifies the +width of the box. Note that the space occupied by the text need not +equal the width of the box. For one thing, <replaceable>text</replaceable> can be too small; +this creates a full-line box +</para> +<screen>\makebox[\linewidth]{Chapter Exam} +</screen> +<para>with ‘<literal>Chapter Exam</literal>’ centered. But <replaceable>text</replaceable> can also be too wide +for <replaceable>width</replaceable>. See the example below of zero-width boxes. +</para> +<anchor id="mbox-makebox-depth"/><anchor id="mbox-makebox-height"/><anchor id="mbox-makebox-width"/><anchor id="mbox-makebox-totalheight"/><para>In the <replaceable>width</replaceable> argument you can use the following lengths that refer +to the dimension of the box that &latex; gets on typesetting +<replaceable>text</replaceable>: <literal>\depth</literal>, <literal>\height</literal>, <literal>\width</literal>, +<literal>\totalheight</literal> (this is the box’s height plus its depth). For +example, to make a box with the text stretched to double the natural +size you can say this. +</para> +<screen>\makebox[2\width]{Get a stretcher} +</screen> +<para>For the fourth command version the optional argument <replaceable>position</replaceable> +gives position of the text within the box. It may take the following +values: +</para> +<variablelist><varlistentry><term><literal>c</literal> +</term><listitem><para>The <replaceable>text</replaceable> is centered (default). +</para> +</listitem></varlistentry><varlistentry><term><literal>l</literal> +</term><listitem><para>The <replaceable>text</replaceable> is flush left. +</para> +</listitem></varlistentry><varlistentry><term><literal>r</literal> +</term><listitem><para>Flush right. +</para> +</listitem></varlistentry><varlistentry><term><literal>s</literal> +</term><listitem><para>Stretch the interword space in <replaceable>text</replaceable> across the entire <replaceable>width</replaceable>. +The <replaceable>text</replaceable> must contain stretchable space for this to work. For +instance, this could head a press release: +<literal>\noindent\makebox[\textwidth][s]{\large\hfil IMMEDIATE\hfil +RELEASE\hfil}</literal> +</para></listitem></varlistentry></variablelist> +<para>A common use of <literal>\makebox</literal> is to make zero-width text boxes. This +puts the value of the quiz questions to the left of those questions. +</para> +<screen>\newcommand{\pts}[1]{\makebox[0em][r]{#1 points\hspace*{1em}}} +\pts{10}What is the air-speed velocity of an unladen swallow? + +\pts{90}An African or European swallow? +</screen> +<para><indexterm role="cp"><primary>package, <literal>TikZ</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>TikZ</literal> package</primary></indexterm> +</para> +<indexterm role="cp"><primary>package, <literal>Asymptote</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>Asymptote</literal> package</primary></indexterm> + +<para>The right edge of the output ‘<literal>10 points </literal>’ (note the ending space) +will be just before the ‘<literal>What</literal>’ (note the space after +‘<literal>points</literal>’). You can use <literal>\makebox</literal> similarly when making +graphics, such as in <filename>TikZ</filename> or <filename>Asymptote</filename>, where you put the +edge of the text at a known location, regardless of the length of that +text. +</para> +<para>For boxes with frames see <link linkend="_005cfbox-_0026-_005cframebox">\fbox & \framebox</link>. For colors +see <link linkend="Colored-boxes">Colored boxes</link>. +</para> +<para>There is a related version of <literal>\makebox</literal> that is used within the +<literal>picture</literal> environment, where the length is given in terms of +<literal>\unitlength</literal> (see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link>). +</para> +<para>If you put a double-backslash into <replaceable>text</replaceable> then &latex; will not +give you a new line; for instance <literal>\makebox{abc def \\ ghi}</literal> +outputs ‘<literal>abc defghi</literal>’ while <literal>\makebox{abc def \par ghi}</literal> +outputs ‘<literal>abc def ghi</literal>’, but neither go to a second line. To get +multiple lines see <link linkend="_005cparbox">\parbox</link> and <link linkend="minipage">minipage</link>. +</para> + +</sect1> +<sect1 label="20.2" id="_005cfbox-_0026-_005cframebox"> +<title><literal>\fbox</literal> & <literal>\framebox</literal></title> + +<indexterm role="fn"><primary>\fbox</primary></indexterm> +<indexterm role="fn"><primary>\framebox</primary></indexterm> + +<para>Synopses, one of: +</para> +<screen>\fbox{<replaceable>text</replaceable>} +\framebox{<replaceable>text</replaceable>} +\framebox[<replaceable>width</replaceable>]{<replaceable>text</replaceable>} +\framebox[<replaceable>width</replaceable>][<replaceable>position</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Create a box with an enclosing frame, four lines surrounding the space. +These commands are the same as <literal>\mbox</literal> and <literal>\makebox</literal> except +for the frame (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link>). The <literal>\fbox</literal> command is +robust, the <literal>\framebox</literal> command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<screen>\fbox{Warning! No work shown, no credit given.} +</screen> +<para>&latex; puts the text into a box that cannot be split or hyphenated. +Around that box, separated from it by a small gap, are four lines making +a frame. +</para> +<para>The first two command invocations, <literal>\fbox{...}</literal> and +<literal>\framebox{...}</literal>, are roughly the same. As to the third and +fourth invocations, the optional arguments allow you to specify the box +width as <replaceable>width</replaceable> and the position of the text inside that box as +<replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link> for the full description but +here is an example creating an empty box that is 1/4in wide. +</para> +<screen>\setlength{\fboxsep}{0pt}\framebox[0.25in]{\strut}} +</screen> +<para>The <literal>\strut</literal> inserts a vertical height of <literal>\baselineskip</literal> +(see <link linkend="_005cstrut">\strut</link>). +</para> +<para>These parameters determine the frame layout. +</para> +<variablelist><anchor id="fbox-framebox-fboxrule"/><varlistentry><term><indexterm role="fn"><primary>\fboxrule</primary></indexterm><literal>\fboxrule</literal> +</term><listitem><indexterm role="fn"><primary>frame, line width</primary></indexterm> +<indexterm role="fn"><primary>frame rule width</primary></indexterm> +<indexterm role="cp"><primary>\fboxrule</primary></indexterm> +<para>The thickness of the lines around the enclosed box. The default is +0.2pt. Change it with a command such as +<literal>\setlength{\fboxrule}{0.8pt}</literal> (see <link linkend="_005csetlength">\setlength</link>). +</para> +<anchor id="fbox-framebox-fboxsep"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\fboxsep</primary></indexterm><literal>\fboxsep</literal> +</term><listitem><indexterm role="fn"><primary>frame, separation from contents</primary></indexterm> +<indexterm role="cp"><primary>\fboxsep</primary></indexterm> +<para>The distance from the frame to the enclosed box. The default is 3pt. +Change it with a command such as <literal>\setlength{\fboxsep}{0pt}</literal> +(see <link linkend="_005csetlength">\setlength</link>). Setting it to 0pt is useful sometimes: +this will put a frame around the picture with no white border. +</para> +<screen>{\setlength{\fboxsep}{0pt} + \framebox{% + \includegraphics[width=0.5\textwidth]{prudence.jpg}}} +</screen> +<para>The extra curly braces keep the effect of the <literal>\setlength</literal> local. +</para> +</listitem></varlistentry></variablelist> +<para>As with <literal>\mbox</literal> and <literal>\makebox</literal>, &latex; will not break lines +in <replaceable>text</replaceable>. But this example has &latex; break lines to make a +paragraph, and then frame the result. +</para> +<screen>\framebox{% + \begin{minipage}{0.6\linewidth} + My dear, here we must run as fast as we can, just to stay in place. + And if you wish to go anywhere you must run twice as fast as that. + \end{minipage}} +</screen> +<para>See <link linkend="Colored-boxes">Colored boxes</link> for colors other than black and white. +</para> +<para>The <literal>picture</literal> environment has a version of this command where the +units depend on <literal>picture</literal>’s <literal>\unitlength</literal> (see <link linkend="_005cframebox-_0028picture_0029">\framebox +(picture)</link>). +</para> + +</sect1> +<sect1 label="20.3" id="_005cparbox"> +<title><literal>\parbox</literal></title> + +<indexterm role="fn"><primary>\parbox</primary></indexterm> +<indexterm role="cp"><primary>paragraph mode</primary></indexterm> +<indexterm role="cp"><primary>paragraph, in a box</primary></indexterm> + +<para>Synopses, one of: +</para> +<screen>\parbox{<replaceable>width</replaceable>}{<replaceable>contents</replaceable>} +\parbox[<replaceable>position</replaceable>]{<replaceable>width</replaceable>}{<replaceable>contents</replaceable>} +\parbox[<replaceable>position</replaceable>][<replaceable>height</replaceable>]{<replaceable>width</replaceable>}{<replaceable>contents</replaceable>} +\parbox[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>}{<replaceable>contents</replaceable>} +</screen> +<para>Produce a box of text that is <replaceable>width</replaceable> wide. Use this command to make +a box of small pieces of text, of a single paragraph. This command is +fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<screen>\begin{picture}(0,0) + ... + \put(1,2){\parbox{1.75in}{\raggedright Because the graph is a line on + this semilog paper, the relationship is + exponential.}} +\end{picture} +</screen> +<para>The <replaceable>contents</replaceable> are processed in a text mode (see <link linkend="Modes">Modes</link>) so +&latex; will break lines to make a paragraph. But it won’t make +multiple paragraphs; for that, use a <literal>minipage</literal> environment +(see <link linkend="minipage">minipage</link>). +</para> +<para>The options for <literal>\parbox</literal> (except for <replaceable>contents</replaceable>) are the same +as those for <literal>minipage</literal>. For convenience a summary of the options +is here but see <link linkend="minipage">minipage</link> for a complete description. +</para> +<para>There are two required arguments. The <replaceable>width</replaceable> is a rigid length +(see <link linkend="Lengths">Lengths</link>). It sets the width of the box into which &latex; +typesets <replaceable>contents</replaceable>. The <replaceable>contents</replaceable> is the text that is placed +in that box. It should not have any paragraph-making components. +</para> +<para>There are three optional arguments, <replaceable>position</replaceable>, <replaceable>height</replaceable>, and +<replaceable>inner-pos</replaceable>. The <replaceable>position</replaceable> gives the vertical alignment of the +<literal>parbox</literal> with respect to the surrounding material. The possible +values are <literal>c</literal> or <literal>m</literal> to make the vertical center of the +<literal>parbox</literal> lines up with the center of the adjacent line (this is the +default), or <literal>t</literal> to match the top line of the <literal>parbox</literal> with +the baseline of the surrounding material, or <literal>b</literal> to match the +bottom line. +</para> +<para>The optional argument <replaceable>height</replaceable> overrides the natural height of the +box. +</para> +<para>The optional argument <replaceable>inner-pos</replaceable> controls the placement of +<replaceable>content</replaceable> inside the <literal>parbox</literal>. Its default is the value of +<replaceable>position</replaceable>. Its possible values are: <literal>t</literal> to put the +<replaceable>content</replaceable> at the top of the box, <literal>c</literal> to put it in the vertical +center, <literal>b</literal> to put it at the bottom of the box, and <literal>s</literal> to +stretch it out vertically (for this, the text must contain vertically +stretchable space). +</para> +</sect1> +<sect1 label="20.4" id="_005craisebox"> +<title><literal>\raisebox</literal></title> + +<indexterm role="fn"><primary>\raisebox</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\raisebox{<replaceable>distance</replaceable>}{<replaceable>text</replaceable>} +\raisebox{<replaceable>distance</replaceable>}[<replaceable>height</replaceable>]{<replaceable>text</replaceable>} +\raisebox{<replaceable>distance</replaceable>}[<replaceable>height</replaceable>][<replaceable>depth</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Raise or lower <replaceable>text</replaceable>. This command is fragile (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This example makes a command for the restriction of a function by +lowering the vertical bar symbol. +</para> +<!-- credit: egreg https://tex.stackexchange.com/a/278631/121234 --> +<screen>\newcommand\restricted[1]{\raisebox{-.5ex}{$|$}_{#1}} +$f\restricted{A}$ +</screen> +<para>The first mandatory argument <replaceable>distance</replaceable> specifies how far to raise +the second mandatory argument <replaceable>text</replaceable>. This is a rigid length +(see <link linkend="Lengths">Lengths</link>). If it is negative then it lowers <replaceable>text</replaceable>. The +<replaceable>text</replaceable> is processed in LR mode so it cannot contain line breaks +(see <link linkend="Modes">Modes</link>). +</para> +<para>The optional arguments <replaceable>height</replaceable> and <replaceable>depth</replaceable> are dimensions. If +they are specified, they override the natural height and depth of the +box &latex; gets by typesetting <replaceable>text</replaceable>. +</para> +<anchor id="raisebox-depth"/><anchor id="raisebox-height"/><anchor id="raisebox-width"/><anchor id="raisebox-totalheight"/><para>In the arguments <replaceable>distance</replaceable>, <replaceable>height</replaceable>, and <replaceable>depth</replaceable> you can +use the following lengths that refer to the dimension of the box that +&latex; gets on typesetting <replaceable>text</replaceable>: <literal>\depth</literal>, <literal>\height</literal>, +<literal>\width</literal>, <literal>\totalheight</literal> (this is the box’s height plus its +depth). +</para> +<para>This will align two graphics on their top (see <link linkend="Graphics">Graphics</link>). +</para> +<!-- credit: FAQ https://texfaq.org/FAQ-topgraph --> +<screen>\usepackage{graphicx} \usepackage{calc} % in preamble + ... +\begin{center} + \raisebox{1ex-\height}{% + \includegraphics[width=0.4\linewidth]{lion.png}} + \qquad + \raisebox{1ex-\height}{% + \includegraphics[width=0.4\linewidth]{meta.png}} +\end{center} +</screen> +<para>The first <literal>\height</literal> is the height of <filename>lion.png</filename> while the +second is the height of <filename>meta.png</filename>. +</para> + +</sect1> +<sect1 label="20.5" id="_005csbox-_0026-_005csavebox"> +<title><literal>\sbox</literal> & <literal>\savebox</literal></title> + +<indexterm role="fn"><primary>\sbox</primary></indexterm> +<indexterm role="fn"><primary>\savebox</primary></indexterm> +<indexterm role="cp"><primary>box, save</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\sbox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>} +\savebox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>} +\savebox{<replaceable>box-cmd</replaceable>}[<replaceable>width</replaceable>]{<replaceable>text</replaceable>} +\savebox{<replaceable>box-cmd</replaceable>}[<replaceable>width</replaceable>][<replaceable>pos</replaceable>]{<replaceable>text</replaceable>} +</screen> +<para>Typeset <replaceable>text</replaceable> just as with <literal>\makebox</literal> (see <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & +\makebox</link>) except that &latex; does not output it but instead saves it +in a storage bin named <replaceable>box-cmd</replaceable>. The bin name <replaceable>box-cmd</replaceable> begins +with a backslash, <literal>\</literal>. You must have previously allocated the bin +<replaceable>box-cmd</replaceable> with <literal>\newsavebox</literal> (see <link linkend="_005cnewsavebox">\newsavebox</link>).The +<literal>\sbox</literal> command is robust while <literal>\savebox</literal> is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>This creates and uses a bin. +</para> +<screen>\newsavebox{\fullname} +\sbox{\fullname}{John Jacob Jingleheimer Schmidt} + ... +\usebox{\fullname}! His name is my name, too! +Whenever we go out, the people always shout! +There goes \\usebox{\fullname}! Ya da da da da da da. +</screen> +<para>One advantage of using and reusing a bin over a <literal>\newcommand</literal> is +efficiency, that &latex; need not repeatedly retypeset the contents. +See the example below. +</para> +<para>The first two command invocations, +<literal>\sbox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>}</literal> and +<literal>\savebox{<replaceable>box-cmd</replaceable>}{<replaceable>text</replaceable>}</literal>, are roughly equivalent. +As to the third and fourth, the optional arguments allow you to specify +the box width as <replaceable>width</replaceable>, and the position of the text inside that +box as <replaceable>position</replaceable>. See <link linkend="_005cmbox-_0026-_005cmakebox">\mbox & \makebox</link> for the full +description. +</para> +<para>In the <literal>\sbox</literal> and <literal>\savebox</literal> commands the <replaceable>text</replaceable> is +typeset in LR mode so it does not have line breaks (see <link linkend="Modes">Modes</link>). If +you use these then &latex; doesn’t give you an error but it ignores +what you want: if you enter <literal>\sbox{\newbin}{test \\ test}</literal> and +<literal>\usebox{\newbin}</literal> then you get ‘<literal>testtest</literal>’, while if you +enter <literal>\sbox{\newbin}{test \par test}</literal> and +<literal>\usebox{\newbin}</literal> then you get ‘<literal>test test</literal>’, but no error or +warning. To fix this use a <literal>\parbox</literal> or <literal>minipage</literal> as here. +</para> +<!-- credit: egreg https://tex.stackexchange.com/a/41668/121234 --> +<screen>\savebox{\abin}{% + \begin{minipage}{\linewidth} + \begin{enumerate} + \item First item + \item Second item + \end{enumerate} + \end{minipage}} + ... +\usebox{\abin} +</screen> +<para>As an example of the efficiency of reusing a bin’s contents, this puts +the same picture on each page of the document by putting it in the +header. &latex; only typesets it once. +</para> +<screen>\usepackage{graphicx} % all this in the preamble +\newsavebox{\sealbin} +\savebox{\sealbin}{% + \setlength{\unitlength}{1in}% + \begin{picture}(0,0)% + \put(1.5,-2.5){% + \begin{tabular}{c} + \includegraphics[height=2in]{companylogo.png} \\ + Office of the President + \end{tabular}} + \end{picture}% +} +\markright{\usebox{\sealbin}} +\pagestyle{headings} +</screen> +<para>The <literal>picture</literal> environment is good for fine-tuning the placement. +</para> +<para>If the bin has not already been defined then you get something like +‘<literal>Undefined control sequence. <argument> \nobin</literal>’. +</para> + +</sect1> +<sect1 label="20.6" id="lrbox"> +<title><literal>lrbox</literal></title> + +<indexterm role="fn"><primary>lrbox</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\begin{lrbox}{<replaceable>box-cmd</replaceable>} + <replaceable>text</replaceable> +\end{lrbox} +</screen> +<para>The <replaceable>text</replaceable> inside the environment is saved in the bin +<literal><replaceable>box-cmd</replaceable></literal>. The <replaceable>box-cmd</replaceable> must begin with a +backslash. You must create this bin in advance with <literal>\newsavebox</literal> +(see <link linkend="_005cnewsavebox">\newsavebox</link>). This is the environment form of the <literal>\sbox</literal> +and <literal>\savebox</literal> commands, and is equivalent to them. See <link linkend="_005csbox-_0026-_005csavebox">\sbox & +\savebox</link> for the full information. +</para> +<para>In this example the environment is convenient for entering the +<literal>tabular</literal>. +</para> +<screen>\newsavebox{\jhbin} +\begin{lrbox}{\jhbin} + \begin{tabular}{c} + \includegraphics[height=1in]{jh.png} \\ + Jim Hef{}feron + \end{tabular} +\end{lrbox} + ... +\usebox{\jhbin} +</screen> + +</sect1> +<sect1 label="20.7" id="_005cusebox"> +<title><literal>\usebox</literal></title> + +<indexterm role="fn"><primary>\usebox</primary></indexterm> +<indexterm role="cp"><primary>box, use saved box</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\usebox{<replaceable>box-cmd</replaceable>} +</screen> +<para>Produce the box most recently saved in the bin <replaceable>box-cmd</replaceable> by the +commands <literal>\sbox</literal> or <literal>\savebox</literal>, or the <literal>lrbox</literal> +environment. See <link linkend="_005csbox-_0026-_005csavebox">\sbox & \savebox</link> for more information and examples. +(Note that <replaceable>box-cmd</replaceable> starts with a backslash.) This command is +robust (see <link linkend="_005cprotect">\protect</link>). +</para> + +</sect1> +</chapter> +<chapter label="21" id="Color"> +<title>Color</title> + +<indexterm role="cp"><primary>color</primary></indexterm> + +<para>You can add color to text, rules, etc. You can also have color in a box +or on an entire page and write text on top of it. +</para> +<para>Color support comes as an additional package. So put +<literal>\usepackage{color}</literal> in your document preamble to use the +commands described here. +</para> +<para>Many other packages also supplement &latex;’s color abilities. +Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and +significantly extends the capabilities described here, including adding +‘<literal>HTML</literal>’ and ‘<literal>Hsb</literal>’ color models. +</para> + + +<sect1 label="21.1" id="Color-package-options"> +<title><literal>color</literal> package options</title> + +<indexterm role="cp"><primary>color package options</primary></indexterm> +<indexterm role="cp"><primary>options, color package</primary></indexterm> + +<para>Synopsis (must be in the document preamble): +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{color} +</screen> +<para>When you load the <filename>color</filename> package there are two kinds of available +options. +</para> +<para>The first specifies the <firstterm>printer driver</firstterm>. &latex; doesn’t contain +information about different output systems but instead depends on +information stored in a file. Normally you should not specify the +driver option in the document, and instead rely on your system’s +default. One advantage of this is that it makes the document portable +across systems. For completeness we include a list of the drivers. The +currently relevant ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>, +<filename>dvisvgm</filename>, <filename>luatex</filename>, <filename>pdftex</filename>, <filename>xetex</filename>. The two +<filename>xdvi</filename> and <filename>oztex</filename> are essentially aliases for <filename>dvips</filename> +(and <filename>xdvi</filename> is monochrome). Ones that should not be used for new +systems are: <filename>dvipdf</filename>, <filename>dvipdfm</filename>, <filename>dviwin</filename>, +<filename>dvipsone</filename>, <filename>emtex</filename>, <filename>pctexps</filename>, <filename>pctexwin</filename>, +<filename>pctexhp</filename>, <filename>pctex32</filename>, <filename>truetex</filename>, <filename>tcidvi</filename>, +<filename>vtex</filename> (and <filename>dviwindo</filename> is an alias for <filename>dvipsone</filename>). +</para> +<para>The second kind of options, beyond the drivers, are below. +</para> +<variablelist> +<varlistentry><term><literal>monochrome</literal> +</term><listitem><para>Disable the color commands, so that they do not generate errors but do +not generate color either. +</para> +</listitem></varlistentry><varlistentry><term><literal>dvipsnames</literal> +</term><listitem><para>Make available a list of 68 color names that are often used, +particularly in legacy documents. These color names were originally +provided by the <filename>dvips</filename> driver, giving the option name. +</para> +</listitem></varlistentry><varlistentry><term><literal>nodvipsnames</literal> +</term><listitem><para>Do not load that list of color names, saving &latex; a tiny amount of +memory space. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="21.2" id="Color-models"> +<title>Color models</title> + +<indexterm role="cp"><primary>color models</primary></indexterm> + +<para>A <firstterm>color model</firstterm> is a way of representing colors. &latex;’s +capabilities depend on the printer driver. However, the <filename>pdftex</filename>, +<filename>xetex</filename>, and <filename>luatex</filename> printer drivers are today by far the +most commonly used. The models below work for those drivers. All but +one of these is also supported by essentially all other printer drivers +used today. +</para> +<para>Note that color combination can be additive or subtractive. Additive +mixes colors of light, so that for instance combining full intensities +of red, green, and blue produces white. Subtractive mixes pigments, +such as with inks, so that combining full intensity of cyan, magenta, +and yellow makes black. +</para> +<variablelist><anchor id="color-models-cmyk"/><varlistentry><term><literal>cmyk</literal> +</term><listitem><para>A comma-separated list with four real numbers between 0 and 1, +inclusive. The first number is the intensity of cyan, the second is +magenta, and the others are yellow and black. A number value of 0 means +minimal intensity, while a 1 is for full intensity. This model is often +used in color printing. It is a subtractive model. +</para> +<anchor id="color-models-gray"/></listitem></varlistentry><varlistentry><term><literal>gray</literal> +</term><listitem><para>A single real number between 0 and 1, inclusive. The colors are shades +of grey. The number 0 produces black while 1 gives white. +</para> +<anchor id="color-models-rgb"/></listitem></varlistentry><varlistentry><term><literal>rgb</literal> +</term><listitem><para>A comma-separated list with three real numbers between 0 and 1, +inclusive. The first number is the intensity of the red component, the +second is green, and the third the blue. A number value of 0 means that +none of that component is added in, while a 1 means full intensity. +This is an additive model. +</para> +<anchor id="color-models-RGB"/></listitem></varlistentry><varlistentry><term><literal>RGB</literal> +</term><listitem><para>(<filename>pdftex</filename>, <filename>xetex</filename>, <filename>luatex</filename> drivers) A comma-separated +list with three integers between 0 and 255, inclusive. This model is a +convenience for using <literal>rgb</literal> since outside of &latex; colors are +often described in a red-green-blue model using numbers in this range. +The values entered here are converted to the <literal>rgb</literal> model by +dividing by 255. +</para> +<anchor id="color-models-named"/></listitem></varlistentry><varlistentry><term><literal>named</literal> +</term><listitem><para>Colors are accessed by name, such as ‘<literal>PrussianBlue</literal>’. The list of +names depends on the driver, but all support the names ‘<literal>black</literal>’, +‘<literal>blue</literal>’, ‘<literal>cyan</literal>’, ‘<literal>green</literal>’, ‘<literal>magenta</literal>’, ‘<literal>red</literal>’, +‘<literal>white</literal>’, and ‘<literal>yellow</literal>’ (See the <literal>dvipsnames</literal> option in +<link linkend="Color-package-options">Color package options</link>). +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="21.3" id="Commands-for-color"> +<title>Commands for color</title> + +<indexterm role="cp"><primary>color package commands</primary></indexterm> + +<para>These are the commands available with the <filename>color</filename> package. +</para> + + +<sect2 label="21.3.1" id="Define-colors"> +<title>Define colors</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>define color</primary></indexterm> +<indexterm role="cp"><primary>color, define</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\definecolor{<replaceable>name</replaceable>}{<replaceable>model</replaceable>}{<replaceable>specification</replaceable>} +</screen> +<para>Give the name <replaceable>name</replaceable> to the color. For example, after this +</para> +<screen>\definecolor{silver}{rgb}{0.75,0.75,0.74} +</screen> +<para>you can use that color name with <literal>Hi ho, +\textcolor{silver}{Silver}!</literal>. +</para> +<para>This example gives the color a more abstract name, so it could change and +not be misleading. +</para> +<screen>\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex +\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}} +</screen> +<para>Often a document’s colors are defined in the preamble, or in the class +or style, rather than in the document body. +</para> + +</sect2> +<sect2 label="21.3.2" id="Colored-text"> +<title>Colored text</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored text</primary></indexterm> + +<para>Synopses: +</para> +<screen>\textcolor{<replaceable>name</replaceable>}{...} +\textcolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}{...} +</screen> +<para>or +</para> +<screen>\color{<replaceable>name</replaceable>} +\color[<replaceable>color model</replaceable>]{<replaceable>specification</replaceable>} +</screen> +<para>The affected text gets the color. This line +</para> +<screen>\textcolor{magenta}{My name is Ozymandias, king of kings:} +Look on my works, ye Mighty, and despair! +</screen> +<para>causes the first half to be in magenta while the rest is in black. You +can use a color declared with <literal>\definecolor</literal> in exactly the same +way that we just used the builtin color ‘<literal>magenta</literal>’. +</para> +<screen>\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0} +I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}. +</screen> +<para>The two <literal>\textcolor</literal> and <literal>\color</literal> differ in that the first is +a command form, enclosing the text to be colored as an argument. Often +this form is more convenient, or at least more explicit. The second +form is a declaration, as in <literal>The moon is made of {\color{green} +green} cheese</literal>, so it is in effect until the end of the current group +or environment. This is sometimes useful when writing macros or as +below where it colors everything inside the <literal>center</literal> environment, +including the vertical and horizontal lines. +</para> +<screen>\begin{center} \color{blue} + \begin{tabular}{l|r} + UL &UR \\ \hline + LL &LR + \end{tabular} +\end{center} +</screen> +<para>You can use color in equations. A document might have this definition +in the preamble +</para> +<screen>\definecolor{highlightcolor}{RGB}{225,15,0} +</screen> +<para>and then contain this equation. +</para> +<screen>\begin{equation} + \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a) +\end{equation} +</screen> +<para>Typically the colors used in a document are declared in a class or style +but sometimes you want a one-off. Those are the second forms in the +synopses. +</para> +<screen>Colors of \textcolor[rgb]{0.33,0.14,0.47}{Purple} and +{\color[rgb]{0.72,0.60,0.37} Gold} for the team. +</screen> +<para>The format of <replaceable>color specification </replaceable> depends on the color model +(see <link linkend="Color-models">Color models</link>). For instance, while <literal>rgb</literal> takes three +numbers, <literal>gray</literal> takes only one. +</para> +<screen>The selection was \textcolor[gray]{0.5}{grayed out}. +</screen> +<para>Colors inside colors do not combine. Thus +</para> +<screen>\textcolor{green}{kind of \textcolor{blue}{blue}} +</screen> +<para>has a final word that is blue, not a combination of blue and green. +</para> +<!-- xx address coloring a line of a table? --> + + +</sect2> +<sect2 label="21.3.3" id="Colored-boxes"> +<title>Colored boxes</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored boxes</primary></indexterm> +<indexterm role="cp"><primary>box, colored</primary></indexterm> + +<para>Synopses: +</para> +<screen>\colorbox{<replaceable>name</replaceable>}{...} +\colorbox[<replaceable>model name</replaceable>]{<replaceable>box background color</replaceable>}{...} +</screen> +<para>or +</para> +<screen>\fcolorbox{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...} +\fcolorbox[<replaceable>model name</replaceable>]{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...} +</screen> +<para>Make a box with the stated background color. The <literal>\fcolorbox</literal> +command puts a frame around the box. For instance this +</para> +<screen>Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}} +</screen> +<para>makes a cyan-colored box that is five centimeters long and gets its +depth and height from the <literal>\strut</literal> (so the depth is +<literal>-.3\baselineskip</literal> and the height is <literal>\baselineskip</literal>). This +puts white text on a blue background. +</para> +<screen>\colorbox{blue}{\textcolor{white}{Welcome to the machine.}} +</screen> +<para>The <literal>\fcolorbox</literal> commands use the same parameters as <literal>\fbox</literal> +(see <link linkend="_005cfbox-_0026-_005cframebox">\fbox & \framebox</link>), <literal>\fboxrule</literal> and <literal>\fboxsep</literal>, to +set the thickness of the rule and the boundary between the box interior +and the surrounding rule. &latex;’s defaults are <literal>0.4pt</literal> and +<literal>3pt</literal>, respectively. +</para> +<para>This example changes the thickness of the border to 0.8 points. Note +that it is surrounded by curly braces so that the change ends at the end +of the second line. +</para> +<screen>{\setlength{\fboxrule}{0.8pt} +\fcolorbox{black}{red}{Under no circumstances turn this knob.}} +</screen> + +</sect2> +<sect2 label="21.3.4" id="Colored-pages"> +<title>Colored pages</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored page</primary></indexterm> +<indexterm role="cp"><primary>page, colored</primary></indexterm> +<indexterm role="cp"><primary>background, colored</primary></indexterm> + +<para>Synopses: +</para> +<screen>\pagecolor{<replaceable>name</replaceable>} +\pagecolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>} +\nopagecolor +</screen> +<para>The first two set the background of the page, and all subsequent pages, +to the color. For an explanation of the specification in the second +form see <link linkend="Colored-text">Colored text</link>. The third returns the background to normal, +which is a transparent background. (If that is not supported use +<literal>\pagecolor{white}</literal>, although that will make a white background +rather than the default transparent background.) +</para> +<screen> ... +\pagecolor{cyan} + ... +\nopagecolor +</screen> + +</sect2> +</sect1> +</chapter> +<chapter label="22" id="Graphics"> +<title>Graphics</title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> + +<para>You can use graphics such as PNG or PDF files in your &latex; document. +You need an additional package, which comes standard with &latex;. +This example is the short how-to. +</para> +<screen>\include{graphicx} % goes in the preamble + ... +\includegraphics[width=0.5\linewidth]{plot.pdf} +</screen> +<para>To use the commands described here your document preamble must contain +either <literal>\usepackage{graphicx}</literal> or +<literal>\usepackage{graphics}</literal>. Most of the time, <filename>graphicx</filename> is the +better choice. +</para> +<para>Graphics come in two main types, raster and vector. &latex; can use +both. In raster graphics the file contains an entry for each location +in an array, describing what color it is. An example is a photograph, +in JPG format. In vector graphics, the file contains a list of +instructions such as ‘<literal>draw a circle with this radius and that +center</literal>’. An example is a line drawing produced by the Asymptote +program, in PDF format. Generally vector graphics are more useful +because you can rescale their size without pixelation or other problems, +and because they often have a smaller size. +</para> +<para>There are systems particularly well-suited to make graphics for a +&latex; document. For example, these allow you to use the same fonts +as in your document. &latex; comes with a <literal>picture</literal> environment +(see <link linkend="picture">picture</link>) that has simple capabilities. Besides that, there are +other ways to include the graphic-making commands in the document. Two +such systems are the PSTricks and TikZ packages. There are also systems +external to &latex;, that generate a graphic that you include using the +commands of this chapter. Two that use a programming language are +Asymptote and MetaPost. One that uses a graphical interface is Xfig. +Full description of these systems is outside the scope of this document; +see their documentation on CTAN. +</para> + + +<sect1 label="22.1" id="Graphics-package-options"> +<title><literal>graphics</literal> package options</title> + +<indexterm role="cp"><primary>graphics package options</primary></indexterm> +<indexterm role="cp"><primary>options, graphics package</primary></indexterm> + +<para>Synopsis (must be in the document preamble): +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphics} +</screen> +<para>or +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphicx} +</screen> +<para>The <literal>graphicx</literal> package has a format for optional arguments to the +<literal>\includegraphics</literal> command that is convenient (it is the key-value +format), so it is the better choice for new documents. When you load +the <filename>graphics</filename> or <filename>graphicx</filename> package with <literal>\usepackage</literal> +there are two kinds of available options. +</para> +<para>The first is that &latex; does not contain information about different +output systems but instead depends on information stored in a +<firstterm>printer driver</firstterm> file. Normally you should not specify the driver +option in the document, and instead rely on your system’s default. One +advantage of this is that it makes the document portable across systems. +</para> +<para>For completeness here is a list of the drivers. The currently relevant +ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>, <filename>dvisvgm</filename>, <filename>luatex</filename>, +<filename>pdftex</filename>, <filename>xetex</filename>. The two <filename>xdvi</filename> and <filename>oztex</filename> are +essentially aliases for <filename>dvips</filename> (and <filename>xdvi</filename> is monochrome). +Ones that should not be used for new systems are: <filename>dvipdf</filename>, +<filename>dvipdfm</filename>, <filename>dviwin</filename>, <filename>dvipsone</filename>, <filename>emtex</filename>, +<filename>pctexps</filename>, <filename>pctexwin</filename>, <filename>pctexhp</filename>, <filename>pctex32</filename>, +<filename>truetex</filename>, <filename>tcidvi</filename>, <filename>vtex</filename> (and <filename>dviwindo</filename> is an +alias for <filename>dvipsone</filename>). These are stored in files with a +<filename>.def</filename> extension, such as <filename>pdftex.def</filename>. +</para> +<para>The second kind of options are below. +</para> +<variablelist><varlistentry><term><literal>demo</literal> +</term><listitem><para>Instead of an image file, &latex; puts in a 150 pt by 100 pt +rectangle (unless another size is specified in the +<literal>\includegraphics</literal> command). +</para> +</listitem></varlistentry><varlistentry><term><literal>draft</literal> +</term><listitem><para>For each graphic file, it is not shown but instead the file name is +printed in a box of the correct size. In order to determine the size, +the file must be present. +</para> +</listitem></varlistentry><varlistentry><term><literal>final</literal> +</term><listitem><para>(Default) Override any previous <literal>draft</literal> option, so that the +document shows the contents of the graphic files. +</para> +</listitem></varlistentry><varlistentry><term><literal>hiderotate</literal> +</term><listitem><para>Do not show rotated text. (This allows for the possibility that a +previewer does not have the capability to rotate text.) +<!-- what does it show? --> +</para> +</listitem></varlistentry><varlistentry><term><literal>hidescale</literal> +</term><listitem><para>Do not show scaled text. (This allows for the possibility that a +previewer does not have the capability to scale.) +<!-- what does it show? --> +</para> +</listitem></varlistentry><varlistentry><term><literal>hiresbb</literal> +</term><listitem><para>In a PS or EPS file the graphic size may be specified in two ways. The +<literal>%%BoundingBox</literal> lines describe the graphic size using integer +multiples of a PostScript point, that is, integer multiples of 1/72 +inch. A later addition to the PostScript language allows decimal +multiples, such as 1.23, in <literal>%%HiResBoundingBox</literal> lines. This +option has &latex; to read the size from the latter. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="22.2" id="Graphics-package-configuration"> +<title><literal>graphics</literal> package configuration</title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> +<indexterm role="cp"><primary>configuration, graphics package</primary></indexterm> +<indexterm role="cp"><primary>EPS files</primary></indexterm> +<indexterm role="cp"><primary>JPEG files</primary></indexterm> +<indexterm role="cp"><primary>JPG files</primary></indexterm> +<indexterm role="cp"><primary>PDF graphic files</primary></indexterm> +<indexterm role="cp"><primary>PNG files</primary></indexterm> + +<para>These commands configure the way &latex; searches the file system for +the graphic. +</para> +<para>The behavior of file system search code is necessarily platform +dependent. In this document we cover GNU/Linux, Macintosh, and Windows, as +those systems are typically configured. For other situations consult +the documentation in <filename>grfguide.pdf</filename>, or the &latex; source, or your +&tex; distribution’s documentation. +</para> + + +<sect2 label="22.2.1" id="_005cgraphicspath"> +<title><literal>\graphicspath</literal></title> + +<indexterm role="fn"><primary>\graphicspath</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\graphicspath{<replaceable>list of dir names inside curly brackets</replaceable>} +</screen> +<para>Declare a list of directories to search for graphics files. This allows +you to later say something like <literal>\includegraphics{lion.png}</literal> +instead of having to give its path. +</para> +<para>&latex; always looks for graphic files first in the current directory. +The declaration below tells the system to then look in the subdirectory +<filename>pix</filename>, and then <filename>../pix</filename>. +</para> +<screen>\usepackage{graphicx} % or graphics; put in preamble + ... +\graphicspath{ {pix/} {../pix/} } +</screen> +<para>The <literal>\graphicspath</literal> declaration is optional. If you don’t include +it then &latex;’s default is to search all of the places that it +usually looks for a file (it uses &latex;’s <literal>\input@path</literal>). In +particular, in this case one of the places it looks is the current +directory. +</para> +<para>Enclose each directory name in curly braces; for example, above it says +‘<literal><literal>{pix}</literal></literal>’. Do this even if there is only one directory. +Each directory name must end in a forward slash, <filename>/</filename>. This is true +even on Windows, where good practice is to use forward slashes for all +the directory separators since it makes the document portable to other +platforms. If you have spaces in your directory name then use double +quotes, as with <literal>{"my docs/"}</literal>. Getting one of these rules wrong +will cause &latex; to report <literal>Error: File `<replaceable>filename</replaceable>' not +found</literal>. +</para> +<para>Basically, the algorithm is that with this example, after looking in the +current directory, +</para> +<screen>\graphicspath{ {pix/} {../pix/} } +... +\usepackage{lion.png} +</screen> +<para>for each of the listed directories, &latex; concatenates it with the +file name and searches for the result, checking for <filename>pix/lion.png</filename> +and then <filename>../pix/lion.png</filename>. This algorithm means that the +<literal>\graphicspath</literal> command does not recursively search subdirectories: +if you issue <literal>\graphicspath{{a/}}</literal> and the graphic is in +<filename>a/b/lion.png</filename> then &latex; will not find it. It also means that +you can use absolute paths such as +<literal>\graphicspath{{/home/jim/logos/}}</literal> or +<literal>\graphicspath{{C:/Users/Albert/Pictures/}}</literal>. However, using +these means that the document is not portable. (You could preserve +portability by adjusting your &tex; system settings configuration file +parameter <literal>TEXINPUTS</literal>; see the documentation of your system.) +</para> +<para>You can use <literal>\graphicspath</literal> anywhere in the document. You can use +it more than once. Show its value with +<literal>\makeatletter\typeout{\Ginput@path}\makeatother</literal>. +</para> +<para>The directories are taken with respect to the base file. That is, +suppose that you are working on a document based on <filename>book/book.tex</filename> +and it contains <literal>\include{chapters/chap1}</literal>. If in +<filename>chap1.tex</filename> you put <literal>\graphicspath{{plots/}}</literal> then +&latex; will not search for graphics in <filename>book/chapters/plots</filename>, but +instead in <filename>book/plots</filename>. +</para> + +</sect2> +<sect2 label="22.2.2" id="_005cDeclareGraphicsExtensions"> +<title><literal>\DeclareGraphicsExtensions</literal></title> + +<indexterm role="fn"><primary>\DeclareGraphicsExtensions</primary></indexterm> + +<para>Synopses: +</para> +<screen>\DeclareGraphicsExtensions{<replaceable>comma-separated list of file extensions</replaceable>} +</screen> +<para>Declare the filename extensions to try. This allows you to specify the +order in which to choose graphic formats when you include graphic files +by giving the filename without the extension, as in +<literal>\includegraphics{functionplot}</literal>. +</para> +<para>In this example, &latex; will find files in the PNG format before PDF +files. +</para> +<screen>\DeclareGraphicsExtensions{.png,PNG,.pdf,.PDF} + ... +\includegraphics{lion} % will find <filename>lion.png</filename> before <filename>lion.pdf</filename> +</screen> +<para>Because the file name <filename>lion</filename> does not have a period, &latex; uses +the extension list. For each directory in the graphics path +(see <link linkend="_005cgraphicspath">\graphicspath</link>), &latex; will try the extensions in the order +given. If it does not find such a file after trying all the directories +and extensions then it reports ‘<literal>! LaTeX Error: File `<filename>lion</filename>' +not found</literal>’. Note that you must include the periods at the start of the +extensions. +</para> +<para>Because GNU/Linux and Macintosh filenames are case sensitive, the list of +file extensions is case sensitive on those platforms. The Windows +platform is not case sensitive. +</para> +<para>You are not required to include <literal>\DeclareGraphicsExtensions</literal> in +your document; the printer driver has a sensible default. For example, +the most recent <filename>pdftex.def</filename> has this extension list. +</para> +<screen>.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2 +</screen> +<para>You can use this command anywhere in the document. You can use it more +than once. Show its value with +<literal>\makeatletter\typeout{\Gin@extensions}\makeatother</literal>. +</para> + +</sect2> +<sect2 label="22.2.3" id="_005cDeclareGraphicsRule"> +<title><literal>\DeclareGraphicsRule</literal></title> + +<indexterm role="fn"><primary>\DeclareGraphicsRule</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\DeclareGraphicsRule{<replaceable>extension</replaceable>}{<replaceable>type</replaceable>}{<replaceable>size-file extension</replaceable>}{<replaceable>command</replaceable>} +</screen> +<para>Declare how to handle graphic files whose names end in <replaceable>extension</replaceable>. +</para> +<para>This example declares that all files with names have the form +<filename>filename-without-dot.mps</filename> will be treated as output from MetaPost, +meaning that the printer driver will use its MetaPost-handling code to +input the file. +</para> +<screen>\DeclareGraphicsRule{.mps}{mps}{.mps}{} +</screen> +<para>This +</para> +<screen>\DeclareGraphicsRule{*}{mps}{*}{} +</screen> +<para>tells &latex; that it should handle as MetaPost output any file with an +extension not covered by another rule, so it covers <filename>filename.1</filename>, +<filename>filename.2</filename>, etc. +</para> +<para>This describes the four arguments. +</para> +<variablelist><varlistentry><term><replaceable>extension</replaceable> +</term><listitem><para>The file extension to which this rule applies. The extension is anything +after and including the first dot in the filename. Use the Kleene star, +<literal>*</literal>, to denote the default behaviour for all undeclared extensions. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>type</replaceable> +</term><listitem><para>The type of file involved. This type is a string that must be defined +in the printer driver. For instance, files with extensions <filename>.ps</filename>, +<filename>.eps</filename>, or <filename>.ps.gz</filename> may all be classed as type <literal>eps</literal>. +All files of the same type will be input with the same internal command +by the printer driver. For example, the file types that <filename>pdftex</filename> +recognizes are: <literal>jpg</literal>, <literal>jbig2</literal>, <literal>mps</literal>, <literal>pdf</literal>, +<literal>png</literal>, <literal>tif</literal>. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>size-file extension</replaceable> +</term><listitem><para>The extension of the file to be read to determine the size of the +graphic, if there is such a file. It may be the same as <replaceable>extension</replaceable> +but it may be different. +</para> +<para>As an example, consider a PostScript graphic. To make it smaller, it +might be compressed into a <filename>.ps.gz</filename> file. Compressed files are not +easily read by &latex; so you can put the bounding box information in a +separate file. If <replaceable>size-file extension</replaceable> is empty then you must +specify size information in the arguments of <literal>\includegraphics</literal>. +</para> +<para>If the driver file has a procedure for reading size files for +<literal>type</literal> then that will be used, otherwise it will use the procedure +for reading <filename>.eps</filename> files. (Thus you may specify the size of bitmap +files in a file with a PostScript style <literal>%%BoundingBox</literal> line if no +other format is available.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>command</replaceable> +</term><listitem><para>A command that will be applied to the +file. This is very often left blank. This command must start with a +single backward quote. Thus, +<literal>\DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c +#1}</literal> specifies that any file with the extension <filename>.eps.gz</filename> should +be treated as an <literal>eps</literal> file, with the BoundingBox information +stored in the file with extension <filename>.eps.bb</filename>, and that the command +<literal>gunzip -c</literal> will run on your platform to decompresses the file. +</para> +<para>Such a command is specific to your platform. In addition, your &tex; +system must allow you to run external commands; as a security measure +modern systems restrict running commands unless you explicitly allow it. +See the documentation for your &tex; distribution. +</para> +</listitem></varlistentry></variablelist> +</sect2> +</sect1> +<sect1 label="22.3" id="Commands-for-graphics"> +<title>Commands for graphics</title> + +<indexterm role="cp"><primary>graphics package commands</primary></indexterm> +<indexterm role="cp"><primary>commands, graphics package</primary></indexterm> + +<para>These are the commands available with the <filename>graphics</filename> and +<filename>graphicx</filename> packages. +</para> + + +<sect2 label="22.3.1" id="_005cincludegraphics"> +<title><literal>\includegraphics</literal></title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> +<indexterm role="cp"><primary>including graphics</primary></indexterm> +<indexterm role="cp"><primary>importing graphics</primary></indexterm> +<indexterm role="cp"><primary>EPS files</primary></indexterm> +<indexterm role="cp"><primary>JPEG files</primary></indexterm> +<indexterm role="cp"><primary>JPG files</primary></indexterm> +<indexterm role="cp"><primary>PDF graphic files</primary></indexterm> +<indexterm role="cp"><primary>PNG files</primary></indexterm> +<indexterm role="fn"><primary>\includegraphics</primary></indexterm> + +<para>Synopses for <filename>graphics</filename> package: +</para> +<screen>\includegraphics{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +</screen> +<para>Synopses for <filename>graphicx</filename> package: +</para> +<screen>\includegraphics{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>} +</screen> +<para>Include a graphics file. The starred form <literal>\includegraphics*</literal> will +clip the graphic to the size specified, while for the unstarred form any +part of the graphic that is outside the box of the specified size will +over-print the surrounding area. +</para> +<para>This +</para> +<screen>\usepackage{graphicx} % in preamble + ... +\begin{center} + \includegraphics{plot.pdf} +\end{center} +</screen> +<para>will incorporate into the document the graphic in <filename>plot.pdf</filename>, +centered and at its nominal size. You can also give a path to the file, +as with <literal>\includegraphics{graphics/plot.pdf}</literal>. To specify a list +of locations to search for the file, see <link linkend="_005cgraphicspath">\graphicspath</link>. +</para> +<para>If your filename includes spaces then put it in double quotes. An example +is <literal>\includegraphics{"sister picture.jpg"}</literal>. +</para> +<para>The <literal>\includegraphics{<replaceable>filename</replaceable>}</literal> command decides on the +type of graphic by splitting <replaceable>filename</replaceable> on the first dot. You can +use <replaceable>filename</replaceable> with no dot, as in <literal>\includegraphics{turing}</literal> +and then &latex; tries a sequence of extensions such as <literal>.png</literal> and +<literal>.pdf</literal> until it finds a file with that extension +(see <link linkend="_005cDeclareGraphicsExtensions">\DeclareGraphicsExtensions</link>). +</para> +<para>If your file name contains dots before the extension then you can hide +them with curly braces, as in +<literal>\includegraphics{{plot.2018.03.12.a}.pdf}</literal>. Or, if you use +the <filename>graphicx</filename> package then you can use the options <literal>type</literal> and +<literal>ext</literal>; see below. This and other filename issues are also handled +with the package <filename>grffile</filename>. +</para> +<para>This example puts a graphic in a figure environment so &latex; can +move it to the next page if fitting it on the current page is awkward +(see <link linkend="figure">figure</link>). +</para> +<screen>\begin{figure} + \centering + \includegraphics[width=3cm]{lungxray.jpg} + \caption{The evidence is overwhelming: don't smoke.} \label{fig:xray} +\end{figure} +</screen> +<para>This places a graphic that will not float, so it is sure to appear at +this point in the document even if makes &latex; stretch the text or +resort to blank areas on the page. It will be centered and will have a +caption. +</para> +<screen>\usepackage{caption} % in preamble + ... +\begin{center} + \includegraphics{pix/nix.png} + \captionof{figure}{The spirit of the night} \label{pix:nix} % optional +\end{center} +</screen> +<para>This example puts a box with a graphic side by side with one having +text, with the two vertically centered. +</para> +<screen>\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}} + ... +\begin{center} + \vcenteredhbox{\includegraphics[width=0.4\textwidth]{plot}} + \hspace{1em} + \vcenteredhbox{\begin{minipage}{0.4\textwidth} + \begin{displaymath} + f(x)=x\cdot \sin (1/x) + \end{displaymath} + \end{minipage}} +\end{center} +</screen> +<para>If you use the <filename>graphics</filename> package then the only options involve the +size of the graphic (but see <link linkend="_005crotatebox">\rotatebox</link> and <link linkend="_005cscalebox">\scalebox</link>). +When one optional argument is present then it is +<literal>[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]</literal> and it gives the coordinates of the top +right corner of the image, as a pair of &tex; dimensions (see <link linkend="Units-of-length">Units +of length</link>). If the units are omitted they default to <literal>bp</literal>. In +this case, the lower left corner of the image is assumed to be at (0,0). +If two optional arguments are present then the leading one is +<literal>[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>]</literal>, specifying the coordinates of the image’s +lower left. Thus, <literal>\includegraphics[1in,0.618in]{...}</literal> calls for +the graphic to be placed so it is 1 inch wide and 0.618 inches +tall and so its origin is at (0,0). +</para> +<para>The <filename>graphicx</filename> package gives you many more options. Specify them +in a key-value form, as here. +</para> +<screen>\begin{center} + \includegraphics[width=1in,angle=90]{lion} + \hspace{2em} + \includegraphics[angle=90,width=1in]{lion} +\end{center} +</screen> +<para>The options are read left-to-right. So the first graphic above is made +one inch wide and then rotated, while the second is rotated and then +made one inch wide. Thus, unless the graphic is perfectly square, the +two will end with different widths and heights. +</para> +<para>There are many options. The primary ones are listed first. +</para> +<para>Note that a graphic is placed by &latex; into a box, which is +traditionally referred to as its bounding box (distinct from the +PostScript BoundingBox described below). The graphic’s printed area may +go beyond this box, or sit inside this box, but when &latex; makes up a +page it puts together boxes and this is the box allocated for the +graphic. +</para> +<variablelist><anchor id="includegraphics-width"/><varlistentry><term><literal>width</literal> +</term><listitem><para>The graphic will be shown so its bounding box is this width. An example +is <literal>\includegraphics[width=1in]{plot}</literal>. You can use the standard +&tex; dimensions (see <link linkend="Units-of-length">Units of length</link>) and also convenient is +<literal>\linewidth</literal>, or in a two-column document, <literal>\columnwidth</literal> +(see <link linkend="Page-layout-parameters">Page layout parameters</link>). An example is that by using the +<filename>calc</filename> package you can make the graphic be 1 cm narrow than +the width of the text with +<literal>\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>height</literal> +</term><listitem><anchor id="includegraphics-height"/><para>The graphic will be shown so its bounding box is this height. You can +use the standard &tex; dimensions (see <link linkend="Units-of-length">Units of length</link>), and also +convenient are <literal>\pageheight</literal> and <literal>\textheight</literal> (see <link linkend="Page-layout-parameters">Page +layout parameters</link>). For instance, the command +<literal>\includegraphics[height=0.25\textheight]{godel}</literal> will make the +graphic a quarter of the height of the text area. +</para> +</listitem></varlistentry><varlistentry><term><literal>totalheight</literal> +</term><listitem><anchor id="includegraphics-totalheght"/><para>The graphic will be shown so its bounding box has this height plus +depth. This differs from the height if the graphic was rotated. For +instance, if it has been rotated by -90 then it will have zero height +but a large depth. +</para> +</listitem></varlistentry><varlistentry><term><literal>keepaspectratio</literal> +</term><listitem><anchor id="includegraphics-keepaspectratio"/><para>If set to <literal>true</literal>, or just specified as here +</para> +<screen><literal>\includegraphics[...,keepaspectratio,...]{...}</literal> +</screen> +<para>and you give as options both <literal>width</literal> and <literal>height</literal> (or +<literal>totalheight</literal>), then &latex; will make the graphic is as large as +possible without distortion. That is, &latex; will ensure that neither +is the graphic wider than <literal>width</literal> nor taller than <literal>height</literal> (or +<literal>totalheight</literal>). +</para> +</listitem></varlistentry><varlistentry><term><literal>scale</literal> +</term><listitem><para>Factor by which to scale the graphic. To make a graphic twice its +nominal size, enter <literal>\includegraphics[scale=2.0]{...}</literal>. This +number may be any value; a number between 1 and 0 will shrink the +graphic and a negative number will reflect it. +</para> +</listitem></varlistentry><varlistentry><term><literal>angle</literal> +</term><listitem><para>Rotate the graphic. The angle is taken in degrees and counterclockwise. +The graphic is rotated about its <literal>origin</literal>; see that option. For a +complete description of how rotated material is typeset, +see <link linkend="_005crotatebox">\rotatebox</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>origin</literal> +</term><listitem><para>The point of the graphic about which the rotation happens. Possible +values are any string containing one or two of: <literal>l</literal> for left, +<literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center, <literal>t</literal> +for top, and <literal>B</literal> for baseline. Thus, entering the command +<literal>\includegraphics[angle=180,origin=c]{moon}</literal> will turn the +picture upside down about that picture’s center, while the command +<literal>\includegraphics[angle=180,origin=lB]{LeBateau}</literal> will turn its +picture upside down about its left baseline. (The character <literal>c</literal> +gives the horizontal center in <literal>bc</literal> or <literal>tc</literal>, but gives the +vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default is <literal>lB</literal>. +</para> +<para>To rotate about an arbitrary point, see <link linkend="_005crotatebox">\rotatebox</link>. +</para> +</listitem></varlistentry></variablelist> +<para>These are lesser-used options. +</para> +<variablelist><anchor id="includegraphics-viewport"/><varlistentry><term><literal>viewport</literal> +</term><listitem><para>Pick out a subregion of the graphic to show. Takes four arguments, +separated by spaces and given in &tex; dimensions, as with +<literal>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</literal>. The +dimensions default to big points, <literal>bp</literal>. They are taken +relative to the origin specified by the bounding box. See also the +<literal>trim</literal> option. +</para> +<anchor id="includegraphics-trim"/></listitem></varlistentry><varlistentry><term><literal>trim</literal> +</term><listitem><para>Gives parts of the graphic to not show. Takes four arguments, separated +by spaces, that are given in &tex; dimensions, as with +<literal>\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}</literal>. +These give the amounts of the graphic not to show, that is, &latex; +will crop the picture by 0 inches on the left, 0.1 inches on +the bottom, 0.2 inches on the right, and 0.3 inches on the +top. See also the <literal>viewport</literal> option. +</para> +<anchor id="includegraphics-clip"/></listitem></varlistentry><varlistentry><term><literal>clip</literal> +</term><listitem><para>If set to <literal>true</literal>, or just specified as here +</para> +<screen>\includegraphics[...,clip,...]{...} +</screen> +<para>then the graphic is cropped to the bounding box. This is the same as +using the starred form of the command, +<literal>\includegraphics*[...]{...}</literal>. +</para> +<anchor id="includegraphics-page"/></listitem></varlistentry><varlistentry><term><literal>page</literal> +</term><listitem><para>Give the page number of a multi-page PDF file. The default is +<literal>page=1</literal>. +</para> +<anchor id="includegraphics-pagebox"/></listitem></varlistentry><varlistentry><term><literal>pagebox</literal> +</term><listitem><para>Specifies which bounding box to use for PDF files from among +<literal>mediabox</literal>, <literal>cropbox</literal>, <literal>bleedbox</literal>, <literal>trimbox</literal>, or +<literal>artbox</literal>. PDF files do not have the BoundingBox that PostScript +files have, but may specify up to four predefined rectangles. The +MediaBox gives the boundaries of the physical medium. The CropBox is the +region to which the contents of the page are to be clipped when +displayed. The BleedBox is the region to which the contents of the page +should be clipped in production. The TrimBox is the intended dimensions +of the finished page. The ArtBox is the extent of the page’s meaningful +content. The driver will set the image size based on CropBox if +present, otherwise it will not use one of the others, with a +driver-defined order of preference. MediaBox is always present. +</para> +<anchor id="includegraphics-interpolate"/></listitem></varlistentry><varlistentry><term><literal>interpolate</literal> +</term><listitem><para>Enable or disable interpolation of raster images by the viewer. Can be +set with <literal>interpolate=true</literal> or just specified as here. +</para> +<screen>\includegraphics[...,interpolate,...]{...} +</screen> +<anchor id="includegraphics-quiet"/></listitem></varlistentry><varlistentry><term><literal>quiet</literal> +</term><listitem><para>Do not write information to the log. You can set it with +<literal>quiet=true</literal> or just specified it with +<literal>\includegraphics[...,quite,...]{...}</literal>, +</para> +<anchor id="includegraphics-draft"/></listitem></varlistentry><varlistentry><term><literal>draft</literal> +</term><listitem><para>If you set it with <literal>draft=true</literal> or just specify it with +</para> +<screen>\includegraphics[...,draft,...]{...} +</screen> +<para>then the graphic will not appear in the document, possibly saving color +printer ink. Instead, &latex; will put an empty box of the correct +size with the filename printed in it. +</para> +</listitem></varlistentry></variablelist> +<para>These options address the bounding box for Encapsulated PostScript +graphic files, which have a size specified with a line +<literal>%%BoundingBox</literal> that appears in the file. It has four values, +giving the lower <inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, lower <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate, upper +<inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, and upper <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate. The units are +PostScript points, equivalent to &tex;’s big points, 1/72 inch. +For example, if an <filename>.eps</filename> file has the line <literal>%%BoundingBox 10 +20 40 80</literal> then its natural size is 30/72 inch wide by +60/72 inch tall. +</para> +<variablelist><anchor id="includegraphics-bb"/><varlistentry><term><literal>bb</literal> +</term><listitem><para>Specify the bounding box of the displayed region. The argument is four +dimensions separated by spaces, as with <literal>\includegraphics[.., bb= +0in 0in 1in 0.618in]{...}</literal>. Usually <literal>\includegraphics</literal> reads the +BoundingBox numbers from the EPS file automatically, so this option is +only useful if the bounding box is missing from that file or if you want +to change it. +</para> +<anchor id="includegraphics-bbllx"/><anchor id="includegraphics-bblly"/><anchor id="includegraphics-bburx"/><anchor id="includegraphics-bbury"/></listitem></varlistentry><varlistentry><term><literal>bbllx, bblly, bburx, bbury</literal> +</term><listitem><para>Set the bounding box. These four are obsolete, but are retained for +compatibility with old packages. +</para> +<anchor id="includegraphics-natwidth"/><anchor id="includegraphics-natheight"/></listitem></varlistentry><varlistentry><term><literal>natwidth, natheight</literal> +</term><listitem><para>An alternative for <literal>bb</literal>. Setting +</para> +<screen>\includegraphics[...,natwidth=1in,natheight=0.618in,...]{...} +</screen> +<para>is the same as setting <literal>bb=0 0 1in 0.618in</literal>. +</para> +<anchor id="includegraphics-hiresbb"/></listitem></varlistentry><varlistentry><term><literal>hiresbb</literal> +</term><listitem><para>If set to <literal>true</literal>, or just specified as with +</para> +<screen>\includegraphics[...,hiresbb,...]{...} +</screen> +<para>then &latex; will look for <literal>%%HiResBoundingBox</literal> lines instead of +<literal>%%BoundingBox</literal> lines. (The <literal>BoundingBox</literal> lines use only +natural numbers while the <literal>HiResBoundingBox</literal> lines use decimals; +both use units equivalent to &tex;’s big points, 1/72 inch.) To +override a prior setting of <literal>true</literal>, you can set it to <literal>false</literal>. +</para> +</listitem></varlistentry></variablelist> +<para>These following options allow a user to override &latex;’s method of +choosing the graphic type based on the filename extension. An example +is that <literal>\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}</literal> +will read the file <filename>lion.xxx</filename> as though it were +<filename>lion.png</filename>. For more on these, see <link linkend="_005cDeclareGraphicsRule">\DeclareGraphicsRule</link>. +</para> +<variablelist><anchor id="includegraphics-type"/><varlistentry><term><literal>type</literal> +</term><listitem><para>Specify the graphics type. +</para> +<anchor id="includegraphics-ext"/></listitem></varlistentry><varlistentry><term><literal>ext</literal> +</term><listitem><para>Specify the graphics extension. +Only use this in conjunction with the option <literal>type</literal>. +</para> +<anchor id="includegraphics-read"/></listitem></varlistentry><varlistentry><term><literal>read</literal> +</term><listitem><para>Specify the file extension of the read file. +Only use this in conjunction with the option <literal>type</literal>. +</para> +<anchor id="includegraphics-command"/></listitem></varlistentry><varlistentry><term><literal>command</literal> +</term><listitem><para>Specify a command to be applied to this file. Only use this in +conjunction with the option <literal>type</literal>. See <link linkend="Command-line-options">Command line options</link> +for a discussion of enabling the <literal>\write18</literal> functionality to run +external commands. +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="22.3.2" id="_005crotatebox"> +<title><literal>\rotatebox</literal></title> + +<indexterm role="cp"><primary>rotation</primary></indexterm> +<indexterm role="cp"><primary>rotating graphics</primary></indexterm> +<indexterm role="cp"><primary>rotating text</primary></indexterm> +<indexterm role="fn"><primary>\rotatebox</primary></indexterm> + +<para>Synopsis if you use the <filename>graphics</filename> package: +</para> +<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Synopses if you use the <filename>graphicx</filename> package: +</para> +<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +\rotatebox[<replaceable>key-value list</replaceable>]{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Put <replaceable>material</replaceable> in a box and rotate it <replaceable>angle</replaceable> degrees +counterclockwise. +</para> +<para>This example rotates the table column heads forty five degrees. +</para> +<screen>\begin{tabular}{ll} + \rotatebox{45}{Character} &\rotatebox{45}{NATO phonetic} \\ + A &AL-FAH \\ + B &BRAH-VOH +\end{tabular} +</screen> +<para>The <replaceable>material</replaceable> can be anything that goes in a box, including a graphic. +</para> +<screen> \rotatebox[origin=c]{45}{\includegraphics[width=1in]{lion}} +</screen> +<para>To place the rotated material, the first step is that &latex; sets +<replaceable>material</replaceable> in a box, with a reference point on the left baseline. +The second step is the rotation, by default about the reference point. +The third step is that &latex; computes a box to bound the rotated +material. Fourth, &latex; moves this box horizontally so that the left +edge of this new bounding box coincides with the left edge of the box +from the first step (they need not coincide vertically). This new +bounding box, in its new position, is what &latex; uses as the box when +typesetting this material. +</para> +<para>If you use the <filename>graphics</filename> package then the rotation is about the +reference point of the box. If you use the <filename>graphicx</filename> package +then these are the options that can go in the <replaceable>key-value list</replaceable>, +but note that you can get the same effect without needing this +package, except for the <literal>x</literal> and <literal>y</literal> options +(see <link linkend="_005cincludegraphics">\includegraphics</link>). +</para> +<variablelist><varlistentry><term><literal>origin</literal> +</term><listitem><para>The point of the <replaceable>material</replaceable>’s box about which the rotation happens. +Possible value is any string containing one or two of: <literal>l</literal> for +left, <literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center, +<literal>t</literal> for top, and <literal>B</literal> for baseline. Thus, the first line here +</para> +<screen>\rotatebox[origin=c]{180}{moon} +\rotatebox[origin=lB]{180}{LeBateau} +</screen> +<para>will turn the picture upside down from the center while the second will +turn its picture upside down about its left baseline. (The character +<literal>c</literal> gives the horizontal center in <literal>bc</literal> or <literal>tc</literal> but gives +the vertical center in <literal>lc</literal> or <literal>rc</literal>, and gives both in +<literal>c</literal>.) The default is <literal>lB</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>x, y</literal> +</term><listitem><para>Specify an arbitrary point of rotation with +<literal>\rotatebox[x=<replaceable>&tex; dimension</replaceable>,y=<replaceable>&tex; +dimension</replaceable>]{...}</literal> (see <link linkend="Units-of-length">Units of length</link>). These give the offset +from the box’s reference point. +</para> +</listitem></varlistentry><varlistentry><term><literal>units</literal> +</term><listitem><para>This key allows you to change the default of degrees counterclockwise. +Setting <literal>units=-360</literal> changes the direction to degrees clockwise and +setting <literal>units=6.283185</literal> changes to radians counterclockwise. +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="22.3.3" id="_005cscalebox"> +<title><literal>\scalebox</literal></title> + +<indexterm role="cp"><primary>graphics, scaling</primary></indexterm> +<indexterm role="cp"><primary>graphics, resizing</primary></indexterm> +<indexterm role="cp"><primary>scaling</primary></indexterm> +<indexterm role="cp"><primary>resizing</primary></indexterm> +<indexterm role="cp"><primary>text, scaling</primary></indexterm> +<indexterm role="cp"><primary>text, resizing</primary></indexterm> +<indexterm role="fn"><primary>\scalebox</primary></indexterm> +<indexterm role="fn"><primary>\reflectbox</primary></indexterm> + +<para>Synopses: +</para> +<screen>\scalebox{<replaceable>horizontal factor</replaceable>}{<replaceable>material</replaceable>} +\scalebox{<replaceable>horizontal factor</replaceable>}[<replaceable>vertical factor</replaceable>]{<replaceable>material</replaceable>} +\reflectbox{<replaceable>material</replaceable>} +</screen> +<para>Scale the <replaceable>material</replaceable>. +</para> +<para>This example halves the size, both horizontally and vertically, of the +first text and doubles the size of the second. +</para> +<screen>\scalebox{0.5}{DRINK ME} and \scalebox{2.0}{Eat Me} +</screen> +<para>If you do not specify the optional <replaceable>vertical factor</replaceable> then it +defaults to the same value as the <replaceable>horizontal factor</replaceable>. +</para> +<para>You can use this command to resize a graphic, as here. +</para> +<screen>\scalebox{0.5}{\includegraphics{lion}} +</screen> +<para>If you use the <filename>graphicx</filename> package then you can accomplish the same +thing with optional arguments to <literal>\includegraphics</literal> +(see <link linkend="_005cincludegraphics">\includegraphics</link>). +</para> +<para>The <literal>\reflectbox</literal> command abbreviates +<literal>\scalebox{-1}[1]{<replaceable>material</replaceable>}</literal>. Thus, <literal>Able was +I\reflectbox{Able was I}</literal> will show the phrase ‘<literal>Able was I</literal>’ +immediately followed by its mirror reflection. +</para> + +</sect2> +<sect2 label="22.3.4" id="_005cresizebox"> +<title><literal>\resizebox</literal></title> + +<indexterm role="cp"><primary>graphics, scaling</primary></indexterm> +<indexterm role="cp"><primary>graphics, resizing</primary></indexterm> +<indexterm role="cp"><primary>scaling</primary></indexterm> +<indexterm role="cp"><primary>resizing</primary></indexterm> +<indexterm role="cp"><primary>text, scaling</primary></indexterm> +<indexterm role="cp"><primary>text, resizing</primary></indexterm> +<indexterm role="fn"><primary>\resizebox</primary></indexterm> + +<para>Synopses: +</para> +<screen>\resizebox{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>} +\resizebox*{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Given a size, such as <literal>3cm</literal>, transform <replaceable>material</replaceable> to make it +that size. If either <replaceable>horizontal length</replaceable> or <replaceable>vertical length</replaceable> +is an exclamation point <literal>!</literal> then the other argument is used +to determine a scale factor for both directions. +</para> +<para>This example makes the graphic be a half inch wide and scales it +vertically by the same factor to keep it from being distorted. +</para> +<screen>\resizebox{0.5in}{!}{\includegraphics{lion}} +</screen> +<para>The unstarred form <literal>\resizebox</literal> takes <replaceable>vertical length</replaceable> to be +the box’s height while the starred form <literal>\resizebox*</literal> takes it to +be height+depth. For instance, make the text have a height+depth of a +quarter inch with <literal>\resizebox*{!}{0.25in}{\parbox{1in}{This +box has both height and depth.}}</literal>. +</para> +<para>You can use <literal>\depth</literal>, <literal>\height</literal>, <literal>\totalheight</literal>, and +<literal>\width</literal> to refer to the original size of the box. Thus, make the +text two inches wide but keep the original height with +<literal>\resizebox{2in}{\height}{Two inches}</literal>. +</para> + +</sect2> +</sect1> +</chapter> +<chapter label="23" id="Special-insertions"> +<title>Special insertions</title> + +<indexterm role="cp"><primary>special insertions</primary></indexterm> +<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> + + +<sect1 label="23.1" id="Reserved-characters"> +<title>Reserved characters</title> + +<indexterm role="cp"><primary>reserved characters</primary></indexterm> +<indexterm role="cp"><primary>characters, reserved</primary></indexterm> +<indexterm role="cp"><primary>special characters</primary></indexterm> +<indexterm role="cp"><primary>characters, special</primary></indexterm> +<para>&latex; sets aside the following characters for special purposes. For +example, the percent sign <literal>%</literal> is for comments. They are +called <firstterm>reserved characters</firstterm> or <firstterm>special characters</firstterm>. +</para> +<screen># $ % & { } _ ~ ^ \ +</screen> +<indexterm role="fn"><primary>\#</primary></indexterm> +<indexterm role="fn"><primary>\$</primary></indexterm> +<indexterm role="fn"><primary>\%</primary></indexterm> +<indexterm role="fn"><primary>\&</primary></indexterm> +<indexterm role="fn"><primary>\_</primary></indexterm> +<indexterm role="fn"><primary>\{</primary></indexterm> +<indexterm role="fn"><primary>\}</primary></indexterm> +<para>If you want a reserved character to be printed as itself, in the text +body font, for all but the final three characters in that list simply +put a backslash <literal>\</literal> in front of the character. Thus, +typing <literal>\$1.23</literal> will produce <literal>$1.23</literal> in your output. +</para> +<indexterm role="fn"><primary>\~</primary></indexterm> +<indexterm role="fn"><primary>\^</primary></indexterm> +<indexterm role="fn"><primary>\textbackslash</primary></indexterm> +<para>As to the last three characters, to get a tilde in the text body font +use <literal>\~{}</literal> (omitting the curly braces would result in the next +character receiving a tilde accent). Similarly, to get a get a text +body font circumflex use <literal>\^{}</literal>. To get a backslash in the font +of the text body, enter <literal>\textbackslash{}</literal>. +</para> +<para>To produce the reserved characters in a typewriter font use +<literal>\verb!!</literal> as below (the double backslash <literal>\\</literal> is only +there to split the lines). +</para> +<screen>\begin{center} + \# \$ \% \& \{ \} \_ \~{} \^{} \textbackslash \\ + \verb!# $ % & { } _ ~ ^ \! +\end{center} +</screen> + +</sect1> +<sect1 label="23.2" id="Upper-and-lower-case"> +<title>Upper and lower case</title> + +<indexterm role="cp"><primary>uppercase</primary></indexterm> +<indexterm role="cp"><primary>lowercase</primary></indexterm> +<indexterm role="cp"><primary>characters, case of</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\uppercase{<replaceable>text</replaceable>} +\lowercase{<replaceable>text</replaceable>} +\MakeUppercase{<replaceable>text</replaceable>} +\MakeLowercase{<replaceable>text</replaceable>} +</screen> +<para>Change the case of characters. The &tex; primitives commands +<literal>\uppercase</literal> and <literal>\lowercase</literal> only work for American +characters. The &latex; commands <literal>\MakeUppercase</literal> and +<literal>\MakeLowercase</literal> commands also change characters accessed by +commands such as <literal>\ae</literal> or <literal>\aa</literal>. The commands +<literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> are robust but they have +moving arguments (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>These commands do not change the case of letters used in the name of a +command within <replaceable>text</replaceable>. But they do change the case of every other +Latin letter inside the argument <replaceable>text</replaceable>. Thus, +<literal>\MakeUppercase{Let $y=f(x)$</literal>} produces ‘<literal>LET Y=F(X)</literal>’. Another +example is that the name of an environment will be changed, so that +<literal>\MakeUppercase{\begin{tabular} ... \end{tabular}}</literal> will +produce an error because the first half is changed to +<literal>\begin{TABULAR}</literal>. +</para> +<para>&latex; uses the same fixed table for changing case throughout a +document, The table used is designed for the font encoding T1; this +works well with the standard &tex; fonts for all Latin alphabets but +will cause problems when using other alphabets. +</para> +<para>To change the case of text that results from a macro inside <replaceable>text</replaceable> +you need to do expansion. Here the <literal>\Schoolname</literal> produces +‘<literal>COLLEGE OF MATHEMATICS</literal>’. +</para> +<screen>\newcommand{\schoolname}{College of Mathematics} +\newcommand{\Schoolname}{\expandafter\MakeUppercase + <!-- /@w -->\expandafter{\schoolname}} +</screen> +<indexterm role="cp"><primary>package, <literal>textcase</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>textcase</literal> package</primary></indexterm> + +<para>The <filename>textcase</filename> package brings some of the missing feature of the +standard &latex; commands <literal>\MakeUppercase</literal> and +<literal>\MakeLowerCase</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>mfirstuc</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mfirstuc</literal> package</primary></indexterm> + +<para>To uppercase only the first letter of words, you can use the package +<filename>mfirstuc</filename>. +</para> + +</sect1> +<sect1 label="23.3" id="Symbols-by-font-position"> +<title>Symbols by font position</title> + +<indexterm role="fn"><primary>\symbol</primary></indexterm> +<indexterm role="cp"><primary>accessing any character of a font</primary></indexterm> +<indexterm role="cp"><primary>font symbols, by number</primary></indexterm> + +<para>You can access any character of the current font using its number with +the <literal>\symbol</literal> command. For example, the visible space character +used in the <literal>\verb*</literal> command has the code decimal 32, so it can be +typed as <literal>\symbol{32}</literal>. +</para> +<para>You can also specify numbers in octal (base 8) by using a <literal>'</literal> +prefix, or hexadecimal (base 16) with a <literal>"</literal> prefix, so the previous +example could also be written as <literal>\symbol{'40}</literal> or +<literal>\symbol{"20}</literal>. +</para> + +</sect1> +<sect1 label="23.4" id="Text-symbols"> +<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. Unless you are using Xe&latex; or Lua&latex; then +you may need to load the <literal>textcomp</literal> package. +</para> +<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. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\dag</primary></indexterm><literal>\dag</literal> +</term><listitem><indexterm role="cp"><primary>dagger, in text</primary></indexterm> +<para>† The dagger symbol (in text). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ddag</primary></indexterm><literal>\ddag</literal> +</term><listitem><indexterm role="cp"><primary>double dagger, in text</primary></indexterm> +<para>‡ The double dagger symbol (in text). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\LaTeX</primary></indexterm><literal>\LaTeX</literal> +</term><listitem><indexterm role="cp"><primary>&latex; logo</primary></indexterm> +<indexterm role="cp"><primary>logo, &latex;</primary></indexterm> +<para>The &latex; logo. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\LaTeXe</primary></indexterm><literal>\LaTeXe</literal> +</term><listitem><indexterm role="cp"><primary>&latex;2e logo</primary></indexterm> +<indexterm role="cp"><primary>logo, &latex;2e</primary></indexterm> +<para>The &latex;2e logo. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\guillemotleft («)</primary></indexterm><literal>\guillemotleft («)</literal> +</term><term><indexterm role="fn"><primary>\guillemotright (»)</primary></indexterm><literal>\guillemotright (»)</literal> +</term><term><indexterm role="fn"><primary>\guilsinglleft (‹)</primary></indexterm><literal>\guilsinglleft (‹)</literal> +</term><term><indexterm role="fn"><primary>\guilsinglright (›)</primary></indexterm><literal>\guilsinglright (›)</literal> +</term><listitem><indexterm role="cp"><primary>double guillemets</primary></indexterm> +<indexterm role="cp"><primary>single guillemets</primary></indexterm> +<indexterm role="cp"><primary>left angle quotation marks</primary></indexterm> +<indexterm role="cp"><primary>right angle quotation marks</primary></indexterm> +<indexterm role="cp"><primary>double angle quotation marks</primary></indexterm> +<indexterm role="cp"><primary>single angle quotation marks</primary></indexterm> +<indexterm role="cp"><primary>French quotation marks</primary></indexterm> +<indexterm role="cp"><primary>quotation marks, French</primary></indexterm> +<para>«, », ‹, › +Double and single angle quotation marks, commonly used in French. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ldots</primary></indexterm><literal>\ldots</literal> +</term><term><indexterm role="fn"><primary>\dots</primary></indexterm><literal>\dots</literal> +</term><term><indexterm role="fn"><primary>\textellipsis</primary></indexterm><literal>\textellipsis</literal> +</term><listitem><indexterm role="cp"><primary>ellipsis</primary></indexterm> +<para>… An ellipsis (three dots at the baseline): <literal>\ldots</literal> +and <literal>\dots</literal> also work in math mode. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lq</primary></indexterm><literal>\lq</literal> +</term><listitem><indexterm role="cp"><primary>left quote</primary></indexterm> +<indexterm role="cp"><primary>opening quote</primary></indexterm> +<para>‘ Left (opening) quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\P</primary></indexterm><literal>\P</literal> +</term><term><indexterm role="fn"><primary>\textparagraph</primary></indexterm><literal>\textparagraph</literal> +</term><listitem><indexterm role="cp"><primary>paragraph symbol</primary></indexterm> +<indexterm role="cp"><primary>pilcrow</primary></indexterm> +<para>¶ Paragraph sign (pilcrow). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pounds</primary></indexterm><literal>\pounds</literal> +</term><term><indexterm role="fn"><primary>\textsterling</primary></indexterm><literal>\textsterling</literal> +</term><listitem><indexterm role="cp"><primary>pounds symbol</primary></indexterm> +<indexterm role="cp"><primary>sterling symbol</primary></indexterm> +<para>£ English pounds sterling. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\quotedblbase („)</primary></indexterm><literal>\quotedblbase („)</literal> +</term><term><indexterm role="fn"><primary>\quotesinglbase (‚)</primary></indexterm><literal>\quotesinglbase (‚)</literal> +</term><listitem><indexterm role="cp"><primary>double low-9 quotation mark</primary></indexterm> +<indexterm role="cp"><primary>single low-9 quotation mark</primary></indexterm> +<indexterm role="cp"><primary>low-9 quotation marks, single and double</primary></indexterm> +<para>„ and ‚ +Double and single quotation marks on the baseline. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rq</primary></indexterm><literal>\rq</literal> +</term><listitem><indexterm role="cp"><primary>right quote</primary></indexterm> +<indexterm role="cp"><primary>closing quote</primary></indexterm> +<para>’ Right (closing) quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\S</primary></indexterm><literal>\S</literal> +</term><term><indexterm role="fn"><primary>\textsection</primary></indexterm><literal>\textsection</literal> +</term><listitem><indexterm role="cp"><primary>section symbol</primary></indexterm> +<para>§ Section sign. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\TeX</primary></indexterm><literal>\TeX</literal> +</term><listitem><indexterm role="cp"><primary>&tex; logo</primary></indexterm> +<indexterm role="cp"><primary>logo, &tex;</primary></indexterm> +<para>The &tex; logo. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textasciicircum</primary></indexterm><literal>\textasciicircum</literal> +</term><listitem><indexterm role="cp"><primary>circumflex, ASCII, in text</primary></indexterm> +<indexterm role="cp"><primary>ASCII circumflex, in text</primary></indexterm> +<para>^ ASCII circumflex. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textasciitilde</primary></indexterm><literal>\textasciitilde</literal> +</term><listitem><indexterm role="cp"><primary>tilde, ASCII, in text</primary></indexterm> +<indexterm role="cp"><primary>ASCII tilde, in text</primary></indexterm> +<para>~ ASCII tilde. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textasteriskcentered</primary></indexterm><literal>\textasteriskcentered</literal> +</term><listitem><indexterm role="cp"><primary>asterisk, centered, in text</primary></indexterm> +<indexterm role="cp"><primary>centered asterisk, in text</primary></indexterm> +<para>* Centered asterisk. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbackslash</primary></indexterm><literal>\textbackslash</literal> +</term><listitem><indexterm role="cp"><primary>backslash, in text</primary></indexterm> +<para>\ Backslash. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbar</primary></indexterm><literal>\textbar</literal> +</term><listitem><indexterm role="cp"><primary>vertical bar, in text</primary></indexterm> +<indexterm role="cp"><primary>bar, vertical, in text</primary></indexterm> +<para>| Vertical bar. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbardbl</primary></indexterm><literal>\textbardbl</literal> +</term><listitem><indexterm role="cp"><primary>vertical bar, double, in text</primary></indexterm> +<indexterm role="cp"><primary>bar, double vertical, in text</primary></indexterm> +<indexterm role="cp"><primary>double vertical bar, in text</primary></indexterm> +<para>⏸ Double vertical bar. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbigcircle</primary></indexterm><literal>\textbigcircle</literal> +</term><listitem><indexterm role="cp"><primary>big circle symbols, in text</primary></indexterm> +<indexterm role="cp"><primary>circle symbol, big, in text</primary></indexterm> +<para>◯ Big circle symbol. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbraceleft</primary></indexterm><literal>\textbraceleft</literal> +</term><listitem><indexterm role="cp"><primary>left brace, in text</primary></indexterm> +<indexterm role="cp"><primary>brace, left, in text</primary></indexterm> +<para>{ Left brace. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbraceright</primary></indexterm><literal>\textbraceright</literal> +</term><listitem><indexterm role="cp"><primary>right brace, in text</primary></indexterm> +<indexterm role="cp"><primary>brace, right, in text</primary></indexterm> +<para>} Right brace. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textbullet</primary></indexterm><literal>\textbullet</literal> +</term><listitem><indexterm role="cp"><primary>bullet, in text</primary></indexterm> +<para>• Bullet. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textcircled{<replaceable>letter</replaceable>}</primary></indexterm><literal>\textcircled{<replaceable>letter</replaceable>}</literal> +</term><listitem><indexterm role="cp"><primary>circled letter, in text</primary></indexterm> +<para>Ⓐ Circle around <replaceable>letter</replaceable>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textcompwordmark</primary></indexterm><literal>\textcompwordmark</literal> +</term><term><indexterm role="fn"><primary>\textcapitalcompwordmark</primary></indexterm><literal>\textcapitalcompwordmark</literal> +</term><term><indexterm role="fn"><primary>\textascendercompwordmark</primary></indexterm><literal>\textascendercompwordmark</literal> +</term><listitem><indexterm role="cp"><primary>composite word mark, in text</primary></indexterm> +<indexterm role="cp"><primary>cap height</primary></indexterm> +<indexterm role="cp"><primary>ascender height</primary></indexterm> +<para>Used to separate letters that would normally ligature. For example, +<literal>f\textcompwordmark i</literal> produces ‘<literal>fi</literal>’ without a ligature. This +is most useful in non-English languages. The +<literal>\textcapitalcompwordmark</literal> form has the cap height of the font +while the <literal>\textascendercompwordmark</literal> form has the ascender height. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textdagger</primary></indexterm><literal>\textdagger</literal> +</term><listitem><indexterm role="cp"><primary>dagger, in text</primary></indexterm> +<para>† Dagger. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textdaggerdbl</primary></indexterm><literal>\textdaggerdbl</literal> +</term><listitem><indexterm role="cp"><primary>dagger, double, in text</primary></indexterm> +<indexterm role="cp"><primary>double dagger, in text</primary></indexterm> +<para>‡ Double dagger. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textdollar (or <literal>\$</literal>)</primary></indexterm><literal>\textdollar (or <literal>\$</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>dollar sign</primary></indexterm> +<indexterm role="cp"><primary>currency, dollar</primary></indexterm> +<para>$ Dollar sign. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textemdash (or <literal>---</literal>)</primary></indexterm><literal>\textemdash (or <literal>---</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>em-dash</primary></indexterm> +<para>— Em-dash (used for punctuation, as in +<literal>The playoffs --- if you are fortunate enough to make the playoffs --- +is more like a sprint.</literal>). +</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 (used for ranges, as in <literal>See pages 12--14</literal>). +</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> +<indexterm role="cp"><primary>currency, euro</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>eurosym</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>eurosym</literal> package</primary></indexterm> + +<para>The Euro symbol: €. For an alternative glyph design, try the +<filename>eurosym</filename> package; also, most fonts nowadays come with their own +Euro symbol (Unicode U+20AC). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textexclamdown (or <literal>!`</literal>)</primary></indexterm><literal>\textexclamdown (or <literal>!`</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>exclamation point, upside-down</primary></indexterm> +<para>¡ Upside down exclamation point. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textgreater</primary></indexterm><literal>\textgreater</literal> +</term><listitem><indexterm role="cp"><primary>greater than symbol, in text</primary></indexterm> +<para>> Greater than symbol. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textless</primary></indexterm><literal>\textless</literal> +</term><listitem><indexterm role="cp"><primary>less than symbol, in text</primary></indexterm> +<para>< Less than symbol. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textleftarrow</primary></indexterm><literal>\textleftarrow</literal> +</term><listitem><indexterm role="cp"><primary>arrow, left, in text</primary></indexterm> +<indexterm role="cp"><primary>left arrow, in text</primary></indexterm> +<para>← Left arrow. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textordfeminine</primary></indexterm><literal>\textordfeminine</literal> +</term><term><indexterm role="fn"><primary>\textordmasculine</primary></indexterm><literal>\textordmasculine</literal> +</term><listitem><indexterm role="cp"><primary>feminine ordinal symbol</primary></indexterm> +<indexterm role="cp"><primary>masculine ordinal symbol</primary></indexterm> +<indexterm role="cp"><primary>ordinals, feminine and masculine</primary></indexterm> +<indexterm role="cp"><primary>Spanish ordinals, feminine and masculine</primary></indexterm> +<para>ª, º Feminine and masculine ordinal symbols. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textperiodcentered</primary></indexterm><literal>\textperiodcentered</literal> +</term><listitem><indexterm role="cp"><primary>period, centered, in text</primary></indexterm> +<indexterm role="cp"><primary>centered period, in text</primary></indexterm> +<para>· Centered period. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquestiondown (or <literal>?`</literal>)</primary></indexterm><literal>\textquestiondown (or <literal>?`</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>question mark, upside-down</primary></indexterm> +<para>¿ Upside down question mark. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotedblleft (or <literal>``</literal>)</primary></indexterm><literal>\textquotedblleft (or <literal>``</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>left quote, double</primary></indexterm> +<indexterm role="cp"><primary>double left quote</primary></indexterm> +<para>“ Double left quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotedblright (or <literal>''</literal>)</primary></indexterm><literal>\textquotedblright (or <literal>''</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>right quote, double</primary></indexterm> +<indexterm role="cp"><primary>double right quote</primary></indexterm> +<para>” Double right quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquoteleft (or <literal>`</literal>)</primary></indexterm><literal>\textquoteleft (or <literal>`</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>left quote, single</primary></indexterm> +<indexterm role="cp"><primary>single left quote</primary></indexterm> +<para>‘ Single left quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquoteright (or <literal>'</literal>)</primary></indexterm><literal>\textquoteright (or <literal>'</literal>)</literal> +</term><listitem><indexterm role="cp"><primary>right quote, single</primary></indexterm> +<indexterm role="cp"><primary>single right quote</primary></indexterm> +<para>’ Single right quote. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotesingle</primary></indexterm><literal>\textquotesingle</literal> +</term><listitem><indexterm role="cp"><primary>quote, single straight</primary></indexterm> +<indexterm role="cp"><primary>straight single quote</primary></indexterm> +<indexterm role="cp"><primary>single quote, straight</primary></indexterm> +<para>' Straight single quote. (From TS1 encoding.) +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotestraightbase</primary></indexterm><literal>\textquotestraightbase</literal> +</term><term><indexterm role="fn"><primary>\textquotestraightdblbase</primary></indexterm><literal>\textquotestraightdblbase</literal> +</term><listitem><indexterm role="cp"><primary>quote, straight base</primary></indexterm> +<indexterm role="cp"><primary>straight quote, base</primary></indexterm> +<indexterm role="cp"><primary>double quote, straight base</primary></indexterm> +<indexterm role="cp"><primary>straight double quote, base</primary></indexterm> +<!-- Unicode doesn't have these https://en.wikipedia.org/wiki/Quotation_mark --> +<para>Single and double straight quotes on the baseline. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textregistered</primary></indexterm><literal>\textregistered</literal> +</term><listitem><indexterm role="cp"><primary>registered symbol</primary></indexterm> +<para>® Registered symbol. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textrightarrow</primary></indexterm><literal>\textrightarrow</literal> +</term><listitem><indexterm role="cp"><primary>arrow, right, in text</primary></indexterm> +<indexterm role="cp"><primary>right arrow, in text</primary></indexterm> +<para>→ Right arrow. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textthreequartersemdash</primary></indexterm><literal>\textthreequartersemdash</literal> +</term><listitem><indexterm role="cp"><primary>three-quarters em-dash</primary></indexterm> +<indexterm role="cp"><primary>em-dash, three-quarters</primary></indexterm> +<para>﹘ “Three-quarters” em-dash, between en-dash and em-dash. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttrademark</primary></indexterm><literal>\texttrademark</literal> +</term><listitem><indexterm role="cp"><primary>trademark symbol</primary></indexterm> +<para>™ Trademark symbol. +</para> +<!-- ?? Diff from \textthreequartersemdash? In Unicode? --> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttwelveudash</primary></indexterm><literal>\texttwelveudash</literal> +</term><listitem><indexterm role="cp"><primary>two-thirds em-dash</primary></indexterm> +<indexterm role="cp"><primary>em-dash, two-thirds</primary></indexterm> +<para>﹘ “Two-thirds” em-dash, between en-dash and em-dash. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textunderscore</primary></indexterm><literal>\textunderscore</literal> +</term><listitem><indexterm role="cp"><primary>underscore, in text</primary></indexterm> +<para>_ Underscore. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textvisiblespace</primary></indexterm><literal>\textvisiblespace</literal> +</term><listitem><indexterm role="cp"><primary>visible space symbol, in text</primary></indexterm> +<para>␣ Visible space symbol. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="23.5" id="Accents"> +<title>Accents</title> + +<indexterm role="cp"><primary>accents</primary></indexterm> +<indexterm role="cp"><primary>characters, accented</primary></indexterm> +<indexterm role="cp"><primary>letters, accented</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>multilingual support</primary></indexterm> +<para>&latex; has wide support for many of the world’s scripts and languages, +through the <literal>babel</literal> package and related support if you are using +pdf&latex;, or <filename>polyglossia</filename> if you are using Xe&latex; or +Lua&latex;. This section does not cover that support. It only lists +the core &latex; commands for creating accented characters. The +<literal>\capital...</literal> commands shown here produce alternative forms for use +with capital letters. These are not available with OT1. +</para> +<para>Below, to make them easier to find, the accents are all illustrated with +lowercase ‘<literal>o</literal>’. +</para> +<indexterm role="fn"><primary>\i (dotless i)</primary></indexterm> +<indexterm role="cp"><primary>dotless i</primary></indexterm> +<para>Note that <literal>\i</literal> produces a dotless i, +<!-- @dotless{i}, --> +<indexterm role="fn"><primary>\j (dotless j)</primary></indexterm> +<indexterm role="cp"><primary>dotless j</primary></indexterm> +and <literal>\j</literal> produces a dotless j. +<!-- @dotless{j}. --> +These are often used in place of their dotted counterparts when they are +accented. +</para> +<variablelist><varlistentry><term><literal>\"</literal> +</term><term><literal>\capitaldieresis</literal> +</term><listitem><indexterm role="fn"><primary>\" (umlaut accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitaldieresis</primary></indexterm> +<indexterm role="cp"><primary>umlaut accent</primary></indexterm> +<indexterm role="cp"><primary>dieresis accent</primary></indexterm> +<para>ö Umlaut (dieresis). +</para> +</listitem></varlistentry><varlistentry><term><literal>\'</literal> +</term><term><literal>\capitalacute</literal> +</term><listitem><indexterm role="fn"><primary>\' (acute accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalacute</primary></indexterm> +<indexterm role="cp"><primary>acute accent</primary></indexterm> +<para>ó Acute accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\.</literal> +</term><listitem><indexterm role="fn"><primary>\. (dot-over accent)</primary></indexterm> +<indexterm role="cp"><primary>dot accent</primary></indexterm> +<indexterm role="cp"><primary>dot-over accent</primary></indexterm> +<para>ȯ Dot accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\=</literal> +</term><term><literal>\capitalmacron</literal> +</term><listitem><indexterm role="fn"><primary>\= (macron accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalmacron</primary></indexterm> +<indexterm role="cp"><primary>macron accent</primary></indexterm> +<indexterm role="cp"><primary>overbar accent</primary></indexterm> +<indexterm role="cp"><primary>bar-over accent</primary></indexterm> +<para>ō Macron (overbar) accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\^</literal> +</term><term><literal>\capitalcircumflex</literal> +</term><listitem><indexterm role="fn"><primary>\^ (circumflex accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalcircumflex</primary></indexterm> +<indexterm role="cp"><primary>circumflex accent</primary></indexterm> +<indexterm role="cp"><primary>hat accent</primary></indexterm> +<para>ô Circumflex (hat) accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\`</literal> +</term><term><literal>\capitalgrave</literal> +</term><listitem><indexterm role="fn"><primary>\` (grave accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalgrave</primary></indexterm> +<indexterm role="cp"><primary>grave accent</primary></indexterm> +<para>ò Grave accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\~</literal> +</term><term><literal>\capitaltilde</literal> +</term><listitem><indexterm role="fn"><primary>\~ (tilde accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitaltilde</primary></indexterm> +<indexterm role="cp"><primary>tilde accent</primary></indexterm> +<para>ñ Tilde accent. +</para> +</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>o_ Bar accent underneath. +</para> +<indexterm role="fn"><primary>\underbar</primary></indexterm> +<indexterm role="cp"><primary>underbar</primary></indexterm> +<para>Related to this, <literal>\underbar{<replaceable>text</replaceable>}</literal> produces a bar under +<replaceable>text</replaceable>. The argument is always processed in LR mode +(see <link linkend="Modes">Modes</link>). 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>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\c</literal> +</term><term><literal>\capitalcedilla</literal> +</term><listitem><indexterm role="fn"><primary>\c (cedilla accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalcedilla</primary></indexterm> +<indexterm role="cp"><primary>cedilla accent</primary></indexterm> +<para>ç Cedilla accent underneath. +</para> +</listitem></varlistentry><varlistentry><term><literal>\d</literal> +</term><term><literal>\capitaldotaccent</literal> +</term><listitem><indexterm role="fn"><primary>\d (dot-under accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitaldotaccent</primary></indexterm> +<indexterm role="cp"><primary>dot-under accent</primary></indexterm> +<para>ọ Dot accent underneath. +</para> +</listitem></varlistentry><varlistentry><term><literal>\H</literal> +</term><term><literal>\capitalhungarumlaut</literal> +</term><listitem><indexterm role="fn"><primary>\H (Hungarian umlaut accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalhungarumlaut</primary></indexterm> +<indexterm role="cp"><primary>hungarian umlaut accent</primary></indexterm> +<para>ő Long Hungarian umlaut accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\k</literal> +</term><term><literal>\capitalogonek</literal> +</term><listitem><indexterm role="fn"><primary>\k (ogonek)</primary></indexterm> +<indexterm role="fn"><primary>\capitalogonek</primary></indexterm> +<indexterm role="cp"><primary>ogonek</primary></indexterm> +<para>ǫ Ogonek. Not available in the OT1 encoding. +</para> +</listitem></varlistentry><varlistentry><term><literal>\r</literal> +</term><term><literal>\capitalring</literal> +</term><listitem><indexterm role="fn"><primary>\r (ring accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalring</primary></indexterm> +<indexterm role="cp"><primary>ring accent</primary></indexterm> +<para>o* Ring accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\t</literal> +</term><term><literal>\capitaltie</literal> +</term><term><literal>\newtie</literal> +</term><term><literal>\capitalnewtie</literal> +</term><listitem><indexterm role="fn"><primary>\t (tie-after accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitaltie</primary></indexterm> +<indexterm role="fn"><primary>\newtie</primary></indexterm> +<indexterm role="fn"><primary>\capitalnewtie</primary></indexterm> +<indexterm role="cp"><primary>tie-after accent</primary></indexterm> +<para>oo[ Tie-after accent. The <literal>\newtie</literal> form is centered in +its box. +</para> +</listitem></varlistentry><varlistentry><term><literal>\u</literal> +</term><term><literal>\capitalbreve</literal> +</term><listitem><indexterm role="fn"><primary>\u (breve accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalbreve</primary></indexterm> +<indexterm role="cp"><primary>breve accent</primary></indexterm> +<para>ŏ Breve accent. +</para> +</listitem></varlistentry><varlistentry><term><literal>\v</literal> +</term><term><literal>\capitalcaron</literal> +</term><listitem><indexterm role="fn"><primary>\v (breve accent)</primary></indexterm> +<indexterm role="fn"><primary>\capitalcaron</primary></indexterm> +<indexterm role="cp"><primary>hacek accent</primary></indexterm> +<indexterm role="cp"><primary>check accent</primary></indexterm> +<indexterm role="cp"><primary>caron accent</primary></indexterm> +<para>ǒ Háček (check, caron) accent. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="23.6" id="Additional-Latin-letters"> +<title>Additional Latin letters</title> + +<anchor id="Non_002dEnglish-characters"/><indexterm role="cp"><primary>Latin letters, additional</primary></indexterm> +<indexterm role="cp"><primary>letters, additional Latin</primary></indexterm> +<indexterm role="cp"><primary>extended Latin</primary></indexterm> +<indexterm role="cp"><primary>special characters</primary></indexterm> +<indexterm role="cp"><primary>non-English characters</primary></indexterm> +<indexterm role="cp"><primary>characters, non-English</primary></indexterm> + +<para>Here are the basic &latex; commands for inserting letters beyond +A–Z that extend the Latin alphabet, used primarily in languages other +than English. +</para> +<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> +<indexterm role="cp"><primary>aring</primary></indexterm> +<para>å and Å. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ae</literal> +</term><term><literal>\AE</literal> +</term><listitem><indexterm role="fn"><primary>\ae (æ)</primary></indexterm> +<indexterm role="fn"><primary>\AE (Æ)</primary></indexterm> +<indexterm role="cp"><primary>ae ligature</primary></indexterm> +<para>æ and Æ. +</para> +</listitem></varlistentry><varlistentry><term><literal>\dh</literal> +</term><term><literal>\DH</literal> +</term><listitem><indexterm role="fn"><primary>\dh (ð)</primary></indexterm> +<indexterm role="fn"><primary>\DH (Ð)</primary></indexterm> +<indexterm role="cp"><primary>Icelandic eth</primary></indexterm> +<indexterm role="cp"><primary>eth, Icelandic letter</primary></indexterm> +<para>Icelandic letter eth: ð and Ð. Not available with OT1 +encoding, you need the <filename>fontenc</filename> package to select an alternate +font encoding, such as T1. +</para> +</listitem></varlistentry><varlistentry><term><literal>\dj</literal> +</term><term><literal>\DJ</literal> +</term><listitem><indexterm role="fn"><primary>\dj</primary></indexterm> +<indexterm role="fn"><primary>\DJ</primary></indexterm> +<para>Crossed d and D, a.k.a. capital and small letter d with stroke. Not +available with OT1 encoding, you need the <filename>fontenc</filename> package to +select an alternate font encoding, such as T1. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ij</literal> +</term><term><literal>\IJ</literal> +</term><listitem><indexterm role="fn"><primary>\ij (ij)</primary></indexterm> +<indexterm role="fn"><primary>\IJ (IJ)</primary></indexterm> +<indexterm role="cp"><primary>ij letter, Dutch</primary></indexterm> +<para>ij and IJ (except somewhat closer together than appears here). +</para> +</listitem></varlistentry><varlistentry><term><literal>\l</literal> +</term><term><literal>\L</literal> +</term><listitem><indexterm role="fn"><primary>\l (ł)</primary></indexterm> +<indexterm role="fn"><primary>\L (Ł)</primary></indexterm> +<indexterm role="cp"><primary>polish l</primary></indexterm> +<para>ł and Ł. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ng</literal> +</term><term><literal>\NG</literal> +</term><listitem><indexterm role="fn"><primary>\ng</primary></indexterm> +<indexterm role="fn"><primary>\NG</primary></indexterm> +<para>Lappish letter eng, also used in phonetics. +</para> +</listitem></varlistentry><varlistentry><term><literal>\o</literal> +</term><term><literal>\O</literal> +</term><listitem><indexterm role="fn"><primary>\o (ø)</primary></indexterm> +<indexterm role="fn"><primary>\O (Ø)</primary></indexterm> +<indexterm role="cp"><primary>oslash</primary></indexterm> +<para>ø and Ø. +</para> +</listitem></varlistentry><varlistentry><term><literal>\oe</literal> +</term><term><literal>\OE</literal> +</term><listitem><indexterm role="fn"><primary>\oe (œ)</primary></indexterm> +<indexterm role="fn"><primary>\OE (Œ)</primary></indexterm> +<indexterm role="cp"><primary>oe ligature</primary></indexterm> +<para>œ and Œ. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ss</literal> +</term><term><literal>\SS</literal> +</term><listitem><indexterm role="fn"><primary>\ss (ß)</primary></indexterm> +<indexterm role="fn"><primary>\SS (SS)</primary></indexterm> +<indexterm role="cp"><primary>es-zet German letter</primary></indexterm> +<indexterm role="cp"><primary>sharp S letters</primary></indexterm> +<para>ß and SS. +</para> +</listitem></varlistentry><varlistentry><term><literal>\th</literal> +</term><term><literal>\TH</literal> +</term><listitem><indexterm role="fn"><primary>\th (þ)</primary></indexterm> +<indexterm role="fn"><primary>\TH (Þ)</primary></indexterm> +<indexterm role="cp"><primary>Icelandic thorn</primary></indexterm> +<indexterm role="cp"><primary>thorn, Icelandic letter</primary></indexterm> +<para>Icelandic letter thorn: þ and Þ. Not available with OT1 +encoding, you need the <filename>fontenc</filename> package to select an alternate +font encoding, such as T1. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="23.7" id="_005crule"> +<title><literal>\rule</literal></title> + +<indexterm role="fn"><primary>\rule</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\rule{<replaceable>width</replaceable>}{<replaceable>thickness</replaceable>} +\rule[<replaceable>raise</replaceable>]{<replaceable>width</replaceable>}{<replaceable>thickness</replaceable>} +</screen> +<para>Produce a <firstterm>rule</firstterm>, a filled-in rectangle. +</para> +<indexterm role="cp"><primary>Halmos symbol</primary></indexterm> +<indexterm role="cp"><primary>tombstone</primary></indexterm> +<para>This produces a rectangular blob, sometimes called a Halmos symbol, +often used to mark the end of a proof. +</para> +<screen>\newcommand{\qedsymbol}{\rule{0.4em}{2ex}} +</screen> +<indexterm role="cp"><primary>package, <literal>amsthm</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsthm</literal> package</primary></indexterm> + +<para>The <filename>amsthm</filename> package includes this command, with a somewhat +different-looking symbol. +</para> +<para>The mandatory arguments give the horizontal <replaceable>width</replaceable> and vertical +<replaceable>thickness</replaceable> of the rectangle. They are rigid lengths +(see <link linkend="Lengths">Lengths</link>). The optional argument <replaceable>raise</replaceable> is also a rigid +length, and tells &latex; how much to raise the rule above the +baseline, or lower it if the length is negative. +</para> +<para>This produces a line, a rectangle that is wide but not tall. +</para> +<screen>\noindent\rule{\textwidth}{0.4pt} +</screen> +<para>The line is the width of the page and 0.4 points tall. This line +thickness is common in &latex;. +</para> +<para>A rule that has zero width, or zero thickness, will not show up in the +output, but can cause &latex; to change the output around it. +See <link linkend="_005cstrut">\strut</link> for examples. +</para> + +</sect1> +<sect1 label="23.8" id="_005ctoday"> +<title><literal>\today</literal></title> + +<indexterm role="fn"><primary>\today</primary></indexterm> +<indexterm role="cp"><primary>date, today’s</primary></indexterm> +<indexterm role="cp"><primary>today’s date</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\today +</screen> +<para>Produce today’s date in the format ‘<literal><replaceable>month</replaceable> <replaceable>dd</replaceable>, +<replaceable>yyyy</replaceable></literal>’. An example of a date in that format is ‘<literal>July 4, +1976</literal>’. +</para> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm> + +<para>Multilingual packages such as <filename>babel</filename> or <filename>polyglossia</filename>, or +classes such as <filename>lettre</filename>, will localize <literal>\today</literal>. For example, +the following will output ‘<literal>4 juillet 1976</literal>’: +</para> +<screen>\year=1976 \month=7 \day=4 +\documentclass{minimal} +\usepackage[french]{babel} +\begin{document} +\today +\end{document} +</screen> +<para><literal>\today</literal> uses the counters <literal>\day</literal>, <literal>\month</literal>, and +<literal>\year</literal> (see <link linkend="_005cday-_0026-_005cmonth-_0026-_005cyear">\day & \month & \year</link>). +</para> +<indexterm role="cp"><primary>package, <literal>datetime</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>datetime</literal> package</primary></indexterm> + +<para>A number of package on CTAN work with dates. One is <filename>datetime</filename> package +which can produce a wide variety of date formats, including ISO standards. +</para> +<para>The date is not updated as the &latex; process runs, so in principle the +date could be incorrect by the time the program finishes. +</para> + +</sect1> +</chapter> +<chapter label="24" 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> + +<para>&latex; lets you split a large document into several smaller ones. +This can simplify editing or allow multiple authors to work on the +document. It can also speed processing. +</para> +<para>Regardless of how many separate files you use, there is always one +<indexterm role="cp"><primary>root file</primary></indexterm> +<indexterm role="cp"><primary>file, root</primary></indexterm> +<firstterm>root file</firstterm>, on which &latex; compilation starts. This shows such +a file with five included files. +</para> +<screen>\documentclass{book} +\includeonly{ % comment out lines below to omit compiling + pref, + chap1, + chap2, + append, + bib + } +\begin{document} +\frontmatter +\include{pref} +\mainmatter +\include{chap1} +\include{chap2} +\appendix +\include{append} +\backmatter +\include{bib} +\end{document} +</screen> +<para>This will bring in material from <filename>pref.tex</filename>, <filename>chap1.tex</filename>, +<filename>chap2.tex</filename>, <filename>append.tex</filename>, and <filename>bib.tex</filename>. If you compile +this file, and then comment out all of the lines inside +<literal>\includeonly{...}</literal> except for <literal>chap1,</literal> and compile again, +then &latex; will only process the material in the first chapter. +Thus, your output will appear more quickly and be shorter to print. +However, the advantage of the <literal>\includeonly</literal> command is that +&latex; will retain the page numbers and all of the cross reference +information from the other parts of the document so these will appear in +your output correctly. +</para> +<para>See <link linkend="Larger-book-template">Larger book template</link> for another example of <literal>\includeonly</literal>. +</para> + + + +<sect1 label="24.1" id="_005cendinput"> +<title><literal>\endinput</literal></title> + +<indexterm role="fn"><primary>\endinput</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\endinput +</screen> +<para>When you <literal>\include{filename}</literal>, inside <filename>filename.tex</filename> the +material after <literal>\endinput</literal> will not be included. This command is +optional; if <filename>filename.tex</filename> has no <literal>\endinput</literal> then &latex; +will read all of the file. +</para> +<para>For example, suppose that a document’s root file has +<literal>\input{chap1}</literal> and this is <filename>chap1.tex</filename>. +</para> +<screen>\chapter{One} +This material will appear in the document. +\endinput +This will not appear. +</screen> +<para>This can be useful for putting documentation or comments at the end of a +file, or for avoiding junk characters that can be added during mailing. +It is also useful for debugging: one strategy to localize errors is to +put <literal>\endinput</literal> halfway through the included file and see if the +error disappears. Now, knowing which half contains the error, moving +<literal>\endinput</literal> to halfway through that area further narrows down the +location. This process rapidly finds the offending line. +</para> +<para>After reading <literal>\endinput</literal>, &latex; continues to read to the end of +the line, so something can follow this command and be read nonetheless. +This allows you, for instance, to close an <literal>\if...</literal> with a +<literal>\fi</literal>. +</para> + +</sect1> +<sect1 label="24.2" id="_005cinclude-_0026-_005cincludeonly"> +<title><literal>\include</literal> & <literal>\includeonly</literal></title> + +<indexterm role="fn"><primary>\include</primary></indexterm> +<indexterm role="fn"><primary>\includeonly</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\includeonly{ % in document preamble + ... + <replaceable>filename</replaceable>, + ... + } + ... +\include{<replaceable>filename</replaceable>} % in document body +</screen> +<para>Bring material from the external file <filename><replaceable>filename</replaceable>.tex</filename> into a +&latex; document. +</para> +<para>The <literal>\include</literal> command does three things: it executes +<literal>\clearpage</literal> (see <link linkend="_005cclearpage-_0026-_005ccleardoublepage">\clearpage & \cleardoublepage</link>), then it +inputs the material from <filename><replaceable>filename</replaceable>.tex</filename> into the document, +and then it does another <literal>\clearpage</literal>. This command can only +appear in the document body. The <literal>\includeonly</literal> command controls +which files will be read by &latex; under subsequent <literal>\include</literal> +commands. Its list of filenames is comma-separated, and it can only +appear in the preamble. +</para> +<para>This example root document, <filename>constitution.tex</filename>, brings in +three files, <filename>preamble.tex</filename>, <filename>articles.tex</filename>, and +<filename>amendments.tex</filename>. +</para> +<screen>\documentclass{book} +\includeonly{ + preamble, + articles, + amendments + } +\begin{document} +\include{preamble} +\include{articles} +\include{amendments} +\end{document} +</screen> +<para>The file <filename>preamble.tex</filename> contains no special code; you have just +excerpted the chapter from <filename>consitution.tex</filename> and put it in a +separate file just for editing convenience. +</para> +<screen>\chapter{Preamble} +We the People of the United States, +in Order to form a more perfect Union, ... +</screen> +<para>Running &latex; on <filename>constitution.tex</filename> makes the material from the +three files appear in the document but also generates the auxiliary +files <filename>preamble.aux</filename>, <filename>articles.aux</filename>, and +<filename>amendments.tex</filename>. These contain information such as page numbers +and cross-references (see <link linkend="Cross-references">Cross references</link>). If you now comment out +<literal>\includeonly</literal>’s lines with <literal>preamble</literal> and <literal>amendments</literal> +and run &latex; again then the resulting document shows only the +material from <filename>articles.tex</filename>, not the material from +<filename>preamble.tex</filename> or <filename>amendments.tex</filename>. Nonetheless, all of the +auxiliary information from the omitted files is still there, including +the starting page number of the chapter. +</para> +<para>If the document preamble does not have <literal>\includeonly</literal> then +&latex; will include all the files you call for with <literal>\include</literal> +commands. +</para> +<para>The <literal>\include</literal> command makes a new page. To avoid that, see +<link linkend="_005cinput">\input</link> (which, however, does not retain the auxiliary +information). +</para> +<para>See <link linkend="Larger-book-template">Larger book template</link> for another example using <literal>\include</literal> +and <literal>\includeonly</literal>. That example also uses <literal>\input</literal> for some +material that will not necessarily start on a new page. +</para> +<para>File names can involve paths. +</para> +<screen>\documentclass{book} +\includeonly{ + chapters/chap1, + } +\begin{document} +\include{chapters/chap1} +\end{document} +</screen> +<para>To make your document portable across distributions and platforms you +should avoid spaces in the file names. The tradition is to instead use +dashes or underscores. Nevertheless, for the name ‘<literal>amo amas amat</literal>’, +this works under &tex; Live on GNU/Linux: +</para> +<screen>\documentclass{book} +\includeonly{ + "amo\space amas\space amat" + } +\begin{document} +\include{"amo\space amas\space amat"} +\end{document} +</screen> +<para>and this works under MiK&tex; on Windows: +</para> +<screen>\documentclass{book} +\includeonly{ + {"amo amas amat"} + } +\begin{document} +\include{{"amo amas amat"}} +\end{document} +</screen> +<indexterm role="cp"><primary>nested <literal>\include</literal>, not allowed</primary></indexterm> +<para>You cannot use <literal>\include</literal> inside a file that is being included or +you get ‘<literal>LaTeX Error: \include cannot be nested.</literal>’ The +<literal>\include</literal> command cannot appear in the document preamble; you will +get ‘<literal>LaTeX Error: Missing \begin{document}</literal>’. +</para> +<para>If a file that you <literal>\include</literal> does not exist, for instance if you +<literal>\include{athiesm}</literal> but you meant <literal>\include{atheism}</literal>, +then &latex; does not give you an error but will warn you ‘<literal>No file +athiesm.tex.</literal>’ (It will also create <filename>athiesm.aux</filename>.) +</para> +<para>If you <literal>\include</literal> the root file in itself then you first get +‘<literal>LaTeX Error: Can be used only in preamble.</literal>’ Later runs get +‘<literal>TeX capacity exceeded, sorry [text input levels=15]</literal>’. To fix +this, you must remove the inclusion <literal>\include{root}</literal> but also +delete the file <filename><replaceable>root</replaceable>.aux</filename> and rerun &latex;. +</para> + +</sect1> +<sect1 label="24.3" id="_005cinput"> +<title><literal>\input</literal></title> + +<indexterm role="fn"><primary>\input</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\input{<replaceable>filename</replaceable>} +</screen> +<para>&latex; processes the file as if its contents were inserted in the +current file. For a more sophisticated inclusion mechanism see +<link linkend="_005cinclude-_0026-_005cincludeonly">\include & \includeonly</link>. +</para> +<para>If <replaceable>filename</replaceable> does not end in ‘<literal>.tex</literal>’ then &latex; first tries +the filename with that extension; this is the usual case. If +<replaceable>filename</replaceable> ends with ‘<literal>.tex</literal>’ then &latex; looks for the +filename as it is. +</para> +<para>For example, this +</para> +<screen>\input{macros} +</screen> +<para>will cause &latex; to first look for <filename>macros.tex</filename>. If it finds +that file then it processes its contents as thought they had been +copy-pasted in. If there is no file of the name <filename>macros.tex</filename> then +&latex; tries the name <filename>macros</filename>, without an extension. (This may +vary by distribution.) +</para> +<para>To make your document portable across distributions and platforms you +should avoid spaces in the file names. The tradition is to instead use +dashes or underscores. Nevertheless, for the name ‘<literal>amo amas amat</literal>’, +this works under &tex; Live on GNU/Linux: +</para> +<screen>\input{"amo\space amas\space amat"} +</screen> +<para>and this works under MiK&tex; on Windows: +</para> +<screen>\input{{"amo amas amat"}} +</screen> + +</sect1> +</chapter> +<chapter label="25" id="Front_002fback-matter"> +<title>Front/back matter</title> + + + +<sect1 label="25.1" id="Table-of-contents-etc_002e"> +<title>Table of contents etc.</title> + +<indexterm role="cp"><primary>table of contents, creating</primary></indexterm> + +<indexterm role="fn"><primary>\tableofcontents</primary></indexterm> +<indexterm role="fn"><primary>.toc file</primary></indexterm> +<indexterm role="fn"><primary>\listoffigures</primary></indexterm> +<indexterm role="fn"><primary>\listoftables</primary></indexterm> +<indexterm role="fn"><primary>.lof file</primary></indexterm> +<indexterm role="fn"><primary>.lot file</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\tableofcontents +\listoffigures +\listoftables +</screen> +<para>Produce a table of contents, or list of figures, or list of tables. Put +the command in the input file where you want the table or list to +go. You do not type the entries; for example, typically the table of +contents entries are automatically generated from the sectioning +commands <literal>\chapter</literal>, etc. +</para> +<para>This example illustrates the first command, <literal>\tableofcontents</literal>. +&latex; will produce a table of contents on the book’s first page. +</para> +<screen>\documentclass{book} +% \setcounter{tocdepth}{1} +\begin{document} +\tableofcontents\newpage + ... +\chapter{...} + ... +\section{...} + ... +\subsection{...} + ... +\end{document} +</screen> +<para>Uncommenting the second line would cause that table to contain chapter +and section listings but not subsection listings, because the +<literal>\section</literal> command has level 1. See <link linkend="Sectioning">Sectioning</link> for level +numbers of the sectioning units. For more on the <literal>tocdepth</literal> +see <link linkend="Sectioning_002ftocdepth">Sectioning/tocdepth</link>. +</para> +<para>Another example of the use of <literal>\tableofcontents</literal> is in <link linkend="Larger-book-template">Larger +book template</link>. +</para> +<para>If you want a page break after the table of contents, write a +<literal>\newpage</literal> command after the <literal>\tableofcontents</literal> command, as +above. +</para> +<para>To make the table of contents &latex; stores the information in an +auxiliary file named <filename><replaceable>root-file</replaceable>.toc</filename> (see <link linkend="Splitting-the-input">Splitting the +input</link>). For example, this &latex; file <filename>test.tex</filename> +</para> +<screen>\documentclass{article} +\begin{document} +\tableofcontents\newpage +\section{First section} +\subsection{First subsection} + ... +</screen> +<para>writes the following line to <filename>test.toc</filename>. +</para> +<screen>\contentsline {section}{\numberline {1}First section}{2} +\contentsline {subsection}{\numberline {1.1}First subsection}{2} +</screen> +<para>The <literal>section</literal> or <literal>subsection</literal> is the sectioning unit. The +hook <literal>\numberline</literal> lets you to change how the information appears +in the table of contents. Of its two arguments, <literal>1</literal> or <literal>1.1</literal> +is the sectioning unit number and <literal>First section</literal> or <literal>First +subsection</literal> is the title. Finally, <literal>2</literal> is the page number on which +the sectioning units start. +</para> +<para>One consequence of this auxiliary file storage strategy is that to get the +contents page correct you must run &latex; twice, once to store the +information and once to get it. In particular, the first time that you +run &latex; on a new document, the table of contents page will be empty +except for its ‘<literal>Contents</literal>’ header. Just run it again. +</para> +<para>The commands <literal>\listoffigures</literal> and <literal>\listoftables</literal> produce a +list of figures and a list of tables. They work the same way as the +contents commands; for instance, these work with information stored in +<filename>.lof</filename> and <filename>.lot</filename> files. +</para> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm> + +<para>To change the header for the table of contents page do something like +the first line here. +</para> +<screen>\renewcommand{\contentsname}{Table of contents} +\renewcommand{\listfigurename}{Plots} +\renewcommand{\listtablename}{Tables} +</screen> +<para>Similarly, the other two lines will do the other two. +Internationalization packages such as <filename>babel</filename> or <filename>polyglossia</filename> +will change the headers depending on the chosen base language. +</para> +<indexterm role="cp"><primary>package, <literal>tocloft</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>tocloft</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>tocbibbind</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>tocbibbind</literal> package</primary></indexterm> + +<para>CTAN has many packages for the table of contents and lists of figures +and tables. One convenient one for adjusting some aspects of the +default, such as spacing, is <filename>tocloft</filename>. And, <filename>tocbibbind</filename> +will automatically add the bibliography, index, etc. to the table of +contents. +</para> + + +<sect2 label="25.1.1" id="_005caddcontentsline"> +<title><literal>\addcontentsline</literal></title> + +<indexterm role="fn"><primary>\addcontentsline</primary></indexterm> +<indexterm role="cp"><primary>table of contents entry, manually adding</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\addcontentsline{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>} +</screen> +<indexterm role="fn"><primary>\contentsline</primary></indexterm> +<para>Add an entry to the file specified by <replaceable>ext</replaceable>. Usually <replaceable>ext</replaceable> is +one of <literal>toc</literal> for the table of contents, <literal>lof</literal> for the list of +figures, or <literal>lot</literal> for the list of tables. +</para> +<para>The following will result in an ‘<literal>Appendices</literal>’ line in the table of +contents. +</para> +<screen>\addcontentsline{toc}{section}{\protect\textbf{Appendices}} +</screen> +<para>It will appear at the same indentation level as the sections, will be in +boldface, and will be assigned the page number associated with the point +where it appears in the input file. +</para> +<para>The <literal>\addcontentsline</literal> command writes information to the file +<filename><replaceable>root-name</replaceable>.<replaceable>ext</replaceable></filename>. It writes that information as the +text of the command +<literal>\contentsline{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}{<replaceable>num</replaceable>}</literal>, where +<literal><replaceable>num</replaceable></literal> is the current value of counter <literal><replaceable>unit</replaceable></literal>. The +most common case is the table of contents and there <replaceable>num</replaceable> is the +page number of the first page of <replaceable>unit</replaceable>. +</para> +<para>This command is invoked by the sectioning commands <literal>\chapter</literal>, +etc., and also by <literal>\caption</literal> inside a float environment. But it is +also used by authors. For example, in a book to have the preface +unnumbered, you may use the starred <literal>\chapter*</literal>. But that does not +put in table of contents information, so you can enter it manually, as +here. +</para> +<screen>\chapter*{Preface} +\addcontentsline{toc}{chapter}{\protect\numberline{}Preface} +</screen> +<para>In the <filename>.toc</filename> file &latex; will put the line <literal>\contentsline +{chapter}{\numberline {}Preface}{3}</literal>; note the page number +‘<literal>3</literal>’. +</para> +<!-- xx how hardwired are these values? other unit names? --> + +<para>All of the arguments for <literal>\addcontentsline</literal> are required. +</para> +<variablelist><varlistentry><term><replaceable>ext</replaceable> +</term><listitem><para>Typically one of the strings <literal>toc</literal> for the table of contents, +<literal>lof</literal> for the list of figures, or <literal>lot</literal> for the list of +tables. The filename extension of the information file. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>unit</replaceable> +</term><listitem><para>A string that depends on the value of the <replaceable>ext</replaceable> argument: +</para> +<variablelist><varlistentry><term><literal>toc</literal> +</term><listitem><para>For the table of contents, this is the name of a sectional unit: +<literal>part</literal>, <literal>chapter</literal>, <literal>section</literal>, <literal>subsection</literal>, etc. +</para> +</listitem></varlistentry><varlistentry><term><literal>lof</literal> +</term><listitem><para>For the list of figures: <literal>figure</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>lot</literal> +</term><listitem><para>For the list of tables: <literal>table</literal>. +</para></listitem></varlistentry></variablelist> +</listitem></varlistentry><varlistentry><term><replaceable>text</replaceable> +</term><listitem><para>The text of the entry. You must <literal>\protect</literal> any commands that are +fragile (see <link linkend="_005cprotect">\protect</link>). +</para></listitem></varlistentry></variablelist> +<para>The <literal>\addcontentsline</literal> command has an interaction with +<literal>\include</literal> (see <link linkend="_005cinclude-_0026-_005cincludeonly">\include & \includeonly</link>). If you use them at +the same level, as with +<literal>\addcontentsline{...}{...}{...}\include{...}</literal> then lines +in the table of contents can come out in the wrong order. The solution +is to move <literal>\addcontentsline</literal> into the file being included. +</para> +<para>If you use a <replaceable>unit</replaceable> that &latex; does not recognize, as here +</para> +<screen>\addcontentsline{toc}{setcion}{\protect\textbf{Appendices}} +</screen> +<para>then you don’t get an error but the formatting in the table of contents +will not make sense. +</para> + +</sect2> +<sect2 label="25.1.2" id="_005caddtocontents"> +<title><literal>\addtocontents</literal></title> + +<indexterm role="fn"><primary>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>Add <replaceable>text</replaceable>, which may be text or formatting commands, directly to +the auxiliary file with extension <replaceable>ext</replaceable>. This is most commonly used +for the table of contents so that is the discussion here, but this also +applies to the list of figures and list of tables. +</para> +<para>This will put some vertical space in the table of contents after the +‘<literal>Contents</literal>’ header. +</para> +<screen>\tableofcontents\newpage +\addtocontents{toc}{\protect\vspace*{3ex}} +</screen> +<para>The <literal>\addtocontents</literal> command has two arguments. Both are +required. +</para> +<variablelist><varlistentry><term><replaceable>ext</replaceable> +</term><listitem><para>Typically one of: <filename>toc</filename> for the table of contents, <filename>lof</filename> for +the list of figures, or <filename>lot</filename> for the list of tables. The +extension of the file holding the information. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>text</replaceable> +</term><listitem><para>The text, and possibly commands, to be written. +</para></listitem></varlistentry></variablelist> +<para>The sectioning commands such as <literal>\chapter</literal> use the +<literal>\addcontentsline</literal> command to store information. This command +creates lines in the <filename>.toc</filename> auxiliary file containing the +<literal>\contentsline</literal> command (see <link linkend="_005caddcontentsline">\addcontentsline</link>). In contrast, +the command <literal>\addtocontents</literal> puts material directly in that file. +</para> +<para>The <literal>\addtocontents</literal> command has an interaction with +<literal>\include</literal> (see <link linkend="_005cinclude-_0026-_005cincludeonly">\include & \includeonly</link>). If you use them at +the same level, as with +<literal>\addtocontents{...}{...}\include{...}</literal> then lines in the +table of contents can come out in the wrong order. The solution is to +move <literal>\addtocontents</literal> into the file being included. +</para> + +</sect2> +<sect2 label="25.1.3" id="_005cnofiles"> +<title><literal>\nofiles</literal></title> + +<indexterm role="fn"><primary>\nofiles</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\nofiles +</screen> +<para>Prevent &latex; from writing any auxiliary files. The only output will +be the <filename>.log</filename> and <filename>.pdf</filename> (or <filename>.dvi</filename>) files. This command +must go in the preamble. +</para> +<para>Because of the <literal>\nofiles</literal> command this example will not produce a +<filename>.toc</filename> file. +</para> +<screen>\documentclass{book} +\nofiles +\begin{document} +\tableofcontents\newpage +\chapter{...} + ... +</screen> +<para>&latex; will not erase any existing auxiliary files, so if you insert +the <literal>\nofiles</literal> command after you have run the file and gotten +a <filename>.toc</filename> then the table of contents page will continue to show +the old information. +</para> + +</sect2> +</sect1> +<sect1 label="25.2" id="Indexes"> +<title>Indexes</title> + +<indexterm role="cp"><primary>indexes</primary></indexterm> + +<indexterm role="fn"><primary>\makeindex</primary></indexterm> +<indexterm role="fn"><primary>\index</primary></indexterm> +<indexterm role="cp"><primary><filename>.idx</filename> file</primary></indexterm> + +<para>This document has an index. +</para> +<screen>\documentclass{article} +\usepackage{makeidx} \makeindex + ... +\begin{document} + ... +Recall Wilson's Theorem: \index{Wilson's Theorem} +a number \( n>1 \) is prime if and only if the factorial of \( n-1 \) +is congruent to \( -1 \) modulo~\( n \). + ... +\printindex + ... +</screen> +<para>The <literal>\usepackage{makeidx}</literal> and <literal>\makeindex</literal> in the preamble +bring in the relevant commands. +</para> +<para>Producing an index is a three stage process. First, in the document +body you declare index entries with the <literal>\index</literal> command +(see <link linkend="_005cindex">\index</link>). When you run &latex;, the <literal>\index</literal> writes its +information to an auxiliary file <filename><replaceable>root-name</replaceable>.idx</filename>. Next, to +alphabetize and to do other manipulations you run an external command, +typically <command>makeindex</command> or <command>xindy</command> (see <link linkend="makeindex">makeindex</link>). +These output a file <filename><replaceable>root-name</replaceable>.ind</filename>. Finally, you bring the +information back into your document and typeset it with the +<literal>\printindex</literal> command (see <link linkend="_005cprintindex">\printindex</link>). +</para> +<indexterm role="cp"><primary>package, <literal>showidx</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>showidx</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>multind</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>multind</literal> package</primary></indexterm> + +<para>There are many packages that apply to indexing commands. The +<literal>showidx</literal> package causes each index entries to be shown in the +margin on the page where the entry appears. This can help in preparing +the index. The <literal>multind</literal> package supports multiple indexes. See +also the &tex; FAQ entry on this topic, +<ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind</ulink>. +</para> + + +<sect2 label="25.2.1" id="_005cindex"> +<title><literal>\index</literal></title> + +<indexterm role="cp"><primary>index entry</primary></indexterm> +<indexterm role="fn"><primary>\index</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\index{<replaceable>index-entry-string</replaceable>} +</screen> +<para>Declare an entry in the index. This command is fragile +(see <link linkend="_005cprotect">\protect</link>). +</para> +<para>For example, as described in <link linkend="Indexes">Indexes</link>, one way to get an index from +what’s below is to compile the document with <literal>pdflatex test</literal>, then +process the index entries with <literal>makeindex test</literal>, and then compile +again with <literal>pdflatex test</literal>. +</para> +<screen>W~Ackermann (1896--1962).\index{Ackermann} + ... +Ackermann function\index{Ackermann!function} + ... +rate of growth\index{Ackermann!function!growth rate} +</screen> +<para>All three index entries will get a page number, such as ‘<literal>Ackermann, +22</literal>’. &latex; will format the second as a subitem of the first, on the +line below it and indented, and the third as a subitem of the second. +Three levels deep is as far as you can nest subentries. (If you add +<literal>\index{Ackermann!function!growth rate!comparison}</literal> then +<command>makeindex</command> says ‘<literal>Scanning input file test.idx....done (4 +entries accepted, 1 rejected)</literal>’ and nothing appears in the index). +</para> +<para>If you enter a second <literal>\index</literal> with the same +<replaceable>index-entry-string</replaceable> then you will get a single index entry with two +page numbers (unless they happen to fall on the same page). Thus, +adding <literal>as for Ackermann.\index{Ackermann}</literal> later in the same +document as above will give an index entry like ‘<literal>Ackermann, 22, +151</literal>’. Also, you can enter the index entries in any order, so for +instance <literal>\index{Ackermann!function}</literal> could come before +<literal>\index{Ackermann}</literal>. +</para> +<indexterm role="cp"><primary>index, page range</primary></indexterm> +<para>Get a page range in the output, like ‘<literal>Hilbert, 23--27</literal>’, as here. +</para> +<screen>W~Ackermann (1896--1962).\index{Ackermann} + ... +D~Hilbert (1862--1943)\index{Ackermann!Hilbert\(} + ... +disapproved of his marriage.\index{Ackermann!Hilbert\)} +</screen> +<para>If the beginning and ending of the page range are equal then the system +just gives a single page entry, not a range. +</para> +<para>If you index subentries but not a main entry, as with +<literal>\index{Jones!program}</literal> and <literal>\index{Jones!results}</literal>, then +the output is the item ‘<literal>Jones</literal>’ with no comma or page number, +followed by two subitems, like ‘<literal>program, 50</literal>’ and ‘<literal>results, +51</literal>’. +</para> +<indexterm role="cp"><primary>‘see’ and ‘see also’ index entries</primary></indexterm> +<indexterm role="cp"><primary>index entries, ‘see’ and ‘see also’</primary></indexterm> +<indexterm role="fn"><primary>\seename</primary></indexterm> +<indexterm role="fn"><primary>\alsoname</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>polyglossia</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>polyglossia</literal> package</primary></indexterm> + + +<para>Generate a index entry that says ‘<literal>See</literal>’ by using a vertical bar +character: <literal>\index{Ackermann!function|see{P\'eter's +function}}</literal>. You can instead get ‘<literal>See also</literal>’ with <literal>seealso</literal>. +(The text ‘<literal>See</literal>’ is defined by <literal>\seename</literal>, and ‘<literal>See also</literal>’ +by <literal>\alsoname</literal>. You can redefine these either by using an +internationalization package such as <filename>babel</filename> or <filename>polyglossia</filename>, +or directly as with <literal>\renewcommand{\alsoname}[1]{Also see +#1}</literal>.) +</para> +<para>The ‘<literal>See</literal>’ feature is part of a more general functionality. After +the vertical bar you can put the name of a one-input command, as in +<literal>\index{group|textit}</literal> (note the missing backslash on the +<literal>\textit</literal> command) and the system will apply that command to the +page number, here giving something like <literal>\textit{7}</literal>. You can +define your own one-input commands, such as +<literal>\newcommand{\definedpage}[1]{{\color{blue}#1}}</literal> and then +<literal>\index{Ackermann!function|definedpage}</literal> will give a blue page +number (see <link linkend="Color">Color</link>). Another, less practical, example is this, +</para> +<!-- credit Ian Thompson https://tex.stackexchange.com/a/272572/121234 --> +<screen>\newcommand\indexownpage[1]{#1, \thepage} + ... Epimenides.\index{self-reference|indexownpage} +</screen> +<para>which creates an entry citing the page number of its own index listing. +</para> +<para>The two functions just described combine, as here +</para> +<screen>\index{Ackermann!function|(definedpage} + ... +\index{Ackermann!function|)} +</screen> +<para>which outputs an index entry like ‘<literal>function, 23--27</literal>’ where the page +number range is in blue. +</para> +<para>Consider an index entry such as ‘<literal>α-ring</literal>’. Entering +it as <literal>$\alpha$-ring</literal> will cause it to be alphabetized according to +the dollar sign. You can instead enter it using an at-sign, as +<literal>\index{alpha-ring@$\alpha$-ring}</literal>. If you specify an entry +with an at-sign separating two strings, <literal><replaceable>pos</replaceable>@<replaceable>text</replaceable></literal>, +then <replaceable>pos</replaceable> gives the alphabetical position of the entry while +<replaceable>text</replaceable> produces the text of the entry. Another example is that +<literal>\index{Saint Michael's College@SMC}</literal> produces an index entry +‘<literal>SMC</literal>’ alphabetized into a different location than its spelling +would naturally give it. +</para> +<para>To put a <literal>!</literal>, or <literal>@</literal>, or <literal>|</literal> character in an index +entry, preceding it with a double quote, <literal>"</literal>. (The double quote +gets deleted before alphabetization.) +</para> +<indexterm role="cp"><primary>package, <literal>index</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>index</literal> package</primary></indexterm> + +<para>A number of packages on CTAN have additional functionality beyond that +provided by <filename>makeidx</filename>. One is <filename>index</filename>, which allows for +multiple indices and contains a command +<literal>\index*{<replaceable>index-entry-string</replaceable>}</literal> that prints the +<replaceable>index-entry-string</replaceable> as well as indexing it. +</para> +<indexterm role="fn"><primary>\indexentry</primary></indexterm> +<indexterm role="cp"><primary>idx file</primary></indexterm> +<para>The <literal>\index</literal> command writes the indexing information to the file +<filename><replaceable>root-name</replaceable>.idx</filename> file. Specifically, it writes text of the +command +<literal>\indexentry{<replaceable>index-entry-string</replaceable>}{<replaceable>page-num</replaceable>}</literal>, +where <replaceable>page-num</replaceable> is the value of the <literal>\thepage</literal> counter. On +occasion, when the <literal>\printindex</literal> command is confused, you have to +delete this file to start with a fresh slate. +</para> +<para>If you omit the closing brace of an <literal>\index</literal> command then you get a +message like this. +</para> +<screen>Runaway argument? {Ackermann!function +! Paragraph ended before \@wrindex was complete. +</screen> + +</sect2> +<sect2 label="25.2.2" id="makeindex"> +<title><command>makeindex</command></title> + +<indexterm role="cp"><primary>index, processing</primary></indexterm> +<indexterm role="fn"><primary>makeindex</primary></indexterm> +<indexterm role="cp"><primary><command>makeindex</command> program</primary></indexterm> +<indexterm role="cp"><primary><filename>.ind</filename> file</primary></indexterm> +<indexterm role="cp"><primary><filename>.idx</filename> file</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>makeindex <replaceable>filename</replaceable> +makeindex -s <replaceable>style-file</replaceable> <replaceable>filename</replaceable> +makeindex <replaceable>options</replaceable> <replaceable>filename0</replaceable> ... +</screen> +<para>Sort, and otherwise process, the index information in the auxiliary file +<replaceable>filename</replaceable>. This is a command line program. It takes one or more +raw index files, <filename><replaceable>filename</replaceable>.idx</filename> files, and produces the +actual index file, the <filename><replaceable>filename</replaceable>.ind</filename> file that is input by +<literal>\printindex</literal> (see <link linkend="_005cprintindex">\printindex</link>). +</para> +<indexterm role="cp"><primary><filename>.isty</filename> file</primary></indexterm> +<indexterm role="fn"><primary>index, style file</primary></indexterm> +<indexterm role="fn"><primary>makeindex, style file</primary></indexterm> +<para>The first form of the command suffices for many uses. The second allows +you to format the index by using an <firstterm>index style file</firstterm>, a +<filename>.isty</filename> file. The third form is the most general; see the full +documentation on CTAN. +</para> +<para>This is a simple <filename>.isty</filename> file. +</para> +<screen>% book.isty +% $ makeindex -s book.isty -p odd book.idx +% creates the index as book.ind, starting on an odd page. +preamble +"\\pagestyle{empty} +\\small +\\begin{theindex} +\\thispagestyle{empty}" + +postamble +"\n +\\end{theindex}" +</screen> +<para>The description here covers only some of the index formatting +possibilities in <replaceable>style-file</replaceable>. For a full list see the documentation +on CTAN. +</para> +<para>A style file consists of a list of pairs: <replaceable>specifier</replaceable> and +<replaceable>attribute</replaceable>. These can appear in the file in any order. All of the +<replaceable>attributes</replaceable> are strings, except where noted. Strings are +surrounded with double quotes, <literal>"</literal>, and the maximum length of a +string is 144 characters. The <literal>\n</literal> is for a newline and <literal>\t</literal> +is for a tab. Backslashes are escaped with another backslash, +<literal>\\</literal>. If a line begins with a percent sign, <literal>%</literal>, then it is a +comment. +</para> +<variablelist><anchor id="makeindex-preamble"/><varlistentry><term><indexterm role="fn"><primary>preamble</primary></indexterm><literal>preamble</literal> +</term><listitem><para>Preamble of the output file. Defines the context in which the index is +formatted. Default: <literal>"\\begin{theindex}\n"</literal>. +</para> +<anchor id="makeindex-postamble"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>postamble</primary></indexterm><literal>postamble</literal> +</term><listitem><para>Postamble of the output file. Default: <literal>"\n\n\\end{theindex}\n"</literal>. +</para> +<anchor id="makeindex-group-skip"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>group_skip</primary></indexterm><literal>group_skip</literal> +</term><listitem><indexterm role="fn"><primary>\indexspace</primary></indexterm> +<para>Traditionally index items are broken into groups, typically a group for +entries starting with ‘<literal>a</literal>’, etc. This specifier gives what is +inserted when a new group begins. Default: <literal>"\n\n \\indexspace\n"</literal> +(<literal>\indexspace</literal> is a rubber length with default value <literal>10pt +plus5pt minus3pt</literal>). +</para> +<anchor id="makeindex-letheadflag"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lethead_flag</primary></indexterm><literal>lethead_flag</literal> +</term><listitem><para>An integer. It governs what is inserted for a new group or letter. If +it is 0 (which is the default) then other than <literal>group_skip</literal> nothing +will be inserted before the group. If it is positive then at a new +letter the <literal>lethead_prefix</literal> and <literal>lethead_suffix</literal> will be +inserted, with that letter in uppercase between them. If it is negative +then what will be inserted is the letter in lowercase. The default +is 0. +</para> +<anchor id="makeindex-lethead-prefix"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lethead_prefix</primary></indexterm><literal>lethead_prefix</literal> +</term><listitem><para>If a new group begins with a different letter then this is the prefix +inserted before the new letter header. Default: <literal>""</literal> +</para> +<anchor id="makeindex-lethead-suffix"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>lethead_suffix</primary></indexterm><literal>lethead_suffix</literal> +</term><listitem><para>If a group begins with a different letter then this is the suffix +inserted after the new letter header. Default: <literal>""</literal>. +</para> +<anchor id="makeindex-item-0"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_0</primary></indexterm><literal>item_0</literal> +</term><listitem><para>What is put between two level 0 items. Default: <literal>"\n \\item +"</literal>. +</para> +<anchor id="makeindex-item-1"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_1</primary></indexterm><literal>item_1</literal> +</term><listitem><para>Put between two level 1 items. Default: <literal>"\n \\subitem "</literal>. +</para> +<anchor id="makeindex-item-2"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_2</primary></indexterm><literal>item_2</literal> +</term><listitem><para>put between two level 2 items. Default: <literal>"\n \\subsubitem "</literal>. +</para> +<anchor id="makeindex-item-01"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_01</primary></indexterm><literal>item_01</literal> +</term><listitem><para>What is put between a level 0 item and a level 1 item. +Default: <literal>"\n \\subitem "</literal>. +</para> +<anchor id="makeindex-item-x1"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_x1</primary></indexterm><literal>item_x1</literal> +</term><listitem><para>What is put between a level 0 item and a level 1 item in the +case that the level 0 item doesn’t have any page numbers (as in +<literal>\index{aaa|see{bbb}}</literal>). Default: <literal>"\n \\subitem "</literal>. +</para> +<anchor id="makeindex-item-12"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_12</primary></indexterm><literal>item_12</literal> +</term><listitem><para>What is put between a level 1 item and a level 2 item. +Default: <literal>"\n \\subsubitem "</literal>. +</para> +<anchor id="makeindex-item-x2"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>item_x2</primary></indexterm><literal>item_x2</literal> +</term><listitem><para>What is put between a level 1 item and a level 2 item, if the +level 1 item doesn’t have page numbers. Default: <literal>"\n +\\subsubitem "</literal>. +</para> +<anchor id="makeindex-delim-0"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>delim_0</primary></indexterm><literal>delim_0</literal> +</term><listitem><para>Delimiter put between a level 0 key and its first page +number. Default: a comma followed by a blank, <literal>", "</literal>. +</para> +<anchor id="makeindex-delim-1"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>delim_1</primary></indexterm><literal>delim_1</literal> +</term><listitem><para>Delimiter put between a level 1 key and its first page +number. Default: a comma followed by a blank, <literal>", "</literal>. +</para> +<anchor id="makeindex-delim-2"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>delim_2</primary></indexterm><literal>delim_2</literal> +</term><listitem><para>Delimiter between a level 2 key and its first page number. Default: +a comma followed by a blank, <literal>", "</literal>. +</para> +<anchor id="makeindex-delim-n"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>delim_n</primary></indexterm><literal>delim_n</literal> +</term><listitem><para>Delimiter between two page numbers for the same key (at any +level). Default: a comma followed by a blank, <literal>", "</literal>. +</para> +<anchor id="makeindex-delim-r"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>delim_r</primary></indexterm><literal>delim_r</literal> +</term><listitem><para>What is put between the starting and ending page numbers of a range. +Default: <literal>"--"</literal>. +</para> +<anchor id="makeindex-line-max"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>line_max</primary></indexterm><literal>line_max</literal> +</term><listitem><para>An integer. Maximum length of an index entry’s line in the output, +beyond which the line wraps. Default: <literal>72</literal>. +</para> +<anchor id="makeindex-indent-space"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>indent_space</primary></indexterm><literal>indent_space</literal> +</term><listitem><para>What is inserted at the start of a wrapped line. Default: +<literal>"\t\t"</literal>. +</para> +<anchor id="makeindex-indent-length"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>indent_length</primary></indexterm><literal>indent_length</literal> +</term><listitem><para>A number. The length of the wrapped line indentation. The default +<literal>indent_space</literal> is two tabs and each tab is eight spaces so the +default here is <literal>16</literal>. +</para> +<anchor id="makeindex-page-precedence"/></listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>page_precedence</primary></indexterm><literal>page_precedence</literal> +</term><listitem><para>A document may have pages numbered in different ways. For example, a +book may have front matter pages numbered in lowercase roman while main +matter pages are in arabic. This string specifies the order in which +they will appear in the index. The <command>makeindex</command> command supports +five different types of numerals: lowercase roman <literal>r</literal>, and numeric +or arabic <literal>n</literal>, and lowercase alphabetic <literal>a</literal>, and uppercase +roman <literal>R</literal>, and uppercase alphabetic <literal>A</literal>. Default: +<literal>"rnaRA"</literal>. +</para> +</listitem></varlistentry></variablelist> +<indexterm role="fn"><primary>xindy</primary></indexterm> +<indexterm role="cp"><primary><command>xindy</command> program</primary></indexterm> +<para>There are a number of other programs that do the job +<command>makeindex</command> does. One is <command>xindy</command>, which does +internationalization and can process indexes for documents marked up +using &latex; and a number of other languages. It is highly +configurable, both in markup terms and in terms of the collating order +of the text, as described in its documentation. +</para> + +</sect2> +<sect2 label="25.2.3" id="_005cprintindex"> +<title><command>\printindex</command></title> + +<indexterm role="cp"><primary>index, printing</primary></indexterm> +<indexterm role="fn"><primary>\printindex</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\printindex +</screen> +<indexterm role="fn"><primary>\printindex</primary></indexterm> +<para>Place the index into the output. +</para> +<para>To get an index you must first include +<literal>\usepackage{makeidx}\makeindex</literal> in the document preamble and +compile the document, then run the system command <command>makeindex</command>, +and then compile the document again. See <link linkend="Indexes">Indexes</link> for further +discussion and an example of the use of <literal>\printindex</literal>. +</para> + +</sect2> +</sect1> +<sect1 label="25.3" id="Glossaries"> +<title>Glossaries</title> + +<indexterm role="cp"><primary>glossary</primary></indexterm> +<indexterm role="cp"><primary>glossaries</primary></indexterm> +<indexterm role="cp"><primary>acronyms, list of</primary></indexterm> +<indexterm role="fn"><primary>\makeglossary</primary></indexterm> +<indexterm role="fn"><primary>\printglossaries</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\usepackage{glossaries} \makeglossaries + ... +\newglossaryentry{<replaceable>label</replaceable>}{<replaceable>settings</replaceable>} + ... +\gls{<replaceable>label</replaceable>}. + ... +\printglossaries +</screen> +<para>The <filename>glossaries</filename> package allows you to make glossaries, including +multiple glossaries, as well as lists of acronyms. +</para> +<para>To get the output from this example, compile the document (for instance +with <literal>pdflatex filename</literal>), then run the command line command +<literal>makeglossaries filename</literal>, and then compile the document again. +</para> +<screen>\documentclass{...} +\usepackage{glossaries} \makeglossaries +\newglossaryentry{tm}{% + name={Turing machine}, + description={A model of a machine that computes. The model is simple + but can compute anything any existing device can compute. + It is the standard model used in Computer Science.}, + } +\begin{document} +Everything begins with the definition of a \gls{tm}. + ... +\printglossaries +\end{document} +</screen> +<para>That gives two things. In the main text it outputs ‘<literal>... definition +of a Turing machine</literal>’. In addition, in a separate sectional unit headed +‘<literal>Glossary</literal>’ there appears a description list. In boldface it says +‘<literal>Turing machine</literal>’ and the rest of the item says in normal type +‘<literal>A model of a machine … Computer Science</literal>’. +</para> +<indexterm role="fn"><primary>\makeglossary</primary></indexterm> +<indexterm role="fn"><primary>\printglossaries</primary></indexterm> +<indexterm role="cp"><primary><filename>.glo</filename> file</primary></indexterm> +<para>The command <literal>\makeglossary</literal> opens the file that will contain the +entry information, <filename><replaceable>root-file</replaceable>.glo</filename>. Put the +<literal>\printglossaries</literal> command where you want the glossaries to appear +in your document. +</para> +<para>The <filename>glossaries</filename> package is very powerful. For instance, besides +the commands <literal>\newglossaryentry</literal> and <literal>\gls</literal>, there are similar +commands for a list of acronyms. See the package documentations on +CTAN. +</para> + + +<sect2 label="25.3.1" id="_005cnewglossaryentry"> +<title><literal>\newglossaryentry</literal></title> + +<indexterm role="cp"><primary>glossary, entries</primary></indexterm> +<indexterm role="fn"><primary>\newglossaryentry</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\newglossaryentry{<replaceable>label</replaceable>} +{ + name={<replaceable>name</replaceable>}, + description={<replaceable>description</replaceable>}, + <replaceable>other options</replaceable>, ... +} +</screen> +<para>or +</para> +<screen>\longnewglossaryentry{<replaceable>label</replaceable>} +{ + name={<replaceable>name</replaceable>}, + <replaceable>other options</replaceable> ..., +} +{<replaceable>description</replaceable>} +</screen> +<para>Declare a new entry for a glossary. The <replaceable>label</replaceable> must be unique for +the document. The settings associated with the label are pairs: +<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>. +</para> +<para>This puts the blackboard bold symbol for the real numbers ℝ in the +glossary. +</para> +<screen>\newglossaryentry{R} +{ + name={\ensuremath{\mathbb{R}}}, + description={the real numbers}, +} +</screen> +<para>Use the second command form if the <replaceable>description</replaceable> spans more than one +paragraph. +</para> +<para>For a full list of <replaceable>key</replaceable>s see the package documentation on CTAN but +here are a few. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>name</primary></indexterm><literal>name</literal> +</term><listitem><para>(Required.) The word, phrase, or symbol that you are defining. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>description</primary></indexterm><literal>description</literal> +</term><listitem><para>(Required.) The description that will appear in the glossary. +If this has more than one paragraph then you must use the second command +form given in the synopsis. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>plural</primary></indexterm><literal>plural</literal> +</term><listitem><para>The plural form of <replaceable>name</replaceable>. Refer to the plural form using +<literal>\glspl</literal> or <literal>\Glspl</literal> (see <link linkend="_005cgls">\gls</link>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>sort</primary></indexterm><literal>sort</literal> +</term><listitem><para>How to place this entry in the list of entries that the glossary holds. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>symbol</primary></indexterm><literal>symbol</literal> +</term><listitem><para>A symbol, such as a mathematical symbol, besides the name. +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="25.3.2" id="_005cgls"> +<title><literal>\gls</literal></title> + +<indexterm role="cp"><primary>glossary, entry reference</primary></indexterm> +<indexterm role="fn"><primary>\gls</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\gls{<replaceable>label</replaceable>} +\glspl{<replaceable>label</replaceable>} +\Gls{<replaceable>label</replaceable>} +\Glspl{<replaceable>label</replaceable>} +</screen> +<para>Refer to a glossary entry. The entries are declared with +<literal>\newglossaryentry</literal> (see <link linkend="_005cnewglossaryentry">\newglossaryentry</link>). +</para> +<para>This +</para> +<screen>\newglossaryentry{N}{% + name={the natural numbers}, + description={The numbers $0$, $1$, $2$, $\ldots$\@}, + symbol={\ensuremath{\mathbb{N}}}, + } + ... +Consider \gls{N}. +</screen> +<para>gives the output ‘<literal>Consider the natural numbers</literal>’. +</para> +<para>The second command form <literal>\glspl{<replaceable>label</replaceable>}</literal> produces the plural +of <replaceable>name</replaceable> (by default it tries adding an ‘<literal>s</literal>’). The third form +capitalizes the first letter of <replaceable>name</replaceable>, as does the fourth form, +which also takes the plural. +</para> + +</sect2> +</sect1> +</chapter> +<chapter label="26" id="Letters"> +<title>Letters</title> + +<indexterm role="cp"><primary>letters, writing</primary></indexterm> +<indexterm role="cp"><primary>writing letters</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\documentclass{letter} +\address{<replaceable>senders address</replaceable>} % return address +\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} + ... +\end{document} +</screen> +<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}{Ninon de l'Enclos \\ + l'h\^otel Sagonne} + ... + \end{letter} +</screen> +<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. +</para> +<para>Each <literal>letter</literal> environment body 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 enumerated lists to displayed math, except that commands +such as <literal>\chapter</literal> that make no sense in a letter are turned off. +Each <literal>letter</literal> environment body typically ends with a +<literal>\closing</literal> command such as <literal>\closing{Yours,}</literal>. +</para> +<indexterm role="fn"><primary>\\ for letters</primary></indexterm> +<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 sender name and the closing 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}{1958-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="26.1" id="_005caddress"> +<title><literal>\address</literal></title> + +<indexterm role="fn"><primary>\address</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\address{<replaceable>senders address</replaceable>} +</screen> +<para>Specify 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>This command is optional: if you do not use it then the letter is +formatted with some blank space on top, for copying onto pre-printed +letterhead paper. If you do use the <literal>\address</literal> declaration then 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="26.2" id="_005ccc"> +<title><literal>\cc</literal></title> + +<indexterm role="fn"><primary>\cc</primary></indexterm> +<indexterm role="cp"><primary>cc list, in letters</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\cc{<replaceable>name0</replaceable> \\ + ... } +</screen> +<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>. Put the names on different lines by separating them +with a double backslash, <literal>\\</literal>, as in: +</para> +<screen>\cc{President \\ + Vice President} +</screen> + +</sect1> +<sect1 label="26.3" id="_005cclosing"> +<title><literal>\closing</literal></title> + +<indexterm role="fn"><primary>\closing</primary></indexterm> +<indexterm role="cp"><primary>letters, ending</primary></indexterm> +<indexterm role="cp"><primary>closing letters</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\closing{<replaceable>text</replaceable>} +</screen> +<para>Produce the letter’s closing. This is optional, but usual. It appears +at the end of a letter, above a handwritten signature. For example: +</para> +<screen>\closing{Regards,} +</screen> + +</sect1> +<sect1 label="26.4" id="_005cencl"> +<title><literal>\encl</literal></title> + +<indexterm role="fn"><primary>\encl</primary></indexterm> +<indexterm role="cp"><primary>enclosure list</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\encl{<replaceable>first enclosed object</replaceable> \\ + ... } +</screen> +<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="26.5" id="_005clocation"> +<title><literal>\location</literal></title> + +<indexterm role="fn"><primary>\location</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\location{<replaceable>text</replaceable>} +</screen> +<para>The <replaceable>text</replaceable> appears centered at the bottom of the page. It only +appears if the page style is <literal>firstpage</literal>. +</para> + +</sect1> +<sect1 label="26.6" id="_005cmakelabels"> +<title><literal>\makelabels</literal></title> + +<indexterm role="fn"><primary>\makelabels</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\makelabels % in preamble +</screen> +<para>Optional, for a document that contains <literal>letter</literal> environments. If +you just put <literal>\makelabels</literal> in the preamble then at the end of the +document you will get a sheet with labels for all the recipients, one +for each letter environment, that you can copy to a sheet of peel-off +address labels. +</para> +<para>Customize the labels by redefining the commands <literal>\startlabels</literal>, +<literal>\mlabel</literal>, and <literal>\returnaddress</literal> (and perhaps <literal>\name</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>return address</replaceable>}{<replaceable>recipient +address</replaceable>}</literal> produces the two labels (or one, if you choose to ignore the +<replaceable>return address</replaceable>) for each letter environment. The first argument, +<replaceable>return address</replaceable>, is the value returned by the macro +<literal>\returnaddress</literal>. The second argument, <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>return +address</replaceable>, causing the default behavior described in the prior paragraph. +</para> +<para>This illustrates customization. Its output includes a page with two +columns having two labels each. +</para> +<screen>\documentclass{letter} +\renewcommand*{\returnaddress}{Fred McGuilicuddy \\ + Oshkosh, Mineola 12305} +\newcommand*\originalMlabel{} +\let\originalMlabel\mlabel +\def\mlabel#1#2{\originalMlabel{}{#1}\originalMlabel{}{#2}} +\makelabels + ... +\begin{document} +\begin{letter}{A Einstein \\ + 112 Mercer Street \\ + Princeton, New Jersey, USA 08540} + ... +\end{letter} +\begin{letter}{K G\"odel \\ + 145 Linden Lane \\ + Princeton, New Jersey, USA 08540} + ... +\end{letter} +\end{document} +</screen> +<para>The first column contains the return address twice. The second column +contains the address for each recipient. +</para> +<indexterm role="cp"><primary>package, <literal>envlab</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>envlab</literal> package</primary></indexterm> + +<para>The package <literal>envlab</literal> makes formatting the labels easier, with +standard sizes already provided. The preamble lines +<literal>\usepackage[personalenvelope]{envlab}</literal> and <literal>\makelabels</literal> +are all that you need to print envelopes. +</para> + +</sect1> +<sect1 label="26.7" id="_005cname"> +<title><literal>\name</literal></title> + +<indexterm role="fn"><primary>\name</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\name{<replaceable>name</replaceable>} +</screen> +<para>Optional. Sender’s name, used for printing on the envelope together +with the return address. +</para> + +</sect1> +<sect1 label="26.8" id="_005copening"> +<title><literal>\opening</literal></title> + +<indexterm role="fn"><primary>\opening</primary></indexterm> +<indexterm role="cp"><primary>letters, starting</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\opening{<replaceable>salutation</replaceable>} +</screen> +<para>Required. Follows the <literal>\begin{letter}{...}</literal>. The argument +<replaceable>salutation</replaceable> is mandatory. For instance: +</para> +<screen>\opening{Dear John:} +</screen> + +</sect1> +<sect1 label="26.9" id="_005cps"> +<title><literal>\ps</literal></title> +<indexterm role="fn"><primary>\ps</primary></indexterm> +<indexterm role="cp"><primary>postscript, in letters</primary></indexterm> + +<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="26.10" id="_005csignature"> +<title><literal>\signature</literal></title> + +<para>Synopsis: +</para> +<screen>\signature{<replaceable>first line</replaceable> \\ + ... } +</screen> +<indexterm role="fn"><primary>\signature</primary></indexterm> + +<para>The sender’s name. This command is optional, although its inclusion is +usual. +</para> +<para>The argument text appears at the end of the letter, after the closing. +&latex; leaves some vertical space for a handwritten +signature. Separate multiple lines with a double +backslash, <literal>\\</literal>. For example: +</para> +<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 <literal>\medskipamount</literal> (where <literal>\medskipamount</literal> is equal to +a <literal>\parskip</literal>, which in turn is defined by default here to +0.7em). +</para> +<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 as here. +</para> +<screen>\signature{\vspace{-6\medskipamount}\includegraphics{sig.png}\\ + My name} +</screen> +<para>For this you must put <literal>\usepackage{graphicx}</literal> in the preamble +(see <link linkend="Graphics">Graphics</link>). +</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="26.11" id="_005ctelephone"> +<title><literal>\telephone</literal></title> + +<indexterm role="fn"><primary>\telephone</primary></indexterm> + +<para>Synopsis: +</para> +<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="27" id="Terminal-input_002foutput"> +<title>Terminal input/output</title> + +<indexterm role="cp"><primary>input/output, to terminal</primary></indexterm> +<indexterm role="cp"><primary>terminal input/output</primary></indexterm> + + + +<sect1 label="27.1" id="_005ctypein"> +<title><literal>\typein</literal></title> + +<indexterm role="fn"><primary>\typein</primary></indexterm> + +<para>Synopsis, one of: +</para> +<screen>\typein{<replaceable>prompt-msg</replaceable>} +\typein[<replaceable>cmd</replaceable>]{<replaceable>prompt-msg</replaceable>} +</screen> +<para>Print <replaceable>prompt-msg</replaceable> on the terminal and cause &latex; to stop and +wait for you to type a line of input. This line of input ends when you +hit the return key. +</para> +<para>For example, this +</para> +<screen>As long as I live I shall never forget \typein{Enter student name:} +</screen> +<para>coupled with this command line interaction +</para> +<screen>Enter student name: + +\@typein=Aphra Behn +</screen> +<para>gives the output ‘<literal>... never forget Aphra Behn</literal>’. +</para> +<para>The first command version, <literal>\typein{<replaceable>prompt-msg</replaceable>}</literal>, causes +the input you typed to be processed as if it had been included in the +input file in place of the <literal>\typein</literal> command. +</para> +<para>In the second command version the optional argument <literal><replaceable>cmd</replaceable></literal> +argument must be a command name — it must begin with a backslash, \. +This command name is then defined or redefined to be the input that you +typed. For example, this +</para> +<screen>\typein[\student]{Enter student name:} +\typeout{Recommendation for \student .} +</screen> +<para>gives this output on the command line, +</para> +<screen>Enter student name: + +\student=John Dee +Recommendation for John Dee. +</screen> +<para>where the user has entered ‘<literal>John Dee.</literal>’ +</para> + +</sect1> +<sect1 label="27.2" id="_005ctypeout"> +<title><literal>\typeout</literal></title> + +<indexterm role="fn"><primary>\typeout</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\typeout{<replaceable>msg</replaceable>} +</screen> +<para>Print <literal>msg</literal> on the terminal and in the <literal>log</literal> file. +</para> +<para>This +</para> +<screen>\newcommand{\student}{John Dee} +\typeout{Recommendation for \student .} +</screen> +<para>outputs ‘<literal>Recommendation for John Dee</literal>’. Like what happens here with +<literal>\student</literal>, commands that are defined with <literal>\newcommand</literal> or +<literal>\renewcommand</literal> (among others) are replaced by their definitions +before being printed. +</para> +<para>&latex;’s usual rules for treating multiple spaces as a single space +and ignoring spaces after a command name apply to <literal>msg</literal>. As above, +use the command <literal>\space</literal> to get a single space, independent of +surrounding spaces. Use <literal>^^J</literal> to get a newline. Get a percent +character with <literal>\csname @percentchar\endcsname</literal>. +</para> +<para>This command can be useful for simple debugging, as here: +</para> +<screen>\newlength{\jhlength} +\setlength{\jhlength}{5pt} +\typeout{The length is \the\jhlength.} +</screen> +<para>produces on the command line ‘<literal>The length is 5.0pt</literal>’. +</para> + +</sect1> +</chapter> +<chapter label="28" id="Command-line"> +<title>Command line</title> + +<indexterm role="cp"><primary>command line</primary></indexterm> + +<para>Synopsis (from a terminal command line): +</para> +<screen>pdflatex <replaceable>options</replaceable> <replaceable>argument</replaceable> +</screen> +<para>Run &latex; on <replaceable>argument</replaceable>. In place of <command>pdflatex</command> you can +also use <command>xelatex</command>, or <literal>lualatex</literal>, or <literal>dviluatex</literal>, or +<literal>latex</literal>. +</para> +<para>For example, this will run &latex; on the file <filename>thesis.tex</filename>, +creating the output <filename>thesis.pdf</filename>. +</para> +<screen>pdflatex thesis +</screen> +<para><indexterm role="fn"><primary>.tex, default extension</primary></indexterm> +Note that <filename>.tex</filename> is the default file extension. +</para> +<para>pdf&tex; is a development of the original &tex; program, as are +Xe&tex; and Lua&tex; (see <link linkend="TeX-engines">&tex; engines</link>). They are completely +backward compatible. But the original program had a custom output +format, DVI, while the newer ones can output directly to PDF. This +allows them to take advantage of the extra features in PDF such as +hyperlinks, support for modern image formats such as JPG and PNG, and +ubiquitous viewing programs. In short, if you run <command>pdflatex</command> or +<command>xelatex</command> or <command>lualatex</command> then you will by default get PDF +and have access to all its modern features. If you run <command>latex</command>, +or <literal>dvilualatex</literal>, then you will get DVI. The description here +assumes pdf&latex;. +</para> +<para>See <link linkend="Command-line-options">Command line options</link>, for a selection of the most useful +command line options. As to <replaceable>argument</replaceable>, the usual case is that it +does not begin with a backslash, so the system takes it to be the name +of a file and it compiles that file. If <replaceable>argument</replaceable> begins with a +backslash then the system will interpret it as a line of &latex; +input, which can be used for special effects (see <link linkend="Command-line-input">Command line +input</link>). +</para> +<para>If you gave no arguments or options then <command>pdflatex</command> prompts for +input from the terminal. You can escape from this by entering +<literal><control>-D</literal>. +</para> +<para>If &latex; finds an error in your document then by default it stops and +asks you about it. See <link linkend="Recovering-from-errors">Recovering from errors</link> for an outline of what +to do. +</para> + + +<sect1 label="28.1" id="Command-line-options"> +<title>Command line options</title> + +<indexterm role="cp"><primary>options, command line</primary></indexterm> + +<para>These are the command-line options relevant to ordinary document +authoring. For a full list, try running ‘<literal>latex --help</literal>’ from the +command line. +</para> +<para>With many implementations you can specify command line options by +prefixing them with ‘<literal>-</literal>’ or ‘<literal>--</literal>’. This is the case for +both &tex; Live (and Mac&tex;) and MiK&tex;. We will use both +conventions interchangeably. +</para> +<variablelist><indexterm role="fn"><primary>--version command-line option</primary></indexterm> +<varlistentry><term><literal>-version</literal> +</term><listitem><para>Show the current version, like ‘<literal>pdfTeX 3.14159265-2.6-1.40.16 (TeX +Live 2015/Debian)</literal>’ along with a small amount of additional information, +and exit. +</para> +<indexterm role="fn"><primary>--help command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-help</literal> +</term><listitem><para>Give a brief usage message that is useful as a prompt and exit. +</para> +<indexterm role="fn"><primary>--interaction command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-interaction=<replaceable>mode</replaceable></literal> +</term><listitem><para>&tex; compiles a document in one of four interaction modes: +<literal>batchmode</literal>, <literal>nonstopmode</literal>, <literal>scrollmode</literal>, +<literal>errorstopmode</literal>. In <firstterm>errorstop mode</firstterm> (the default), &tex; +stops at each error and asks for user intervention. In <firstterm>batch +mode</firstterm> it prints nothing on the terminal, errors are scrolled as if the +user hit <literal><return></literal> at every error, and missing files cause the +job to abort. In <firstterm>nonstop mode</firstterm>, diagnostic message appear on the +terminal but as in batch mode there is no user interaction. In +<firstterm>scroll mode</firstterm>, &tex; only stops for missing files or keyboard +input. +</para> +<para>For instance, starting &latex; with this command line +</para> +<screen>pdflatex -interaction=batchmode <replaceable>filename</replaceable> +</screen> +<para>eliminates most terminal output. +</para> +<indexterm role="fn"><primary>--jobname command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-jobname=<replaceable>string</replaceable></literal> +</term><listitem><para>Set the value of &tex;’s <literal>jobname</literal> to the string. The log file +and output file will then be named <filename><replaceable>string</replaceable>.log</filename> and +<filename><replaceable>string</replaceable>.pdf</filename>. +</para> +<para>When you run <literal><command>pdflatex</command> <replaceable>options</replaceable> <replaceable>argument</replaceable></literal>, if +<replaceable>argument</replaceable> does not start with a backslash then &tex; considers it +the name of a file to input. Otherwise it waits for the first +<literal>\input</literal> instruction and the name of the input file will be the job +name. This is used to name the log file the output file. The +<literal>jobname</literal> option overrides that process and directly specifies the +name. See <link linkend="Command-line-input">Command line input</link> for an example of its use. +</para> +<indexterm role="fn"><primary>--output-directory command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-output-directory=<replaceable>directory</replaceable></literal> +</term><listitem><para>Write files in the directory <replaceable>directory</replaceable>. It must already exist. +</para> +<indexterm role="fn"><primary>--shell-escape command-line option</primary></indexterm> +<indexterm role="fn"><primary>--no-shell-escape command-line option</primary></indexterm> +<indexterm role="fn"><primary>--enable-write18 command-line option</primary></indexterm> +<indexterm role="fn"><primary>--disable-write18 command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>--shell-escape</literal> +</term><term><literal>--no-shell-escape</literal> +</term><term><literal>--enable-write18</literal> +</term><term><literal>--disable-write18</literal> +</term><listitem><para>Enable or disable <literal>\write18{<replaceable>shell command</replaceable>}</literal>. The first two +options are for with &tex; Live or Mac&tex; while the second two are +for MiK&tex;. +</para> +<indexterm role="cp"><primary>package, <literal>sagetex</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>sagetex</literal> package</primary></indexterm> + +<para>Sometimes you want to run external system commands from inside a +&latex; file. For instance the package <filename>sagetex</filename> allows you to +have the mathematics software system <emphasis>Sage</emphasis> do calculations or draw +graphs and then incorporate that output in your document. For this +&tex; provides the <literal>\write18</literal> command. +</para> +<para>But with this functionality enabled, security issues could happen if you +compiled a &latex; file from the Internet. By default <literal>\write18</literal> +is disabled. (More precisely, by default &tex; Live, Mac&tex;, and +MiK&tex; only allow the execution of a limited number of &tex;-related +programs, which they distribute.) +</para> +<para>If you invoke &latex; with the option <literal>no-shell-escape</literal>, and in +your document you call <literal>\write18{ls -l}</literal>, then you do not get an +error but the log file says ‘<literal>runsystem(ls -l)...disabled</literal>’. +</para> +<indexterm role="fn"><primary>--halt-on-error command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-halt-on-error</literal> +</term><listitem><para>Stop processing at the first error. +</para> +<indexterm role="fn"><primary>--file-line-error command-line option</primary></indexterm> +<indexterm role="fn"><primary>--no-file-line-error command-line option</primary></indexterm> +</listitem></varlistentry><varlistentry><term><literal>-file-line-error</literal> +</term></varlistentry><varlistentry><term><literal>-no-file-line-error</literal> +</term><listitem><para>Enable or disable <literal><replaceable>filename</replaceable>:<replaceable>lineno</replaceable>:<replaceable>error</replaceable></literal>-style +error messages. These are only available with &tex; Live or Mac&tex;. +</para></listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="28.2" id="Command-line-input"> +<title>Command line input</title> + +<indexterm role="cp"><primary>input, on command line</primary></indexterm> + +<para>As part of the command line invocation <literal>pdflatex <replaceable>options</replaceable> +<replaceable>argument</replaceable></literal> you can specify arbitrary &latex; input by starting +<replaceable>argument</replaceable> with a backslash. This allows you to do some special +effects. +</para> +<indexterm role="cp"><primary>package, <literal>hyperref</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>hyperref</literal> package</primary></indexterm> + +<para>For example, this file (which uses the <filename>hyperref</filename> package for +hyperlinks) can produce two kinds of output, one for paper and one for a +PDF. +</para> +<screen>\ifdefined\paperversion % in preamble +\newcommand{\urlcolor}{black} +\else +\newcommand{\urlcolor}{blue} +\fi +\usepackage[colorlinks=true,urlcolor=\urlcolor]{hyperref} + ... +\href{https://www.ctan.org}{CTAN} % in body + ... +</screen> +<para>Compiling this document <filename>book.tex</filename> with the command line +<literal>pdflatex book</literal> will give the ‘<literal>CTAN</literal>’ link in blue. But +compiling it with <literal>pdflatex "\def\paperversion{}\input book.tex"</literal> +has the link in black. (Note the use of double quotes to prevent +interpretation of the symbols by the command line shell; your system may +do this differently.) +</para> +<para>In a similar way, from the single file <filename>main.tex</filename> you can compile +two different versions. +</para> +<!-- credit Paul Gaborit: https://tex.stackexchange.com/a/220101/121234 --> +<screen>pdflatex -jobname=students "\def\student{}\input{main}" +pdflatex -jobname=teachers "\def\teachers{}\input{main}" +</screen> +<para>The <literal>jobname</literal> option is there because otherwise both files would be +called <filename>main.pdf</filename> and the second would overwrite the first. +</para> +<para>A final example. This loads the package <filename>graphicx</filename> with the option +<literal>draft</literal> +</para> +<!-- credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234 --> +<screen>pdflatex -jobname=aa "\RequirePackage[draft]{graphicx}\input{aa.tex}" +</screen> +<para>so the graphic files are read for their size information but not +incorporated into the PDF. (The <literal>jobname</literal> option is there because +otherwise the output file would be <filename>graphicx.pdf</filename>, as +<literal>\RequirePackage</literal> does an <literal>\input</literal> of its own.) +</para> + +</sect1> +<sect1 label="28.3" id="Recovering-from-errors"> +<title>Recovering from errors</title> + +<para>If &latex; finds an error in your document then it gives you an error +message and prompts you with a question mark, <literal>?</literal>. For instance, +running &latex; on this file +</para> +<screen>\newcommand{\NP}{\ensuremath{\textbf{NP}}} +The \PN{} problem is a million dollar one. +</screen> +<para>causes it show this, and wait for input. +</para> +<screen>! Undefined control sequence. +l.5 The \PN + {} problem is a million dollar one. +? +</screen> +<para>The simplest thing is to enter ‘<literal>x</literal>’ and <literal><return></literal> and fix the +typo. You could instead enter ‘<literal>?</literal>’ and <literal><return></literal> to see other +options. +</para> +<indexterm role="cp"><primary>‘<literal>*</literal>’ prompt</primary></indexterm> +<indexterm role="cp"><primary>prompt, ‘<literal>*</literal>’</primary></indexterm> +<indexterm role="fn"><primary>\stop</primary></indexterm> +<para>There are two other error scenarios. The first is that you forgot to +include the <literal>\end{document}</literal> or misspelled it. In this case +&latex; gives you a ‘<literal>*</literal>’ prompt. You can get back to the command +line by typing <literal>\stop</literal> and <literal><return></literal>. +</para> +<para>The last scenario is that you mistyped the file name. For instance, +instead of <literal>pdflatex test</literal> you might type <literal>pdflatex tste</literal>. +</para> +<screen>! I can't find file `tste'. +<*> tste + +(Press Enter to retry, or Control-D to exit) +Please type another input file name: +</screen> +<para>The simplest thing is to enter <literal><Control></literal> and ‘<literal>d</literal>’ (holding +them down at the same time), and then retype the correct command line. +</para> + +</sect1> +</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 +<ulink url="http://tug.org/interest.html#latextemplates">http://tug.org/interest.html#latextemplates</ulink>. +</para> + + +<sect1 label="A.1" id="beamer-template"> +<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> +<screen>\documentclass{beamer} + +\title{Beamer Class template} +\author{Alex Author} +\date{July 31, 2007} + +\begin{document} + +\maketitle + +% without [fragile], any {verbatim} code gets mysterious errors. +\begin{frame}[fragile] + \frametitle{First Slide} + +\begin{verbatim} + This is \verbatim! +\end{verbatim} + +\end{frame} + +\end{document} +</screen> +<para>One web resource for this: +<ulink url="http://robjhyndman.com/hyndsight/beamer/">http://robjhyndman.com/hyndsight/beamer/</ulink>. +</para> + +</sect1> +<sect1 label="A.2" id="article-template"> +<title><literal>article</literal> template</title> + +<indexterm role="cp"><primary>template, <literal>article</literal></primary></indexterm> + +<screen>\documentclass{article} +\title{Article Class Template} +\author{Alex Author} + +\begin{document} +\maketitle + +\section{First section} +Some text. + +\subsection{First section, first subsection} +Additional text. + +\section{Second section} +Some more text. +\end{document} +</screen> + +</sect1> +<sect1 label="A.3" id="book-template"> +<title><literal>book</literal> template</title> + +<indexterm role="cp"><primary>template, <literal>book</literal></primary></indexterm> + +<para>This is a straightforward template for a book. See See <link linkend="Larger-book-template">Larger book +template</link> for a more elaborate one. +</para> +<screen>\documentclass{book} +\title{Book Class Template} +\author{Alex Author} + +\begin{document} +\maketitle + +\chapter{First} +Some text. + +\chapter{Second} +Some other text. + +\section{A subtopic} +The end. +\end{document} +</screen> + +</sect1> +<sect1 label="A.4" id="Larger-book-template"> +<title>Larger <literal>book</literal> template</title> + +<indexterm role="cp"><primary>template, <literal>book</literal></primary></indexterm> + +<para>This is a more elaborate template for a book. It has +<literal>\frontmatter</literal>, <literal>\mainmatter</literal>, and <literal>\backmatter</literal> to +control the typography of the three main areas of a book +(see <link linkend="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter">\frontmatter & \mainmatter & \backmatter</link>). The book has a +bibliography and an index. +</para> +<para>Notable is that it uses <literal>\include</literal> and <literal>\includeonly</literal> +(see <link linkend="Splitting-the-input">Splitting the input</link>). While you are working on a chapter you +can comment out all the other chapter entries from the argument to +<literal>\includeonly</literal>. That will speed up compilation without losing any +information such as cross-references. (Material that does not need to +come on a new page is brought in with <literal>\input</literal> instead of +<literal>\include</literal>. You don’t get the cross-reference benefit this way.) +</para> +<screen>\documentclass[titlepage]{book} +\usepackage{makeidx}\makeindex + +\title{Book Class Template} +\author{Alex Author} + +\includeonly{% + frontcover, + preface, + chap1, + ... + } +\begin{document} +\frontmatter +\include{frontcover} + % maybe comment out while drafting: +\maketitle \input{dedication} \input{copyright} +\tableofcontents +\include{preface} +\mainmatter +\include{chap1} +... +\appendix +\include{appena} +... +\backmatter +\bibliographystyle{apalike} +\addcontentsline{toc}{chapter}{Bibliography} +\bibliography +\addcontentsline{toc}{chapter}{Index} +\printindex +\include{backcover} +\end{document} +</screen> + +</sect1> +<sect1 label="A.5" 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> + +<para><citetitle>TUGboat</citetitle> is the journal of the &tex; Users Group, +<ulink url="http://tug.org/TUGboat">http://tug.org/TUGboat</ulink>. +</para> +<screen>\documentclass{ltugboat} + +\usepackage{graphicx} +\usepackage{ifpdf} +\ifpdf +\usepackage[breaklinks,hidelinks]{hyperref} +\else +\usepackage{url} +\fi + +%%% Start of metadata %%% + +\title{Example \TUB\ article} + +% repeat info for each author. +\author{First Last} +\address{Street Address \\ Town, Postal \\ Country} +\netaddress{user (at) example dot org} +\personalURL{http://example.org/~user/} + +%%% End of metadata %%% + +\begin{document} + +\maketitle + +\begin{abstract} +This is an example article for \TUB{}. +Please write an abstract. +\end{abstract} + +\section{Introduction} + +This is an example article for \TUB, linked from +\url{http://tug.org/TUGboat/location.html}. + +We recommend the \texttt{graphicx} package for image inclusions, and the +\texttt{hyperref} package if active urls are desired (in the \acro{PDF} +output). Nowadays \TUB\ is produced using \acro{PDF} files exclusively. + +The \texttt{ltugboat} class provides these abbreviations (and many more): +% verbatim blocks are often better in \small +\begin{verbatim}[\small] +\AllTeX \AMS \AmS \AmSLaTeX \AmSTeX \aw \AW +\BibTeX \CTAN \DTD \HTML +\ISBN \ISSN \LaTeXe +\mf \MFB +\plain \POBox \PS +\SGML \TANGLE \TB \TP +\TUB \TUG \tug +\UNIX \XeT \WEB \WEAVE + +\, \bull \Dash \dash \hyph + +\acro{FRED} -> {\small[er] fred} % please use! +\cs{fred} -> \fred +\meta{fred} -> <fred> +\nth{n} -> 1st, 2nd, ... +\sfrac{3/4} -> 3/4 +\booktitle{Book of Fred} +\end{verbatim} + +For references to other \TUB\ issue, please use the format +\textsl{volno:issno}, e.g., ``\TUB\ 32:1'' for our \nth{100} issue. + +This file is just a template. The \TUB\ style documentation is the +\texttt{ltubguid} document at \url{http://ctan.org/pkg/tugboat}. (For +\CTAN\ references, where sensible we recommend that form of url, using +\texttt{/pkg/}; or, if you need to refer to a specific file location, +\texttt{http://mirror.ctan.org/\textsl{path}}.) + +Email \verb|tugboat@tug.org| if problems or questions. + +\bibliographystyle{plain} % we recommend the plain bibliography style +\nocite{book-minimal} % just making the bibliography non-empty +\bibliography{xampl} % xampl.bib comes with BibTeX + +\makesignature +\end{document} +</screen> + +</sect1> +</appendix> +<chapter label="" id="Index"> +<title>Index</title> + +<!-- Keep `Command Index' working for ltx-help.el. --> +<anchor id="Command-Index"/> +<index role="cp"></index> + +</chapter> +</book> |