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.xml |
Initial commit
Diffstat (limited to 'info/latex2e-help-texinfo/latex2e.xml')
-rw-r--r-- | info/latex2e-help-texinfo/latex2e.xml | 19395 |
1 files changed, 19395 insertions, 0 deletions
diff --git a/info/latex2e-help-texinfo/latex2e.xml b/info/latex2e-help-texinfo/latex2e.xml new file mode 100644 index 0000000000..9ba4e402d7 --- /dev/null +++ b/info/latex2e-help-texinfo/latex2e.xml @@ -0,0 +1,19395 @@ +<?xml version="1.0"?> +<!DOCTYPE texinfo PUBLIC "-//GNU//DTD TexinfoML V6.4//EN" "http://www.gnu.org/software/texinfo/dtd/6.4/texinfo.dtd"> +<texinfo xml:lang="en"> +<filename file="latex2e.xml"></filename> +<preamble>\input texinfo +</preamble><!-- c $Id: latex2e.texi 710 2018-10-14 14:32:52Z karl $ --> +<!-- comment %**start of header (This is for running Texinfo on a region.) --> +<setfilename file="latex2e.info" spaces=" ">latex2e.info</setfilename> +<set name="UPDATED" line=" UPDATED October 2018">October 2018</set> +<!-- c $Id: common.texi 701 2018-10-08 14:32:37Z jimhefferon $ --> +<!-- c Public domain. --> +<set name="LTXREFMAN_HOME_PAGE" line=" LTXREFMAN_HOME_PAGE https://puszcza.gnu.org.ua/software/latexrefman">https://puszcza.gnu.org.ua/software/latexrefman</set> +<set name="LTXREFMAN_BUGS" line=" LTXREFMAN_BUGS latexrefman@@tug.org">latexrefman@@tug.org</set> +<clear name="HAS-MATH" line=" HAS-MATH "></clear> +<macro name="iftexthenelse" line=" iftexthenelse {then,else}"><formalarg>then</formalarg><formalarg>else</formalarg>\else\@c +</macro> + + +<settitle spaces=" ">&latex;2e unofficial reference manual (October 2018)</settitle> +<!-- comment %**end of header (This is for running Texinfo on a region.) --> + +<!-- c latex 2.09 commands should all be present now, --> +<!-- c xx but latex2e stuff is missing. --> +<!-- c xx random list of a few of the missing items is at the end of this file --> +<!-- c --> +<!-- c xx ctan, distributions, components of TeX --> +<!-- c xx classes and packages - required, additional, useful; oberdiek; fonts --> +<!-- c --> +<!-- c xx merge permuted-index --> +<!-- c xx merge latex-manual from savannah --> +<!-- c xx merge display style math --> +<!-- c xx JH explain nfss somewhere --> +<!-- c xx JH expand BiBTeX --> +<!-- c xx JH expand theorem, AMS math --> +<!-- c xx JH something on code listings --> +<!-- c xx JH ligatures --> +<!-- c xx JH \xspace --> +<!-- c xx JH \stretch --> +<!-- c xx JH \mathstrut --> +<!-- c xx JH \phantom https://tex.stackexchange.com/questions/4519/how-do-i-create-an-invisible-character --> +<!-- c xx JH \baselineskip https://texfaq.org/FAQ-baselinepar --> +<!-- c xx JH \contentsline, \@@dottedtocline? --> +<!-- c xx JH more on \write18, beyond what's mentioned in Command line. --> +<!-- c xx JH \numexpr, \dimexpr, \glueexpr, \muexpr --> +<!-- c --> +<!-- c xx The typeset source2e has an index with all kernel --> +<!-- c xx commands, though some are internal and shouldn't be included. --> +<!-- c xx classes.dtx et al. define additional commands. --> +<!-- c xx See also http://ctan.org/pkg/macros2e. --> + +<copying endspaces=" "> +<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 <file>LATEX.HLP</file> 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 <cite>Hypertext Help with &latex;</cite>, by Sheldon Green, and +<cite>&latex; Command Summary</cite> (for &latex; 2.09) by +L. Botway and C. Biemesderfer (published by the &tex; Users +Group as <cite>&tex;niques</cite> 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.&linebreak; +Copyright 1988, 1994, 2007 Stephen Gilmore.&linebreak; +Copyright 1994, 1995, 1996 Torsten Martinsen. +</para> +<!-- comment 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> +<ignore> +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +</ignore> + +<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. +<!-- comment end of License --> +</para></copying> + +<!-- c Merge into one index (arbitrarily chosen to be the concept index). --> +<syncodeindex from="fn" to="cp" line=" fn cp"></syncodeindex> + +<dircategory spaces=" ">TeX</dircategory> +<direntry endspaces=" "> +<menuentry leadingtext="* "><menutitle separator=": ">LaTeX2e</menutitle><menunode separator=". ">(latex2e)</menunode><menudescription><pre xml:space="preserve">Unofficial LaTeX reference manual. +</pre></menudescription></menuentry></direntry> + +<tex endspaces=" "> +</tex> + +<titlepage endspaces=" "> +<title spaces=" ">&latex;2e: An unofficial reference manual</title> +<subtitle spaces=" ">October 2018</subtitle> +<author spaces=" "><url><urefurl>https://puszcza.gnu.org.ua/software/latexrefman</urefurl></url></author> +<page></page> +<vskip> 0pt plus 1filll</vskip> +<insertcopying></insertcopying> +</titlepage> + +<shortcontents></shortcontents> +<contents></contents> + +<!-- c Best Effort Symbol --> +<macro name="BES" line=" BES {utf8,math}"><formalarg>utf8</formalarg><formalarg>math</formalarg>@U{\utf8\} +</macro> +<macro name="BESU" line=" BESU {utf8,math}"><formalarg>utf8</formalarg><formalarg>math</formalarg>@U{\utf8\} +</macro> +<macro name="EnvIndex" line=" EnvIndex {env}"><formalarg>env</formalarg>@findex @r{environment}, @code{\env\} +@findex @code{\env\} @r{environment} + +</macro> +<macro name="PkgIndex" line=" PkgIndex {pkg}"><formalarg>pkg</formalarg>@cindex @r{package}, @code{\pkg\} +@cindex @code{\pkg\} @r{package} + +</macro> + +<set name="NotInPlainTeX" line=" NotInPlainTeX Not available in plain @TeX{}.">Not available in plain @TeX{}.</set> +<set name="NeedsAMSSymb" line=" NeedsAMSSymb @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{amssymb} package.">@value{NotInPlainTeX} In @LaTeX{} you need to load the @file{amssymb} package.</set> +<set name="NeedsSTIX" line=" NeedsSTIX @value{NotInPlainTeX} In @LaTeX{} you need to load the @file{stix} package.">@value{NotInPlainTeX} In @LaTeX{} you need to load the @file{stix} package.</set> + +<node name="Top" spaces=" "><nodename>Top</nodename><nodenext automatic="on">About this document</nodenext><nodeup automatic="on">(dir)</nodeup></node> +<top spaces=" "><sectiontitle>&latex;2e: An unofficial reference manual</sectiontitle> + +<para>This document is an unofficial reference manual (version of +October 2018) for &latex;2e, a document preparation system. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">About this document</menunode><menudescription><pre xml:space="preserve">Bug reporting, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Overview</menunode><menudescription><pre xml:space="preserve">What is &latex;? +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Document classes</menunode><menudescription><pre xml:space="preserve">Some of the various classes available. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Fonts</menunode><menudescription><pre xml:space="preserve">Italic, bold, typewriter, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Layout</menunode><menudescription><pre xml:space="preserve">Controlling the page layout. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Sectioning</menunode><menudescription><pre xml:space="preserve">Parts, Chapters, Sections, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Cross references</menunode><menudescription><pre xml:space="preserve">Automatic referencing. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Environments</menunode><menudescription><pre xml:space="preserve">Such as enumerate & itemize. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Line breaking</menunode><menudescription><pre xml:space="preserve">Influencing line breaks. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Page breaking</menunode><menudescription><pre xml:space="preserve">Influencing page breaks. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Footnotes</menunode><menudescription><pre xml:space="preserve">How to produce footnotes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Definitions</menunode><menudescription><pre xml:space="preserve">Define your own commands, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Counters</menunode><menudescription><pre xml:space="preserve">Internal counters used by &latex;. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Lengths</menunode><menudescription><pre xml:space="preserve">The length commands. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Making paragraphs</menunode><menudescription><pre xml:space="preserve">Paragraph commands. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Math formulas</menunode><menudescription><pre xml:space="preserve">How to create mathematical formulas. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Modes</menunode><menudescription><pre xml:space="preserve">Paragraph, Math or LR modes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Page styles</menunode><menudescription><pre xml:space="preserve">Various styles of page layout. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Spaces</menunode><menudescription><pre xml:space="preserve">Horizontal and vertical space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Boxes</menunode><menudescription><pre xml:space="preserve">Making boxes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Color</menunode><menudescription><pre xml:space="preserve">Defining and using colors. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Graphics</menunode><menudescription><pre xml:space="preserve">Importing graphics from outside &latex;. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Special insertions</menunode><menudescription><pre xml:space="preserve">Inserting reserved and special characters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Splitting the input</menunode><menudescription><pre xml:space="preserve">Dealing with big files by splitting. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Front/back matter</menunode><menudescription><pre xml:space="preserve">Tables of contents, glossaries, indexes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Letters</menunode><menudescription><pre xml:space="preserve">The <code>letter</code> class. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Terminal input/output</menunode><menudescription><pre xml:space="preserve">User interaction. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Command line</menunode><menudescription><pre xml:space="preserve">System-independent command-line behavior. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Document templates</menunode><menudescription><pre xml:space="preserve">Starter templates for various document classes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Index</menunode><menudescription><pre xml:space="preserve">General index. +</pre></menudescription></menuentry></menu> + + +</top> +<node name="About-this-document" spaces=" "><nodename>About this document</nodename><nodenext automatic="on">Overview</nodenext><nodeprev automatic="on">Top</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>About this document</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="1">home page for manual</indexterm></cindex> +<para>This is an unofficial reference manual for the &latex;2e document +preparation system, which is a macro package for the &tex; +typesetting program (<pxref label="Overview"><xrefnodename>Overview</xrefnodename></pxref>). +</para> +<para>This document&textrsquo;s home page is <url><urefurl>https://puszcza.gnu.org.ua/software/latexrefman</urefurl></url>. There +you can get the sources, subscribe to the mailing list or read its +archives, see other infrastructure, and get the current output in +various formats. In particular, the output comes in two web formats. +Probably the most convenient one, shown at <url><urefurl>http://latexref.xyz/</urefurl></url>, +has pages for each topic and so is good for a quick lookup; see also the +note there about easy-to-remember links. The other, shown at +<url><urefurl>http://svn.gnu.org.ua/viewvc/latexrefman/trunk/latex2e.html?view=co</urefurl></url>, +has all the information on single page. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="2">&latex; vs.&noeos; &latex;2e</indexterm></cindex> +<para>In this document, we will mostly just use &textlsquo;&latex;&textrsquo; rather than +&textlsquo;&latex;2e&textrsquo;, since the previous version of &latex; (2.09) was +frozen decades ago. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="3">unofficial nature of this manual</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="4">&latex; Project team</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1" mergedindex="cp"><email><emailaddress>latexrefman&arobase;tug.org</emailaddress></email> <r>email address</r></indexterm></findex> +<para>&latex; is currently maintained by a group of volunteers +(<url><urefurl>http://latex-project.org</urefurl></url>). 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. +<cindex index="cp" spaces=" "><indexterm index="cp" number="5">bug reporting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="6">reporting bugs</indexterm></cindex> +Do not send bug reports or anything else about this document to them. +Instead, please send all comments to <email><emailaddress>latexrefman&arobase;tug.org</emailaddress></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> +<table commandarg="url" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="url">http://ctan.org/pkg/latex-doc-ptr</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="2" mergedindex="cp">latex-doc-ptr <r>document</r></indexterm></findex> +<para>Two pages of recommended references to &latex; documentation. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="url">http://ctan.org/pkg/first-latex-doc</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="3" mergedindex="cp">first-latex-doc <r>document</r></indexterm></findex> +<para>Writing your first document, with a bit of both text and math. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="url">http://ctan.org/pkg/usrguide</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="4" mergedindex="cp">usrguide <r>official documentation</r></indexterm></findex> +<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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="url">http://ctan.org/pkg/lshort</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="5" mergedindex="cp">lshort <r>document</r></indexterm></findex> +<para>A short introduction to &latex;, translated to many languages. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="url">http://tug.org/begin.html</itemformat></item> +</tableterm><tableitem><para>Introduction to the &tex; system, including &latex;, with further +references. +</para> +</tableitem></tableentry></table> + + +</chapter> +<node name="Overview" spaces=" "><nodename>Overview</nodename><nodenext automatic="on">Document classes</nodenext><nodeprev automatic="on">About this document</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Overview of &latex;</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="7">overview of &latex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="8">basics of &latex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="9">Knuth, Donald E.</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="10">Lamport, Leslie</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="11">&latex; overview</indexterm></cindex> + +<para>&latex; is a system for typesetting documents. It was originally +created by Leslie Lamport and is now maintained by a group of volunteers +(<url><urefurl>http://latex-project.org</urefurl></url>). It is widely used, particularly for +complex and technical documents, such as those involving mathematics. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="12">macro package, &latex; as</indexterm></cindex> +<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&textrsquo;s &tex; typesetting program +(the technical term is that &latex; is a <dfn>macro package</dfn> 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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="13">Lamport &tex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="14">pronunciation</indexterm></cindex> +<para>The name &latex; is short for &textldquo;Lamport &tex;&textrdquo;. It is pronounced +LAH-teck or LAY-teck, or sometimes LAY-tecks. Inside a document, +produce the logo with <code>\LaTeX</code>. Where use of the logo is not +sensible, such as in plain text, write it as <samp>LaTeX</samp>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Starting and ending</menunode><menudescription><pre xml:space="preserve">The standard beginning and end of a document. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Output files</menunode><menudescription><pre xml:space="preserve">Files produced. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">&tex; engines</menunode><menudescription><pre xml:space="preserve">Programs that can compile &tex; and &latex;. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">&latex; command syntax</menunode><menudescription><pre xml:space="preserve">General syntax of &latex; commands. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Environment</menunode><menudescription><pre xml:space="preserve">Area of the source giving distinct behavior. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">CTAN</menunode><menudescription><pre xml:space="preserve">Our repository. +</pre></menudescription></menuentry></menu> + + +<node name="Starting-and-ending" spaces=" "><nodename>Starting and ending</nodename><nodenext automatic="on">Output files</nodenext><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>Starting and ending</sectiontitle> + +<anchor name="Starting-_0026-ending">Starting & ending</anchor><!-- c old name --> +<cindex index="cp" spaces=" "><indexterm index="cp" number="15">starting and ending</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="16">ending and starting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="17">hello, world</indexterm></cindex> + +<para>&latex; files have a simple global structure, with a standard beginning +and ending. This is a small example. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{article} +\begin{document} +Hello, \LaTeX\ world. +\end{document} +</pre></example> + +<noindent></noindent> +<para>Every &latex; document has a <code>\begin{document}</code> line and an +<code>\end{document}</code> line. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="18">document class, defined</indexterm></cindex> +<noindent></noindent> +<para>Here, the <samp>article</samp> is the <dfn>document class</dfn>. It is implemented +in a file <file>article.cls</file>. 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. <xref label="Document-classes"><xrefnodename>Document classes</xrefnodename></xref>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="19">preamble, defined</indexterm></cindex> +<para>You can include other &latex; commands between the +<code>\documentclass</code> and the <code>\begin{document}</code> commands. +This area is called the <dfn>preamble</dfn>. +</para> +<para>The <code>\begin{document}</code>, <code>\end{document}</code> pair defines an +<cindex index="cp" spaces=" "><indexterm index="cp" number="20">environment</indexterm></cindex> +<dfn>environment</dfn>; the <samp>document</samp> environment (and no others) is +required in all &latex; documents (<pxref label="document"><xrefnodename>document</xrefnodename></pxref>). &latex; make +available to you many environments that are documented here +(<pxref label="Environments"><xrefnodename>Environments</xrefnodename></pxref>). Many more are available to you from external +packages, most importantly those available at CTAN (<pxref label="CTAN"><xrefnodename>CTAN</xrefnodename></pxref>). +</para> +<para>The following sections discuss how to produce PDF or other output from +a &latex; input file. +</para> + +</section> +<node name="Output-files" spaces=" "><nodename>Output files</nodename><nodenext automatic="on">&tex; engines</nodenext><nodeprev automatic="on">Starting and ending</nodeprev><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>Output files</sectiontitle> + +<para>&latex; produces a main output file and at least two auxiliary files. +The main output file&textrsquo;s name ends in either <file>.dvi</file> or <file>.pdf</file>. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">.dvi</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="6" mergedindex="cp">.dvi <r>file</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="7" mergedindex="cp">latex <r>command</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="8" mergedindex="cp">xdvi <r>command</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="9" mergedindex="cp">dvips <r>command</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="10" mergedindex="cp">dvipdfmx <r>command</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="11" mergedindex="cp">dvitype <r>command</r></indexterm></findex> +<anchor name="output-files-dvi">output files dvi</anchor> +<para>If &latex; is invoked with the system command <command>latex</command> then it +produces a DeVice Independent file, with extension <file>.dvi</file>. You +can view this file with a command such as <command>xdvi</command>, or convert +it to a PostScript <code>.ps</code> file with <command>dvips</command> or to a +Portable Document Format <code>.pdf</code> 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 (<url><urefurl>http://mirror.ctan.org/dviware</urefurl></url>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">.pdf</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="12" mergedindex="cp">.pdf <r>file</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="21">pdf&tex;</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="13" mergedindex="cp">pdflatex <r>command</r></indexterm></findex> +<anchor name="output-files-pdf">output files pdf</anchor> +<para>If &latex; is invoked via the system command <command>pdflatex</command>, +among other commands (<pxref label="TeX-engines"><xrefnodename>&tex; engines</xrefnodename></pxref>), 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> +</tableitem></tableentry></table> + +<para>&latex; also produces at least two additional files. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">.log</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="22">transcript file</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="23">log file</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="14" mergedindex="cp">.log <r>file</r></indexterm></findex> +<anchor name="output-files-log">output files log</anchor> +<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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">.aux</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="24">auxiliary file</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="15" mergedindex="cp">.aux <r>file</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="25">cross references, resolving</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="26">forward references, resolving</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="27">references, resolving forward</indexterm></cindex> +<anchor name="output-files-aux">output files aux</anchor> +<para>Auxiliary information is used by &latex; for things such as +cross references. For example, the first time that &latex; finds a +forward reference&textmdash;a cross reference to something that has not yet +appeared in the source&textmdash;it will appear in the output as a doubled +question mark <code>??</code>. When the referred-to spot does eventually +appear in the source then &latex; writes its location information to +this <code>.aux</code> 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> +</tableitem></tableentry></table> + +<findex index="fn" spaces=" "><indexterm index="fn" number="16" mergedindex="cp">.lof <r>file</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="28">list of figures file</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="17" mergedindex="cp">.lot <r>file</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="29">list of tables file</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="18" mergedindex="cp">.toc <r>file</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="30">table of contents file</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="31">contents file</indexterm></cindex> +<para>&latex; may produce yet more files, characterized by the filename +ending. These include a <code>.lof</code> file that is used to make a list of +figures, a <code>.lot</code> file used to make a list of tables, and a +<code>.toc</code> file used to make a table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of +contents etc.</xrefnodename></pxref>). A particular class may create others; the list is +open-ended. +</para> + +</section> +<node name="TeX-engines" spaces=" "><nodename>&tex; engines</nodename><nodenext automatic="on">&latex; command syntax</nodenext><nodeprev automatic="on">Output files</nodeprev><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>&tex; engines</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="32">engines, &tex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="33">implementations of &tex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="34">UTF-8</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="35">Unicode input, native</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="36">TrueType fonts</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="37">OpenType fonts</indexterm></cindex> + +<para>&latex; is defined to be a set of commands that are run by a &tex; +implementation (<pxref label="Overview"><xrefnodename>Overview</xrefnodename></pxref>). This section gives a terse +overview of the main programs (see also <ref label="Command-line"><xrefnodename>Command line</xrefnodename></ref>). +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">latex</itemformat></item> +<itemx spaces=" "><itemformat command="code">pdflatex</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="38">pdf&tex; engine</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="19" mergedindex="cp">etex <r>command</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="39">e-&tex;</indexterm></cindex> +<anchor name="tex-engines-latex">tex engines latex</anchor> +<para>In &tex; Live (<url><urefurl>http://tug.org/texlive</urefurl></url>), if &latex; is invoked +via either the system command <command>latex</command> or <command>pdflatex</command>, +then the pdf&tex; engine is run (<url><urefurl>http://ctan.org/pkg/pdftex</urefurl></url>). +When invoked as <command>latex</command>, the main output is a <file>.dvi</file> +file; as <command>pdflatex</command>, the main output is a <file>.pdf</file> file. +</para> +<para>pdf&tex; incorporates the e-&tex; extensions to Knuth&textrsquo;s original +program (<url><urefurl>http://ctan.org/pkg/etex</urefurl></url>), 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 +<file>.dvi</file>). +</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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">lualatex</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="20" mergedindex="cp">lualatex <r>command</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="40">Lua&tex;</indexterm></cindex> +<anchor name="tex-engines-lualatex">tex engines lualatex</anchor> +<para>If &latex; is invoked via the system command <command>lualatex</command>, the +Lua&tex; engine is run (<url><urefurl>http://ctan.org/pkg/luatex</urefurl></url>). This +program allows code written in the scripting language Lua +(<url><urefurl>http://luatex.org</urefurl></url>) to interact with &tex;&textrsquo;s typesetting. +Lua&tex; handles UTF-8 Unicode input natively, can handle OpenType +and TrueType fonts, and produces a <file>.pdf</file> file by default. +There is also <command>dvilualatex</command> to produce a <file>.dvi</file> file, +but this is rarely used. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">xelatex</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="21" mergedindex="cp">xelatex <r>command</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="41">Xe&tex;</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="22" mergedindex="cp">.xdv <r>file</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="23" mergedindex="cp">xdvipdfmx</indexterm></findex> +<anchor name="tex-engines-xelatex">tex engines xelatex</anchor> +<para>If &latex; is invoked with the system command <command>xelatex</command>, the +Xe&tex; engine is run (<url><urefurl>http://tug.org/xetex</urefurl></url>). 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 +<file>.pdf</file> file as output; it does not support DVI output. +</para> +<para>Internally, Xe&tex; creates an <code>.xdv</code> file, a variant of DVI, +and translates that to PDF using the (<code>x</code>)<code>dvipdfmx</code> +program, but this process is automatic. The <code>.xdv</code> file is only +useful for debugging. +</para> +</tableitem></tableentry></table> + +<para>Other variants of &latex; and &tex; exist, e.g., to provide +additional support for Japanese and other languages ([u]p&tex;, +<url><urefurl>http://ctan.org/pkg/ptex</urefurl></url>, <url><urefurl>http://ctan.org/pkg/uptex</urefurl></url>). +</para> + +</section> +<node name="LaTeX-command-syntax" spaces=" "><nodename>&latex; command syntax</nodename><nodenext automatic="on">Environment</nodenext><nodeprev automatic="on">&tex; engines</nodeprev><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>&latex; command syntax</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="42">command syntax</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="24" mergedindex="cp">\ <r>character starting commands</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="25" mergedindex="cp">[...] <r>for optional arguments</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="26" mergedindex="cp">{...} <r>for required arguments</r></indexterm></findex> +<para>In the &latex; input file, a command name starts with a backslash +character, <code>\</code>. 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 <code>\pagebreak</code> +differs from <code>\Pagebreak</code> (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, <code>{...}</code>. Optional arguments are +contained in square brackets, <code>[...]</code>. 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 (<code>]</code>) hide it inside curly braces, as +in <code>\item[closing bracket {]}]</code>. 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;&textrsquo;s commands are a <dfn>declaration</dfn>. Such a command +changes the value the meaning of some other command or parameter. For +instance, the <code>\mainmatter</code> declaration changes the typesetting of +page numbers from roman numerals to arabic (<pxref label="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter"><xrefnodename>\frontmatter & +\mainmatter & \backmatter</xrefnodename></pxref>). +</para> +<para>&latex; has the convention that some commands have a <code>*</code> form that +is related to the form without a <code>*</code>, such as <code>\chapter</code> and +<code>\chapter*</code>. The exact difference in behavior varies from command +to command. +</para> +<para>This manual describes all accepted options and <code>*</code>-forms for the +commands it covers (barring unintentional omissions, a.k.a.&noeos; bugs). +</para> + +</section> +<node name="Environment" spaces=" "><nodename>Environment</nodename><nodenext automatic="on">CTAN</nodenext><nodeprev automatic="on">&latex; command syntax</nodeprev><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>Environment</sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{<var>environment name</var>} + ... +\end{<var>environment name</var>} +</pre></example> + +<para>An area of &latex; source, inside of which there is a distinct +behavior. For instance, for poetry in &latex; put the lines between +<code>\begin{verse}</code> and <code>\end{verse}</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{verse} + There once was a man from Nantucket \\ + ... +\end{verse} +</pre></example> + +<para><xref label="Environments"><xrefnodename>Environments</xrefnodename></xref> for a list of environments. Particularly notable is +that every &latex; document must have a <code>document</code> environment, +a <code>\begin{document} ... \end{document}</code> pair. +</para> +<para>The <var>environment name</var> at the beginning must exactly match that at +the end. This includes the case where <var>environment name</var> ends in a +star (<code>*</code>); both the <code>\begin</code> and <code>\end</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}[t]{r|l} + ... rows of table ... +\end{tabular} +</pre></example> + + +</section> +<node name="CTAN" spaces=" "><nodename>CTAN</nodename><nodeprev automatic="on">Environment</nodeprev><nodeup automatic="on">Overview</nodeup></node> +<section spaces=" "><sectiontitle>CTAN: the Comprehensive &tex; Archive Network</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="43">CTAN</indexterm></cindex> + +<para>The Comprehensive &tex; Archive Network, CTAN, is the &tex; and +&latex; community&textrsquo;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 <url><urefurl>https://ctan.org</urefurl></url>. +</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&textrsquo;s +specifications. +</para> +<para>In addition to the massive holdings, the web site offers features such +as search by name or by functionality. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="44">DANTE e.V.</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="45">mirrors of CTAN</indexterm></cindex> +<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 <url><urefurl>https://ctan.org/mirrors</urefurl></url>. +</para> + +</section> +</chapter> +<node name="Document-classes" spaces=" "><nodename>Document classes</nodename><nodenext automatic="on">Fonts</nodenext><nodeprev automatic="on">Overview</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Document classes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="46">document classes</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="47">classes of documents</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="27" mergedindex="cp">\documentclass</indexterm></findex> + +<para>The document&textrsquo;s overall class is defined with this command, which is +normally the first command in a &latex; source file. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass[<var>options</var>]{<var>class</var>} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="28" mergedindex="cp">article <r>class</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="29" mergedindex="cp">report <r>class</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="30" mergedindex="cp">book <r>class</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="31" mergedindex="cp">letter <r>class</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="32" mergedindex="cp">slides <r>class</r></indexterm></findex> +<para>The following document <var>class</var> names are built into &latex;. +(Many other document classes are available as separate packages; +<pxref label="Overview"><xrefnodename>Overview</xrefnodename></pxref>.) +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">article</itemformat></item> +</tableterm><tableitem><anchor name="document-classes-article">document classes article</anchor> +<para>For a journal article, a presentation, and miscellaneous general use. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">book</itemformat></item> +</tableterm><tableitem><anchor name="document-classes-book">document classes book</anchor> +<para>Full-length books, including chapters and possibly including front +matter, such as a preface, and back matter, such as an appendix +(<pxref label="Front_002fback-matter"><xrefnodename>Front/back matter</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">letter</itemformat></item> +</tableterm><tableitem><anchor name="document-classes-letter">document classes letter</anchor> +<para>Mail, optionally including mailing labels +(<pxref label="Letters"><xrefnodename>Letters</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">report</itemformat></item> +</tableterm><tableitem><anchor name="document-classes-report">document classes report</anchor> +<para>For documents of length between an <code>article</code> and a <code>book</code>, +such as technical reports or theses, which may contain several chapters. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">slides</itemformat></item> +</tableterm><tableitem><anchor name="document-classes-slides">document classes slides</anchor> +<para>For slide presentations&textmdash;rarely used today. In its place the +<code>beamer</code> package is perhaps the most prevalent (<pxref label="beamer-template"><xrefnodename>beamer +template</xrefnodename></pxref>). +</para> +</tableitem></tableentry></table> + +<para>Standard <var>options</var> are described in the next section. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Document class options</menunode><menudescription><pre xml:space="preserve">Global options. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Additional packages</menunode><menudescription><pre xml:space="preserve">Bring in packages. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Class and package construction</menunode><menudescription><pre xml:space="preserve">Create new classes and packages. +</pre></menudescription></menuentry></menu> + + +<node name="Document-class-options" spaces=" "><nodename>Document class options</nodename><nodenext automatic="on">Additional packages</nodenext><nodeup automatic="on">Document classes</nodeup></node> +<section spaces=" "><sectiontitle>Document class options</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="48">document class options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="49">options, document class</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="50">class options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="51">global options</indexterm></cindex> + +<para>You can specify <dfn>global options</dfn> or <dfn>class options</dfn> to the +<code>\documentclass</code> command by enclosing them in square brackets. To +specify more than one <var>option</var>, separate them with a comma. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass[<var>option1</var>,<var>option2</var>,...]{<var>class</var>} +</pre></example> + +<para>Here is the list of the standard class options. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="33" mergedindex="cp">10pt <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="34" mergedindex="cp">11pt <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="35" mergedindex="cp">12pt <r>option</r></indexterm></findex> +<para>All of the standard classes except <code>slides</code> accept the following +options for selecting the typeface size (default is <code>10pt</code>): +</para> +<example endspaces=" "> +<pre xml:space="preserve">10pt 11pt 12pt +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="36" mergedindex="cp">a4paper <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="37" mergedindex="cp">a5paper <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="38" mergedindex="cp">b5paper <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="39" mergedindex="cp">executivepaper <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="40" mergedindex="cp">legalpaper <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="41" mergedindex="cp">letterpaper <r>option</r></indexterm></findex> +<para>All of the standard classes accept these options for selecting the paper +size (these show height by width): +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">a4paper </itemformat></item> +</tableterm><tableitem><para>210 by 297<dmn>mm</dmn> (about 8.25 by 11.75 inches) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">a5paper </itemformat></item> +</tableterm><tableitem><para>148 by 210<dmn>mm</dmn> (about 5.8 by 8.3 inches) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b5paper</itemformat></item> +</tableterm><tableitem><para>176 by 250<dmn>mm</dmn> (about 6.9 by 9.8 inches) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">executivepaper</itemformat></item> +</tableterm><tableitem><para>7.25 by 10.5 inches +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">legalpaper</itemformat></item> +</tableterm><tableitem><para>8.5 by 14 inches +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">letterpaper</itemformat></item> +</tableterm><tableitem><para>8.5 by 11 inches (the default) +</para></tableitem></tableentry></table> + +<findex index="fn" spaces=" "><indexterm index="fn" number="42" mergedindex="cp">\pdfpagewidth</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="43" mergedindex="cp">\pdfpageheight</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="52"><r>package</r>, <code>geometry</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="53"><code>geometry</code> <r>package</r></indexterm></cindex> + +<para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex; +(<pxref label="TeX-engines"><xrefnodename>&tex; engines</xrefnodename></pxref>), options other than <code>letterpaper</code> set +the print area but you must also set the physical paper size. One way +to do that is to put <code>\pdfpagewidth=\paperwidth</code> and +<code>\pdfpageheight=\paperheight</code> in your document&textrsquo;s preamble. +<cindex index="cp" spaces=" "><indexterm index="cp" number="54"><r>package</r>, <code>geometry</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="55"><code>geometry</code> <r>package</r></indexterm></cindex> +</para> +<para>The <code>geometry</code> package provides flexible ways of setting the print +area and physical page size. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="44" mergedindex="cp">draft <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="45" mergedindex="cp">final <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="46" mergedindex="cp">fleqn <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="47" mergedindex="cp">landscape <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="48" mergedindex="cp">leqno <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="49" mergedindex="cp">openbib <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="50" mergedindex="cp">titlepage <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="51" mergedindex="cp">notitlepage <r>option</r></indexterm></findex> +<para>Miscellaneous other options: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">draft</itemformat></item> +<itemx spaces=" "><itemformat command="code">final</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="56">black boxes, omitting</indexterm></cindex> +<para>Mark (<code>draft</code>) or do not mark (<code>final</code>) overfull boxes with a +black box in the margin; default is <code>final</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">fleqn</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="57">flush left equations</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="58">centered equations</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="59">equations, flush left vs.&noeos; centered</indexterm></cindex> +<para>Put displayed formulas flush left; default is centered. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">landscape</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="60">landscape orientation</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="61">portrait orientation</indexterm></cindex> +<para>Selects landscape format; default is portrait. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">leqno</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="62">left-hand equation numbers</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="63">right-hand equation numbers</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="64">equation numbers, left vs.&noeos; right</indexterm></cindex> +<para>Put equation numbers on the left side of equations; default is the right side. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">openbib</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="65">bibliography format, open</indexterm></cindex> +<para>Use &textldquo;open&textrdquo; bibliography format. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">titlepage</itemformat></item> +<itemx spaces=" "><itemformat command="code">notitlepage</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="66">title page, separate or run-in</indexterm></cindex> +<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 +<code>report</code> class is <code>titlepage</code>, for the other classes it is +<code>notitlepage</code>. +</para></tableitem></tableentry></table> + +<para>The following options are not available with the <code>slides</code> class. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="52" mergedindex="cp">onecolumn <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="53" mergedindex="cp">twocolumn <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="54" mergedindex="cp">oneside <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="55" mergedindex="cp">twoside <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="56" mergedindex="cp">openright <r>option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="57" mergedindex="cp">openany <r>option</r></indexterm></findex> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">onecolumn</itemformat></item> +<itemx spaces=" "><itemformat command="code">twocolumn</itemformat></itemx> +</tableterm><tableitem><para>Typeset in one or two columns; default is <code>onecolumn</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">oneside</itemformat></item> +<itemx spaces=" "><itemformat command="code">twoside</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="58" mergedindex="cp">\evensidemargin</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="59" mergedindex="cp">\oddsidemargin</indexterm></findex> +<para>Selects one- or two-sided layout; default is <code>oneside</code>, except +that in the <code>book</code> class the default is <code>twoside</code>. +</para> +<para>For one-sided printing, the text is centered on the page. For two-sided +printing, the <code>\evensidemargin</code> (<code>\oddsidemargin</code>) parameter +determines the distance on even (odd) numbered pages between the left +side of the page and the text&textrsquo;s left margin, with <code>\oddsidemargin</code> +being 40% of the difference between <code>\paperwidth</code> and +<code>\textwidth</code>, and <code>\evensidemargin</code> is the remainder. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">openright</itemformat></item> +<itemx spaces=" "><itemformat command="code">openany</itemformat></itemx> +</tableterm><tableitem><para>Determines if a chapter should start on a right-hand page; default is +<code>openright</code> for <code>book</code>, and <code>openany</code> for <code>report</code>. +</para></tableitem></tableentry></table> + +<findex index="fn" spaces=" "><indexterm index="fn" number="60" mergedindex="cp">clock <r>option to <code>slides</code> class</r></indexterm></findex> +<para>The <code>slides</code> class offers the option <code>clock</code> for printing +the time at the bottom of each note. +</para> + +</section> +<node name="Additional-packages" spaces=" "><nodename>Additional packages</nodename><nodenext automatic="on">Class and package construction</nodenext><nodeprev automatic="on">Document class options</nodeprev><nodeup automatic="on">Document classes</nodeup></node> +<section spaces=" "><sectiontitle>Additional packages</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="67">loading additional packages</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="68">packages, loading additional</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="69">additional packages, loading</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="61" mergedindex="cp">\usepackage</indexterm></findex> +<para>Load a package <var>pkg</var>, with the package options given in the comma-separated +list <var>options</var>, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage[<var>options</var>]{<var>pkg</var>}. +</pre></example> + +<para>To specify more than one package you can separate them with a comma, +as in <code>\usepackage{<var>pkg1</var>,<var>pkg2</var>,...}</code>, or use multiple +<code>\usepackage</code> commands. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="70">global options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="71">options, global</indexterm></cindex> +<para>Any options given in the <code>\documentclass</code> command that are unknown +to the selected document class are passed on to the packages loaded with +<code>\usepackage</code>. +</para> + +</section> +<node name="Class-and-package-construction" spaces=" "><nodename>Class and package construction</nodename><nodeprev automatic="on">Additional packages</nodeprev><nodeup automatic="on">Document classes</nodeup></node> +<section spaces=" "><sectiontitle>Class and package construction</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="72">document class commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="73">commands, document class</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="74">new class commands</indexterm></cindex> + +<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 +<code>smcmemo.cls</code> and begin your documents with +<code>\documentclass{smcmemo}</code>. +</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 <code>Memo from the +SMC Math Department</code> is for a class. +<cindex index="cp" spaces=" "><indexterm index="cp" number="75">class and package difference</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="76">difference between class and package</indexterm></cindex> +</para> +<para>Inside of a class or package file you can use the at-sign <code>&arobase;</code> as a +character in command names without having to surround the code +containing that command with <code>\makeatletter</code> and +<code>\makeatother</code>. <xref label="_005cmakeatletter-_0026-_005cmakeatother"><xrefnodename>\makeatletter & \makeatother</xrefnodename></xref>. 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 <code>smcmemo</code> might have commands +<code>\smc&arobase;tolist</code>, <code>\smc&arobase;fromlist</code>, etc. +</para> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Class and package structure</menunode><menudescription><pre xml:space="preserve">Layout of the file. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Class and package commands</menunode><menudescription><pre xml:space="preserve">List of commands. +</pre></menudescription></menuentry></menu> + + +<node name="Class-and-package-structure" spaces=" "><nodename>Class and package structure</nodename><nodenext automatic="on">Class and package commands</nodenext><nodeup automatic="on">Class and package construction</nodeup></node> +<subsection spaces=" "><sectiontitle>Class and package structure</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="77">class and package structure</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="78">class file layout</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="79">package file layout</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="80">options, document class</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="81">options, package</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="82">class options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="83">package options</indexterm></cindex> + +<para>A class file or package file typically has four parts. +</para><enumerate first="1" endspaces=" "> +<listitem> +<para>In the <dfn>identification part</dfn>, the file says that it is a &latex; +package or class and describes itself, using the <code>\NeedsTeXFormat</code> +and <code>\ProvidesClass</code> or <code>\ProvidesPackage</code> commands. +</para> +</listitem><listitem> +<para>The <dfn>preliminary declarations part</dfn> 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 <code>smcmemo</code> +class might be called with an option to read in a file with a list of +people for the to-head, as <code>\documentclass[mathto]{smcmemo}</code>, and +therefore needs to define a command +<code>\newcommand{\setto}[1]{\def\&arobase;tolist{#1}}</code> used in that +file. +</para> +</listitem><listitem> +<para>In the <dfn>handle options part</dfn> the class or package declares +and processes its options. Class options allow a user to start their +document as <code>\documentclass[<var>option list</var>]{<var>class +name</var>}</code>, to modify the behavior of the class. An example is when you +declare <code>\documentclass[11pt]{article}</code> to set the default +document font size. +</para> +</listitem><listitem> +<para>Finally, in the <dfn>more declarations part</dfn> the class or package usually does +most of its work: declaring new variables, commands and fonts, and +loading other files. +</para></listitem></enumerate> + +<para>Here is a starting class file, which should be saved as <file>stub.cls</file> +where &latex; can find it, for example in the same directory as the +<file>.tex</file> file. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{stub}[2017/07/06 stub to start building classes from] +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions\relax +\LoadClass{article} +</pre></example> +<cindex index="cp" spaces=" "><indexterm index="cp" number="84">class file example</indexterm></cindex> + +<noindent></noindent> +<para>It identifies itself, handles the class options via the default of +passing them all to the <code>article</code> class, and then loads the +<code>article</code> class to provide the basis for this class&textrsquo;s code. +</para> +<para>For more, see the official guide for class and package writers, the +Class Guide, at +<url><urefurl>http://www.latex-project.org/help/documentation/clsguide.pdf</urefurl></url> (much +of the descriptions here derive from this document), or the tutorial +<url><urefurl>https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf</urefurl></url>. +</para> + +</subsection> +<node name="Class-and-package-commands" spaces=" "><nodename>Class and package commands</nodename><nodeprev automatic="on">Class and package structure</nodeprev><nodeup automatic="on">Class and package construction</nodeup></node> +<subsection spaces=" "><sectiontitle>Class and package commands</sectiontitle> +<cindex index="cp" spaces=" "><indexterm index="cp" number="85">class and package commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="86">commands, class and package</indexterm></cindex> + +<para>These are the commands designed to help writers of classes or packages. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\AtBeginDvi{specials}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="62" mergedindex="cp">\AtBeginDvi</indexterm></findex> +<para>Save in a box register things that are written to the <file>.dvi</file> file +at the beginning of the shipout of the first page of the document. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\AtEndOfClass{<var>code</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\AtEndOfPackage{<var>code</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="63" mergedindex="cp">\AtEndOfClass</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="64" mergedindex="cp">\AtEndOfPackage</indexterm></findex> +<para>Hook to insert <var>code</var> to be executed when &latex; finishes +processing the current class or package. You can use these hooks +multiple times; the <code>code</code> will be executed in the order that you +called it. See also <ref label="_005cAtBeginDocument"><xrefnodename>\AtBeginDocument</xrefnodename></ref>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\CheckCommand{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\CheckCommand*{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="65" mergedindex="cp">\CheckCommand</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="66" mergedindex="cp">\CheckCommand*</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="87">new command, check</indexterm></cindex> +<para>Like <code>\newcommand</code> (<pxref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & \renewcommand</xrefnodename></pxref>) but does +not define <var>cmd</var>; instead it checks that the current definition of +<var>cmd</var> is exactly as given by <var>definition</var> and is or is not +<cindex index="cp" spaces=" "><indexterm index="cp" number="88">long command</indexterm></cindex> +<dfn>long</dfn> as expected. A long command is a command that accepts +<code>\par</code> within an argument. The <var>cmd</var> command is expected to be +long with the unstarred version of <code>\CheckCommand</code>. Raises an +error when the check fails. This allows you to check before you start +redefining <code>cmd</code> yourself that no other package has already +redefined this command. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ClassError{<var>class name</var>}{<var>error text</var>}{<var>help text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PackageError{<var>package name</var>}{<var>error text</var>}{<var>help text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ClassWarning{<var>class name</var>}{<var>warning text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PackageWarning{<var>package name</var>}{<var>warning text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ClassWarningNoLine{<var>class name</var>}{<var>warning text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PackageWarningNoLine{<var>package name</var>}{<var>warning text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ClassInfo{<var>class name</var>}{<var>info text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PackageInfo{<var>package name</var>}{<var>info text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ClassInfoNoLine{<var>class name</var>}{<var>info text</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PackageInfoNoLine{<var>package name</var>}{<var>info text</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="67" mergedindex="cp">\ClassError</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="68" mergedindex="cp">\PackageError</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="69" mergedindex="cp">\ClassWarning</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="70" mergedindex="cp">\PackageWarning</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="71" mergedindex="cp">\ClassWarningNoLine</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="72" mergedindex="cp">\PackageWarningNoLine</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="73" mergedindex="cp">\ClassInfo</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="74" mergedindex="cp">\PackageInfo</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="75" mergedindex="cp">\ClassInfoNoLine</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="76" mergedindex="cp">\PackageInfoNoLine</indexterm></findex> +<para>Produce an error message, or warning or informational messages. +</para> +<para>For <code>\ClassError</code> and <code>\PackageError</code> the message is +<var>error text</var>, followed by &tex;&textrsquo;s <code>?</code> error prompt. If the +user then asks for help by typing <code>h</code>, they see the <var>help +text</var>. +</para> +<para>The four warning commands are similar except that they write +<var>warning text</var> on the screen with no error prompt. The four info +commands write <var>info text</var> only in the transcript file. The +<code>NoLine</code> 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 <var>help text</var>: use +<code>\protect</code> to stop a command from expanding, get a line break with +<code>\MessageBreak</code>, and get a space with <code>\space</code> when a space +character does not allow it, like after a command. Note that &latex; +appends a period to the messages. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\CurrentOption</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="77" mergedindex="cp">\CurrentOption</indexterm></findex> +<para>Expands to the name of the currently-being-processed option. Can only +be used within the <var>code</var> argument of either <code>\DeclareOption</code> +or <code>\DeclareOption*</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\DeclareOption{<var>option</var>}{<var>code</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\DeclareOption*{<var>code</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="78" mergedindex="cp">\DeclareOption</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="79" mergedindex="cp">\DeclareOption*</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="89">class options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="90">package options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="91">options, class</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="92">options, package</indexterm></cindex> +<para>Make an option available to a user to invoke in their +<code>\documentclass</code> command. For example, the <code>smcmemo</code> class +could have an option <code>\documentclass[logo]{smcmemo}</code> allowing +users to put the institutional logo on the first page. The class file +must contain <code>\DeclareOption{logo}{<var>code</var>}</code> (and later, +<code>\ProcessOptions</code>). +</para> +<para>If you request an option that has not been declared, by default this +will produce a warning like <code>Unused global option(s): [badoption].</code> +Change this behaviour with the starred version +<code>\DeclareOption*{<var>code</var>}</code>. For example, many classes extend +an existing class, using a declaration such as +<code>\LoadClass{article}</code>, and for passing extra options to the +underlying class use code such as this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareOption*{% +\PassOptionsToClass{\CurrentOption}{article}% +} +</pre></example> + +<para>Another example is that the class <code>smcmemo</code> may allow users to keep +lists of memo recipients in external files. Then the user could invoke +<code>\documentclass[math]{smcmemo}</code> and it will read the file +<code>math.memo</code>. This code handles the file if it exists and otherwise +passes the option to the <code>article</code> class. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{% + \PassOptionsToClass{\CurrentOption}{article}}} +</pre></example> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\DeclareRobustCommand{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>} </itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\DeclareRobustCommand*{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="80" mergedindex="cp">\DeclareRobustCommand</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="81" mergedindex="cp">\DeclareRobustCommand*</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="93">new command, definition</indexterm></cindex> +<para>Like <code>\newcommand</code> and <code>\newcommand*</code> (<pxref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & +\renewcommand</xrefnodename></pxref>) but these declare a robust command, even if some code +within the <var>definition</var> is fragile. (For a discussion of robust and +fragile commands <pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>.) Use this command to define new +robust commands or to redefine existing commands and make them +robust. Unlike <code>\newcommand</code> these do not give an error if macro +<var>cmd</var> 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 <code>\newcommand</code> so unless the command&textrsquo;s data is fragile and the +command is used within a moving argument, use <code>\newcommand</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="94"><r>package</r>, <code>etoolbox</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="95"><code>etoolbox</code> <r>package</r></indexterm></cindex> + <para>The <file>etoolbox</file> package offers the commands +<code>\newrobustcmd</code>, <code>\newrobustcmd*</code>, as well as the commands +<code>\renewrobustcmd</code>, <code>\renewrobustcmd*</code>, and the commands +<code>\providerobustcmd</code>, and <code>\providerobustcmd*</code>. These are +similar to <code>\newcommand</code>, <code>\newcommand*</code>, +<code>\renewcommand</code>, <code>\renewcommand*</code>, <code>\providecommand</code>, and +<code>\providecommand*</code>, but define a robust <var>cmd</var> with two +advantages as compared to <code>\DeclareRobustCommand</code>: +</para><enumerate first="1" endspaces=" "> +<listitem> +<para>They use the low-level e-&tex; protection mechanism rather than the +higher level &latex; <code>\protect</code> mechanism, so they do not incur +the slight loss of performance mentioned above, and +</para></listitem><listitem> +<para>They make the same distinction between <code>\new&dots;</code>, +<code>\renew&dots;</code>, and <code>\provide&dots;</code>, as the standard +commands, so they do not just make a log message when you redefine +<var>cmd</var> that already exists, in that case you need to use either +<code>\renew&dots;</code> or <code>\provide&dots;</code> or you get an error. +</para></listitem></enumerate> + + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\IfFileExists{<var>file name</var>}{<var>true code</var>}{<var>false code</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\InputIfFileExists{<var>file name</var>}{<var>true code</var>}{<var>false code</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="82" mergedindex="cp">\IfFileExists</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="83" mergedindex="cp">\InputIfFileExists</indexterm></findex> +<para>Execute <var>true code</var> if &latex; finds the file <file><var>file +name</var></file> or <var>false code</var> otherwise. In the first case it executing +<var>true code</var> and then inputs the file. Thus the command +</para> +<example endspaces=" "> +<pre xml:space="preserve">\IfFileExists{img.pdf}{% + \includegraphics{img.pdf}}{\typeout{!! img.pdf not found} +</pre></example> + +<noindent></noindent> +<para>will include the graphic <file>img.pdf</file> 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 <code>\IfFileExists{./filename}{<var>true +code</var>}{<var>false code</var>}</code>. If you ask for a filename without a +<code>.tex</code> extension then &latex; will first look for the file by +appending the <code>.tex</code>; for more on how &latex; handles file +extensions see <ref label="_005cinput"><xrefnodename>\input</xrefnodename></ref>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\LoadClass[<var>options list</var>]{<var>class name</var>}[<var>release date</var>]</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\LoadClassWithOptions{<var>class name</var>}[<var>release date</var>]</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="84" mergedindex="cp">\LoadClass</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="85" mergedindex="cp">\LoadClassWithOptions</indexterm></findex> +<para>Load a class, as with <code>\documentclass[<var>options +list</var>]{<var>class name</var>}[<var>release info</var>]</code>. An example is +<code>\LoadClass[twoside]{article}</code>. +</para> +<para>The <var>options list</var>, if present, is a comma-separated list. The +<var>release date</var> is optional. If present it must have the form +<var>YYYY/MM/DD</var>. +<!-- c BTW, there are at-macros documented in macros2e.pdf to check the version --> +<!-- c and do some actions conditionnally on version later or not to some --> +<!-- c date. --> +</para> +<para>If you request a <var>release date</var> 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> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<para>The command version <code>\LoadClassWithOptions</code> uses the list of +options for the current class. This means it ignores any options passed +to it via <code>\PassOptionsToClass</code>. This is a convenience command +that lets you build classes on existing ones, such as the standard +<code>article</code> class, without having to track which options were passed. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ExecuteOptions{<var>options-list</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="86" mergedindex="cp">\ExecuteOptions</indexterm></findex> +<para>For each option <var>option</var> in the <var>options-list</var>, in order, this command +executes the command <code>\ds&arobase;<var>option</var></code>. 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 +<code>\ProcessOptions</code>. For example, if in a class file you want the +default to be 11pt fonts then you could specify +<code>\ExecuteOptions{11pt}\ProcessOptions\relax</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\NeedsTeXFormat{<var>format</var>}[<var>format date</var>]</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="87" mergedindex="cp">\NeedsTeXFormat</indexterm></findex> +<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: +<code>\NeedsTeXFormat{LaTeX2e}</code>. 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 <var>format</var> string is case +sensitive). If it does not match then execution stops with an error +like <samp>This file needs format `LaTeX2e' but this is `xxx'.</samp> +</para> +<para>To specify a version of the format that you know to have certain +features, include the optional <var>format date</var> on which those features +were implemented. If present it must be in the form <code>YYYY/MM/DD</code>. +If the format version installed on your system is earlier than +<var>format date</var> then you get a warning like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">You have requested release `2038/01/20' of LaTeX, but only +release `2016/02/01' is available. +</pre></example> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\OptionNotUsed</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="88" mergedindex="cp">\OptionNotUsed</indexterm></findex> +<para>Adds the current option to the list of unused options. Can only be used +within the <var>code</var> argument of either <code>\DeclareOption</code> or +<code>\DeclareOption*</code>. +</para> +<!-- c I cannot reproduce this behavior as it is documented in clsguide. --> +<!-- c In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues --> +<!-- c on the console a warning like @code{LaTeX Warning: Unused global --> +<!-- c option(s): [unusedoption].} with the list of not-used options when it --> +<!-- c reaches @code{\begin@{document@}}. --> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PassOptionsToClass{<var>option list</var>}{<var>class name</var>}</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\PassOptionsToPackage{<var>option list</var>}{<var>package name</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="89" mergedindex="cp">\PassOptionsToClass</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="90" mergedindex="cp">\PassOptionsToPackage</indexterm></findex> +<para>Adds the options in the comma-separated list <var>option list</var> to the +options used by any future <code>\RequirePackage</code> or <code>\usepackage</code> +command for package <var>package name</var> or the class <var>class name</var>. +</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 <code>Option clash for package +foo.</code> (&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 +<code>\RequirePackage[landscape]{geometry}</code> and +<code>\RequirePackage[margins=1in]{geometry}</code> with the single command +<code>\RequirePackage[landscape,margins=1in]{geometry}</code>. +</para> +<para>However, imagine that you are loading <file>firstpkg</file> and inside that +package it loads <file>secondpkg</file>, and you need the second package to be +loaded with option <code>draft</code>. Then before doing the first package +you must queue up the options for the second package, like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\PassOptionsToPackage{draft}{secondpkg} +\RequirePackage{firstpkg} +</pre></example> + +<noindent></noindent> +<para>(If <code>firstpkg.sty</code> 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 <code>graphicx</code> +package with the option <code>draft</code> and also wants to use a class +<code>foo</code> that loads the <code>graphicx</code> package, but without that +option. The user could start their &latex; file with +<code>\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProcessOptions</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProcessOptions*<var>\&arobase;options</var></itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="91" mergedindex="cp">\ProcessOptions</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="92" mergedindex="cp">\ProcessOptions*</indexterm></findex> +<para>Execute the code for each option that the user has invoked. Include it +in the class file as <code>\ProcessOptions\relax</code> (because of the +existence of the starred command). +</para> +<para>Options come in two types. <dfn>Local options</dfn> have been specified for this +particular package in the <var>options</var> argument of +<code>\PassOptionsToPackage{<var>options</var>}</code>, +<code>\usepackage[<var>options</var>]</code>, or +<code>\RequirePackage[<var>options</var>]</code>. <dfn>Global options</dfn> are those given +by the class user in <code>\documentclass[<var>options</var>]</code> (If an option +is specified both locally and globally then it is local.) +</para> +<para>When <code>\ProcessOptions</code> is called for a package <file>pkg.sty</file>, the +following happens: +</para><enumerate first="1" endspaces=" "> +<listitem> +<para>For each option <var>option</var> so far declared +with <code>\DeclareOption</code>, it looks to see if that option is either a +global or a local option for <code>pkg</code>. If so then it executes the +declared code. This is done in the order in which these options were +given in <file>pkg.sty</file>. +</para></listitem><listitem> +<para>For each remaining local option, it executes the command +<code>\ds&arobase;</code><var>option</var> if it has been defined somewhere (other than by +a <code>\DeclareOption</code>); otherwise, it executes the default option code +given in <code>\DeclareOption*</code>. 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></enumerate> + +<para>When <code>\ProcessOptions</code> is called for a class it works in the same +way except that all options are local, and the default <var>code</var> for +<code>\DeclareOption*</code> is <code>\OptionNotUsed</code> rather than an error. +</para> +<para>The starred version <code>\ProcessOptions*</code> 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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProvidesClass{<var>class name</var>}[<var>release date</var> <var>brief additional information</var>]</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProvidesClass{<var>class name</var>}[<var>release date</var>]</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProvidesPackage{<var>package name</var>}[<var>release date</var> <var>brief additional information</var>]</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProvidesPackage{<var>package name</var>}[<var>release date</var>]</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="93" mergedindex="cp">\ProvidesClass</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="94" mergedindex="cp">\ProvidesPackage</indexterm></findex> +<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 +<code>\documentclass{smcmemo}</code> or <code>\usepackage{test}</code>, &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 +<code>\documentclass{smcmemo}</code>, and the file <file>smcmemo.cls</file> has +the statement <code>\ProvidesClass{xxx}</code> then you get a warning like +<code>You have requested document class `smcmemo', but the document +class provides 'xxx'.</code> 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 <code>YYYY/MM/DD</code>. 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 <file>smcmemo.cls</file> contains the line +<code>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</code> and +your document&textrsquo;s first line is <code>\documentclass{smcmemo}</code> then you +will see <code>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</code>. +</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 +<var>release date</var>. For instance, a user could enter +<code>\documentclass{smcmemo}[2018/10/12]</code> or +<code>\usepackage{foo}[[2017/07/07]]</code> 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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ProvidesFile{<var>file name</var>}[<var>additional information</var>]</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="95" mergedindex="cp">\ProvidesFile</indexterm></findex> +<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 <code>File: test.config +2017/10/12 config file for test.cls</code> for <var>file name</var> equal to +<samp>test.config</samp> and <var>additional information</var> equal to +<samp>2017/10/12 config file for test.cls</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\RequirePackage[<var>option list</var>]{<var>package name</var>}[<var>release date</var>]</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\RequirePackageWithOptions{<var>package name</var>}[<var>release date</var>]</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="96" mergedindex="cp">\RequirePackage</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="97" mergedindex="cp">\RequirePackageWithOptions</indexterm></findex> +<para>Load a package, like the command <code>\usepackage</code> (<pxref label="Additional-packages"><xrefnodename>Additional +packages</xrefnodename></pxref>). The &latex; development team strongly recommends use of +these commands over Plain &tex;&textrsquo;s <code>\input</code>; see the Class +Guide. An example is +<code>\RequirePackage[landscape,margin=1in]{geometry}</code>. +</para> +<para>The <var>option list</var>, if present, is a comma-separated list. The +<var>release date</var>, if present, must have the form <var>YYYY/MM/DD</var>. If +the release date of the package as installed on your system is earlier +than <var>release date</var> then you get a warning like <code>You have +requested, on input line 9, version `2017/07/03' of package jhtest, but +only version `2000/01/01' is available</code>. +</para> +<para>The <code>\RequirePackageWithOptions</code> version uses the list of options +for the current class. This means it ignores any options passed to it +via <code>\PassOptionsToClass</code>. 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 <code>\usepackage</code> and <code>\RequirePackage</code> is +small. The <code>\usepackage</code> command is intended for the document file +while <code>\RequirePackage</code> is intended for package and class files. +Thus, using <code>\usepackage</code> before the <code>\documentclass</code> command +causes &latex; to give error like <code>\usepackage before +\documentclass</code>, but you can use <code>\RequirePackage</code> there. +</para></tableitem></tableentry></table> + + +</subsection> +</section> +</chapter> +<node name="Fonts" spaces=" "><nodename>Fonts</nodename><nodenext automatic="on">Layout</nodenext><nodeprev automatic="on">Document classes</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Fonts</sectiontitle> +<anchor name="Typefaces">Typefaces</anchor><!-- c old name --> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="96">typefaces</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="97">fonts</indexterm></cindex> + +<para>Two important aspects of selecting a <dfn>font</dfn> are specifying a size +and a style. The &latex; commands for doing this are described here. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Font styles</menunode><menudescription><pre xml:space="preserve">Select roman, italics, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Font sizes</menunode><menudescription><pre xml:space="preserve">Select point size. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Low-level font commands</menunode><menudescription><pre xml:space="preserve">Select encoding, family, series, shape. +</pre></menudescription></menuentry></menu> + + +<node name="Font-styles" spaces=" "><nodename>Font styles</nodename><nodenext automatic="on">Font sizes</nodenext><nodeup automatic="on">Fonts</nodeup></node> +<section spaces=" "><sectiontitle>Font styles</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="98">font styles</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="99">type styles</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="100">styles of text</indexterm></cindex> + +<para>The following type style commands are supported by &latex;. +</para> +<para>In the table below the listed commands, the <code>\text...</code> commands, +is used with an argument, as in <code>\textit{<var>text</var>}</code>. This is +the preferred form. But shown after it, in parenthesis, is the +corresponding declaration form, which is sometimes useful. This form +takes no arguments, as in <code>{\itshape <var>text</var>}</code>. The scope of +the declaration form lasts until the next type style command or the end +of the current group. In addition, each has an environment form such as +<code>\begin{itshape}...\end{itshape}</code>. +</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 +<code>\sffamily\bfseries</code> or <code>\bfseries\sffamily</code>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="98" mergedindex="cp">\nocorrlist</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="99" mergedindex="cp">\nocorr</indexterm></findex> +<para>One advantage of these commands is that they automatically insert italic +corrections if needed (<pxref label="_005c_002f"><xrefnodename>\/</xrefnodename></pxref>). Specifically, they insert the +italic correction unless the following character is in the list +<code>\nocorrlist</code>, which by default consists of a period and a comma. +To suppress the automatic insertion of italic correction, use +<code>\nocorr</code> at the start or end of the command argument, such as +<code>\textit{\nocorr text}</code> or <code>\textsc{text \nocorr}</code>. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\textrm (\rmfamily)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="100" mergedindex="cp">\textrm</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="101" mergedindex="cp">\rmfamily</indexterm></findex> +<para>Roman. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textit (\itshape)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="102" mergedindex="cp">\textit</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="103" mergedindex="cp">\itshape</indexterm></findex> +<para>Italics. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textmd (\mdseries)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="104" mergedindex="cp">\textmd</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="105" mergedindex="cp">\mdseries</indexterm></findex> +<para>Medium weight (default). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textbf (\bfseries)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="106" mergedindex="cp">\textbf</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="107" mergedindex="cp">\bfseries</indexterm></findex> +<para>Boldface. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textup (\upshape)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="108" mergedindex="cp">\textup</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="109" mergedindex="cp">\upshape</indexterm></findex> +<para>Upright (default). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textsl (\slshape)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="110" mergedindex="cp">\textsl</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="111" mergedindex="cp">\slshape</indexterm></findex> +<para>Slanted. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textsf (\sffamily)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="112" mergedindex="cp">\textsf</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="113" mergedindex="cp">\sffamily</indexterm></findex> +<para>Sans serif. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textsc (\scshape)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="114" mergedindex="cp">\textsc</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="115" mergedindex="cp">\scshape</indexterm></findex> +<para>Small caps. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\texttt (\ttfamily)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="116" mergedindex="cp">\texttt</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="117" mergedindex="cp">\ttfamily</indexterm></findex> +<para>Typewriter. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\textnormal (\normalfont)</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="118" mergedindex="cp">\textnormal</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="119" mergedindex="cp">\normalfont</indexterm></findex> +<para>Main document font. +</para> +</tableitem></tableentry></table> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="101">emphasis</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="120" mergedindex="cp">\emph</indexterm></findex> +<para>Although it also changes fonts, the <code>\emph{<var>text</var>}</code> command +is semantic, for text to be emphasized, and should not be used as a +substitute for <code>\textit</code>. For example, <code>\emph{<var>start +text</var> \emph{<var>middle text</var>} <var>end text</var>}</code> will result in the +<var>start text</var> and <var>end text</var> in italics, but <var>middle text</var> +will be in roman. +</para> +<para>&latex; also provides the following commands, which unconditionally +switch to the given style, that is, are <emph>not</emph> cumulative. They are +used as declarations: <code>{\<var>cmd</var>...}</code> instead of +<code>\<var>cmd</var>{...}</code>. +</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> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="121" mergedindex="cp">\bf</indexterm>\bf</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="102">bold font</indexterm></cindex> +<para>Switch to bold face. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="122" mergedindex="cp">\cal</indexterm>\cal</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="103">script letters for math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="104">calligraphic letters for math</indexterm></cindex> +<para>Switch to calligraphic letters for math. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="123" mergedindex="cp">\it</indexterm>\it</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="105">italic font</indexterm></cindex> +<para>Italics. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="124" mergedindex="cp">\rm</indexterm>\rm</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="106">roman font</indexterm></cindex> +<para>Roman. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="125" mergedindex="cp">\sc</indexterm>\sc</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="107">small caps font</indexterm></cindex> +<para>Small caps. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="126" mergedindex="cp">\sf</indexterm>\sf</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="108">sans serif font</indexterm></cindex> +<para>Sans serif. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="127" mergedindex="cp">\sl</indexterm>\sl</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="109">slanted font</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="110">oblique font</indexterm></cindex> +<para>Slanted (oblique). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="128" mergedindex="cp">\tt</indexterm>\tt</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="111">typewriter font</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="112">monospace font</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="113">fixed-width font</indexterm></cindex> +<para>Typewriter (monospace, fixed-width). +</para> +</tableitem></tableentry></ftable> + +<para>The <code>\em</code> command is the unconditional version of <code>\emph</code>. +</para> +<para>The following commands are for use in math mode. They are not +cumulative, so <code>\mathbf{\mathit{<var>symbol</var>}}</code> does not +create a boldface and italic <var>symbol</var>; instead, it will just be in +italics. This is because typically math symbols need consistent +typographic treatment, regardless of the surrounding environment. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\mathrm</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="129" mergedindex="cp">\mathrm</indexterm></findex> +<para>Roman, for use in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathbf</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="130" mergedindex="cp">\mathbf</indexterm></findex> +<para>Boldface, for use in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathsf</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="131" mergedindex="cp">\mathsf</indexterm></findex> +<para>Sans serif, for use in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathtt</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="132" mergedindex="cp">\mathtt</indexterm></findex> +<para>Typewriter, for use in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathit</itemformat></item> +<itemx spaces=" "><itemformat command="code">(\mit)</itemformat></itemx> +</tableterm><tableitem><para>Italics, for use in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathnormal</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="133" mergedindex="cp">\mathnormal</indexterm></findex> +<para>For use in math mode, e.g., inside another type style declaration. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\mathcal</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="134" mergedindex="cp">\mathcal</indexterm></findex> +<para>Calligraphic letters, for use in math mode. +</para> +</tableitem></tableentry></table> + +<findex index="fn" spaces=" "><indexterm index="fn" number="135" mergedindex="cp">\mathversion</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="114">math, bold</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="115">bold math</indexterm></cindex> +<para>In addition, the command <code>\mathversion{bold}</code> can be used for +switching to bold letters and symbols in +formulas. <code>\mathversion{normal}</code> restores the default. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="136" mergedindex="cp">\oldstylenums</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="116">numerals, old-style</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="117">old-style numerals</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="118">lining numerals</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="119"><r>package</r>, <code>textcomp</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="120"><code>textcomp</code> <r>package</r></indexterm></cindex> + +<para>Finally, the command <code>\oldstylenums{<var>numerals</var>}</code> will typeset +so-called &textldquo;old-style&textrdquo; numerals, which have differing heights and +depths (and sometimes widths) from the standard &textldquo;lining&textrdquo; numerals, +which all have the same height as uppercase letters. &latex;&textrsquo;s +default fonts support this, and will respect <code>\textbf</code> (but not +other styles; there are no italic old-style numerals in Computer +Modern). Many other fonts have old-style numerals also; sometimes the +<code>textcomp</code> package must be loaded, and sometimes package options +are provided to make them the default. FAQ entry: +<url><urefurl>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=osf</urefurl></url>. +</para> + +</section> +<node name="Font-sizes" spaces=" "><nodename>Font sizes</nodename><nodenext automatic="on">Low-level font commands</nodenext><nodeprev automatic="on">Font styles</nodeprev><nodeup automatic="on">Fonts</nodeup></node> +<section spaces=" "><sectiontitle>Font sizes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="121">font sizes</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="122">typeface sizes</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="123">sizes of text</indexterm></cindex> + +<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 <samp>10pt</samp>, <samp>11pt</samp>, and +<samp>12pt</samp> document size options, respectively (<pxref label="Document-class-options"><xrefnodename>Document class +options</xrefnodename></pxref>). +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="137" mergedindex="cp">\tiny</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="138" mergedindex="cp">\scriptsize</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="139" mergedindex="cp">\footnotesize</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="140" mergedindex="cp">\small</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="141" mergedindex="cp">\normalsize</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="142" mergedindex="cp">\large</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="143" mergedindex="cp">\Large</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="144" mergedindex="cp">\LARGE</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="145" mergedindex="cp">\huge</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="146" mergedindex="cp">\Huge</indexterm></findex> + +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on"><code>\normalsize</code> (default)<spacecmd type="spc"/><spacecmd type="spc"/></columnprototype> <columnprototype bracketed="on">24.88<spacecmd type="spc"/><spacecmd type="spc"/></columnprototype> <columnprototype bracketed="on">24.88<spacecmd type="spc"/><spacecmd type="spc"/></columnprototype> <columnprototype bracketed="on">24.88</columnprototype></columnprototypes> +<thead><row><entry command="headitem" spaces=" "><para>Command </para></entry><entry command="tab" spaces=" "><para><code>10pt</code> </para></entry><entry command="tab" spaces=" "><para><code>11pt</code> </para></entry><entry command="tab" spaces=" "><para><code>12pt</code> +</para></entry></row></thead><tbody><row><entry command="item" spaces=" "><para><code>\tiny</code> +</para></entry><entry command="tab" spaces=" "><para>5 </para></entry><entry command="tab" spaces=" "><para>6 </para></entry><entry command="tab" spaces=" "><para>6 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\scriptsize</code> +</para></entry><entry command="tab" spaces=" "><para>7 </para></entry><entry command="tab" spaces=" "><para>8 </para></entry><entry command="tab" spaces=" "><para>8 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\footnotesize</code> +</para></entry><entry command="tab" spaces=" "><para>8 </para></entry><entry command="tab" spaces=" "><para>9 </para></entry><entry command="tab" spaces=" "><para>10 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\small</code> +</para></entry><entry command="tab" spaces=" "><para>9 </para></entry><entry command="tab" spaces=" "><para>10 </para></entry><entry command="tab" spaces=" "><para>10.95 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\normalsize</code> (default) +</para></entry><entry command="tab" spaces=" "><para>10 </para></entry><entry command="tab" spaces=" "><para>10.95 </para></entry><entry command="tab" spaces=" "><para>12 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\large</code> +</para></entry><entry command="tab" spaces=" "><para>12 </para></entry><entry command="tab" spaces=" "><para>12 </para></entry><entry command="tab" spaces=" "><para>14.4 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\Large</code> +</para></entry><entry command="tab" spaces=" "><para>14.4 </para></entry><entry command="tab" spaces=" "><para>14.4 </para></entry><entry command="tab" spaces=" "><para>17.28 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\LARGE</code> +</para></entry><entry command="tab" spaces=" "><para>17.28 </para></entry><entry command="tab" spaces=" "><para>17.28 </para></entry><entry command="tab" spaces=" "><para>20.74 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\huge</code> +</para></entry><entry command="tab" spaces=" "><para>20.74 </para></entry><entry command="tab" spaces=" "><para>20.74 </para></entry><entry command="tab" spaces=" "><para>24.88 +</para></entry></row><row><entry command="item" spaces=" "><para><code>\Huge</code> +</para></entry><entry command="tab" spaces=" "><para>24.88 </para></entry><entry command="tab" spaces=" "><para>24.88 </para></entry><entry command="tab" spaces=" "><para>24.88 +</para></entry></row></tbody></multitable> + +<para>The commands are listed here in declaration forms. You use them by +declaring them, as with this example. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{quotation} \small + The Tao that can be named is not the eternal Tao. +\end{quotation} +</pre></example> + +<noindent></noindent> +<para>The scope of the <code>\small</code> lasts until the end of the +<code>quotation</code> environment. It would also end at the next type style +command or the end of the current group, so you could enclose it in +extra curly braces <code>{\small We are here, we are here, we are +here!}</code>. You can instead use the environment form of these commands; +for instance, <code>\begin{tiny}...\end{tiny}</code>. +</para> + +</section> +<node name="Low_002dlevel-font-commands" spaces=" "><nodename>Low-level font commands</nodename><nodeprev automatic="on">Font sizes</nodeprev><nodeup automatic="on">Fonts</nodeup></node> +<section spaces=" "><sectiontitle>Low-level font commands</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="124">low-level font commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="125">font commands, low-level</indexterm></cindex> + +<para>These commands are primarily intended for writers of macros and +packages. The commands listed here are only a subset of the available +ones. +<!-- c xx but it should be complete --> +<!-- c xx something about ultimately reading ENCFAM.fd? --> +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="low-level-font-commands-fontencoding">low level font commands fontencoding</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">\fontencoding{<var>encoding</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="147" mergedindex="cp">\fontencoding</indexterm></findex> +<para>Select the font encoding, the encoding of the output font. There are a +large number of valid encodings. The most common are <code>OT1</code>, +Knuth&textrsquo;s original encoding for Computer Modern (the default), and +<code>T1</code>, 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 +<url><urefurl>https://ctan.org/pkg/encguide</urefurl></url>. +</para> +<anchor name="low-level-font-commands-fontfamily">low level font commands fontfamily</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\fontfamily{<var>family</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="148" mergedindex="cp">\fontfamily</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="126">families, of fonts</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="127">font catalogue</indexterm></cindex> +<para>Select the font family. The web page +<url><urefurl>http://www.tug.dk/FontCatalogue/</urefurl></url> provides one way to browse +through many of the fonts easily used with &latex;. Here are +examples of some common families. +</para> +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on">font</columnprototype> <columnprototype bracketed="on">Computer Modern Typewriter more space</columnprototype></columnprototypes> +<tbody><row><entry command="item" spaces=" "><para><code>pag</code> +</para></entry><entry command="tab" spaces=" "><para>Avant Garde +</para></entry></row><row><entry command="item" spaces=" "><para><code>fvs</code> +</para></entry><entry command="tab" spaces=" "><para>Bitstream Vera Sans +</para></entry></row><row><entry command="item" spaces=" "><para><code>pbk</code> +</para></entry><entry command="tab" spaces=" "><para>Bookman +</para></entry></row><row><entry command="item" spaces=" "><para><code>bch</code> +</para></entry><entry command="tab" spaces=" "><para>Charter +</para></entry></row><row><entry command="item" spaces=" "><para><code>ccr</code> +</para></entry><entry command="tab" spaces=" "><para>Computer Concrete +</para></entry></row><row><entry command="item" spaces=" "><para><code>cmr</code> +</para></entry><entry command="tab" spaces=" "><para>Computer Modern +</para></entry></row><row><entry command="item" spaces=" "><para><code>cmss</code> +</para></entry><entry command="tab" spaces=" "><para>Computer Modern Sans Serif +</para></entry></row><row><entry command="item" spaces=" "><para><code>cmtt</code> +</para></entry><entry command="tab" spaces=" "><para>Computer Modern Typewriter +</para></entry></row><row><entry command="item" spaces=" "><para><code>pcr</code> +</para></entry><entry command="tab" spaces=" "><para>Courier +</para></entry></row><row><entry command="item" spaces=" "><para><code>phv</code> +</para></entry><entry command="tab" spaces=" "><para>Helvetica +</para></entry></row><row><entry command="item" spaces=" "><para><code>fi4</code> +</para></entry><entry command="tab" spaces=" "><para>Inconsolata +</para></entry></row><row><entry command="item" spaces=" "><para><code>lmr</code> +</para></entry><entry command="tab" spaces=" "><para>Latin Modern +</para></entry></row><row><entry command="item" spaces=" "><para><code>lmss</code> +</para></entry><entry command="tab" spaces=" "><para>Latin Modern Sans +</para></entry></row><row><entry command="item" spaces=" "><para><code>lmtt</code> +</para></entry><entry command="tab" spaces=" "><para>Latin Modern Typewriter +</para></entry></row><row><entry command="item" spaces=" "><para><code>pnc</code> +</para></entry><entry command="tab" spaces=" "><para>New Century Schoolbook +</para></entry></row><row><entry command="item" spaces=" "><para><code>ppl</code> +</para></entry><entry command="tab" spaces=" "><para>Palatino +</para></entry></row><row><entry command="item" spaces=" "><para><code>ptm</code> +</para></entry><entry command="tab" spaces=" "><para>Times +</para></entry></row><row><entry command="item" spaces=" "><para><code>uncl</code> +</para></entry><entry command="tab" spaces=" "><para>Uncial +</para></entry></row><row><entry command="item" spaces=" "><para><code>put</code> +</para></entry><entry command="tab" spaces=" "><para>Utopia +</para></entry></row><row><entry command="item" spaces=" "><para><code>pzc</code> +</para></entry><entry command="tab" spaces=" "><para>Zapf Chancery +</para></entry></row></tbody></multitable> + + +<anchor name="low-level-font-commands-fontseries">low level font commands fontseries</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\fontseries{<var>series</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="149" mergedindex="cp">\fontseries</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="128">series, of fonts</indexterm></cindex> +<para>Select the font series. A <dfn>series</dfn> combines a <dfn>weight</dfn> and a +<dfn>width</dfn>. Typically, a font supports only a few of the possible +combinations. Some common combined series values include: +</para> +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on">xx</columnprototype> <columnprototype bracketed="on">Medium (normal)xx</columnprototype></columnprototypes> +<tbody><row><entry command="item" spaces=" "><para><code>m</code> +</para></entry><entry command="tab" spaces=" "><para>Medium (normal) +</para></entry></row><row><entry command="item" spaces=" "><para><code>b</code> +</para></entry><entry command="tab" spaces=" "><para>Bold +</para></entry></row><row><entry command="item" spaces=" "><para><code>c</code> +</para></entry><entry command="tab" spaces=" "><para>Condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>bc</code> +</para></entry><entry command="tab" spaces=" "><para>Bold condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>bx</code> +</para></entry><entry command="tab" spaces=" "><para>Bold extended +</para></entry></row></tbody></multitable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="129">weights, of fonts</indexterm></cindex> +<para>The possible values for weight, individually, are: +</para> +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on">xx</columnprototype> <columnprototype bracketed="on">Medium (normal) xx</columnprototype></columnprototypes> +<tbody><row><entry command="item" spaces=" "><para><code>ul</code> +</para></entry><entry command="tab" spaces=" "><para>Ultra light +</para></entry></row><row><entry command="item" spaces=" "><para><code>el</code> +</para></entry><entry command="tab" spaces=" "><para>Extra light +</para></entry></row><row><entry command="item" spaces=" "><para><code>l</code> +</para></entry><entry command="tab" spaces=" "><para>Light +</para></entry></row><row><entry command="item" spaces=" "><para><code>sl</code> +</para></entry><entry command="tab" spaces=" "><para>Semi light +</para></entry></row><row><entry command="item" spaces=" "><para><code>m</code> +</para></entry><entry command="tab" spaces=" "><para>Medium (normal) +</para></entry></row><row><entry command="item" spaces=" "><para><code>sb</code> +</para></entry><entry command="tab" spaces=" "><para>Semi bold +</para></entry></row><row><entry command="item" spaces=" "><para><code>b</code> +</para></entry><entry command="tab" spaces=" "><para>Bold +</para></entry></row><row><entry command="item" spaces=" "><para><code>eb</code> +</para></entry><entry command="tab" spaces=" "><para>Extra bold +</para></entry></row><row><entry command="item" spaces=" "><para><code>ub</code> +</para></entry><entry command="tab" spaces=" "><para>Ultra bold +</para></entry></row></tbody></multitable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="130">widths, of fonts</indexterm></cindex> +<para>The possible values for width, individually, are (the meaning and +relationship of these terms varies with individual typefaces): +</para> +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on">xx</columnprototype> <columnprototype bracketed="on">Ultra condensed</columnprototype></columnprototypes> +<tbody><row><entry command="item" spaces=" "><para><code>uc</code> +</para></entry><entry command="tab" spaces=" "><para>Ultra condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>ec</code> +</para></entry><entry command="tab" spaces=" "><para>Extra condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>c</code> +</para></entry><entry command="tab" spaces=" "><para>Condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>sc</code> +</para></entry><entry command="tab" spaces=" "><para>Semi condensed +</para></entry></row><row><entry command="item" spaces=" "><para><code>m</code> +</para></entry><entry command="tab" spaces=" "><para>Medium +</para></entry></row><row><entry command="item" spaces=" "><para><code>sx</code> +</para></entry><entry command="tab" spaces=" "><para>Semi expanded +</para></entry></row><row><entry command="item" spaces=" "><para><code>x</code> +</para></entry><entry command="tab" spaces=" "><para>Expanded +</para></entry></row><row><entry command="item" spaces=" "><para><code>ex</code> +</para></entry><entry command="tab" spaces=" "><para>Extra expanded +</para></entry></row><row><entry command="item" spaces=" "><para><code>ux</code> +</para></entry><entry command="tab" spaces=" "><para>Ultra expanded +</para></entry></row></tbody></multitable> + +<para>When forming the <var>series</var> string from the weight and width, drop the +<code>m</code> that stands for medium weight or medium width, unless both +weight and width are <code>m</code>, in which case use just one +(<samp><code>m</code></samp>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\fontshape{<var>shape</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="150" mergedindex="cp">\fontshape</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="131">shapes, of fonts</indexterm></cindex> +<anchor name="low-level-font-commands-fontshape">low level font commands fontshape</anchor> +<para>Select font shape. Valid shapes are: +</para> +<multitable spaces=" " endspaces=" "><columnprototypes><columnprototype bracketed="on">xx</columnprototype> <columnprototype bracketed="on">Slanted (oblique)xx</columnprototype></columnprototypes> +<tbody><row><entry command="item" spaces=" "><para><code>n</code> +</para></entry><entry command="tab" spaces=" "><para>Upright (normal) +</para></entry></row><row><entry command="item" spaces=" "><para><code>it</code> +</para></entry><entry command="tab" spaces=" "><para>Italic +</para></entry></row><row><entry command="item" spaces=" "><para><code>sl</code> +</para></entry><entry command="tab" spaces=" "><para>Slanted (oblique) +</para></entry></row><row><entry command="item" spaces=" "><para><code>sc</code> +</para></entry><entry command="tab" spaces=" "><para>Small caps +</para></entry></row><row><entry command="item" spaces=" "><para><code>ui</code> +</para></entry><entry command="tab" spaces=" "><para>Upright italics +</para></entry></row><row><entry command="item" spaces=" "><para><code>ol</code> +</para></entry><entry command="tab" spaces=" "><para>Outline +</para></entry></row></tbody></multitable> + +<para>The two last shapes are not available for most font families, and +small caps are often missing as well. +</para> +<anchor name="low-level-font-commands-fontsize">low level font commands fontsize</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\fontsize{<var>size</var>}{<var>skip</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="151" mergedindex="cp">\fontsize</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="132">font size</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="152" mergedindex="cp">\baselineskip</indexterm></findex> +<para>Set the font size and the line spacing. The unit of both parameters +defaults to points (<code>pt</code>). The line spacing is the nominal +vertical space between lines, baseline to baseline. It is stored in the +parameter <code>\baselineskip</code>. The default <code>\baselineskip</code> for +the Computer Modern typeface is 1.2 times the <code>\fontsize</code>. +Changing <code>\baselineskip</code> directly is inadvisable since its value is +reset every time a size change happens; see <code>\baselinestretch</code>, next. +</para> +<anchor name="low-level-font-commands-baselinestretch">low level font commands baselinestretch</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\baselinestretch</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="153" mergedindex="cp">\baselinestretch</indexterm></findex> +<para>&latex; multiplies the line spacing by the value of the +<code>\baselinestretch</code> parameter; the default factor is 1. A change +takes effect when <code>\selectfont</code> (see below) is called. You can +make a line skip change happen for the entire document, for instance +doubling it, by doing <code>\renewcommand{\baselinestretch}{2.0}</code> in +the preamble. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="133"><r>package</r>, <code>setspace</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="134"><code>setspace</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="135">double spacing</indexterm></cindex> +<para>However, the best way to double-space a document is to use the +<file>setspace</file> 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 name="low-level-font-commands-linespread">low level font commands linespread</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\linespread{<var>factor</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="154" mergedindex="cp">\linespread</indexterm></findex> +<para>Equivalent to +<code>\renewcommand{\baselinestretch}{<var>factor</var>}</code>, and +therefore must be followed by <code>\selectfont</code> to have any effect. +Best specified in the preamble, or use the <code>setspace</code> package, as +just described. +</para> +<anchor name="low-level-font-commands-selectfont">low level font commands selectfont</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\selectfont</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="155" mergedindex="cp">\selectfont</indexterm></findex> +<para>The effects of the font commands described above do not happen until +<code>\selectfont</code> is called, as in +<code>\fontfamily{<var>familyname</var>}\selectfont</code>. It is often useful +to put this in a macro:&linebreak; +<code>\newcommand*{\myfont}{\fontfamily{<var>familyname</var>}\selectfont}</code>&linebreak; +(<pxref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & \renewcommand</xrefnodename></pxref>). +</para> +<anchor name="low-level-font-commands-usefont">low level font commands usefont</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\usefont{<var>enc</var>}{<var>family</var>}{<var>series</var>}{<var>shape</var>}</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="156" mergedindex="cp">\usefont</indexterm></findex> +<para>The same as invoking <code>\fontencoding</code>, <code>\fontfamily</code>, +<code>\fontseries</code> and <code>\fontshape</code> with the given parameters, +followed by <code>\selectfont</code>. For example: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usefont{ot1}{cmr}{m}{n} +</pre></example> + +</tableitem></tableentry></table> + + +</section> +</chapter> +<node name="Layout" spaces=" "><nodename>Layout</nodename><nodenext automatic="on">Sectioning</nodenext><nodeprev automatic="on">Fonts</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Layout</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="136">layout commands</indexterm></cindex> + +<para>Commands for controlling the general page layout. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\onecolumn</menunode><menudescription><pre xml:space="preserve">Use one-column layout. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\twocolumn</menunode><menudescription><pre xml:space="preserve">Use two-column layout. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\flushbottom</menunode><menudescription><pre xml:space="preserve">Make all text pages the same height. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\raggedbottom</menunode><menudescription><pre xml:space="preserve">Allow text pages of differing height. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Page layout parameters</menunode><menudescription><pre xml:space="preserve"><code>\headheight</code> <code>\footskip</code>. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Floats</menunode><menudescription><pre xml:space="preserve">Figures, tables, etc. +</pre></menudescription></menuentry></menu> + + +<node name="_005conecolumn" spaces=" "><nodename>\onecolumn</nodename><nodenext automatic="on">\twocolumn</nodenext><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle><code>\onecolumn</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="157" mergedindex="cp">\onecolumn</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="137">one-column output</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\onecolumn +</pre></example> + +<para>Start a new page and produce single-column output. If the document is +given the class option <code>onecolumn</code> then this is the default +behavior (<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>). This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> + +</section> +<node name="_005ctwocolumn" spaces=" "><nodename>\twocolumn</nodename><nodenext automatic="on">\flushbottom</nodenext><nodeprev automatic="on">\onecolumn</nodeprev><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle><code>\twocolumn</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="158" mergedindex="cp">\twocolumn</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="138">multicolumn text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="139">two-column output</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\twocolumn +\twocolumn[<var>prelim one column text</var>] +</pre></example> + +<para>Start a new page and produce two-column output. If the document is given +the class option <code>twocolumn</code> then this is the default +(<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>). This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>If the optional <var>prelim one column text</var> 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> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="159" mergedindex="cp">\columnsep</indexterm>\columnsep</itemformat></item> +</tableterm><tableitem><anchor name="twocolumn-columnsep">twocolumn columnsep</anchor> +<para>The distance between columns. The default is 35pt. Change it with a +command such as <code>\setlength{\columnsep}{40pt}</code> You must change +it before the two column environment starts; in the preamble is a good +place. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="160" mergedindex="cp">\columnseprule</indexterm>\columnseprule</itemformat></item> +</tableterm><tableitem><anchor name="twocolumn-columnseprule">twocolumn columnseprule</anchor> +<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 +<code>\setlength{\columnseprule}{0.4pt}</code>, before the two-column +environment starts. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="161" mergedindex="cp">\columnwidth</indexterm>\columnwidth</itemformat></item> +</tableterm><tableitem><anchor name="twocolumn-columnwidth">twocolumn columnwidth</anchor> +<para>The width of a single column. In one-column mode this is equal to +<code>\textwidth</code>. In two-column mode by default &latex; sets the +width of each of the two columns to be half of <code>\textwidth</code> minus +<code>\columnsep</code>. +</para> +</tableitem></tableentry></ftable> + +<para>In a two-column document, the starred environments <code>table*</code> and +<code>figure*</code> are two columns wide, whereas the unstarred environments +<code>table</code> and <code>figure</code> take up only one column (<pxref label="figure"><xrefnodename>figure</xrefnodename></pxref> +and <pxref label="table"><xrefnodename>table</xrefnodename></pxref>). &latex; places starred floats at the top of a page. +The following parameters control float behavior of two-column output. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="twocolumn-dbltopfraction">twocolumn dbltopfraction</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="162" mergedindex="cp">\dbltopfraction</indexterm>\dbltopfraction</itemformat></item> +</tableterm><tableitem><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 <code>table*</code> or <code>figure*</code> environment must not +exceed <code>0.7\textheight</code> . 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> +<itemize commandarg="bullet" spaces=" " endspaces=" "><itemprepend><formattingcommand command="bullet"/></itemprepend> +<listitem><prepend>•</prepend> +<para>Use the <code>[tp]</code> 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><prepend>•</prepend> +<para>Use the <code>[t!]</code> location specifier to override the effect of +<code>\dbltopfraction</code> for this particular float. +</para> +</listitem><listitem><prepend>•</prepend> +<para>Increase the value of <code>\dbltopfraction</code> to a suitably large number, +to avoid going to float pages so soon. +</para></listitem></itemize> + +<para>You can redefine it, as with +<code>\renewcommand{\dbltopfraction}{0.9}</code>. +</para> +<anchor name="twocolumn-dblfloatpagefraction">twocolumn dblfloatpagefraction</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="163" mergedindex="cp">\dblfloatpagefraction</indexterm>\dblfloatpagefraction</itemformat></item> +</tableterm><tableitem><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;&textrsquo;s default is <code>0.5</code>. Change it with <code>\renewcommand</code>. +</para> +<anchor name="twocolumn-dblfloatsep">twocolumn dblfloatsep</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="164" mergedindex="cp">\dblfloatsep</indexterm>\dblfloatsep</itemformat></item> +</tableterm><tableitem><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 +<code>12pt plus2pt minus2pt</code> for a document set at <code>10pt</code> or +<code>11pt</code>, and <code>14pt plus2pt minus4pt</code> for a document set at +<code>12pt</code>. +</para> +<anchor name="twocolumn-dbltextfloatsep">twocolumn dbltextfloatsep</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="165" mergedindex="cp">\dbltextfloatsep</indexterm>\dbltextfloatsep</itemformat></item> +</tableterm><tableitem><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 <code>20pt plus2pt +minus4pt</code>. +</para> +<anchor name="twocolumn-dbltopnumber">twocolumn dbltopnumber</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="166" mergedindex="cp">\dbltopnumber</indexterm>\dbltopnumber</itemformat></item> +</tableterm><tableitem><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 <code>2</code>. +</para> +</tableitem></tableentry></ftable> + +<!-- c From egreg at http://tex.stackexchange.com/a/142232/339 --> +<para>This example uses <code>\twocolumn</code>&textrsquo;s optional argument of to create a +title that spans the two-column article: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}&arobase;{\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. +</pre></example> + + +</section> +<node name="_005cflushbottom" spaces=" "><nodename>\flushbottom</nodename><nodenext automatic="on">\raggedbottom</nodenext><nodeprev automatic="on">\twocolumn</nodeprev><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle><code>\flushbottom</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="167" mergedindex="cp">\flushbottom</indexterm></findex> + +<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 <samp>Underfull \vbox (badness 10000) has +occurred while \output is active</samp>. If you get that, one option is to +change to <code>\raggedbottom</code> (<pxref label="_005craggedbottom"><xrefnodename>\raggedbottom</xrefnodename></pxref>). Alternatively, +you can adjust the <code>textheight</code> to make compatible pages, or you +can add some vertical stretch glue between lines or between paragraphs, +as in <code>\setlength{\parskip}{0ex plus0.1ex}</code>. Your last option +is to, in a final editing stage, adjust the height of individual pages +(<pxref label="_005cenlargethispage"><xrefnodename>\enlargethispage</xrefnodename></pxref>). +</para> +<para>The <code>\flushbottom</code> state is the default only if you select the +<code>twoside</code> document class option (<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>). +</para> + +</section> +<node name="_005craggedbottom" spaces=" "><nodename>\raggedbottom</nodename><nodenext automatic="on">Page layout parameters</nodenext><nodeprev automatic="on">\flushbottom</nodeprev><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle><code>\raggedbottom</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="168" mergedindex="cp">\raggedbottom</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="140">stretch, omitting vertical</indexterm></cindex> + +<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 <ref label="_005cflushbottom"><xrefnodename>\flushbottom</xrefnodename></ref>. +</para> +<para>This is the default unless you select the <code>twoside</code> document class +option (<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>). +</para> + +</section> +<node name="Page-layout-parameters" spaces=" "><nodename>Page layout parameters</nodename><nodenext automatic="on">Floats</nodenext><nodeprev automatic="on">\raggedbottom</nodeprev><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle>Page layout parameters</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="141">page layout parameters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="142">parameters, page layout</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="143">layout, page parameters for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="144">header, parameters for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="145">footer, parameters for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="146">running header and footer</indexterm></cindex> + +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="169" mergedindex="cp">\columnsep</indexterm>\columnsep</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="170" mergedindex="cp">\columnseprule</indexterm>\columnseprule</itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="171" mergedindex="cp">\columnwidth</indexterm>\columnwidth</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="172" mergedindex="cp">\columnsep</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="173" mergedindex="cp">\columnseprule</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="174" mergedindex="cp">\columnwidth</indexterm></findex> +<anchor name="page-layout-parameters-columnsep">page layout parameters columnsep</anchor> +<anchor name="page-layout-parameters-columnseprule">page layout parameters columnseprule</anchor> +<anchor name="page-layout-parameters-columnwidth">page layout parameters columnwidth</anchor> +<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 +<code>twocolumn</code> is in effect (<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>). +<xref label="_005ctwocolumn"><xrefnodename>\twocolumn</xrefnodename></xref>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="175" mergedindex="cp">\headheight</indexterm>\headheight</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="176" mergedindex="cp">\headheight</indexterm></findex> +<anchor name="page-layout-parameters-headheight">page layout parameters headheight</anchor> +<para>Height of the box that contains the running head. The default in the +<code>article</code>, <code>report</code>, and <code>book</code> classes is <samp>12pt</samp>, +at all type sizes. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="177" mergedindex="cp">\headsep</indexterm>\headsep</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="178" mergedindex="cp">\headsep</indexterm></findex> +<anchor name="page-layout-parameters-headsep">page layout parameters headsep</anchor> +<para>Vertical distance between the bottom of the header line and the top of +the main text. The default in the <code>article</code> and <code>report</code> +classes is <samp>25pt</samp>. In the <code>book</code> class the default is: if the +document is set at 10pt then it is <samp>0.25in</samp>, and at 11pt and 12pt +it is <samp>0.275in</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="179" mergedindex="cp">\footskip</indexterm>\footskip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="180" mergedindex="cp">\footskip</indexterm></findex> +<anchor name="page-layout-parameters-footskip">page layout parameters footskip</anchor> +<para>Distance from the baseline of the last line of text to the baseline of +the page footer. The default in the <code>article</code> and <code>report</code> +classes is <samp>30pt</samp>. In the <code>book</code> class the default is: when +the type size is 10pt the default is <samp>0.35in</samp>, while at 11pt it is +<samp>0.38in</samp>, and at 12pt it is <samp>30pt</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="181" mergedindex="cp">\linewidth</indexterm>\linewidth</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="182" mergedindex="cp">\linewidth</indexterm></findex> +<anchor name="page-layout-parameters-linewidth">page layout parameters linewidth</anchor> +<para>Width of the current line, decreased for each nested <code>list</code> +(<pxref label="list"><xrefnodename>list</xrefnodename></pxref>). That is, the nominal value for <code>\linewidth</code> is to +equal <code>\textwidth</code> but for each nested list the <code>\linewidth</code> +is decreased by the sum of that list&textrsquo;s <code>\leftmargin</code> and +<code>\rightmargin</code> (<pxref label="itemize"><xrefnodename>itemize</xrefnodename></pxref>). +<!-- c The default varies with the font size, paper width, two-column mode, --> +<!-- c etc. For an @code{article} document set in 10pt, the default is --> +<!-- c @samp{345pt}, while in two-column mode that becomes @samp{229.5pt}. --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="183" mergedindex="cp">\marginparpush</indexterm>\marginparpush</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="184" mergedindex="cp">\marginsep</indexterm>\marginsep</itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="185" mergedindex="cp">\marginparwidth</indexterm>\marginparwidth</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="186" mergedindex="cp">\marginparpush</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="187" mergedindex="cp">\marginsep</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="188" mergedindex="cp">\marginparwidth</indexterm></findex> +<anchor name="page-layout-parameters-marginparpush">page layout parameters marginparpush</anchor> +<anchor name="page-layout-parameters-marginsep">page layout parameters marginsep</anchor> +<anchor name="page-layout-parameters-marginparwidth">page layout parameters marginparwidth</anchor> +<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 <code>\reversemarginpar</code> changes that (and +<code>\normalmarginpar</code> changes it back). +</para> +<para>The defaults for <code>\marginparpush</code> in both <code>book</code> and +<code>article</code> classes are: <samp>7pt</samp> if the document is set at 12pt, +and <samp>5pt</samp> if the document is set at 11pt or 10pt. +</para> +<para>For <code>\marginsep</code>, in <code>article</code> class the default is +<samp>10pt</samp> except if the document is set at 10pt and in two-column mode +where the default is <samp>11pt</samp>. +</para> +<para>For <code>\marginsep</code> in <code>book</code> class the default is <samp>10pt</samp> in +two-column mode and <samp>7pt</samp> in one-column mode. +</para> +<para>For <code>\marginparwidth</code> in both <code>book</code> and <code>article</code> +classes, in two-column mode the default is 60% of <code>\paperwidth +− \textwidth</code>, while in one-column mode it is 50% of that +distance. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="189" mergedindex="cp">\oddsidemargin</indexterm>\oddsidemargin</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="190" mergedindex="cp">\evensidemargin</indexterm>\evensidemargin</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="191" mergedindex="cp">\oddsidemargin</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="192" mergedindex="cp">\evensidemargin</indexterm></findex> +<anchor name="page-layout-parameters-oddsidemargin">page layout parameters oddsidemargin</anchor> +<anchor name="page-layout-parameters-evensidemargin">page layout parameters evensidemargin</anchor> +<para>The <code>\oddsidemargin</code> is the extra distance between the left side of +the page and the text&textrsquo;s left margin, on odd-numbered pages when the +document class option <code>twoside</code> is chosen and on all pages when +<code>oneside</code> is in effect. When <code>twoside</code> is in effect, on +even-numbered pages the extra distance on the left is +<code>evensidemargin</code>. +</para> +<para>&latex;&textrsquo;s default is that <code>\oddsidemargin</code> is 40% of the +difference between <code>\paperwidth</code> and <code>\textwidth</code>, and +<code>\evensidemargin</code> is the remainder. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="193" mergedindex="cp">\paperheight</indexterm>\paperheight</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="194" mergedindex="cp">\paperheight</indexterm></findex> +<anchor name="page-layout-parameters-paperheight">page layout parameters paperheight</anchor> +<para>The height of the paper, as distinct from the height of the print area. +Normally set with a document class option, as in +<code>\documentclass[a4paper]{article}</code> (<pxref label="Document-class-options"><xrefnodename>Document class +options</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="195" mergedindex="cp">\paperwidth</indexterm>\paperwidth</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="196" mergedindex="cp">\paperwidth</indexterm></findex> +<anchor name="page-layout-parameters-paperwidth">page layout parameters paperwidth</anchor> +<para>The width of the paper, as distinct from the width of the print area. +Normally set with a document class option, as in +<code>\documentclass[a4paper]{article}</code> (<pxref label="Document-class-options"><xrefnodename>Document class +options</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="197" mergedindex="cp">\textheight</indexterm>\textheight</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="198" mergedindex="cp">\textheight</indexterm></findex> +<anchor name="page-layout-parameters-textheight">page layout parameters textheight</anchor> +<para>The normal vertical height of the page body. If the document is set at +a nominal type size of 10pt then for an <code>article</code> or <code>report</code> +the default is <samp>43\baselineskip</samp>, while for a <code>book</code> it is +<samp>41\baselineskip</samp>. At a type size of 11pt the default is +<samp>38\baselineskip</samp> for all document classes. At 12pt it is +<samp>36\baselineskip</samp> for all classes. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="199" mergedindex="cp">\textwidth</indexterm>\textwidth</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="200" mergedindex="cp">\textwidth</indexterm></findex> +<anchor name="page-layout-parameters-textwidth">page layout parameters textwidth</anchor> +<para>The full horizontal width of the entire page body. For an +<code>article</code> or <code>report</code> document, the default is <samp>345pt</samp> +when the chosen type size is 10pt, the default is <samp>360pt</samp> at 11pt, +and it is <samp>390pt</samp> at 12pt. For a <code>book</code> document, the default +is <samp>4.5in</samp> at a type size of 10pt, and <samp>5in</samp> at 11pt or 12pt. +</para> +<para>In multi-column output, <code>\textwidth</code> remains the width of the +entire page body, while <code>\columnwidth</code> is the width of one column +(<pxref label="_005ctwocolumn"><xrefnodename>\twocolumn</xrefnodename></pxref>). +</para> +<para>In lists (<pxref label="list"><xrefnodename>list</xrefnodename></pxref>), <code>\textwidth</code> remains the width of the +entire page body (and <code>\columnwidth</code> the width of the entire +column), while <code>\linewidth</code> may decrease for nested lists. +</para> +<para>Inside a minipage (<pxref label="minipage"><xrefnodename>minipage</xrefnodename></pxref>) or <code>\parbox</code> +(<pxref label="_005cparbox"><xrefnodename>\parbox</xrefnodename></pxref>), all the width-related parameters are set to the +specified width, and revert to their normal values at the end of the +<code>minipage</code> or <code>\parbox</code>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="201" mergedindex="cp">\hsize</indexterm></findex> +<anchor name="page-layout-parameters-hsize">page layout parameters hsize</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="202" mergedindex="cp">\hsize</indexterm>\hsize</itemformat></item> +</tableterm><tableitem><para>This entry is included for completeness: <code>\hsize</code> is the &tex; +primitive parameter used when text is broken into lines. It should not +be used in normal &latex; documents. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="203" mergedindex="cp">\topmargin</indexterm>\topmargin</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="204" mergedindex="cp">topmargin</indexterm></findex> +<anchor name="page-layout-parameters-topmargin">page layout parameters topmargin</anchor> +<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: <code>\paperheight − 2in − +\headheight − \headsep − \textheight − \footskip</code>, +and then divided by two. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="205" mergedindex="cp">\topskip</indexterm>\topskip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="206" mergedindex="cp">\topskip</indexterm></findex> +<anchor name="page-layout-parameters-topskip">page layout parameters topskip</anchor> +<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., <samp>10pt</samp> at a type size of 10pt. +</para> +</tableitem></tableentry></ftable> + + +</section> +<node name="Floats" spaces=" "><nodename>Floats</nodename><nodeprev automatic="on">Page layout parameters</nodeprev><nodeup automatic="on">Layout</nodeup></node> +<section spaces=" "><sectiontitle>Floats</sectiontitle> + +<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, <code>figure</code> (<pxref label="figure"><xrefnodename>figure</xrefnodename></pxref>) and +<code>table</code> (<pxref label="table"><xrefnodename>table</xrefnodename></pxref>), but you can create a new class with the +package <file>float</file>. +</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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="147">placement of floats</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="148">specifier, float placement</indexterm></cindex> +<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 +<var>placement</var> argument. The possible values are a sequence of the +letters below. The default for both <code>figure</code> and <code>table</code>, in +both <code>article</code> and <code>book</code> classes, is <code>tbp</code>. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">t</itemformat></item> +</tableterm><tableitem><para>(Top)&textmdash;at the top of a text page. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b</itemformat></item> +</tableterm><tableitem><para>(Bottom)&textmdash;at the bottom of a text page. (However, <code>b</code> is not +allowed for full-width floats (<code>figure*</code>) with double-column +output. To ameliorate this, use the <file>stfloats</file> or +<file>dblfloatfix</file> package, but see the discussion at caveats in the +FAQ: <url><urefurl>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=2colfloat</urefurl></url>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">h</itemformat></item> +</tableterm><tableitem><para>(Here)&textmdash;at the position in the text where the <code>figure</code> environment +appears. However, <code>h</code> is not allowed by itself; <code>t</code> is +automatically added. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="149">here, putting floats</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="150"><r>package</r>, <code>float</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="151"><code>float</code> <r>package</r></indexterm></cindex> + +<para>To absolutely force a float to appear &textldquo;here&textrdquo;, you can +<code>\usepackage{float}</code> and use the <code>H</code> specifier which it +defines. For further discussion, see the FAQ entry at +<url><urefurl>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=figurehere</urefurl></url>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">p</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="152">float page</indexterm></cindex> +<para>(Page of floats)&textmdash;on a separate <dfn>float page</dfn>, which is a page +containing no text, only floats. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">!</itemformat></item> +</tableterm><tableitem><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 <code>!</code> specifier does <emph>not</emph> mean &textldquo;put the float here&textrdquo;; +see above. +</para> +</tableitem></tableentry></table> + +<para>Note: the order in which letters appear in the <var>placement</var> argument +does not change the order in which &latex; tries to place the float; +for instance, <code>btp</code> has the same effect as <code>tbp</code>. All that +<var>placement</var> does is that if a letter is not present then the +algorithm does not try that location. Thus, &latex;&textrsquo;s default of +<code>tbp</code> 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 <code>\clearpage</code> command to start a new page and +insert all pending floats. If a pagebreak is undesirable then you can +use the <file>afterpage</file> package and issue +<code>\afterpage{\clearpage}</code>. This will wait until the current page +is finished and then flush all outstanding floats. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="153"><r>package</r>, <code>flafter</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="154"><code>flafter</code> <r>package</r></indexterm></cindex> + +<para>&latex; can typeset a float before where it appears in the source +(although on the same output page) if there is a <code>t</code> specifier in +the <var>placement</var> parameter. If this is not desired, and deleting +the <code>t</code> 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 <file>flafter</file> package or using the command +<findex index="fn" spaces=" "><indexterm index="fn" number="207" mergedindex="cp">\suppressfloats</indexterm></findex> +<code>\suppressfloats[t]</code>, 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 +<code>\renewcommand{<var>parameter</var>}{<var>decimal between 0 and 1</var>}</code>): +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="208" mergedindex="cp">\bottomfraction</indexterm>\bottomfraction</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="209" mergedindex="cp">\bottomfraction</indexterm></findex> +<anchor name="floats-bottomfraction">floats bottomfraction</anchor> +<para>The maximum fraction of the page allowed to be occupied by floats at +the bottom; default <samp>.3</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="210" mergedindex="cp">\floatpagefraction</indexterm>\floatpagefraction</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="211" mergedindex="cp">\floatpagefraction</indexterm></findex> +<anchor name="floats-floatpagefraction">floats floatpagefraction</anchor> +<para>The minimum fraction of a float page that must be occupied by floats; +default <samp>.5</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="212" mergedindex="cp">\textfraction</indexterm>\textfraction</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="213" mergedindex="cp">\textfraction</indexterm></findex> +<anchor name="floats-textfraction">floats textfraction</anchor> +<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 <samp>.2</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="214" mergedindex="cp">\topfraction</indexterm>\topfraction</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="215" mergedindex="cp">\topfraction</indexterm></findex> +<anchor name="floats-topfraction">floats topfraction</anchor> +<para>Maximum fraction at the top of a page that may be occupied before +floats; default <samp>.7</samp>. +</para></tableitem></tableentry></ftable> + +<para>Parameters relating to vertical space around floats (change them with a +command of the form <code>\setlength{<var>parameter</var>}{<var>length +expression</var>}</code>): +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="216" mergedindex="cp">\floatsep</indexterm>\floatsep</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="217" mergedindex="cp">\floatsep</indexterm></findex> +<anchor name="floats-floatsep">floats floatsep</anchor> +<para>Space between floats at the top or bottom of a page; default +<samp>12pt plus2pt minus2pt</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="218" mergedindex="cp">\intextsep</indexterm>\intextsep</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="219" mergedindex="cp">\intextsep</indexterm></findex> +<anchor name="floats-intextsep">floats intextsep</anchor> +<para>Space above and below a float in the middle of the main text; default +<samp>12pt plus2pt minus2pt</samp> for 10 point and 11 point documents, +and <samp>14pt plus4pt minus4pt</samp> for 12 point documents. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="220" mergedindex="cp">\textfloatsep</indexterm>\textfloatsep</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="221" mergedindex="cp">\textfloatsep</indexterm></findex> +<anchor name="floats-textfloatsep">floats textfloatsep</anchor> +<para>Space between the last (first) float at the top (bottom) of a page; +default <samp>20pt plus2pt minus4pt</samp>. +</para></tableitem></tableentry></ftable> + +<para>Counters relating to the number of floats on a page (change them with a +command of the form <code>\setcounter{<var>ctrname</var>}{<var>natural +number</var>}</code>): +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="222" mergedindex="cp">bottomnumber</indexterm>bottomnumber</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="223" mergedindex="cp">bottomnumber</indexterm></findex> +<anchor name="floats-bottomnumber">floats bottomnumber</anchor> +<para>Maximum number of floats that can appear at the bottom of a text page; +default 1. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="224" mergedindex="cp">dbltopnumber</indexterm>dbltopnumber</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="225" mergedindex="cp">dbltopnumber</indexterm></findex> +<anchor name="floats-dbltopnumber">floats dbltopnumber</anchor> +<para>Maximum number of full-sized floats that can appear at the top of a +two-column page; default 2. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="226" mergedindex="cp">topnumber</indexterm>topnumber</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="227" mergedindex="cp">topnumber</indexterm></findex> +<anchor name="floats-topnumber">floats topnumber</anchor> +<para>Maximum number of floats that can appear at the top of a text page; +default 2. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="228" mergedindex="cp">totalnumber</indexterm>totalnumber</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="229" mergedindex="cp">totalnumber</indexterm></findex> +<anchor name="floats-totalnumber">floats totalnumber</anchor> +<para>Maximum number of floats that can appear on a text page; default 3. +</para></tableitem></tableentry></ftable> + +<para>The principal &tex; FAQ entry relating to floats +<url><urefurl>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats</urefurl></url> contains +suggestions for relaxing &latex;&textrsquo;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&textrsquo;s article &textldquo;How to +influence the position of float environments like figure and table in +&latex;?&textrdquo; +(<url><urefurl>http://latex-project.org/papers/tb111mitt-float.pdf</urefurl></url>). +</para> + +</section> +</chapter> +<node name="Sectioning" spaces=" "><nodename>Sectioning</nodename><nodenext automatic="on">Cross references</nodenext><nodeprev automatic="on">Layout</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Sectioning</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="155">sectioning commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="156">part</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="157">chapter</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="158">section</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="159">subsection</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="160">paragraph</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="161">subparagraph</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="230" mergedindex="cp">\part</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="231" mergedindex="cp">\chapter</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="232" mergedindex="cp">\section</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="233" mergedindex="cp">\subsection</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="234" mergedindex="cp">\paragraph</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="235" mergedindex="cp">\subparagraph</indexterm></findex> + +<para>Structure your text into divisions: parts, chapters, sections, etc. All +sectioning commands have the same form, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>sectioning-command</var>{<var>title</var>} +<var>sectioning-command</var>*{<var>title</var>} +<var>sectioning-command</var>[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<noindent></noindent> +<para>For instance, declare the start of a subsection as with +<code>\subsection{Motivation}</code>. +</para> +<para>The table has each <var>sectioning-command</var> in &latex;. All are +available in all of &latex;&textrsquo;s standard document classes <code>book</code>, +<code>report</code>, and <code>article</code>, except that <code>\chapter</code> is +not available in <code>article</code>. +</para> +<multitable spaces=" " endspaces=" "><columnfractions line=" .25 .25 .40 "><columnfraction value=".25"></columnfraction><columnfraction value=".25"></columnfraction><columnfraction value=".40"></columnfraction></columnfractions> +<thead><row><entry command="headitem" spaces=" "><para>Sectioning unit </para></entry><entry command="tab" spaces=" "><para>Command </para></entry><entry command="tab" spaces=" "><para>Level +</para></entry></row></thead><tbody><row><entry command="item" spaces=" "><para>Part +</para></entry><entry command="tab" spaces=" "><para><code>\part</code> </para></entry><entry command="tab" spaces=" "><para>-1 (<code>book</code>, <code>report</code>), 0 (<code>article</code>) +</para></entry></row><row><entry command="item" spaces=" "><para>Chapter +</para></entry><entry command="tab" spaces=" "><para><code>\chapter</code> </para></entry><entry command="tab" spaces=" "><para>0 +</para></entry></row><row><entry command="item" spaces=" "><para>Section +</para></entry><entry command="tab" spaces=" "><para><code>\section</code> </para></entry><entry command="tab" spaces=" "><para>1 +</para></entry></row><row><entry command="item" spaces=" "><para>Subsection +</para></entry><entry command="tab" spaces=" "><para><code>\subsection</code> </para></entry><entry command="tab" spaces=" "><para>2 +</para></entry></row><row><entry command="item" spaces=" "><para>Subsubsection +</para></entry><entry command="tab" spaces=" "><para><code>\subsubsection</code> </para></entry><entry command="tab" spaces=" "><para>3 +</para></entry></row><row><entry command="item" spaces=" "><para>Paragraph +</para></entry><entry command="tab" spaces=" "><para><code>\paragraph</code> </para></entry><entry command="tab" spaces=" "><para>4 +</para></entry></row><row><entry command="item" spaces=" "><para>Subparagraph +</para></entry><entry command="tab" spaces=" "><para><code>\subparagraph</code> </para></entry><entry command="tab" spaces=" "><para>5 +</para></entry></row></tbody></multitable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="162"><code>*</code>-form of sectioning commands</indexterm></cindex> +<para>All these commands have a <code>*</code>-form that prints <var>title</var> as usual +but is not numbered and does not make an entry in the table of contents. +An example of using this is for an appendix in an <code>article</code> . The +input <code>\appendix\section{Appendix}</code> gives the output <samp>A +Appendix</samp> (<pxref label="_005cappendix"><xrefnodename>\appendix</xrefnodename></pxref>). You can lose the numbering <samp>A</samp> +by instead entering <code>\section*{Appendix}</code> (articles often omit a +table of contents and have simple page headers so the other differences +from the <code>\section</code> command may not matter). +</para> +<para>The section title <var>title</var> provides the heading in the main text, but +it may also appear in the table of contents and in the running head or +foot (<pxref label="Page-styles"><xrefnodename>Page styles</xrefnodename></pxref>). You may not want the same text in these +places as in the main text. All of these commands have an optional +argument <var>toc-title</var> 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&textrsquo;s <var>level</var> is less than or equal to the value of the counter +<code>secnumdepth</code> then the titles for this sectioning command will be +numbered (<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref>). And, if <var>level</var> is less +than or equal to the value of the counter <code>tocdepth</code> then the table +of contents will have an entry for this sectioning unit +(<pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<para>&latex; expects that before you have a <code>\subsection</code> you will have +a <code>\section</code> and, in a book, that before a <code>\section</code> you will +have a <code>\chapter</code>. Otherwise you can get a something like a +subsection numbered <samp>3.0.1</samp>. +</para> +<para>Two counters relate to the appearance of sectioning commands. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="236" mergedindex="cp">secnumdepth</indexterm>secnumdepth</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="237" mergedindex="cp">secnumdepth <r>counter</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="163">section numbers, printing</indexterm></cindex> +<anchor name="sectioning-secnumdepth">sectioning secnumdepth</anchor> +<anchor name="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</anchor> +<para>Controls which sectioning commands are +numbered. Suppress numbering of sectioning at any depth greater than +<var>level</var> <code>\setcounter{secnumdepth}{<var>level</var>}</code> +(<pxref label="_005csetcounter"><xrefnodename>\setcounter</xrefnodename></pxref>). See the above table for the level numbers. For +instance, if the <code>secnumdepth</code> is 1 in an <code>article</code> then a +<code>\section{Introduction}</code> command will produce output like <samp>1 +Introduction</samp> while <code>\subsection{Discussion}</code> will produce output +like <samp>Discussion</samp>, without the number. &latex;&textrsquo;s default +<code>secnumdepth</code> is 3 in <file>article</file> class and 2 in the +<file>book</file> and <file>report</file> classes. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="238" mergedindex="cp">tocdepth</indexterm>tocdepth</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="239" mergedindex="cp">tocdepth <r>counter</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="164">table of contents, sectioning numbers printed</indexterm></cindex> +<anchor name="sectioning-tocdepth">sectioning tocdepth</anchor> +<anchor name="Sectioning_002ftocdepth">Sectioning/tocdepth</anchor> +<para>Controls which sectioning units are listed in the table of contents. +The setting <code>\setcounter{tocdepth}{<var>level</var>}</code> makes the +sectioning units at <var>level</var> be the smallest ones listed +(<pxref label="_005csetcounter"><xrefnodename>\setcounter</xrefnodename></pxref>). See the above table for the level numbers. For +instance, if <code>tocdepth</code> is 1 then the table of contents will +list sections but not subsections. &latex;&textrsquo;s default +<code>secnumdepth</code> is 3 in <file>article</file> class and 2 in the +<file>book</file> and <file>report</file> classes. +</para> +</tableitem></tableentry></ftable> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\part</menunode><menudescription><pre xml:space="preserve">Start a part. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\chapter</menunode><menudescription><pre xml:space="preserve">Start a chapter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\section</menunode><menudescription><pre xml:space="preserve">Start a section. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\subsection</menunode><menudescription><pre xml:space="preserve">Start a subsection. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\subsubsection & \paragraph & \subparagraph</menunode><menudescription><pre xml:space="preserve">Lower divisions. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\appendix</menunode><menudescription><pre xml:space="preserve">Start appendices. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\frontmatter & \mainmatter & \backmatter</menunode><menudescription><pre xml:space="preserve">The three parts of a book. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\&arobase;startsection</menunode><menudescription><pre xml:space="preserve">Layout of sectional units. +</pre></menudescription></menuentry></menu> + + +<node name="_005cpart" spaces=" "><nodename>\part</nodename><nodenext automatic="on">\chapter</nodenext><nodeup automatic="on">Sectioning</nodeup></node> +<section spaces=" "><sectiontitle><code>\part</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="240" mergedindex="cp">\part</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="165">part</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="166">sectioning, part</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\part{<var>title</var>} +\part*{<var>title</var>} +\part[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<para>Start a document part. The standard &latex; classes <code>book</code>, +<code>report</code>, and <code>article</code>, all have this command. +</para> +<para>This produces a document part, in a book. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<para>In each standard class the <code>\part</code> command outputs a part number +such as <samp>Part I</samp>, alone on its line, in boldface, and in large +type. Then &latex; outputs <var>title</var>, also alone on its line, in +bold and in even larger type. In class <code>book</code>, 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 <code>report</code> it is again alone on a page, but +&latex; won&textrsquo;t force it onto an odd-numbered page. In an <code>article</code> +&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 <code>*</code> form shows <var>title</var> +but it does not show the part number, does not increment the +<code>part</code> counter, and produces no table of contents entry. +</para> +<para>The optional argument <var>toc-title</var> will appear as the part title in +the table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>) and in running +headers (<pxref label="Page-styles"><xrefnodename>Page styles</xrefnodename></pxref>). If it is not present then <var>title</var> +will be there. This example puts a line break in <var>title</var> but leaves +out the break in the table of contents. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\part[Up from the bottom; my life]{Up from the bottom\\ my life} +</pre></example> + +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a part is -1 +(<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref> and <pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="167"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="168"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<para>In the class <code>article</code>, if a paragraph immediately follows the part +title then it is not indented. To get an indent you can use the package +<file>indentfirst</file>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="169"><r>package</r>, <code>titlesec</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="170"><code>titlesec</code> <r>package</r></indexterm></cindex> + +<para>One package to change the behavior of <code>\part</code> is <file>titlesec</file>. +See its documentation on CTAN. +</para> + +</section> +<node name="_005cchapter" spaces=" "><nodename>\chapter</nodename><nodenext automatic="on">\section</nodenext><nodeprev automatic="on">\part</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> +<section spaces=" "><sectiontitle><code>\chapter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="241" mergedindex="cp">\chapter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="171">chapter</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter{<var>title</var>} +\chapter*{<var>title</var>} +\chapter[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<para>Start a chapter. The standard &latex; classes <code>book</code> and +<code>report</code> have this command but <code>article</code> does not. +</para> +<para>This produces a chapter. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<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 <samp>Chapter 1</samp> in large boldface type (the size is +<code>\huge</code>). It then puts <var>title</var> on a fresh line, in boldface +type that is still larger (size <code>\Huge</code>). It also increments the +<code>chapter</code> counter, adds an entry to the table of contents +(<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>), and sets the running header +information (<pxref label="Page-styles"><xrefnodename>Page styles</xrefnodename></pxref>). +</para> +<para>The <code>*</code> form shows <var>title</var> on a fresh line, in boldface. +But it does not show the chapter number, does not increment the +<code>chapter</code> counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +<code>headings</code> in a two-sided document then the header will be from the +prior chapter.) This example illustrates. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter*{Preamble} +</pre></example> + +<para>The optional argument <var>toc-title</var> will appear as the chapter title +in the table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>) and in +running headers (<pxref label="Page-styles"><xrefnodename>Page styles</xrefnodename></pxref>). If it is not present then +<var>title</var> will be there. This shows the full name in the chapter +title, +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter[Weyl]{Hermann Klaus Hugo (Peter) Weyl (1885--1955)} +</pre></example> + +<noindent></noindent> +<para>but only <samp>Weyl</samp> on the contents page. This puts a line break in +the title but that doesn&textrsquo;t work well with running headers so it omits +the break in the contents +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter[Given it all\\ my story]{Given it all\\ my story} +</pre></example> + +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a chapter is 0 +(<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref> and <pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="172"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="173"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<para>The paragraph that follows the chapter title is not indented, as is a +standard typographical practice. To get an indent use the package +<file>indentfirst</file>. +</para> +<para>You can change what is shown for the chapter number. To change it to +something like <samp>Lecture 1</samp>, put in the preamble either +<code>\renewcommand{\chaptername}{Lecture}</code> or this +(<pxref label="_005cmakeatletter-_0026-_005cmakeatother"><xrefnodename>\makeatletter & \makeatother</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makeatletter +\renewcommand{\&arobase;chapapp}{Lecture} +\makeatother +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="174"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="175"><code>babel</code> <r>package</r></indexterm></cindex> + +<noindent></noindent> <para>To make this change because of the primary language for +the document, see the package <file>babel</file>. +</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 <ref label="_005cclearpage-_0026-_005ccleardoublepage"><xrefnodename>\clearpage & \cleardoublepage</xrefnodename></ref>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="176"><r>package</r>, <code>titlesec</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="177"><code>titlesec</code> <r>package</r></indexterm></cindex> + +<para>To change the behavior of the <code>\chapter</code> 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 +<file>titlesec</file>. See its documentation, but the example below gives a +sense of what it can do. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 +</pre></example> + +<noindent></noindent> +<para>This omits the chapter number <samp>Chapter 1</samp> from the page but unlike +<code>\chapter*</code> it keeps the chapter in the table of contents and the +running headers. +</para> + +</section> +<node name="_005csection" spaces=" "><nodename>\section</nodename><nodenext automatic="on">\subsection</nodenext><nodeprev automatic="on">\chapter</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> +<section spaces=" "><sectiontitle><code>\section</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="242" mergedindex="cp">\section</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="178">section</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\section{<var>title</var>} +\section*{<var>title</var>} +\section[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<para>Start a section. The standard &latex; classes <code>article</code>, +<code>book</code>, and <code>report</code> all have this command. +</para> +<para>This produces a section. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<para>For the standard &latex; classes <code>book</code> and <code>report</code> the +default output is like <samp>1.2 <var>title</var></samp> (for chapter 1, +section 2), alone on its line and flush left, in boldface and a +larger type (the type size is <code>\Large</code>). The same holds in +<code>article</code> except that there are no chapters in that class so it +looks like <samp>2 <var>title</var></samp>. +</para> +<para>The <code>*</code> form shows <var>title</var>. +But it does not show the section number, does not increment the +<code>section</code> counter, produces no table of contents entry, and does +not affect the running header. (If you use the page style +<code>headings</code> in a two-sided document then the header will be from the +prior section.) +</para> +<para>The optional argument <var>toc-title</var> will appear as the section title +in the table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>) and in +running headers (<pxref label="Page-styles"><xrefnodename>Page styles</xrefnodename></pxref>). If it is not present then +<var>title</var> will be there. This shows the full name in the title of the +section, +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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.} +</pre></example> + +<noindent></noindent> +<para>but only <samp>Elizabeth II</samp> on the contents page and in the headers. +This has a line break in <var>title</var> but that does not work with headers +so it is omitted from the contents and headers. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\section[Truth is, I cheated; my life story]{Truth is, + I cheated\\my life story} +</pre></example> + +<para>For determining which sectional units are numbered and which appear in +the table of contents, the level number of a section is 1 +(<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref> and <pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="179"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="180"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<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 <file>indentfirst</file>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="181"><r>package</r>, <code>titlesec</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="182"><code>titlesec</code> <r>package</r></indexterm></cindex> + +<para>In general, to change the behavior of the <code>\section</code> command, there +are a number of options. One is the <code>\&arobase;startsection</code> command +(<pxref label="_005c_0040startsection"><xrefnodename>\&arobase;startsection</xrefnodename></pxref>). There are also many packages on CTAN that +address this, including <file>titlesec</file>. See the documentation but the +example below gives a sense of what they can do. +</para> +<!-- c credit: egreg https://groups.google.com/forum/#!topic/comp.text.tex/tvc8oM5P4y4 --> +<example endspaces=" "> +<pre xml:space="preserve">\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] +</pre></example> + +<noindent></noindent> +<para>That puts the section number in the margin. +</para> + +</section> +<node name="_005csubsection" spaces=" "><nodename>\subsection</nodename><nodenext automatic="on">\subsubsection & \paragraph & \subparagraph</nodenext><nodeprev automatic="on">\section</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> +<section spaces=" "><sectiontitle><code>\subsection</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="243" mergedindex="cp">\subsection</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="183">subsection</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\subsection{<var>title</var>} +\subsection*{<var>title</var>} +\subsection[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<para>Start a subsection. The standard &latex; classes <code>article</code>, +<code>book</code>, and <code>report</code> all have this command. +</para> +<para>This produces a subsection. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<para>For the standard &latex; classes <code>book</code> and <code>report</code> the +default output is like <samp>1.2.3 <var>title</var></samp> (for chapter 1, +section 2, subsection 3), alone on its line and flush left, in +boldface and a larger type (the type size is <code>\large</code>). The same +holds in <code>article</code> except that there are no chapters in that class +so it looks like <samp>2.3 <var>title</var></samp>. +</para> +<para>The <code>*</code> form shows <var>title</var>. +But it does not show the section number, does not increment the +<code>section</code> counter, and produces no table of contents entry. +</para> +<para>The optional argument <var>toc-title</var> will appear as the section title +in the table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>). If it is +not present then <var>title</var> will be there. This shows the full name in +the title of the section, +</para> +<example endspaces=" "> +<pre xml:space="preserve">\subsection[$\alpha,\beta,\gamma$ paper]{\textit{The Origin of + Chemical Elements} by R.A.~Alpher, H.~Bethe, and G.~Gamow} +</pre></example> + +<noindent></noindent> +<para>but only <samp><U>03B1</U>,<U>03B2</U>,<U>03B3</U> +paper</samp> 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 +(<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref> and <pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="184"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="185"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<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 <file>indentfirst</file>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="186"><r>package</r>, <code>titlesec</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="187"><code>titlesec</code> <r>package</r></indexterm></cindex> + +<para>There are a number of ways to change the behavior of the +<code>\subsection</code> command. One is the <code>\&arobase;startsection</code> command +(<pxref label="_005c_0040startsection"><xrefnodename>\&arobase;startsection</xrefnodename></pxref>). There are also many packages on CTAN that +address this, including <file>titlesec</file>. See the documentation but the +example below gives a sense of what they can do. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 +</pre></example> + +<noindent></noindent> +<para>That puts the subsection number and <var>title</var> in the first line of +text. +</para> + +</section> +<node name="_005csubsubsection-_0026-_005cparagraph-_0026-_005csubparagraph" spaces=" "><nodename>\subsubsection & \paragraph & \subparagraph</nodename><nodenext automatic="on">\appendix</nodenext><nodeprev automatic="on">\subsection</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> + +<section spaces=" "><sectiontitle><code>\subsubsection</code>, <code>\paragraph</code>, <code>\subparagraph</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="244" mergedindex="cp">\subsubsection</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="188">subsubsection</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="245" mergedindex="cp">\paragraph</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="189">paragraph</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="246" mergedindex="cp">\subparagraph</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="190">subparagraph</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\subsubsection{<var>title</var>} +\subsubsection*{<var>title</var>} +\subsubsection[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<noindent></noindent> +<para>or one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\paragraph{<var>title</var>} +\paragraph*{<var>title</var>} +\paragraph[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<noindent></noindent> +<para>or one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\subparagraph{<var>title</var>} +\subparagraph*{<var>title</var>} +\subparagraph[<var>toc-title</var>]{<var>title</var>} +</pre></example> + +<para>Start a subsubsection, paragraph, or subparagraph. The standard +&latex; classes <code>article</code>, <code>book</code>, and <code>report</code> all have +these commands, although they are not commonly used. +</para> +<para>This produces a subsubsection. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<para>The default output of each of the three does not change over the +standard &latex; classes <code>article</code>, <code>book</code>, and +<code>report</code>. For <code>\subsubsection</code> the <var>title</var> is alone on +its line, in boldface and normal size type. For <code>\paragraph</code> the +<var>title</var> is inline with the text, not indented, in boldface and +normal size type. For <code>\subparagraph</code> the <var>title</var> is inline +with the text, with a paragraph indent, in boldface and normal size type +(Because an <code>article</code> has no chapters its subsubsections are +numbered and so it looks like <samp>1.2.3 <var>title</var></samp>, for +section 1, subsection 2, and subsubsection 3. The other +two divisions are not numbered.) +</para> +<para>The <code>*</code> form shows <var>title</var>. But it does not increment the +associated counter and produces no table of contents entry (and does not +show the number for <code>\subsubsection</code>). +</para> +<para>The optional argument <var>toc-title</var> will appear as the division title +in the table of contents (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>). If it is +not present then <var>title</var> 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 +(<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref> and <pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="191"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="192"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<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 <file>indentfirst</file>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="193"><r>package</r>, <code>titlesec</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="194"><code>titlesec</code> <r>package</r></indexterm></cindex> + +<para>There are a number of ways to change the behavior of the these commands. +One is the <code>\&arobase;startsection</code> command (<pxref label="_005c_0040startsection"><xrefnodename>\&arobase;startsection</xrefnodename></pxref>). +There are also many packages on CTAN that address this, including +<file>titlesec</file>. See the documentation on CTAN. +</para> + +</section> +<node name="_005cappendix" spaces=" "><nodename>\appendix</nodename><nodenext automatic="on">\frontmatter & \mainmatter & \backmatter</nodenext><nodeprev automatic="on">\subsubsection & \paragraph & \subparagraph</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> + +<section spaces=" "><sectiontitle><code>\appendix</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="247" mergedindex="cp">\appendix</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="195">appendix</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="196">appendices</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\appendix +</pre></example> + +<para>This does not directly produce any output. But in a book or report it +declares that subsequent <code>\chapter</code> commands start an appendix. In +an article it does the same, for <code>\section</code> commands. It also +resets the <code>chapter</code> and <code>section</code> counters to 0 in a +book or report, and in an article resets the <code>section</code> and +<code>subsection</code> counters. +</para> +<para>In this book +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter{One} ... +\chapter{Two} ... + ... +\appendix +\chapter{Three} ... +\chapter{Four} ... +</pre></example> + +<noindent></noindent> +<para>the first two will generate output numbered <samp>Chapter 1</samp> and +<samp>Chapter 2</samp>. After the <code>\appendix</code> the numbering will be +<samp>Appendix A</samp> and <samp>Appendix B</samp>. <xref label="Larger-book-template"><xrefnodename>Larger book template</xrefnodename></xref> +for another example. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="197"><r>package</r>, <code>appendix</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="198"><code>appendix</code> <r>package</r></indexterm></cindex> + <para>The <file>appendix</file> package adds the command +<code>\appendixpage</code> to put a separate <samp>Appendices</samp> in the document +body before the first appendix, and the command <code>\addappheadtotoc</code> +to do the same in the table of contents. You can reset the name +<samp>Appendix</samp> with a command like +<code>\renewcommand{\appendixname}{Specification}</code>, as well as a +number of other features. See the documentation on CTAN. +</para> + +</section> +<node name="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter" spaces=" "><nodename>\frontmatter & \mainmatter & \backmatter</nodename><nodenext automatic="on">\&arobase;startsection</nodenext><nodeprev automatic="on">\appendix</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> + +<section spaces=" "><sectiontitle><code>\frontmatter</code>, <code>\mainmatter</code>, <code>\backmatter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="248" mergedindex="cp">\frontmatter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="199">book, front matter</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="249" mergedindex="cp">\mainmatter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="200">book, main matter</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="250" mergedindex="cp">\backmatter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="201">book, back matter</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="202">book, end matter</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\frontmatter +\mainmatter +\backmatter +</pre></example> + +<para>Format a <code>book</code> class document differently according to which part +of the document is being produced. All three commands are optional. +</para> +<para>Traditionally, a book&textrsquo;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 <code>\frontmatter</code> declaration makes the pages numbered in +lowercase roman, and makes chapters not numbered, although each +chapter&textrsquo;s title appears in the table of contents; if you use other +sectioning commands here, use the <code>*</code>-version (<pxref label="Sectioning"><xrefnodename>Sectioning</xrefnodename></pxref>). +The <code>\mainmatter</code> changes the behavior back to the expected +version, and resets the page number. The <code>\backmatter</code> leaves the +page numbering alone but switches the chapters back to being not +numbered. <xref label="Larger-book-template"><xrefnodename>Larger book template</xrefnodename></xref> for an example using the three. +</para> + +</section> +<node name="_005c_0040startsection" spaces=" "><nodename>\&arobase;startsection</nodename><nodeprev automatic="on">\frontmatter & \mainmatter & \backmatter</nodeprev><nodeup automatic="on">Sectioning</nodeup></node> +<section spaces=" "><sectiontitle><code>\&arobase;startsection</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="251" mergedindex="cp">\&arobase;startsection</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="203">section, redefining</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\&arobase;startsection{<var>name</var>}{<var>level</var>}{<var>indent</var>}{<var>beforeskip</var>}{<var>afterskip</var>}{<var>style</var>} +</pre></example> + +<para>Used to help redefine the behavior of commands that start sectioning +divisions such as <code>\section</code> or <code>\subsection</code>. +</para> +<para>Note that the <file>titlesec</file> package makes manipulation of sectioning +easier. Further, while most requirements for sectioning commands can be +satisfied with <code>\&arobase;startsection</code>, some cannot. For instance, in +the standard &latex; <code>book</code> and <code>report</code> classes the commands +<code>\chapter</code> and <code>\report</code> are not constructed in this way. To +make such a command you may want to use the <code>\secdef</code> command. +<!-- c xx define, and make a cross reference to, secdef. --> +</para> +<para>Technically, <code>\&arobase;startsection</code> has the form +</para> +<example endspaces=" "> +<pre xml:space="preserve">\&arobase;startsection{<var>name</var>} + {<var>level</var>} + {<var>indent</var>} + {<var>beforeskip</var>} + {<var>afterskip</var>} + {<var>style</var>}*[<var>toctitle</var>]{<var>title</var>} +</pre></example> + +<noindent></noindent> +<para>so that issuing +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\section}{\&arobase;startsection{<var>name</var>} + {<var>level</var>} + {<var>indent</var>} + {<var>beforeskip</var>} + {<var>afterskip</var>} + {<var>style</var>}} +</pre></example> + +<noindent></noindent> +<para>redefines <code>\section</code> to have the form +<code>\section*[<var>toctitle</var>]{<var>title</var>}</code> (here too, the +star <code>*</code> is optional). <xref label="Sectioning"><xrefnodename>Sectioning</xrefnodename></xref>. This implies that +when you write a command like <code>\renewcommand{section}{...}</code>, +the <code>\&arobase;startsection{...}</code> must come last in the definition. See +the examples below. +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<beforefirstitem> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="var">name</itemformat></item> +</tableterm><tableitem><anchor name="startsection-name">startsection name</anchor> +<anchor name="_005c_0040startsection_002fname">\&arobase;startsection/name</anchor> +<para>Name of the counter used to number the sectioning header. This counter +must be defined separately. Most commonly this is either +<code>section</code>, <code>subsection</code>, or <code>paragraph</code>. Although in +those cases the counter name is the same as the sectioning command +itself, you don&textrsquo;t have to use the same name. +</para> +<para>Then <code>\the</code><var>name</var> displays the title number and +<code>\</code><var>name</var><code>mark</code> is for the page headers. See the third +example below. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">level</itemformat></item> +</tableterm><tableitem><anchor name="startsection-level">startsection level</anchor> +<anchor name="_005c_0040startsection_002flevel">\&arobase;startsection/level</anchor> +<para>An integer giving the depth of the sectioning command. +<xref label="Sectioning"><xrefnodename>Sectioning</xrefnodename></xref> for the list of standard level numbers. +</para> +<para>If <var>level</var> is less than or equal to the value of the counter +<code>secnumdepth</code> then titles for this sectioning command will be +numbered (<pxref label="Sectioning_002fsecnumdepth"><xrefnodename>Sectioning/secnumdepth</xrefnodename></pxref>). For instance, if +<code>secnumdepth</code> is 1 in an <code>article</code> then the command +<code>\section{Introduction}</code> will produce output like &textldquo;1 +Introduction&textrdquo; while <code>\subsection{Discussion}</code> will produce +output like &textldquo;Discussion&textrdquo;, without the number prefix. +</para> +<para>If <var>level</var> is less than or equal to the value of the counter +<var>tocdepth</var> then the table of contents will have an entry for this +sectioning unit (<pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>). For instance, in an +<code>article</code>, if <var>tocdepth</var> is 1 then the table of contents will +list sections but not subsections. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">indent</itemformat></item> +</tableterm><tableitem><anchor name="startsection-indent">startsection indent</anchor> +<anchor name="_005c_0040startsection_002findent">\&arobase;startsection/indent</anchor> +<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 +<code>0pt</code>. A negative indentation such as <code>-\parindent</code> will move +the title into the left margin. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">beforeskip</itemformat></item> +</tableterm><tableitem><anchor name="startsection-beforeskip">startsection beforeskip</anchor> +<anchor name="_005c_0040startsection_002fbeforeskip">\&arobase;startsection/beforeskip</anchor> +<para>The absolute value of this length is the amount of vertical space that +is inserted before this sectioning unit&textrsquo;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 <code>1pt plus 2pt minus 3pt</code> +is <code>-1pt plus -2pt minus -3pt</code>.) +</para> +<para>For example, if <var>beforeskip</var> is <code>-3.5ex plus -1ex minus -0.2ex</code> +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 +<code>plus</code> and <code>minus</code>, is good practice here since it gives +&latex; more flexibility in making up the page (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>The full accounting of the vertical space between the baseline of the +line prior to this sectioning unit&textrsquo;s header and the baseline of the +header is that it is the sum of the <code>\parskip</code> of the text font, +the <code>\baselineskip</code> of the title font, and the absolute value of +the <var>beforeskip</var>. 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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">afterskip</itemformat></item> +</tableterm><tableitem><anchor name="startsection-afterskip">startsection afterskip</anchor> +<anchor name="_005c_0040startsection_002fafterskip">\&arobase;startsection/afterskip</anchor> +<para>This is a length. If <var>afterskip</var> is non-negative then this is the +vertical space inserted after the sectioning unit&textrsquo;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 +<code>1pt plus 2pt minus 3pt</code> is <code>-1pt plus -2pt minus -3pt</code>.) +</para> +<para>As with <var>beforeskip</var>, using a rubber length, with <code>plus</code> and +<code>minus</code> components, is good practice here since it gives &latex; +more flexibility in putting together the page. +</para> +<para>If <code>afterskip</code> is non-negative then the full accounting of the +vertical space between the baseline of the sectioning unit&textrsquo;s header and +the baseline of the first line of the following paragraph is that it is +the sum of the <code>\parskip</code> of the title font, the +<code>\baselineskip</code> of the text font, and the value of <var>after</var>. +That space is typically rubber so it may stretch or shrink. (Note that +because the sign of <code>afterskip</code> changes the sectioning unit +header&textrsquo;s from standalone to run-in, you cannot use a negative +<code>afterskip</code> to cancel part of the <code>\parskip</code>.) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">style</itemformat></item> +</tableterm><tableitem><anchor name="startsection-style">startsection style</anchor> +<anchor name="_005c_0040startsection_002fstyle">\&arobase;startsection/style</anchor> +<para>Controls the styling of the title. See the examples below. Typical +commands to use here are <code>\centering</code>, <code>\raggedright</code>, +<code>\normalfont</code>, <code>\hrule</code>, or <code>\newpage</code>. The last command +in <var>style</var> may be one that takes one argument, such as +<code>\MakeUppercase</code> or <code>\fbox</code> that takes one argument. The +section title will be supplied as the argument to this command. For +instance, setting <var>style</var> to <code>\bfseries\MakeUppercase</code> would +produce titles that are bold and uppercase. +</para></tableitem></tableentry></table> + +<para>These are &latex;&textrsquo;s defaults for the first three sectioning units that +are defined with <code>\&arobase;startsection</code>, for the <file>article</file>, +<file>book</file>, and <file>report</file> classes. For section, the <var>level</var> is +1, the <var>indent</var> is 0<dmn>pt</dmn>, the <var>beforeskip</var> is <code>-3.5ex +plus -1ex minus -0.2ex</code>, the <var>afterskip</var> is <code>2.3ex plus 0.2ex</code>, +and the <var>style</var> is <code>\normalfont\Large\bfseries</code>. For +subsection, the <var>level</var> is 2, the <var>indent</var> is 0<dmn>pt</dmn>, the +<var>beforeskip</var> is <code>-3.25ex plus -1ex minus -0.2ex</code>, the +<var>afterskip</var> is <code>1.5ex plus 0.2ex</code>, and the <var>style</var> is +<code>\normalfont\large\bfseries</code>. For subsubsection, the <var>level</var> +is 3, the <var>indent</var> is 0<dmn>pt</dmn>, the <var>beforeskip</var> is +<code>-3.25ex plus -1ex minus -0.2ex</code>, the <var>afterskip</var> is +<code>1.5ex plus 0.2ex</code>, and the <var>style</var> is +<code>\normalfont\normalsize\bfseries</code>. +</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 <code>\makeatletter</code> command and a +<code>\makeatother</code>. (Probably the error message <code>You can't use +`\spacefactor' in vertical mode.</code> means that you forgot this.) +<xref label="_005cmakeatletter-_0026-_005cmakeatother"><xrefnodename>\makeatletter & \makeatother</xrefnodename></xref>. +</para> +<para>This will put section titles in large boldface type, centered. It says +<code>\renewcommand</code> because &latex;&textrsquo;s standard classes have already +defined a <code>\section</code>. For the same reason it does not define a +<code>section</code> counter, or the commands <code>\thesection</code> and +<code>\l&arobase;section</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand\section{% + \&arobase;startsection{section}% <ref label="_005c_0040startsection_002fname"><xrefnodename>\&arobase;startsection/name</xrefnodename><xrefinfoname><var>name</var></xrefinfoname><xrefprinteddesc><var>name</var></xrefprinteddesc></ref> + {1}% <ref label="_005c_0040startsection_002flevel"><xrefnodename>\&arobase;startsection/level</xrefnodename><xrefinfoname><var>level</var></xrefinfoname><xrefprinteddesc><var>level</var></xrefprinteddesc></ref> + {0pt}% <ref label="_005c_0040startsection_002findent"><xrefnodename>\&arobase;startsection/indent</xrefnodename><xrefinfoname><var>indent</var></xrefinfoname><xrefprinteddesc><var>indent</var></xrefprinteddesc></ref> + {-3.5ex plus -1ex minus -.2ex}% <ref label="_005c_0040startsection_002fbeforeskip"><xrefnodename>\&arobase;startsection/beforeskip</xrefnodename><xrefinfoname><var>beforeskip</var></xrefinfoname><xrefprinteddesc><var>beforeskip</var></xrefprinteddesc></ref> + {2.3ex plus.2ex}% <ref label="_005c_0040startsection_002fafterskip"><xrefnodename>\&arobase;startsection/afterskip</xrefnodename><xrefinfoname><var>afterskip</var></xrefinfoname><xrefprinteddesc><var>afterskip</var></xrefprinteddesc></ref> + {\centering\normalfont\Large\bfseries}% <ref label="_005c_0040startsection_002fstyle"><xrefnodename>\&arobase;startsection/style</xrefnodename><xrefinfoname><var>style</var></xrefinfoname><xrefprinteddesc><var>style</var></xrefprinteddesc></ref> + } +</pre></example> + +<para>This will put <code>subsection</code> titles in small caps type, inline with the paragraph. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand\subsection{% + \&arobase;startsection{subsection}% <ref label="_005c_0040startsection_002fname"><xrefnodename>\&arobase;startsection/name</xrefnodename><xrefinfoname><var>name</var></xrefinfoname><xrefprinteddesc><var>name</var></xrefprinteddesc></ref> + {2}% <ref label="_005c_0040startsection_002flevel"><xrefnodename>\&arobase;startsection/level</xrefnodename><xrefinfoname><var>level</var></xrefinfoname><xrefprinteddesc><var>level</var></xrefprinteddesc></ref> + {0em}% <ref label="_005c_0040startsection_002findent"><xrefnodename>\&arobase;startsection/indent</xrefnodename><xrefinfoname><var>indent</var></xrefinfoname><xrefprinteddesc><var>indent</var></xrefprinteddesc></ref> + {-1ex plus 0.1ex minus -0.05ex}% <ref label="_005c_0040startsection_002fbeforeskip"><xrefnodename>\&arobase;startsection/beforeskip</xrefnodename><xrefinfoname><var>beforeskip</var></xrefinfoname><xrefprinteddesc><var>beforeskip</var></xrefprinteddesc></ref> + {-1em plus 0.2em}% <ref label="_005c_0040startsection_002fafterskip"><xrefnodename>\&arobase;startsection/afterskip</xrefnodename><xrefinfoname><var>afterskip</var></xrefinfoname><xrefprinteddesc><var>afterskip</var></xrefprinteddesc></ref> + {\scshape}% <ref label="_005c_0040startsection_002fstyle"><xrefnodename>\&arobase;startsection/style</xrefnodename><xrefinfoname><var>style</var></xrefinfoname><xrefprinteddesc><var>style</var></xrefprinteddesc></ref> + } +</pre></example> + +<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> +<!-- c From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ --> +<example endspaces=" "> +<pre xml:space="preserve">\setcounter{secnumdepth}{6}% show counters this far down +\newcounter{subsubparagraph}[subparagraph]% counter for numbering +\renewcommand{\thesubsubparagraph}% how to display + {\thesubparagraph.\&arobase;arabic\c&arobase;subsubparagraph}% numbering +\newcommand{\subsubparagraph}{\&arobase;startsection + {subsubparagraph}% + {6}% + {0em}% + {\baselineskip}% + {0.5\baselineskip}% + {\normalfont\normalsize}} +\newcommand*\l&arobase;subsubparagraph{\&arobase;dottedtocline{6}{10em}{5em}}% for toc +\newcommand{\subsubparagraphmark}[1]{}% for page headers +</pre></example> + + +</section> +</chapter> +<node name="Cross-references" spaces=" "><nodename>Cross references</nodename><nodenext automatic="on">Environments</nodenext><nodeprev automatic="on">Sectioning</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Cross references</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="204">cross references</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="205">label</indexterm></cindex> +<para>We often want something like <samp>See Theorem~31</samp>. But by-hand typing +the 31 is poor practice. Instead you should write a <dfn>label</dfn> such as +<code>\label{eq:GreensThm}</code> and then <dfn>reference</dfn> it, as with +<code>See equation~\ref{eq:GreensThm}</code>. &latex; will automatically +work out the number, put it into the output, and will change that number +later if needed. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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}. +</pre></example> + +<para>&latex; tracks cross reference information in a file having the +extension <file>.aux</file> and with the same base name as the file containing +the <code>\label</code>. So if <code>\label</code> is in <file>calculus.tex</file> then +the information is in <file>calculus.aux</file>. &latex; puts the +information in that file every time it runs across a <code>\label</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="206">forward reference</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="207">reference, forward</indexterm></cindex> +<para>The behavior described in the prior paragraph results in a quirk that +happens when your document has a <dfn>forward reference</dfn>, a <code>\ref</code> +that appears before the associated <code>\label</code>. If this is the first +time that you are compiling the document then you will get <samp>LaTeX +Warning: Label(s) may have changed. Rerun to get cross references right</samp> +and in the output the forward reference will appear as two question +marks <samp>??</samp>, 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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="208"><r>package</r>, <code>cleveref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="209"><code>cleveref</code> <r>package</r></indexterm></cindex> + <para>The <code>cleveref</code> package enhances &latex;&textrsquo;s +cross referencing features. You can arrange that if you enter +<code>\begin{thm}\label{th:Nerode}...\end{thm}</code> then +<code>\cref{th:Nerode}</code> will output <samp>Theorem 3.21</samp>, without you +having to enter the &textldquo;Theorem.&textrdquo; +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\label</menunode><menudescription><pre xml:space="preserve">Assign a symbolic name to a piece of text. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\pageref</menunode><menudescription><pre xml:space="preserve">Refer to a page number. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\ref</menunode><menudescription><pre xml:space="preserve">Refer to a section, figure or similar. +</pre></menudescription></menuentry></menu> + + +<node name="_005clabel" spaces=" "><nodename>\label</nodename><nodenext automatic="on">\pageref</nodenext><nodeup automatic="on">Cross references</nodeup></node> +<section spaces=" "><sectiontitle><code>\label</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="252" mergedindex="cp">\label</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\label{<var>key</var>} +</pre></example> + +<para>Assign a reference number to <var>key</var>. In ordinary text +<code>\label{<var>key</var>}</code> assigns to <var>key</var> the number of the +current sectional unit. Inside an environment with numbering, such as a +<code>table</code> or <code>theorem</code> environment, <code>\label{<var>key</var>}</code> +assigns to <var>key</var> the number of that environment. Retrieve the +assigned number with the <code>\ref{<var>key</var>}</code> command +(<pxref label="_005cref"><xrefnodename>\ref</xrefnodename></pxref>). +</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, <code>\label{fig:Post}</code> 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> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">ch</itemformat></item> +</tableterm><tableitem><para>for chapters +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">sec</itemformat></item> +<itemx spaces=" "><itemformat command="code">subsec</itemformat></itemx> +</tableterm><tableitem><para>for lower-level sectioning commands +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">fig</itemformat></item> +</tableterm><tableitem><para>for figures +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">tab</itemformat></item> +</tableterm><tableitem><para>for tables +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">eq</itemformat></item> +</tableterm><tableitem><para>for equations +</para></tableitem></tableentry></table> + +<para>In the auxiliary file the reference information is kept as the text of +a command of the form +<code>\newlabel{<var>label</var>}{{<var>currentlabel</var>}{<var>pagenumber</var>}}</code>. +Here <var>currentlabel</var> is the current value of the macro +<code>\&arobase;currentlabel</code> that is usually updated whenever you call +<code>\refstepcounter{<var>counter</var>}</code>. +</para> +<para>Below, the key <code>sec:test</code> will get the number of the current +section and the key <code>fig:test</code> will get the number of the figure. +(Incidentally, put labels after captions in figures and tables.) +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}. +</pre></example> + + +</section> +<node name="_005cpageref" spaces=" "><nodename>\pageref</nodename><nodenext automatic="on">\ref</nodenext><nodeprev automatic="on">\label</nodeprev><nodeup automatic="on">Cross references</nodeup></node> +<section spaces=" "><sectiontitle><code>\pageref</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="253" mergedindex="cp">\pageref</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="210">cross referencing with page number</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="211">page number, cross referencing</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\pageref{<var>key</var>} +</pre></example> + +<para>Produce the page number of the place in the text where the corresponding +<code>\label</code>{<var>key</var>} command appears. +</para> +<para>If there is no <code>\label{<var>key</var>}</code> then you get something like +<samp>LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.</samp> +</para> +<para>Below, the <code>\label{eq:main}</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">The main result is formula~\ref{eq:main} on page~\pageref{eq:main}. + ... +\begin{equation} \label{eq:main} + \mathbf{P}=\mathbf{NP} +\end{equation} +</pre></example> + + +</section> +<node name="_005cref" spaces=" "><nodename>\ref</nodename><nodeprev automatic="on">\pageref</nodeprev><nodeup automatic="on">Cross references</nodeup></node> +<section spaces=" "><sectiontitle><code>\ref</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="254" mergedindex="cp">\ref</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="212">cross referencing, symbolic</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="213">section number, cross referencing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="214">equation number, cross referencing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="215">figure number, cross referencing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="216">footnote number, cross referencing</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ref{<var>key</var>} +</pre></example> + +<para>Produces the number of the sectional unit, +equation, footnote, figure, &dots;, of the corresponding +<code>\label</code> command (<pxref label="_005clabel"><xrefnodename>\label</xrefnodename></pxref>). It does not produce any text, +such as the word &textlsquo;Section&textrsquo; or &textlsquo;Figure&textrsquo;, just the bare number itself. +</para> +<para>If there is no <code>\label{<var>key</var>}</code> then you get something like +<samp>LaTeX Warning: Reference `th:GrensThm' on page 1 undefined on +input line 11.</samp> +</para> +<para>In this example the <code>\ref{popular}</code> produces <samp>2</samp>. Note that +it is a forward reference since it comes before <code>\label{popular}</code> +so this document would have to be compiled twice. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="217"><r>package</r>, <code>cleveref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="218"><code>cleveref</code> <r>package</r></indexterm></cindex> + +<para>The <file>cleveref</file> package includes text such as <samp>Theorem</samp> in the +reference. See the documentation on CTAN. +</para> + +</section> +</chapter> +<node name="Environments" spaces=" "><nodename>Environments</nodename><nodenext automatic="on">Line breaking</nodenext><nodeprev automatic="on">Cross references</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Environments</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="219">environments</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="255" mergedindex="cp">\begin</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="256" mergedindex="cp">\end</indexterm></findex> + +<para>&latex; provides many environments for delimiting certain behavior. +An environment begins with <code>\begin</code> and ends with <code>\end</code>, +like this: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{<var>environment-name</var>} + ... +\end{<var>environment-name</var>} +</pre></example> + +<para>The <var>environment-name</var> at the beginning must exactly match that at +the end. For instance, the input +<code>\begin{table*}...\end{table}</code> will cause an error like: +<samp>! LaTeX Error: \begin{table*} on input line 5 ended by +\end{table}.</samp> +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="220">group, and environments</indexterm></cindex> +<para>Environments are executed within a group. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">abstract</menunode><menudescription><pre xml:space="preserve">Produce an abstract. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">array</menunode><menudescription><pre xml:space="preserve">Math arrays. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">center</menunode><menudescription><pre xml:space="preserve">Centered lines. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">description</menunode><menudescription><pre xml:space="preserve">Labelled lists. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">displaymath</menunode><menudescription><pre xml:space="preserve">Formulas that appear on their own line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">document</menunode><menudescription><pre xml:space="preserve">Enclose the whole document. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">enumerate</menunode><menudescription><pre xml:space="preserve">Numbered lists. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">eqnarray</menunode><menudescription><pre xml:space="preserve">Sequences of aligned equations. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">equation</menunode><menudescription><pre xml:space="preserve">Displayed equation. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">figure</menunode><menudescription><pre xml:space="preserve">Floating figures. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">filecontents</menunode><menudescription><pre xml:space="preserve">Writing multiple files from the source. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">flushleft</menunode><menudescription><pre xml:space="preserve">Flushed left lines. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">flushright</menunode><menudescription><pre xml:space="preserve">Flushed right lines. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">itemize</menunode><menudescription><pre xml:space="preserve">Bulleted lists. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">letter</menunode><menudescription><pre xml:space="preserve">Letters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">list</menunode><menudescription><pre xml:space="preserve">Generic list environment. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">math</menunode><menudescription><pre xml:space="preserve">In-line math. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">minipage</menunode><menudescription><pre xml:space="preserve">Miniature page. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">picture</menunode><menudescription><pre xml:space="preserve">Picture with text, arrows, lines and circles. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">quotation & quote</menunode><menudescription><pre xml:space="preserve">Include a quotation. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">tabbing</menunode><menudescription><pre xml:space="preserve">Align text arbitrarily. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">table</menunode><menudescription><pre xml:space="preserve">Floating tables. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">tabular</menunode><menudescription><pre xml:space="preserve">Align text in columns. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">thebibliography</menunode><menudescription><pre xml:space="preserve">Bibliography or reference list. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">theorem</menunode><menudescription><pre xml:space="preserve">Theorems, lemmas, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">titlepage</menunode><menudescription><pre xml:space="preserve">For hand crafted title pages. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">verbatim</menunode><menudescription><pre xml:space="preserve">Simulating typed input. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">verse</menunode><menudescription><pre xml:space="preserve">For poetry and other things. +</pre></menudescription></menuentry></menu> + + +<node name="abstract" spaces=" "><nodename>abstract</nodename><nodenext automatic="on">array</nodenext><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>abstract</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="257" mergedindex="cp"><r>environment</r>, <code>abstract</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="258" mergedindex="cp"><code>abstract</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="221">abstracts</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{abstract} +... +\end{abstract} +</pre></example> + +<para>Produce an abstract, possibly of multiple paragraphs. This environment +is only defined in the <code>article</code> and <code>report</code> document classes +(<pxref label="Document-classes"><xrefnodename>Document classes</xrefnodename></pxref>). +</para> +<para>Using the example below in the <code>article</code> class produces a displayed +paragraph. Document class option <code>titlepage</code> causes the abstract +to be on a separate page (<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>); this is the +default only in the <code>report</code> class. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>The next example produces a one column abstract in a two column document (for +a more flexible solution, use the package <file>abstract</file>). +</para> +<!-- c Adopted from http://www.tex.ac.uk/FAQ-onecolabs.html --> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass[twocolumn]{article} + ... +\begin{document} +\title{Babe Ruth as Cultural Progenitor: a Atavistic Approach} +\author{Smith \\ Jones \\ Robinson\thanks{Railroad tracking grant.}} +\twocolumn[ + \begin{&arobase;twocolumnfalse} + \maketitle + \begin{abstract} + Ruth was not just the Sultan of Swat, he was the entire swat + team. + \end{abstract} + \end{&arobase;twocolumnfalse} + ] +{ % by-hand insert a footnote at page bottom + \renewcommand{\thefootnote}{\fnsymbol{footnote}} + \footnotetext[1]{Thanks for all the fish.} +} +</pre></example> + + +</section> +<node name="array" spaces=" "><nodename>array</nodename><nodenext automatic="on">center</nodenext><nodeprev automatic="on">abstract</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>array</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="259" mergedindex="cp"><r>environment</r>, <code>array</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="260" mergedindex="cp"><code>array</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="222">arrays, math</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{array}{<var>cols</var>} + <var>column 1 entry</var> &<var>column 2 entry</var> ... &<var>column n entry</var> \\ + ... +\end{array} +</pre></example> + +<noindent></noindent> +<para>or: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{array}[<var>pos</var>]{<var>cols</var>} + <var>column 1 entry</var> &<var>column 2 entry</var> ... &<var>column n entry</var> \\ + ... +\end{array} +</pre></example> + +<para>Produce a mathematical array. This environment can only be used in math +mode, and normally appears within a displayed mathematics environment +such as <code>equation</code> (<pxref label="equation"><xrefnodename>equation</xrefnodename></pxref>). Inside of each row the +column entries are separated by an ampersand, (<code>&</code>). Rows are +terminated with double-backslashes (<pxref label="_005c_005c"><xrefnodename>\\</xrefnodename></pxref>). +</para> +<para>This example shows a three by three array. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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*} +</pre></example> + +<para>The required argument <var>cols</var> describes the number of columns, their +alignment, and the formatting of the intercolumn regions. For instance, +<code>\begin{array}{rcl}...\end{array}</code> gives three columns: the +first flush right, the second centered, and the third flush left. See +<ref label="tabular"><xrefnodename>tabular</xrefnodename></ref> for the complete description of <var>cols</var> and of the +other common features of the two environments, including the optional +<var>pos</var> argument. +</para> +<para>There are two ways that <code>array</code> diverges from <code>tabular</code>. The +first is that <code>array</code> entries are typeset in math mode, in +textstyle (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>) except if the <var>cols</var> definition specifies +the column with <code>p{...}</code>, which causes the entry to be typeset in +text mode. The second is that, instead of <code>tabular</code>&textrsquo;s parameter +<code>\tabcolsep</code>, &latex;&textrsquo;s intercolumn space in an <code>array</code> is +governed by +<findex index="fn" spaces=" "><indexterm index="fn" number="261" mergedindex="cp">\arraycolsep</indexterm></findex> +<code>\arraycolsep</code>, which gives half the width between columns. The +default for this is <samp>5pt</samp> so that between two columns comes +10<dmn>pt</dmn> of space. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="223"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="224"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>To obtain arrays with braces the standard is to use the <file>amsmath</file> +package. It comes with environments <code>pmatrix</code> for an array +surrounded by parentheses <code>(...)</code>, <code>bmatrix</code> for an array +surrounded by square brackets <code>[...]</code>, <code>Bmatrix</code> for an +array surrounded by curly braces <code>{...}</code>, <code>vmatrix</code> for +an array surrounded by vertical bars <code>|...|</code>, and +<code>Vmatrix</code> for an array surrounded by double vertical +bars <code>||...||</code>, along with a number of other array constructs. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="225"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="226"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>The next example uses the <file>amsmath</file> package. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{amsmath} % in preamble + +\begin{equation} + \begin{vmatrix}{cc} % array with vert lines + a &b \\ + c &d + \end{vmatrix}=ad-bc +\end{equation} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="227"><r>package</r>, <code>array (package)</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="228"><code>array (package)</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="229"><r>package</r>, <code>dcolumn</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="230"><code>dcolumn</code> <r>package</r></indexterm></cindex> + +<para>There are many packages concerning arrays. The <file>array</file> package has +many useful extensions, including more column types. The <file>dcolumn</file> +package adds a column type to center on a decimal point. For both see +the documentation on CTAN. +</para> + +</section> +<node name="center" spaces=" "><nodename>center</nodename><nodenext automatic="on">description</nodenext><nodeprev automatic="on">array</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>center</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="262" mergedindex="cp"><r>environment</r>, <code>center</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="263" mergedindex="cp"><code>center</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="231">centering text, environment for</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + <var>line1</var> \\ + <var>line2</var> \\ + ... +\end{center} +</pre></example> + +<para>Create a new paragraph consisting of a sequence of lines that are +centered within the left and right margins. Use +double-backslash, <code>\\</code>, to get a line break (<pxref label="_005c_005c"><xrefnodename>\\</xrefnodename></pxref>). +<findex index="fn" spaces=" "><indexterm index="fn" number="264" mergedindex="cp">\\ <r>(for <code>center</code>)</r></indexterm></findex> +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 +<ref label="_005ccentering"><xrefnodename>\centering</xrefnodename></ref> to avoid such space, for example inside a <code>figure</code> +environment. +</para> +<para>This example produces three centered lines. There is extra vertical +space between the last two lines. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + A Thesis Submitted in Partial Fufillment \\ + of the Requirements of \\[0.5ex] + the School of Environmental Engineering +\end{center} +</pre></example> + +<para>In this example, depending on the page&textrsquo;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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>A double backslash after the final line is optional. If present it +doesn&textrsquo;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> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\centering</menunode><menudescription><pre xml:space="preserve">Declaration form of the <code>center</code> environment. +</pre></menudescription></menuentry></menu> + + +<node name="_005ccentering" spaces=" "><nodename>\centering</nodename><nodeup automatic="on">center</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\centering</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="265" mergedindex="cp">\centering</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="232">centering text, declaration for</indexterm></cindex> + + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">{\centering ... } +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{group} + \centering ... +\end{group} +</pre></example> + +<para>Center the material in its scope. It is most often used inside an +environment such as <code>figure</code>, or in a <code>parbox</code>. +</para> +<para>This example&textrsquo;s <code>\centering</code> declaration causes the graphic to be +horizontally centered. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{figure} + \centering + \includegraphics[width=0.6\textwidth]{ctan_lion.png} + \caption{CTAN Lion} \label{fig:CTANLion} +\end{figure} +</pre></example> + +<noindent></noindent> +<para>The scope of this <code>\centering</code> ends with the <code>\end{figure}</code>. +</para> +<para>Unlike the <code>center</code> environment, the <code>\centering</code> command does +not add vertical space above and below the text. That&textrsquo;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 <code>ww {\centering xx \\ yy} zz</code> is +surrounded by blank lines then &latex; will create a paragraph whose +first line <samp>ww xx</samp> is centered and whose second line, not centered, +contains <samp>yy zz</samp>. Usually what is desired is for the scope of the +declaration to contain a blank line or the <code>\end</code> command of an +environment such as <code>figure</code> or <code>table</code> that ends the +paragraph unit. Thus, if <code>{\centering xx \\ yy\par} zz</code> is +surrounded by blank lines then it makes a new paragraph with two +centered lines <samp>xx</samp> and <samp>yy</samp>, followed by a new paragraph with +<samp>zz</samp> that is formatted as usual. +</para> + +</subsection> +</section> +<node name="description" spaces=" "><nodename>description</nodename><nodenext automatic="on">displaymath</nodenext><nodeprev automatic="on">center</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>description</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="266" mergedindex="cp"><r>environment</r>, <code>description</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="267" mergedindex="cp"><code>description</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="233">labelled lists, creating</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="234">description lists, creating</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{description} + \item[<var>label of first item</var>] <var>text of first item</var> + \item[<var>label of second item</var>] <var>text of second item</var> + ... +\end{description} +</pre></example> + +<para>Environment to make a list of labeled items. Each item&textrsquo;s <var>label</var> 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 <samp>Something's wrong--perhaps a +missing \item</samp>. +</para> +<para>This example shows the environment used for a sequence of definitions. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{definition} + \item[lama] A priest. + \item[llama] A beast. +\end{definition} +</pre></example> + +<noindent></noindent> +<para>The labels <samp>lama</samp> and <samp>llama</samp> are output in boldface, with the +left edge on the left margin. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="268" mergedindex="cp">\item</indexterm></findex> +<para>Start list items with the <code>\item</code> command (<pxref label="_005citem"><xrefnodename>\item</xrefnodename></pxref>). Use the +optional labels, as in <code>\item[Main point]</code>, because there is +no sensible default. Following the <code>\item</code> is optional text, which +may contain multiple paragraphs. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="235">bold typewriter, avoiding</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="236">typewriter labels in lists</indexterm></cindex> +<para>Since the labels are in bold style, if the label text calls for a font +change given in argument style (see <ref label="Font-styles"><xrefnodename>Font styles</xrefnodename></ref>) then it will come +out bold. For instance, if the label text calls for typewriter with +<code>\item[\texttt{label text}]</code> 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: +<code>\item[{\tt label text}]</code>. Similarly, get the standard roman +font with <code>\item[{\rm label text}]</code>. +</para> +<para>For other major &latex; labelled list environments, see <ref label="itemize"><xrefnodename>itemize</xrefnodename></ref> +and <ref label="enumerate"><xrefnodename>enumerate</xrefnodename></ref>. Unlike those environments, nesting +<code>description</code> 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 +<ref label="list"><xrefnodename>list</xrefnodename></ref>. The package <file>enumitem</file> is useful for customizing +lists. +</para> +<para>This example changes the description labels to small caps. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\descriptionlabel}[1]{% + {\hspace{\labelsep}\textsc{#1}}} +</pre></example> + + +</section> +<node name="displaymath" spaces=" "><nodename>displaymath</nodename><nodenext automatic="on">document</nodenext><nodeprev automatic="on">description</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>displaymath</code></sectiontitle> +<!-- c http://tex.stackexchange.com/questions/40492/what-are-the-differences-between-align-equation-and-displaymath --> + +<findex index="fn" spaces=" "><indexterm index="fn" number="269" mergedindex="cp"><r>environment</r>, <code>displaymath</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="270" mergedindex="cp"><code>displaymath</code> <r>environment</r></indexterm></findex> + + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{displaymath} + <var>mathematical text</var> +\end{displaymath} +</pre></example> + +<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 +<code>fleqn</code>; see <ref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></ref>. +</para> +<para>In the <code>displaymath</code> environment no equation number is added to the +math text. One way to get an equation number is to use the +<code>equation</code> environment (<pxref label="equation"><xrefnodename>equation</xrefnodename></pxref>). +</para> +<para>&latex; will not break the <var>math text</var> across lines. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="237"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="238"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>Note that the <file>amsmath</file> 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 <code>\[<var>math text</var>\]</code> is essentially a synonym for +<code>\begin{displaymath}<var>math text</var>\end{displaymath}</code> 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 +<code>displaymath</code> will likely be unique. (The construct +<code>$$<var>math text</var>$$</code> from Plain &tex; is sometimes +mistakenly used as a synonym for <code>displaymath</code>. It is not a +synonym, because the <code>displaymath</code> environment checks that it isn&textrsquo;t +started in math mode and that it ends in math mode begun by the matching +environment start, because the <code>displaymath</code> environment has +different vertical spacing, and because the <code>displaymath</code> +environment honors the <code>fleqn</code> option.) +</para> +<para>The output from this example is centered and alone on its line. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{displaymath} + \int_1^2 x^2\,dx=7/3 +\end{displaymath} +</pre></example> + +<noindent></noindent> +<para>Also, the integral sign is larger than the inline version +<code>\( \int_1^2 x^2\,dx=7/3 \)</code> produces. +</para> + +</section> +<node name="document" spaces=" "><nodename>document</nodename><nodenext automatic="on">enumerate</nodenext><nodeprev automatic="on">displaymath</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>document</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="271" mergedindex="cp"><r>environment</r>, <code>document</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="272" mergedindex="cp"><code>document</code> <r>environment</r></indexterm></findex> + + +<para>The <code>document</code> environment encloses the entire body of a document. +It is required in every &latex; document. <xref label="Starting-and-ending"><xrefnodename>Starting and ending</xrefnodename></xref>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\AtBeginDocument</menunode><menudescription><pre xml:space="preserve">Hook for commands at the start of the document. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\AtEndDocument</menunode><menudescription><pre xml:space="preserve">Hook for commands at the end of the document. +</pre></menudescription></menuentry></menu> + + +<node name="_005cAtBeginDocument" spaces=" "><nodename>\AtBeginDocument</nodename><nodenext automatic="on">\AtEndDocument</nodenext><nodeup automatic="on">document</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\AtBeginDocument</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="273" mergedindex="cp">\AtBeginDocument</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="239">beginning of document hook</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\AtBeginDocument{<var>code</var>} +</pre></example> + +<para>Save <var>code</var> and execute it when <code>\begin{document}</code> 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> + +</subsection> +<node name="_005cAtEndDocument" spaces=" "><nodename>\AtEndDocument</nodename><nodeprev automatic="on">\AtBeginDocument</nodeprev><nodeup automatic="on">document</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\AtEndDocument</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="274" mergedindex="cp">\AtEndDocument</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="240">end of document hook</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\AtEndDocument{<var>code</var>} +</pre></example> + +<para>Save <var>code</var> and execute it near the end of the document. +Specifically, it is executed when <code>\end{document}</code> 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 <code>\clearpage</code> at the +appropriate point in <var>code</var>. +</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> + +</subsection> +</section> +<node name="enumerate" spaces=" "><nodename>enumerate</nodename><nodenext automatic="on">eqnarray</nodenext><nodeprev automatic="on">document</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>enumerate</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="275" mergedindex="cp"><r>environment</r>, <code>enumerate</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="276" mergedindex="cp"><code>enumerate</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="241">lists of items, numbered</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{enumerate} + \item[<var>optional label of first item</var>] <var>text of first item</var> + \item[<var>optional label of second item</var>] <var>text of second item</var> + ... +\end{enumerate} +</pre></example> + +<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 <samp>1.</samp>, <samp>2.</samp>, +etc. Each <code>enumerate</code> list environment must have at least one item; +having none causes the &latex; error <samp>Something's wrong--perhaps a +missing \item</samp>. +</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 <samp>1.</samp> and +<samp>2.</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{enumerate} + \item Johnny Hayes (USA) + \item Charles Hefferon (RSA) +\end{enumerate} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="277" mergedindex="cp">\item</indexterm></findex> +<para>Start list items with the <code>\item</code> command (<pxref label="_005citem"><xrefnodename>\item</xrefnodename></pxref>). If you +give <code>\item</code> an optional argument by following it with square +brackets, as in <code>\item[Interstitial label]</code>, then the next item +will continue the interrupted sequence (<pxref label="_005citem"><xrefnodename>\item</xrefnodename></pxref>). That is, you +will get labels like <samp>1.</samp>, then <samp>Interstitial label</samp>, then +<samp>2.</samp>. Following the <code>\item</code> is optional text, which may +contain multiple paragraphs. +</para> +<para>Enumerations may be nested within other <code>enumerate</code> environments, +or within any paragraph-making environment such as <code>itemize</code> +(<pxref label="itemize"><xrefnodename>itemize</xrefnodename></pxref>), up to four levels deep. This gives &latex;&textrsquo;s +default for the format at each nesting level, where 1 is the top level, +the outermost level. +</para> +<enumerate first="1" endspaces=" "> +<listitem spaces=" "><para>arabic number followed by a period: <samp>1.</samp>, <samp>2.</samp>, &dots; +</para></listitem><listitem spaces=" "><para>lowercase letter inside parentheses: <samp>(a)</samp>, <samp>(b)</samp> &dots; +</para></listitem><listitem spaces=" "><para>lowercase roman numeral followed by a period: <samp>i.</samp>, <samp>ii.</samp>, &dots; +</para></listitem><listitem spaces=" "><para>uppercase letter followed by a period: <samp>A.</samp>, <samp>B.</samp>, &dots; +</para></listitem></enumerate> + +<findex index="fn" spaces=" "><indexterm index="fn" number="278" mergedindex="cp">\enumi</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="279" mergedindex="cp">\enumii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="280" mergedindex="cp">\enumiii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="281" mergedindex="cp">\enumiv</indexterm></findex> +<anchor name="enumerate-enumi">enumerate enumi</anchor> +<anchor name="enumerate-enumii">enumerate enumii</anchor> +<anchor name="enumerate-enumiii">enumerate enumiii</anchor> +<anchor name="enumerate-enumiv">enumerate enumiv</anchor> +<para>The <code>enumerate</code> environment uses the counters <code>\enumi</code> through +<code>\enumiv</code> (<pxref label="Counters"><xrefnodename>Counters</xrefnodename></pxref>). +</para> +<para>For other major &latex; labeled list environments, see +<ref label="description"><xrefnodename>description</xrefnodename></ref> and <ref label="itemize"><xrefnodename>itemize</xrefnodename></ref>. For information about list layout +parameters, including the default values, and for information about +customizing list layout, see <ref label="list"><xrefnodename>list</xrefnodename></ref>. The package <file>enumitem</file> is +useful for customizing lists. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="282" mergedindex="cp">\labelenumi</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="283" mergedindex="cp">\labelenumii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="284" mergedindex="cp">\labelenumiii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="285" mergedindex="cp">\labelenumiv</indexterm></findex> +<anchor name="enumerate-labelenumi">enumerate labelenumi</anchor> +<anchor name="enumerate-labelenumii">enumerate labelenumii</anchor> +<anchor name="enumerate-labelenumiii">enumerate labelenumiii</anchor> +<anchor name="enumerate-labelenumiv">enumerate labelenumiv</anchor> +<para>To change the format of the label use <code>\renewcommand</code> +(<pxref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & \renewcommand</xrefnodename></pxref>) on the commands <code>\labelenumi</code> +through <code>\labelenumiv</code>. For instance, this first level list will be +labelled with uppercase letters, in boldface, and without a trailing +period. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="286" mergedindex="cp">\Alph <r>example</r></indexterm></findex> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\labelenumi}{\textbf{\Alph{enumi}}} +\begin{enumerate} + \item Shows as boldface A + \item Shows as boldface B +\end{enumerate} +</pre></example> + +<para>For a list of counter-labeling commands see <ref label="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"><xrefnodename>\alph \Alph \arabic +\roman \Roman \fnsymbol</xrefnodename></ref>. +</para> + +</section> +<node name="eqnarray" spaces=" "><nodename>eqnarray</nodename><nodenext automatic="on">equation</nodenext><nodeprev automatic="on">enumerate</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>eqnarray</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="287" mergedindex="cp"><r>environment</r>, <code>eqnarray</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="288" mergedindex="cp"><code>eqnarray</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="242">equations, aligning</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="243">aligning equations</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="244">align <r>environment, from <code>amsmath</code></r></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="245">amsmath <r>package, replacing <code>eqnarray</code></r></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="246">Madsen, Lars</indexterm></cindex> +<para>The <code>eqnarray</code> environment is obsolete. It has infelicities, +including spacing that is inconsistent with other mathematics elements. +(See &textldquo;Avoid eqnarray!&textrdquo;&noeos; by Lars Madsen +<url><urefurl>http://tug.org/TUGboat/tb33-1/tb103madsen.pdf</urefurl></url>). New documents +should include the <file>amsmath</file> package and use the displayed +mathematics environments provided there, such as the <code>align</code> +environment. We include a description only for completeness and for +working with old documents. +</para> +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{eqnarray} + <var>first formula left</var> &<var>first formula middle</var> &<var>first formula right</var> \\ + ... +\end{eqnarray} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{eqnarray*} + <var>first formula left</var> &<var>first formula middle</var> &<var>first formula right</var> \\ + ... +\end{eqnarray*} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="289" mergedindex="cp">\\ <r>(for <code>eqnarray</code>)</r></indexterm></findex> +<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 <code>array</code> environment, with items +within a row separated by an ampersand (<code>&</code>), and with rows +separated by double backslash <code>\\</code>). +<findex index="fn" spaces=" "><indexterm index="fn" number="290" mergedindex="cp">\\* <r>(for <code>eqnarray</code>)</r></indexterm></findex> +The starred form of line break (<code>\\*</code>) can also be used to separate +equations, and will disallow a page break there (<pxref label="_005c_005c"><xrefnodename>\\</xrefnodename></pxref>). +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="291" mergedindex="cp">\nonumber</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="247">equation numbers, omitting</indexterm></cindex> +<para>The unstarred form <code>eqnarray</code> places an equation number on every +line (using the <code>equation</code> counter), unless that line contains a +<code>\nonumber</code> command. The starred form <code>eqnarray*</code> omits +equation numbering, while otherwise being the same. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="292" mergedindex="cp">\lefteqn</indexterm></findex> +<para>The command <code>\lefteqn</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\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*} +</pre></example> + + +</section> +<node name="equation" spaces=" "><nodename>equation</nodename><nodenext automatic="on">figure</nodenext><nodeprev automatic="on">eqnarray</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>equation</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="293" mergedindex="cp"><r>environment</r>, <code>equation</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="294" mergedindex="cp"><code>equation</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="248">equations, environment for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="249">formulas, environment for</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} + <var>mathematical text</var> +\end{equation} +</pre></example> + +<para>The same as a <code>displaymath</code> environment (<pxref label="displaymath"><xrefnodename>displaymath</xrefnodename></pxref>) +except that &latex; puts an equation number flush to the right margin. +The equation number is generated using the <code>equation</code> counter. +</para> +<para>You should have no blank lines between <code>\begin{equation}</code> and +<code>\begin{equation}</code>, or &latex; will tell you that there is a +missing dollar sign. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="250"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="251"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>The package <file>amsmath</file> package has extensive displayed equation +facilities. New documents should include this package. +</para> + +</section> +<node name="figure" spaces=" "><nodename>figure</nodename><nodenext automatic="on">filecontents</nodenext><nodeprev automatic="on">equation</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>figure</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="295" mergedindex="cp"><r>environment</r>, <code>figure</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="296" mergedindex="cp"><code>figure</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="252">inserting figures</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="253">figures, inserting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{figure}[<var>placement</var>] + <var>figure body</var> + \caption[<var>loftitle</var>]{<var>title</var>} % optional + \label{<var>label}</var> % optional +\end{figure} +</pre></example> + +<noindent></noindent> +<para>or: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{figure*}[<var>placement</var>] + <var>figure body</var> + \caption[<var>loftitle</var>]{<var>title</var>} % optional + \label{<var>label}</var> % optional +\end{figure*} +</pre></example> + +<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 &textldquo;floats&textrdquo; them to a convenient +place, such as the top of a following page (<pxref label="Floats"><xrefnodename>Floats</xrefnodename></pxref>). +</para> +<para>The <var>figure body</var> can consist of imported graphics +(<pxref label="Graphics"><xrefnodename>Graphics</xrefnodename></pxref>), or text, &latex; commands, etc. It is typeset in a +<code>parbox</code> of width <code>\textwidth</code>. +</para> +<para>The possible values of <var>placement</var> are <code>h</code> for <samp>here</samp>, +<code>t</code> for <samp>top</samp>, <code>b</code> for <samp>bottom</samp>, and <code>p</code> for +<samp>on a separate page of floats</samp>. For the effect of these options on +the float placement algorithm, see <ref label="Floats"><xrefnodename>Floats</xrefnodename></ref>. +</para> +<para>The starred form <code>figure*</code> is used when a document is in +double-column mode (<pxref label="_005ctwocolumn"><xrefnodename>\twocolumn</xrefnodename></pxref>). 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 <var>placement</var> <code>b</code> +in <ref label="Floats"><xrefnodename>Floats</xrefnodename></ref>. +</para> +<para>The label is optional; it is used for cross references (<pxref label="Cross-references"><xrefnodename>Cross +references</xrefnodename></pxref>). +<findex index="fn" spaces=" "><indexterm index="fn" number="297" mergedindex="cp">\caption</indexterm></findex> +The optional <code>\caption</code> command specifies caption text for the +figure. By default it is numbered. If <var>loftitle</var> is present, it is +used in the list of figures instead of <var>title</var> (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of +contents etc.</xrefnodename></pxref>). +</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> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{graphicx} % in preamble + ... +\begin{figure}[t] + \centering + \includegraphics[width=0.5\textwidth]{CTANlion.png} + \caption{The CTAN lion, by Duane Bibby} +\end{figure} +</pre></example> + + +</section> +<node name="filecontents" spaces=" "><nodename>filecontents</nodename><nodenext automatic="on">flushleft</nodenext><nodeprev automatic="on">figure</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>filecontents</code>: Write an external file</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="298" mergedindex="cp"><r>environment</r>, <code>filecontents</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="299" mergedindex="cp"><code>filecontents</code> <r>environment</r></indexterm></findex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="300" mergedindex="cp"><r>environment</r>, <code>filecontents*</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="301" mergedindex="cp"><code>filecontents*</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="254">external files, writing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="255">writing external files</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{filecontents}{<var>filename</var>} + <var>text</var> +\end{filecontents} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{filecontents*}{<var>filename</var>} + <var>text</var> +\end{filecontents*} +</pre></example> + +<para>Create a file named <var>filename</var> and fill it with <var>text</var>. The +unstarred version of the environment <code>filecontents</code> prefixes the +content of the created file with a header; see the example below. The +starred version <code>filecontents*</code> does not include the header. +</para> +<para>This environment can be used anywhere in the preamble, although it often +appears before the <code>\documentclass</code> command. It is typically used +when a source file requires a nonstandard style or class file. The +environment will write that file to the directory containing the source +and thus make the source file self-contained. Another use is to include +<code>bib</code> 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 <file>filecontents</file> package that +redefines the <code>filecontents</code> environment so that instead of doing +nothing in that case, it will overwrite the existing file. +</para> +<para>For example, this document +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{article} +\begin{filecontents}{JH.sty} +\newcommand{\myname}{Jim Hef{}feron} +\end{filecontents} +\usepackage{JH} +\begin{document} +Article by \myname. +\end{document} +</pre></example> + +<noindent></noindent> +<para>produces this file <file>JH.sty</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">%% LaTeX2e file `JH.sty' +%% generated by the `filecontents' environment +%% from source `test' on 2015/10/12. +%% +\newcommand{\myname}{Jim Hef{}feron} +</pre></example> + + +</section> +<node name="flushleft" spaces=" "><nodename>flushleft</nodename><nodenext automatic="on">flushright</nodenext><nodeprev automatic="on">filecontents</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>flushleft</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="302" mergedindex="cp"><r>environment</r>, <code>flushleft</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="303" mergedindex="cp"><code>flushleft</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="256">left-justifying text, environment for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="257">ragged right text, environment for</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{flushleft} + <var>line1</var> \\ + <var>line2</var> \\ + ... +\end{flushleft} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="304" mergedindex="cp">\\ <r>for <code>flushleft</code></r></indexterm></findex> +<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, <code>\\</code>. For the declaration form +see <ref label="_005craggedright"><xrefnodename>\raggedright</xrefnodename></ref>. +</para> +<para>This creates a box of text that is at most 3 inches wide, with the text +flush left and ragged right. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\raggedright</menunode><menudescription><pre xml:space="preserve">Declaration form of the <code>flushleft</code> environment. +</pre></menudescription></menuentry></menu> + + +<node name="_005craggedright" spaces=" "><nodename>\raggedright</nodename><nodeup automatic="on">flushleft</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\raggedright</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="305" mergedindex="cp">\raggedright</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="258">ragged right text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="259">left-justifying text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="260">justification, ragged right</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">{\raggedright ... } +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{<var>environment</var>} \raggedright + ... +\end{<var>environment</var>} +</pre></example> + +<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 <code>quote</code> +or in a <code>parbox</code>. For the environment form +see <ref label="flushleft"><xrefnodename>flushleft</xrefnodename></ref>. +</para> +<para>Unlike the <code>flushleft</code> environment, the <code>\raggedright</code> +command does not start a new paragraph; it only changes how &latex; +formats paragraph units. To affect a paragraph unit&textrsquo;s format, the +scope of the declaration must contain the blank line or <code>\end</code> +command that ends the paragraph unit. +</para> +<para>Here <code>\raggedright</code> in each second column keeps &latex; from doing +very awkward typesetting to fit the text into the narrow column. Note +that <code>\raggedright</code> is inside the curly braces <code>{...}</code> to +delimit its effect. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</subsection> +</section> +<node name="flushright" spaces=" "><nodename>flushright</nodename><nodenext automatic="on">itemize</nodenext><nodeprev automatic="on">flushleft</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>flushright</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="306" mergedindex="cp"><r>environment</r>, <code>flushright</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="307" mergedindex="cp"><code>flushright</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="261">ragged left text, environment for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="262">right-justifying text, environment for</indexterm></cindex> + +<example endspaces=" "> +<pre xml:space="preserve">\begin{flushright} + <var>line1</var> \\ + <var>line2</var> \\ + ... +\end{flushright} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="308" mergedindex="cp">\\ (for <code>flushright</code>)</indexterm></findex> +<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, <code>\\</code>. For the declaration form +see <ref label="_005craggedleft"><xrefnodename>\raggedleft</xrefnodename></ref>. +</para> +<para>For an example related to this environment, see <ref label="flushleft"><xrefnodename>flushleft</xrefnodename></ref>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\raggedleft</menunode><menudescription><pre xml:space="preserve">Declaration form of the <code>flushright</code> environment. +</pre></menudescription></menuentry></menu> + + +<node name="_005craggedleft" spaces=" "><nodename>\raggedleft</nodename><nodeup automatic="on">flushright</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\raggedleft</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="309" mergedindex="cp">\raggedleft</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="263">ragged left text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="264">justification, ragged left</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="265">right-justifying text</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">{\raggedleft ... } +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{<var>environment</var>} \raggedleft + ... +\end{<var>environment</var>} +</pre></example> + +<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 <code>quote</code> +or in a <code>parbox</code>. For the environment form +see <ref label="flushright"><xrefnodename>flushright</xrefnodename></ref>. +</para> +<para>Unlike the <code>flushright</code> environment, the <code>\raggedleft</code> +command does not start a new paragraph; it only changes how &latex; +formats paragraph units. To affect a paragraph unit&textrsquo;s format, the +scope of the declaration must contain the blank line or <code>\end</code> +command that ends the paragraph unit. +</para> +<para>For an example related to this environment, see <ref label="_005craggedright"><xrefnodename>\raggedright</xrefnodename></ref>. +</para> + +</subsection> +</section> +<node name="itemize" spaces=" "><nodename>itemize</nodename><nodenext automatic="on">letter</nodenext><nodeprev automatic="on">flushright</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>itemize</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="310" mergedindex="cp"><r>environment</r>, <code>itemize</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="311" mergedindex="cp"><code>itemize</code> <r>environment</r></indexterm></findex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="312" mergedindex="cp">\item</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="266">lists of items</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="267">unordered lists</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="268">bulleted lists</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="269">bullet lists</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{itemize} + \item[<var>optional label of first item</var>] <var>text of first item</var> + \item[<var>optional label of second item</var>] <var>text of second item</var> + ... +\end{itemize} +</pre></example> + +<para>Produce a list that is unordered, sometimes called a bullet list. The +environment must have at least one <code>\item</code>; having none causes the +&latex; error <samp>Something's wrong--perhaps a missing \item</samp>. +</para> +<para>This gives a two-item list. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{itemize} + \item Pencil and watercolor sketch by Cassandra + \item Rice portrait +\end{itemize} +</pre></example> + +<noindent></noindent> +<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> +<findex index="fn" spaces=" "><indexterm index="fn" number="313" mergedindex="cp">\item</indexterm></findex> +<para>Start list items with the <code>\item</code> command (<pxref label="_005citem"><xrefnodename>\item</xrefnodename></pxref>). If you +give <code>\item</code> an optional argument by following it with square +brackets, as in <code>\item[Optional label]</code>, then by default it will +appear in bold and be flush right, so it could extend into the left +margin. For labels that are flush left see the <ref label="description"><xrefnodename>description</xrefnodename></ref> +environment. Following the <code>\item</code> is optional text, which may +contain multiple paragraphs. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="314" mergedindex="cp">\labelitemi</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="315" mergedindex="cp">\labelitemii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="316" mergedindex="cp">\labelitemiii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="317" mergedindex="cp">\labelitemiv</indexterm></findex> +<anchor name="itemize-labelitemi">itemize labelitemi</anchor> +<anchor name="itemize-labelitemii">itemize labelitemii</anchor> +<anchor name="itemize-labelitemiii">itemize labelitemiii</anchor> +<anchor name="itemize-labelitemiv">itemize labelitemiv</anchor> +<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 <code>enumerate</code> (<pxref label="enumerate"><xrefnodename>enumerate</xrefnodename></pxref>). The <code>itemize</code> environment +uses the commands <code>\labelitemi</code> through <code>\labelitemiv</code> 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> +<enumerate first="1" endspaces=" "> +<listitem spaces=" "><para>• (bullet, from <code>\textbullet</code>) +</para></listitem><listitem spaces=" "><para><b>-<w>-</w></b> (bold en-dash, from <code>\normalfont\bfseries\textendash</code>) +</para></listitem><listitem spaces=" "><para>* (asterisk, from <code>\textasteriskcentered</code>) +</para></listitem><listitem spaces=" "><para>. (centered dot, rendered here as a period, from <code>\textperiodcentered</code>) +</para></listitem></enumerate> + +<para>Change the labels with <code>\renewcommand</code>. For instance, this makes +the first level use diamonds. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\labelitemi}{$\diamond$} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="318" mergedindex="cp">\leftmargin</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="319" mergedindex="cp">\leftmargini</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="320" mergedindex="cp">\leftmarginii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="321" mergedindex="cp">\leftmarginiii</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="322" mergedindex="cp">\leftmarginiv</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="323" mergedindex="cp">\leftmarginv</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="324" mergedindex="cp">\leftmarginvi</indexterm></findex> +<anchor name="itemize-leftmargin">itemize leftmargin</anchor> +<anchor name="itemize-leftmargini">itemize leftmargini</anchor> +<anchor name="itemize-leftmarginii">itemize leftmarginii</anchor> +<anchor name="itemize-leftmarginiii">itemize leftmarginiii</anchor> +<anchor name="itemize-leftmarginiv">itemize leftmarginiv</anchor> +<anchor name="itemize-leftmarginv">itemize leftmarginv</anchor> +<anchor name="itemize-leftmarginvi">itemize leftmarginvi</anchor> +<para>The distance between the left margin of the enclosing environment and +the left margin of the <code>itemize</code> list is determined by the +parameters <code>\leftmargini</code> through <code>\leftmarginvi</code>. (Note the +convention of using lowercase roman numerals a the end of the command +name to denote the nesting level.) The defaults are: <code>2.5em</code> in +level 1 (<code>2em</code> in two-column mode), <code>2.2em</code> in level 2, +<code>1.87em</code> in level 3, and <code>1.7em</code> in level 4, with smaller +values for more deeply nested levels. +</para> +<para>For other major &latex; labeled list environments, see +<ref label="description"><xrefnodename>description</xrefnodename></ref> and <ref label="enumerate"><xrefnodename>enumerate</xrefnodename></ref>. For information about list +layout parameters, including the default values, and for information +about customizing list layout, see <ref label="list"><xrefnodename>list</xrefnodename></ref>. The package +<file>enumitem</file> is useful for customizing lists. +</para> +<para>This example greatly reduces the margin space for outermost itemized +lists. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\leftmargini}{1.25em} % default 2.5em +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="325" mergedindex="cp">\parskip <r>example</r></indexterm></findex> +<para>Especially for lists with short items, it may be desirable to elide +space between items. Here is an example defining an <code>itemize*</code> +environment with no extra spacing between items, or between paragraphs +within a single item (<code>\parskip</code> is not list-specific, +<pxref label="_005cparindent-_0026-_005cparskip"><xrefnodename>\parindent & \parskip</xrefnodename></pxref>): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{itemize*}% + {\begin{itemize}% + \setlength{\itemsep}{0pt}% + \setlength{\parsep}{0pt}}% + \setlength{\parskip}{0pt}}% + {\end{itemize}} +</pre></example> + + +</section> +<node name="letter" spaces=" "><nodename>letter</nodename><nodenext automatic="on">list</nodenext><nodeprev automatic="on">itemize</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>letter</code> environment: writing letters</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="326" mergedindex="cp"><r>environment</r>, <code>letter</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="327" mergedindex="cp"><code>letter</code> <r>environment</r></indexterm></findex> + + +<para>This environment is used for creating letters. <xref label="Letters"><xrefnodename>Letters</xrefnodename></xref>. +</para> + +</section> +<node name="list" spaces=" "><nodename>list</nodename><nodenext automatic="on">math</nodenext><nodeprev automatic="on">letter</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>list</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="328" mergedindex="cp"><r>environment</r>, <code>list</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="329" mergedindex="cp"><code>list</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="270">lists of items, generic</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{list}{<var>labeling</var>}{<var>spacing</var>} + \item[<var>optional label of first item</var>] <var>text of first item</var> + \item[<var>optional label of second item</var>] <var>text of second item</var> + ... +\end{list} +</pre></example> + +<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 <code>description</code>, <code>enumerate</code>, and <code>itemize</code> +environments (<pxref label="description"><xrefnodename>description</xrefnodename></pxref>, <ref label="enumerate"><xrefnodename>enumerate</xrefnodename></ref>, and <ref label="itemize"><xrefnodename>itemize</xrefnodename></ref>). +</para> +<para>Instead, the <code>list</code> 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 <code>list</code>, including +<code>quotation</code>, <code>quote</code>, and <code>center</code> (<pxref label="quotation-_0026-quote"><xrefnodename>quotation & +quote</xrefnodename></pxref>, <pxref label="center"><xrefnodename>center</xrefnodename></pxref>). +</para> +<para>This uses the <code>list</code> environment to define a new custom +environment. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>The mandatory first argument <var>labeling</var> specifies the default +labeling of list items. It can contain text and &latex; commands, as +above where it contains both <samp>Item</samp> and <samp>\Roman{...}</samp>. +&latex; forms the label by putting the <var>labeling</var> argument in a box +of width <code>\labelwidth</code>. If the label is wider than that, the +additional material extends to the right. When making an instance of a +list you can override the default labeling by giving <code>\item</code> an +optional argument by including square braces and the text, as in the +above <code>\item[Special label.]</code>; <pxref label="_005citem"><xrefnodename>\item</xrefnodename></pxref>. +</para> +<para>The mandatory second argument <var>spacing</var> has a list of commands. +This list can be empty. A command that can go in here is +<code>\usecounter{<var>countername</var>}</code> (<pxref label="_005cusecounter"><xrefnodename>\usecounter</xrefnodename></pxref>). 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 +<code>\item</code> that does not have an optional argument. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="330" mergedindex="cp">\makelabel</indexterm></findex> +<anchor name="list-makelabel">list makelabel</anchor> <para>Another command that can go in <var>spacing</var> is +<code>\makelabel</code>, 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 (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). One example of changing its +definition is that to the above <code>named</code> example, before the +definition of the environment add +<code>\newcommand{\namedmakelabel}[1]{\textsc{#1}}</code>, and between +the <code>\setlength</code> command and the parenthesis that closes the +<var>spacing</var> argument also add <code>\let\makelabel\namedmakelabel</code>. +Then the items will be typeset in small caps. Similarly, changing the +second code line to <code>\let\makelabel\fbox</code> puts the labels inside a +framed box. Another example of the <code>\makelabel</code> command is below, +in the definition of the <code>redlabel</code> environment. +</para> +<para>Also often in <var>spacing</var> 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 <code>itemize</code> can be +different than the values shown here.) See also the figure that follows +the list. Each is a length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). The vertical spaces are +normally rubber lengths, with <code>plus</code> and <code>minus</code> components, +to give &tex; flexibility in setting the page. Change each with a +command such as <code>\setlength{itemsep}{2pt plus1pt minus1pt}</code>. +For some effects these lengths should be zero or negative. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="331" mergedindex="cp">\itemindent</indexterm>\itemindent</itemformat></item> +</tableterm><tableitem><anchor name="list-itemindent">list itemindent</anchor> +<para>Extra horizontal space indentation, beyond <code>leftmargin</code>, of the +first line each item. Its default value is <code>0pt</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="332" mergedindex="cp">\itemsep</indexterm>\itemsep</itemformat></item> +</tableterm><tableitem><anchor name="list-itemsep">list itemsep</anchor> +<para>Vertical space between items, beyond the <code>\parsep</code>. The defaults +for the first three levels in &latex;&textrsquo;s <samp>article</samp>, <samp>book</samp>, +and <samp>report</samp> classes at 10 point size are: <code>4pt plus2pt +minus1pt</code>, <code>\parsep</code> (that is, <code>2pt plus1pt minus1pt</code>), and +<code>\topsep</code> (that is, <code>2pt plus1pt minus1pt</code>). The defaults at +11 point are: <code>4.5pt plus2pt minus1pt</code>, <code>\parsep</code> (that is, +<code>2pt plus1pt minus1pt</code>), and <code>topsep</code> (that is, <code>2pt +plus1pt minus1pt</code>). The defaults at 12 point are: <code>5pt plus2.5pt +minus1pt</code>, <code>\parsep</code> (that is, <code>2.5pt plus1pt minus1pt</code>), and +<code>\topsep</code> (that is, <code>2.5pt plus1pt minus1pt</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="333" mergedindex="cp">\labelsep</indexterm>\labelsep</itemformat></item> +</tableterm><tableitem><anchor name="list-labelsep">list labelsep</anchor> +<para>Horizontal space between the label and text of an item. +The default for &latex;&textrsquo;s <samp>article</samp>, <samp>book</samp>, +and <samp>report</samp> classes is <code>0.5em</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="334" mergedindex="cp">\labelwidth</indexterm>\labelwidth</itemformat></item> +</tableterm><tableitem><anchor name="list-labelwidth">list labelwidth</anchor> +<para>Horizontal width. The box containing the label is nominally this wide. +If <code>\makelabel</code> 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 <code>\makelabel</code> returns text of width less than or equal to +<code>\labelwidth</code> then &latex;&textrsquo;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 +<code>\leftmargin</code>+<code>\itemindent</code>-<code>\labelsep</code>-<code>\labelwidth</code> +from the left margin of the enclosing environment. +</para> +<para>The default for &latex;&textrsquo;s <samp>article</samp>, <samp>book</samp>, and +<samp>report</samp> classes at the top level is +<code>\leftmargini</code>-<code>\labelsep</code>, (which is <code>2em</code> in one column +mode and <code>1.5em</code> in two column mode). At the second level it is +<code>\leftmarginii</code>-<code>\labelsep</code>, and at the third level it is +<code>\leftmarginiii</code>-<code>\labelsep</code>. These definitions make the +label&textrsquo;s left edge coincide with the left margin of the enclosing +environment. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="335" mergedindex="cp">\leftmargin</indexterm>\leftmargin</itemformat></item> +</tableterm><tableitem><anchor name="list-leftmargin">list leftmargin</anchor> +<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 <code>\leftmargini</code>, while a list that is nested inside +a top-level list has this margin set to <code>\leftmarginii</code>. More +deeply nested lists get the values of <code>\leftmarginiii</code> through +<code>\leftmarginvi</code>. (Nesting greater than level five generates the +error message <samp>Too deeply nested</samp>.) +</para> +<para>The defaults for the first three levels in &latex;&textrsquo;s <samp>article</samp>, +<samp>book</samp>, and <samp>report</samp> classes are: <code>\leftmargini</code> is +<code>2.5em</code> (in two column mode, <code>2em</code>), <code>\leftmarginii</code> is +<code>2.2em</code>, and <code>\leftmarginiii</code> is <code>1.87em</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="336" mergedindex="cp">\listparindent</indexterm>\listparindent</itemformat></item> +</tableterm><tableitem><anchor name="list-listparindent">list listparindent</anchor> +<para>Horizontal space of additional line indentation, beyond +<code>\leftmargin</code>, for second and subsequent paragraphs within a list +item. A negative value makes this an &textldquo;outdent&textrdquo;. Its default value +is <code>0pt</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="337" mergedindex="cp">\parsep</indexterm>\parsep</itemformat></item> +</tableterm><tableitem><anchor name="list-parsep">list parsep</anchor> +<para>Vertical space between paragraphs within an item. In the <samp>book</samp> +and <samp>article</samp> classes The defaults for the first three levels in +&latex;&textrsquo;s <samp>article</samp>, <samp>book</samp>, and <samp>report</samp> classes at 10 +point size are: <code>4pt plus2pt minus1pt</code>, <code>2pt plus1pt +minus1pt</code>, and <code>0pt</code>. The defaults at 11 point size are: +<code>4.5pt plus2pt minus1pt</code>, <code>2pt plus1pt minus1pt</code>, and +<code>0pt</code>. The defaults at 12 point size are: <code>5pt plus2.5pt +minus1pt</code>, <code>2.5pt plus1pt minus1pt</code>, and <code>0pt</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="338" mergedindex="cp">\partopsep</indexterm>\partopsep</itemformat></item> +</tableterm><tableitem><anchor name="list-partopsep">list partopsep</anchor> +<para>Vertical space added, beyond <code>\topsep</code>+<code>\parskip</code>, 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;&textrsquo;s <samp>article</samp>, +<samp>book</samp>, and <samp>report</samp> classes at 10 point size are: <code>2pt +plus1 minus1pt</code>, <code>2pt plus1pt minus1pt</code>, and <code>1pt plus0pt +minus1pt</code>. The defaults at 11 point are: <code>3pt plus1pt minus1pt</code>, +<code>3pt plus1pt minus1pt</code>, and <code>1pt plus0pt minus1pt</code>). The +defaults at 12 point are: <code>3pt plus2pt minus3pt</code>, <code>3pt plus2pt +minus2pt</code>, and <code>1pt plus0pt minus1pt</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="339" mergedindex="cp">\rightmargin</indexterm>\rightmargin</itemformat></item> +</tableterm><tableitem><anchor name="list-rightmargin">list rightmargin</anchor> +<para>Horizontal space between the right margin of the list and the right +margin of the enclosing environment. Its default value is <code>0pt</code>. +It must be non-negative. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="340" mergedindex="cp">\topsep</indexterm>\topsep</itemformat></item> +</tableterm><tableitem><anchor name="list-topsep">list topsep</anchor> +<para>Vertical space added to both the top and bottom of the list, in addition +to <code>\parskip</code> (<pxref label="_005cparindent-_0026-_005cparskip"><xrefnodename>\parindent & \parskip</xrefnodename></pxref>). The defaults for +the first three levels in &latex;&textrsquo;s <samp>article</samp>, <samp>book</samp>, and +<samp>report</samp> classes at 10 point size are: <code>8pt plus2pt minus4pt</code>, +<code>4pt plus2pt minus1pt</code>, and <code>2pt plus1pt minus1pt</code>. The +defaults at 11 point are: <code>9pt plus3pt minus5pt</code>, <code>4.5pt +plus2pt minus1pt</code>, and <code>2pt plus1pt minus1pt</code>. The defaults at 12 +point are: <code>10pt plus4pt minus6pt</code>, <code>5pt plus2.5pt minus1pt</code>, +and <code>2.5pt plus1pt minus1pt</code>. +</para> +</tableitem></tableentry></ftable> + +<para>This shows the horizontal and vertical distances. +</para> +<float type="" endspaces=" "> +<image><imagefile>latex2e-figures/list</imagefile><imagewidth>3.21in</imagewidth><imageextension>.png</imageextension></image> +</float> + +<para>The lengths shown are listed below. The key relationship is that the +right edge of the bracket for <var>h1</var> equals the right edge of the +bracket for <var>h4</var>, so that the left edge of the label box is at +<var>h3</var>+<var>h4</var>-(<var>h0</var>+<var>h1</var>). +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">v0</itemformat></item> +</tableterm><tableitem><para><math><code>&backslash;topsep</code> + <code>&backslash;parskip</code></math> if +the list environment does not start a new paragraph, and +<code>\topsep</code>+<code>\parskip</code>+<code>\partopsep</code> if it does +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">v1</itemformat></item> +</tableterm><tableitem><para><code>\parsep</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">v2</itemformat></item> +</tableterm><tableitem><para><code>\itemsep</code>+<code>\parsep</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">v3</itemformat></item> +</tableterm><tableitem><para>Same as <var>v0</var>. (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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h0</itemformat></item> +</tableterm><tableitem><para><code>\labelwidth</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h1</itemformat></item> +</tableterm><tableitem><para><code>\labelsep</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h2</itemformat></item> +</tableterm><tableitem><para><code>\listparindent</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h3</itemformat></item> +</tableterm><tableitem><para><code>\leftmargin</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h4</itemformat></item> +</tableterm><tableitem><para><code>\itemindent</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">h5</itemformat></item> +</tableterm><tableitem><para><code>\rightmargin</code> +</para> +</tableitem></tableentry></table> + +<para>The list&textrsquo;s left and right margins, shown above as <var>h3</var> and <var>h5</var>, +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 <code>\linewidth</code> (<pxref label="Page-layout-parameters"><xrefnodename>Page +layout parameters</xrefnodename></pxref>). For instance, set the list&textrsquo;s left margin to be one +quarter of the distance between the left and right margins of the +enclosing environment with +<code>\setlength{\leftmargin}{0.25\linewidth}</code>. +</para> +<para>Page breaking in a list structure is controlled by the three +parameters below. For each, the &latex; default is +<code>-\&arobase;lowpenalty</code>, that is, <code>-51</code>. Because it is negative, +it somewhat encourages a page break at each spot. Change it with, +e.g., <code>\&arobase;beginparpenalty=9999</code>; a value of 10000 prohibits a +page break. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="341" mergedindex="cp">\&arobase;beginparpenalty</indexterm>\&arobase;beginparpenalty</itemformat></item> +</tableterm><tableitem><anchor name="list-beginparpenalty">list beginparpenalty</anchor> +<para>The page breaking penalty for breaking before the list (default <code>-51</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="342" mergedindex="cp">\&arobase;itempenalty</indexterm>\&arobase;itempenalty</itemformat></item> +</tableterm><tableitem><anchor name="list-itempenalty">list itempenalty</anchor> +<para>The page breaking penalty for breaking before a list item (default <code>-51</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="343" mergedindex="cp">\&arobase;endparpenalty</indexterm>\&arobase;endparpenalty</itemformat></item> +</tableterm><tableitem><anchor name="list-endparpenalty">list endparpenalty</anchor> +<para>The page breaking penalty for breaking after a list (default <code>-51</code>). +</para> +</tableitem></tableentry></ftable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="271"><r>package</r>, <code>enumitem</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="272"><code>enumitem</code> <r>package</r></indexterm></cindex> + +<para>The package <code>enumitem</code> 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. +<xref label="_005cusecounter"><xrefnodename>\usecounter</xrefnodename></xref>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} } +</pre></example> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\item</menunode><menudescription><pre xml:space="preserve">An entry in a list. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">trivlist</menunode><menudescription><pre xml:space="preserve">A restricted form of <code>list</code>. +</pre></menudescription></menuentry></menu> + + +<node name="_005citem" spaces=" "><nodename>\item</nodename><nodenext automatic="on">trivlist</nodenext><nodeup automatic="on">list</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\item</code>: An entry in a list</sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\item text of item +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\item[<var>optional-label</var>] text of item +</pre></example> + +<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 +<samp>[...]</samp>, if you have an item whose text starts with <samp>[</samp>, you +have to hide the bracket inside curly braces, as in: <code>\item +{[} is an open square bracket</code>; 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: <code>\item[Close square bracket, {]}]</code>. <xref label="LaTeX-command-syntax"><xrefnodename>&latex; +command syntax</xrefnodename></xref>. +</para> +<para>In this example the enumerate list has two items that use the default +label and one that uses the optional label. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{enumerate} + \item Moe + \item[sometimes] Shemp + \item Larry +\end{enumerate} +</pre></example> + +<para>The first item is labelled <samp>1.</samp>, the second item is labelled +<samp>sometimes</samp>, and the third item is labelled <samp>2.</samp>. Because +of the optional label in the second item, the third item is not +labelled <samp>3.</samp>. +</para> + +</subsection> +<node name="trivlist" spaces=" "><nodename>trivlist</nodename><nodeprev automatic="on">\item</nodeprev><nodeup automatic="on">list</nodeup></node> +<subsection spaces=" "><sectiontitle><code>trivlist</code>: A restricted form of <code>list</code></sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{trivlist} + ... +\end{trivlist} +</pre></example> + +<para>A restricted version of the list environment, in which margins are not +indented and an <code>\item</code> without an optional argument produces no +text. It is most often used in macros, to define an environment where +the <code>\item</code> command as part of the environment&textrsquo;s definition. For +instance, the <code>center</code> environment is defined essentially like +this: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{center} + {\begin{trivlist}\centering\item\relax} + {\end{trivlist}} +</pre></example> + +<para>Using <code>trivlist</code> 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, <code>trivlist</code> uses the current values of the list +parameters (<pxref label="list"><xrefnodename>list</xrefnodename></pxref>), except that <code>\parsep</code> is set to the +value of <code>\parskip</code>, and <code>\leftmargin</code>, <code>\labelwidth</code>, +and <code>\itemindent</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</subsection> +</section> +<node name="math" spaces=" "><nodename>math</nodename><nodenext automatic="on">minipage</nodenext><nodeprev automatic="on">list</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>math</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="344" mergedindex="cp"><r>environment</r>, <code>math</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="345" mergedindex="cp"><code>math</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="273">in-line formulas</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{math} +<var>math</var> +\end{math} +</pre></example> + +<para>The <code>math</code> environment inserts given <var>math</var> material within +the running text. <code>\(...\)</code> and <code>$...$</code> are synonyms. +<xref label="Math-formulas"><xrefnodename>Math formulas</xrefnodename></xref>. +</para> + +</section> +<node name="minipage" spaces=" "><nodename>minipage</nodename><nodenext automatic="on">picture</nodenext><nodeprev automatic="on">math</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>minipage</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="346" mergedindex="cp"><r>environment</r>, <code>minipage</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="347" mergedindex="cp"><code>minipage</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="274">minipage, creating a</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{minipage}{<var>width</var>} + <var>contents</var> +\end{minipage} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{minipage}[<var>position</var>][<var>height</var>][<var>inner-pos</var>]{<var>width</var>} + <var>contents</var> +\end{minipage} +</pre></example> + +<para>Put <var>contents</var> into a box that is <var>width</var> 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 <code>minipage</code> +is similar to <code>\parbox</code> (<pxref label="_005cparbox"><xrefnodename>\parbox</xrefnodename></pxref>) but here you can have +paragraphs. +</para> +<para>This example will be 3 inches wide, and has two paragraphs. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>See below for a discussion of the paragraph indent inside a +<code>minipage</code>. +</para> +<para>The required argument <var>width</var> is a rigid length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +It gives the width of the box into which <var>contents</var> are typeset. +</para> +<para>There are three optional arguments, <var>position</var>, <var>height</var>, and +<var>inner-pos</var>. You need not include all three. For example, get the +default <var>position</var> and set the <var>height</var> with +<code>\begin{minipage}[c][2.54cm] <var>contents</var> \end{minipage}</code>. +(Get the natural height with an empty argument, <code>[]</code>.) +</para> +<para>The optional argument <var>position</var> governs how the <code>minipage</code> +vertically aligns with the surrounding material. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">c</itemformat></item> +</tableterm><tableitem><para>(synonym <code>m</code>) Default. Positions the <code>minipage</code> so its +vertical center lines up with the center of the adjacent text line (what +Plain &tex; calls <code>\vcenter</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">t</itemformat></item> +</tableterm><tableitem><para>Match the top line in the <code>minipage</code> with the baseline of the +surrounding text (Plain &tex;&textrsquo;s <code>\vtop</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b</itemformat></item> +</tableterm><tableitem><para>Match the bottom line in the <code>minipage</code> with the baseline of the +surrounding text (Plain &tex;&textrsquo;s <code>\vbox</code>. +</para></tableitem></tableentry></table> + +<para>To see the effects of these, contrast running this +</para> +<example endspaces=" "> +<pre xml:space="preserve">---\begin{minipage}[c]{0.25in} + first\\ second\\ third +\end{minipage} +</pre></example> + +<noindent></noindent> +<para>with the results of changing <code>c</code> to <code>b</code> or <code>t</code>. +</para> +<para>The optional argument <var>height</var> is a rigid length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +It sets the height of the <code>minipage</code>. You can enter any value +larger than, or equal to, or smaller than the <code>minipage</code>&textrsquo;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 <var>inner-pos</var> controls the placement of +<var>content</var> inside the box. These are the possible values are (the +default is the value of <var>position</var>). +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">t</itemformat></item> +</tableterm><tableitem><para>Place <var>content</var> at the top of the box. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">c</itemformat></item> +</tableterm><tableitem><para>Place it in the vertical center. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b</itemformat></item> +</tableterm><tableitem><para>Place it at the box bottom. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">s</itemformat></item> +</tableterm><tableitem><para>Stretch <var>contents</var> out vertically; it must contain vertically +stretchable space. +</para> +</tableitem></tableentry></table> + +<para>The <var>inner-pos</var> argument makes sense when the <var>height</var> option +is set to a value larger than the <code>minipage</code>&textrsquo;s natural height. To +see the effect of the options, run this example with the various choices +in place of <code>b</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Text before +\begin{center} + ---\begin{minipage}[c][3in][b]{0.25\textwidth} + first\\ second\\ third + \end{minipage} +\end{center} +Text after +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="275">indentation of paragraphs, in minipage</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="276">paragraph indentation, in minipage</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="348" mergedindex="cp">\parindent</indexterm></findex> +<para>By default paragraphs are not indented in a <code>minipage</code>. Change +that with a command such as <code>\setlength{\parindent}{1pc}</code> at +the start of <var>contents</var>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="277">footnotes in figures</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="278">figures, footnotes in</indexterm></cindex> +<para>Footnotes in a <code>minipage</code> environment are handled in a way that is +particularly useful for putting footnotes in figures or tables. A +<code>\footnote</code> or <code>\footnotetext</code> command puts the footnote at +the bottom of the minipage instead of at the bottom of the page, and it +uses the <code>\mpfootnote</code> counter instead of the ordinary +<code>footnote</code> counter (<pxref label="Counters"><xrefnodename>Counters</xrefnodename></pxref>). +</para> +<para>This puts the footnote at the bottom of the table, not the bottom of the +page. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<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 +<code>\end{minipage}</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{&arobase;{}c&arobase;{}}#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} +</pre></example> + + +</section> +<node name="picture" spaces=" "><nodename>picture</nodename><nodenext automatic="on">quotation & quote</nodenext><nodeprev automatic="on">minipage</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>picture</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="349" mergedindex="cp"><r>environment</r>, <code>picture</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="350" mergedindex="cp"><code>picture</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="279">creating pictures</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="280">pictures, creating</indexterm></cindex> + +<para>Synopses: +</para><example endspaces=" "> +<pre xml:space="preserve">\begin{picture}(<var>width</var>,<var>height</var>) + <var>picture commands</var> +\end{picture} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{picture}(<var>width</var>,<var>height</var>)(<var>xoffset</var>,<var>yoffset</var>) + <var>picture commands</var> +\end{picture} +</pre></example> + +<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 <code>TikZ</code>, <code>PSTricks</code>, <code>MetaPost</code>, +or <code>Asymptote</code>. These are not covered in this document; see CTAN. +</para> +<para>This shows the parallelogram law for adding vectors. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="351" mergedindex="cp">\unitlength</indexterm></findex> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>You can also use this environment to place arbitrary material at an +exact location. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The red X will be precisely a quarter of the <code>\linewidth</code> from +the left margin, and <code>0.35\linewidth</code> 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&textrsquo;s pages. +</para> +<para>The <code>picture</code> environment has one required argument, a pair of +numbers (<var>width</var>,<var>height</var>). Multiply these by the value +<code>\unitlength</code> 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&textrsquo;s box. +</para> +<para>This environment also has an optional argument +(<var>xoffset</var>,<var>yoffset</var>). It is used to shift the origin. Unlike +most optional arguments, this one is not contained in square brackets. +As with the required argument, it consists of two real numbers. +Multiply these by <code>\unitlength</code> to get the point at the lower-left +corner of the picture. +</para> +<para>For example, if <code>\unitlength</code> has been set to <code>1mm</code>, the +command +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{picture}(100,200)(10,20) +</pre></example> + +<noindent></noindent> +<para>produces a box of width 100 millimeters and height 200 millimeters. The +picture&textrsquo;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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="281">position, in picture</indexterm></cindex> +<para>Each <var>picture command</var> tells &latex; where to put something by +naming its position. A <dfn>position</dfn> is a pair such as <code>(2.4,-5)</code> +giving the x- and y-coordinates. A <dfn>coordinate</dfn> is a not a length, +it is a real number (it may have a decimal point or a minus sign). It +specifies a length in multiples of the unit length <code>\unitlength</code>, +so if <code>\unitlength</code> has been set to <code>1cm</code>, then the coordinate +2.54 specifies a length of 2.54 centimeters. +</para> +<para>&latex;&textrsquo;s default for <code>\unitlength</code> is <code>1pt</code>. it is a rigid +length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). Change it with the <code>\setlength</code> command +(<pxref label="_005csetlength"><xrefnodename>\setlength</xrefnodename></pxref>). Make this change only outside of a <code>picture</code> +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 <code>\put(1,2){...}</code>, 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: <code>\put</code>, +<code>\multiput</code>, <code>\qbezier</code>, and <code>\graphpaper</code>. The most +often used is <code>\put</code>. This +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(11.3,-0.3){...} +</pre></example> + +<noindent></noindent> +<para>places the object with its reference point at coordinates +<math>(11.3,-0.3)</math>. The reference points for various objects will be +described below. +<findex index="fn" spaces=" "><indexterm index="fn" number="352" mergedindex="cp">LR box</indexterm></findex> +The <code>\put</code> command creates an <dfn>LR box</dfn> (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +Anything that can go in an <code>\mbox</code> (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></pxref>) can +go in the text argument of the <code>\put</code> command. The reference point +will be the lower left corner of the box. In this picture +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\unitlength}{1cm} +...\begin{picture}(1,1) + \put(0,0){\line(1,0){1}} + \put(0,0){\line(1,1){1}} +\end{picture} +</pre></example> + +<noindent></noindent> +<para>the three dots are just slightly left of the point of the angle formed +by the two lines. (Also, <code>\line(1,1){1}</code> does not call for a +line of length one; rather the line has a change in the x coordinate of +1.) +</para> +<para>The <code>\multiput</code>, <code>qbezier</code>, and <code>graphpaper</code> commands are +described below. +</para> +<para>This draws a rectangle with a wavy top, using <code>\qbezier</code> for +that curve. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\put</menunode><menudescription><pre xml:space="preserve">Place an object at a specified place. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\multiput</menunode><menudescription><pre xml:space="preserve">Draw multiple instances of an object. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\qbezier</menunode><menudescription><pre xml:space="preserve">Draw a quadratic Bezier curve. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\graphpaper</menunode><menudescription><pre xml:space="preserve">Draw graph paper. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\line</menunode><menudescription><pre xml:space="preserve">Draw a straight line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\linethickness</menunode><menudescription><pre xml:space="preserve">Set thickness of horizontal and vertical lines. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\thinlines</menunode><menudescription><pre xml:space="preserve">The default line thickness. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\thicklines</menunode><menudescription><pre xml:space="preserve">A heavier line thickness. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\circle</menunode><menudescription><pre xml:space="preserve">Draw a circle. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\oval</menunode><menudescription><pre xml:space="preserve">Draw an oval. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\shortstack</menunode><menudescription><pre xml:space="preserve">Make a stack of objects. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\vector</menunode><menudescription><pre xml:space="preserve">Draw a line with an arrow. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\makebox (picture)</menunode><menudescription><pre xml:space="preserve">Draw a box of the specified size. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\framebox (picture)</menunode><menudescription><pre xml:space="preserve">Draw a box with a frame around it. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\frame</menunode><menudescription><pre xml:space="preserve">Draw a frame around an object. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\dashbox</menunode><menudescription><pre xml:space="preserve">Draw a dashed box. +</pre></menudescription></menuentry></menu> + + +<node name="_005cput" spaces=" "><nodename>\put</nodename><nodenext automatic="on">\multiput</nodenext><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\put</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="353" mergedindex="cp">\put</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(<var>xcoord</var>,<var>ycoord</var>){<var>content</var>} +</pre></example> + +<para>Place <var>content</var> at the coordinate (<var>xcoord</var>,<var>ycoord</var>). See +the discussion of coordinates and <code>\unitlength</code> in <ref label="picture"><xrefnodename>picture</xrefnodename></ref>. +The <var>content</var> is processed in LR mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>) so it cannot +contain line breaks. +</para> +<para>This includes the text into the <code>picture</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(4.5,2.5){Apply the \textit{unpoke} move} +</pre></example> + +<para>The reference point, the location (4.5,2.5), is the lower left of the +text, at the bottom left of the <samp>A</samp>. +</para> + +</subsection> +<node name="_005cmultiput" spaces=" "><nodename>\multiput</nodename><nodenext automatic="on">\qbezier</nodenext><nodeprev automatic="on">\put</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\multiput</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="354" mergedindex="cp">\multiput</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\multiput(<var>x</var>,<var>y</var>)(<var>delta_x</var>,<var>delta_y</var>){<var>num-copies</var>}{<var>obj</var>} +</pre></example> + +<para>Copy <var>obj</var> a total of <var>num-copies</var> times, with an increment of +<var>delta_x,delta_y</var>. The <var>obj</var> first appears at position +<math>(x,y)</math>, then at <math>(x+\delta_x,y+\delta_y)</math>, and so on. +</para> +<para>This draws a simple grid with every fifth line in bold (see also +<ref label="_005cgraphpaper"><xrefnodename>\graphpaper</xrefnodename></ref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</subsection> +<node name="_005cqbezier" spaces=" "><nodename>\qbezier</nodename><nodenext automatic="on">\graphpaper</nodenext><nodeprev automatic="on">\multiput</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\qbezier</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="355" mergedindex="cp">\qbezier</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\qbezier(<var>x1</var>,<var>y1</var>)(<var>x2</var>,<var>y2</var>)(<var>x3</var>,<var>y3</var>) +\qbezier[<var>num</var>](<var>x1</var>,<var>y1</var>)(<var>x2</var>,<var>y2</var>)(<var>x3</var>,<var>y3</var>) +</pre></example> + +<para>Draw a quadratic Bezier curve whose control points are given by the +three required arguments <code>(<var>x1</var>,<var>y1</var>)</code>, +<code>(<var>x2</var>,<var>y2</var>)</code>, and <code>(<var>x3</var>,<var>y3</var>)</code>. That is, +the curve runs from <var>(x1,y1)</var> to <var>(x3,y3)</var>, is quadratic, and is +such that the tangent line at <var>(x1,y1)</var> passes through +<var>(x2,y2)</var>, as does the tangent line at <var>(x3,y3)</var>. +</para> +<para>This draws a curve from the coordinate (1,1) to (1,0). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\qbezier(1,1)(1.25,0.75)(1,0) +</pre></example> + +<noindent></noindent> +<para>The curve&textrsquo;s tangent line at (1,1) contains (1.25,0.75), as does the +curve&textrsquo;s tangent line at (1,0). +</para> +<para>The optional argument <var>num</var> gives the number of calculated +intermediate points. The default is to draw a smooth curve whose +maximum number of points is <code>\qbeziermax</code> (change this value with +<code>\renewcommand</code>). +</para> + +</subsection> +<node name="_005cgraphpaper" spaces=" "><nodename>\graphpaper</nodename><nodenext automatic="on">\line</nodenext><nodeprev automatic="on">\qbezier</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\graphpaper</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="356" mergedindex="cp">\graphpaper</indexterm></findex> +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\graphpaper(<var>x_init</var>,<var>y_init</var>)(<var>x_dimen</var>,<var>y_dimen</var>) +\graphpaper[<var>spacing</var>](<var>x_init</var>,<var>y_init</var>)(<var>x_dimen</var>,<var>y_dimen</var>) +</pre></example> + +<para>Draw a coordinate grid. Requires the <code>graphpap</code> package. +The grid&textrsquo;s origin is <code>(<var>x_init</var>,<var>y_init</var>)</code>. +Grid lines come every <var>spacing</var> units (the default is 10). +The grid extends <var>x_dimen</var> units to the right and <var>y_dimen</var> units up. +All arguments must be positive integers. +</para> +<para>This make a grid with seven vertical lines and eleven horizontal lines. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{graphpap} % in preamble + ... +\begin{picture}(6,20) % in document body + \graphpaper[2](0,0)(12,20) +\end{picture} +</pre></example> + +<noindent></noindent> +<para>The lines are numbered every ten units. +</para> + +</subsection> +<node name="_005cline" spaces=" "><nodename>\line</nodename><nodenext automatic="on">\linethickness</nodenext><nodeprev automatic="on">\graphpaper</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\line</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="357" mergedindex="cp">\line</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\line(<var>x_run</var>,<var>y_rise</var>){<var>travel</var>} +</pre></example> + +<para>Draw a line. It slopes such that it vertically rises <var>y_rise</var> for +every horizontal <var>x_run</var>. The <var>travel</var> is the total horizontal +change &textmdash; it is not the length of the vector, it is the change in +<math>x</math>. In the special case of vertical lines, where +(<var>x_run</var>,<var>y_rise</var>)=(0,1), the <var>travel</var> gives the change in +<math>y</math>. +</para> +<para>This draws a line starting at coordinates (1,3). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(1,3){\line(2,5){4}} +</pre></example> + +<noindent></noindent> +<para>For every over 2, this line will go up 5. Because <var>travel</var> +specifies that this goes over 4, it must go up 10. Thus its +endpoint is <math>(1,3)+(4,10)=(5,13)</math>. In particular, note that +<math><var>travel</var>=4</math> is not the length of the line, it is the change in +<math>x</math>. +</para> +<para>The arguments <var>x_run</var> and <var>y_rise</var> are integers that can be +positive, negative, or zero. (If both are 0 then &latex; treats the +second as 1.) With +<code>\put(<var>x_init</var>,<var>y_init</var>){\line(<var>x_run</var>,<var>y_rise</var>){<var>travel</var>}}</code>, +if <var>x_run</var> is negative then the line&textrsquo;s ending point has a first +coordinate that is less than <var>x_init</var>. If <var>y_rise</var> is negative +then the line&textrsquo;s ending point has a second coordinate that is less than +<var>y_init</var>. +</para> +<para>If <var>travel</var> is negative then you get <code>LaTeX Error: Bad \line or +\vector argument.</code> +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="282"><code>pict2e</code> package</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="283">graphics packages</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="284"><r>package</r>, <code>pict2e</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="285"><code>pict2e</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="286"><r>package</r>, <code>TikZ</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="287"><code>TikZ</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="288"><r>package</r>, <code>PSTricks</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="289"><code>PSTricks</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="290"><r>package</r>, <code>MetaPost</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="291"><code>MetaPost</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="292"><r>package</r>, <code>Asymptote</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="293"><code>Asymptote</code> <r>package</r></indexterm></cindex> + +<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 <var>x_run</var> and <var>y_rise</var> must have +integer values from −6 through 6. Also, they must be +relatively prime, so that <var>(x_run,y_rise)</var> can be (2,1) but not +(4,2) (if you choose the latter then instead of lines you get sequences +of arrowheads; the solution is to switch to the former). To get lines +of arbitrary slope and plenty of other shapes in a system like +<code>picture</code>, see the package <file>pict2e</file> on CTAN. Another solution +is to use a full-featured graphics system such as <file>TikZ</file>, or +<file>PSTricks</file>, or <file>MetaPost</file>, or <file>Asymptote</file> +</para> + +</subsection> +<node name="_005clinethickness" spaces=" "><nodename>\linethickness</nodename><nodenext automatic="on">\thinlines</nodenext><nodeprev automatic="on">\line</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\linethickness</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="358" mergedindex="cp">\linethickness</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\linethickness{<var>dim</var>} +</pre></example> + +<para>Declares the thickness of subsequent horizontal and vertical lines in a +picture to be <var>dim</var>, which must be a positive length +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). It differs from <code>\thinlines</code> and +<code>\thicklines</code> in that it does not affect the thickness of slanted +lines, circles, or ovals. +</para> + +</subsection> +<node name="_005cthinlines" spaces=" "><nodename>\thinlines</nodename><nodenext automatic="on">\thicklines</nodenext><nodeprev automatic="on">\linethickness</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\thinlines</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="359" mergedindex="cp">\thinlines</indexterm></findex> + +<para>Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.4<dmn>pt</dmn>. This is the default +thickness, so this command is unnecessary unless the thickness has been +changed with either <ref label="_005clinethickness"><xrefnodename>\linethickness</xrefnodename></ref> or <ref label="_005cthicklines"><xrefnodename>\thicklines</xrefnodename></ref>. +</para> + +</subsection> +<node name="_005cthicklines" spaces=" "><nodename>\thicklines</nodename><nodenext automatic="on">\circle</nodenext><nodeprev automatic="on">\thinlines</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\thicklines</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="360" mergedindex="cp">\thicklines</indexterm></findex> + +<para>Declaration to set the thickness of subsequent lines, circles, and ovals +in a picture environment to be 0.8<dmn>pt</dmn>. See also +<ref label="_005clinethickness"><xrefnodename>\linethickness</xrefnodename></ref> and <ref label="_005cthinlines"><xrefnodename>\thinlines</xrefnodename></ref>. This command is illustrated +in the Trapezoidal Rule example of <ref label="picture"><xrefnodename>picture</xrefnodename></ref>. +</para> + +</subsection> +<node name="_005ccircle" spaces=" "><nodename>\circle</nodename><nodenext automatic="on">\oval</nodenext><nodeprev automatic="on">\thicklines</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\circle</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="361" mergedindex="cp">\circle</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\circle{<var>diameter</var>} +\circle*{<var>diameter</var>} +</pre></example> + +<para>Produces a circle with a diameter as close as possible to the specified +one. The <code>*</code> form produces a filled-in circle. +</para> +<para>This draws a circle of radius 6, centered at <code>(5,7)</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(5,7){\circle{6}} +</pre></example> + +<para>The available radii for <code>circle</code> are, in points, the even +numbers from 2 to 20, inclusive. For <code>circle*</code> they are all the +integers from 1 to 15. +</para> + +</subsection> +<node name="_005coval" spaces=" "><nodename>\oval</nodename><nodenext automatic="on">\shortstack</nodenext><nodeprev automatic="on">\circle</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\oval</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="362" mergedindex="cp">\oval</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\oval(<var>width</var>,<var>height</var>) +\oval(<var>width</var>,<var>height</var>)[<var>portion</var>] +</pre></example> + +<para>Produce a rectangle with rounded corners. The optional argument +<var>portion</var> allows you to produce only half or a quarter of the oval. +For half an oval take <var>portion</var> to be one of these. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">t</itemformat></item> +</tableterm><tableitem><para>top half +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b</itemformat></item> +</tableterm><tableitem><para>bottom half +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">r</itemformat></item> +</tableterm><tableitem><para>right half +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">l</itemformat></item> +</tableterm><tableitem><para>left half +</para></tableitem></tableentry></table> + +<para>Produce only one quarter of the oval by setting <var>portion</var> to +<code>tr</code>, <code>br</code>, <code>bl</code>, or <code>tl</code>. +</para> +<para>This draws the top half of an oval that is 3 wide and 7 tall. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(5,7){\oval(3,7)[t]} +</pre></example> + +<noindent></noindent> +<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 +20<dmn>pt</dmn> (<pxref label="_005ccircle"><xrefnodename>\circle</xrefnodename></pxref> for the sizes). Thus large ovals are just +boxes with a small amount of corner rounding. +</para> + +</subsection> +<node name="_005cshortstack" spaces=" "><nodename>\shortstack</nodename><nodenext automatic="on">\vector</nodenext><nodeprev automatic="on">\oval</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\shortstack</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="363" mergedindex="cp">\shortstack</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\shortstack[<var>position</var>]{<var>line 1</var> \\ ... } +</pre></example> + +<para>Produce a vertical stack of objects. +</para> +<para>This labels the <math>y</math> axis. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}}} +</pre></example> + +<noindent></noindent> +<para>For a short stack, the reference point is the lower left of the stack. +In the above example the <ref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></ref> puts the stack flush +right in a zero width box so in total the short stack sits slightly to +the left of the <math>y</math> axis. +</para> +<para>The valid positions are: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">r</itemformat></item> +</tableterm><tableitem><para>Make objects flush right +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">l</itemformat></item> +</tableterm><tableitem><para>Make objects flush left +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">c</itemformat></item> +</tableterm><tableitem><para>Center objects (default) +</para></tableitem></tableentry></table> + +<findex index="fn" spaces=" "><indexterm index="fn" number="364" mergedindex="cp">\\ <r>(for <code>\shortstack</code> objects)</r></indexterm></findex> +<para>Separate objects into lines with <code>\\</code>. These stacks are short in +that, unlike in a <code>tabular</code> or <code>array</code> environment, here the +rows are not spaced out to be of even heights. Thus, in +<code>\shortstack{X\\o\\o\\X}</code> 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 <code>\shortstack{X\\ \strut o\\o\\X}</code>, +or by hand, via an explicit zero-width box <code>\shortstack{X \\ +\rule{0pt}{12pt} o\\o\\X}</code> or by using <code>\\</code>&textrsquo;s optional +argument <code>\shortstack{X\\[2pt] o\\o\\X}</code>. +</para> +<para>The <code>\shortstack</code> command is also available outside the +<code>picture</code> environment. +</para> + +</subsection> +<node name="_005cvector" spaces=" "><nodename>\vector</nodename><nodenext automatic="on">\makebox (picture)</nodenext><nodeprev automatic="on">\shortstack</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\vector</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="365" mergedindex="cp">\vector</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\vector(<var>x_run</var>,<var>y_rise</var>){<var>travel</var>} +</pre></example> + +<para>Draw a line ending in an arrow. The slope of that line is: it +vertically rises <var>y_rise</var> for every horizontal <var>x_run</var>. The +<var>travel</var> is the total horizontal change &textmdash; it is not the +length of the vector, it is the change in <math>x</math>. In the special case +of vertical vectors, if (<var>x_run</var>,<var>y_rise</var>)=(0,1), then +<var>travel</var> gives the change in <math>y</math>. +</para> +<para>For an example see <ref label="picture"><xrefnodename>picture</xrefnodename></ref>. +</para> +<para>For elaboration on <var>x_run</var> and <var>y_rise</var> see <ref label="_005cline"><xrefnodename>\line</xrefnodename></ref>. As +there, the values of <var>x_run</var> and <var>y_rise</var> are limited. For +<code>\vector</code> you must chooses integers between −4 and 4, +inclusive. Also, the two you choose must be relatively prime. Thus, +<code>\vector(2,1){4}</code> is acceptable but <code>\vector(4,2){4}</code> is +not (if you use the latter then you get a sequence of arrowheads). +</para> + +</subsection> +<node name="_005cmakebox-_0028picture_0029" spaces=" "><nodename>\makebox (picture)</nodename><nodenext automatic="on">\framebox (picture)</nodenext><nodeprev automatic="on">\vector</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\makebox</code> (picture)</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="366" mergedindex="cp">\makebox <r>(for <code>picture</code>)</r></indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makebox(<var>rec-width</var>,<var>rec-height</var>){<var>text</var>} +\makebox(<var>rec-width</var>,<var>rec-height</var>)[<var>position</var>]{<var>text</var>} +</pre></example> + +<para>Make a box to hold <var>text</var>. This command fits with the +<code>picture</code> environment, although you can use it outside of there, +because <var>rec-width</var> and <var>rec-height</var> are numbers specifying +distances in terms of the <code>\unitlength</code> (<pxref label="picture"><xrefnodename>picture</xrefnodename></pxref>). This +command is similar to the normal <code>\makebox</code> command (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & +\makebox</xrefnodename></pxref>) except here that you must specify the width and height. This +command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This makes a box of length 3.5 times <code>\unitlength</code> and height 4 +times <code>\unitlength</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(1,2){\makebox(3.5,4){...}} +</pre></example> + +<para>The optional argument <code><var>position</var></code> specifies where in the box +the <var>text</var> 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> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">t</itemformat></item> +</tableterm><tableitem><para>Puts <var>text</var> the top of the box. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">b</itemformat></item> +</tableterm><tableitem><para>Put <var>text</var> at the bottom. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">l</itemformat></item> +</tableterm><tableitem><para>Put <var>text</var> on the left. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">r</itemformat></item> +</tableterm><tableitem><para>Put <var>text</var> on the right. +</para> +</tableitem></tableentry></table> + + +</subsection> +<node name="_005cframebox-_0028picture_0029" spaces=" "><nodename>\framebox (picture)</nodename><nodenext automatic="on">\frame</nodenext><nodeprev automatic="on">\makebox (picture)</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\framebox</code> (picture)</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="367" mergedindex="cp">\framebox</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\framebox(<var>rec-width</var>,<var>rec-height</var>){<var>text</var>} +\framebox(<var>rec-width</var>,<var>rec-height</var>)[<var>position</var>]{<var>text</var>} +</pre></example> + +<para>This is the same as <ref label="_005cmakebox-_0028picture_0029"><xrefnodename>\makebox (picture)</xrefnodename></ref> 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 +<code>picture</code> environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +<code>\unitlength</code> (<pxref label="picture"><xrefnodename>picture</xrefnodename></pxref>). This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This example creates a frame 2.5 inches by 3 inches and puts +the text in the center. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\unitlength}{1in} +\framebox(2.5,3){test text} +</pre></example> + +<para>The required arguments are that the rectangle has overall width +<var>rect-width</var> units and height <var>rect-height</var> units. +</para> +<para>The optional argument <var>position</var> specifies the position of +<var>text</var>; see <ref label="_005cmakebox-_0028picture_0029"><xrefnodename>\makebox (picture)</xrefnodename></ref> for the values that it can +take. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="368" mergedindex="cp">\fboxrule</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="369" mergedindex="cp">\fboxsep</indexterm></findex> +<para>The rule has thickness <code>\fboxrule</code> and there is a blank space +<code>\fboxsep</code> between the frame and the contents of the box. +</para> +<para>For this command, you must specify the <var>width</var> and <var>height</var>. If +you want to just put a frame around some contents whose dimension is +determined in some other way then either use <code>\fbox</code> (<pxref label="_005cfbox-_0026-_005cframebox"><xrefnodename>\fbox +& \framebox</xrefnodename></pxref>) or <code>\frame</code> (<pxref label="_005cframe"><xrefnodename>\frame</xrefnodename></pxref>). +</para> + +</subsection> +<node name="_005cframe" spaces=" "><nodename>\frame</nodename><nodenext automatic="on">\dashbox</nodenext><nodeprev automatic="on">\framebox (picture)</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\frame</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="370" mergedindex="cp">\frame</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\frame{<var>contents</var>} +</pre></example> + +<para>Puts a rectangular frame around <var>contents</var>. The reference point is +the bottom left corner of the frame. In contrast to <code>\framebox</code> +(<pxref label="_005cframebox-_0028picture_0029"><xrefnodename>\framebox (picture)</xrefnodename></pxref>), this command puts no extra space is put +between the frame and the object. It is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> + +</subsection> +<node name="_005cdashbox" spaces=" "><nodename>\dashbox</nodename><nodeprev automatic="on">\frame</nodeprev><nodeup automatic="on">picture</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\dashbox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="371" mergedindex="cp">\dashbox</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\dashbox{<var>dash-len</var>}(<var>rect-width</var>,<var>rect-height</var>){<var>text</var>} +\dashbox{<var>dash-len</var>}(<var>rect-width</var>,<var>rect-height</var>)[<var>position</var>]{<var>text</var>} +</pre></example> + +<para>Create a dashed rectangle around <var>text</var>. This command fits with the +<code>picture</code> environment, although you can use it outside of there, +because lengths are numbers specifying the distance in terms of the +<code>\unitlength</code> (<pxref label="picture"><xrefnodename>picture</xrefnodename></pxref>). +</para> +<para>The required arguments are: dashes are <var>dash-len</var> units long, with +the same length gap, and the rectangle has overall width +<var>rect-width</var> units and height <var>rect-height</var> units. +</para> +<para>The optional argument <var>position</var> specifies the position of +<var>text</var>; see <ref label="_005cmakebox-_0028picture_0029"><xrefnodename>\makebox (picture)</xrefnodename></ref> for the values that it can +take. +</para> +<para>This shows that you can use non-integer value for <var>dash-len</var>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\put(0,0){\dashbox{0.1}(5,0.5){My hovercraft is full of eels.}} +</pre></example> + +<noindent></noindent> +<para>Each dash will be <code>0.1\unitlength</code> long, the box&textrsquo;s width is +<code>5\unitlength</code> and its height is <code>0.5\unitlength</code>. +</para> +<para>As in that example, a dashed box looks best when <var>rect-width</var> and +<var>rect-height</var> are multiples of the <var>dash-len</var>. +</para> + +</subsection> +</section> +<node name="quotation-_0026-quote" spaces=" "><nodename>quotation & quote</nodename><nodenext automatic="on">tabbing</nodenext><nodeprev automatic="on">picture</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>quotation</code> & <code>quote</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="372" mergedindex="cp"><r>environment</r>, <code>quotation</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="373" mergedindex="cp"><code>quotation</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="294">quoted text with paragraph indentation, displaying</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="295">displaying quoted text with paragraph indentation</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="296">paragraph indentations in quoted text</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="374" mergedindex="cp"><r>environment</r>, <code>quote</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="375" mergedindex="cp"><code>quote</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="297">quoted text without paragraph indentation, displaying</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="298">displaying quoted text without paragraph indentation</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="299">paragraph indentations in quoted text, omitting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{quotation} + <var>text</var> +\end{quotation} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{quote} + <var>text</var> +\end{quote} +</pre></example> + +<para>Include a quotation. Both environments indent margins on both sides by +<code>\leftmargin</code> and the text is right-justified. +</para> +<para>They differ in how they treat paragraphs. In the <code>quotation</code> +environment, paragraphs are indented by 1.5<dmn>em</dmn> and the space +between paragraphs is small, <code>0pt plus 1pt</code>. In the <code>quote</code> +environment, paragraphs are not indented and there is vertical space +between paragraphs (it is the rubber length <code>\parsep</code>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{quotation} \small\it + Four score and seven years ago + ... shall not perish from the earth. + \hspace{1em plus 1fill}---Abraham Lincoln +\end{quotation} +</pre></example> + + +</section> +<node name="tabbing" spaces=" "><nodename>tabbing</nodename><nodenext automatic="on">table</nodenext><nodeprev automatic="on">quotation & quote</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>tabbing</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="376" mergedindex="cp"><r>environment</r>, <code>tabbing</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="377" mergedindex="cp"><code>tabbing</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="300">tab stops, using</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="301">lining text up using tab stops</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="302">alignment via tabbing</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabbing} +<var>row1col1</var> \= <var>row1col2</var> ... \\ +<var>row2col1</var> \> <var>row2col2</var> ... \\ +... +\end{tabbing} +</pre></example> + +<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 +<code>tabular</code> (<pxref label="tabular"><xrefnodename>tabular</xrefnodename></pxref>) or <code>array</code> (<pxref label="array"><xrefnodename>array</xrefnodename></pxref>) 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 <code>\kill</code> command (which is described below): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>Both the <code>tabbing</code> environment and the more widely-used +<code>tabular</code> environment put text in columns. The most important +distinction is that in <code>tabular</code> the width of columns is +determined automatically by &latex;, while in <code>tabbing</code> the user +sets the tab stops. Another distinction is that <code>tabular</code> +generates a box, but <code>tabbing</code> can be broken across pages. +Finally, while <code>tabular</code> can be used in any mode, <code>tabbing</code> +can be used only in paragraph mode and it starts a new paragraph. +</para> +<para>A <code>tabbing</code> 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 <code>\hspace</code> command at the beginning +of a tabbed row. The right margin of the <code>tabbing</code> environment is +the end of line, so that the width of the environment is +<code>\linewidth</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="303">row, <r>tabbing</r></indexterm></cindex> +<para>The <code>tabbing</code> environment contains a sequence of <dfn>tabbed +rows</dfn>. The first tabbed row begins immediately after +<code>\begin{tabbing}</code> and each row ends with <code>\\</code> or +<code>\kill</code>. The last row may omit the <code>\\</code> and end with just +<code>\end{tabbing}</code>. +</para> +<para>At any point the <code>tabbing</code> environment has a current tab stop +pattern, a sequence of <math><var>n</var> > 0</math> tab stops, numbered 0, 1, +etc. These create <var>n</var> corresponding columns. Tab stop 0 is +always the left margin, defined by the enclosing environment. Tab +stop number <var>i</var> is set if it is assigned a horizontal +position on the page. Tab stop number <var>i</var> can only be set if +all the stops 0, &dots;, <math>i-1</math> have already been set; normally +later stops are to the right of earlier ones. +</para> +<para>By default any text typeset in a <code>tabbing</code> environment is typeset +ragged right and left-aligned on the current tab stop. Typesetting is +done in LR mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<para>The following commands can be used inside a <code>tabbing</code> environment. +They are all fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="378" mergedindex="cp">\\ <r>(tabbing)</r></indexterm>\\ <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><para>End a tabbed line and typeset it. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="379" mergedindex="cp">\= <r>(tabbing)</r></indexterm>\= <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><para>Sets a tab stop at the current position. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="380" mergedindex="cp">\> <r>(tabbing)</r></indexterm>\> <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="381" mergedindex="cp">\></indexterm></findex> +<para>Advances to the next tab stop. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="382" mergedindex="cp">\<</indexterm>\<</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="383" mergedindex="cp">\+</indexterm>\+</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="384" mergedindex="cp">\-</indexterm>\-</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="385" mergedindex="cp">\' <r>(tabbing)</r></indexterm>\' <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><para>Moves everything that you have typed so far in the current column, i.e., +everything from the most recent <code>\></code>, <code>\<</code>, <code>\'</code>, +<code>\\</code>, or <code>\kill</code> command, to the previous column and aligned +to the right, flush against the current column&textrsquo;s tab stop. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="386" mergedindex="cp">\` <r>(tabbing)</r></indexterm>\` <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><para>Allows you to put text flush right against any tab stop, including tab +stop 0. However, it can&textrsquo;t move text to the right of the last +column because there&textrsquo;s no tab stop there. The <code>\`</code> command moves +all the text that follows it, up to the <code>\\</code> or +<code>\end{tabbing}</code> command that ends the line, to the right margin +of the <code>tabbing</code> environment. There must be no <code>\></code> or +<code>\'</code> command between the <code>\`</code> and the <code>\\</code> or +<code>\end{tabbing}</code> command that ends the line. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="387" mergedindex="cp">\a <r>(tabbing)</r></indexterm>\a <r>(tabbing)</r></itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="388" mergedindex="cp">\a' <r>(acute accent in tabbing)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="389" mergedindex="cp">\a` <r>(grave accent in tabbing)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="390" mergedindex="cp">\a= <r>(macron accent in tabbing)</r></indexterm></findex> +<para>In a <code>tabbing</code> environment, the commands <code>\=</code>, <code>\'</code> and +<code>\`</code> do not produce accents as usual (<pxref label="Accents"><xrefnodename>Accents</xrefnodename></pxref>). Instead, +use the commands <code>\a=</code>, <code>\a'</code> and <code>\a`</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="391" mergedindex="cp">\kill</indexterm>\kill</itemformat></item> +</tableterm><tableitem><para>Sets tab stops without producing text. Works just like <code>\\</code> except +that it throws away the current line instead of producing output for it. +Any <code>\=</code>, <code>\+</code> or <code>\-</code> commands in that line remain in +effect. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="392" mergedindex="cp">\poptabs</indexterm>\poptabs</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="393" mergedindex="cp">\poptabs</indexterm></findex> +<para>Restores the tab stop positions saved by the last <code>\pushtabs</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="394" mergedindex="cp">\pushtabs</indexterm>\pushtabs</itemformat></item> +</tableterm><tableitem><para>Saves all current tab stop positions. Useful for temporarily changing +tab stop positions in the middle of a <code>tabbing</code> environment. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="395" mergedindex="cp">\tabbingsep</indexterm>\tabbingsep</itemformat></item> +</tableterm><tableitem><para>Distance of the text moved by <code>\'</code> to left of current tab stop. +</para> +</tableitem></tableentry></ftable> + +<para>This example typesets a Pascal function: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabbing} +function \= fact(n : integer) : integer;\\ + \> begin \= \+ \\ + \> if \= n > 1 then \+ \\ + fact := n * fact(n-1) \- \\ + else \+ \\ + fact := 1; \-\- \\ + end;\\ +\end{tabbing} +</pre></example> + +<noindent></noindent> +<para>The output looks like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">function fact(n : integer) : integer; + begin + if n > 1 then + fact := n * fact(n-1); + else + fact := 1; + end; +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="304"><r>package</r>, <code>algorithm2e</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="305"><code>algorithm2e</code> <r>package</r></indexterm></cindex> + <cindex index="cp" spaces=" "><indexterm index="cp" number="306"><r>package</r>, <code>listings</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="307"><code>listings</code> <r>package</r></indexterm></cindex> + <cindex index="cp" spaces=" "><indexterm index="cp" number="308"><r>package</r>, <code>minted</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="309"><code>minted</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="310"><r>package</r>, <code>fancyvrb</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="311"><code>fancyvrb</code> <r>package</r></indexterm></cindex> + +<noindent></noindent> +<para>This example is just for illustration of the environment. To actually +typeset computer code in typewriter like this, a verbatim environment +(<pxref label="verbatim"><xrefnodename>verbatim</xrefnodename></pxref>) would normally be best. For pretty-printed code, +there are quite a few packages, including <code>algorithm2e</code>, +<code>fancyvrb</code>, <code>listings</code>, and <code>minted</code>. +</para> + +</section> +<node name="table" spaces=" "><nodename>table</nodename><nodenext automatic="on">tabular</nodenext><nodeprev automatic="on">tabbing</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>table</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="396" mergedindex="cp"><r>environment</r>, <code>table</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="397" mergedindex="cp"><code>table</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="312">tables, creating</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="313">creating tables</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{table}[<var>placement</var>] + <var>table body</var> + \caption[<var>loftitle</var>]{<var>title</var>} % optional + \label{<var>label}</var> % also optional +\end{table} +</pre></example> + +<para>A class of floats (<pxref label="Floats"><xrefnodename>Floats</xrefnodename></pxref>). 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 <code>table</code> environment contains a <code>tabular</code> +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>but you can put many different kinds of content in a <code>table</code>, +including text, &latex; commands, etc. +</para> +<para>For the possible values of <var>placement</var> and their effect on the +float placement algorithm, see <ref label="Floats"><xrefnodename>Floats</xrefnodename></ref>. +</para> +<para>The table body is typeset in a <code>parbox</code> of width <code>\textwidth</code>. +It can contain text, commands, graphics, etc. +</para> +<para>The label is optional; it is used for cross references (<pxref label="Cross-references"><xrefnodename>Cross +references</xrefnodename></pxref>). +<findex index="fn" spaces=" "><indexterm index="fn" number="398" mergedindex="cp">\caption</indexterm></findex> +The <code>\caption</code> command is also optional. It specifies caption text +for the table. By default it is numbered. If its optional +<var>lottitle</var> is present then that text is used in the list of tables +instead of <var>title</var> (<pxref label="Table-of-contents-etc_002e"><xrefnodename>Table of contents etc.</xrefnodename></pxref>). +</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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</section> +<node name="tabular" spaces=" "><nodename>tabular</nodename><nodenext automatic="on">thebibliography</nodenext><nodeprev automatic="on">table</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>tabular</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="399" mergedindex="cp"><r>environment</r>, <code>tabular</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="400" mergedindex="cp"><code>tabular</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="314">lines in tables</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="315">lining text up in tables</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}[<var>pos</var>]{<var>cols</var>} + <var>column 1 entry</var> &<var>column 2 entry</var> ... &<var>column n entry</var> \\ + ... +\end{tabular} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular*}{<var>width</var>}[<var>pos</var>]{<var>cols</var>} + <var>column 1 entry</var> &<var>column 2 entry</var> ... &<var>column n entry</var> \\ + ... +\end{tabular*} +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{l|l} + \textit{Player name} &\textit{Career home runs} \\ + \hline + Hank Aaron &755 \\ + Babe Ruth &714 +\end{tabular} +</pre></example> + +<noindent></noindent> +<para>The output will have two left-aligned columns with a vertical bar +between them. This is specified in <code>tabular</code>&textrsquo;s argument +<code>{l|l}</code>. +<findex index="fn" spaces=" "><indexterm index="fn" number="401" mergedindex="cp">&</indexterm></findex> +Put the entries into different columns by separating them with an +ampersand, <code>&</code>. The end of each row is marked with a double +backslash, <code>\\</code>. Put a horizontal rule below a row, after a double +backslash, with <code>\hline</code>. +<findex index="fn" spaces=" "><indexterm index="fn" number="402" mergedindex="cp">\\ <r>for <code>tabular</code></r></indexterm></findex> +After the last row the <code>\\</code> is optional, unless an <code>\hline</code> +command follows to put a rule below the table. +</para> +<para>The required and optional arguments to <code>tabular</code> consist of: +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">pos</itemformat></item> +</tableterm><tableitem><para>Optional. Specifies the table&textrsquo;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: <code>t</code> +aligns the table so its top row matches the baseline of the surrounding +text, and <code>b</code> aligns on the bottom row. +</para> +<para>This only has an effect if there is other text. In the common case of a +<code>tabular</code> alone in a <code>center</code> environment this option makes +no difference. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">cols</itemformat></item> +</tableterm><tableitem><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> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">l</itemformat></item> +</tableterm><tableitem><para>A column of left-aligned items. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">r</itemformat></item> +</tableterm><tableitem><para>A column of right-aligned items. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">c</itemformat></item> +</tableterm><tableitem><para>A column of centered items. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">|</itemformat></item> +</tableterm><tableitem><para>A vertical line the full height and depth of the environment. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">&arobase;{<var>text or space</var>}</itemformat></item> +</tableterm><tableitem><para>Insert <var>text or space</var> at this location in every row. The <var>text +or space</var> material is typeset in LR mode. This text is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>If between two columns there is no &arobase;-expression then &latex;&textrsquo;s +<code>book</code>, <code>article</code>, and <code>report</code> classes will put on +either side of each column a space of length <code>\tabcolsep</code>, which by +default is 6<dmn>pt</dmn>. That is, by default adjacent columns are +separated by 12<dmn>pt</dmn> (so <code>\tabcolsep</code> is misleadingly named +since it is only half of the separation between tabular columns). In +addition, a space of 6<dmn>pt</dmn> also comes before the first column and +after the final column, unless you put a <code>&arobase;{...}</code> or <code>|</code> +there. +</para> +<para>If you override the default and use an &arobase;-expression then &latex; does +not insert <code>\tabcolsep</code> so you must insert any desired space +yourself, as in <code>&arobase;{\hspace{1em}}</code>. +</para> +<para>An empty expression <code>&arobase;{}</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{flushleft} + \begin{tabular}{&arobase;{}l} + ... + \end{tabular} +\end{flushleft} +</pre></example> + +<para>The next example shows text, a decimal point between the columns, +arranged so the numbers in the table are aligned on it. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{r&arobase;{$.$}l} + $3$ &$14$ \\ + $9$ &$80665$ +\end{tabular} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="403" mergedindex="cp">\extracolsep</indexterm></findex> +<para>An <code>\extracolsep{<var>wd</var>}</code> command in an &arobase;-expression causes an +extra space of width <var>wd</var> to appear to the left of all subsequent +columns, until countermanded by another <code>\extracolsep</code>. Unlike +ordinary intercolumn space, this extra space is not suppressed by an +&arobase;-expression. An <code>\extracolsep</code> command can be used only in an +&arobase;-expression in the <code>cols</code> argument. Below, &latex; inserts the +right amount of intercolumn space to make the entire table 4 inches +wide. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular*}{4in}{l&arobase;{\extracolsep{\fill}}l} + Seven times down, eight times up \ldots + &such is life! +\end{tabular*} +</pre></example> + +<para>To insert commands that are automatically executed before a given +column, load the <code>array</code> package and use the <code>>{...}</code> +specifier. +<!-- c xx should fully explain array, tabularx, and all other base packages... --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">p{<var>wd</var>}</itemformat></item> +</tableterm><tableitem><para>Each item in the column is typeset in a parbox of width <var>wd</var>, as if +it were the argument of a <code>\parbox[t]{wd}{...}</code> command. +</para> +<para>A line break double backslash <code>\\</code> may not appear in the item, +except inside an environment like <code>minipage</code>, <code>array</code>, or +<code>tabular</code>, or inside an explicit <code>\parbox</code>, or in the scope of +a <code>\centering</code>, <code>\raggedright</code>, or <code>\raggedleft</code> +declaration (when used in a <code>p</code>-column element these declarations +must appear inside braces, as with <code>{\centering .. \\ +..}</code>). Otherwise &latex; will misinterpret the double backslash as +ending the row. Instead, to get a line break in there use +<code>\newline</code> (<pxref label="_005cnewline"><xrefnodename>\newline</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">*{<var>num</var>}{<var>cols</var>}</itemformat></item> +</tableterm><tableitem><para>Equivalent to <var>num</var> copies of <var>cols</var>, where <var>num</var> is a +positive integer and <var>cols</var> is a list of specifiers. Thus the +specifier <code>\begin{tabular}{|*{3}{l|r}|}</code> is equivalent to +the specifier <code>\begin{tabular}{|l|rl|rl|r|}</code>. Note that +<var>cols</var> may contain another <code>*</code>-expression. +</para> +</tableitem></tableentry></table> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">width</itemformat></item> +</tableterm><tableitem><para>Required for <code>tabular*</code>, not allowed for <code>tabular</code>. Specifies +the width of the <code>tabular*</code> environment. The space between columns +should be rubber, as with <code>&arobase;{\extracolsep{\fill}}</code>, to allow +the table to stretch or shrink to make the specified width, or else you +are likely to get the <code>Underfull \hbox (badness 10000) in alignment +...</code> warning. +</para> +</tableitem></tableentry></table> + +<para>Parameters that control formatting: +<!-- c xx defaults, own node (xref from array)? --> +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="404" mergedindex="cp">\arrayrulewidth</indexterm>\arrayrulewidth</itemformat></item> +</tableterm><tableitem><anchor name="tabular-arrayrulewidth">tabular arrayrulewidth</anchor> +<para>A length that is the thickness of the rule created by <code>|</code>, +<code>\hline</code>, and <code>\vline</code> in the <code>tabular</code> and <code>array</code> +environments. The default is <samp>.4pt</samp>. Change it as in +<code>\setlength{\arrayrulewidth}{0.8pt}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="405" mergedindex="cp">\arraystretch</indexterm>\arraystretch</itemformat></item> +</tableterm><tableitem><anchor name="tabular-arraystrech">tabular arraystrech</anchor> +<para>A factor by which the spacing between rows in the <code>tabular</code> and +<code>array</code> environments is multiplied. The default is <samp>1</samp>, for +no scaling. Change it as <code>\renewcommand{\arraystretch}{1.2}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="406" mergedindex="cp">\doublerulesep</indexterm>\doublerulesep</itemformat></item> +</tableterm><tableitem><anchor name="tabular-doublerulesep">tabular doublerulesep</anchor> +<para>A length that is the distance between the vertical rules produced by the +<code>||</code> specifier. The default is <samp>2pt</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="407" mergedindex="cp">\tabcolsep</indexterm>\tabcolsep</itemformat></item> +</tableterm><tableitem><anchor name="tabular-tabcolsep">tabular tabcolsep</anchor> +<para>A length that is half of the space between columns. The default is +<samp>6pt</samp>. Change it with <code>\setlength</code>. +</para> +</tableitem></tableentry></ftable> + +<para>The following commands can be used inside the body of a <code>tabular</code> +environment, the first two inside an entry and the second two between +lines: +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\multicolumn</menunode><menudescription><pre xml:space="preserve">Make an item spanning several columns. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\vline</menunode><menudescription><pre xml:space="preserve">Draw a vertical line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\cline</menunode><menudescription><pre xml:space="preserve">Draw a horizontal line spanning some columns. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hline</menunode><menudescription><pre xml:space="preserve">Draw a horizontal line spanning all columns. +</pre></menudescription></menuentry></menu> + + +<node name="_005cmulticolumn" spaces=" "><nodename>\multicolumn</nodename><nodenext automatic="on">\vline</nodenext><nodeup automatic="on">tabular</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\multicolumn</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="408" mergedindex="cp">\multicolumn</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\multicolumn{<var>numcols</var>}{<var>cols</var>}{<var>text</var>} +</pre></example> + +<para>Make an <code>array</code> or <code>tabular</code> entry that spans several columns. +The first argument <var>numcols</var> gives the number of columns to span. +The second argument <var>cols</var> specifies the formatting of the entry, +with <code>c</code> for centered, <code>l</code> for flush left, or <code>r</code> for +flush right. The third argument <var>text</var> 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 <samp>Name</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{lccl} + \textit{ID} &\multicolumn{2}{c}{\textit{Name}} &\textit{Age} \\ + \hline + 978-0-393-03701-2 &O'Brian &Patrick &55 \\ + ... +\end{tabular} +</pre></example> + +<para>What counts as a column is: the column format specifier for the +<code>array</code> or <code>tabular</code> environment is broken into parts, where +each part (except the first) begins with <code>l</code>, <code>c</code>, <code>r</code>, +or <code>p</code>. So from <code>\begin{tabular}{|r|ccp{1.5in}|}</code> +the parts are <code>|r|</code>, <code>c</code>, <code>c</code>, +and <code>p{1.5in}|</code>. +</para> +<para>The <var>cols</var> argument overrides the <code>array</code> or <code>tabular</code> +environment&textrsquo;s intercolumn area default adjoining this multicolumn +entry. To affect that area, this argument can contain vertical bars +<code>|</code> indicating the placement of vertical rules, and <code>&arobase;{...}</code> +expressions. Thus if <var>cols</var> is <samp>|c|</samp> 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>Before the first entry the output will not have a vertical rule because +the <code>\multicolumn</code> has the <var>cols</var> specifier <samp>r</samp> with no +initial vertical bar. Between entry one and entry two there will be a +vertical rule; although the first <var>cols</var> does not have an ending +vertical bar, the second <var>cols</var> does have a starting one. Between +entry two and entry three there is a single vertical rule; despite that +the <var>cols</var> in both of the surrounding <code>multicolumn</code>&textrsquo;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 +<var>cols</var> in the entry three <code>\multicolumn</code> 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 <var>numcols</var> can be 1. Besides giving +the ability to change the horizontal alignment, this also is useful to +override for one row the <code>tabular</code> definition&textrsquo;s default intercolumn +area specification, including the placement of vertical rules. +</para> +<para>In the example below, in the <code>tabular</code> definition the first column +is specified to default to left justified but in the first row the entry +is centered with <code>\multicolumn{1}{c}{\textsc{Period}}</code>. +Also in the first row, the second and third columns are spanned by a +single entry with <code>\multicolumn{2}{c}{\textsc{Span}}</code>, +overriding the specification to center those two columns on the page +range en-dash. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{l|r&arobase;{--}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} +</pre></example> + +<noindent></noindent> +<para>Although the <code>tabular</code> specification by default puts a vertical +rule between the first and second columns, no such vertical rule appears +in the first row here. That&textrsquo;s because there is no vertical bar in the +<var>cols</var> part of the first row&textrsquo;s first <code>\multicolumn</code> command. +</para> + +</subsection> +<node name="_005cvline" spaces=" "><nodename>\vline</nodename><nodenext automatic="on">\cline</nodenext><nodeprev automatic="on">\multicolumn</nodeprev><nodeup automatic="on">tabular</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\vline</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="409" mergedindex="cp">\vline</indexterm></findex> +<para>Draw a vertical line in a <code>tabular</code> or <code>array</code> environment +extending the full height and depth of an entry&textrsquo;s row. Can also be +used in an &arobase;-expression, although its synonym vertical +bar <code>|</code> is more common. This command is rarely used in the +body of a table; typically a table&textrsquo;s vertical lines are specified in +<code>tabular</code>&textrsquo;s <var>cols</var> argument and overridden as needed with +<code>\multicolumn</code> (<pxref label="tabular"><xrefnodename>tabular</xrefnodename></pxref>). +</para> +<para>The example below illustrates some pitfalls. In the first row&textrsquo;s second +entry the <code>\hfill</code> moves the <code>\vline</code> 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 <code>{c|cc}</code> specifier coming before the +one produced by the <code>\vline\hfill</code>. In contrast, the first row&textrsquo;s +third entry shows the usual way to put a vertical bar between two +columns. In the second row, the <code>ghi</code> is the widest entry in its +column so in the <code>\vline\hfill</code> the <code>\hfill</code> has no effect and +the vertical line in that entry appears immediately next to the +<code>g</code>, with no whitespace. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{c|cc} + x &\vline\hfill y &\multicolumn{1}{|r}{z} \\ % row 1 + abc &def &\vline\hfill ghi % row 2 +\end{tabular} +</pre></example> + + +</subsection> +<node name="_005ccline" spaces=" "><nodename>\cline</nodename><nodenext automatic="on">\hline</nodenext><nodeprev automatic="on">\vline</nodeprev><nodeup automatic="on">tabular</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\cline</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="410" mergedindex="cp">\cline</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cline{<var>i</var>-<var>j</var>} +</pre></example> + +<para>In an <code>array</code> or <code>tabular</code> environment, draw a horizontal rule +beginning in column <var>i</var> and ending in column <var>j</var>. The +dash, <code>-</code>, must appear in the mandatory argument. To span a single +column use the number twice, as with <code>\cline{2-2}</code>. +</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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{llrr} + a &b &c &d \\ \cline{1-1} \cline{3-4} + e &f &g &h +\end{tabular} +</pre></example> + + +</subsection> +<node name="_005chline" spaces=" "><nodename>\hline</nodename><nodeprev automatic="on">\cline</nodeprev><nodeup automatic="on">tabular</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\hline</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="411" mergedindex="cp">\hline</indexterm></findex> + +<para>Draw a horizontal line the width of the enclosing <code>tabular</code> or +<code>array</code> environment. It&textrsquo;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 <code>\hline</code>, the +<code>tabular</code> second row&textrsquo;s line ending double backslash <code>\\</code> +is required. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{ll} \hline\hline + Baseball &Red Sox \\ + Basketball &Celtics \\ \hline +\end{tabular} +</pre></example> + + +</subsection> +</section> +<node name="thebibliography" spaces=" "><nodename>thebibliography</nodename><nodenext automatic="on">theorem</nodenext><nodeprev automatic="on">tabular</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>thebibliography</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="412" mergedindex="cp"><r>environment</r>, <code>thebibliography</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="413" mergedindex="cp"><code>thebibliography</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="316">bibliography, creating (manually)</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{thebibliography}{<var>widest-label</var>} + \bibitem[<var>label</var>]{<var>cite_key}</var> + ... +\end{thebibliography} +</pre></example> + +<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. <xref label="Using-BibTeX"><xrefnodename>Using BibTeX</xrefnodename></xref> +for a more sophisticated approach. +</para> +<para>This shows the environment with two entries. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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} +</pre></example> + +<noindent></noindent> +<para>This styles the first reference as <samp>[1] Leslie ...</samp>, and so that +<code>\cite{latexdps}</code> produces the matching <samp>... based on [1]</samp>. +The second <code>\cite</code> produces <samp>[1, 2]</samp>. You must compile the +document twice to resolve these references. +</para> +<para>The mandatory argument <var>widest-label</var> is text that, when typeset, is +as wide as the widest item label produced by the <code>\bibitem</code> +commands. The tradition is to use <code>9</code> for bibliographies with less +than 10 references, <code>99</code> for ones with less than 100, etc. +</para> +<para>The bibliographic list is headed by a title such as <samp>Bibliography</samp>. +To change it there are two cases. In the <file>book</file> and <file>report</file> +classes, where the top level sectioning is <code>\chapter</code> and the +default title is <samp>Bibliography</samp>, that title is in the macro +<code>\bibname</code>. For <file>article</file>, where the class&textrsquo;s top level +sectioning is <code>\section</code> and the default is <samp>References</samp>, the +title is in macro <code>\refname</code>. Change it by redefining the command, +as with <code>\renewcommand{\refname}{Cited references}</code> after +<code>\begin{document}</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="317"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="318"><code>babel</code> <r>package</r></indexterm></cindex> + +<para>Language support packages such as <file>babel</file> will automatically +redefine <code>\refname</code> or <code>\bibname</code> to fit the selected +language. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\bibitem</menunode><menudescription><pre xml:space="preserve">Specify a bibliography item. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\cite</menunode><menudescription><pre xml:space="preserve">Refer to a bibliography item. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\nocite</menunode><menudescription><pre xml:space="preserve">Include an item in the bibliography. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Using BibTeX</menunode><menudescription><pre xml:space="preserve">Automatic generation of bibliographies. +</pre></menudescription></menuentry></menu> + + +<node name="_005cbibitem" spaces=" "><nodename>\bibitem</nodename><nodenext automatic="on">\cite</nodenext><nodeup automatic="on">thebibliography</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\bibitem</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="414" mergedindex="cp">\bibitem</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\bibitem{<var>cite_key</var>} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\bibitem[<var>label</var>]{<var>cite_key</var>} +</pre></example> + +<para>Generate an entry labeled by <var>label</var>. The default is for &latex; to +generates a number using the <code>enumi</code> counter. The <dfn>citation key</dfn> +<cindex index="cp" spaces=" "><indexterm index="cp" number="319">citation key</indexterm></cindex> +<var>cite_key</var> is a string of +letters, numbers, and punctuation symbols (but not comma). +</para> +<para><xref label="thebibliography"><xrefnodename>thebibliography</xrefnodename></xref> for an example. +</para> +<para>The optional <var>label</var> changes the default label from an integer to the +given string. With this +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>the first entry will be styled as <samp>[Lamport 1993] Leslie ...</samp> (The +amount of horizontal space that &latex; leaves for the label depends on +the <var>widest-label</var> argument of the <code>thebibliography</code> +environment; see <ref label="thebibliography"><xrefnodename>thebibliography</xrefnodename></ref>.) Similarly, <code>... based on +\cite{latexdps}</code> will produce <samp>... based on [Lamport 1994]</samp>. +</para> +<para>If you mix <code>\bibitem</code> entries having a <var>label</var> with those that +do not then &latex; will number the unlabelled ones sequentially. In +the example above the <code>texbook</code> entry will appear as <samp>[1] +Donald ...</samp>, despite that it is the second entry. +</para> +<para>If you use the same <var>cite_key</var> twice then you get <samp>LaTeX +Warning: There were multiply-defined labels</samp>. +</para> +<para>Under the hood, &latex; remembers the <var>cite_key</var> and <var>label</var> +information because <code>\bibitem</code> writes it to the auxiliary file +<file><var>filename</var>.aux</file>. For instance, the above example causes +<code>\bibcite{latexdps}{Lamport, 1993}</code> and +<code>\bibcite{texbook}{1}</code> to appear in that file. The <file>.aux</file> +file is read by the <code>\begin{document}</code> command and then the +information is available for <code>\cite</code> 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 <code>\bibitem</code> or +change its <var>cite_key</var> you may get <samp>LaTeX Warning: Label(s) may +have changed. Rerun to get cross-references right</samp>. Fix it by +recompiling. +</para> + +</subsection> +<node name="_005ccite" spaces=" "><nodename>\cite</nodename><nodenext automatic="on">\nocite</nodenext><nodeprev automatic="on">\bibitem</nodeprev><nodeup automatic="on">thebibliography</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\cite</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="415" mergedindex="cp">\cite</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cite{<var>keys</var>} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cite[<var>subcite</var>]{<var>keys</var>} +</pre></example> + +<para>Generate as output a citation to the references associated with +<var>keys</var>. The mandatory <var>keys</var> is a citation key, or a +comma-separated list of citation keys (<pxref label="_005cbibitem"><xrefnodename>\bibitem</xrefnodename></pxref>). +</para> +<para>This +</para> +<example endspaces=" "> +<pre xml:space="preserve">The ultimate source is \cite{texbook}. + ... +\begin{thebibliography} +\bibitem{texbook} + Donald Ervin Knuth. + \textit{The \TeX book}. + Addison-Wesley, Reading, Massachusetts, 1983. +\end{thebibliography} +</pre></example> + +<noindent></noindent> +<para>produces output like <samp>... source is [1]</samp>. (You can change the +appearance of the citation with bibliography styles. More is in +<ref label="Using-BibTeX"><xrefnodename>Using BibTeX</xrefnodename></ref>.) +</para> +<para>The optional argument <var>subcite</var> is appended to the citation. For +example, <code>See 14.3 in \cite[p.~314]{texbook}</code> might produce +<samp>See 14.3 in [1, p. 314]</samp>. +</para> +<para>In addition to what appears in the output, <code>\cite</code> writes +information to the auxiliary file <file><var>filename</var>.aux</file>. For +instance, <code>\cite{latexdps}</code> writes <samp>\citation{latexdps}</samp> +to that file. This information is used by Bib&tex; to include in your +reference list only those works that you have actually cited; see +<ref label="_005cnocite"><xrefnodename>\nocite</xrefnodename></ref> also. +</para> +<para>If <var>keys</var> is not in your bibliography information then you get +<samp>LaTeX Warning: There were undefined references</samp>, 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 +<code>\cite{texbok}</code> 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 <file>.aux</file> file (<pxref label="_005cbibitem"><xrefnodename>\bibitem</xrefnodename></pxref>) then +the fix may be to run &latex; again. +</para> + +</subsection> +<node name="_005cnocite" spaces=" "><nodename>\nocite</nodename><nodenext automatic="on">Using BibTeX</nodenext><nodeprev automatic="on">\cite</nodeprev><nodeup automatic="on">thebibliography</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\nocite</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="416" mergedindex="cp">\nocite</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><code>\nocite{<var>keys</var>}</code> +</pre></example> + +<para>Produces no output but writes <var>keys</var> to the auxiliary file +<file><var>doc-filename</var>.aux</file>. +</para> +<para>The mandatory argument <var>keys</var> is a comma-separated list of one or +more citation keys (<pxref label="_005cbibitem"><xrefnodename>\bibitem</xrefnodename></pxref>). This information is used by +Bib&tex; to include these works in your reference list even though you +have not cited them (<pxref label="_005ccite"><xrefnodename>\cite</xrefnodename></pxref>). +</para> + +</subsection> +<node name="Using-BibTeX" spaces=" "><nodename>Using BibTeX</nodename><nodeprev automatic="on">\nocite</nodeprev><nodeup automatic="on">thebibliography</nodeup></node> +<subsection spaces=" "><sectiontitle>Using Bib&tex;</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="320">using Bib&tex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="321">bib&tex;, using</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="322">bibliography, creating (automatically)</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="417" mergedindex="cp">\bibliographystyle</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="418" mergedindex="cp">\bibliography</indexterm></findex> + +<para>As described in <code>thebibliography</code> (<pxref label="thebibliography"><xrefnodename>thebibliography</xrefnodename></pxref>), 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&textrsquo;t use <code>thebibliography</code> +(<pxref label="thebibliography"><xrefnodename>thebibliography</xrefnodename></pxref>). Instead, include these lines. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\bibliographystyle{<var>bibstyle</var>} +\bibliography{<var>bibfile1</var>, <var>bibfile2</var>, ...} +</pre></example> + +<noindent></noindent> +<para>The <var>bibstyle</var> refers to a file <file><var>bibstyle</var>.bst</file>, which +defines how your citations will look. The standard <var>bibstyle</var>&textrsquo;s +distributed with Bib&tex; are: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">alpha</itemformat></item> +</tableterm><tableitem><para>Labels are formed from name of author and year of publication. +The bibliographic items are sorted alphabetically. +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">plain</itemformat></item> +</tableterm><tableitem><para>Labels are integers. +Sort the bibliographic items alphabetically. +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">unsrt</itemformat></item> +</tableterm><tableitem><para>Like <code>plain</code>, but entries are in order of citation. +</para></tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">abbrv</itemformat></item> +</tableterm><tableitem><para>Like <code>plain</code>, but more compact labels. +</para></tableitem></tableentry></table> + +<noindent></noindent> <para>Many, many other Bib&tex; style files exist, +tailored to the demands of various publications. See CTAN&textrsquo;s listing +<url><urefurl>http://mirror.ctan.org/biblio/bibtex/contrib</urefurl></url>. +</para> +<para>The <code>\bibliography</code> command is what actually produces the +bibliography. Its argument is a comma-separated list, referring to +files named <file><var>bibfile1</var>.bib</file>, <file><var>bibfile2</var>.bib</file>, +&dots; These contain your database in Bib&tex; format. This shows a +typical couple of entries in that format. +</para> +<example endspaces=" "> +<pre xml:space="preserve">&arobase;book{texbook, + title = {The {{\TeX}}book}, + author = {D.E. Knuth}, + isbn = {0201134489}, + series = {Computers \& typesetting}, + year = {1983}, + publisher = {Addison-Wesley} +} +&arobase;book{sexbook, + author = {W.H. Masters and V.E. Johnson}, + title = {Human Sexual Response}, + year = {1966}, + publisher = {Bantam Books} +} +</pre></example> + +<para>Only the bibliographic entries referred to via <code>\cite</code> and +<code>\nocite</code> will be listed in the document&textrsquo;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> + +</subsection> +</section> +<node name="theorem" spaces=" "><nodename>theorem</nodename><nodenext automatic="on">titlepage</nodenext><nodeprev automatic="on">thebibliography</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>theorem</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="419" mergedindex="cp"><r>environment</r>, <code>theorem</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="420" mergedindex="cp"><code>theorem</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="323">theorems, typesetting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{theorem} + <var>theorem body</var> +\end{theorem} +</pre></example> + +<para>Produces <samp>Theorem <var>n</var></samp> in boldface followed by <var>theorem +body</var> in italics. The numbering possibilities for <var>n</var> are described under +<code>\newtheorem</code> (<pxref label="_005cnewtheorem"><xrefnodename>\newtheorem</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="324"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="325"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="326"><r>package</r>, <code>amsthm</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="327"><code>amsthm</code> <r>package</r></indexterm></cindex> + +<para>Most new documents use the packages <code>amsthm</code> and <code>amsmath</code> +from the American Mathematical Society. Among other things these +packages include a large number of options for theorem environments, +such as styling options. +</para> + +</section> +<node name="titlepage" spaces=" "><nodename>titlepage</nodename><nodenext automatic="on">verbatim</nodenext><nodeprev automatic="on">theorem</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>titlepage</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="421" mergedindex="cp"><r>environment</r>, <code>titlepage</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="422" mergedindex="cp"><code>titlepage</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="328">making a title page</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="329">title pages, creating</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{titlepage} + ... text and spacing ... +\end{titlepage} +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>To instead produce a standard title page without a <code>titlepage</code> +environment, use <code>\maketitle</code> (<pxref label="_005cmaketitle"><xrefnodename>\maketitle</xrefnodename></pxref>). +</para> + +</section> +<node name="verbatim" spaces=" "><nodename>verbatim</nodename><nodenext automatic="on">verse</nodenext><nodeprev automatic="on">titlepage</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>verbatim</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="423" mergedindex="cp"><r>environment</r>, <code>verbatim</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="424" mergedindex="cp"><code>verbatim</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="330">verbatim text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="331">simulating typed text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="332">typed text, simulating</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="333">code, typesetting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="334">computer programs, typesetting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{verbatim} +<var>literal-text</var> +\end{verbatim} +</pre></example> + +<para>A paragraph-making environment in which &latex; produces as output +exactly what you type as input. For instance inside <var>literal-text</var> +the backslash <code>\</code> character does not start commands, it +produces a printed <samp>\</samp>, and carriage returns and blanks are taken +literally. The output appears in a monospaced typewriter-like font +(<code>\tt</code>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{verbatim} +Symbol swearing: %&$#?&eosexcl;. +\end{verbatim} +</pre></example> + +<para>The only restriction on <code>literal-text</code> is that it cannot include +the string <code>\end{verbatim}</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="335"><r>package</r>, <code>cprotect</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="336"><code>cprotect</code> <r>package</r></indexterm></cindex> + +<para>You cannot use the verbatim environment in the argument to macros, for +instance in the argument to a <code>\section</code>. This is not the same as +commands being fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>), instead it just cannot appear +there. (But the <code>cprotect</code> package can help with this.) +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="337"><r>package</r>, <code>listings</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="338"><code>listings</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="339"><r>package</r>, <code>minted</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="340"><code>minted</code> <r>package</r></indexterm></cindex> + +<para>One common use of verbatim input is to typeset computer code. There are +packages that are an improvement the <code>verbatim</code> environment. For +instance, one improvement is to allow the verbatim inclusion of external +files, or parts of those files. Such packages include <code>listings</code>, +and <code>minted</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="341"><r>package</r>, <code>fancyvrb</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="342"><code>fancyvrb</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="343"><r>package</r>, <code>verbatimbox</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="344"><code>verbatimbox</code> <r>package</r></indexterm></cindex> + +<para>A package that provides many more options for verbatim environments is +<code>fancyvrb</code>. Another is <code>verbatimbox</code>. +</para> +<para>For a list of all the relevant packages, see CTAN. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\verb</menunode><menudescription><pre xml:space="preserve">The macro form of the <code>verbatim</code> environment. +</pre></menudescription></menuentry></menu> + + +<node name="_005cverb" spaces=" "><nodename>\verb</nodename><nodeup automatic="on">verbatim</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\verb</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="425" mergedindex="cp">\verb</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="345">verbatim text, inline</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\verb <var>char</var> <var>literal-text</var> <var>char</var> +\verb* <var>char</var> <var>literal-text</var> <var>char</var> +</pre></example> + +<para>Typeset <var>literal-text</var> as it is input, including special characters +and spaces, using the typewriter (<code>\tt</code>) font. +</para> +<para>This example shows two different invocations of <code>\verb</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">This is \verb!literally! the biggest pumpkin ever. +And this is the best squash, \verb+literally!+ +</pre></example> + +<noindent></noindent> +<para>The first <code>\verb</code> has its <var>literal-text</var> surrounded with +exclamation point, <code>!</code>. The second instead uses plus, <code>+</code>, +because the exclamation point is part of <code>literal-text</code>. +</para> +<para>The single-character delimiter <var>char</var> surrounds +<var>literal-text</var> &textmdash; it must be the same character before and +after. No spaces come between <code>\verb</code> or <code>\verb*</code> and +<var>char</var>, or between <var>char</var> and <var>literal-text</var>, or between +<var>literal-text</var> and the second occurrence of <var>char</var> (the synopsis +shows a space only to distinguish one component from the other). The +delimiter must not appear in <var>literal-text</var>. The <var>literal-text</var> +cannot include a line break. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="346">visible space</indexterm></cindex> +<para>The <code>*</code>-form differs only in that spaces are printed with a visible +space character. +<tex endspaces=" "> +</tex> +</para> +<para>The output from this will include a character showing the spaces. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The commands's first argument is \verb*!filename with extension! and ... +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="347"><r>package</r>, <code>url</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="348"><code>url</code> <r>package</r></indexterm></cindex> + +<para>For typesetting Internet addresses, urls, the package <code>url</code> +provides an option that is better than the <code>\verb</code> command, since +it allows line breaks. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="349"><r>package</r>, <code>listings</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="350"><code>listings</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="351"><r>package</r>, <code>minted</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="352"><code>minted</code> <r>package</r></indexterm></cindex> + +<para>For computer code there are many packages with advantages over +<code>\verb</code>. One is <file>listings</file>, another is <file>minted</file>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="353"><r>package</r>, <code>cprotect</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="354"><code>cprotect</code> <r>package</r></indexterm></cindex> + +<para>You cannot use <code>\verb</code> in the argument to a macro, for instance in +the argument to a <code>\section</code>. It is not a question of <code>\verb</code> +being fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>), instead it just cannot appear there. +(But the <code>cprotect</code> package can help with this.) +</para> + +</subsection> +</section> +<node name="verse" spaces=" "><nodename>verse</nodename><nodeprev automatic="on">verbatim</nodeprev><nodeup automatic="on">Environments</nodeup></node> +<section spaces=" "><sectiontitle><code>verse</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="426" mergedindex="cp"><r>environment</r>, <code>verse</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="427" mergedindex="cp"><code>verse</code> <r>environment</r></indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="355">poetry, an environment for</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{verse} + <var>line1</var> \\ + <var>line2</var> \\ + ... +\end{verse} +</pre></example> + +<para>An environment for poetry. +</para> +<para>Here are two lines from Shakespeare&textrsquo;s Romeo and Juliet. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Then plainly know my heart's dear love is set \\ +On the fair daughter of rich Capulet. +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="428" mergedindex="cp">\\ <r>for <code>verse</code></r></indexterm></findex> +<para>Separate the lines of each stanza with <code>\\</code>, and use one or more +blank lines to separate the stanzas. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The output has margins indented on the left and the right, paragraphs +are not indented, and the text is not right-justified. +</para> + +</section> +</chapter> +<node name="Line-breaking" spaces=" "><nodename>Line breaking</nodename><nodenext automatic="on">Page breaking</nodenext><nodeprev automatic="on">Environments</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Line breaking</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="356">line breaking</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="357">breaking lines</indexterm></cindex> + +<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> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\\</menunode><menudescription><pre xml:space="preserve">Start a new line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\obeycr & \restorecr</menunode><menudescription><pre xml:space="preserve">Make each input line start a new output line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newline</menunode><menudescription><pre xml:space="preserve">Break the line +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\- (hyphenation)</menunode><menudescription><pre xml:space="preserve">Insert explicit hyphenation. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\discretionary</menunode><menudescription><pre xml:space="preserve">Explicit control of the hyphen character. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\fussy & \sloppy</menunode><menudescription><pre xml:space="preserve">Be more or less particular with line breaking. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hyphenation</menunode><menudescription><pre xml:space="preserve">Tell &latex; how to hyphenate a word. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\linebreak & \nolinebreak</menunode><menudescription><pre xml:space="preserve">Forcing & avoiding line breaks. +</pre></menudescription></menuentry></menu> + + +<node name="_005c_005c" spaces=" "><nodename>\\</nodename><nodenext automatic="on">\obeycr & \restorecr</nodenext><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\\</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="429" mergedindex="cp">\\ <r>force line break</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="358">new line, starting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="359">line break, forcing</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\\ +\\[<var>morespace</var>] +</pre></example> + +<noindent></noindent> +<para>or one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\\* +\\*[<var>morespace</var>] +</pre></example> + +<para>End the current line. The optional argument <var>morespace</var> specifies +extra vertical space to be inserted before the next line. This is a +rubber length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>) 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 (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>The starred form, <code>\\*</code>, tells &latex; not to start a new page +between the two lines, by issuing a <code>\nobreak</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\title{My story: \\[0.25in] + a tale of woe} +</pre></example> + +<para>Explicit line breaks in the main text body are unusual in &latex;. In +particular, don&textrsquo;t start new paragraphs with <code>\\</code>. Instead leave a +blank line between the two paragraphs. And don&textrsquo;t put in a sequence of +<code>\\</code>&textrsquo;s to make vertical space. Instead use +<code>\vspace{<var>length</var>}</code>, or +<code>\leavevmode\vspace{<var>length</var>}</code>, or +<code>\vspace*{<var>length</var>}</code> if you want the space to not be thrown +out at the top of a new page (<pxref label="_005cvspace"><xrefnodename>\vspace</xrefnodename></pxref>). +</para> +<para>The <code>\\</code> command is mostly used outside of the main flow of text +such as in a <code>tabular</code> or <code>array</code> environment or in an +equation environment. +</para> +<para>The <code>\\</code> command is a synonym for <code>\newline</code> +(<pxref label="_005cnewline"><xrefnodename>\newline</xrefnodename></pxref>) under ordinary circumstances (an example of an +exception is the <code>p{...}</code> column in a <code>tabular</code> +environment; <pxref label="tabular"><xrefnodename>tabular</xrefnodename></pxref>). +</para> +<!-- c credit: David Carlisle https://tex.stackexchange.com/a/82666 --> +<para>The <code>\\</code> command is a macro, and its definition changes by context +so that its definition in normal text, a <code>center</code> environment, a +<code>flushleft</code> environment, and a <code>tabular</code> are all different. +In normal text when it forces a linebreak it is essentially a shorthand +for <code>\newline</code>. 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 <samp>LaTeX Error: There's no line here to end</samp> if you use +<code>\\</code> to ask for a new line, rather than to end the current line. +An example is if you have <code>\begin{document}\\</code> or, more likely, +something like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + \begin{minipage}{0.5\textwidth} + \\ + In that vertical space put your mark. + \end{minipage} +\end{center} +</pre></example> + +<noindent></noindent> +<para>Fix it by replacing the double backslash with something like +<code>\vspace{\baselineskip}</code>. +</para> + +</section> +<node name="_005cobeycr-_0026-_005crestorecr" spaces=" "><nodename>\obeycr & \restorecr</nodename><nodenext automatic="on">\newline</nodenext><nodeprev automatic="on">\\</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\obeycr</code> & <code>\restorecr</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="430" mergedindex="cp">\obeycr</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="431" mergedindex="cp">\restorecr</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="360">new line, output as input</indexterm></cindex> + +<para>The <code>\obeycr</code> command makes a return in the input file (<samp>^^M</samp>, +internally) the same as <code>\\</code>, followed by <code>\relax</code>. So each +new line in the input will also be a new line in the output. The +<code>\restorecr</code> command restores normal line-breaking behavior. +</para> +<para>This is not the way to show verbatim text or computer code. +<xref label="verbatim"><xrefnodename>verbatim</xrefnodename></xref> instead. +</para> +<para>With &latex;&textrsquo;s usual defaults, this +</para> +<example endspaces=" "> +<pre xml:space="preserve">aaa +bbb + +\obeycr +ccc +ddd + eee + +\restorecr +fff +ggg + +hhh +iii +</pre></example> + +<noindent></noindent> +<para>produces output like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve"> aaa bbb + ccc +ddd +eee + +fff ggg + hhh iii +</pre></example> + +<noindent></noindent> +<para>The indents are paragraph indents. +</para> + +</section> +<node name="_005cnewline" spaces=" "><nodename>\newline</nodename><nodenext automatic="on">\- (hyphenation)</nodenext><nodeprev automatic="on">\obeycr & \restorecr</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\newline</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="432" mergedindex="cp">\newline</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="361">new line, starting (paragraph mode)</indexterm></cindex> + +<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 +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>), the <code>\newline</code> command is equivalent to +double-backslash (<pxref label="_005c_005c"><xrefnodename>\\</xrefnodename></pxref>). This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>However, the two commands are different inside a <code>tabular</code> or +<code>array</code> environment. In a column with a specifier producing a +paragraph box such as typically <code>p{...}</code>, <code>\newline</code> 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 <code>\\</code> or its +equivalent <code>\tabularnewline</code>. +</para> +<para>This will print <samp>Name:</samp> and <samp>Address:</samp> as two lines in a +single cell of the table. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{p{1in}{\hspace{2in}}p{1in}} + Name: \newline Address: &Date: \\ \hline +\end{tabular} +</pre></example> + +<noindent></noindent> +<para>The <samp>Date:</samp> will be baseline-aligned with <samp>Name:</samp>. +</para> + +</section> +<node name="_005c_002d-_0028hyphenation_0029" spaces=" "><nodename>\- (hyphenation)</nodename><nodenext automatic="on">\discretionary</nodenext><nodeprev automatic="on">\newline</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\-</code> (discretionary hyphen)</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="433" mergedindex="cp">\- <r>(hyphenation)</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="362">hyphenation, forcing</indexterm></cindex> + +<para>Tell &latex; that it may hyphenate the word at that point. When you +insert <code>\-</code> 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 (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>&latex; is good at hyphenating and usually finds most of the correct +hyphenation points, while almost never using an incorrect one. The +<code>\-</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>Commenting out the third line and uncommenting the fourth makes a much +better fit. +</para> +<para>The <code>\-</code> command only allows &latex; to break there, it does not +require that it break there. You can insist on a split with something +like <code>Hef-\linebreak feron</code>. Of course, if you later change the +text then this forced break may look very odd, so this approach requires +care. +</para> + +</section> +<node name="_005cdiscretionary" spaces=" "><nodename>\discretionary</nodename><nodenext automatic="on">\fussy & \sloppy</nodenext><nodeprev automatic="on">\- (hyphenation)</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\discretionary</code> (generalized hyphenation point)</sectiontitle> +<cindex index="cp" spaces=" "><indexterm index="cp" number="363">hyphenation, discretionary</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="364">discretionary hyphenation</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\discretionary{<var>pre-break</var>}{<var>post-break</var>}{<var>no-break</var>} +</pre></example> + +<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 <code>\discretionary</code> appears +then &tex; puts <var>pre-break</var> at the end of the current line and puts +<var>post-break</var> at the start of the next line. If there is no line +break here then &tex; puts <var>no-break</var> +</para> +<para>In <samp>difficult</samp> the three letters <code>ffi</code> form a ligature. But +&tex; can nonetheless break between the two f&textrsquo;s with this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">di\discretionary{f-}{fi}{ffi}cult +</pre></example> + +<para>Note that users do not have to do this. It is typically handled +automatically by &tex;&textrsquo;s hyphenation algorithm. +</para> + +</section> +<node name="_005cfussy-_0026-_005csloppy" spaces=" "><nodename>\fussy & \sloppy</nodename><nodenext automatic="on">\hyphenation</nodenext><nodeprev automatic="on">\discretionary</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\fussy</code> & <code>\sloppy</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="434" mergedindex="cp">\fussy</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="435" mergedindex="cp">\sloppy</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="365">line breaks, changing</indexterm></cindex> + +<para>Declarations to make &tex; more picky or less picky about line +breaking. Declaring <code>\fussy</code> usually avoids too much space between +words, at the cost of an occasional overfull box. Conversely, +<code>\sloppy</code> avoids overfull boxes while suffering loose interword +spacing. +</para> +<para>The default is <code>\fussy</code>. Line breaking in a paragraph is +controlled by whichever declaration is current at the blank line, or +<code>\par</code>, or displayed equation ending that paragraph. So to affect +the line breaks, include that paragraph-ending material in the scope of +the command. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">sloppypar</menunode><menudescription><pre xml:space="preserve">Environment version of \sloppy command. +</pre></menudescription></menuentry></menu> + + +<node name="sloppypar" spaces=" "><nodename>sloppypar</nodename><nodeup automatic="on">\fussy & \sloppy</nodeup></node> +<subsection spaces=" "><sectiontitle><code>sloppypar</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="436" mergedindex="cp">sloppypar</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="366">sloppypar environment</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{sloppypar} + ... paragraphs ... +\end{sloppypar} +</pre></example> + +<para>Typeset the paragraphs with <code>\sloppy</code> in effect (<pxref label="_005cfussy-_0026-_005csloppy"><xrefnodename>\fussy & +\sloppy</xrefnodename></pxref>). Use this to locally adjust line breaking, to avoid +<samp>Overfull box</samp> or <samp>Underfull box</samp> errors. +</para> +<para>The example is simple. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</subsection> +</section> +<node name="_005chyphenation" spaces=" "><nodename>\hyphenation</nodename><nodenext automatic="on">\linebreak & \nolinebreak</nodenext><nodeprev automatic="on">\fussy & \sloppy</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\hyphenation</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="437" mergedindex="cp">\hyphenation</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="367">hyphenation, defining</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hyphenation{<var>word1</var> ...} +</pre></example> + +<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, <code>-</code>. +</para> +<para>Here is an example: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hyphenation{hat-er il-lit-e-ra-ti tru-th-i-ness} +</pre></example> + +<para>Use lowercase letters. &tex; will only hyphenate if the word matches +exactly. Multiple <code>\hyphenation</code> commands accumulate. +</para> + +</section> +<node name="_005clinebreak-_0026-_005cnolinebreak" spaces=" "><nodename>\linebreak & \nolinebreak</nodename><nodeprev automatic="on">\hyphenation</nodeprev><nodeup automatic="on">Line breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\linebreak</code> & <code>\nolinebreak</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="438" mergedindex="cp">\linebreak</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="439" mergedindex="cp">\nolinebreak</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="368">line breaks, forcing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="369">line breaks, preventing</indexterm></cindex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\linebreak +\linebreak[<var>zero-to-four</var>] +</pre></example> + +<noindent></noindent> +<para>or one of these. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\nolinebreak +\nolinebreak[<var>zero-to-four</var>] +</pre></example> + +<para>Encourage or discourage a line break. The optional <var>zero-to-four</var> +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, <code>\nolinebreak[1]</code> is a +suggestion that another place may be better. The higher the number, the +more insistent the request. Both commands are fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Here we tell &latex; that a good place to put a linebreak is after the +standard legal text. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\boilerplatelegal{} \linebreak[2] +We especially encourage applications from members of traditionally +underrepresented groups. +</pre></example> + +<para>When you issue <code>\linebreak</code>, the spaces in the line are stretched +out so that it extends to the right margin. <xref label="_005c_005c"><xrefnodename>\\</xrefnodename></xref> +and <ref label="_005cnewline"><xrefnodename>\newline</xrefnodename></ref> to have the spaces not stretched out. +</para> + + +</section> +</chapter> +<node name="Page-breaking" spaces=" "><nodename>Page breaking</nodename><nodenext automatic="on">Footnotes</nodenext><nodeprev automatic="on">Line breaking</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Page breaking</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="370">page breaking</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="371">breaking pages</indexterm></cindex> + +<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> +<!-- c credit: H Vogt https://tex.stackexchange.com/a/115563 --> +<para>&latex;&textrsquo;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&textrsquo;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&textrsquo;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><xref label="Layout"><xrefnodename>Layout</xrefnodename></xref> for more material that is relevant to page breaking. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\clearpage & \cleardoublepage</menunode><menudescription><pre xml:space="preserve">Start a new page; eject floats. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newpage</menunode><menudescription><pre xml:space="preserve">Start a new page. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\enlargethispage</menunode><menudescription><pre xml:space="preserve">Enlarge the current page a bit. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\pagebreak & \nopagebreak</menunode><menudescription><pre xml:space="preserve">Forcing & avoiding page breaks. +</pre></menudescription></menuentry></menu> + + +<node name="_005cclearpage-_0026-_005ccleardoublepage" spaces=" "><nodename>\clearpage & \cleardoublepage</nodename><nodenext automatic="on">\newpage</nodenext><nodeup automatic="on">Page breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\clearpage</code> & <code>\cleardoublepage</code> </sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="440" mergedindex="cp">\clearpage</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="372">flushing floats and starting a page</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="373">starting a new page and clearing floats</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="441" mergedindex="cp">\cleardoublepage</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="374">starting on a right-hand page</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\clearpage +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cleardoublepage +</pre></example> + +<para>End the current page and output all of the pending floating figures and +tables (<pxref label="Floats"><xrefnodename>Floats</xrefnodename></pxref>). 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, <code>\cleardoublepage</code> also makes the next page of +content a right-hand page, an odd-numbered page, if necessary inserting +a blank page. The <code>\clearpage</code> command is robust while +<code>\cleardoublepage</code> is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>&latex;&textrsquo;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> +<!-- c credit: https://www.tex.ac.uk/FAQ-reallyblank.html --> +<para>The <code>\cleardoublepage</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\let\origdoublepage\cleardoublepage +\newcommand{\clearemptydoublepage}{% + \clearpage + {\pagestyle{empty}\origdoublepage}% +} +</pre></example> + +<noindent></noindent> +<para>If you want &latex;&textrsquo;s standard <code>\chapter</code> command to do this then +add the line <code>\let\cleardoublepage\clearemptydoublepage</code>. +</para> +<para>The command <code>\newpage</code> (<pxref label="_005cnewpage"><xrefnodename>\newpage</xrefnodename></pxref>) also ends the current +page, but without clearing pending floats. And, if &latex; is in +two-column mode then <code>\newpage</code> ends the current column while +<code>\clearpage</code> and <code>\cleardoublepage</code> end the current page. +</para> + + +</section> +<node name="_005cnewpage" spaces=" "><nodename>\newpage</nodename><nodenext automatic="on">\enlargethispage</nodenext><nodeprev automatic="on">\clearpage & \cleardoublepage</nodeprev><nodeup automatic="on">Page breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\newpage</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="442" mergedindex="cp">\newpage</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="375">new page, starting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="376">starting a new page</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newpage +</pre></example> + +<para>End the current page. This command is robust (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>&latex;&textrsquo;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 <code>\clearpage</code> and <code>\cleardoublepage</code> also +end the current page, in addition they clear pending floats +(<pxref label="_005cclearpage-_0026-_005ccleardoublepage"><xrefnodename>\clearpage & \cleardoublepage</xrefnodename></pxref>). And, if &latex; is in +two-column mode then <code>\clearpage</code> and <code>\cleardoublepage</code> end +the current page, possibly leaving an empty column, while +<code>\newpage</code> only ends the current column. +</para> +<para>In contrast with <code>\pagebreak</code> (<pxref label="_005cpagebreak-_0026-_005cnopagebreak"><xrefnodename>\pagebreak & \nopagebreak</xrefnodename></pxref>), +the <code>\newpage</code> command will cause the new page to start right where +requested. This +</para> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<noindent></noindent> +<para>makes a new page start after <samp>continent,</samp> and the cut-off line is +not right justified. In addition, <code>\newpage</code> does not vertically +stretch out the page, as <code>\pagebreak</code> does. +</para> + +</section> +<node name="_005cenlargethispage" spaces=" "><nodename>\enlargethispage</nodename><nodenext automatic="on">\pagebreak & \nopagebreak</nodenext><nodeprev automatic="on">\newpage</nodeprev><nodeup automatic="on">Page breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\enlargethispage</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="443" mergedindex="cp">\enlargethispage</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="377">enlarge current page</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\enlargethispage{size} +\enlargethispage*{size} +</pre></example> + +<para>Enlarge the <code>\textheight</code> for the current page. The required +argument <var>size</var> must be a rigid length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). It may be +positive or negative. This command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</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> +<example endspaces=" "> +<pre xml:space="preserve">\enlargethispage{\baselineskip} +</pre></example> + +<para>The starred form <code>\enlargesthispage*</code> 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 <code>\pagebreak</code>. +</para> + +</section> +<node name="_005cpagebreak-_0026-_005cnopagebreak" spaces=" "><nodename>\pagebreak & \nopagebreak</nodename><nodeprev automatic="on">\enlargethispage</nodeprev><nodeup automatic="on">Page breaking</nodeup></node> +<section spaces=" "><sectiontitle><code>\pagebreak</code> & <code>\nopagebreak</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="444" mergedindex="cp">\pagebreak</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="445" mergedindex="cp">\nopagebreak</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="378">page break, forcing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="379">page break, preventing</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\pagebreak +\pagebreak[<var>zero-to-four</var>] +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\nopagebreak +\nopagebreak[<var>zero-to-four</var>] +</pre></example> + +<para>Encourage or discourage a page break. The optional <var>zero-to-four</var> +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 <code>\nopagebreak[1]</code> suggests to +&latex; that another spot might be preferable. The higher the number, +the more insistent the request. Both commands are fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>&latex;&textrsquo;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> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<noindent></noindent> +<para>does not give a page break at <samp>continent,</samp> but instead at +<samp>nation,</samp> since that is where &latex; breaks that line. In +addition, with <code>\pagebreak</code> the vertical space on the page is +stretched out where possible so that it extends to the normal bottom +margin. This can look strange, and if <code>\flushbottom</code> is in effect +this can cause you to get <samp>Underfull \vbox (badness 10000) has +occurred while \output is active</samp>. <xref label="_005cnewpage"><xrefnodename>\newpage</xrefnodename></xref> for a command that +does not have these effects. +</para> + +</section> +</chapter> +<node name="Footnotes" spaces=" "><nodename>Footnotes</nodename><nodenext automatic="on">Definitions</nodenext><nodeprev automatic="on">Page breaking</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Footnotes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="380">footnotes, creating</indexterm></cindex> + +<para>Place a footnote at the bottom of the current page, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">No<accent type="uml">e</accent>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.} +</pre></example> + +<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 <code>\footnotemark</code> and +the <code>\footnotetext</code> 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 (<pxref label="Using-BibTeX"><xrefnodename>Using BibTeX</xrefnodename></pxref>). +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\footnote</menunode><menudescription><pre xml:space="preserve">Insert a footnote. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\footnotemark</menunode><menudescription><pre xml:space="preserve">Insert footnote mark only. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\footnotetext</menunode><menudescription><pre xml:space="preserve">Insert footnote text only. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Footnotes in section headings</menunode><menudescription><pre xml:space="preserve">Chapter or section titles. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Footnotes in a table</menunode><menudescription><pre xml:space="preserve">Table footnotes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Footnotes of footnotes</menunode><menudescription><pre xml:space="preserve">Multiple classes of footnotes. +</pre></menudescription></menuentry></menu> + + +<node name="_005cfootnote" spaces=" "><nodename>\footnote</nodename><nodenext automatic="on">\footnotemark</nodenext><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle><code>\footnote</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="446" mergedindex="cp">\footnote</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\footnote{<var>text</var>} +\footnote[<var>number</var>]{<var>text</var>} +</pre></example> + +<para>Place a footnote <var>text</var> at the bottom of the current page. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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.''} +</pre></example> + +<para>The optional argument <var>number</var> allows you to specify the number of +the footnote. If you use this then &latex; does not increment the +<code>footnote</code> counter. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="381">footnotes, symbols instead of numbers</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="447" mergedindex="cp">\fnsymbol<r>, and footnotes</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="448" mergedindex="cp">\&arobase;fnsymbol</indexterm></findex> +<para>By default, &latex; uses arabic numbers as footnote markers. Change +this with something like +<code>\renewcommand{\thefootnote}{\fnsymbol{footnote}}</code>, which +uses a sequence of symbols (<pxref label="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"><xrefnodename>\alph \Alph \arabic \roman \Roman +\fnsymbol</xrefnodename></pxref>). 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 +<code>\setcounter{footnote}{0}</code>. +</para> +<para>&latex; determines the spacing of footnotes with two parameters. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="382">footnote parameters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="383">parameters, for footnotes</indexterm></cindex> + +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="449" mergedindex="cp">\footnoterule</indexterm>\footnoterule</itemformat></item> +</tableterm><tableitem><anchor name="footnote-footnoterule">footnote footnoterule</anchor> +<para>Produces the rule separating the main text on a page from the page&textrsquo;s +footnotes. Default dimensions in the standard document classes (except +<code>slides</code>, where it does not appear) is: vertical thickness of +<code>0.4pt</code>, and horizontal size of <code>0.4\columnwidth</code> long. +Change the rule with something like this. +</para> +<!-- c Credit egreg: https://tex.stackexchange.com/a/21917 --> +<example endspaces=" "> +<pre xml:space="preserve">\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 +</pre></example> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="450" mergedindex="cp">\footnotesep</indexterm>\footnotesep</itemformat></item> +</tableterm><tableitem><anchor name="footnote-footnotesep">footnote footnotesep</anchor> +<para>The height of the strut placed at the beginning of the footnote +(<pxref label="_005cstrut"><xrefnodename>\strut</xrefnodename></pxref>). By default, this is set to the normal strut for +<code>\footnotesize</code> fonts (<pxref label="Font-sizes"><xrefnodename>Font sizes</xrefnodename></pxref>), therefore there is no +extra space between footnotes. This is <samp>6.65pt</samp> for <samp>10pt</samp>, +<samp>7.7pt</samp> for <samp>11pt</samp>, and <samp>8.4pt</samp> for <samp>12pt</samp>. Change +it as with <code>\setlength{\footnotesep}{11pt}</code>. +</para> +</tableitem></tableentry></ftable> + +<para>The <code>\footnote</code> command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>&latex;&textrsquo;s default puts many restrictions on where you can use a +<code>\footnote</code>; for instance, you cannot use it in an argument to a +sectioning command such as <code>\chapter</code> (it can only be used in outer +paragraph mode; <pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). There are some workarounds; see +following sections. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="384">Footnotes, in a minipage</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="385">mpfootnote counter</indexterm></cindex> +<para>In a <code>minipage</code> environment the <code>\footnote</code> command uses the +<code>mpfootnote</code> counter instead of the <code>footnote</code> 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. <xref label="minipage"><xrefnodename>minipage</xrefnodename></xref> and <ref label="Footnotes-in-a-table"><xrefnodename>Footnotes in a table</xrefnodename></ref>. +</para> + +</section> +<node name="_005cfootnotemark" spaces=" "><nodename>\footnotemark</nodename><nodenext automatic="on">\footnotetext</nodenext><nodeprev automatic="on">\footnote</nodeprev><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle><code>\footnotemark</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="451" mergedindex="cp">\footnotemark</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\footnotemark +\footnotemark[<var>number</var>] +</pre></example> + +<para>Put the current footnote mark in the text. To specify associated text +for the footnote see <ref label="_005cfootnotetext"><xrefnodename>\footnotetext</xrefnodename></ref>. The optional argument +<var>number</var> causes the command to use that number to determine the +footnote mark. This command can be used in inner paragraph mode +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<para>If you use <code>\footnotemark</code> without the optional argument then it +increments the footnote counter but if you use the optional <var>number</var> +then it does not. The next example produces several consecutive footnote +markers referring to the same footnote. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The first theorem\footnote{Due to Gauss.} +and the second theorem\footnotemark[\value{footnote}] +and the third theorem.\footnotemark[\value{footnote}] +</pre></example> + +<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 (<code>\thanks</code> is a version of +<code>footnote</code>), by-hand giving the number of the footnote. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 +</pre></example> + +<para>This uses a counter to remember the footnote number. The third sentence +is followed by the same footnote marker as the first. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="386"><r>package</r>, <code>cleveref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="387"><code>cleveref</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="388"><r>package</r>, <code>hyperref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="389"><code>hyperref</code> <r>package</r></indexterm></cindex> + +<para>This example accomplishes the same by using the package <file>cleveref</file>. +</para> +<!-- c from SE user Jake http://tex.stackexchange.com/a/10116/339 --> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="390"><r>package</r>, <code>hyperref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="391"><code>hyperref</code> <r>package</r></indexterm></cindex> + +<para>It will work with the package <file>hyperref</file>. +</para> + +</section> +<node name="_005cfootnotetext" spaces=" "><nodename>\footnotetext</nodename><nodenext automatic="on">Footnotes in section headings</nodenext><nodeprev automatic="on">\footnotemark</nodeprev><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle><code>\footnotetext</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="452" mergedindex="cp">\footnotetext</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\footnotetext{<var>text</var>} +\footnotetext[<var>number</var>]{<var>text</var>} +</pre></example> + +<para>Place <var>text</var> at the bottom of the page as a footnote. It pairs with +<code>\footnotemark</code> (<pxref label="_005cfootnotemark"><xrefnodename>\footnotemark</xrefnodename></pxref>) and can come anywhere after +that command, but must appear in outer paragraph mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +The optional argument <var>number</var> changes the number of the footnote +mark. +</para> +<para><xref label="_005cfootnotemark"><xrefnodename>\footnotemark</xrefnodename></xref> and <ref label="Footnotes-in-a-table"><xrefnodename>Footnotes in a table</xrefnodename></ref> for usage +examples. +</para> + +</section> +<node name="Footnotes-in-section-headings" spaces=" "><nodename>Footnotes in section headings</nodename><nodenext automatic="on">Footnotes in a table</nodenext><nodeprev automatic="on">\footnotetext</nodeprev><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle>Footnotes in section headings</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="392">footnote, in section headings</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="393">table of contents, avoiding footnotes</indexterm></cindex> + +<para>Putting a footnote in a section heading, as in: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\section{Full sets\protect\footnote{This material due to ...}} +</pre></example> + +<noindent></noindent> +<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 <code>\section</code> +</para> +<example endspaces=" "> +<pre xml:space="preserve">\section[Please]{Please\footnote{% + Don't footnote in chapter and section headers!}} +</pre></example> + +<noindent></noindent> +<para>No <code>\protect</code> is needed in front of <code>\footnote</code> here because +what gets moved to the table of contents is the optional argument. +</para> + +</section> +<node name="Footnotes-in-a-table" spaces=" "><nodename>Footnotes in a table</nodename><nodenext automatic="on">Footnotes of footnotes</nodenext><nodeprev automatic="on">Footnotes in section headings</nodeprev><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle>Footnotes in a table</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="394">footnote, in a table</indexterm></cindex> + +<para>Inside a <code>tabular</code> or <code>array</code> environment the <code>\footnote</code> +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 +<code>minipage</code> environment as here (<pxref label="minipage"><xrefnodename>minipage</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>Inside a <code>minipage</code>, footnote marks are lowercase letters. Change +that with something like +<code>\renewcommand{\thempfootnote}{\arabic{mpfootnote}}</code> +(<pxref label="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"><xrefnodename>\alph \Alph \arabic \roman \Roman \fnsymbol</xrefnodename></pxref>). +</para> +<para>The footnotes in the prior example appear at the bottom of the +<code>minipage</code>. To have them appear at the bottom of the main page, as +part of the regular footnote sequence, use the <code>\footnotemark</code> and +<code>\footnotetext</code> pair and make a new counter. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>For a floating <code>table</code> environment (<pxref label="table"><xrefnodename>table</xrefnodename></pxref>), use the +<file>tablefootnote</file> package. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The footnote appears at the page bottom and is numbered in sequence with +other footnotes. +</para> + +</section> +<node name="Footnotes-of-footnotes" spaces=" "><nodename>Footnotes of footnotes</nodename><nodeprev automatic="on">Footnotes in a table</nodeprev><nodeup automatic="on">Footnotes</nodeup></node> +<section spaces=" "><sectiontitle>Footnotes of footnotes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="395">footnote, of a footnote</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="396"><r>package</r>, <code>bigfoot</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="397"><code>bigfoot</code> <r>package</r></indexterm></cindex> + +<para>Particularly in the humanities, authors can have multiple classes of +footnotes, including having footnotes of footnotes. The package +<file>bigfoot</file> extends &latex;&textrsquo;s default footnote mechanism in many +ways, including allow these two, as in this example. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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.}} +</pre></example> + + +</section> +</chapter> +<node name="Definitions" spaces=" "><nodename>Definitions</nodename><nodenext automatic="on">Counters</nodenext><nodeprev automatic="on">Footnotes</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Definitions</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="398">definitions</indexterm></cindex> + +<para>&latex; has support for making new commands of many different kinds. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\newcommand & \renewcommand</menunode><menudescription><pre xml:space="preserve">(Re)define a new command. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\providecommand</menunode><menudescription><pre xml:space="preserve">Define a new command, if name not used. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\makeatletter & \makeatother</menunode><menudescription><pre xml:space="preserve">Change the status of the at-sign character. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\&arobase;ifstar</menunode><menudescription><pre xml:space="preserve">Define your own commands with *-variants. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newcounter</menunode><menudescription><pre xml:space="preserve">Define a new counter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newlength</menunode><menudescription><pre xml:space="preserve">Define a new length. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newsavebox</menunode><menudescription><pre xml:space="preserve">Define a new box. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newenvironment & \renewenvironment</menunode><menudescription><pre xml:space="preserve">Define a new environment. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newtheorem</menunode><menudescription><pre xml:space="preserve">Define a new theorem-like environment. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\newfont</menunode><menudescription><pre xml:space="preserve">Define a new font name. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\protect</menunode><menudescription><pre xml:space="preserve">Using tricky commands. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\ignorespaces & \ignorespacesafterend</menunode><menudescription><pre xml:space="preserve">Discard extra spaces. +</pre></menudescription></menuentry></menu> + + +<node name="_005cnewcommand-_0026-_005crenewcommand" spaces=" "><nodename>\newcommand & \renewcommand</nodename><nodenext automatic="on">\providecommand</nodenext><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newcommand</code> & <code>\renewcommand</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="453" mergedindex="cp">\newcommand</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="399">commands, defining new ones</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="400">commands, redefining</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="401">defining a new command</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="402">new commands, defining</indexterm></cindex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\<var>cmd</var>}{<var>defn</var>} +\newcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\newcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +\newcommand*{\<var>cmd</var>}{<var>defn</var>} +\newcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\newcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +</pre></example> + +<noindent></noindent> +<para>or one of these. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\renewcommand{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\renewcommand{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +\renewcommand*{\<var>cmd</var>}{<var>defn</var>} +\renewcommand*{\<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\renewcommand*{\<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +</pre></example> + +<para>Define or redefine a command. See also the discussion of +<code>\DeclareRobustCommand</code> in <ref label="Class-and-package-commands"><xrefnodename>Class and package commands</xrefnodename></ref>. +<cindex index="cp" spaces=" "><indexterm index="cp" number="403">starred form, defining new commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="404">*-form, defining new commands</indexterm></cindex> +The starred form of these two requires that the arguments not contain +multiple paragraphs of text (in plain &tex; terms that it not be +<code>\long</code>). +</para> +<para>These are the parameters: +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">cmd</itemformat></item> +</tableterm><tableitem> +<para>Required; the command name. It must begin with a backslash, <code>\</code>, +and must not begin with the four letter string <code>\end</code>. For +<code>\newcommand</code>, it must not be already defined. For +<code>\renewcommand</code>, this name must already be defined. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">nargs</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">optargdefault</itemformat></item> +</tableterm><tableitem><para>Optional; if this argument is present then the first argument of +<code>\<var>cmd</var></code> is optional, with default value <var>optargdefault</var> +(which may be the empty string). If this argument is not present then +<code>\<var>cmd</var></code> does not take an optional argument. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="405">positional parameter</indexterm></cindex> +<para>That is, if <code>\<var>cmd</var></code> is used with square brackets, as in +<code>\<var>cmd</var>[<var>optval</var>]{...}...</code>, then within <var>defn</var> the +parameter <code>#1</code> is set to the value of <var>optval</var>. On the +other hand, if <code>\<var>cmd</var></code> is called without the square brackets +then within <var>defn</var> the parameter <code>#1</code> is set to the value of +<var>optargdefault</var>. In either case, the required arguments start with +<code>#2</code>. +</para> +<para>Omitting <code>[<var>optargdefault</var>]</code> is different from having the +square brackets with no contents, as in <code>[]</code>. The former sets +<code>#1</code> to the value of <var>optargdefault</var>; the latter sets <code>#1</code> +to the empty string. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">defn</itemformat></item> +</tableterm><tableitem><para>Required; the text to be substituted for every occurrence of +<code>\<var>cmd</var></code>. The parameters <code>#1</code>, <code>#2</code>, +... <code>#<var>nargs</var></code> 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&textrsquo;t exercise the option). +</para> +</tableitem></tableentry></table> + +<para>&tex; ignores spaces in the source following an alphabetic control +sequence, as in <samp>\cmd </samp>. If you actually want a space there, one +solution is to type <code>{}</code> after the command (<samp>\cmd{} </samp>, and +another solution is to use an explicit control space (<samp>\cmd\ </samp>). +</para> +<para>A simple example of defining a new command: +<code>\newcommand{\RS}{Robin Smith}</code> results in <code>\RS</code> being +replaced by the longer text. Redefining an existing command is similar: +<code>\renewcommand{\qedsymbol}{{\small QED}}</code>. +</para> +<para>If you try to define a command and the name has already been used then +you get something like <samp>LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual</samp>. If you try +to redefine a command and the name has not yet been used then you get +something like <samp>LaTeX Error: \hank undefined</samp>. +</para> +<para>Here the first command definition has no arguments, and the second has +one required argument. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\student}{Ms~O'Leary} +\newcommand{\defref}[1]{Definition~\ref{#1}} +</pre></example> + +<noindent></noindent> +<para>Use the first as in <code>I highly recommend \student{} to you</code>. The +second has a variable, so that <code>\defref{def:basis}</code> expands to +<code>Definition~\ref{def:basis}</code>, which ultimately expands to +something like <samp>Definition~3.14</samp>. +</para> +<para>Similarly, but with two required arguments: +<code>\newcommand{\nbym}[2]{$#1 \times #2$}</code> is invoked as +<code>\nbym{2}{k}</code>. +</para> +<para>This example has an optional argument. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\salutation}[1][Sir or Madam]{Dear #1:} +</pre></example> + +<noindent></noindent> +<para>Then <code>\salutation</code> gives <samp>Dear Sir or Madam:</samp> while +<code>\salutation[John]</code> gives <samp>Dear John:</samp>. And +<code>\salutation[]</code> gives <samp>Dear :</samp>. +</para> +<para>This example has an optional argument and two required arguments. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\lawyers}[3][company]{#2, #3, and~#1} +I employ \lawyers[Howe]{Dewey}{Cheatem}. +</pre></example> + +<noindent></noindent> +<para>The output is <samp>I employ Dewey, Cheatem, and Howe</samp>. The optional +argument, the <code>Howe</code>, is associated with <code>#1</code>, while +<code>Dewey</code> and <code>Cheatem</code> are associated with <code>#2</code> +and <code>#3</code>. Because of the optional argument, +<code>\lawyers{Dewey}{Cheatem}</code> will give the output <samp>I employ +Dewey, Cheatem, and company</samp>. +</para> +<para>The braces around <var>defn</var> do not define a group, that is, they do not +delimit the scope of the result of expanding <var>defn</var>. For example, +with <code>\newcommand{\shipname}[1]{\it #1}</code>, in this sentence, +</para> +<example endspaces=" "> +<pre xml:space="preserve">The \shipname{Monitor} met the \shipname{Merrimac}. +</pre></example> + +<noindent></noindent> +<para>the words <samp>met the</samp> would incorrectly be in italics. The solution +is to put another pair of braces inside the definition: +<code>\newcommand{\shipname}[1]{{\it #1}}</code>. +</para> + +</section> +<node name="_005cprovidecommand" spaces=" "><nodename trailingspaces=" ">\providecommand</nodename><nodenext automatic="on">\makeatletter & \makeatother</nodenext><nodeprev automatic="on">\newcommand & \renewcommand</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\providecommand</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="454" mergedindex="cp">\providecommand</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="406">commands, defining new ones</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="407">defining a new command</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="408">new commands, defining</indexterm></cindex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\providecommand{<var>cmd</var>}{<var>defn</var>} +\providecommand{<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\providecommand{<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +\providecommand*{<var>cmd</var>}{<var>defn</var>} +\providecommand*{<var>cmd</var>}[<var>nargs</var>]{<var>defn</var>} +\providecommand*{<var>cmd</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>defn</var>} +</pre></example> + +<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 <code>\newcommand</code>. If a command of this name already exists then +this definition does nothing. This is particularly useful in a file +that may be loaded more than once, such as a style file. +<xref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & \renewcommand</xrefnodename></xref> for the description of the arguments. +</para> +<para>This example +</para> +<example endspaces=" "> +<pre xml:space="preserve">\providecommand{\myaffiliation}{Saint Michael's College} +\providecommand{\myaffiliation}{Saint Michael's College} +From \myaffiliation. +</pre></example> + +<noindent></noindent> +<para>outputs <samp>From Saint Michael's College</samp>. Unlike <code>\newcommand</code>, +the repeated use of <code>\providecommand</code> does not give an error. +</para> + +</section> +<node name="_005cmakeatletter-_0026-_005cmakeatother" spaces=" "><nodename>\makeatletter & \makeatother</nodename><nodenext automatic="on">\&arobase;ifstar</nodenext><nodeprev automatic="on">\providecommand</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\makeatletter</code> & <code>\makeatother</code></sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makeatletter + ... definition of commands with &arobase; in their name .. +\makeatother +</pre></example> + +<para>Use this pair when you redefine &latex; commands that are named with an +at-sign character <samp><code>&arobase;</code></samp>. The <code>\makeatletter</code> +declaration makes the at-sign character have the category code of a +letter, code 11. The <code>\makeatother</code> 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 +<cindex index="cp" spaces=" "><indexterm index="cp" number="409">catcode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="410">character category code</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="411">category code, character</indexterm></cindex> +<dfn>catcode</dfn>. For instance, it assigns the backslash +character <samp><code>\</code></samp> 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;&textrsquo;s source code has the convention that some commands use +<code>&arobase;</code> 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 <code>\makeatletter</code> and <code>\makeatother</code> changes the +default code and then changes it back. Use them inside a <file>.tex</file> +file, in the preamble, when you are defining or redefining commands +named with <code>&arobase;</code>, by having them surround your definition. Don&textrsquo;t +use these inside <file>.sty</file> or <file>.cls</file> files since the +<code>\usepackage</code> and <code>\documentclass</code> commands already arrange +that the at-sign has the character code of a letter, catcode 11. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="412"><r>package</r>, <code>macros2e</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="413"><code>macros2e</code> <r>package</r></indexterm></cindex> + +<para>For a comprehensive list of macros with an at-sign in their names see +<url><urefurl>http://ctan.org/pkg/macros2e</urefurl></url>. +</para> +<para>In this example the class file has a command +<code>\thesis&arobase;universityname</code> that the user wants to change. These +three lines should go in the preamble, before the +<code>\begin{document}</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makeatletter +\renewcommand{\thesis&arobase;universityname}{Saint Michael's College} +\makeatother +</pre></example> + + +</section> +<node name="_005c_0040ifstar" spaces=" "><nodename>\&arobase;ifstar</nodename><nodenext automatic="on">\newcounter</nodenext><nodeprev automatic="on">\makeatletter & \makeatother</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\&arobase;ifstar</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="455" mergedindex="cp">\&arobase;ifstar</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="414">commands, star-variants</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="415">star-variants, commands</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\mycmd}{\&arobase;ifstar{\mycmd&arobase;star}{\mycmd&arobase;nostar}} +\newcommand{\mycmd&arobase;nostar}[<var>nostar-num-args</var>]{<var>nostar-body</var>} +\newcommand{\mycmd&arobase;star}[<var>star-num-args</var>]{<var>star-body</var>} +</pre></example> + +<para>Many standard &latex; environments or commands have a variant with the +same name but ending with a star character <code>*</code>, an asterisk. +Examples are the <code>table</code> and <code>table*</code> environments and the +<code>\section</code> and <code>\section*</code> commands. +</para> +<para>When defining environments, following this pattern is straightforward +because <code>\newenvironment</code> and <code>\renewenvironment</code> allow the +environment name to contain a star. For commands the situation is more +complex. As in the synopsis above, there will be a user-called command, +given above as <code>\mycmd</code>, which peeks ahead to see if it is followed +by a star. For instance, &latex; does not really have a +<code>\section*</code> command; instead, the <code>\section</code> command peeks +ahead. This command does not accept arguments but instead expands to +one of two commands that do accept arguments. In the synopsis these two +are <code>\mycmd&arobase;nostar</code> and <code>\mycmd&arobase;star</code>. 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 <code>&arobase;</code> +must be enclosed inside a <code>\makeatletter ... \makeatother</code> block +(<pxref label="_005cmakeatletter-_0026-_005cmakeatother"><xrefnodename>\makeatletter & \makeatother</xrefnodename></pxref>). +</para> +<para>This example of <code>\&arobase;ifstar</code> defines the command <code>\ciel</code> and a +variant <code>\ciel*</code>. Both have one required argument. A call to +<code>\ciel{night}</code> will return "starry night sky" while +<code>\ciel*{blue}</code> will return "starry not blue sky". +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand*{\ciel&arobase;unstarred}[1]{starry #1 sky} +\newcommand*{\ciel&arobase;starred}[1]{starry not #1 sky} +\newcommand*{\ciel}{\&arobase;ifstar{\ciel&arobase;starred}{\ciel&arobase;unstarred}} +</pre></example> + +<para>In the next example, the starred variant takes a different number of +arguments than the unstarred one. With this definition, Agent 007&textrsquo;s +<code>``My name is \agentsecret*{Bond}, +\agentsecret{James}{Bond}.''</code> is equivalent to entering the commands +<code>``My name is \textsc{Bond}, \textit{James} textsc{Bond}.''</code> +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand*{\agentsecret&arobase;unstarred}[2]{\textit{#1} \textsc{#2}} +\newcommand*{\agentsecret&arobase;starred}[1]{\textsc{#1}} +\newcommand*{\agentsecret}{% + \&arobase;ifstar{\agentsecret&arobase;starred}{\agentsecret&arobase;unstarred}} +</pre></example> + +<para>There are two sometimes more convenient ways to accomplish the work of +<code>\&arobase;ifstar</code>. The <file>suffix</file> package allows the construct +<code>\newcommand\mycommand{<var>unstarred version</var>}</code> followed by +<code>\WithSuffix\newcommand\mycommand*{<var>starred version</var>}</code>. And +&latex;3 has the <file>xparse</file> package that allows this code. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\NewDocumentCommand\foo{s}{\IfBooleanTF#1 + {<var>starred version</var>}% + {<var>unstarred version</var>}% + } +</pre></example> + + +</section> +<node name="_005cnewcounter" spaces=" "><nodename>\newcounter</nodename><nodenext automatic="on">\newlength</nodenext><nodeprev automatic="on">\&arobase;ifstar</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newcounter</code>: Allocating a counter</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="456" mergedindex="cp">\newcounter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="416">counters, defining new</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcounter{<var>countername</var>} +\newcounter{<var>countername</var>}[<var>supercounter</var>] +</pre></example> + +<para>Globally defines a new counter named <var>countername</var> and initialize it +to zero (<pxref label="Counters"><xrefnodename>Counters</xrefnodename></pxref>). +</para> +<para>The name <var>countername</var> 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 <code>[<var>supercounter</var>]</code> then the +counter <var>countername</var> will be reset to zero whenever +<var>supercounter</var> is incremented. For example, ordinarily +<code>subsection</code> is numbered within <code>section</code> so that any time you +increment <var>section</var>, either with <code>\stepcounter</code> +(<pxref label="_005cstepcounter"><xrefnodename>\stepcounter</xrefnodename></pxref>) or <code>\refstepcounter</code> +(<pxref label="_005crefstepcounter"><xrefnodename>\refstepcounter</xrefnodename></pxref>), then &latex; will reset <var>subsection</var> to +zero. +</para> +<para>This example +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}. +</pre></example> + +<para>produces <samp>The value of asuper is 1 and that of asub is 3</samp> and +<samp>Now asuper is 2 while asub is 0</samp>. +</para> +<para>If the counter already exists, for instance by entering <code>asuper</code> +twice, then you get something like <samp>LaTeX Error: Command \c&arobase;asuper +already defined. Or name \end... illegal, see p.192 of the manual.</samp>. +</para> +<para>If you use the optional argument then the super counter must already +exist. Entering <code>\newcounter{jh}[lh]</code> when <code>lh</code> is not a +defined counter will get you <samp>LaTeX Error: No counter 'lh' +defined.</samp> +</para> + +</section> +<node name="_005cnewlength" spaces=" "><nodename>\newlength</nodename><nodenext automatic="on">\newsavebox</nodenext><nodeprev automatic="on">\newcounter</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newlength</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="457" mergedindex="cp">\newlength</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="417">lengths, allocating new</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="418">rubber lengths, defining new</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="419">skip register, plain &tex;</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="420">glue register, plain &tex;</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{<var>arg</var>} +</pre></example> + +<para>Allocate a new length register (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). The required argument +<var>arg</var> must begin with a backslash, <code>\</code>. The new register holds +rubber lengths such as <code>72.27pt</code> or <code>1in plus.2in minus.1in</code> +(a &latex; length register is what plain &tex; calls a <code>skip</code> +register). The initial value is zero. The control sequence +<code>\<var>arg</var></code> must not be already defined. +</para> +<para>An example: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{\graphichgt} +</pre></example> + +<para>If you forget the backslash then you get <samp>Missing control sequence +inserted</samp>. If the command sequence already exists then you get +something like <samp>LaTeX Error: Command \graphichgt already defined. +Or name \end... illegal, see p.192 of the manual</samp>. +</para> + +</section> +<node name="_005cnewsavebox" spaces=" "><nodename>\newsavebox</nodename><nodenext automatic="on">\newenvironment & \renewenvironment</nodenext><nodeprev automatic="on">\newlength</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newsavebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="458" mergedindex="cp">\newsavebox</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="421">box, allocating new</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newsavebox{\<var>cmd</var>} +</pre></example> + +<para>Define \<var>cmd</var>, the string consisting of a backslash followed by +<var>cmd</var>, 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 (<pxref label="Boxes"><xrefnodename>Boxes</xrefnodename></pxref>). The bin name \<var>cmd</var> is required, must +start with a backslash, \, and must not already be a defined command. +This command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This allocates a bin and then puts typeset material into it. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newsavebox{\logobox} +\savebox{\logobox}{LoGo} +Our logo is \usebox{\logobox}. +</pre></example> + +<noindent></noindent> +<para>The output is <samp>Our logo is LoGo</samp>. +</para> +<para>If there is an already defined bin then you get something like +<samp>LaTeX Error: Command \logobox already defined. Or name +\end... illegal, see p.192 of the manual</samp>. +</para> +<para>The allocation of a box is global. +</para> + +</section> +<node name="_005cnewenvironment-_0026-_005crenewenvironment" spaces=" "><nodename>\newenvironment & \renewenvironment</nodename><nodenext automatic="on">\newtheorem</nodenext><nodeprev automatic="on">\newsavebox</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newenvironment</code> & <code>\renewenvironment</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="459" mergedindex="cp">\newenvironment</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="460" mergedindex="cp">\renewenvironment</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="422">environments, defining</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="423">defining new environments</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="424">redefining environments</indexterm></cindex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} +\newenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} +\newenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} +\newenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} +\newenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} +\newenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} +</pre></example> + +<noindent></noindent> +<para>or one of these. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewenvironment{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} +\renewenvironment{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} +\renewenvironment{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} +\renewenvironment*{<var>env</var>}{<var>begdef</var>}{<var>enddef</var>} +\renewenvironment*{<var>env</var>}[<var>nargs</var>]{<var>begdef</var>}{<var>enddef</var>} +\renewenvironment*{<var>env</var>}[<var>nargs</var>][<var>optargdefault</var>]{<var>begdef</var>}{<var>enddef</var>} +</pre></example> + +<para>Define or redefine the environment <var>env</var>, that is, create the +construct <code>\begin{<var>env</var>} ... <var>body</var> ... \end{<var>env</var>}</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="425"><code>*</code>-form of environment commands</indexterm></cindex> +<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> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">env</itemformat></item> +</tableterm><tableitem><para>Required; the environment name. It consists only of letters or the +<code>*</code> character, and thus does not begin with backslash, <code>\</code>. +It must not begin with the string <code>end</code>. For +<code>\newenvironment</code>, the name <var>env</var> must not be the name of an +already existing environment, and also the command <code>\<var>env</var></code> +must be undefined. For <code>\renewenvironment</code>, <var>env</var> must be the +name of an existing environment. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">nargs</itemformat></item> +</tableterm><tableitem><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 <code>\begin</code>, as in +<code>\begin{<var>env</var>}{<var>arg1</var>} ... {<var>argn</var>}</code>. 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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">optargdefault</itemformat></item> +</tableterm><tableitem><para>Optional; if this is present then the first argument of the defined +environment is optional, with default value <var>optargdefault</var> (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 <var>optargdefault</var> is present in the definition of the +environment then you can start the environment with square brackets, as +in <code>\begin{<var>env</var>}[<var>optval</var>]{...} ... \end{<var>env</var>}</code>. +In this case, within <var>begdefn</var> the parameter <code>#1</code> is set to the +value of <var>optval</var>. If you call <code>\begin{<var>env</var>}</code> without +square brackets, then within <var>begdefn</var> the parameter <code>#1</code> is +set to the value of the default <var>optargdefault</var>. In either case, +any required arguments start with <code>#2</code>. +</para> +<para>Omitting <code>[<var>myval</var>]</code> in the call is different than having the +square brackets with no contents, as in <code>[]</code>. The former results +in <code>#1</code> expanding to <var>optargdefault</var>; the latter results in +<code>#1</code> expanding to the empty string. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">begdef</itemformat></item> +</tableterm><tableitem><para>Required; the text expanded at every occurrence of +<code>\begin{<var>env</var>}</code>. Within <var>begdef</var>, the parameters +<code>#1</code>, <code>#2</code>, ... <code>#<var>nargs</var></code>, are replaced by the +values that you supply when you call the environment; see the examples +below. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">enddef</itemformat></item> +</tableterm><tableitem><para>Required; the text expanded at every occurrence of +<code>\end{<var>env</var>}</code>. This may not contain any parameters, that is, +you cannot use <code>#1</code>, <code>#2</code>, etc., here (but see the final +example below). +</para> +</tableitem></tableentry></table> + +<para>All environments, that is to say the <var>begdef</var> code, the environment +body, and the <var>enddef</var> code, are processed within a group. Thus, in +the first example below, the effect of the <code>\small</code> 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 <samp>LaTeX Error: Command \fred already +defined. Or name \end... illegal, see p.192 of the manual</samp>. If you try +to redefine an environment and the name has not yet been used then you +get something like <samp>LaTeX Error: Environment hank undefined.</samp>. +</para> +<para>This example gives an environment like &latex;&textrsquo;s <code>quotation</code> +except that it will be set in smaller type. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{smallquote}{% + \small\begin{quotation} +}{% + \end{quotation} +} +</pre></example> + +<para>This has an argument, which is set in boldface at the start of a +paragraph. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{point}[1]{% + \noindent\textbf{#1} +}{% +} +</pre></example> + +<para>This one shows the use of a optional argument; it gives a quotation +environment that cites the author. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newenvironment{citequote}[1][Shakespeare]{% + \begin{quotation} + \noindent\textit{#1}: +}{% + \end{quotation} +} +</pre></example> + +<noindent></noindent> +<para>The author&textrsquo;s name is optional, and defaults to <samp>Shakespeare</samp>. In +the document, use the environment like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{citequote}[Lincoln] + ... +\end{citequote} +</pre></example> + +<para>The final example shows how to save the value of an argument to use in +<var>enddef</var>, in this case in a box (<pxref label="_005csbox-_0026-_005csavebox"><xrefnodename>\sbox & \savebox</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newsavebox{\quoteauthor} +\newenvironment{citequote}[1][Shakespeare]{% + \sbox\quoteauthor{#1}% + \begin{quotation} +}{% + \hspace{1em plus 1fill}---\usebox{\quoteauthor} + \end{quotation} +} +</pre></example> + + +</section> +<node name="_005cnewtheorem" spaces=" "><nodename>\newtheorem</nodename><nodenext automatic="on">\newfont</nodenext><nodeprev automatic="on">\newenvironment & \renewenvironment</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newtheorem</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="461" mergedindex="cp">\newtheorem</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="426">theorems, defining</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="427">defining new theorems</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="428">theorem-like environment</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="429">environment, theorem-like</indexterm></cindex> +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newtheorem{<var>name</var>}{<var>title</var>} +\newtheorem{<var>name</var>}{<var>title</var>}[<var>numbered_within</var>] +\newtheorem{<var>name</var>}[<var>numbered_like</var>]{<var>title</var>} +</pre></example> + +<para>Define a new theorem-like environment. You can specify one of +<var>numbered_within</var> and <var>numbered_like</var>, or neither, but not both. +</para> +<para>The first form, <code>\newtheorem{<var>name</var>}{<var>title</var>}</code>, creates +an environment that will be labelled with <var>title</var>; see the first +example below. +</para> +<para>The second form, +<code>\newtheorem{<var>name</var>}{<var>title</var>}[<var>numbered_within</var>]</code>, +creates an environment whose counter is subordinate to the existing +counter <var>numbered_within</var>, so this counter will be reset when +<var>numbered_within</var> is reset. See the second example below. +</para> +<para>The third form +<code>\newtheorem{<var>name</var>}[<var>numbered_like</var>]{<var>title</var>}</code>, +with optional argument between the two required arguments, creates an +environment whose counter will share the previously defined counter +<var>numbered_like</var>. See the third example. +</para> +<para>This command creates a counter named <var>name</var>. In addition, unless +the optional argument <var>numbered_like</var> is used, inside of the +theorem-like environment the current <code>\ref</code> value will be that of +<code>\the<var>numbered_within</var></code> (<pxref label="_005cref"><xrefnodename>\ref</xrefnodename></pxref>). +</para> +<para>This declaration is global. It is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Arguments: +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">name</itemformat></item> +</tableterm><tableitem><para>The name of the environment. It is a string of letters. It must not +begin with a backslash, <code>\</code>. It must not be the name of an +existing environment, and the command name <code>\<var>name</var></code> must not +already be defined. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">title</itemformat></item> +</tableterm><tableitem><para>The text to be printed at the beginning of the environment, before the +number. For example, <samp>Theorem</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">numbered_within</itemformat></item> +</tableterm><tableitem><para>Optional; the name of an already defined counter, usually a sectional +unit such as <code>chapter</code> or <code>section</code>. When the +<var>numbered_within</var> counter is reset then the <var>name</var> environment&textrsquo;s +counter will also be reset. +</para> +<para>If this optional argument is not used then the command +<code>\the<var>name</var></code> is set to <code>\arabic{<var>name</var>}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">numbered_like</itemformat></item> +</tableterm><tableitem><para>Optional; the name of an already defined theorem-like environment. The +new environment will be numbered in sequence with <var>numbered_like</var>. +</para> +</tableitem></tableentry></table> + +<para>Without any optional arguments the environments are numbered +sequentially. The example below has a declaration in the preamble that +results in <samp>Definition 1</samp> and <samp>Definition 2</samp> in the +output. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newtheorem{defn}{Definition} +\begin{document} +\section{...} +\begin{defn} + First def +\end{defn} + +\section{...} +\begin{defn} + Second def +\end{defn} +</pre></example> + +<para>This example has the same document body as the prior one. But here +<code>\newtheorem</code>&textrsquo;s optional argument <var>numbered_within</var> is given as +<code>section</code>, so the output is like <samp>Definition 1.1</samp> and +<samp>Definition 2.1</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newtheorem{defn}{Definition}[section] +\begin{document} +\section{...} +\begin{defn} + First def +\end{defn} + +\section{...} +\begin{defn} + Second def +\end{defn} +</pre></example> + +<para>In the next example there are two declarations in the preamble, the +second of which calls for the new <code>thm</code> environment to use the same +counter as <code>defn</code>. It gives <samp>Definition 1.1</samp>, followed +by <samp>Theorem 2.1</samp> and <samp>Definition 2.2</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</section> +<node name="_005cnewfont" spaces=" "><nodename>\newfont</nodename><nodenext automatic="on">\protect</nodenext><nodeprev automatic="on">\newtheorem</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\newfont</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="462" mergedindex="cp">\newfont</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="430">fonts, new commands for</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="431">defining new fonts</indexterm></cindex> + +<!-- c @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 (<pxref label="Fonts"><xrefnodename>Fonts</xrefnodename></pxref>). +<!-- c This is done either by using --> +<!-- c @file{.fd} files or through the use of an engine that can access system --> +<!-- c fonts such as Xe@LaTeX{} (@pxref{@TeX{} engines}). --> +</para> +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newfont{\<var>cmd</var>}{<var>font description</var>} +</pre></example> + +<para>Define a command <code>\<var>cmd</var></code> that will change the current font. +The control sequence must not already be defined. It must begin with a +backslash, <code>\</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="432">at clause, in font definitions</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="433">design size, in font definitions</indexterm></cindex> +<para>The <var>font description</var> consists of a <var>fontname</var> and an optional +<dfn>at clause</dfn>. &latex; will look on your system for a file named +<file><var>fontname</var>.tfm</file>. The at clause can have the form either +<code>at <var>dimen</var></code> or <code>scaled <var>factor</var></code>, where a +<var>factor</var> of <samp>1000</samp> means no scaling. For &latex;&textrsquo;s purposes, +all this does is scale all the character and other font dimensions +relative to the font&textrsquo;s design size, which is a value defined in the +<file>.tfm</file> file. +</para> +<para>This defines two equivalent fonts and typesets a few characters in each. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newfont{\testfontat}{cmb10 at 11pt} +\newfont{\testfontscaled}{cmb10 scaled 1100} +\testfontat abc +\testfontscaled abc +</pre></example> + + +</section> +<node name="_005cprotect" spaces=" "><nodename>\protect</nodename><nodenext automatic="on">\ignorespaces & \ignorespacesafterend</nodenext><nodeprev automatic="on">\newfont</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\protect</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="463" mergedindex="cp">\protect</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="434">fragile commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="435">robust commands</indexterm></cindex> + +<para>All &latex; commands are either <dfn>fragile</dfn> or <dfn>robust</dfn>. 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 +<code>\protect</code>. +</para> +<para>For example, when &latex; runs the <code>\section{<var>section +name</var>}</code> command it writes the <var>section name</var> text to the +<file>.aux</file> 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 +<cindex index="cp" spaces=" "><indexterm index="cp" number="436">moving arguments</indexterm></cindex> +<dfn>moving argument</dfn>. 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 <code>\caption{...}</code> +command (<pxref label="figure"><xrefnodename>figure</xrefnodename></pxref>), in the <code>\thanks{...}</code> command +(<pxref label="_005cmaketitle"><xrefnodename>\maketitle</xrefnodename></pxref>), and in &arobase;-expressions in the <code>tabular</code> and +<code>array</code> environments (<pxref label="tabular"><xrefnodename>tabular</xrefnodename></pxref>). +</para> +<para>If you get strange errors from commands used in moving arguments, try +preceding it with <code>\protect</code>. Every fragile commands must be +protected with their own <code>\protect</code>. +</para> +<para>Although usually a <code>\protect</code> command doesn&textrsquo;t hurt, length +commands are robust and should not be preceded by a <code>\protect</code> +command. Nor can a <code>\protect</code> command be used in the argument to +<code>\addtocounter</code> or <code>\setcounter</code> command. +</para> +<para>In this example the <code>\caption</code> command gives a mysterious error +about an extra curly brace. Fix the problem by preceding each +<code>\raisebox</code> command with <code>\protect</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{figure} + ... + \caption{Company headquarters of A\raisebox{1pt}{B}\raisebox{-1pt}{C}} +\end{figure} +</pre></example> + +<para>In the next example the <code>\tableofcontents</code> command gives an error +because the <code>\(..\)</code> in the section title expands to illegal &tex; +in the <file>.toc</file> file. You can solve this by changing <code>\(..\)</code> +to <code>\protect\(..\protect\)</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{document} +\tableofcontents +... +\section{Einstein's \( e=mc^2 \)} +... +</pre></example> + + +</section> +<node name="_005cignorespaces-_0026-_005cignorespacesafterend" spaces=" "><nodename>\ignorespaces & \ignorespacesafterend</nodename><nodeprev automatic="on">\protect</nodeprev><nodeup automatic="on">Definitions</nodeup></node> +<section spaces=" "><sectiontitle><code>\ignorespaces & \ignorespacesafterend</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="464" mergedindex="cp">\ignorespaces</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="465" mergedindex="cp">\ignorespacesafterend</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="437">spaces, ignore around commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="438">commands, ignore spaces</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ignorespaces +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ignorespacesafterend +</pre></example> + +<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 <code>ignorespaces</code> is often used when defining commands via +<code>\newcommand</code>, or <code>\newenvironment</code>, or <code>\def</code>. 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 <code>enumerate</code> list, users must not put any space between +the command and the question text. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The solution is to change to this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\points}[1]{% + \makebox[0pt]{\makebox[10em][l]{#1~pts}}\ignorespaces} +</pre></example> + +<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 +<code>\fullname</code> will reproduce that. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makeatletter +\newcommand{\honorific}[1]{\def\&arobase;honorific{#1}} % remember title +\newcommand{\fullname}[1]{\&arobase;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} +</pre></example> + +<noindent></noindent> +<para>To fix this, change to +<code>\newcommand{\fullname}[1]{\ignorespaces\&arobase;honorific~#1}</code>. +</para> +<para>The <code>\ignorespaces</code> is also often used in a <code>\newenvironment</code> +at the end of the <var>begin</var> clause, that is, as part of the second +argument, as in <code>\begin{newenvironment}{<var>env +name</var>}{... \ignorespaces}{...}</code>. +</para> +<para>To strip spaces off the end of an environment use +<code>\ignorespacesafterend</code>. 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>Putting a comment character <code>%</code> immediately after the +<code>\end{eq}</code> will make the vertical space disappear, but that is +inconvenient. The solution is to change to +<code>\newenvironment{eq}{\begin{equation}}{\end{equation}\ignorespacesafterend}</code>. +</para> + +</section> +</chapter> +<node name="Counters" spaces=" "><nodename>Counters</nodename><nodenext automatic="on">Lengths</nodenext><nodeprev automatic="on">Definitions</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Counters</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="439">counters, a list of</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="440">variables, a list of</indexterm></cindex> + +<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&textrsquo;s name has no backslash <code>\</code>. Thus, associated with +the <code>\chapter</code> command is the <code>chapter</code> counter that keeps +track of the chapter number. +</para> +<para>Below is a list of the counters used in &latex;&textrsquo;s standard document +classes to control numbering. +</para> +<example endspaces=" "> +<pre xml:space="preserve">part paragraph figure enumi +chapter subparagraph table enumii +section page footnote enumiii +subsection equation mpfootnote enumiv +subsubsection +</pre></example> + +<para>The <code>mpfootnote</code> counter is used by the <code>\footnote</code> command +inside of a minipage (<pxref label="minipage"><xrefnodename>minipage</xrefnodename></pxref>). The counters <code>enumi</code> +through <code>enumiv</code> are used in the <code>enumerate</code> environment, for +up to four levels of nesting (<pxref label="enumerate"><xrefnodename>enumerate</xrefnodename></pxref>). +</para> +<para>Counters can have any integer value but they are typically positive. +</para> +<para>New counters are created with <code>\newcounter</code>. <xref label="_005cnewcounter"><xrefnodename>\newcounter</xrefnodename></xref>. +</para> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\alph \Alph \arabic \roman \Roman \fnsymbol</menunode><menudescription><pre xml:space="preserve">Print value of a counter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\usecounter</menunode><menudescription><pre xml:space="preserve">Use a specified counter in a list environment. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\value</menunode><menudescription><pre xml:space="preserve">Use the value of a counter in an expression. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\setcounter</menunode><menudescription><pre xml:space="preserve">Set the value of a counter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\addtocounter</menunode><menudescription><pre xml:space="preserve">Add a quantity to a counter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\refstepcounter</menunode><menudescription><pre xml:space="preserve">Add to a counter. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\stepcounter</menunode><menudescription><pre xml:space="preserve">Add to a counter, resetting subsidiary counters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\day & \month & \year</menunode><menudescription><pre xml:space="preserve">Numeric date values. +</pre></menudescription></menuentry></menu> + + +<node name="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol" spaces=" "><nodename>\alph \Alph \arabic \roman \Roman \fnsymbol</nodename><nodenext automatic="on">\usecounter</nodenext><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\alph \Alph \arabic \roman \Roman \fnsymbol</code>: Printing counters</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="441">counters, printing</indexterm></cindex> + +<para>Print the value of a counter, in a specified style. For instance, if +the counter <var>counter</var> has the value 1 then a +<code>\alph{<var>counter</var>}</code> 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, <code>\alph{enumi}</code>. Note that the counter name does not +start with a backslash. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="466" mergedindex="cp">\alph{<var>counter</var>}</indexterm>\alph{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Print the value of <var>counter</var> in lowercase letters: &textlsquo;a&textrsquo;, &textlsquo;b&textrsquo;, +&enddots; If the counter&textrsquo;s value is less than 1 or more than 26 then +you get <samp>LaTeX Error: Counter too large.</samp> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="467" mergedindex="cp">\Alph{<var>counter</var>}</indexterm>\Alph{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Print in uppercase letters: &textlsquo;A&textrsquo;, &textlsquo;B&textrsquo;, &enddots; If the counter&textrsquo;s value +is less than 1 or more than 26 then you get <samp>LaTeX Error: Counter +too large.</samp> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="468" mergedindex="cp">\arabic{<var>counter</var>}</indexterm>\arabic{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Print in Arabic numbers such as <samp>5</samp> or <samp>-2</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="469" mergedindex="cp">\roman{<var>counter</var>}</indexterm>\roman{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Print in lowercase roman numerals: &textlsquo;i&textrsquo;, &textlsquo;ii&textrsquo;, &enddots; If the +counter&textrsquo;s value is less than 1 then you get no warning or error but +&latex; does not print anything in the output. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="470" mergedindex="cp">\Roman{<var>counter</var>}</indexterm>\Roman{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Print in uppercase roman numerals: &textlsquo;I&textrsquo;, &textlsquo;II&textrsquo;, &enddots; If the +counter&textrsquo;s value is less than 1 then you get no warning or error but +&latex; does not print anything in the output. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="471" mergedindex="cp">\fnsymbol{<var>counter</var>}</indexterm>\fnsymbol{<var>counter</var>}</itemformat></item> +</tableterm><tableitem><para>Prints the value of <var>counter</var> using a sequence of nine symbols that +are traditionally used for labeling footnotes. The value of +<var>counter</var> should be between 1 and 9, inclusive. If the +counter&textrsquo;s value is less than 0 or more than 9 then you get <samp>LaTeX +Error: Counter too large</samp>, 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> +<multitable spaces=" " endspaces=" "><columnfractions line=" .10 .30 .30 .30"><columnfraction value=".10"></columnfraction><columnfraction value=".30"></columnfraction><columnfraction value=".30"></columnfraction><columnfraction value=".30"></columnfraction></columnfractions> +<thead><row><entry command="headitem" spaces=" "><para>Number</para></entry><entry command="tab" spaces=" "><para>Name</para></entry><entry command="tab" spaces=" "><para>Command</para></entry><entry command="tab" spaces=" "><para>Symbol +</para></entry></row></thead><tbody><row><entry command="item"> +<para>1</para></entry><entry command="tab" spaces=" "><para>asterisk</para></entry><entry command="tab"><para><code>\ast</code></para></entry><entry command="tab"><para>*<!-- c --> +</para></entry></row><row><entry command="item"> +<para>2</para></entry><entry command="tab" spaces=" "><para>dagger</para></entry><entry command="tab"><para><code>\dagger</code></para></entry><entry command="tab"><para><U>2020</U> +</para></entry></row><row><entry command="item"> +<para>3</para></entry><entry command="tab" spaces=" "><para>ddagger</para></entry><entry command="tab"><para><code>\ddagger</code></para></entry><entry command="tab"><para><U>2021</U> +</para></entry></row><row><entry command="item"> +<para>4</para></entry><entry command="tab" spaces=" "><para>section-sign</para></entry><entry command="tab"><para><code>\S</code></para></entry><entry command="tab"><para><U>00A7</U> +</para></entry></row><row><entry command="item"> +<para>5</para></entry><entry command="tab" spaces=" "><para>paragraph-sign</para></entry><entry command="tab"><para><code>\P</code></para></entry><entry command="tab"><para><U>00B6</U> +</para></entry></row><row><entry command="item"> +<para>6</para></entry><entry command="tab" spaces=" "><para>double-vert</para></entry><entry command="tab"><para><code>\parallel</code></para></entry><entry command="tab"><para><U>2016</U> +</para></entry></row><row><entry command="item"> +<para>7</para></entry><entry command="tab" spaces=" "><para>double-asterisk</para></entry><entry command="tab"><para><code>\ast\ast</code></para></entry><entry command="tab"><para>**<!-- c --> +</para></entry></row><row><entry command="item"> +<para>8</para></entry><entry command="tab"> + <para>double-dagger</para></entry><entry command="tab"><para><code>\dagger\dagger</code></para></entry><entry command="tab"><para><U>2020</U><U>2020</U> +</para></entry></row><row><entry command="item"> +<para>9</para></entry><entry command="tab"> + <para>double-ddagger</para></entry><entry command="tab"><para><code>\ddagger\ddagger</code></para></entry><entry command="tab"><para><U>2021</U><U>2021</U> +</para></entry></row></tbody></multitable> + +</tableitem></tableentry></ftable> + + +</section> +<node name="_005cusecounter" spaces=" "><nodename>\usecounter</nodename><nodenext automatic="on">\value</nodenext><nodeprev automatic="on">\alph \Alph \arabic \roman \Roman \fnsymbol</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\usecounter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="472" mergedindex="cp">\usecounter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="442">list items, specifying counter</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="443">numbered items, specifying counter</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usecounter{<var>counter</var>} +</pre></example> + +<para>Used in the second argument of the <code>list</code> environment +(<pxref label="list"><xrefnodename>list</xrefnodename></pxref>), this declares that list items will be numbered by +<var>counter</var>. It initializes <var>counter</var> to zero, and arranges that +when <code>\item</code> is called without its optional argument then +<var>counter</var> is incremented by <code>\refstepcounter</code>, making its value +be the current <code>ref</code> value (<pxref label="_005cref"><xrefnodename>\ref</xrefnodename></pxref>). This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Put in the document preamble, this example makes a new list environment +enumerated with <var>testcounter</var>: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcounter{testcounter} +\newenvironment{test}{% + \begin{list}{}{% + \usecounter{testcounter} + } +}{% + \end{list} +} +</pre></example> + + +</section> +<node name="_005cvalue" spaces=" "><nodename>\value</nodename><nodenext automatic="on">\setcounter</nodenext><nodeprev automatic="on">\usecounter</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\value</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="473" mergedindex="cp">\value</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="444">counters, getting value of</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\value{<var>counter</var>} +</pre></example> + +<para>Expands to the value of the counter <var>counter</var>. (Note that the name +of a counter does not begin with a backslash.) +</para> +<para>This example outputs <samp>Test counter is 6. Other counter +is 5.</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcounter{test} \setcounter{test}{5} +\newcounter{other} \setcounter{other}{\value{test}} +\addtocounter{test}{1} + +Test counter is \arabic{test}. +Other counter is \arabic{other}. +</pre></example> + +<para>The <code>\value</code> command is not used for typesetting the value of the +counter. For that, see <ref label="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"><xrefnodename>\alph \Alph \arabic \roman \Roman \fnsymbol</xrefnodename></ref>. +</para> +<para>It is often used in <code>\setcounter</code> or <code>\addtocounter</code> but +<code>\value</code> can be used anywhere that &latex; expects a number, such +as in <code>\hspace{\value{foo}\parindent}</code>. It must not be +preceded by <code>\protect</code> (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This example inserts <code>\hspace{4\parindent}</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setcounter{myctr}{3} \addtocounter{myctr}{1} +\hspace{\value{myctr}\parindent} +</pre></example> + + +</section> +<node name="_005csetcounter" spaces=" "><nodename>\setcounter</nodename><nodenext automatic="on">\addtocounter</nodenext><nodeprev automatic="on">\value</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\setcounter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="474" mergedindex="cp">\setcounter</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="445">counters, setting</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="446">setting counters</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setcounter{<var>counter</var>}{<var>value</var>} +</pre></example> + +<para>Globally set the counter <var>counter</var> to have the value of the +<var>value</var> argument, which must be an integer. Thus, you can set a +counter&textrsquo;s value as <code>\setcounter{section}{5}</code>. Note that the +counter name does not start with a backslash. +</para> +<para>In this example if the counter <code>theorem</code> has value 12 then the +second line will print <samp>XII</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setcounter{exercise}{\value{theorem}} +Here it is in Roman: \Roman{exercise}. +</pre></example> + + +</section> +<node name="_005caddtocounter" spaces=" "><nodename>\addtocounter</nodename><nodenext automatic="on">\refstepcounter</nodenext><nodeprev automatic="on">\setcounter</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\addtocounter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="475" mergedindex="cp">\addtocounter</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addtocounter{<var>counter</var>}{<var>value</var><spacecmd type="nl"/></pre></example> + +<para>Globally increment <var>counter</var> by the amount specified by the +<var>value</var> argument, which may be negative. +</para> +<para>In this example the section value appears as <samp>VII</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setcounter{section}{5} +\addtocounter{section}{2} +Here it is in Roman: \Roman{section}. +</pre></example> + + +</section> +<node name="_005crefstepcounter" spaces=" "><nodename>\refstepcounter</nodename><nodenext automatic="on">\stepcounter</nodenext><nodeprev automatic="on">\addtocounter</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\refstepcounter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="476" mergedindex="cp">\refstepcounter</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\refstepcounter{<var>counter</var>} +</pre></example> + +<para>Globally increments the value of <var>counter</var> by one, as does +<code>\stepcounter</code> (<pxref label="_005cstepcounter"><xrefnodename>\stepcounter</xrefnodename></pxref>). The difference is that this +command resets the value of any counter numbered within it. (For the +definition of &textldquo;counters numbered within&textrdquo;, <pxref label="_005cnewcounter"><xrefnodename>\newcounter</xrefnodename></pxref>.) +</para> +<para>In addition, this command also defines the current <code>\ref</code> value +to be the result of <code>\thecounter</code>. +</para> +<para>While the counter value is set globally, the <code>\ref</code> value is set +locally, i.e., inside the current group. +</para> + +</section> +<node name="_005cstepcounter" spaces=" "><nodename>\stepcounter</nodename><nodenext automatic="on">\day & \month & \year</nodenext><nodeprev automatic="on">\refstepcounter</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\stepcounter</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="477" mergedindex="cp">\stepcounter</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\stepcounter{<var>counter</var>} +</pre></example> + +<para>Globally adds one to <var>counter</var> and resets all counters numbered +within it. (For the definition of &textldquo;counters numbered within&textrdquo;, +<pxref label="_005cnewcounter"><xrefnodename>\newcounter</xrefnodename></pxref>.) +</para> +<para>This command differs from <code>\refstepcounter</code> in that this one does +not influence references &textmdash; it does not define the current +<code>\ref</code> value to be the result of <code>\thecounter</code> +(<pxref label="_005crefstepcounter"><xrefnodename>\refstepcounter</xrefnodename></pxref>). +</para> + +</section> +<node name="_005cday-_0026-_005cmonth-_0026-_005cyear" spaces=" "><nodename>\day & \month & \year</nodename><nodeprev automatic="on">\stepcounter</nodeprev><nodeup automatic="on">Counters</nodeup></node> +<section spaces=" "><sectiontitle><code>\day</code> & <code>\month</code> & <code>\year</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="478" mergedindex="cp">\day</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="479" mergedindex="cp">\month</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="480" mergedindex="cp">\year</indexterm></findex> + +<para>&latex; defines the counter <code>\day</code> for the day of the month +(nominally with value between 1 and 31), <code>\month</code> for the month of +the year (nominally with value between 1 and 12), and year <code>\year</code>. +When &tex; starts up, they are set from the current values on the +system. The related command <code>\today</code> produces a string +representing the current day (<pxref label="_005ctoday"><xrefnodename>\today</xrefnodename></pxref>). +</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> +<example endspaces=" "> +<pre xml:space="preserve">\day=-2 \month=13 \year=-4 \today +</pre></example> + +<noindent></noindent> +<para>gives no error or warning and results in the output <samp>-2, -4</samp> (the +bogus month value produces no output). +</para> + +</section> +</chapter> +<node name="Lengths" spaces=" "><nodename>Lengths</nodename><nodenext automatic="on">Making paragraphs</nodenext><nodeprev automatic="on">Counters</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Lengths</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="447">lengths, defining and using</indexterm></cindex> + +<para>A <dfn>length</dfn> is a measure of distance. Many &latex; commands take a +length as an argument. +</para> +<para>Lengths come in two types. A <dfn>rigid length</dfn> such as <code>10pt</code> +does not contain a <code>plus</code> or <code>minus</code> component. (Plain &tex; +calls this a <dfn>dimen</dfn>.) A <dfn>rubber length</dfn> (what Plain &tex; +calls a <dfn>skip</dfn>) such as as with <code>1cm plus0.05cm minus0.01cm</code> +can contain either or both of those components. In that rubber length, +the <code>1cm</code> is the <dfn>natural length</dfn> while the other two, the +<code>plus</code> and <code>minus</code> components, allow &tex; to stretch or +shrink the length to optimize placement. +</para> +<para>The illustrations below use these two commands. +</para> +<example endspaces=" "> +<pre xml:space="preserve">% 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}}} +</pre></example> + +<noindent></noindent> +<para>This example uses those commands to show a black bar 100 points +long between <samp>XXX</samp> and <samp>YYY</samp>. This length is rigid. +</para> +<example endspaces=" "> +<pre xml:space="preserve">XXX\showhbox{100pt}{\blackbar{100pt}}YYY +</pre></example> + +<para>As for rubber lengths, shrinking is simpler one: with <code>1cm minus +0.05cm</code>, the natural length is 1<dmn>cm</dmn> but &tex; can shrink it down +as far as 0.95<dmn>cm</dmn>. 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> +<example endspaces=" "> +<pre xml:space="preserve">XXX\showhbox{300pt}{% + \blackbar{101pt}\hspace{100pt minus 2pt}\blackbar{101pt}}YYY + +XXX\showhbox{300pt}{% + \blackbar{105pt}\hspace{100pt minus 1pt}\blackbar{105pt}}YYY +</pre></example> + +<noindent></noindent> +<para>But the second one gets a warning like <samp>Overfull \hbox (1.0pt too +wide) detected at line 17</samp>. In the output the first <samp>Y</samp> is +overwritten by the end of the black bar, because the box&textrsquo;s material is +wider than the 300<dmn>pt</dmn> 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> +<example endspaces=" "> +<pre xml:space="preserve">XXX\showhbox{300pt}{% + \blackbar{95pt}\hspace{100pt plus 10pt}\blackbar{95pt}}YYY + +XXX\showhbox{300pt}{% + \blackbar{95pt}\hspace{100pt plus 1pt}\blackbar{95pt}}YYY +</pre></example> + +<noindent></noindent> +<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 <samp>Underfull \hbox (badness +10000) detected at line 22</samp>. (We won&textrsquo;t discuss badness.) +</para> +<para>You can put both stretch and shrink in the same length, as in +<code>1ex plus 0.05ex minus 0.02ex</code>. +</para> +<para>If &tex; is setting two or more rubber lengths then it allocates the +stretch or shrink in proportion. +</para> +<example endspaces=" "> +<pre xml:space="preserve">XXX\showhbox{300pt}{% + \blackbar{100pt}% left + \hspace{0pt plus 50pt}\blackbar{80pt}\hspace{0pt plus 10pt}% middle + \blackbar{100pt}}YYY % right +</pre></example> + +<noindent></noindent> +<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 +<code>\hspace</code>&textrsquo;s must stretch 20 points. Because the two are +<code>plus 50pt</code> and <code>plus 10pt</code>, &tex; gets 5/6 of the stretch +from the first space and 1/6 from the second. +</para> +<para>The <code>plus</code> or <code>minus</code> component of a rubber length can contain +a <dfn>fill</dfn> component, as in <code>1in plus2fill</code>. 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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{minipage}{\linewidth} + \hspace{0pt plus 1fill}\includegraphics{godel.png}% + \hspace{0pt plus 1fill}\includegraphics{einstein.png}% + \hspace{0pt plus 1fill} +\end{minipage} +</pre></example> + +<para>&tex; actually has three levels of infinity for glue components: +<code>fil</code>, <code>fill</code>, and <code>filll</code>. The later ones are more +infinite than the earlier ones. Ordinarily document authors only use +the middle one (<pxref label="_005chfill"><xrefnodename>\hfill</xrefnodename></pxref> and <pxref label="_005cvfill"><xrefnodename>\vfill</xrefnodename></pxref>). +</para> +<para>Multiplying a rubber length by a number turns it into a rigid length, so +that after <code>\setlength{\ylength}{1in plus 0.2in}</code> and +<code>\setlength{\zlength}{3\ylength}</code> then the value of +<code>\zlength</code> is <code>3in</code>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Units of length</menunode><menudescription><pre xml:space="preserve">The units that &latex; knows. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\setlength</menunode><menudescription><pre xml:space="preserve">Set the value of a length. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\addtolength</menunode><menudescription><pre xml:space="preserve">Add a quantity to a length. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\settodepth</menunode><menudescription><pre xml:space="preserve">Set a length to the depth of something. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\settoheight</menunode><menudescription><pre xml:space="preserve">Set a length to the height of something. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\settowidth</menunode><menudescription><pre xml:space="preserve">Set a length to the width of something. +<!-- c * Predefined lengths:: Lengths that are, like, predefined. --> +</pre></menudescription></menuentry></menu> + + +<node name="Units-of-length" spaces=" "><nodename>Units of length</nodename><nodenext automatic="on">\setlength</nodenext><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle>Units of length</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="448">units, of length</indexterm></cindex> + +<para>&tex; and &latex; know about these units both inside and outside of +math mode. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">pt </itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="481" mergedindex="cp">pt</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="449">Point</indexterm></cindex> +<anchor name="units-of-length-pt">units of length pt</anchor> +<para>Point, 1/72.27 inch. The conversion to metric units, to two decimal +places, is 1<dmn>point</dmn> = 2.85<dmn>mm</dmn> = 28.45<dmn>cm</dmn>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">pc</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="450">pica</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="482" mergedindex="cp">pc</indexterm></findex> +<anchor name="units-of-length-pc">units of length pc</anchor> +<para>Pica, 12 pt +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">in </itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="483" mergedindex="cp">in</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="484" mergedindex="cp">inch</indexterm></findex> +<anchor name="units-of-length-in">units of length in</anchor> +<para>Inch, 72.27 pt +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">bp </itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="485" mergedindex="cp">bp</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="451">Big point</indexterm></cindex> +<anchor name="units-of-length-bp">units of length bp</anchor> +<para>Big point, 1/72 inch. This length is the definition of a point in +PostScript and many desktop publishing systems. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">cm </itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="452">Centimeter</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="486" mergedindex="cp">cm</indexterm></findex> +<anchor name="units-of-length-cm">units of length cm</anchor> +<para>Centimeter +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">mm </itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="453">Millimeter</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="487" mergedindex="cp">mm</indexterm></findex> +<anchor name="units-of-length-mm">units of length mm</anchor> +<para>Millimeter +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">dd </itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="454">Didot point</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="488" mergedindex="cp">dd</indexterm></findex> +<anchor name="units-of-length-dd">units of length dd</anchor> +<para>Didot point, 1.07 pt +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">cc </itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="455">Cicero</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="489" mergedindex="cp">cc</indexterm></findex> +<anchor name="units-of-length-cc">units of length cc</anchor> +<para>Cicero, 12 dd +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">sp </itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="456">Scaled point</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="490" mergedindex="cp">sp</indexterm></findex> +<anchor name="units-of-length-sp">units of length sp</anchor> +<para>Scaled point, 1/65536 pt +</para> +</tableitem></tableentry></table> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="457">ex</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="458">x-height</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="491" mergedindex="cp">ex</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="459">m-width</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="460">em</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="492" mergedindex="cp">em</indexterm></findex> +<anchor name="Lengths_002fem">Lengths/em</anchor> +<anchor name="Lengths_002fen">Lengths/en</anchor> +<anchor name="Lengths_002fex">Lengths/ex</anchor> +<anchor name="units-of-length-em">units of length em</anchor> +<anchor name="units-of-length-en">units of length en</anchor> +<anchor name="units-of-length-ex">units of length ex</anchor> +<para>Two other lengths that are often used are values set by the designer of +the font. The x-height of the current font <dfn>ex</dfn>, traditionally the +height of the lowercase letter x, is often used for vertical +lengths. Similarly <dfn>em</dfn>, traditionally the width of the capital +letter M, is often used for horizontal lengths (there is also +<code>\enspace</code>, which is <code>0.5em</code>). 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 +<code>\setlength{\itemsep}{1ex plus 0.05ex minus 0.01ex}</code> is more +likely to still be reasonable if the font is changed than a definition +given in points. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="461">mu, math unit</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="493" mergedindex="cp">mu</indexterm></findex> +<para>In math mode, many definitions are expressed in terms of the math unit +<dfn>mu</dfn> given by 1 em = 18 mu, where the em is taken from the current +math symbols family. <xref label="Spacing-in-math-mode"><xrefnodename>Spacing in math mode</xrefnodename></xref>. +</para> + +</section> +<node name="_005csetlength" spaces=" "><nodename>\setlength</nodename><nodenext automatic="on">\addtolength</nodenext><nodeprev automatic="on">Units of length</nodeprev><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle><code>\setlength</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="494" mergedindex="cp">\setlength</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="462">lengths, setting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{<var>len</var>}{<var>amount</var>} +</pre></example> + +<para>Set the length <var>len</var> to <var>amount</var>. The length name <var>len</var> +must begin with a backslash, <code>\</code>. The <code>amount</code> can be a +rubber length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). It can be positive, negative or zero, +and can be in any units that &latex; understands (<pxref label="Units-of-length"><xrefnodename>Units of +length</xrefnodename></pxref>). +</para> +<para>Below, with &latex;&textrsquo;s defaults the first paragraph will be indented +while the second will not. +</para> +<example endspaces=" "> +<pre xml:space="preserve">I told the doctor I broke my leg in two places. + +\setlength{\parindent}{0em} +He said stop going to those places. +</pre></example> + +<para>If you did not declare <var>len</var> with <code>\newlength</code>, for example if +you mistype the above as +<code>\newlength{\specparindent}\setlength{\sepcparindent}{...}</code>, +then you get an error like <samp>Undefined control sequence. <argument> +\sepcindent</samp>. If you omit the backslash at the start of the length name +then you get an error like <samp>Missing number, treated as zero. <to be +read again> \relax l.19 \setlength{specparindent}{0.6\parindent}</samp> +</para> + +</section> +<node name="_005caddtolength" spaces=" "><nodename>\addtolength</nodename><nodenext automatic="on">\settodepth</nodenext><nodeprev automatic="on">\setlength</nodeprev><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle><code>\addtolength</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="495" mergedindex="cp">\addtolength</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="463">lengths, adding to</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addtolength{<var>len</var>}{<var>amount</var>} +</pre></example> + +<para>Increment the length <var>len</var> by <var>amount</var>. The length name +<var>len</var> begins with a backslash, <code>\</code>. The <code>amount</code> is a +rubber length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). It can be positive, negative or zero, +and can be in any units that &latex; understands (<pxref label="Units-of-length"><xrefnodename>Units of +length</xrefnodename></pxref>). +</para> +<para>Below, if <code>\parskip</code> starts with the value <code>0pt plus 1pt</code> +</para> +<example endspaces=" "> +<pre xml:space="preserve">Doctor: how is the boy who swallowed the silver dollar? +\addtolength{\parskip}{1pt} + +Nurse: no change. +</pre></example> + +<noindent></noindent> +<para>then it has the value <code>1pt plus 1pt</code> for the second paragraph. +</para> +<para>If you did not declare the length <var>len</var> with <code>\newlength</code>, if +for example you mistype the above as +<code>\addtolength{\specparindent}{0.6\praindent}</code>, then you get +something like <samp>Undefined control sequence. <argument> \praindent</samp>. +If you leave off the backslash at the start of <var>len</var>, as in +<code>\addtolength{parindent}{1pt}</code>, then you get something like +<samp>You can't use `the letter p' after \advance</samp>. +</para> + +</section> +<node name="_005csettodepth" spaces=" "><nodename>\settodepth</nodename><nodenext automatic="on">\settoheight</nodenext><nodeprev automatic="on">\addtolength</nodeprev><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle><code>\settodepth</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="496" mergedindex="cp">\settodepth</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\settodepth{<var>len</var>}{<var>text</var>} +</pre></example> + +<para>Set the length <var>len</var> to the depth of box that &latex; gets on +typesetting the <var>text</var> argument. The length name <var>len</var> must +begin with a backslash, <code>\</code>. +</para> +<para>This will show how low the character descenders go. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{\alphabetdepth} +\settodepth{\alphabetdepth}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetdepth +</pre></example> + +<para>If you did not set aside the length <var>len</var>, if for example you +mistype the above as <code>\settodepth{\aplhabetdepth}{abc...}</code>, +then you get something like <samp>Undefined control sequence. <argument> +\aplhabetdepth</samp>. If you leave the backslash out of <var>len</var>, as in +<code>\settodepth{alphabetdepth}{...}</code> then you get something like +<samp>Missing number, treated as zero. <to be read again> \setbox</samp>. +</para> + +</section> +<node name="_005csettoheight" spaces=" "><nodename>\settoheight</nodename><nodenext automatic="on">\settowidth</nodenext><nodeprev automatic="on">\settodepth</nodeprev><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle><code>\settoheight</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="497" mergedindex="cp">\settoheight</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\settoheight{<var>len</var>}{text} +</pre></example> + +<para>Sets the length <var>len</var> to the height of box that &latex; gets on +typesetting the <code>text</code> argument. The length name <var>len</var> must +begin with a backslash, <code>\</code>. +</para> +<para>This will show how high the characters go. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{\alphabetheight} +\settoheight{\alphabetheight}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetheight +</pre></example> + +<para>If no such length <var>len</var> has been declared with <code>\newlength</code>, if +for example you mistype as +<code>\settoheight{\aplhabetheight}{abc...}</code>, then you get something +like <samp>Undefined control sequence. <argument> \alphabetheight</samp>. If +you leave the backslash out of <var>len</var>, as in +<code>\settoheight{alphabetheight}{...}</code> then you get something like +<samp>Missing number, treated as zero. <to be read again> \setbox</samp>. +</para> + +</section> +<node name="_005csettowidth" spaces=" "><nodename>\settowidth</nodename><nodeprev automatic="on">\settoheight</nodeprev><nodeup automatic="on">Lengths</nodeup></node> +<section spaces=" "><sectiontitle><code>\settowidth</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="498" mergedindex="cp">\settowidth</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\settowidth{<var>len</var>}{<var>text</var>} +</pre></example> + +<para>Set the length <var>len</var> to the width of the box that &latex; gets on +typesetting the <var>text</var> argument. The length name <var>len</var> must +begin with a backslash, <code>\</code>. +</para> +<para>This measures the width of the lowercase ASCII alphabet. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{\alphabetwidth} +\settowidth{\alphabetwidth}{abcdefghijklmnopqrstuvwxyz} +\the\alphabetwidth +</pre></example> + +<para>If no such length <var>len</var> has been set aside, if for example you +mistype the above as <code>\settowidth{\aplhabetwidth}{abc...}</code>, +then you get something like <samp>Undefined control sequence. <argument> +\aplhabetwidth</samp>. If you leave the backslash out of <var>len</var>, as in +<code>\settoheight{alphabetwidth}{...}</code> then you get something like +<samp>Missing number, treated as zero. <to be read again> \setbox</samp>. +</para> + +</section> +</chapter> +<node name="Making-paragraphs" spaces=" "><nodename>Making paragraphs</nodename><nodenext automatic="on">Math formulas</nodenext><nodeprev automatic="on">Lengths</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Making paragraphs</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="464">making paragraphs</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="465">paragraphs</indexterm></cindex> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">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?'' +</pre></example> + +<para>The separator lines must be empty, including not containing a comment +character, <code>%</code>. +</para> +<para>Once &latex; has gathered all of a paragraph&textrsquo;s contents it divides that +content into lines in a way that is optimized over the entire paragraph +(<pxref label="Line-breaking"><xrefnodename>Line breaking</xrefnodename></pxref>). +</para> +<para>There are places where a new paragraph is not permitted. Don&textrsquo;t put a +blank line in math mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>); here the line before the +<code>\end{equation}</code> +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} + 2^{|S|} > |S| + +\end{equation} +</pre></example> + +<noindent></noindent> +<para>will get you the error <samp>Missing $ inserted</samp>. Similarly, the blank +line in this <code>section</code> argument +</para> +<example endspaces=" "> +<pre xml:space="preserve">\section{aaa + +bbb} +</pre></example> + +<noindent></noindent> +<para>gets <samp>Runaway argument? {aaa ! Paragraph ended before \&arobase;sect was +complete</samp>. +</para> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\par</menunode><menudescription><pre xml:space="preserve">End the current paragraph. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\indent & \noindent</menunode><menudescription><pre xml:space="preserve">Go into horizontal mode, possibly with an indent. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\parindent & \parskip</menunode><menudescription><pre xml:space="preserve">Space added before paragraphs. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Marginal notes</menunode><menudescription><pre xml:space="preserve">Put remarks in the margin. +</pre></menudescription></menuentry></menu> + + +<node name="_005cpar" spaces=" "><nodename>\par</nodename><nodenext automatic="on">\indent & \noindent</nodenext><nodeup automatic="on">Making paragraphs</nodeup></node> +<section spaces=" "><sectiontitle><code>\par</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="499" mergedindex="cp">\par</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="466">paragraph, ending</indexterm></cindex> + +<para>Synopsis (note that while reading the input &tex; converts two +consecutive newlines to a <code>\par</code>): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\par +</pre></example> + +<para>End the current paragraph. The usual way to separate paragraphs is with +a blank line but the <code>\par</code> command is entirely equivalent. This +command is robust (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This example uses <code>\par</code> rather than a blank line simply for +readability. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\syllabusLegalese}{% + \whatCheatingIs\par\whatHappensWhenICatchYou} +</pre></example> + +<para>In LR mode or a vertical mode the <code>\par</code> command does nothing but +it terminates paragraph mode, switching &latex; to vertical mode +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<para>You cannot use the <code>\par</code> command in a math mode. You also cannot +use it in the argument of many commands, such as the <code>\section</code> +command (<pxref label="Making-paragraphs"><xrefnodename>Making paragraphs</xrefnodename></pxref> and <ref label="_005cnewcommand-_0026-_005crenewcommand"><xrefnodename>\newcommand & +\renewcommand</xrefnodename></ref>). +</para> +<para>The <code>\par</code> command is not the same as the <code>\paragraph</code> +command. The latter is, like <code>\section</code> or <code>\subsection</code>, a +sectioning unit used by the standard &latex; documents +(<pxref label="_005csubsubsection-_0026-_005cparagraph-_0026-_005csubparagraph"><xrefnodename>\subsubsection & \paragraph & \subparagraph</xrefnodename></pxref>). +</para> +<para>The <code>\par</code> command is not the same as <code>\newline</code> or the line +break double backslash, <code>\\</code>. The difference is that <code>\par</code> +ends the paragraph, not just the line, and also triggers the addition of +the between-paragraph vertical space <code>\parskip</code> (<pxref label="_005cparindent-_0026-_005cparskip"><xrefnodename>\parindent +& \parskip</xrefnodename></pxref>). +</para> +<para>The output from this example +</para> +<example endspaces=" "> +<pre xml:space="preserve">xyz + +\setlength{\parindent}{3in} +\setlength{\parskip}{5in} +\noindent test\indent test1\par test2 +</pre></example> + +<noindent></noindent> +<para>is: after <samp>xyz</samp> there is a vertical skip of 5 inches and then +<samp>test</samp> appears, aligned with the left margin. On the same line, +there is an empty horizontal space of 3 inches and then +<samp>test1</samp> 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 <samp>test2</samp>. +</para> + +</section> +<node name="_005cindent-_0026-_005cnoindent" spaces=" "><nodename>\indent & \noindent</nodename><nodenext automatic="on">\parindent & \parskip</nodenext><nodeprev automatic="on">\par</nodeprev><nodeup automatic="on">Making paragraphs</nodeup></node> +<section spaces=" "><sectiontitle><code>\indent</code> & <code>\noindent</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="500" mergedindex="cp">\indent</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="501" mergedindex="cp">\noindent</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="502" mergedindex="cp">\parindent</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="467">indent, forcing</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\indent +</pre></example> + +<noindent></noindent> <para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\noindent +</pre></example> + +<para>Go into horizontal mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). The <code>\indent</code> command +first outputs an empty box whose width is <code>\parindent</code>. These +commands are robust (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Ordinarily you create a new paragraph by putting in a blank line. +<xref label="_005cpar"><xrefnodename>\par</xrefnodename></xref> for the difference between this command and <code>\par</code>. To +start a paragraph without an indent, or to continue an interrupted +paragraph, use <code>\noindent</code>. +</para> +<para>In the middle of a paragraph the <code>\noindent</code> command has no effect, +because &latex; is already in horizontal mode there. The +<code>\indent</code> command&textrsquo;s only effect is to output a space. +</para> +<para>This example starts a fresh paragraph. +</para> +<example endspaces=" "> +<pre xml:space="preserve">... end of the prior paragraph. + +\noindent This paragraph is not indented. +</pre></example> + +<noindent></noindent> +<para>and this continues an interrupted paragraph. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The data + +\begin{center} + \begin{tabular}{rl} ... \end{tabular} +\end{center} + +\noindent shows this clearly. +</pre></example> + +<para>To omit indentation in the entire document put +<code>\setlength{\parindent}{0pt}</code> in the preamble. If you do that, +you may want to also set the length of spaces between paragraphs, +<code>\parskip</code> (<pxref label="_005cparindent-_0026-_005cparskip"><xrefnodename>\parindent & \parskip</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="468"><r>package</r>, <code>indentfirst</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="469"><code>indentfirst</code> <r>package</r></indexterm></cindex> + +<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 <code>indentfirst</code>. +</para> + +</section> +<node name="_005cparindent-_0026-_005cparskip" spaces=" "><nodename>\parindent & \parskip</nodename><nodenext automatic="on">Marginal notes</nodenext><nodeprev automatic="on">\indent & \noindent</nodeprev><nodeup automatic="on">Making paragraphs</nodeup></node> +<section spaces=" "><sectiontitle><code>\parindent</code> & <code>\parskip</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="503" mergedindex="cp">\parindent</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="504" mergedindex="cp">\parskip</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="470">paragraph indentation</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="471">vertical space before paragraphs</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\parskip}{<var>horizontal len</var>} +\setlength{\parinden}{<var>vertical len</var>} +</pre></example> + +<para>Both are a rubber lengths (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). They give the indentation +of ordinary paragraphs, not paragraphs inside minipages +(<pxref label="minipage"><xrefnodename>minipage</xrefnodename></pxref>), and the vertical space between paragraphs. +</para> +<para>This, put in the preamble, +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\parindent}{0em} +\setlength{\parskip}{1ex} +</pre></example> + +<noindent></noindent> +<para>arranges that the document will have paragraphs that are not indented, +but instead are vertically separated by about the height of a lowercase +<samp>x</samp>. +</para> +<para>In standard &latex; documents, the default value for <code>\parindent</code> +in one-column documents is <code>15pt</code> when the default text size is +<code>10pt</code> , <code>17pt</code> for <code>11pt</code>, and <code>1.5em</code> for +<code>12pt</code>. In two-column documents it is <code>1em</code>. The default +value for <code>\parskip</code> in &latex;&textrsquo;s standard document styles is +<code>0pt plus1pt</code>. +</para> + +</section> +<node name="Marginal-notes" spaces=" "><nodename>Marginal notes</nodename><nodeprev automatic="on">\parindent & \parskip</nodeprev><nodeup automatic="on">Making paragraphs</nodeup></node> +<section spaces=" "><sectiontitle>Marginal notes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="472">marginal notes</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="473">notes in the margin</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="474">remarks in the margin</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="505" mergedindex="cp">\marginpar</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\marginpar{<var>right</var>} +\marginpar[<var>left</var>]{<var>right</var>} +</pre></example> + +<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 <code>\marginpar</code> +occurs. +</para> +<para>The margin that &latex; uses for the note depends on the current layout +(<pxref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></pxref>) and also on <code>\reversemarginpar</code> +(see below). If you are using one-sided layout (document option +<code>oneside</code>) then it goes in the right margin. If you are using +two-sided layout (document option <code>twoside</code>) then it goes in the +outside margin. If you are in two-column layout (document option +<code>twocolumn</code>) then it goes in the nearest margin. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="506" mergedindex="cp">\reversemarginpar</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="507" mergedindex="cp">\normalmarginpar</indexterm></findex> +<para>If you declare <code>\reversemarginpar</code> 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 +<code>\normalmarginpar</code>. +</para> +<para>When you specify the optional argument <var>left</var> then it is used for +a note in the left margin, while the mandatory argument <var>right</var> is +used for a note in the right margin. +</para> +<para>Normally, a note&textrsquo;s first word will not be hyphenated. You can enable +hyphenation there by beginning <var>left</var> or <var>right</var> with +<code>\hspace{0pt}</code>. +</para> +<para>These parameters affect the formatting of the note: +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="508" mergedindex="cp">\marginparpush</indexterm>\marginparpush</itemformat></item> +</tableterm><tableitem><anchor name="marginal-notes-marginparpush">marginal notes marginparpush</anchor> +<para>Minimum vertical space between notes; default <samp>7pt</samp> for +<samp>12pt</samp> documents, <samp>5pt</samp> else. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="509" mergedindex="cp">\marginparsep</indexterm>\marginparsep</itemformat></item> +</tableterm><tableitem><anchor name="marginal-notes-marginparsep">marginal notes marginparsep</anchor> +<para>Horizontal space between the main text and the note; default +<samp>11pt</samp> for <samp>10pt</samp> documents, <samp>10pt</samp> else. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="510" mergedindex="cp">\marginparwidth</indexterm>\marginparwidth</itemformat></item> +</tableterm><tableitem><anchor name="marginal-notes-marginparwidth">marginal notes marginparwidth</anchor> +<para>Width of the note itself; default for a one-sided <samp>10pt</samp> document +is <samp>90pt</samp>, <samp>83pt</samp> for <samp>11pt</samp>, and <samp>68pt</samp> for +<samp>12pt</samp>; <samp>17pt</samp> more in each case for a two-sided document. +In two column mode, the default is <samp>48pt</samp>. +</para> +</tableitem></tableentry></ftable> + +<para>The standard &latex; routine for marginal notes does not prevent +notes from falling off the bottom of the page. +<!-- c @TeX{} FAQ entry on this topic (xx when there): --> +<!-- c @url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=marginparside}. --> +<!-- c (+marginfix) --> +</para> + +</section> +</chapter> +<node name="Math-formulas" spaces=" "><nodename>Math formulas</nodename><nodenext automatic="on">Modes</nodenext><nodeprev automatic="on">Making paragraphs</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Math formulas</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="475">math formulas</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="476">formulas, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="477">math mode, entering</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="511" mergedindex="cp"><r>environment</r>, <code>math</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="512" mergedindex="cp"><code>math</code> <r>environment</r></indexterm></findex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="513" mergedindex="cp"><r>environment</r>, <code>displaymath</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="514" mergedindex="cp"><code>displaymath</code> <r>environment</r></indexterm></findex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="515" mergedindex="cp"><r>environment</r>, <code>equation</code></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="516" mergedindex="cp"><code>equation</code> <r>environment</r></indexterm></findex> + + +<para>Produce mathematical text by putting &latex; into math mode or display +math mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). This example shows both. +</para> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<noindent></noindent> +<para>Math mode is for inline mathematics. In the above example it is invoked +by the starting <code>\(</code> and finished by the matching ending <code>\)</code>. +Display math mode is for displayed equations and here is invoked by the +<code>displaymath</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">contrast x+y with \( x+y \) +</pre></example> + +<noindent></noindent> +<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> +<example endspaces=" "> +<pre xml:space="preserve">\( <var>mathematical material</var> \) +$ <var>mathematical material</var> $ +\begin{math} <var>mathematical material</var> \end{math} +</pre></example> + +<noindent></noindent> +<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 <code>\(x\) and $y$</code>. You can use these in paragraph +mode or in LR mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<para>To make displayed formulas, put &latex; into display math mode with +either: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{displaymath} + <var>mathematical material</var> +\end{displaymath} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} + <var>mathematical material</var> +\end{equation} +</pre></example> + +<noindent></noindent> +<para>(<pxref label="displaymath"><xrefnodename>displaymath</xrefnodename></pxref>, <pxref label="equation"><xrefnodename>equation</xrefnodename></pxref>). The only difference is that +with the <code>equation</code> environment, &latex; puts a formula number +alongside the formula. The construct <code>\[ <var>math</var> \]</code> is +equivalent to <code>\begin{displaymath} <var>math</var> +\end{displaymath}</code>. These environments can only be used in paragraph +mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="517" mergedindex="cp">\displaystyle</indexterm></findex> +<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 <code>\displaystyle</code> declaration +forces the size and style of the formula to be that of +<code>displaymath</code>. Thus <code>\(\displaystyle \sum_{n=0}^\infty +x_n\)</code> will have the limits above and below the summation sign, not next +to it. Another example is that +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>because it has no <code>\displaystyle</code>, the <samp>Arithmetic</samp> line&textrsquo;s +fraction will be scrunched. But, because of its <code>\displaystyle</code>, +the <samp>Geometric</samp> line&textrsquo;s fraction will be easy to read, with +characters the same size as in the rest of the line. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="478"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="479"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="480"><r>package</r>, <code>amsfonts</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="481"><code>amsfonts</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="482"><r>package</r>, <code>mathtools</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="483"><code>mathtools</code> <r>package</r></indexterm></cindex> + +<para>The American Mathematical Society has made freely available a set of +packages that greatly expand your options for writing mathematics, +<file>amsmath</file> and <file>amssymb</file> (also be aware of the <file>mathtools</file> +package that is an extension to, and loads, <file>amsmath</file>). 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> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Subscripts & superscripts</menunode><menudescription><pre xml:space="preserve">Also known as exponent or index. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Math symbols</menunode><menudescription><pre xml:space="preserve">Various mathematical squiggles. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Math functions</menunode><menudescription><pre xml:space="preserve">Math function names like sin and exp. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Math accents</menunode><menudescription><pre xml:space="preserve">Accents in math. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Over- and Underlining</menunode><menudescription><pre xml:space="preserve">Things over or under formulas. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Spacing in math mode</menunode><menudescription><pre xml:space="preserve">Thick, medium, thin, and negative spaces. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Math miscellany</menunode><menudescription><pre xml:space="preserve">Stuff that doesn&textrsquo;t fit anywhere else. +</pre></menudescription></menuentry></menu> + + +<node name="Subscripts-_0026-superscripts" spaces=" "><nodename>Subscripts & superscripts</nodename><nodenext automatic="on">Math symbols</nodenext><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Subscripts & superscripts</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="484">superscript</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="485">subscript</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="486">exponent</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="518" mergedindex="cp">_</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="519" mergedindex="cp">^</indexterm></findex> + +<para>Synopsis (in math mode or display math mode), one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>base</var>^<var>exp</var> +<var>base</var>^{<var>exp</var>} +</pre></example> + +<noindent></noindent> +<para>or, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>base</var>_<var>exp</var> +<var>base</var>_{<var>exp</var>} +</pre></example> + +<para>Make <var>exp</var> appear as a superscript of <var>base</var> (with the caret +character, <code>^</code>) or a subscript (with +underscore, <code>_</code>). +</para> +<para>In this example the <code>0</code>&textrsquo;s and <code>1</code>&textrsquo;s are subscripts while the +<code>2</code>&textrsquo;s are superscripts. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\( (x_0+x_1)^2 \leq (x_0)^2+(x_1)^2 \) +</pre></example> + +<para>To have the subscript or superscript contain more than one character, +surround the expression with curly braces, as in <code>e^{-2x}</code>. +This example&textrsquo;s fourth line shows curly braces used to group an expression +for the exponent. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{displaymath} + (3^3)^3=27^3=19\,683 + \qquad + 3^{(3^3)}=3^{27}=7\,625\,597\,484\,987 +\end{displaymath} +</pre></example> + +<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 <code>e^{x^2}</code> and <code>x_{i_0}</code> give correct +output. Note the use in those expressions of curly braces to give the +<var>base</var> a determined <var>exp</var>. If you enter <code>\(3^3^3\)</code> then +you get <samp>Double superscript</samp>. +</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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{displaymath} + \int_{x=a}^b f'(x)\,dx = f(b)-f(a) +\end{displaymath} +</pre></example> + +<noindent></noindent> +<para>Note the parentheses around <code>x=a</code> to make the entire expression a +subscript. +</para> +<para>To put a superscript or subscript before a symbol, use a construct like +<code>{}_t K^2</code>. The empty curly braces <code>{}</code> 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 <code>the expression x^2</code>, will get you +the error <samp>Missing $ inserted</samp>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="487"><r>package</r>, <code>mhchem</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="488"><code>mhchem</code> <r>package</r></indexterm></cindex> + +<para>A common reason to want subscripts outside of a mathematics mode is to +typeset chemical formulas. There are packages for that such as +<file>mhchem</file>; see CTAN. +</para> + +</section> +<node name="Math-symbols" spaces=" "><nodename>Math symbols</nodename><nodenext automatic="on">Math functions</nodenext><nodeprev automatic="on">Subscripts & superscripts</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Math symbols</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="489">math symbols</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="490">symbols, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="491">greek letters</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="492"><r>package</r>, <code>symbols</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="493"><code>symbols</code> <r>package</r></indexterm></cindex> + + +<para>&latex; provides almost any mathematical or technical symbol that +anyone uses. For example, if you include <code>$\pi$</code> in your source, +you will get the pi symbol <U>03C0</U>. See the <file>Comprehensive +&latex; Symbol List</file> at +<url><urefurl>https://ctan.org/tex-archive/info/symbols/comprehensive/</urefurl></url>. +</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 <ref label="_005censuremath"><xrefnodename>\ensuremath</xrefnodename></ref>. +</para> +<!-- c xx Add Negation: for negations of relevant symbols --> +<!-- c Useful: http://www.w3.org/TR/WD-math-970515/section6.html --> + +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="520" mergedindex="cp">\|</indexterm>\|</itemformat></item> +</tableterm><tableitem><para><U>2225</U> Parallel (relation). Synonym: <code>\parallel</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="521" mergedindex="cp">\aleph</indexterm>\aleph</itemformat></item> +</tableterm><tableitem><para><U>2135</U> Aleph, transfinite cardinal (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="522" mergedindex="cp">\alpha</indexterm>\alpha</itemformat></item> +</tableterm><tableitem><para><U>03B1</U> Lowercase Greek letter alpha (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="523" mergedindex="cp">\amalg</indexterm>\amalg</itemformat></item> +</tableterm><tableitem><para><U>2A3F</U> Disjoint union (binary) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="524" mergedindex="cp">\angle</indexterm>\angle</itemformat></item> +</tableterm><tableitem><para><U>2220</U> Geometric angle (ordinary). Similar: less-than +sign <code><</code> and angle bracket <code>\langle</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="525" mergedindex="cp">\approx</indexterm>\approx</itemformat></item> +</tableterm><tableitem><para><U>2248</U> Almost equal to (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="526" mergedindex="cp">\ast</indexterm>\ast</itemformat></item> +</tableterm><tableitem><para><U>2217</U> Asterisk operator, convolution, six-pointed +(binary). Synonym: <code>*</code>, which is often a superscript or +subscript, as in the Kleene star. Similar: <code>\star</code>, which is +five-pointed, and is sometimes used as a general binary operation, and +sometimes reserved for cross-correlation. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="527" mergedindex="cp">\asymp</indexterm>\asymp</itemformat></item> +</tableterm><tableitem><para><U>224D</U> Asymptotically equivalent (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="528" mergedindex="cp">\backslash</indexterm>\backslash</itemformat></item> +</tableterm><tableitem><para>\ Backslash (ordinary). Similar: set minus <code>\setminus</code>, and +<code>\textbackslash</code> for backslash outside of math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="529" mergedindex="cp">\beta</indexterm>\beta</itemformat></item> +</tableterm><tableitem><para><U>03B2</U> Lowercase Greek letter beta (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="530" mergedindex="cp">\bigcap</indexterm>\bigcap</itemformat></item> +</tableterm><tableitem><para><U>22C2</U> Variable-sized, or n-ary, intersection (operator). Similar: +binary intersection <code>\cap</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="531" mergedindex="cp">\bigcirc</indexterm>\bigcirc</itemformat></item> +</tableterm><tableitem><para><U>26AA</U> Circle, larger (binary). Similar: function +composition <code>\circ</code>. +<!-- c bb Best unicode symbol for this? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="532" mergedindex="cp">\bigcup</indexterm>\bigcup</itemformat></item> +</tableterm><tableitem><para><U>22C3</U> Variable-sized, or n-ary, union (operator). Similar: binary +union <code>\cup</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="533" mergedindex="cp">\bigodot</indexterm>\bigodot</itemformat></item> +</tableterm><tableitem><para><U>2A00</U> Variable-sized, or n-ary, circled dot operator (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="534" mergedindex="cp">\bigoplus</indexterm>\bigoplus</itemformat></item> +</tableterm><tableitem><para><U>2A01</U> Variable-sized, or n-ary, circled plus operator (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="535" mergedindex="cp">\bigotimes</indexterm>\bigotimes</itemformat></item> +</tableterm><tableitem><para><U>2A02</U> Variable-sized, or n-ary, circled times operator (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="536" mergedindex="cp">\bigtriangledown</indexterm>\bigtriangledown</itemformat></item> +</tableterm><tableitem><para><U>25BD</U> Variable-sized, or n-ary, open triangle pointing down +(operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="537" mergedindex="cp">\bigtriangleup</indexterm>\bigtriangleup</itemformat></item> +</tableterm><tableitem><para><U>25B3</U> Variable-sized, or n-ary, open triangle pointing up (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="538" mergedindex="cp">\bigsqcup</indexterm>\bigsqcup</itemformat></item> +</tableterm><tableitem><para><U>2A06</U> Variable-sized, or n-ary, square union (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="539" mergedindex="cp">\biguplus</indexterm>\biguplus</itemformat></item> +</tableterm><tableitem><para><U>2A04</U> Variable-sized, or n-ary, union operator with a plus +(operator). (Note that the name has only one p.) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="540" mergedindex="cp">\bigvee</indexterm>\bigvee</itemformat></item> +</tableterm><tableitem><para><U>22C1</U> Variable-sized, or n-ary, logical-and (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="541" mergedindex="cp">\bigwedge</indexterm>\bigwedge</itemformat></item> +</tableterm><tableitem><para><U>22C0</U> Variable-sized, or n-ary, logical-or (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="542" mergedindex="cp">\bot</indexterm>\bot</itemformat></item> +</tableterm><tableitem><para><U>22A5</U> Up tack, bottom, least element of a partially ordered +set, or a contradiction (ordinary). See also <code>\top</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="543" mergedindex="cp">\bowtie</indexterm>\bowtie</itemformat></item> +</tableterm><tableitem><para><U>22C8</U> Natural join of two relations (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="544" mergedindex="cp">\Box</indexterm>\Box</itemformat></item> +</tableterm><tableitem><para><U>25A1</U> Modal operator for necessity; square open box +(ordinary). Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +<!-- c bb Best Unicode equivalent? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="545" mergedindex="cp">\bullet</indexterm>\bullet</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="494">bullet symbol</indexterm></cindex> +<para><U>2022</U> Bullet (binary). Similar: multiplication +dot <code>\cdot</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="546" mergedindex="cp">\cap</indexterm>\cap</itemformat></item> +</tableterm><tableitem><para><U>2229</U> Intersection of two sets (binary). Similar: variable-sized +operator <code>\bigcap</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="547" mergedindex="cp">\cdot</indexterm>\cdot</itemformat></item> +</tableterm><tableitem><para><U>22C5</U> Multiplication (binary). Similar: Bullet +dot <code>\bullet</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="548" mergedindex="cp">\chi</indexterm>\chi</itemformat></item> +</tableterm><tableitem><para><U>03C7</U> Lowercase Greek chi (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="549" mergedindex="cp">\circ</indexterm>\circ</itemformat></item> +</tableterm><tableitem><para><U>2218</U> Function composition, ring operator (binary). Similar: +variable-sized operator <code>\bigcirc</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="550" mergedindex="cp">\clubsuit</indexterm>\clubsuit</itemformat></item> +</tableterm><tableitem><para><U>2663</U> Club card suit (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="551" mergedindex="cp">\complement</indexterm>\complement</itemformat></item> +</tableterm><tableitem><para><U>2201</U> Set complement, used as a superscript as in +<code>$S^\complement$</code> (ordinary). Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. Also used: +<code>$S^{\mathsf{c}}$</code> or <code>$\bar{S}$</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="552" mergedindex="cp">\cong</indexterm>\cong</itemformat></item> +</tableterm><tableitem><para><U>2245</U> Congruent (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="553" mergedindex="cp">\coprod</indexterm>\coprod</itemformat></item> +</tableterm><tableitem><para><U>2210</U> Coproduct (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="554" mergedindex="cp">\cup</indexterm>\cup</itemformat></item> +</tableterm><tableitem><para><U>222A</U> Union of two sets (binary). Similar: variable-sized +operator <code>\bigcup</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="555" mergedindex="cp">\dagger</indexterm>\dagger</itemformat></item> +</tableterm><tableitem><para><U>2020</U> Dagger relation (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="556" mergedindex="cp">\dashv</indexterm>\dashv</itemformat></item> +</tableterm><tableitem><para><U>22A3</U> Dash with vertical, reversed turnstile (relation). Similar: +turnstile <code>\vdash</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="557" mergedindex="cp">\ddagger</indexterm>\ddagger</itemformat></item> +</tableterm><tableitem><para><U>2021</U> Double dagger relation (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="558" mergedindex="cp">\Delta</indexterm>\Delta</itemformat></item> +</tableterm><tableitem><para><U>0394</U> Greek uppercase delta, used for increment (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="559" mergedindex="cp">\delta</indexterm>\delta</itemformat></item> +</tableterm><tableitem><para><U>03B4</U> Greek lowercase delta (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="560" mergedindex="cp">\Diamond</indexterm>\Diamond</itemformat></item> +</tableterm><tableitem><para><U>25C7</U> Large diamond operator (ordinary). Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="561" mergedindex="cp">\diamond</indexterm>\diamond</itemformat></item> +</tableterm><tableitem><para><U>22C4</U> Diamond operator (binary). Similar: large +diamond <code>\Diamond</code>, circle bullet <code>\bullet</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="562" mergedindex="cp">\diamondsuit</indexterm>\diamondsuit</itemformat></item> +</tableterm><tableitem><para><U>2662</U> Diamond card suit (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="563" mergedindex="cp">\div</indexterm>\div</itemformat></item> +</tableterm><tableitem><para><U>00F7</U> Division sign (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="564" mergedindex="cp">\doteq</indexterm>\doteq</itemformat></item> +</tableterm><tableitem><para><U>2250</U> Approaches the limit (relation). Similar: geometrically equal +to <code>\Doteq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="565" mergedindex="cp">\downarrow</indexterm>\downarrow</itemformat></item> +</tableterm><tableitem><para><U>2193</U> Down arrow, converges (relation). Similar: +<code>\Downarrow</code> double line down arrow. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="566" mergedindex="cp">\Downarrow</indexterm>\Downarrow</itemformat></item> +</tableterm><tableitem><para><U>21D3</U> Double line down arrow (relation). Similar: +<code>\downarrow</code> single line down arrow. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="567" mergedindex="cp">\ell</indexterm>\ell</itemformat></item> +</tableterm><tableitem><para><U>2113</U> Lowercase cursive letter l (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="568" mergedindex="cp">\emptyset</indexterm>\emptyset</itemformat></item> +</tableterm><tableitem><para><U>2205</U> Empty set symbol (ordinary). The variant form is +<code>\varnothing</code>. +<!-- c bb Why Unicode has \revemptyset but no \emptyset? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="569" mergedindex="cp">\epsilon</indexterm>\epsilon</itemformat></item> +</tableterm><tableitem><para><U>03F5</U> Lowercase lunate epsilon (ordinary). Similar to +Greek text letter. More widely used in mathematics is the script small +letter epsilon <code>\varepsilon</code> <U>03B5</U>. Related: +the set membership relation <code>\in</code> <U>2208</U>. +<!-- c src: David Carlisle http://tex.stackexchange.com/a/98018/339 and --> +<!-- c Unicode referenced there asserts varepsilon is much more widely used. --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="570" mergedindex="cp">\equiv</indexterm>\equiv</itemformat></item> +</tableterm><tableitem><para><U>2261</U> Equivalence (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="571" mergedindex="cp">\eta</indexterm>\eta</itemformat></item> +</tableterm><tableitem><para><U>03B7</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="572" mergedindex="cp">\exists</indexterm>\exists</itemformat></item> +</tableterm><tableitem><para><U>2203</U> Existential quantifier (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="573" mergedindex="cp">\flat</indexterm>\flat</itemformat></item> +</tableterm><tableitem><para><U>266D</U> Musical flat (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="574" mergedindex="cp">\forall</indexterm>\forall</itemformat></item> +</tableterm><tableitem><para><U>2200</U> Universal quantifier (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="575" mergedindex="cp">\frown</indexterm>\frown</itemformat></item> +</tableterm><tableitem><para><U>2322</U> Downward curving arc (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="576" mergedindex="cp">\Gamma</indexterm>\Gamma</itemformat></item> +</tableterm><tableitem><para><U>0393</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="577" mergedindex="cp">\gamma</indexterm>\gamma</itemformat></item> +</tableterm><tableitem><para><U>03B3</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="578" mergedindex="cp">\ge</indexterm>\ge</itemformat></item> +</tableterm><tableitem><para><U>2265</U> Greater than or equal to (relation). This is a synonym +for <code>\geq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="579" mergedindex="cp">\geq</indexterm>\geq</itemformat></item> +</tableterm><tableitem><para><U>2265</U> Greater than or equal to (relation). This is a synonym +for <code>\ge</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="580" mergedindex="cp">\gets</indexterm>\gets</itemformat></item> +</tableterm><tableitem><para><U>2190</U> Is assigned the value (relation). +Synonym: <code>\leftarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="581" mergedindex="cp">\gg</indexterm>\gg</itemformat></item> +</tableterm><tableitem><para><U>226B</U> Much greater than (relation). Similar: much less +than <code>\ll</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="582" mergedindex="cp">\hbar</indexterm>\hbar</itemformat></item> +</tableterm><tableitem><para><U>210F</U> Planck constant over two pi (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="583" mergedindex="cp">\heartsuit</indexterm>\heartsuit</itemformat></item> +</tableterm><tableitem><para><U>2661</U> Heart card suit (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="584" mergedindex="cp">\hookleftarrow</indexterm>\hookleftarrow</itemformat></item> +</tableterm><tableitem><para><U>21A9</U> Hooked left arrow (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="585" mergedindex="cp">\hookrightarrow</indexterm>\hookrightarrow</itemformat></item> +</tableterm><tableitem><para><U>21AA</U> Hooked right arrow (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="586" mergedindex="cp">\iff</indexterm>\iff</itemformat></item> +</tableterm><tableitem><para><U>27F7</U> If and only if (relation). It is <code>\Longleftrightarrow</code> +with a <code>\thickmuskip</code> on either side. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="587" mergedindex="cp">\Im</indexterm>\Im</itemformat></item> +</tableterm><tableitem><para><U>2111</U> Imaginary part (ordinary). See: real part <code>\Re</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="588" mergedindex="cp">\imath</indexterm>\imath</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="495">dotless i, math</indexterm></cindex> +<para>Dotless i; used when you are putting an accent on an i (<pxref label="Math-accents"><xrefnodename>Math +accents</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="589" mergedindex="cp">\in</indexterm>\in</itemformat></item> +</tableterm><tableitem><para><U>2208</U> Set element (relation). See also: lowercase lunate +epsilon <code>\epsilon</code><U>03F5</U> and small letter script +epsilon <code>\varepsilon</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="590" mergedindex="cp">\infty</indexterm>\infty</itemformat></item> +</tableterm><tableitem><para><U>221E</U> Infinity (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="591" mergedindex="cp">\int</indexterm>\int</itemformat></item> +</tableterm><tableitem><para><U>222B</U> Integral (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="592" mergedindex="cp">\iota</indexterm>\iota</itemformat></item> +</tableterm><tableitem><para><U>03B9</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="593" mergedindex="cp">\Join</indexterm>\Join</itemformat></item> +</tableterm><tableitem><para><U>2A1D</U> Condensed bowtie symbol (relation). Not available in Plain +&tex;. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="594" mergedindex="cp">\jmath</indexterm>\jmath</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="496">dotless j, math</indexterm></cindex> +<para>Dotless j; used when you are putting an accent on a j (<pxref label="Math-accents"><xrefnodename>Math +accents</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="595" mergedindex="cp">\kappa</indexterm>\kappa</itemformat></item> +</tableterm><tableitem><para><U>03BA</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="596" mergedindex="cp">\Lambda</indexterm>\Lambda</itemformat></item> +</tableterm><tableitem><para><U>039B</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="597" mergedindex="cp">\lambda</indexterm>\lambda</itemformat></item> +</tableterm><tableitem><para><U>03BB</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="598" mergedindex="cp">\land</indexterm>\land</itemformat></item> +</tableterm><tableitem><para><U>2227</U> Logical and (binary). This is a synonym for <code>\wedge</code>. +See also logical or <code>\lor</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="599" mergedindex="cp">\langle</indexterm>\langle</itemformat></item> +</tableterm><tableitem><para><U>27E8</U> Left angle, or sequence, bracket (opening). Similar: +less-than <code><</code>. Matches <code>\rangle</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="600" mergedindex="cp">\lbrace</indexterm>\lbrace</itemformat></item> +</tableterm><tableitem><para><U>007B</U> Left curly brace +(opening). Synonym: <code>\{</code>. Matches <code>\rbrace</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="601" mergedindex="cp">\lbrack</indexterm>\lbrack</itemformat></item> +</tableterm><tableitem><para><U>005B</U> Left square bracket (opening). +Synonym: <code>[</code>. Matches <code>\rbrack</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="602" mergedindex="cp">\lceil</indexterm>\lceil</itemformat></item> +</tableterm><tableitem><para><U>2308</U> Left ceiling bracket, like a square bracket but with the bottom +shaved off (opening). Matches <code>\rceil</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="603" mergedindex="cp">\le</indexterm>\le</itemformat></item> +</tableterm><tableitem><para><U>2264</U> Less than or equal to (relation). This is a synonym +for <code>\leq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="604" mergedindex="cp">\leadsto</indexterm>\leadsto</itemformat></item> +</tableterm><tableitem><para><U>21DD</U> Squiggly right arrow (relation). Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +To get this symbol outside of math mode you can put +<code>\newcommand*{\Leadsto}{\ensuremath{\leadsto}}</code> in the +preamble and then use <code>\Leadsto</code> instead. +<!-- c bb Best Unicode equivalent? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="605" mergedindex="cp">\Leftarrow</indexterm>\Leftarrow</itemformat></item> +</tableterm><tableitem><para><U>21D0</U> Is implied by, double-line left arrow (relation). Similar: +single-line left arrow <code>\leftarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="606" mergedindex="cp">\leftarrow</indexterm>\leftarrow</itemformat></item> +</tableterm><tableitem><para><U>2190</U> Single-line left arrow (relation). +Synonym: <code>\gets</code>. Similar: double-line left +arrow <code>\Leftarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="607" mergedindex="cp">\leftharpoondown</indexterm>\leftharpoondown</itemformat></item> +</tableterm><tableitem><para><U>21BD</U> Single-line left harpoon, barb under bar (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="608" mergedindex="cp">\leftharpoonup</indexterm>\leftharpoonup</itemformat></item> +</tableterm><tableitem><para><U>21BC</U> Single-line left harpoon, barb over bar (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="609" mergedindex="cp">\Leftrightarrow</indexterm>\Leftrightarrow</itemformat></item> +</tableterm><tableitem><para><U>21D4</U> Bi-implication; double-line double-headed arrow (relation). +Similar: single-line double headed arrow <code>\leftrightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="610" mergedindex="cp">\leftrightarrow</indexterm>\leftrightarrow</itemformat></item> +</tableterm><tableitem><para><U>2194</U> Single-line double-headed arrow (relation). Similar: +double-line double headed arrow <code>\Leftrightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="611" mergedindex="cp">\leq</indexterm>\leq</itemformat></item> +</tableterm><tableitem><para><U>2264</U> Less than or equal to (relation). This is a synonym +for <code>\le</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="612" mergedindex="cp">\lfloor</indexterm>\lfloor</itemformat></item> +</tableterm><tableitem><para><U>230A</U> Left floor bracket (opening). Matches: <code>\floor</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="613" mergedindex="cp">\lhd</indexterm>\lhd</itemformat></item> +</tableterm><tableitem><para><U>25C1</U> Arrowhead, that is, triangle, pointing left (binary). +Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. For the normal subgroup symbol you should load +<file>amssymb</file> and use <code>\vartriangleleft</code> (which is a relation +and so gives better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="614" mergedindex="cp">\ll</indexterm>\ll</itemformat></item> +</tableterm><tableitem><para><U>226A</U> Much less than (relation). Similar: much greater +than <code>\gg</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="615" mergedindex="cp">\lnot</indexterm>\lnot</itemformat></item> +</tableterm><tableitem><para><U>00AC</U> Logical negation (ordinary). Synonym: <code>\neg</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="616" mergedindex="cp">\longleftarrow</indexterm>\longleftarrow</itemformat></item> +</tableterm><tableitem><para><U>27F5</U> Long single-line left arrow (relation). Similar: long +double-line left arrow <code>\Longleftarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="617" mergedindex="cp">\longleftrightarrow</indexterm>\longleftrightarrow</itemformat></item> +</tableterm><tableitem><para><U>27F7</U> Long single-line double-headed arrow (relation). Similar: long +double-line double-headed arrow <code>\Longleftrightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="618" mergedindex="cp">\longmapsto</indexterm>\longmapsto</itemformat></item> +</tableterm><tableitem><para><U>27FC</U> Long single-line left arrow starting with vertical bar +(relation). Similar: shorter version <code>\mapsto</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="619" mergedindex="cp">\longrightarrow</indexterm>\longrightarrow</itemformat></item> +</tableterm><tableitem><para><U>27F6</U> Long single-line right arrow (relation). Similar: long +double-line right arrow <code>\Longrightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="620" mergedindex="cp">\lor</indexterm>\lor</itemformat></item> +</tableterm><tableitem><para><U>2228</U> Logical or (binary). Synonym: wedge <code>\wedge</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="621" mergedindex="cp">\mapsto</indexterm>\mapsto</itemformat></item> +</tableterm><tableitem><para><U>21A6</U> Single-line left arrow starting with vertical bar (relation). +Similar: longer version <code>\longmapsto</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="622" mergedindex="cp">\mho</indexterm>\mho</itemformat></item> +</tableterm><tableitem><para><U>2127</U> Conductance, half-circle rotated capital omega (ordinary). +Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="623" mergedindex="cp">\mid</indexterm>\mid</itemformat></item> +</tableterm><tableitem><para><U>2223</U> Single-line vertical bar (relation). A typical use of +<code>\mid</code> is for a set <code>\{\, x \mid x\geq 5 \,\}</code>. +</para> +<para>Similar: <code>\vert</code> and <code>|</code> 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 <code>\vert</code> and for norm see the entry for <code>\Vert</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="624" mergedindex="cp">\models</indexterm>\models</itemformat></item> +</tableterm><tableitem><para><U>22A8</U> Entails, or satisfies; double turnstile, short double dash +(relation). Similar: long double dash <code>\vDash</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="625" mergedindex="cp">\mp</indexterm>\mp</itemformat></item> +</tableterm><tableitem><para><U>2213</U> Minus or plus (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="626" mergedindex="cp">\mu</indexterm>\mu</itemformat></item> +</tableterm><tableitem><para><U>03BC</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="627" mergedindex="cp">\nabla</indexterm>\nabla</itemformat></item> +</tableterm><tableitem><para><U>2207</U> Hamilton&textrsquo;s del, or differential, operator (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="628" mergedindex="cp">\natural</indexterm>\natural</itemformat></item> +</tableterm><tableitem><para><U>266E</U> Musical natural notation (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="629" mergedindex="cp">\ne</indexterm>\ne</itemformat></item> +</tableterm><tableitem><para><U>2260</U> Not equal (relation). Synonym: <code>\neq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="630" mergedindex="cp">\nearrow</indexterm>\nearrow</itemformat></item> +</tableterm><tableitem><para><U>2197</U> North-east arrow (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="631" mergedindex="cp">\neg</indexterm>\neg</itemformat></item> +</tableterm><tableitem><para><U>00AC</U> Logical negation (ordinary). +Synonym: <code>\lnot</code>. Sometimes instead used for +negation: <code>\sim</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="632" mergedindex="cp">\neq</indexterm>\neq</itemformat></item> +</tableterm><tableitem><para><U>2260</U> Not equal (relation). Synonym: <code>\ne</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="633" mergedindex="cp">\ni</indexterm>\ni</itemformat></item> +</tableterm><tableitem><para><U>220B</U> Reflected membership epsilon; has the member +(relation). Synonym: <code>\owns</code>. Similar: is a member +of <code>\in</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="634" mergedindex="cp">\not</indexterm>\not</itemformat></item> +</tableterm><tableitem><!-- c the "@ "s put in spaces so the not slash doesn't hit the next char. --> +<para><U>0020</U><spacecmd type="spc"/><spacecmd type="spc"/><spacecmd type="spc"/><spacecmd type="spc"/>Long solidus, or slash, used to overstrike a +following operator (relation). +</para> +<para>Many negated operators are available that don&textrsquo;t require <code>\not</code>, +particularly with the <file>amssymb</file> package. For example, <code>\notin</code> +is typographically preferable to <code>\not\in</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="635" mergedindex="cp">\notin</indexterm>\notin</itemformat></item> +</tableterm><tableitem><para><U>2209</U> Not an element of (relation). Similar: not subset +of <code>\nsubseteq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="636" mergedindex="cp">\nu</indexterm>\nu</itemformat></item> +</tableterm><tableitem><para><U>03BD</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="637" mergedindex="cp">\nwarrow</indexterm>\nwarrow</itemformat></item> +</tableterm><tableitem><para><U>2196</U> North-west arrow (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="638" mergedindex="cp">\odot</indexterm>\odot</itemformat></item> +</tableterm><tableitem><para><U>2299</U> Dot inside a circle (binary). Similar: variable-sized +operator <code>\bigodot</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="639" mergedindex="cp">\oint</indexterm>\oint</itemformat></item> +</tableterm><tableitem><para><U>222E</U> Contour integral, integral with circle in the middle +(operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="640" mergedindex="cp">\Omega</indexterm>\Omega</itemformat></item> +</tableterm><tableitem><para><U>03A9</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="641" mergedindex="cp">\omega</indexterm>\omega</itemformat></item> +</tableterm><tableitem><para><U>03C9</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="642" mergedindex="cp">\ominus</indexterm>\ominus</itemformat></item> +</tableterm><tableitem><para><U>2296</U> Minus sign, or dash, inside a circle (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="643" mergedindex="cp">\oplus</indexterm>\oplus</itemformat></item> +</tableterm><tableitem><para><U>2295</U> Plus sign inside a circle (binary). Similar: variable-sized +operator <code>\bigoplus</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="644" mergedindex="cp">\oslash</indexterm>\oslash</itemformat></item> +</tableterm><tableitem><para><U>2298</U> Solidus, or slash, inside a circle (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="645" mergedindex="cp">\otimes</indexterm>\otimes</itemformat></item> +</tableterm><tableitem><para><U>2297</U> Times sign, or cross, inside a circle (binary). Similar: +variable-sized operator <code>\bigotimes</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="646" mergedindex="cp">\owns</indexterm>\owns</itemformat></item> +</tableterm><tableitem><para><U>220B</U> Reflected membership epsilon; has the member +(relation). Synonym: <code>\ni</code>. Similar: is a member +of <code>\in</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="647" mergedindex="cp">\parallel</indexterm>\parallel</itemformat></item> +</tableterm><tableitem><para><U>2225</U> Parallel (relation). Synonym: <code>\|</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="648" mergedindex="cp">\partial</indexterm>\partial</itemformat></item> +</tableterm><tableitem><para><U>2202</U> Partial differential (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="649" mergedindex="cp">\perp</indexterm>\perp</itemformat></item> +</tableterm><tableitem><para><U>27C2</U> Perpendicular (relation). Similar: <code>\bot</code> uses the +same glyph but the spacing is different because it is in the class +ordinary. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="650" mergedindex="cp">\phi</indexterm>\phi</itemformat></item> +</tableterm><tableitem><para><U>03D5</U> Lowercase Greek letter (ordinary). The variant form is +<code>\varphi</code> <U>03C6</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="651" mergedindex="cp">\Pi</indexterm>\Pi</itemformat></item> +</tableterm><tableitem><para><U>03A0</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="652" mergedindex="cp">\pi</indexterm>\pi</itemformat></item> +</tableterm><tableitem><para><U>03C0</U> Lowercase Greek letter (ordinary). The variant form is +<code>\varpi</code> <U>03D6</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="653" mergedindex="cp">\pm</indexterm>\pm</itemformat></item> +</tableterm><tableitem><para><U>00B1</U> Plus or minus (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="654" mergedindex="cp">\prec</indexterm>\prec</itemformat></item> +</tableterm><tableitem><para><U>227A</U> Precedes (relation). Similar: less than <code><</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="655" mergedindex="cp">\preceq</indexterm>\preceq</itemformat></item> +</tableterm><tableitem><para><U>2AAF</U> Precedes or equals (relation). Similar: less than or +equals <code>\leq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="656" mergedindex="cp">\prime</indexterm>\prime</itemformat></item> +</tableterm><tableitem><para><U>2032</U> Prime, or minute in a time expression (ordinary). +Typically used as a superscript: <code>$f^\prime$</code>; <code>$f^\prime$</code> +and <code>$f'$</code> produce the same result. An advantage of the second +is that <code>$f'''$</code> produces the desired symbol, that is, the same +result as <code>$f^{\prime\prime\prime}$</code>, but uses rather less +typing. You can only use <code>\prime</code> in math mode. Using the right +single quote <code>'</code> in text mode produces a different character +(apostrophe). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="657" mergedindex="cp">\prod</indexterm>\prod</itemformat></item> +</tableterm><tableitem><para><U>220F</U> Product (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="658" mergedindex="cp">\propto</indexterm>\propto</itemformat></item> +</tableterm><tableitem><para><U>221D</U> Is proportional to (relation) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="659" mergedindex="cp">\Psi</indexterm>\Psi</itemformat></item> +</tableterm><tableitem><para><U>03A8</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="660" mergedindex="cp">\psi</indexterm>\psi</itemformat></item> +</tableterm><tableitem><para><U>03C8</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="661" mergedindex="cp">\rangle</indexterm>\rangle</itemformat></item> +</tableterm><tableitem><para><U>27E9</U> Right angle, or sequence, bracket (closing). +Similar: greater than <code>></code>. Matches:<code>\langle</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="662" mergedindex="cp">\rbrace</indexterm>\rbrace</itemformat></item> +</tableterm><tableitem><para><U>007D</U> Right curly brace +(closing). Synonym: <code>\}</code>. Matches <code>\lbrace</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="663" mergedindex="cp">\rbrack</indexterm>\rbrack</itemformat></item> +</tableterm><tableitem><para><U>005D</U> Right square bracket +(closing). Synonym: <code>]</code>. Matches <code>\lbrack</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="664" mergedindex="cp">\rceil</indexterm>\rceil</itemformat></item> +</tableterm><tableitem><para><U>2309</U> Right ceiling bracket (closing). Matches <code>\lceil</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="665" mergedindex="cp">\Re</indexterm>\Re</itemformat></item> +</tableterm><tableitem><para><U>211C</U> Real part, real numbers, cursive capital R (ordinary). Related: +double-line, or blackboard bold, R <code>\mathbb{R}</code>; to access +this, load the <file>amsfonts</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="666" mergedindex="cp">\restriction</indexterm>\restriction</itemformat></item> +</tableterm><tableitem><para><U>21BE</U> Restriction of a function (relation). Synonym: +<code>\upharpoonright</code>. Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="667" mergedindex="cp">\revemptyset</indexterm>\revemptyset</itemformat></item> +</tableterm><tableitem><para><U>29B0</U> Reversed empty set symbol (ordinary). Related: +<code>\varnothing</code>. Not available in plain &tex;. In &latex; you need to load the <file>stix</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="668" mergedindex="cp">\rfloor</indexterm>\rfloor</itemformat></item> +</tableterm><tableitem><para><U>230B</U> Right floor bracket, a right square bracket with the top cut +off (closing). Matches <code>\lfloor</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="669" mergedindex="cp">\rhd</indexterm>\rhd</itemformat></item> +</tableterm><tableitem><para><U>25C1</U> Arrowhead, that is, triangle, pointing right (binary). +Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. For the normal subgroup symbol you should instead +load <file>amssymb</file> and use <code>\vartriangleright</code> (which is a +relation and so gives better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="670" mergedindex="cp">\rho</indexterm>\rho</itemformat></item> +</tableterm><tableitem><para><U>03C1</U> Lowercase Greek letter (ordinary). The variant form is +<code>\varrho</code> <U>03F1</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="671" mergedindex="cp">\Rightarrow</indexterm>\Rightarrow</itemformat></item> +</tableterm><tableitem><para><U>21D2</U> Implies, right-pointing double line arrow +(relation). Similar: right single-line arrow <code>\rightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="672" mergedindex="cp">\rightarrow</indexterm>\rightarrow</itemformat></item> +</tableterm><tableitem><para><U>2192</U> Right-pointing single line arrow (relation). +Synonym: <code>\to</code>. Similar: right double line +arrow <code>\Rightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="673" mergedindex="cp">\rightharpoondown</indexterm>\rightharpoondown</itemformat></item> +</tableterm><tableitem><para><U>21C1</U> Right-pointing harpoon with barb below +the line (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="674" mergedindex="cp">\rightharpoonup</indexterm>\rightharpoonup</itemformat></item> +</tableterm><tableitem><para><U>21C0</U> Right-pointing harpoon with barb above the +line (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="675" mergedindex="cp">\rightleftharpoons</indexterm>\rightleftharpoons</itemformat></item> +</tableterm><tableitem><para><U>21CC</U> Right harpoon up above left harpoon down +(relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="676" mergedindex="cp">\searrow</indexterm>\searrow</itemformat></item> +</tableterm><tableitem><para><U>2198</U> Arrow pointing southeast (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="677" mergedindex="cp">\setminus</indexterm>\setminus</itemformat></item> +</tableterm><tableitem><para><U>29F5</U> Set difference, reverse solidus or reverse slash, +like \ (binary). Similar: backslash <code>\backslash</code> and also +<code>\textbackslash</code> outside of math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="678" mergedindex="cp">\sharp</indexterm>\sharp</itemformat></item> +</tableterm><tableitem><para><U>266F</U> Musical sharp (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="679" mergedindex="cp">\Sigma</indexterm>\Sigma</itemformat></item> +</tableterm><tableitem><para><U>03A3</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="680" mergedindex="cp">\sigma</indexterm>\sigma</itemformat></item> +</tableterm><tableitem><para><U>03C3</U> Lowercase Greek letter (ordinary). The variant form is +<code>\varsigma</code> <U>03C2</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="681" mergedindex="cp">\sim</indexterm>\sim</itemformat></item> +</tableterm><tableitem><para><U>223C</U> Similar, in a relation (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="682" mergedindex="cp">\simeq</indexterm>\simeq</itemformat></item> +</tableterm><tableitem><para><U>2243</U> Similar or equal to, in a relation (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="683" mergedindex="cp">\smallint</indexterm>\smallint</itemformat></item> +</tableterm><tableitem><para><U>222B</U> Integral sign that does not change to a larger size in a +display (operator). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="684" mergedindex="cp">\smile</indexterm>\smile</itemformat></item> +</tableterm><tableitem><para><U>2323</U> Upward curving arc, smile (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="685" mergedindex="cp">\spadesuit</indexterm>\spadesuit</itemformat></item> +</tableterm><tableitem><para><U>2660</U> Spade card suit (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="686" mergedindex="cp">\sqcap</indexterm>\sqcap</itemformat></item> +</tableterm><tableitem><para><U>2293</U> Square intersection symbol (binary). Similar: +intersection <code>cap</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="687" mergedindex="cp">\sqcup</indexterm>\sqcup</itemformat></item> +</tableterm><tableitem><para><U>2294</U> Square union symbol (binary). Similar: +union <code>cup</code>. Related: variable-sized +operator <code>\bigsqcup</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="688" mergedindex="cp">\sqsubset</indexterm>\sqsubset</itemformat></item> +</tableterm><tableitem><para><U>228F</U> Square subset symbol (relation). Similar: +subset <code>\subset</code>. Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="689" mergedindex="cp">\sqsubseteq</indexterm>\sqsubseteq</itemformat></item> +</tableterm><tableitem><para><U>2291</U> Square subset or equal symbol (binary). Similar: subset or +equal to <code>\subseteq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="690" mergedindex="cp">\sqsupset</indexterm>\sqsupset</itemformat></item> +</tableterm><tableitem><para><U>2290</U> Square superset symbol (relation). Similar: +superset <code>\supset</code>. Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="691" mergedindex="cp">\sqsupseteq</indexterm>\sqsupseteq</itemformat></item> +</tableterm><tableitem><para><U>2292</U> Square superset or equal symbol (binary). +Similar: superset or equal <code>\supseteq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="692" mergedindex="cp">\star</indexterm>\star</itemformat></item> +</tableterm><tableitem><para><U>22C6</U> Five-pointed star, sometimes used as a general binary +operation but sometimes reserved for cross-correlation (binary). +Similar: the synonyms asterisk <code>*</code> and <code>\ast</code>, which +are six-pointed, and more often appear as a superscript or subscript, +as with the Kleene star. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="693" mergedindex="cp">\subset</indexterm>\subset</itemformat></item> +</tableterm><tableitem><para><U>2282</U> Subset (occasionally, is implied by) (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="694" mergedindex="cp">\subseteq</indexterm>\subseteq</itemformat></item> +</tableterm><tableitem><para><U>2286</U> Subset or equal to (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="695" mergedindex="cp">\succ</indexterm>\succ</itemformat></item> +</tableterm><tableitem><para><U>227B</U> Comes after, succeeds (relation). Similar: is less +than <code>></code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="696" mergedindex="cp">\succeq</indexterm>\succeq</itemformat></item> +</tableterm><tableitem><para><U>2AB0</U> Succeeds or is equal to (relation). Similar: less +than or equal to <code>\leq</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="697" mergedindex="cp">\sum</indexterm>\sum</itemformat></item> +</tableterm><tableitem><para><U>2211</U> Summation (operator). Similar: Greek capital +sigma <code>\Sigma</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="698" mergedindex="cp">\supset</indexterm>\supset</itemformat></item> +</tableterm><tableitem><para><U>2283</U> Superset (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="699" mergedindex="cp">\supseteq</indexterm>\supseteq</itemformat></item> +</tableterm><tableitem><para><U>2287</U> Superset or equal to (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="700" mergedindex="cp">\surd</indexterm>\surd</itemformat></item> +</tableterm><tableitem><para><U>221A</U> Radical symbol (ordinary). The &latex; command +<code>\sqrt{...}</code> typesets the square root of the argument, with a bar +that extends to cover the argument. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="701" mergedindex="cp">\swarrow</indexterm>\swarrow</itemformat></item> +</tableterm><tableitem><para><U>2199</U> Southwest-pointing arrow (relation). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="702" mergedindex="cp">\tau</indexterm>\tau</itemformat></item> +</tableterm><tableitem><para><U>03C4</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="703" mergedindex="cp">\theta</indexterm>\theta</itemformat></item> +</tableterm><tableitem><para><U>03B8</U> Lowercase Greek letter (ordinary). The variant form is +<code>\vartheta</code> <U>03D1</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="704" mergedindex="cp">\times</indexterm>\times</itemformat></item> +</tableterm><tableitem><para><U>00D7</U> Primary school multiplication sign (binary). See +also <code>\cdot</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="705" mergedindex="cp">\to</indexterm>\to</itemformat></item> +</tableterm><tableitem><para><U>2192</U> Right-pointing single line arrow (relation). +Synonym: <code>\rightarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="706" mergedindex="cp">\top</indexterm>\top</itemformat></item> +</tableterm><tableitem><para><U>22A4</U> Top, greatest element of a partially ordered set +(ordinary). See also <code>\bot</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="707" mergedindex="cp">\triangle</indexterm>\triangle</itemformat></item> +</tableterm><tableitem><para><U>25B3</U> Triangle (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="708" mergedindex="cp">\triangleleft</indexterm>\triangleleft</itemformat></item> +</tableterm><tableitem><para><U>25C1</U> Not-filled triangle pointing left +(binary). Similar: <code>\lhd</code>. For the normal subgroup symbol you +should load <file>amssymb</file> and use <code>\vartriangleleft</code> (which +is a relation and so gives better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="709" mergedindex="cp">\triangleright</indexterm>\triangleright</itemformat></item> +</tableterm><tableitem><para><U>25B7</U> Not-filled triangle pointing right +(binary). For the normal subgroup symbol you should instead load +<file>amssymb</file> and use <code>\vartriangleright</code> (which is a +relation and so gives better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="710" mergedindex="cp">\unlhd</indexterm>\unlhd</itemformat></item> +</tableterm><tableitem><para><U>22B4</U> 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 <file>amssymb</file> package. For the +normal subgroup symbol load <file>amssymb</file> and +use <code>\vartrianglelefteq</code> (which is a relation and so gives +better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="711" mergedindex="cp">\unrhd</indexterm>\unrhd</itemformat></item> +</tableterm><tableitem><para><U>22B5</U> 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 <file>amssymb</file> package. For the +normal subgroup symbol load <file>amssymb</file> and +use <code>\vartrianglerighteq</code> (which is a relation and so gives +better spacing). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="712" mergedindex="cp">\Uparrow</indexterm>\Uparrow</itemformat></item> +</tableterm><tableitem><para><U>21D1</U> Double-line upward-pointing arrow +(relation). Similar: single-line up-pointing +arrow <code>\uparrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="713" mergedindex="cp">\uparrow</indexterm>\uparrow</itemformat></item> +</tableterm><tableitem><para><U>2191</U> Single-line upward-pointing arrow, diverges +(relation). Similar: double-line up-pointing +arrow <code>\Uparrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="714" mergedindex="cp">\Updownarrow</indexterm>\Updownarrow</itemformat></item> +</tableterm><tableitem><para><U>21D5</U> Double-line upward-and-downward-pointing arrow +(relation). Similar: single-line upward-and-downward-pointing +arrow <code>\updownarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="715" mergedindex="cp">\updownarrow</indexterm>\updownarrow</itemformat></item> +</tableterm><tableitem><para><U>2195</U> Single-line upward-and-downward-pointing arrow +(relation). Similar: double-line upward-and-downward-pointing +arrow <code>\Updownarrow</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="716" mergedindex="cp">\upharpoonright</indexterm>\upharpoonright</itemformat></item> +</tableterm><tableitem><para><U>21BE</U> Up harpoon, with barb on right side +(relation). Synonym: <code>&backslashchar;restriction</code>. +Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="717" mergedindex="cp">\uplus</indexterm>\uplus</itemformat></item> +</tableterm><tableitem><para><U>228E</U> Multiset union, a union symbol with a plus symbol in +the middle (binary). Similar: union <code>\cup</code>. Related: +variable-sized operator <code>\biguplus</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="718" mergedindex="cp">\Upsilon</indexterm>\Upsilon</itemformat></item> +</tableterm><tableitem><para><U>03A5</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="719" mergedindex="cp">\upsilon</indexterm>\upsilon</itemformat></item> +</tableterm><tableitem><para><U>03C5</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="720" mergedindex="cp">\varepsilon</indexterm>\varepsilon</itemformat></item> +</tableterm><tableitem><para><U>03B5</U> Small letter script epsilon (ordinary). This is +more widely used in mathematics than the non-variant lunate epsilon form +<code>\epsilon</code> <U>03F5</U>. Related: set +membership <code>\in</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="721" mergedindex="cp">\vanothing</indexterm>\vanothing</itemformat></item> +</tableterm><tableitem><para><U>2205</U> Empty set symbol. Similar: <code>\emptyset</code>. Related: +<code>\revemptyset</code>. Not available in plain &tex;. In &latex; you need to load the <file>amssymb</file> package. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="722" mergedindex="cp">\varphi</indexterm>\varphi</itemformat></item> +</tableterm><tableitem><para><U>03C6</U> Variant on the lowercase Greek letter (ordinary). +The non-variant form is <code>\phi</code> <U>03D5</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="723" mergedindex="cp">\varpi</indexterm>\varpi</itemformat></item> +</tableterm><tableitem><para><U>03D6</U> Variant on the lowercase Greek letter (ordinary). +The non-variant form is <code>\pi</code> <U>03C0</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="724" mergedindex="cp">\varrho</indexterm>\varrho</itemformat></item> +</tableterm><tableitem><para><U>03F1</U> Variant on the lowercase Greek letter (ordinary). +The non-variant form is <code>\rho</code> <U>03C1</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="725" mergedindex="cp">\varsigma</indexterm>\varsigma</itemformat></item> +</tableterm><tableitem><para><U>03C2</U> Variant on the lowercase Greek letter +(ordinary). The non-variant form is +<code>\sigma</code> <U>03C3</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="726" mergedindex="cp">\vartheta</indexterm>\vartheta</itemformat></item> +</tableterm><tableitem><para><U>03D1</U> Variant on the lowercase Greek letter +(ordinary). The non-variant form is +<code>\theta</code> <U>03B8</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="727" mergedindex="cp">\vdash</indexterm>\vdash</itemformat></item> +</tableterm><tableitem><para><U>22A2</U> Provable; turnstile, vertical and a dash +(relation). Similar: turnstile rotated a +half-circle <code>\dashv</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="728" mergedindex="cp">\vee</indexterm>\vee</itemformat></item> +</tableterm><tableitem><para><U>2228</U> Logical or; a downwards v shape (binary). Related: +logical and <code>\wedge</code>. Similar: variable-sized +operator <code>\bigvee</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="729" mergedindex="cp">\Vert</indexterm>\Vert</itemformat></item> +</tableterm><tableitem><para><U>2016</U> Vertical double bar (ordinary). Similar: vertical single +bar <code>\vert</code>. +</para> +<para>For a norm symbol, you can use the <file>mathtools</file> package and put in +your preamble +<code>\DeclarePairedDelimiter\norm{\lVert}{\rVert}</code>. This gives you +three command variants for double-line vertical bars that are correctly +horizontally spaced: if in the document body you write the starred +version <code>$\norm*{M^\perp}$</code> then the height of the vertical bars +will match the height of the argument, whereas with +<code>\norm{M^\perp}</code> the bars do not grow with the height of the +argument but instead are the default height, and <code>\norm[<var>size +command</var>]{M^\perp}</code> also gives bars that do not grow but are set to +the size given in the <var>size command</var>, e.g., <code>\Bigg</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="730" mergedindex="cp">\vert</indexterm>\vert</itemformat></item> +</tableterm><tableitem><para><U>007C</U> Single line vertical bar (ordinary). Similar: double-line +vertical bar <code>\Vert</code>. For such that, as in the definition of a +set, use <code>\mid</code> because it is a relation. +</para> +<para>For absolute value you can use the <file>mathtools</file> package and in your +preamble put +<code>\DeclarePairedDelimiter\abs{\lvert}{\rvert}</code>. This gives you +three command variants for single-line vertical bars that are correctly +horizontally spaced: if in the document body you write the starred +version <code>$\abs*{\frac{22}{7}}$</code> then the height of the +vertical bars will match the height of the argument, whereas with +<code>\abs{\frac{22}{7}}</code> the bars do not grow with the height of +the argument but instead are the default height, and +<code>\abs[<var>size command</var>]{\frac{22}{7}}</code> also gives bars that +do not grow but are set to the size given in the <var>size command</var>, +e.g., <code>\Bigg</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="731" mergedindex="cp">\wedge</indexterm>\wedge</itemformat></item> +</tableterm><tableitem><para><U>2227</U> Logical and (binary). Synonym: <code>\land</code>. See also +logical or <code>\vee</code>. Similar: variable-sized +operator <code>\bigwedge</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="732" mergedindex="cp">\wp</indexterm>\wp</itemformat></item> +</tableterm><tableitem><para><U>2118</U> Weierstrass p (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="733" mergedindex="cp">\wr</indexterm>\wr</itemformat></item> +</tableterm><tableitem><para><U>2240</U> Wreath product (binary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="734" mergedindex="cp">\Xi</indexterm>\Xi</itemformat></item> +</tableterm><tableitem><para><U>039E</U> uppercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="735" mergedindex="cp">\xi</indexterm>\xi</itemformat></item> +</tableterm><tableitem><para><U>03BE</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="736" mergedindex="cp">\zeta</indexterm>\zeta</itemformat></item> +</tableterm><tableitem><para><U>03B6</U> Lowercase Greek letter (ordinary). +</para> +</tableitem></tableentry></ftable> + +<para>The following symbols are most often used in plain text but &latex; +provides versions to use in mathematical text. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="737" mergedindex="cp">\mathdollar</indexterm>\mathdollar</itemformat></item> +</tableterm><tableitem><para>Dollar sign in math mode: $. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="738" mergedindex="cp">\mathparagraph</indexterm>\mathparagraph</itemformat></item> +</tableterm><tableitem><para>Paragraph sign (pilcrow) in math mode, <U>00B6</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="739" mergedindex="cp">\mathsection</indexterm>\mathsection</itemformat></item> +</tableterm><tableitem><para>Section sign in math mode <U>00A7</U>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="740" mergedindex="cp">\mathsterling</indexterm>\mathsterling</itemformat></item> +</tableterm><tableitem><para>Sterling sign in math mode: £. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="741" mergedindex="cp">\mathunderscore</indexterm>\mathunderscore</itemformat></item> +</tableterm><tableitem><para>Underscore in math mode: _. +</para> +</tableitem></tableentry></ftable> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Blackboard bold</menunode><menudescription><pre xml:space="preserve">Doublestruck characters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Calligraphic</menunode><menudescription><pre xml:space="preserve">Cursive characters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\boldmath & \unboldmath</menunode><menudescription><pre xml:space="preserve">Symbols in boldface. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Dots</menunode><menudescription><pre xml:space="preserve">Ellipses, etc. +</pre></menudescription></menuentry></menu> + + +<node name="Blackboard-bold" spaces=" "><nodename>Blackboard bold</nodename><nodenext automatic="on">Calligraphic</nodenext><nodeup automatic="on">Math symbols</nodeup></node> +<subsection spaces=" "><sectiontitle>Blackboard bold</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="497">blackboard bold</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="498">doublestruck</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{amssymb} % in preamble + ... +\mathbb{<var>uppercase-letter</var>} +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\( \forall n \in \mathbb{N}, n^2 \geq 0 \) +</pre></example> + +<noindent></noindent> +<para>the <code>\mathbb{N}</code> gives blackboard bold symbol <U>2115</U> +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> + +</subsection> +<node name="Calligraphic" spaces=" "><nodename>Calligraphic</nodename><nodenext automatic="on">\boldmath & \unboldmath</nodenext><nodeprev automatic="on">Blackboard bold</nodeprev><nodeup automatic="on">Math symbols</nodeup></node> +<subsection spaces=" "><sectiontitle>Calligraphic</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="499">calligraphic fonts</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="500">script fonts</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="501">fonts, script</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\mathcal{<var>uppercase-letters</var>} +</pre></example> + +<para>Use a script-like font. +</para> +<para>In this example the graph identifier is output in a cursive font. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Let the graph be \( \mathcal{G} \). +</pre></example> + +<para>If you use something other than an uppercase letter then you do not get +an error. Instead you get unexpected output. For instance, +<code>\mathcal{g}</code> outputs a close curly brace symbol, while +<code>\mathcal{+}</code> outputs a plus sign. +</para> + +</subsection> +<node name="_005cboldmath-_0026-_005cunboldmath" spaces=" "><nodename>\boldmath & \unboldmath</nodename><nodenext automatic="on">Dots</nodenext><nodeprev automatic="on">Calligraphic</nodeprev><nodeup automatic="on">Math symbols</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\boldmath</code> & <code>\unboldmath</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="502">boldface mathematics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="503">symbols, boldface</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="742" mergedindex="cp">\boldmath</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="743" mergedindex="cp">\unboldmath</indexterm></findex> + +<para>Synopsis (used in paragraph mode or LR mode): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\boldmath \( <var>math</var> \) +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\unboldmath \( <var>math</var> \) +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="744" mergedindex="cp">\boldmath</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="745" mergedindex="cp">\unboldmath</indexterm></findex> +<para>Declarations to change the letters and symbols in <var>math</var> to be in +a bold font, or to countermand that and bring back the regular +(non-bold) default. They must be used when not in math mode or display +math mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). Both commands are fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>In this example each <code>\boldmath</code> command takes place inside an +<code>\mbox</code>, +</para> +<example endspaces=" "> +<pre xml:space="preserve">we have $\mbox{\boldmath \( v \)} = 5\cdot\mbox{\boldmath \( u \)$}$ +</pre></example> + +<noindent></noindent> +<para>which means <code>\boldmath</code> is only called in a text mode, here LR +mode, and explains why &latex; must switch to math mode to set <code>v</code> +and <code>u</code>. +</para> +<para>If you use either command inside math mode, as with <code>Trouble: \( +\boldmath x \)</code>, then you get something like <samp>LaTeX Font Warning: +Command \boldmath invalid in math mode on input line 11</samp> and <samp>LaTeX +Font Warning: Command \mathversion invalid in math mode on input line +11</samp>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="504"><r>package</r>, <code>bm</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="505"><code>bm</code> <r>package</r></indexterm></cindex> + +<para>There are many issues with <code>\boldmath</code>. New documents should use +the <file>bm</file> 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> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{bm} % in preamble +... +we have $\bm{v} = 5\cdot\bm{u}$ +</pre></example> + +<noindent></noindent> +<para>shows that it is an improvement over <code>\boldmath</code>. +</para> + +</subsection> +<node name="Dots" spaces=" "><nodename>Dots</nodename><nodeprev automatic="on">\boldmath & \unboldmath</nodeprev><nodeup automatic="on">Math symbols</nodeup></node> +<subsection spaces=" "><sectiontitle>Dots, horizontal or vertical</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="506">ellipses</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="507">dots</indexterm></cindex> + +<para>Ellipses are the three dots (usually three) indicating that a pattern +continues. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{array}{cccc} + a_{0,0} &a_{0,1} &a_{0,2} &\ldots \\ + a_{1,0} &\ddots \\ + \vdots +\end{array} +</pre></example> + +<para>&latex; provides these. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="ellipses-cdots">ellipses cdots</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="746" mergedindex="cp">\cdots</indexterm>\cdots</itemformat></item> +</tableterm><tableitem><para>Horizontal ellipsis with the dots raised to the center of the line, as +in <U>22EF</U>. Used as: <code>\( a_0\cdot a_1\cdots a_{n-1} +\)</code>. +</para> +<anchor name="ellipses-ddots">ellipses ddots</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="747" mergedindex="cp">\ddots</indexterm>\ddots</itemformat></item> +</tableterm><tableitem><para>Diagonal ellipsis, <U>22F1</U>. See the above array example for a +usage. +</para> +<anchor name="ellipses-ldots">ellipses ldots</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="748" mergedindex="cp">\ldots</indexterm>\ldots</itemformat></item> +</tableterm><tableitem><para>Ellipsis on the baseline, <U>2026</U>. Used as: <code>\( +x_0,\ldots x_{n-1} \)</code>. Another example is the above array example. A +synonym is <code>\mathellipsis</code>. A synonym from the <file>amsmath</file> +package is <code>\hdots</code>. +</para> +<para>You can also use this command outside of mathematical text, as in +<code>The gears, brakes, \ldots{} are all broken</code>. (In a paragraph +mode or LR mode a synonym for <code>\ldots</code> is <code>\dots</code>.) +</para> +<anchor name="ellipses-vdots">ellipses vdots</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="749" mergedindex="cp">\vdots</indexterm>\vdots</itemformat></item> +</tableterm><tableitem><para>Vertical ellipsis, <U>22EE</U>. See the above array example for a +usage. +</para> +</tableitem></tableentry></ftable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="508"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="509"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>The <file>amsmath</file> package has the command <code>\dots</code> to semantically +mark up ellipses. This example produces two different-looking outputs +for the first two uses of the <code>\dots</code> command. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 \). +</pre></example> + +<noindent></noindent> +<para>In the first line &latex; looks to the comma following <code>\dots</code> to +determine that it should output an ellipsis on the baseline. The second +line has a <code>\cdot</code> following <code>\dots</code> 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: <code>\dotsc</code> if you need the +ellipsis appropriate for a comma following, <code>\dotsb</code> if you need +the ellipses that fits when the dots are followed by a binary operator +or relation symbol, <code>\dotsi</code> for dots with integrals, or +<code>\dotso</code> for others. +</para> + +</subsection> +</section> +<node name="Math-functions" spaces=" "><nodename>Math functions</nodename><nodenext automatic="on">Math accents</nodenext><nodeprev automatic="on">Math symbols</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Math functions</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="510">math functions</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="511">functions, math</indexterm></cindex> + +<para>These commands produce roman function names in math mode with proper +spacing. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="750" mergedindex="cp">\arccos</indexterm>\arccos</itemformat></item> +</tableterm><tableitem><para>Inverse cosine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="751" mergedindex="cp">\arcsin</indexterm>\arcsin</itemformat></item> +</tableterm><tableitem><para>Inverse sine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="752" mergedindex="cp">\arctan</indexterm>\arctan</itemformat></item> +</tableterm><tableitem><para>Inverse tangent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="753" mergedindex="cp">\arg</indexterm>\arg</itemformat></item> +</tableterm><tableitem><para>Angle between the real axis and a point in the complex plane +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="754" mergedindex="cp">\bmod</indexterm>\bmod</itemformat></item> +</tableterm><tableitem><para>Binary modulo operator, used as in <code>\( 5\bmod 3=2 \)</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="755" mergedindex="cp">\cos</indexterm>\cos</itemformat></item> +</tableterm><tableitem><para>Cosine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="756" mergedindex="cp">\cosh</indexterm>\cosh</itemformat></item> +</tableterm><tableitem><para>Hyperbolic cosine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="757" mergedindex="cp">\cot</indexterm>\cot</itemformat></item> +</tableterm><tableitem><para>Cotangent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="758" mergedindex="cp">\coth</indexterm>\coth</itemformat></item> +</tableterm><tableitem><para>Hyperbolic cotangent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="759" mergedindex="cp">\csc</indexterm>\csc</itemformat></item> +</tableterm><tableitem><para>Cosecant +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="760" mergedindex="cp">\deg</indexterm>\deg</itemformat></item> +</tableterm><tableitem><para>Degrees +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="761" mergedindex="cp">\det</indexterm>\det</itemformat></item> +</tableterm><tableitem><para>Determinant +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="762" mergedindex="cp">\dim</indexterm>\dim</itemformat></item> +</tableterm><tableitem><para>Dimension +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="763" mergedindex="cp">\exp</indexterm>\exp</itemformat></item> +</tableterm><tableitem><para>Exponential +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="764" mergedindex="cp">\gcd</indexterm>\gcd</itemformat></item> +</tableterm><tableitem><para>Greatest common divisor +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="765" mergedindex="cp">\hom</indexterm>\hom</itemformat></item> +</tableterm><tableitem><para>Homomorphism +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="766" mergedindex="cp">\inf</indexterm>\inf</itemformat></item> +</tableterm><tableitem><para>Infinum +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="767" mergedindex="cp">\ker</indexterm>\ker</itemformat></item> +</tableterm><tableitem><para>Kernel +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="768" mergedindex="cp">\lg</indexterm>\lg</itemformat></item> +</tableterm><tableitem><para>Base 2 logarithm +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="769" mergedindex="cp">\lim</indexterm>\lim</itemformat></item> +</tableterm><tableitem><para>Limit +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="770" mergedindex="cp">\liminf</indexterm>\liminf</itemformat></item> +</tableterm><tableitem><para>Limit inferior +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="771" mergedindex="cp">\limsup</indexterm>\limsup</itemformat></item> +</tableterm><tableitem><para>Limit superior +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="772" mergedindex="cp">\ln</indexterm>\ln</itemformat></item> +</tableterm><tableitem><para>Natural logarithm +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="773" mergedindex="cp">\log</indexterm>\log</itemformat></item> +</tableterm><tableitem><para>Logarithm +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="774" mergedindex="cp">\max</indexterm>\max</itemformat></item> +</tableterm><tableitem><para>Maximum +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="775" mergedindex="cp">\min</indexterm>\min</itemformat></item> +</tableterm><tableitem><para>Minimum +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="776" mergedindex="cp">\pmod</indexterm>\pmod</itemformat></item> +</tableterm><tableitem><para>Parenthesized modulus, as used in <code>\( 5\equiv 2\pmod 3 \)</code> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="777" mergedindex="cp">\Pr</indexterm>\Pr</itemformat></item> +</tableterm><tableitem><para>Probability +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="778" mergedindex="cp">\sec</indexterm>\sec</itemformat></item> +</tableterm><tableitem><para>Secant +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="779" mergedindex="cp">\sin</indexterm>\sin</itemformat></item> +</tableterm><tableitem><para>Sine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="780" mergedindex="cp">\sinh</indexterm>\sinh</itemformat></item> +</tableterm><tableitem><para>Hyperbolic sine +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="781" mergedindex="cp">\sup</indexterm>\sup</itemformat></item> +</tableterm><tableitem><para>sup +<!-- c don't try to use \sup with dvi/pdf output since that turned into a --> +<!-- c Texinfo command and it's not worth hassling with different versions --> +<!-- c when it's just three roman letters anyway. --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="782" mergedindex="cp">\tan</indexterm>\tan</itemformat></item> +</tableterm><tableitem><para>Tangent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="783" mergedindex="cp">\tanh</indexterm>\tanh</itemformat></item> +</tableterm><tableitem><para>Hyperbolic tangent +</para> +</tableitem></tableentry></ftable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="512"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="513"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>The <file>amsmath</file> 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 +<code>\DeclareMathOperator{\identity}{id}</code> that is like the ones +above but prints as <samp>id</samp>. The starred form +<code>\DeclareMathOperator*{\op}{op}</code> sets any limits above and +below, as is traditional with <code>\lim</code>, <code>\sup</code>, or <code>\max</code>. +</para> + +</section> +<node name="Math-accents" spaces=" "><nodename>Math accents</nodename><nodenext automatic="on">Over- and Underlining</nodenext><nodeprev automatic="on">Math functions</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Math accents</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="514">math accents</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="515">accents, mathematical</indexterm></cindex> + +<para>&latex; provides a variety of commands for producing accented letters +in math. These are different from accents in normal text +(<pxref label="Accents"><xrefnodename>Accents</xrefnodename></pxref>). +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="784" mergedindex="cp">\acute</indexterm>\acute</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="516">acute accent, math</indexterm></cindex> +<para>Math acute accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="785" mergedindex="cp">\bar</indexterm>\bar</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="517">bar-over accent, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="518">macron accent, math</indexterm></cindex> +<para>Math bar-over accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="786" mergedindex="cp">\breve</indexterm>\breve</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="519">breve accent, math</indexterm></cindex> +<para>Math breve accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="787" mergedindex="cp">\check</indexterm>\check</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="520">check accent, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="521">h<accent type="acute" bracketed="off">a</accent><accent type="caron">c</accent>ek accent, math</indexterm></cindex> +<para>Math h<accent type="acute" bracketed="off">a</accent><accent type="caron">c</accent>ek (check) accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="788" mergedindex="cp">\ddot</indexterm>\ddot</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="522">double dot accent, math</indexterm></cindex> +<para>Math dieresis accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="789" mergedindex="cp">\dot</indexterm>\dot</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="523">overdot accent, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="524">dot over accent, math</indexterm></cindex> +<para>Math dot accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="790" mergedindex="cp">\grave</indexterm>\grave</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="525">grave accent, math</indexterm></cindex> +<para>Math grave accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="791" mergedindex="cp">\hat</indexterm>\hat</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="526">hat accent, math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="527">circumflex accent, math</indexterm></cindex> +<para>Math hat (circumflex) accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="792" mergedindex="cp">\mathring</indexterm>\mathring</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="528">ring accent, math</indexterm></cindex> +<para>Math ring accent <!-- c don't bother implementing in texinfo --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="793" mergedindex="cp">\tilde</indexterm>\tilde</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="529">tilde accent, math</indexterm></cindex> +<para>Math tilde accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="794" mergedindex="cp">\vec</indexterm>\vec</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="530">vector symbol, math</indexterm></cindex> +<para>Math vector symbol +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="795" mergedindex="cp">\widehat</indexterm>\widehat</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="531">wide hat accent, math</indexterm></cindex> +<para>Math wide hat accent +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="796" mergedindex="cp">\widetilde</indexterm>\widetilde</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="532">wide tilde accent, math</indexterm></cindex> +<para>Math wide tilde accent +</para> +</tableitem></tableentry></ftable> + +<para>When you are putting an accent on an i or a j, the tradition is to use +one without a dot, <code>\imath</code> or <code>jmath</code> (<pxref label="Math-symbols"><xrefnodename>Math symbols</xrefnodename></pxref>). +</para> + +</section> +<node name="Over_002d-and-Underlining" spaces=" "><nodename>Over- and Underlining</nodename><nodenext automatic="on">Spacing in math mode</nodenext><nodeprev automatic="on">Math accents</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Over- and Underlining</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="533">overlining</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="534">underlining</indexterm></cindex> + +<para>&latex; provides commands for making overlines or underlines, or +putting braces over or under some material. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="797" mergedindex="cp">\underline{<var>text</var>}</indexterm>\underline{<var>text</var>}</itemformat></item> +</tableterm><tableitem><para>Underline <var>text</var>. Works inside math mode, and outside. +The line is always completely below the text, taking account of +descenders, so in <code>\(\underline{y}\)</code> the line is lower than in +<code>\(\underline{x}\)</code>. This command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="535"><r>package</r>, <code>ulem</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="536"><code>ulem</code> <r>package</r></indexterm></cindex> + +<para>Note that the package <file>ulem</file> does text mode underlining and allows +line breaking as well as a number of other features. See the +documentation on CTAN. See also <ref label="_005chrulefill-_0026-_005cdotfill"><xrefnodename>\hrulefill & \dotfill</xrefnodename></ref> for +producing a line, for such things as a signature. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="798" mergedindex="cp">\overline{<var>text</var>}</indexterm>\overline{<var>text</var>}</itemformat></item> +</tableterm><tableitem><para>Put a horizontal line over <var>text</var>. Works inside math mode, and +outside. For example, <code>\overline{x+y}</code>. +Note that this differs from the command <code>\bar</code> (<pxref label="Math-accents"><xrefnodename>Math +accents</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="799" mergedindex="cp">\underbrace{<var>math</var>}</indexterm>\underbrace{<var>math</var>}</itemformat></item> +</tableterm><tableitem><para>Put a brace under <var>math</var>. For example, this +<code>(1-\underbrace{1/2)+(1/2}-1/3)</code> emphasizes the telescoping part. +Attach text to the brace by using subscript, <code>_</code>, or superscript, +<code>^</code>, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>The superscript appears on top of the expression, and so can look +unconnected to the underbrace. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="800" mergedindex="cp">\overbrace{<var>math</var>}</indexterm>\overbrace{<var>math</var>}</itemformat></item> +</tableterm><tableitem><para>Put a brace over <var>math</var>, as with +<code>\overbrace{x+x+\cdots+x}^{\mbox{\(k\) times}}</code>. See also +<code>\underbrace</code>. +</para> +</tableitem></tableentry></ftable> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="537"><r>package</r>, <code>mathtools</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="538"><code>mathtools</code> <r>package</r></indexterm></cindex> + +<para>The package <file>mathtools</file> adds an over- and underbrace, as well as +some improvements on the braces. See the documentation on CTAN. +</para> + +</section> +<node name="Spacing-in-math-mode" spaces=" "><nodename>Spacing in math mode</nodename><nodenext automatic="on">Math miscellany</nodenext><nodeprev automatic="on">Over- and Underlining</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Spacing in math mode</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="539">spacing within math mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="540">math mode, spacing</indexterm></cindex> + +<para>When typesetting mathematics, &latex; puts in spacing according to the +normal rules for mathematics texts. If you enter <code>y=m x</code> then +&latex; ignores the space and in the output the m is next to the x, +as <math>y=mx</math>. +</para> +<para>But &latex;&textrsquo;s rules sometimes need tweaking. For example, in an +integral the tradition is to put a small extra space between the +<code>f(x)</code> and the <code>dx</code>, here done with the <code>\,</code> command. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\int_0^1 f(x)\,dx +</pre></example> + +<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 +<dfn>mu</dfn>. It is defined as 1/18<dmn>em</dmn>, where the em is taken from the +current math symbols family (<pxref label="Units-of-length"><xrefnodename>Units of length</xrefnodename></pxref>). Thus, a +<code>\thickspace</code> is something like 5/18 times the width of +a <samp>M</samp>. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\;</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="801" mergedindex="cp">\;</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="802" mergedindex="cp">\thickspace</indexterm></findex> +<anchor name="spacing-in-math-mode-thickspace">spacing in math mode thickspace</anchor> +<para>Synonym: <code>\thickspace</code>. Normally <code>5.0mu plus 5.0mu</code>. Math +mode only. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\:</itemformat></item> +<itemx spaces=" "><itemformat command="code">\></itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="803" mergedindex="cp">\:</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="804" mergedindex="cp">\></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="805" mergedindex="cp">\medspace</indexterm></findex> +<anchor name="spacing-in-math-mode-medspace">spacing in math mode medspace</anchor> +<para>Synonym: <code>\medspace</code>. Normally <code>4.0mu plus 2.0mu minus 4.0mu</code>. +Math mode only. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\,</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="806" mergedindex="cp">\,</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="807" mergedindex="cp">\thinspace</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="541">thin space</indexterm></cindex> +<anchor name="Spacing-in-math-mode_002f_005cthinspace">Spacing in math mode/\thinspace</anchor> +<anchor name="spacing-in-math-mode-thinspace">spacing in math mode thinspace</anchor> +<para>Synonym: <code>\thinspace</code>. Normally <code>3mu</code>, which is 1/6<dmn>em</dmn>. +Can be used in both math mode and text mode (<pxref label="_005cthinspace-_0026-_005cnegthinspace"><xrefnodename>\thinspace & +\negthinspace</xrefnodename></pxref>). +</para> +<para>This space is widely used, for instance between the function and the +infinitesimal in an integral <code>\int f(x)\,dx</code> and, if an author does +this, before punctuation in a displayed equation. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The antiderivative is +\begin{equation} + 3x^{-1/2}+3^{1/2}\,. +\end{equation} +</pre></example> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\!</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="808" mergedindex="cp">\!</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="809" mergedindex="cp">\negthinspace</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="542">thin space, negative</indexterm></cindex> +<anchor name="spacing-in-math-mode-negthinspace">spacing in math mode negthinspace</anchor> +<para>A negative thin space. Normally <code>-3mu</code>. The <code>\!</code> command is +math mode only but the <code>\negthinspace</code> command is available for +text mode (<pxref label="_005cthinspace-_0026-_005cnegthinspace"><xrefnodename>\thinspace & \negthinspace</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\quad</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="543">quad</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="810" mergedindex="cp">\quad</indexterm></findex> +<anchor name="spacing-in-math-mode-quad">spacing in math mode quad</anchor> +<para>This is 18<dmn>mu</dmn>, that is, 1<dmn>em</dmn>. This is often used for space +surrounding equations or expressions, for instance for the space between +two equations inside a <code>displaymath</code> environment. It is available +in both text and math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\qquad</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="811" mergedindex="cp">\qquad</indexterm></findex> +<anchor name="spacing-in-math-mode-qquad">spacing in math mode qquad</anchor> +<para>A length of 2 quads, that is, 36<dmn>mu</dmn> = 2<dmn>em</dmn>. It is available in +both text and math mode. +</para></tableitem></tableentry></table> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\smash</menunode><menudescription><pre xml:space="preserve">Eliminate height or depth of a subformula. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\phantom & \vphantom & \hphantom</menunode><menudescription><pre xml:space="preserve">Make empty box with the same size as the argument. +</pre></menudescription></menuentry></menu> + + +<node name="_005csmash" spaces=" "><nodename>\smash</nodename><nodenext automatic="on">\phantom & \vphantom & \hphantom</nodenext><nodeup automatic="on">Spacing in math mode</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\smash</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="544">vertical spacing, math mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="545">math mode, vertical space</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\smash{<var>subformula</var>} +</pre></example> + +<para>Typeset <var>subformula</var> as if its height and depth were zero. +</para> +<para>In this example the exponential is so tall that without the +<code>\smash</code> command &latex; would separate its line from the line +above it, and the uneven line spacing might be unsightly. +</para> +<example endspaces=" "> +<pre xml:space="preserve">To compute the tetration $\smash{2^{2^{2^2}}}$, +evaluate from the top down, as $2^{2^4}=2^{16}=65536$. +</pre></example> + +<para>(Because of the <code>\smash</code> 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 <code>\smash</code> by using <code>\fbox</code> to +surround the box that &latex; will put on the line. The +<code>\blackbar</code> command makes a bar extending from 10 points below +the baseline to 20 points above. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\blackbar}{\rule[-10pt]{5pt}{30pt}} +\fbox{\blackbar} +\fbox{\smash{\blackbar}} +</pre></example> + +<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 <code>\smash</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} +\sqrt{\sum_{0\leq k< n} f(k)} +\sqrt{\vphantom{\sum}\smash{\sum_{0\leq k< n}} f(k)} +\end{equation} +</pre></example> + +<para>Note the use of <code>\vphantom</code> to give the <code>\sqrt</code> command an +argument with the height of the <code>\sum</code> (<pxref label="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom"><xrefnodename>\phantom & \vphantom +& \hphantom</xrefnodename></pxref>). +</para> +<para>While most often used in mathematics, the <code>\smash</code> command can +appear in other contexts. However, it doesn&textrsquo;t change into horizontal +mode. So if it starts a paragraph then you should first put a +<code>\leavevmode</code>, as in the bottom line below. +</para> +<example endspaces=" "> +<pre xml:space="preserve">xxx xxx xxx + +\smash{yyy} % no paragraph indent + +\leavevmode\smash{zzz} % usual paragraph indent +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="546"><r>package</r>, <code>mathtools</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="547"><code>mathtools</code> <r>package</r></indexterm></cindex> + +<para>The package <code>mathtools</code> has operators that provide even finer +control over smashing a subformula box. +</para> + +</subsection> +<node name="_005cphantom-_0026-_005cvphantom-_0026-_005chphantom" spaces=" "><nodename>\phantom & \vphantom & \hphantom</nodename><nodeprev automatic="on">\smash</nodeprev><nodeup automatic="on">Spacing in math mode</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\phantom</code> & <code>\vphantom</code> & <code>\hphantom</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="548">spacing, math mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="549">horizontal spacing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="550">vertical spacing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="551">math mode, spacing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="552">invisible character</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="553">character, invisible</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\phantom{<var>subformula</var>} +</pre></example> + +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\vphantom{<var>subformula</var>} +</pre></example> + +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hphantom{<var>subformula</var>} +</pre></example> + +<para>The <code>\phantom</code> command creates a box with the same height, depth, +and width as <var>subformula</var>, but empty. That is, this command causes +&latex; to typeset the box but not its ink. The <code>\vphantom</code> +variant also produces an invisible box with the same height and depth as +<var>subformula</var>, but it has width zero. And <code>\hphantom</code> makes a +box with the same width as <var>subformula</var> but with height and depth +zero. +</para> +<para>Without the <code>\vphantom</code> in this example, the top bars of the two +square roots would be at different heights. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\( \sqrt{\vphantom{a^3}a}\cdot\sqrt{a^3} \) +</pre></example> + +<para>The <code>\vphantom{a^3}</code> causes the first <code>\sqrt</code> to have inside +it a box of the same height as the second <code>\sqrt</code>, so &latex; +makes the bars align. +</para> +<para>These commands often are combined with <code>\smash</code>. <xref label="_005csmash"><xrefnodename>\smash</xrefnodename></xref> +for another example of the use of <code>\vphantom</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="554"><r>package</r>, <code>mathtools</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="555"><code>mathtools</code> <r>package</r></indexterm></cindex> + +<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 <code>\makebox</code> (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></pxref>) as well +as <code>\settodepth</code> (<pxref label="_005csettodepth"><xrefnodename>\settodepth</xrefnodename></pxref>), <code>\settoheight</code> +(<pxref label="_005csettoheight"><xrefnodename>\settoheight</xrefnodename></pxref>), and <code>\settowidth</code> (<pxref label="_005csettowidth"><xrefnodename>\settowidth</xrefnodename></pxref>). +In addition, the <file>mathtools</file> package has many commands that offer +fine-grained control over spacing. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="556"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="557"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<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 <code>\operatorname</code> +command from the package <file>amsmath</file>. +</para> +<para>While most often used in mathematics, these three can appear in other +contexts. However, they don&textrsquo;t cause &latex; to change into horizontal +mode. So if one of these starts a paragraph then you should prefix it +with <code>\leavevmode</code>. +</para> + +</subsection> +</section> +<node name="Math-miscellany" spaces=" "><nodename>Math miscellany</nodename><nodeprev automatic="on">Spacing in math mode</nodeprev><nodeup automatic="on">Math formulas</nodeup></node> +<section spaces=" "><sectiontitle>Math miscellany</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="558">math miscellany</indexterm></cindex> + +<para>&latex; contains a wide variety of mathematics facilities. Here are +some that don&textrsquo;t fit into other categories. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Colon character & \colon</menunode><menudescription><pre xml:space="preserve">Colon. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\*</menunode><menudescription><pre xml:space="preserve">Discretionary multiplication. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\frac</menunode><menudescription><pre xml:space="preserve">Fraction. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\left & \right</menunode><menudescription><pre xml:space="preserve">Paired delimiters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\sqrt</menunode><menudescription><pre xml:space="preserve">Radicals. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\stackrel</menunode><menudescription><pre xml:space="preserve">Text over a relation. +</pre></menudescription></menuentry></menu> + + +<node name="Colon-character-_0026-_005ccolon" spaces=" "><nodename trailingspaces=" ">Colon character & \colon</nodename><nodenext automatic="on">\*</nodenext><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle>Colon character <code>:</code> & <code>\colon</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="559">:</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="560">colon character</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="812" mergedindex="cp">:</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="813" mergedindex="cp">\colon</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">: +\colon +</pre></example> + +<para>In mathematics, the colon character, <code>:</code>, is a relation. +</para> +<example endspaces=" "> +<pre xml:space="preserve">With side ratios \( 3:4 \) and \( 4:5 \), the triangle is right. +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="561"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="562"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<noindent></noindent> +<para>Ordinary &latex; defines <code>\colon</code> to produce the colon character +with the spacing appropriate for punctuation, as in set-builder notation +<code>\{x\colon 0\leq x<1\}</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="563"><r>package</r>, <code>amsmath</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="564"><code>amsmath</code> <r>package</r></indexterm></cindex> + +<para>But the widely-used <file>amsmath</file> package defines <code>\colon</code> for use +in the definition of functions <code>f\colon D\to C</code>. So if you want +the colon character as a punctuation then use <code>\mathpunct{:}</code>. +</para> + +</subsection> +<node name="_005c_002a" spaces=" "><nodename trailingspaces=" ">\*</nodename><nodenext automatic="on">\frac</nodenext><nodeprev automatic="on">Colon character & \colon</nodeprev><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\*</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="565">multiplication, discretionary</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="566">breaks, multiplication discretionary</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="567">line breaks, multiplication discretionary</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="568">discretionary breaks, multiplication</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="814" mergedindex="cp">\*</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\* +</pre></example> + +<para>A multiplication symbol that allows a line break. If there is a break +then &latex; puts a <code>\times</code> symbol, <U>00D7</U>, before +that break. +</para> +<para>In <code>\( A_1\* A_2\* A_3\* A_4 \)</code>, if there is no line break then +&latex; outputs it as though it were <code>\( A_1 A_2 A_3 A_4 \)</code>. If +a line break does happen, for example between the two middle ones, then +&latex; sets it like <code>\( A_1 A_2 \times \)</code>, followed by the +break, followed by <code>\( A_3 A_4 \)</code>. +</para> + +</subsection> +<node name="_005cfrac" spaces=" "><nodename>\frac</nodename><nodenext automatic="on">\left & \right</nodenext><nodeprev automatic="on">\*</nodeprev><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\frac</code> </sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="569">fraction</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="815" mergedindex="cp">\frac</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\frac{<var>numerator</var>}{<var>denominator</var>} +</pre></example> + +<para>Produces the fraction. Used as: <code>\begin{displaymath} +\frac{1}{\sqrt{2\pi\sigma}} \end{displaymath}</code>. In inline math +mode it comes out small; see the discussion of <code>\displaystyle</code> +(<pxref label="Math-formulas"><xrefnodename>Math formulas</xrefnodename></pxref>). +</para> + +</subsection> +<node name="_005cleft-_0026-_005cright" spaces=" "><nodename>\left & \right</nodename><nodenext automatic="on">\sqrt</nodenext><nodeprev automatic="on">\frac</nodeprev><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\left</code> & <code>\right</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="570">delimiters, paired</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="571">paired delimiters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="572">matching parentheses</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="573">matching brackets</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="574">null delimiter</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="816" mergedindex="cp">\left</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="817" mergedindex="cp">\right</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\left <var>delimiter1</var> ... \right <var>delimiter2</var> +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} + \left(\begin{array}{c} + 1 \\ + 0 \\ + \end{array}\right) +</pre></example> + +<para>Every <code>\left</code> must have a matching <code>\right</code>. Leaving out the +<code>\left(</code> in the above gets <samp>Extra \right</samp>. Leaving off the +<code>\right)</code> gets <samp>You can't use `\eqno' in math mode</samp>. +</para> +<para>However, the two delimiters <var>delimiter1</var> and <var>delimiter2</var> need +not match. A common case is that you want an unmatched brace, as +below. Use a period, <samp>.</samp>, as a null delimiter. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>Note that to get a curly brace as a delimiter you must prefix it with a +backslash, <code>\{</code>. +</para> + +</subsection> +<node name="_005csqrt" spaces=" "><nodename>\sqrt</nodename><nodenext automatic="on">\stackrel</nodenext><nodeprev automatic="on">\left & \right</nodeprev><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\sqrt</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="575">square root</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="576">roots</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="577">radical</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="818" mergedindex="cp">\sqrt</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\sqrt{<var>arg</var>} +\sqrt[<var>root-number</var>]{<var>arg</var>} +</pre></example> + +<para>The square root, or optionally other roots, of <var>arg</var>. The optional +argument <var>root-number</var> gives the root, i.e., enter the cube root of +<code>x+y</code> as <code>\sqrt[3]{x+y}</code>. +The radical grows with the size of <var>arg</var> (as the height of the +radical grows, the angle on the leftmost part gets steeper, until for +a large enough <code>arg</code>, it is vertical). +</para> +<para>&latex; has a separate <code>\surd</code> character (<pxref label="Math-symbols"><xrefnodename>Math symbols</xrefnodename></pxref>). +</para> + +</subsection> +<node name="_005cstackrel" spaces=" "><nodename>\stackrel</nodename><nodeprev automatic="on">\sqrt</nodeprev><nodeup automatic="on">Math miscellany</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\stackrel</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="578">stack math</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="579">relation, text above</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="819" mergedindex="cp">\stackrel</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\stackrel{<var>text</var>}{<var>relation</var>} +</pre></example> + +<para>Put <var>text</var> above <var>relation</var>. To put a function name above an +arrow enter <code>\stackrel{f}{\longrightarrow}</code>. +</para> + +</subsection> +</section> +</chapter> +<node name="Modes" spaces=" "><nodename>Modes</nodename><nodenext automatic="on">Page styles</nodenext><nodeprev automatic="on">Math formulas</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Modes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="580">modes</indexterm></cindex> + +<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> +<itemize commandarg="bullet" endspaces=" "> +<listitem><prepend>•</prepend> +<anchor name="modes-paragraph-mode">modes paragraph mode</anchor> +<cindex index="cp" spaces=" "><indexterm index="cp" number="581">paragraph mode</indexterm></cindex> +<para><dfn>Paragraph mode</dfn> 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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="582">left-to-right mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="583">LR mode</indexterm></cindex> +<anchor name="modes-lr-mode">modes lr mode</anchor> +<para><dfn>LR mode</dfn> (for left-to-right mode; in plain &tex; this is called +<dfn>restricted horizontal mode</dfn>) is in effect when &latex; starts +making a box with an <code>\mbox</code> command. As in paragraph mode, +&latex;&textrsquo;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&textrsquo;t fit there.) +</para> +</listitem><listitem><prepend>•</prepend> +<cindex index="cp" spaces=" "><indexterm index="cp" number="584">math mode</indexterm></cindex> +<anchor name="modes-math-mode">modes math mode</anchor> <para><dfn>Math mode</dfn> is when &latex; is generating +an inline mathematical formula. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="585">display math mode</indexterm></cindex> +<para><dfn>Display math mode</dfn> 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 <code>\int</code> +differs in the two situations.) +</para> +</listitem><listitem><prepend>•</prepend> +<cindex index="cp" spaces=" "><indexterm index="cp" number="586">vertical mode</indexterm></cindex> +<anchor name="modes-vertical-mode">modes vertical mode</anchor> +<para><dfn>Vertical mode</dfn> 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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="587">internal vertical mode</indexterm></cindex> +<anchor name="modes-internal-vertical-mode">modes internal vertical mode</anchor> +<para><dfn>Internal vertical mode</dfn> is in effect when &latex; starts making a +<code>\vbox</code>. This is the vertical analogue of LR mode. +</para> +</listitem></itemize> + +<noindent></noindent> +<para>For instance, if you begin a &latex; article with <samp>Let \( x \) be +...</samp> then these are the modes: first &latex; starts every document in +vertical mode, then it reads the <samp>L</samp> and switches to paragraph +mode, then the next switch happens at the <samp>\(</samp> where &latex; +changes to math mode, and then when it leaves the formula it pops +back to paragraph mode. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="588">inner paragraph mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="589">outer paragraph mode</indexterm></cindex> +<anchor name="modes-inner-paragraph-mode">modes inner paragraph mode</anchor> +<anchor name="modes-outer-paragraph-mode">modes outer paragraph mode</anchor> +<para>Paragraph mode has two subcases. If you use a <code>\parbox</code> command +or a <code>minipage</code> then &latex; is put into paragraph mode. But it +will not put a page break here. Inside one of these boxes, called a +<dfn>parbox</dfn>, &latex; is in <dfn>inner paragraph mode</dfn>. Its more usual +situation, where it can put page breaks, is <dfn>outer paragraph mode</dfn> +(<pxref label="Page-breaking"><xrefnodename>Page breaking</xrefnodename></pxref>). +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\ensuremath</menunode><menudescription><pre xml:space="preserve">Ensure that math mode is active. +</pre></menudescription></menuentry></menu> + +<node name="_005censuremath" spaces=" "><nodename>\ensuremath</nodename><nodeup automatic="on">Modes</nodeup></node> +<section spaces=" "><sectiontitle><code>\ensuremath</code></sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ensuremath{<var>formula</var>} +</pre></example> + +<para>Ensure that <var>formula</var> 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> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\dx}{\ensuremath{dx}} +In $\int f(x)\, \dx$, the \dx{} is an infinitesimal. +</pre></example> + +<para>Caution: the <code>\ensuremath</code> command is useful but not a panacea. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<noindent></noindent> +<para>Best is to typeset math things in a math mode. +</para> + +</section> +</chapter> +<node name="Page-styles" spaces=" "><nodename>Page styles</nodename><nodenext automatic="on">Spaces</nodenext><nodeprev automatic="on">Modes</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Page styles</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="590">styles, page</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="591">page styles</indexterm></cindex> + +<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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="592"><r>package</r>, <code>fancyhdr</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="593"><code>fancyhdr</code> <r>package</r></indexterm></cindex> + +<para>The package <file>fancyhdr</file> is very helpful for constructing page +styles. See its documentation on CTAN. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\maketitle</menunode><menudescription><pre xml:space="preserve">Generate a title page. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\pagenumbering</menunode><menudescription><pre xml:space="preserve">Set the style used for page numbers. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\pagestyle</menunode><menudescription><pre xml:space="preserve">Change the headings/footings style. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\thispagestyle</menunode><menudescription><pre xml:space="preserve">Change the headings/footings style for this page. +</pre></menudescription></menuentry></menu> + + +<node name="_005cmaketitle" spaces=" "><nodename>\maketitle</nodename><nodenext automatic="on">\pagenumbering</nodenext><nodeup automatic="on">Page styles</nodeup></node> +<section spaces=" "><sectiontitle><code>\maketitle</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="594">titles, making</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="820" mergedindex="cp">\maketitle</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\maketitle +</pre></example> + +<para>Generate a title. In the standard classes the title appears on a +separate page, except in the <code>article</code> class where it is at the top +of the first page. (<xref label="Document-class-options"><xrefnodename>Document class options</xrefnodename></xref> for information about +the <code>titlepage</code> document class option.) +</para> +<para>This example shows <code>\maketitle</code> appearing in its usual place, +immediately after <code>\begin{document}</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. + ... +</pre></example> + +<para>You tell &latex; the information used to produce the title by making +the following declarations. These must come before the +<code>\maketitle</code>, either in the preamble or in the document body. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="821" mergedindex="cp">\author{<var>name1</var> \and <var>name2</var> \and ...}</indexterm>\author{<var>name1</var> \and <var>name2</var> \and ...}</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="595">author, for titlepage</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="822" mergedindex="cp">\\ <r>for <code>\author</code></r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="823" mergedindex="cp">\and <r>for <code>\author</code></r></indexterm></findex> +<para>Required. Declare the document author or authors. The argument is a +list of authors separated by <code>\and</code> commands. To separate lines +within a single author&textrsquo;s entry, for instance to give the author&textrsquo;s +institution or address, use a double backslash, <code>\\</code>. If you omit +the <code>\author</code> declaration then you get <samp>LaTeX Warning: No +\author given</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="824" mergedindex="cp">\date{<var>text</var>}</indexterm>\date{<var>text</var>}</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="596">date, for titlepage</indexterm></cindex> +<para>Optional. Declare <var>text</var> to be the document&textrsquo;s date. The <var>text</var> +doesn&textrsquo;t need to be in a date format; it can be any text at all. If you +omit <code>\date</code> then &latex; uses the current date (<pxref label="_005ctoday"><xrefnodename>\today</xrefnodename></pxref>). +To have no date, instead use <code>\date{}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="825" mergedindex="cp">\thanks{<var>text</var>}</indexterm>\thanks{<var>text</var>}</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="597">thanks, for titlepage</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="598">credit footnote</indexterm></cindex> +<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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="826" mergedindex="cp">\title{<var>text</var>}</indexterm>\title{<var>text</var>}</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="599">title, for titlepage</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="827" mergedindex="cp">\\ <r>for <code>\title</code></r></indexterm></findex> +<para>Required. Declare <var>text</var> to be the title of the document. Get line +breaks inside <var>text</var> with a double backslash, <code>\\</code>. If you +omit the <code>\title</code> declaration then you get <samp>LaTeX Error: No +\title given</samp>. +</para> +</tableitem></tableentry></ftable> + +<para>To make your own title page, see <ref label="titlepage"><xrefnodename>titlepage</xrefnodename></ref>. You can either +create this as a one-off or you can include it as part of a renewed +<code>\maketitle</code> command. (Many publishers will provide a class to use +in place of <code>article</code> that formats the title according to their +house requirements.) +</para> + +</section> +<node name="_005cpagenumbering" spaces=" "><nodename>\pagenumbering</nodename><nodenext automatic="on">\pagestyle</nodenext><nodeprev automatic="on">\maketitle</nodeprev><nodeup automatic="on">Page styles</nodeup></node> +<section spaces=" "><sectiontitle><code>\pagenumbering</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="828" mergedindex="cp">\pagenumbering</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="600">page numbering style</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\pagenumbering{<var>number-style</var>} +</pre></example> + +<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 +<samp>a</samp>, etc. Starting on the page containing that section, the pages +are numbered <samp>1</samp>, etc. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{document}\pagenumbering{alph} + ... +\section{Main}\pagenumbering{arabic} + ... +</pre></example> + +<para>The argument <var>number-style</var> is one of the following (see +also <ref label="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol"><xrefnodename>\alph \Alph \arabic \roman \Roman \fnsymbol</xrefnodename></ref>). +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">arabic</itemformat></item> +</tableterm><tableitem><para>Arabic numerals: 1, 2, &dots; +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">roman</itemformat></item> +</tableterm><tableitem><para>lowercase Roman numerals: i, ii, &dots; +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">Roman</itemformat></item> +</tableterm><tableitem><para>uppercase Roman numerals: I, II, &dots; +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">alph</itemformat></item> +</tableterm><tableitem><para>lowercase letters: a, b, &dots; If you have more than 26 pages then you +get <samp>LaTeX Error: Counter too large</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">Alph</itemformat></item> +</tableterm><tableitem><para>uppercase letters: A, B, &dots; If you have more than 26 pages then you +get <samp>LaTeX Error: Counter too large</samp>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">gobble</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="601"><r>package</r>, <code>hyperref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="602"><code>hyperref</code> <r>package</r></indexterm></cindex> + <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 <file>hyperref</file> so to have the page number +not appear you may want to instead use <code>\pagestyle{empty}</code> or +<code>\thispagestyle{empty}</code>.) +</para> +</tableitem></tableentry></table> + +<para>Traditionally, if a document has front matter&textmdash;preface, table of +contents, etc.&textmdash;then it is numbered with lowercase Roman numerals. The +main matter of a document uses arabic. <xref label="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter"><xrefnodename>\frontmatter & \mainmatter +& \backmatter</xrefnodename></xref>. +</para> +<para>If you want to address where the page number appears on the page, +see <ref label="_005cpagestyle"><xrefnodename>\pagestyle</xrefnodename></ref>. If you want to change the value of page +number then you will manipulate the <code>page</code> counter +(<pxref label="Counters"><xrefnodename>Counters</xrefnodename></pxref>). +</para> + +</section> +<node name="_005cpagestyle" spaces=" "><nodename>\pagestyle</nodename><nodenext automatic="on">\thispagestyle</nodenext><nodeprev automatic="on">\pagenumbering</nodeprev><nodeup automatic="on">Page styles</nodeup></node> +<section spaces=" "><sectiontitle><code>\pagestyle</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="829" mergedindex="cp">\pagestyle</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="603">header style</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="604">footer style</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="605">running header and footer style</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\pagestyle{<var>style</var>} +</pre></example> + +<para>Declaration that specifies how the page headers and footers are typeset, +from the current page onwards. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="606"><r>package</r>, <code>fancyhdr</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="607"><code>fancyhdr</code> <r>package</r></indexterm></cindex> + +<para>A discussion with an example is below. Note first that the package +<file>fancyhdr</file> 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 <var>style</var>: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">plain</itemformat></item> +</tableterm><tableitem><para>The header is empty. The footer contains only a page number, centered. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">empty</itemformat></item> +</tableterm><tableitem><para>The header and footer is empty. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">headings</itemformat></item> +</tableterm><tableitem><para>Put running headers and footers on each page. The document style +specifies what goes in there; see the discussion below. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">myheadings</itemformat></item> +</tableterm><tableitem><para>Custom headers, specified via the <code>\markboth</code> or the +<code>\markright</code> commands. +</para> +</tableitem></tableentry></table> + +<para>Some discussion of the motivation for &latex;&textrsquo;s mechanism will help you +work with the options <code>headings</code> or <code>myheadings</code>. The +document source below produces an article, two-sided, with the pagestyle +<code>headings</code>. On this document&textrsquo;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 <code>\leftmark</code> and <code>\rightmark</code>. So it is up to +<code>\section</code> and <code>\subsection</code> to store that information there. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} + ... +</pre></example> + +<noindent></noindent> +<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 +<samp>Section 2</samp> 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, &dots;, 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 <code>\section</code> +issue a command <code>\markboth</code>, setting <code>\leftmark</code> +to <samp>Section 2</samp> and setting <code>\rightmark</code> to blank. +And, &latex; has <code>\subsection</code> issue a command <code>\markright</code>, +setting <code>\rightmark</code> to <samp>Subsection 2.1</samp>, etc. +</para> +<para>Here are the descriptions of <code>\markboth</code> and <code>\markright</code>: +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="830" mergedindex="cp">\markboth{<var>left-head</var>}{<var>right-head</var>}</indexterm>\markboth{<var>left-head</var>}{<var>right-head</var>}</itemformat></item> +</tableterm><tableitem><para>Sets both the right hand and left hand heading information for either a +page style of <code>headings</code> or <code>myheadings</code>. A left hand page +heading <var>left-head</var> is generated by the last <code>\markboth</code> +command before the end of the page. A right hand page heading +<var>right-head</var> is generated by the first <code>\markboth</code> or +<code>\markright</code> that comes on the page if there is one, otherwise by +the last one that came before that page. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="831" mergedindex="cp">\markright{<var>right</var>}</indexterm>\markright{<var>right</var>}</itemformat></item> +</tableterm><tableitem><para>Sets the right hand page heading, leaving the left unchanged. +</para> +</tableitem></tableentry></ftable> + + +</section> +<node name="_005cthispagestyle" spaces=" "><nodename>\thispagestyle</nodename><nodeprev automatic="on">\pagestyle</nodeprev><nodeup automatic="on">Page styles</nodeup></node> +<section spaces=" "><sectiontitle><code>\thispagestyle</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="832" mergedindex="cp">\thispagestyle</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="608">page style, this page</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\thispagestyle{<var>style</var>} +</pre></example> + +<para>Works in the same way as the <code>\pagestyle</code> (<pxref label="_005cpagestyle"><xrefnodename>\pagestyle</xrefnodename></pxref>), +except that it changes to <var>style</var> 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 <code>plain</code> style, as is the default (<pxref label="Page-styles"><xrefnodename>Page +styles</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\pagestyle{headings} +\begin{document} +\chapter{First chapter} + ... +\chapter{Second chapter}\thispagestyle{empty} + ... +</pre></example> + +<noindent></noindent> +<para>The <code>plain</code> style has a page number on it, centered in the footer. +To make the page entirely empty, the command +<code>\thispagestyle{empty}</code> immediately follows the second +<code>\chapter</code>. +</para> + +</section> +</chapter> +<node name="Spaces" spaces=" "><nodename>Spaces</nodename><nodenext automatic="on">Boxes</nodenext><nodeprev automatic="on">Page styles</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Spaces</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="609">spaces</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="610">white space</indexterm></cindex> + +<para>&latex; has many ways to produce white (or filled) space. Some of +these are best suited to mathematical text; see <ref label="Spacing-in-math-mode"><xrefnodename>Spacing in +math mode</xrefnodename></ref>. Some spacing commands are suitable for both regular text +and mathematical text; versions of some of these commands are in this +chapter. +</para> +<menu endspaces=" "> +<menucomment><pre xml:space="preserve">Horizontal space +</pre></menucomment><menuentry leadingtext="* "><menunode separator=":: ">\enspace & \quad & \qquad</menunode><menudescription><pre xml:space="preserve">Traditional horizontal spaces. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hspace</menunode><menudescription><pre xml:space="preserve">Any horizontal space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hfill</menunode><menudescription><pre xml:space="preserve">Stretchable horizontal space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hss</menunode><menudescription><pre xml:space="preserve">Infinitely stretchable/shrinkable horizontal space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\spacefactor</menunode><menudescription><pre xml:space="preserve">Stretchability of following space +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\(SPACE)</menunode><menudescription><pre xml:space="preserve">Backslash-space; and explicit space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">~</menunode><menudescription><pre xml:space="preserve">Tie, an unbreakable space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\thinspace & \negthinspace</menunode><menudescription><pre xml:space="preserve">One-sixth of an em, and negative one-sixth. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\/</menunode><menudescription><pre xml:space="preserve">Italic correction. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\hrulefill & \dotfill</menunode><menudescription><pre xml:space="preserve">Stretchable horizontal rule or dots. +</pre></menudescription></menuentry><menucomment><pre xml:space="preserve"> +Vertical space +</pre></menucomment><menuentry leadingtext="* "><menunode separator=":: ">\bigskip & \medskip & \smallskip</menunode><menudescription><pre xml:space="preserve">Inter-paragraph vertical spaces. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\bigbreak & \medbreak & \smallbreak</menunode><menudescription><pre xml:space="preserve">Inter-paragraph space and page breaks. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\strut</menunode><menudescription><pre xml:space="preserve">Ensure height of a line. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\vspace</menunode><menudescription><pre xml:space="preserve">Vertical space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\vfill</menunode><menudescription><pre xml:space="preserve">Stretchable vertical space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\addvspace</menunode><menudescription><pre xml:space="preserve">Add arbitrary vertical space if needed. +</pre></menudescription></menuentry></menu> + + +<node name="_005censpace-_0026-_005cquad-_0026-_005cqquad" spaces=" "><nodename>\enspace & \quad & \qquad</nodename><nodenext automatic="on">\hspace</nodenext><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\enspace</code> & <code>\quad</code> & <code>\qquad</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="833" mergedindex="cp">\enspace</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="834" mergedindex="cp">\quad</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="835" mergedindex="cp">\qquad</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\enspace +\quad +\qquad +</pre></example> + +<para>Insert a horizontal space of 1/2<dmn>em</dmn>, 1<dmn>em</dmn>, or 2<dmn>em</dmn>. 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 (<pxref label="Lengths_002fem"><xrefnodename>Lengths/em</xrefnodename></pxref>). +</para> +<para>This puts a suitable gap between two graphics. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + \includegraphics{womensmile.png}% + \qquad\includegraphics{mensmile.png} +\end{center} +</pre></example> + +<noindent></noindent> +<para><xref label="Spacing-in-math-mode"><xrefnodename>Spacing in math mode</xrefnodename></xref> for <code>\quad</code> and <code>\qquad</code>. These +are lengths from centuries of typesetting and so may be a better choice +in many circumstances than arbitrary lengths, such as you get with +<code>\hspace</code>. +</para> + +</section> +<node name="_005chspace" spaces=" "><nodename>\hspace</nodename><nodenext automatic="on">\hfill</nodenext><nodeprev automatic="on">\enspace & \quad & \qquad</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\hspace</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="836" mergedindex="cp">\hspace</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hspace{<var>length</var>} +\hspace*{<var>length</var>} +</pre></example> + +<para>Insert the horizontal space <var>length</var>. The <var>length</var> can be +positive, negative, or zero; adding negative space is like backspacing. +It is a rubber length, that is, it may contain a <code>plus</code> or +<code>minus</code> component, or both (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). Because the space is +stretchable and shrinkable, it is sometimes called <dfn>glue</dfn>. +</para> +<para>This makes a line with <samp>Name:</samp> an inch from the right margin. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\noindent\makebox[\linewidth][r]{Name:\hspace{1in}} +</pre></example> + +<para>The <code>*</code>-version inserts horizontal space that non-discardable. +More precisely, when &tex; breaks a paragraph into lines any white +space&textmdash;glues and kerns&textmdash;that come at a line break are discarded. The +<code>*</code>-version avoids that (technically, it adds a non-discardable +invisible item in front of the space). +</para> +<para>In this example +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}.} +</pre></example> + +<noindent></noindent> +<para>the 1 inch blank following <samp>conceived in</samp> falls at the start +of a line. If you erase the <code>*</code> then &latex; discards the blank. +</para> +<para>Here, the <code>\hspace</code> separates the three graphics. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>Because the argument to each <code>\hspace</code> has <code>minus 0.25cm</code>, +each can shrink a little if the three figures are too wide. But each +space won&textrsquo;t shrink more than 0.25<dmn>cm</dmn> (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> + +</section> +<node name="_005chfill" spaces=" "><nodename>\hfill</nodename><nodenext automatic="on">\hss</nodenext><nodeprev automatic="on">\hspace</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\hfill</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="837" mergedindex="cp">\hfill</indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="611">stretch, infinite horizontal</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="612">infinite horizontal stretch</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hfill +</pre></example> + +<para>Produce a rubber length which has no natural space but that can stretch +horizontally as far as needed (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>This creates a one-line paragraph with <samp>Name:</samp> on the left side +of the page and <samp>Quiz One</samp> on the right. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\noindent Name:\hfill Quiz One +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="838" mergedindex="cp">\fill</indexterm></findex> +<para>The <code>\hfill</code> command is equivalent to <code>\hspace{\fill}</code> and +so the space can be discarded at line breaks. To avoid that instead use +<code>\hspace*{\fill}</code> (<pxref label="_005chspace"><xrefnodename>\hspace</xrefnodename></pxref>). +</para> +<para>Here the graphs are evenly spaced in the middle of the figure. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{&arobase;{}c&arobase;{}}#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} +</pre></example> + +<noindent></noindent> +<para>Note the <code>\hspace*</code>&textrsquo;s where the space could otherwise be dropped. +</para> + +</section> +<node name="_005chss" spaces=" "><nodename>\hss</nodename><nodenext automatic="on">\spacefactor</nodenext><nodeprev automatic="on">\hfill</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\hss</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="839" mergedindex="cp">\hss</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="613">horizontal space</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="614">horizontal space, stretchable</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="615">space, inserting horizontal</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hss +</pre></example> + +<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 <code>\makebox</code> command to get the +effects of <code>\hss</code> (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></pxref>). +</para> +<para>Here, the first line&textrsquo;s <code>\hss</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">X\hbox to 0pt{Z\hss}Y +X\hbox to 0pt{\hss Z}Y +</pre></example> + +<noindent></noindent> +<para>Without the <code>\hss</code> you get something like <samp>Overfull \hbox +(6.11111pt too wide) detected at line 20</samp>. +</para> + +</section> +<node name="_005cspacefactor" spaces=" "><nodename>\spacefactor</nodename><nodenext automatic="on">\(SPACE)</nodenext><nodeprev automatic="on">\hss</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\spacefactor</code></sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\spacefactor=<var>integer</var> +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="840" mergedindex="cp">\spacefactor</indexterm></findex> +<para>Influence &latex;&textrsquo;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 +<dfn>interword glue</dfn>; <pxref label="_005chspace"><xrefnodename>\hspace</xrefnodename></pxref>). The <code>\spacefactor</code> 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 <dfn>space factor</dfn>. 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 <var>f</var> is 1000 then the glue gap will be the +font&textrsquo;s normal space value (for Computer Modern Roman 10 point this is +3.3333 points). Otherwise, if the space factor <var>f</var> is greater +than 2000 then &tex; adds the font&textrsquo;s extra space value (for Computer +Modern Roman 10 point this is 1.11111 points), and then the font&textrsquo;s +normal stretch value is multiplied by <math>f /1000</math> and the normal +shrink value is multiplied by <math>1000/f</math> (for Computer Modern Roman +10 point these are 1.66666 and 1.11111 points). +</para> +<para>For example, consider the period ending <code>A man's best friend is his +dog.</code> 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 <code>friend</code>, 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 (<pxref label="_005c_0040"><xrefnodename>\&arobase;</xrefnodename></pxref>). +</para> +<para>You can only use <code>\spacefactor</code> in paragraph mode or LR mode +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). You can see the current value with +<code>\the\spacefactor</code> or <code>\showthe\spacefactor</code>. +</para> +<para>(Comment, not really related to <code>\spacefactor</code>: if you get errors +like <samp>You can't use `\spacefactor' in vertical mode</samp>, or <samp>You +can't use `\spacefactor' in math mode.</samp>, or <samp>Improper \spacefactor</samp> +then you have probably tried to redefine an internal command. +<xref label="_005cmakeatletter-_0026-_005cmakeatother"><xrefnodename>\makeatletter & \makeatother</xrefnodename></xref>.) +</para> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\&arobase;</menunode><menudescription><pre xml:space="preserve">Distinguish sentence-ending periods from abbreviations. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\frenchspacing</menunode><menudescription><pre xml:space="preserve">Equal interword and inter-sentence space. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\normalsfcodes</menunode><menudescription><pre xml:space="preserve">Restore space factor settings to the default. +</pre></menudescription></menuentry></menu> + + +<node name="_005c_0040" spaces=" "><nodename trailingspaces=" ">\&arobase;</nodename><nodenext automatic="on">\frenchspacing</nodenext><nodeup automatic="on">\spacefactor</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\&arobase;</code> </sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="841" mergedindex="cp">\&arobase;</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="842" mergedindex="cp">at-sign</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="616">period, sentence-ending</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="617">period, abbreviation-ending</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="618">period, spacing after</indexterm></cindex> +<anchor name="_005cAT">\AT</anchor><!-- c old name --> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>capital-letter</var>\&arobase;. +</pre></example> + +<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 (<pxref label="_005cspacefactor"><xrefnodename>\spacefactor</xrefnodename></pxref>). +</para> +<para>This example shows the two cases to remember. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The songs \textit{Red Guitar}, etc.\ are by Loudon Wainwright~III\&arobase;. +</pre></example> + +<noindent></noindent> +<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 +<code>\&arobase;</code> before it. The first period ends the abbreviation +<samp>etc.</samp> but not the sentence. The backslash-space, <code>\ </code>, +produces a mid-sentence space. +</para> +<para>So: if you have a capital letter followed by a period that ends the +sentence, then put <code>\&arobase;</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">Use the \textit{Instructional Practices Guide}, +(a book by the MAA)\&arobase;. +</pre></example> + +<noindent></noindent> +<para>will have correct inter-sentence spacing after the period. +</para> +<para>The <code>\&arobase;</code> command is only for a text mode. If you use it outside of +a text mode then you get <samp>You can't use `\spacefactor' in vertical +mode</samp> (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</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, (<code>\ </code>), or a tie, (<code>~</code>), or <code>\&arobase;</code>. +Examples are <code>Nat.\ Acad.\ Science</code>, and <code>Mr.~Bean</code>, and +<code>(manure, etc.\&arobase;) for sale</code> (note in the last one that the +<code>\&arobase;</code> comes before the closing parenthesis). +</para> + +</subsection> +<node name="_005cfrenchspacing" spaces=" "><nodename>\frenchspacing</nodename><nodenext automatic="on">\normalsfcodes</nodenext><nodeprev automatic="on">\&arobase;</nodeprev><nodeup automatic="on">\spacefactor</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\frenchspacing</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="843" mergedindex="cp">\frenchspacing</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="844" mergedindex="cp">\nonfrenchspacing</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="619">spacing, inter-sentence</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\frenchspacing +\nonfrenchspacing +</pre></example> + +<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 +(<pxref label="_005cspacefactor"><xrefnodename>\spacefactor</xrefnodename></pxref>); 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 <code>\frenchspacing</code> +(the command is from Plain &tex;) switches to the tradition that all +spaces are treated equally. +</para> + +</subsection> +<node name="_005cnormalsfcodes" spaces=" "><nodename>\normalsfcodes</nodename><nodeprev automatic="on">\frenchspacing</nodeprev><nodeup automatic="on">\spacefactor</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\normalsfcodes</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="845" mergedindex="cp">\normalsfcodes</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="620">spacing, inter-sentence</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\normalsfcodes +</pre></example> + +<para>Reset the &latex; space factor values to the default +(<pxref label="_005cspacefactor"><xrefnodename>\spacefactor</xrefnodename></pxref>). +</para> + +</subsection> +</section> +<node name="_005c_0028SPACE_0029" spaces=" "><nodename trailingspaces=" ">\(SPACE)</nodename><nodenext automatic="on">~</nodenext><nodeprev automatic="on">\spacefactor</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle>Backslash-space, <code>\ </code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="621">\NEWLINE</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="622">\SPACE</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="623">\TAB</indexterm></cindex> + +<para>This section refers to the command consisting of two characters, a +backslash followed by a space. Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ +</pre></example> + +<para>Produce a space. By default it produces white space of length +3.33333<dmn>pt</dmn> plus 1.66666<dmn>pt</dmn> minus 1.11111<dmn>pt</dmn>. +</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> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{l} +One blank: makes some space \\ +Three blanks: in a row \\ +Three spaces:\ \ \ in a row \\ +\end{tabular} +</pre></example> + +<noindent></noindent> +<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 +<code>\hspace</code>; see <ref label="_005chspace"><xrefnodename>\hspace</xrefnodename></ref>.) +</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 <code>\TeX\ is nice</code>. (But using curly parentheses, as in +<code>\TeX{} is best</code>, has the advantage of still working if the next +character is a period.) The other common use is that it marks a period +as ending an abbreviation instead of ending a sentence, as in <code>So +says Prof.\ Smith</code> (<pxref label="_005c_0040"><xrefnodename>\&arobase;</xrefnodename></pxref>). +</para> +<para>Under normal circumstances, <code>\</code><key>tab</key> and <code>\</code><key>newline</key> +are equivalent to backslash-space, <code>\ </code>. +</para> +<!-- c @PkgIndex{xspace} --> +<!-- c Some individual commands, notably those defined with the @code{xspace}, --> +<!-- c package do not follow the standard behavior. --> + + +</section> +<node name="_007e" spaces=" "><nodename>~</nodename><nodenext automatic="on">\thinspace & \negthinspace</nodenext><nodeprev automatic="on">\(SPACE)</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>~</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="846" mergedindex="cp">~</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="624">tie</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="625">space, hard</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="626">space, unbreakable</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="627">NBSP</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>before</var>~<var>after</var> +</pre></example> + +<para>The tie character, <code>~</code>, produces a space between <var>before</var> and +<var>after</var> at which the line will not be broken. By default the white +space has length 3.33333<dmn>pt</dmn> plus 1.66666<dmn>pt</dmn> minus +1.11111<dmn>pt</dmn> (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>Here &latex; will not break the line between the final two words. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Thanks to Prof.~Lerman. +</pre></example> + +<noindent></noindent> +<para>In addition, despite the period, &latex; does not use the +end-of-sentence spacing (<pxref label="_005c_0040"><xrefnodename>\&arobase;</xrefnodename></pxref>). +</para> +<para>Ties prevent the end of line separation of things where that could cause +confusion. But they also reduce &latex;&textrsquo;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> +<itemize commandarg="bullet" spaces=" " endspaces=" "><itemprepend><formattingcommand command="bullet"/></itemprepend> +<listitem><prepend>•</prepend> +<para>Between an enumerator and its item, such as in references: +<code>Chapter~12</code>, or <code>Theorem~\ref{th:Wilsons}</code>, or +<code>Figure~\ref{fig:KGraph}</code>. When cases are enumerated inline: +<code>(b)~Show that $f(x)$ is (1)~continuous, and (2)~bounded</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="628"><r>package</r>, <code>siunitx</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="629"><code>siunitx</code> <r>package</r></indexterm></cindex> + +</listitem><listitem><prepend>•</prepend> +<para>Between a number and its unit: <code>$745.7.8$~watts</code> (the +<file>siunitx</file> package has a special facility for this) or +<code>144~eggs</code>. This includes between a month and a date: +<code>October~12</code> or <code>12~Oct</code>. In general, in any expressions where +numbers and abbreviations or symbols are separated by a space: +<code>AD~565</code>, or <code>2:50~pm</code>, or <code>Boeing~747</code>, or +<code>268~Plains Road</code>, or <code>\$$1.4$~billion</code>. +</para> +</listitem><listitem><prepend>•</prepend> +<para>When mathematical phrases are rendered in words: <code>equals~$n$</code>, or +<code>less than~$\epsilon$</code>, or <code>given~$X$</code>, or <code>modulo~$p^e$ +for all large~$n$</code> (but compare <code>is~$15$</code> with <code>is $15$~times +the height</code>). Between mathematical symbols in apposition with nouns: +<code>dimension~$d$</code> or <code>function~$f(x)$</code> (but compare <code>with +length $l$~or more</code>). When a symbol is a tightly bound object of a +preposition: <code>of~$x$</code>, or <code>from $0$ to~$1$</code>, or <code>in +common with~$m$</code>. +</para> +</listitem><listitem><prepend>•</prepend> +<para>Between symbols in series: <code>$1$,~$2$, or~$3$</code> or <code>$1$,~$2$, +\ldots,~$n$</code>. +</para> +</listitem><listitem><prepend>•</prepend> +<para>Between a person&textrsquo;s forenames and between multiple surnames: +<code>Donald~E. Knuth</code>, or <code>Luis~I. Trabb~Pardo</code>, or +<code>Charles~XII</code> (but you must give TeX places to break the line so +you may do <code>Charles Louis Xavier~Joseph de~la Vall\'ee~Poussin</code>). +</para> +</listitem><listitem><prepend>•</prepend> +<para>Before a dash: <code>pages 12~--14</code> or <code>it is~--- it must be +said~--- plausible</code>. +</para> +</listitem></itemize> + + +</section> +<node name="_005cthinspace-_0026-_005cnegthinspace" spaces=" "><nodename>\thinspace & \negthinspace</nodename><nodenext automatic="on">\/</nodenext><nodeprev automatic="on">~</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\thinspace</code> & <code>\negthinspace</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="847" mergedindex="cp">\thinspace</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="848" mergedindex="cp">\negthinspace</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="630">thin space</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="631">space, thin</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="632">thin space, negative</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="633">space, negative thin</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\thinspace +\negthinspace +</pre></example> + +<para>Produce an unbreakable and unstretchable space of 1/6<dmn>em</dmn> and +-1/6<dmn>em</dmn>. These are the text mode equivalents of <code>\,</code> and +<code>\!</code> (<pxref label="Spacing-in-math-mode_002f_005cthinspace"><xrefnodename>Spacing in math mode/\thinspace</xrefnodename></pxref>). You can use +<code>\,</code> as a synonym for <code>\thinspace</code> in text mode. +</para> +<para>The <code>\negthinspace</code> command is used in text mode mostly for +fiddling with spaces. One common use of <code>\thinspace</code> is as the +space between nested quotes. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Killick replied, ``I heard the Captain say, `Ahoy there.'\thinspace'' +</pre></example> + +<noindent></noindent> +<para>Another use is that some style guides call for a <code>\thinspace</code> +between an ellipsis and a sentence ending period (other style guides, +though, think the three dots are quite enough already). Still another +use is between initials, as in <code>D.\thinspace E.\ Knuth</code>. +</para> + +</section> +<node name="_005c_002f" spaces=" "><nodename>\/</nodename><nodenext automatic="on">\hrulefill & \dotfill</nodenext><nodeprev automatic="on">\thinspace & \negthinspace</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\/</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="849" mergedindex="cp">\/</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="634">italic correction</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve"><var>before-character</var>\/<var>after-character</var> +</pre></example> + +<para>Insert an <dfn>italic correction</dfn>, a small space defined by the font +designer for each character, to avoid the character colliding with +whatever follows. When you use <code>\/</code>, &latex; takes the correction +from the font metric file, scales it by any scaling that has been +applied to the font, and then inserts that much horizontal space. +</para> +<para>Here, were it not for the <code>\/</code>, the <var>before-character</var> +italic f would hit the <var>after-character</var> roman H +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\companylogo}{{\it f}\/H} +</pre></example> + +<noindent></noindent> +<para>because the italic letter leans far to the right. +</para> +<para>If <var>after-character</var> is a period or comma then don&textrsquo;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 <code>\textit</code> or <code>\itshape</code> to +change fonts, &latex; will automatically insert any needed italic +correction (<pxref label="Font-styles"><xrefnodename>Font styles</xrefnodename></pxref>). +</para> +<para>Roman characters can also have an italic correction. An example is in +the name <code>pdf\/\TeX</code>. +</para> +<para>There is no concept of italic correction in math mode; spacing is done +in a different way. +</para> + +</section> +<node name="_005chrulefill-_0026-_005cdotfill" spaces=" "><nodename>\hrulefill & \dotfill</nodename><nodenext automatic="on">\bigskip & \medskip & \smallskip</nodenext><nodeprev automatic="on">\/</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\hrulefill</code> & <code>\dotfill</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="850" mergedindex="cp">\hrulefill</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="851" mergedindex="cp">\dotfill</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\hrulefill +\dotfill +</pre></example> + +<para>Produce an infinite horizontal rubber length (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>) 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> +<example endspaces=" "> +<pre xml:space="preserve">Name:~\makebox[2in]{\hrulefill} +</pre></example> + +<noindent></noindent> +<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> +<example endspaces=" "> +<pre xml:space="preserve">\noindent John Aubrey, RN \dotfill{} Melbury Lodge +</pre></example> + +<para>To make the rule or dots go to the line&textrsquo;s end use <code>\null</code> at the +start or end. +</para> +<para>To change the rule&textrsquo;s thickness, copy the definition and adjust it, as +here +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\hrulefill}{% + \leavevmode\leaders\hrule height 1pt\hfill\kern\z&arobase;} +</pre></example> + +<noindent></noindent> +<para>which changes the default thickness of 0.4<dmn>pt</dmn> to 1<dmn>pt</dmn>. +Similarly, adjust the dot spacing as with +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\dotfill}{% + \leavevmode\cleaders\hb&arobase;xt&arobase;1.00em{\hss .\hss }\hfill\kern\z&arobase;} +</pre></example> + +<noindent></noindent> +<para>which changes the default length of 0.33<dmn>em</dmn> to 1.00<dmn>em</dmn>. +</para> +<para>This example produces a line for a signature. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{minipage}{4cm} + \centering + \hrulefill\\ + Signed +\end{minipage} +</pre></example> + +<noindent></noindent> +<para>The line is 4<dmn>cm</dmn> long. +</para> + +</section> +<node name="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip" spaces=" "><nodename>\bigskip & \medskip & \smallskip</nodename><nodenext automatic="on">\bigbreak & \medbreak & \smallbreak</nodenext><nodeprev automatic="on">\hrulefill & \dotfill</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\bigskip</code> & <code>\medskip</code> & <code>\smallskip</code></sectiontitle> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\bigskip +\medskip +\smallskip +</pre></example> + +<para>Produce an amount of vertical space, large or medium-sized or +small. These commands are fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Here the skip suggests the passage of time (from <i>The Golden Ocean</i> by +O&textrsquo;Brian). +</para> +<example endspaces=" "> +<pre xml:space="preserve">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. +</pre></example> + +<para>Each command is associated with a length defined in the document class +file. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="bigskip">bigskip</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="852" mergedindex="cp">\bigskip</indexterm>\bigskip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="853" mergedindex="cp">\bigskipamount</indexterm></findex> +<para>The same as <code>\vspace{\bigskipamount}</code>, ordinarily about one line +space, with stretch and shrink. The default for the <code>book</code> and +<code>article</code> classes is <code>12pt plus 4pt minus 4pt</code>. +</para> +<anchor name="medskip">medskip</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="854" mergedindex="cp">\medskip</indexterm>\medskip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="855" mergedindex="cp">\medskipamount</indexterm></findex> +<para>The same as <code>\vspace{\medskipamount}</code>, ordinarily about half of a +line space, with stretch and shrink. The default for the <code>book</code> +and <code>article</code> classes is <code>6pt plus 2pt minus 2pt</code>. +</para> +<anchor name="smallskip">smallskip</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="856" mergedindex="cp">\smallskip</indexterm>\smallskip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="857" mergedindex="cp">\smallskipamount</indexterm></findex> +<para>The same as <code>\vspace{\smallskipamount}</code>, ordinarily about a +quarter of a line space, with stretch and shrink. The default for the +<code>book</code> and <code>article</code> classes is <code>3pt plus 1pt minus 1pt</code>. +</para> +</tableitem></tableentry></ftable> + +<para>Because each command is a <code>\vspace</code>, 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 <code>\bigbreak</code>, <code>\medbreak</code>, and <code>\smallbreak</code> +are similar but also suggest to &latex; that this is a good place to +put a page break (<pxref label="_005cbigbreak-_0026-_005cmedbreak-_0026-_005csmallbreak"><xrefnodename>\bigbreak & \medbreak & \smallbreak</xrefnodename></pxref>. +</para> + +</section> +<node name="_005cbigbreak-_0026-_005cmedbreak-_0026-_005csmallbreak" spaces=" "><nodename>\bigbreak & \medbreak & \smallbreak</nodename><nodenext automatic="on">\strut</nodenext><nodeprev automatic="on">\bigskip & \medskip & \smallskip</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\bigbreak</code> & <code>\medbreak</code> & <code>\smallbreak</code></sectiontitle> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\bigbreak +\medbreak +\smallbreak +</pre></example> + +<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><xref label="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip"><xrefnodename>\bigskip & \medskip & \smallskip</xrefnodename></xref>, 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 <code>\addvspace</code>). In addition, they terminate a paragraph where +they are used: this example +</para> +<example endspaces=" "> +<pre xml:space="preserve">abc\bigbreak def ghi + +jkl mno pqr +</pre></example> + +<noindent></noindent> +<para>will output three paragraphs, the first ending in <samp>abc</samp> and the +second starting, after an extra vertical space and a paragraph indent, +with <samp>def</samp>. +</para> + +</section> +<node name="_005cstrut" spaces=" "><nodename>\strut</nodename><nodenext automatic="on">\vspace</nodenext><nodeprev automatic="on">\bigbreak & \medbreak & \smallbreak</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\strut</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="858" mergedindex="cp">\strut</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="635">strut</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\strut +</pre></example> + +<para>Ensure that the current line has height at least <code>0.7\baselineskip</code> +and depth at least <code>0.3\baselineskip</code>. Essentially, &latex; +inserts into the line a rectangle having zero width, +<code>\rule[-0.3\baselineskip]{0pt}{\baselineskip}</code> (<pxref label="_005crule"><xrefnodename>\rule</xrefnodename></pxref>). +The <code>\baselineskip</code> changes with the current font and fontsize. +</para> +<para>In this example the <code>\strut</code> keeps the box inside the frame from +having zero height. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\fboxsep}{0pt}\framebox[2in]{\strut} +</pre></example> + +<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 <code>\strut</code> at the end of its first +item&textrsquo;s second line. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}% +</pre></example> + +<noindent></noindent> +<para>The final two lists use <code>\fbox</code> to show what&textrsquo;s happening. The +third list&textrsquo;s <code>\parbox</code> goes only to the bottom of its second +<samp>test</samp>, 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> +<cindex index="cp" spaces=" "><indexterm index="cp" number="636"><r>package</r>, <code>TikZ</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="637"><code>TikZ</code> <r>package</r></indexterm></cindex> + <cindex index="cp" spaces=" "><indexterm index="cp" number="638"><r>package</r>, <code>Asymptote</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="639"><code>Asymptote</code> <r>package</r></indexterm></cindex> + +<para>The <code>\strut</code> command is often useful in graphics, such as in +<file>TikZ</file> or <file>Asymptote</file>. For instance, you may have a command +such as <code>\graphnode{<var>node-name</var>}</code> that fits a circle around +<var>node-name</var>. However, unless you are careful the <var>node-name</var>&textrsquo;s +<samp>x</samp> and <samp>y</samp> will produce different-diameter circles because +the characters are different sizes. A careful <code>\graphnode</code> might +insert a <code>\strut</code>, then <var>node-name</var>, and then draw the circle. +</para> +<para>The general approach of using a zero width <code>\rule</code> is useful in +many circumstances. In this table, the zero-width rule keeps the top of +the first integral from hitting the <code>\hline</code>. Similarly, the +second rule keeps the second integral from hitting the first. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>(Although the line-ending double backslash command has an available +optional argument to put in more vertical room, that won&textrsquo;t work here. +Changing the first double backslash to something like <code>\\[2.5ex]</code> +will put the room between the header line and the <code>\hline</code>, and the +integral would still hit the line.) +</para> + +</section> +<node name="_005cvspace" spaces=" "><nodename>\vspace</nodename><nodenext automatic="on">\vfill</nodenext><nodeprev automatic="on">\strut</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\vspace</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="859" mergedindex="cp">\vspace</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="640">vertical space</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="641">space, vertical</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\vspace{<var>length</var>} +\vspace*{<var>length</var>} +</pre></example> + +<para>Add the vertical space <var>length</var>. The <var>length</var> can be positive, +negative, or zero. It is a rubber length&textmdash;it may contain a <code>plus</code> +or <code>minus</code> component (<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>This puts space between the two paragraphs. +</para> +<example endspaces=" "> +<pre xml:space="preserve">And I slept. + +\vspace{1ex plus 0.5ex} +The new day dawned cold. +</pre></example> + +<noindent></noindent> +<para>(<xref label="_005cbigskip-_0026-_005cmedskip-_0026-_005csmallskip"><xrefnodename>\bigskip & \medskip & \smallskip</xrefnodename></xref> for common inter-paragraph +spaces.) +</para> +<para>The <code>*</code>-version inserts vertical space that non-discardable. More +precisely, &latex; discards vertical space at a page break and the +<code>*</code>-version causes the space to stay. This example leaves space +between the two questions. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Question: Find the integral of \( 5x^4+5 \). + +\vspace*{2cm plus 0.5cm} +Question: Find the derivative of \( x^5+5x+9 \). +</pre></example> + +<noindent></noindent> +<para>That space will be present even if the page break happens to fall +between the questions. +</para> +<para>If you use <code>\vspace</code> in the middle of a paragraph (i.e., in +horizontal mode) then the space is inserted after the line containing +the <code>\vspace</code> command; it does not start a new paragraph at the +<code>\vspace</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + + +</section> +<node name="_005cvfill" spaces=" "><nodename>\vfill</nodename><nodenext automatic="on">\addvspace</nodenext><nodeprev automatic="on">\vspace</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\vfill</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="860" mergedindex="cp">\vfill</indexterm></findex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="642">stretch, infinite vertical</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="643">infinite vertical stretch</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\vfill +</pre></example> + +<para>End the current paragraph and insert a vertical rubber length that is +infinite, so it can stretch or shrink as far as needed +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>It is often used in the same way as <code>\vspace{\fill}</code>, except that +<code>\vfill</code> ends the current paragraph whereas <code>\vspace{\fill}</code> +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 <ref label="_005cvspace"><xrefnodename>\vspace</xrefnodename></ref>. +</para> +<para>In this example the page is filled, so the top and bottom lines contain +the text <samp>Lost Dog!</samp> and the second <samp>Lost Dog!</samp> is exactly +halfway between them. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{document} +Lost Dog! +\vfill +Lost Dog! % perfectly in the middle +\vfill +Lost Dog! +\end{document} +</pre></example> + + +</section> +<node name="_005caddvspace" spaces=" "><nodename>\addvspace</nodename><nodeprev automatic="on">\vfill</nodeprev><nodeup automatic="on">Spaces</nodeup></node> +<section spaces=" "><sectiontitle><code>\addvspace</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="861" mergedindex="cp">\addvspace</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="644">vertical space</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="645">space, inserting vertical</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addvspace{<var>vert-length</var>} +</pre></example> + +<para>Add a vertical space of <var>vert-length</var>. However, if there are two or +more <code>\addvspace</code>&textrsquo;s in a sequence then together they only add the +space needed to make the natural length equal to the maximum of the +<var>vert-length</var>&textrsquo;s in that sequence. This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). The <var>vert-length</var> is a rubber length +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). +</para> +<para>This example illustrates. The <code>picture</code> draws a scale. In a +standard &latex; article the length <code>\baselineskip</code> is 12<dmn>pt</dmn>. +The two rules here are 22<dmn>pt</dmn> apart: the sum of the +<code>\baselineskip</code> and the 10<dmn>pt</dmn> from the first <code>addvspace</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>Now uncomment the second <code>\addvspace</code>. It does not make the gap +20<dmn>pt</dmn> longer; instead the gap is the sum of <code>\baselineskip</code> +and 20<dmn>pt</dmn>. So <code>\addvspace</code> in a sense does the opposite of +its name &textmdash; 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 +<code>theorem</code> environment begins and ends with <code>\addvspace</code> so +that two consecutive <code>theorem</code>&textrsquo;s are separated by one vertical +space, not two. +</para> +<para>A error <samp>Something's wrong--perhaps a missing \item</samp> pointing to an +<code>\addvspace</code> means that you were not in vertical mode when you hit +this command. One way to change that is to precede <code>\addvspace</code> +with a <code>\par</code> command (<pxref label="_005cpar"><xrefnodename>\par</xrefnodename></pxref>), as in the above example. +</para> + +</section> +</chapter> +<node name="Boxes" spaces=" "><nodename>Boxes</nodename><nodenext automatic="on">Color</nodenext><nodeprev automatic="on">Spaces</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Boxes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="646">boxes</indexterm></cindex> + +<!-- c 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 <file>adjustbox</file>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\mbox & \makebox</menunode><menudescription><pre xml:space="preserve">Horizontal boxes. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\fbox & \framebox</menunode><menudescription><pre xml:space="preserve">Put a frame around a box. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\parbox</menunode><menudescription><pre xml:space="preserve">Box with text in paragraph mode. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\raisebox</menunode><menudescription><pre xml:space="preserve">Raise or lower text. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\sbox & \savebox</menunode><menudescription><pre xml:space="preserve">Like <code>\makebox</code> but save the text for later. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">lrbox</menunode><menudescription><pre xml:space="preserve">Environment version of <code>\sbox</code>. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\usebox</menunode><menudescription><pre xml:space="preserve">Print saved text. +</pre></menudescription></menuentry></menu> + + +<node name="_005cmbox-_0026-_005cmakebox" spaces=" "><nodename>\mbox & \makebox</nodename><nodenext automatic="on">\fbox & \framebox</nodenext><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\mbox</code> & <code>\makebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="862" mergedindex="cp">\mbox</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="863" mergedindex="cp">\makebox</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="647">box</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="648">make a box</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="649">hyphenation, preventing</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\mbox{<var>text</var>} +\makebox{<var>text</var>} +\makebox[<var>width</var>]{<var>text</var>} +\makebox[<var>width</var>][<var>position</var>]{<var>text</var>} +</pre></example> + +<para>Create a box, a container for material. The <var>text</var> is typeset in +LR mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>) so it is not broken into lines. The +<code>\mbox</code> command is robust, while <code>\makebox</code> is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>Because <code>text</code> is not broken into lines, you can use <code>\mbox</code> +to prevent hyphenation. In this example, &latex; will not hyphenate +the table name, <samp>T-4</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">See Table~\mbox{T-4} +</pre></example> + +<para>The first two command versions, <code>\mbox</code> and <code>\makebox</code>, are +roughly equivalent. They create a box just wide enough to contain the +<var>text</var>. (They are like plain &tex;&textrsquo;s <code>\hbox</code>.) +</para> +<para>In the third version the optional argument <var>width</var> 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, <var>text</var> can be too small; +this creates a full-line box +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makebox[\linewidth]{Chapter Exam} +</pre></example> + +<noindent></noindent> +<para>with <samp>Chapter Exam</samp> centered. But <var>text</var> can also be too wide +for <var>width</var>. See the example below of zero-width boxes. +</para> +<anchor name="mbox-makebox-depth">mbox makebox depth</anchor> +<anchor name="mbox-makebox-height">mbox makebox height</anchor> +<anchor name="mbox-makebox-width">mbox makebox width</anchor> +<anchor name="mbox-makebox-totalheight">mbox makebox totalheight</anchor> +<para>In the <var>width</var> argument you can use the following lengths that refer +to the dimension of the box that &latex; gets on typesetting +<var>text</var>: <code>\depth</code>, <code>\height</code>, <code>\width</code>, +<code>\totalheight</code> (this is the box&textrsquo;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> +<example endspaces=" "> +<pre xml:space="preserve">\makebox[2\width]{Get a stretcher} +</pre></example> + +<para>For the fourth command version the optional argument <var>position</var> +gives position of the text within the box. It may take the following +values: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">c</itemformat></item> +</tableterm><tableitem><para>The <var>text</var> is centered (default). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">l</itemformat></item> +</tableterm><tableitem><para>The <var>text</var> is flush left. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">r</itemformat></item> +</tableterm><tableitem><para>Flush right. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">s</itemformat></item> +</tableterm><tableitem><para>Stretch the interword space in <var>text</var> across the entire <var>width</var>. +The <var>text</var> must contain stretchable space for this to work. For +instance, this could head a press release: +<code>\noindent\makebox[\textwidth][s]{\large\hfil IMMEDIATE\hfil +RELEASE\hfil}</code> +</para></tableitem></tableentry></table> + +<para>A common use of <code>\makebox</code> is to make zero-width text boxes. This +puts the value of the quiz questions to the left of those questions. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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? +</pre></example> + +<noindent></noindent> +<para><cindex index="cp" spaces=" "><indexterm index="cp" number="650"><r>package</r>, <code>TikZ</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="651"><code>TikZ</code> <r>package</r></indexterm></cindex> +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="652"><r>package</r>, <code>Asymptote</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="653"><code>Asymptote</code> <r>package</r></indexterm></cindex> + +<para>The right edge of the output <samp>10 points </samp> (note the ending space) +will be just before the <samp>What</samp> (note the space after +<samp>points</samp>). You can use <code>\makebox</code> similarly when making +graphics, such as in <file>TikZ</file> or <file>Asymptote</file>, 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 <ref label="_005cfbox-_0026-_005cframebox"><xrefnodename>\fbox & \framebox</xrefnodename></ref>. For colors +see <ref label="Colored-boxes"><xrefnodename>Colored boxes</xrefnodename></ref>. +</para> +<para>There is a related version of <code>\makebox</code> that is used within the +<code>picture</code> environment, where the length is given in terms of +<code>\unitlength</code> (<pxref label="_005cmakebox-_0028picture_0029"><xrefnodename>\makebox (picture)</xrefnodename></pxref>). +</para> +<para>If you put a double-backslash into <var>text</var> then &latex; will not +give you a new line; for instance <code>\makebox{abc def \\ ghi}</code> +outputs <samp>abc defghi</samp> while <code>\makebox{abc def \par ghi}</code> +outputs <samp>abc def ghi</samp>, but neither go to a second line. To get +multiple lines see <ref label="_005cparbox"><xrefnodename>\parbox</xrefnodename></ref> and <ref label="minipage"><xrefnodename>minipage</xrefnodename></ref>. +</para> + +</section> +<node name="_005cfbox-_0026-_005cframebox" spaces=" "><nodename>\fbox & \framebox</nodename><nodenext automatic="on">\parbox</nodenext><nodeprev automatic="on">\mbox & \makebox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\fbox</code> & <code>\framebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="864" mergedindex="cp">\fbox</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="865" mergedindex="cp">\framebox</indexterm></findex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\fbox{<var>text</var>} +\framebox{<var>text</var>} +\framebox[<var>width</var>]{<var>text</var>} +\framebox[<var>width</var>][<var>position</var>]{<var>text</var>} +</pre></example> + +<para>Create a box with an enclosing frame, four lines surrounding the space. +These commands are the same as <code>\mbox</code> and <code>\makebox</code> except +for the frame (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></pxref>). The <code>\fbox</code> command is +robust, the <code>\framebox</code> command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\fbox{Warning! No work shown, no credit given.} +</pre></example> + +<noindent></noindent> +<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, <code>\fbox{...}</code> and +<code>\framebox{...}</code>, are roughly the same. As to the third and +fourth invocations, the optional arguments allow you to specify the box +width as <var>width</var> and the position of the text inside that box as +<var>position</var>. <xref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></xref> for the full description but +here is an example creating an empty box that is 1/4<dmn>in</dmn> wide. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\setlength{\fboxsep}{0pt}\framebox[0.25in]{\strut}} +</pre></example> + +<noindent></noindent> +<para>The <code>\strut</code> inserts a vertical height of <code>\baselineskip</code> +(<pxref label="_005cstrut"><xrefnodename>\strut</xrefnodename></pxref>). +</para> +<para>These parameters determine the frame layout. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="fbox-framebox-fboxrule">fbox framebox fboxrule</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="866" mergedindex="cp">\fboxrule</indexterm>\fboxrule</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="867" mergedindex="cp">frame, line width</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="868" mergedindex="cp">frame rule width</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="654">\fboxrule</indexterm></cindex> +<para>The thickness of the lines around the enclosed box. The default is +0.2<dmn>pt</dmn>. Change it with a command such as +<code>\setlength{\fboxrule}{0.8pt}</code> (<pxref label="_005csetlength"><xrefnodename>\setlength</xrefnodename></pxref>). +</para> +<anchor name="fbox-framebox-fboxsep">fbox framebox fboxsep</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="869" mergedindex="cp">\fboxsep</indexterm>\fboxsep</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="870" mergedindex="cp">frame, separation from contents</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="655">\fboxsep</indexterm></cindex> +<para>The distance from the frame to the enclosed box. The default is 3<dmn>pt</dmn>. +Change it with a command such as <code>\setlength{\fboxsep}{0pt}</code> +(<pxref label="_005csetlength"><xrefnodename>\setlength</xrefnodename></pxref>). Setting it to 0<dmn>pt</dmn> is useful sometimes: +this will put a frame around the picture with no white border. +</para> +<example endspaces=" "> +<pre xml:space="preserve">{\setlength{\fboxsep}{0pt} + \framebox{% + \includegraphics[width=0.5\textwidth]{prudence.jpg}}} +</pre></example> + +<noindent></noindent> +<para>The extra curly braces keep the effect of the <code>\setlength</code> local. +</para> +</tableitem></tableentry></ftable> + +<para>As with <code>\mbox</code> and <code>\makebox</code>, &latex; will not break lines +in <var>text</var>. But this example has &latex; break lines to make a +paragraph, and then frame the result. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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}} +</pre></example> + +<para><xref label="Colored-boxes"><xrefnodename>Colored boxes</xrefnodename></xref> for colors other than black and white. +</para> +<para>The <code>picture</code> environment has a version of this command where the +units depend on <code>picture</code>&textrsquo;s <code>\unitlength</code> (<pxref label="_005cframebox-_0028picture_0029"><xrefnodename>\framebox +(picture)</xrefnodename></pxref>). +</para> + +</section> +<node name="_005cparbox" spaces=" "><nodename>\parbox</nodename><nodenext automatic="on">\raisebox</nodenext><nodeprev automatic="on">\fbox & \framebox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\parbox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="871" mergedindex="cp">\parbox</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="656">paragraph mode</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="657">paragraph, in a box</indexterm></cindex> + +<para>Synopses, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\parbox{<var>width</var>}{<var>contents</var>} +\parbox[<var>position</var>]{<var>width</var>}{<var>contents</var>} +\parbox[<var>position</var>][<var>height</var>]{<var>width</var>}{<var>contents</var>} +\parbox[<var>position</var>][<var>height</var>][<var>inner-pos</var>]{<var>width</var>}{<var>contents</var>} +</pre></example> + +<para>Produce a box of text that is <var>width</var> wide. Use this command to make +a box of small pieces of text, of a single paragraph. This command is +fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>The <var>contents</var> are processed in a text mode (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>) so +&latex; will break lines to make a paragraph. But it won&textrsquo;t make +multiple paragraphs; for that, use a <code>minipage</code> environment +(<pxref label="minipage"><xrefnodename>minipage</xrefnodename></pxref>). +</para> +<para>The options for <code>\parbox</code> (except for <var>contents</var>) are the same +as those for <code>minipage</code>. For convenience a summary of the options +is here but see <ref label="minipage"><xrefnodename>minipage</xrefnodename></ref> for a complete description. +</para> +<para>There are two required arguments. The <var>width</var> is a rigid length +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). It sets the width of the box into which &latex; +typesets <var>contents</var>. The <var>contents</var> is the text that is placed +in that box. It should not have any paragraph-making components. +</para> +<para>There are three optional arguments, <var>position</var>, <var>height</var>, and +<var>inner-pos</var>. The <var>position</var> gives the vertical alignment of the +<code>parbox</code> with respect to the surrounding material. The possible +values are <code>c</code> or <code>m</code> to make the vertical center of the +<code>parbox</code> lines up with the center of the adjacent line (this is the +default), or <code>t</code> to match the top line of the <code>parbox</code> with +the baseline of the surrounding material, or <code>b</code> to match the +bottom line. +</para> +<para>The optional argument <var>height</var> overrides the natural height of the +box. +</para> +<para>The optional argument <var>inner-pos</var> controls the placement of +<var>content</var> inside the <code>parbox</code>. Its default is the value of +<var>position</var>. Its possible values are: <code>t</code> to put the +<var>content</var> at the top of the box, <code>c</code> to put it in the vertical +center, <code>b</code> to put it at the bottom of the box, and <code>s</code> to +stretch it out vertically (for this, the text must contain vertically +stretchable space). +</para> +</section> +<node name="_005craisebox" spaces=" "><nodename>\raisebox</nodename><nodenext automatic="on">\sbox & \savebox</nodenext><nodeprev automatic="on">\parbox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\raisebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="872" mergedindex="cp">\raisebox</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\raisebox{<var>distance</var>}{<var>text</var>} +\raisebox{<var>distance</var>}[<var>height</var>]{<var>text</var>} +\raisebox{<var>distance</var>}[<var>height</var>][<var>depth</var>]{<var>text</var>} +</pre></example> + +<para>Raise or lower <var>text</var>. This command is fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This example makes a command for the restriction of a function by +lowering the vertical bar symbol. +</para> +<!-- c credit: egreg https://tex.stackexchange.com/a/278631/121234 --> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand\restricted[1]{\raisebox{-.5ex}{$|$}_{#1}} +$f\restricted{A}$ +</pre></example> + +<para>The first mandatory argument <var>distance</var> specifies how far to raise +the second mandatory argument <var>text</var>. This is a rigid length +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). If it is negative then it lowers <var>text</var>. The +<var>text</var> is processed in LR mode so it cannot contain line breaks +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). +</para> +<para>The optional arguments <var>height</var> and <var>depth</var> are dimensions. If +they are specified, they override the natural height and depth of the +box &latex; gets by typesetting <var>text</var>. +</para> +<anchor name="raisebox-depth">raisebox depth</anchor> +<anchor name="raisebox-height">raisebox height</anchor> +<anchor name="raisebox-width">raisebox width</anchor> +<anchor name="raisebox-totalheight">raisebox totalheight</anchor> +<para>In the arguments <var>distance</var>, <var>height</var>, and <var>depth</var> you can +use the following lengths that refer to the dimension of the box that +&latex; gets on typesetting <var>text</var>: <code>\depth</code>, <code>\height</code>, +<code>\width</code>, <code>\totalheight</code> (this is the box&textrsquo;s height plus its +depth). +</para> +<para>This will align two graphics on their top (<pxref label="Graphics"><xrefnodename>Graphics</xrefnodename></pxref>). +</para> +<!-- c credit: FAQ https://texfaq.org/FAQ-topgraph --> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The first <code>\height</code> is the height of <file>lion.png</file> while the +second is the height of <file>meta.png</file>. +</para> + +</section> +<node name="_005csbox-_0026-_005csavebox" spaces=" "><nodename>\sbox & \savebox</nodename><nodenext automatic="on">lrbox</nodenext><nodeprev automatic="on">\raisebox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\sbox</code> & <code>\savebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="873" mergedindex="cp">\sbox</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="874" mergedindex="cp">\savebox</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="658">box, save</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\sbox{<var>box-cmd</var>}{<var>text</var>} +\savebox{<var>box-cmd</var>}{<var>text</var>} +\savebox{<var>box-cmd</var>}[<var>width</var>]{<var>text</var>} +\savebox{<var>box-cmd</var>}[<var>width</var>][<var>pos</var>]{<var>text</var>} +</pre></example> + +<para>Typeset <var>text</var> just as with <code>\makebox</code> (<pxref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & +\makebox</xrefnodename></pxref>) except that &latex; does not output it but instead saves it +in a storage bin named <var>box-cmd</var>. The bin name <var>box-cmd</var> begins +with a backslash, <code>\</code>. You must have previously allocated the bin +<var>box-cmd</var> with <code>\newsavebox</code> (<pxref label="_005cnewsavebox"><xrefnodename>\newsavebox</xrefnodename></pxref>).The +<code>\sbox</code> command is robust while <code>\savebox</code> is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>This creates and uses a bin. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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. +</pre></example> + +<noindent></noindent> +<para>One advantage of using and reusing a bin over a <code>\newcommand</code> is +efficiency, that &latex; need not repeatedly retypeset the contents. +See the example below. +</para> +<para>The first two command invocations, +<code>\sbox{<var>box-cmd</var>}{<var>text</var>}</code> and +<code>\savebox{<var>box-cmd</var>}{<var>text</var>}</code>, are roughly equivalent. +As to the third and fourth, the optional arguments allow you to specify +the box width as <var>width</var>, and the position of the text inside that +box as <var>position</var>. <xref label="_005cmbox-_0026-_005cmakebox"><xrefnodename>\mbox & \makebox</xrefnodename></xref> for the full +description. +</para> +<para>In the <code>\sbox</code> and <code>\savebox</code> commands the <var>text</var> is +typeset in LR mode so it does not have line breaks (<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). If +you use these then &latex; doesn&textrsquo;t give you an error but it ignores +what you want: if you enter <code>\sbox{\newbin}{test \\ test}</code> and +<code>\usebox{\newbin}</code> then you get <samp>testtest</samp>, while if you +enter <code>\sbox{\newbin}{test \par test}</code> and +<code>\usebox{\newbin}</code> then you get <samp>test test</samp>, but no error or +warning. To fix this use a <code>\parbox</code> or <code>minipage</code> as here. +</para> +<!-- c credit: egreg https://tex.stackexchange.com/a/41668/121234 --> +<example endspaces=" "> +<pre xml:space="preserve">\savebox{\abin}{% + \begin{minipage}{\linewidth} + \begin{enumerate} + \item First item + \item Second item + \end{enumerate} + \end{minipage}} + ... +\usebox{\abin} +</pre></example> + +<para>As an example of the efficiency of reusing a bin&textrsquo;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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The <code>picture</code> environment is good for fine-tuning the placement. +</para> +<para>If the bin has not already been defined then you get something like +<samp>Undefined control sequence. <argument> \nobin</samp>. +</para> + +</section> +<node name="lrbox" spaces=" "><nodename>lrbox</nodename><nodenext automatic="on">\usebox</nodenext><nodeprev automatic="on">\sbox & \savebox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>lrbox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="875" mergedindex="cp">lrbox</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{lrbox}{<var>box-cmd</var>} + <var>text</var> +\end{lrbox} +</pre></example> + +<para>The <var>text</var> inside the environment is saved in the bin +<code><var>box-cmd</var></code>. The <var>box-cmd</var> must begin with a +backslash. You must create this bin in advance with <code>\newsavebox</code> +(<pxref label="_005cnewsavebox"><xrefnodename>\newsavebox</xrefnodename></pxref>). This is the environment form of the <code>\sbox</code> +and <code>\savebox</code> commands, and is equivalent to them. <xref label="_005csbox-_0026-_005csavebox"><xrefnodename>\sbox & +\savebox</xrefnodename></xref> for the full information. +</para> +<para>In this example the environment is convenient for entering the +<code>tabular</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newsavebox{\jhbin} +\begin{lrbox}{\jhbin} + \begin{tabular}{c} + \includegraphics[height=1in]{jh.png} \\ + Jim Hef{}feron + \end{tabular} +\end{lrbox} + ... +\usebox{\jhbin} +</pre></example> + + +</section> +<node name="_005cusebox" spaces=" "><nodename>\usebox</nodename><nodeprev automatic="on">lrbox</nodeprev><nodeup automatic="on">Boxes</nodeup></node> +<section spaces=" "><sectiontitle><code>\usebox</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="876" mergedindex="cp">\usebox</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="659">box, use saved box</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usebox{<var>box-cmd</var>} +</pre></example> + +<para>Produce the box most recently saved in the bin <var>box-cmd</var> by the +commands <code>\sbox</code> or <code>\savebox</code>, or the <code>lrbox</code> +environment. <xref label="_005csbox-_0026-_005csavebox"><xrefnodename>\sbox & \savebox</xrefnodename></xref> for more information and examples. +(Note that <var>box-cmd</var> starts with a backslash.) This command is +robust (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> + +</section> +</chapter> +<node name="Color" spaces=" "><nodename>Color</nodename><nodenext automatic="on">Graphics</nodenext><nodeprev automatic="on">Boxes</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Color</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="660">color</indexterm></cindex> + +<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 +<code>\usepackage{color}</code> in your document preamble to use the +commands described here. +</para> +<para>Many other packages also supplement &latex;&textrsquo;s color abilities. +Particularly worth mentioning is <file>xcolor</file>, which is widely used and +significantly extends the capabilities described here, including adding +<samp>HTML</samp> and <samp>Hsb</samp> color models. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Color package options</menunode><menudescription><pre xml:space="preserve">Options when you load the standard package. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Color models</menunode><menudescription><pre xml:space="preserve">How colors are represented. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Commands for color</menunode><menudescription><pre xml:space="preserve">The available commands. +</pre></menudescription></menuentry></menu> + + +<node name="Color-package-options" spaces=" "><nodename>Color package options</nodename><nodenext automatic="on">Color models</nodenext><nodeup automatic="on">Color</nodeup></node> +<section spaces=" "><sectiontitle><code>color</code> package options</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="661">color package options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="662">options, color package</indexterm></cindex> + +<para>Synopsis (must be in the document preamble): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage[<var>comma-separated option list</var>]{color} +</pre></example> + +<para>When you load the <file>color</file> package there are two kinds of available +options. +</para> +<para>The first specifies the <dfn>printer driver</dfn>. &latex; doesn&textrsquo;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&textrsquo;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: <file>dvipdfmx</file>, <file>dvips</file>, +<file>dvisvgm</file>, <file>luatex</file>, <file>pdftex</file>, <file>xetex</file>. The two +<file>xdvi</file> and <file>oztex</file> are essentially aliases for <file>dvips</file> +(and <file>xdvi</file> is monochrome). Ones that should not be used for new +systems are: <file>dvipdf</file>, <file>dvipdfm</file>, <file>dviwin</file>, +<file>dvipsone</file>, <file>emtex</file>, <file>pctexps</file>, <file>pctexwin</file>, +<file>pctexhp</file>, <file>pctex32</file>, <file>truetex</file>, <file>tcidvi</file>, +<file>vtex</file> (and <file>dviwindo</file> is an alias for <file>dvipsone</file>). +</para> +<para>The second kind of options, beyond the drivers, are below. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">monochrome</itemformat></item> +</tableterm><tableitem><para>Disable the color commands, so that they do not generate errors but do +not generate color either. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">dvipsnames</itemformat></item> +</tableterm><tableitem><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 <file>dvips</file> driver, giving the option name. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">nodvipsnames</itemformat></item> +</tableterm><tableitem><para>Do not load that list of color names, saving &latex; a tiny amount of +memory space. +</para> +</tableitem></tableentry></table> + + +</section> +<node name="Color-models" spaces=" "><nodename>Color models</nodename><nodenext automatic="on">Commands for color</nodenext><nodeprev automatic="on">Color package options</nodeprev><nodeup automatic="on">Color</nodeup></node> +<section spaces=" "><sectiontitle>Color models</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="663">color models</indexterm></cindex> + +<para>A <dfn>color model</dfn> is a way of representing colors. &latex;&textrsquo;s +capabilities depend on the printer driver. However, the <file>pdftex</file>, +<file>xetex</file>, and <file>luatex</file> 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> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="color-models-cmyk">color models cmyk</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">cmyk</itemformat></item> +</tableterm><tableitem><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 name="color-models-gray">color models gray</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">gray</itemformat></item> +</tableterm><tableitem><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 name="color-models-rgb">color models rgb</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">rgb</itemformat></item> +</tableterm><tableitem><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 name="color-models-RGB">color models RGB</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">RGB</itemformat></item> +</tableterm><tableitem><para>(<file>pdftex</file>, <file>xetex</file>, <file>luatex</file> drivers) A comma-separated +list with three integers between 0 and 255, inclusive. This model is a +convenience for using <code>rgb</code> 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 <code>rgb</code> model by +dividing by 255. +</para> +<anchor name="color-models-named">color models named</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">named</itemformat></item> +</tableterm><tableitem><para>Colors are accessed by name, such as <samp>PrussianBlue</samp>. The list of +names depends on the driver, but all support the names <samp>black</samp>, +<samp>blue</samp>, <samp>cyan</samp>, <samp>green</samp>, <samp>magenta</samp>, <samp>red</samp>, +<samp>white</samp>, and <samp>yellow</samp> (See the <code>dvipsnames</code> option in +<ref label="Color-package-options"><xrefnodename>Color package options</xrefnodename></ref>). +</para> +</tableitem></tableentry></table> + + +</section> +<node name="Commands-for-color" spaces=" "><nodename>Commands for color</nodename><nodeprev automatic="on">Color models</nodeprev><nodeup automatic="on">Color</nodeup></node> +<section spaces=" "><sectiontitle>Commands for color</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="664">color package commands</indexterm></cindex> + +<para>These are the commands available with the <file>color</file> package. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Define colors</menunode><menudescription><pre xml:space="preserve">Give a color a name. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Colored text</menunode><menudescription><pre xml:space="preserve">Text or rules in color. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Colored boxes</menunode><menudescription><pre xml:space="preserve">A box of color, to write over. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Colored pages</menunode><menudescription><pre xml:space="preserve">A whole page colored. +</pre></menudescription></menuentry></menu> + + +<node name="Define-colors" spaces=" "><nodename>Define colors</nodename><nodenext automatic="on">Colored text</nodenext><nodeup automatic="on">Commands for color</nodeup></node> +<subsection spaces=" "><sectiontitle>Define colors</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="665">color</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="666">define color</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="667">color, define</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\definecolor{<var>name</var>}{<var>model</var>}{<var>specification</var>} +</pre></example> + +<para>Give the name <var>name</var> to the color. For example, after this +</para> +<example endspaces=" "> +<pre xml:space="preserve">\definecolor{silver}{rgb}{0.75,0.75,0.74} +</pre></example> + +<noindent></noindent> +<para>you can use that color name with <code>Hi ho, +\textcolor{silver}{Silver}!</code>. +</para> +<para>This example gives the color a more abstract name, so it could change and +not be misleading. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex +\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}} +</pre></example> + +<para>Often a document&textrsquo;s colors are defined in the preamble, or in the class +or style, rather than in the document body. +</para> + +</subsection> +<node name="Colored-text" spaces=" "><nodename>Colored text</nodename><nodenext automatic="on">Colored boxes</nodenext><nodeprev automatic="on">Define colors</nodeprev><nodeup automatic="on">Commands for color</nodeup></node> +<subsection spaces=" "><sectiontitle>Colored text</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="668">color</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="669">colored text</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\textcolor{<var>name</var>}{...} +\textcolor[<var>color model</var>]{<var>color specification</var>}{...} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\color{<var>name</var>} +\color[<var>color model</var>]{<var>specification</var>} +</pre></example> + +<para>The affected text gets the color. This line +</para> +<example endspaces=" "> +<pre xml:space="preserve">\textcolor{magenta}{My name is Ozymandias, king of kings:} +Look on my works, ye Mighty, and despair! +</pre></example> + +<noindent></noindent> +<para>causes the first half to be in magenta while the rest is in black. You +can use a color declared with <code>\definecolor</code> in exactly the same +way that we just used the builtin color <samp>magenta</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0} +I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}. +</pre></example> + +<para>The two <code>\textcolor</code> and <code>\color</code> 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 <code>The moon is made of {\color{green} +green} cheese</code>, 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 <code>center</code> environment, +including the vertical and horizontal lines. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} \color{blue} + \begin{tabular}{l|r} + UL &UR \\ \hline + LL &LR + \end{tabular} +\end{center} +</pre></example> + +<para>You can use color in equations. A document might have this definition +in the preamble +</para> +<example endspaces=" "> +<pre xml:space="preserve">\definecolor{highlightcolor}{RGB}{225,15,0} +</pre></example> + +<noindent></noindent> +<para>and then contain this equation. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{equation} + \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a) +\end{equation} +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">Colors of \textcolor[rgb]{0.33,0.14,0.47}{Purple} and +{\color[rgb]{0.72,0.60,0.37} Gold} for the team. +</pre></example> + +<para>The format of <var>color specification </var> depends on the color model +(<pxref label="Color-models"><xrefnodename>Color models</xrefnodename></pxref>). For instance, while <code>rgb</code> takes three +numbers, <code>gray</code> takes only one. +</para> +<example endspaces=" "> +<pre xml:space="preserve">The selection was \textcolor[gray]{0.5}{grayed out}. +</pre></example> + +<para>Colors inside colors do not combine. Thus +</para> +<example endspaces=" "> +<pre xml:space="preserve">\textcolor{green}{kind of \textcolor{blue}{blue}} +</pre></example> + +<noindent></noindent> +<para>has a final word that is blue, not a combination of blue and green. +</para> +<!-- c xx address coloring a line of a table? --> + + +</subsection> +<node name="Colored-boxes" spaces=" "><nodename>Colored boxes</nodename><nodenext automatic="on">Colored pages</nodenext><nodeprev automatic="on">Colored text</nodeprev><nodeup automatic="on">Commands for color</nodeup></node> +<subsection spaces=" "><sectiontitle>Colored boxes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="670">color</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="671">colored boxes</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="672">box, colored</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\colorbox{<var>name</var>}{...} +\colorbox[<var>model name</var>]{<var>box background color</var>}{...} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\fcolorbox{<var>frame color</var>}{<var>box background color</var>}{...} +\fcolorbox[<var>model name</var>]{<var>frame color</var>}{<var>box background color</var>}{...} +</pre></example> + +<para>Make a box with the stated background color. The <code>\fcolorbox</code> +command puts a frame around the box. For instance this +</para> +<example endspaces=" "> +<pre xml:space="preserve">Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}} +</pre></example> + +<noindent></noindent> +<para>makes a cyan-colored box that is five centimeters long and gets its +depth and height from the <code>\strut</code> (so the depth is +<code>-.3\baselineskip</code> and the height is <code>\baselineskip</code>). This +puts white text on a blue background. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\colorbox{blue}{\textcolor{white}{Welcome to the machine.}} +</pre></example> + +<para>The <code>\fcolorbox</code> commands use the same parameters as <code>\fbox</code> +(<pxref label="_005cfbox-_0026-_005cframebox"><xrefnodename>\fbox & \framebox</xrefnodename></pxref>), <code>\fboxrule</code> and <code>\fboxsep</code>, to +set the thickness of the rule and the boundary between the box interior +and the surrounding rule. &latex;&textrsquo;s defaults are <code>0.4pt</code> and +<code>3pt</code>, 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> +<example endspaces=" "> +<pre xml:space="preserve">{\setlength{\fboxrule}{0.8pt} +\fcolorbox{black}{red}{Under no circumstances turn this knob.}} +</pre></example> + + +</subsection> +<node name="Colored-pages" spaces=" "><nodename>Colored pages</nodename><nodeprev automatic="on">Colored boxes</nodeprev><nodeup automatic="on">Commands for color</nodeup></node> +<subsection spaces=" "><sectiontitle>Colored pages</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="673">color</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="674">colored page</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="675">page, colored</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="676">background, colored</indexterm></cindex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\pagecolor{<var>name</var>} +\pagecolor[<var>color model</var>]{<var>color specification</var>} +\nopagecolor +</pre></example> + +<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 <pxref label="Colored-text"><xrefnodename>Colored text</xrefnodename></pxref>. The third returns the background to normal, +which is a transparent background. (If that is not supported use +<code>\pagecolor{white}</code>, although that will make a white background +rather than the default transparent background.) +</para> +<example endspaces=" "> +<pre xml:space="preserve"> ... +\pagecolor{cyan} + ... +\nopagecolor +</pre></example> + + +</subsection> +</section> +</chapter> +<node name="Graphics" spaces=" "><nodename>Graphics</nodename><nodenext automatic="on">Special insertions</nodenext><nodeprev automatic="on">Color</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Graphics</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="677">graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="678">graphics package</indexterm></cindex> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\include{graphicx} % goes in the preamble + ... +\includegraphics[width=0.5\linewidth]{plot.pdf} +</pre></example> + +<para>To use the commands described here your document preamble must contain +either <code>\usepackage{graphicx}</code> or +<code>\usepackage{graphics}</code>. Most of the time, <file>graphicx</file> 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 <samp>draw a circle with this radius and that +center</samp>. 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 <code>picture</code> environment +(<pxref label="picture"><xrefnodename>picture</xrefnodename></pxref>) 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> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Graphics package options</menunode><menudescription><pre xml:space="preserve">Options when you load the package. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Graphics package configuration</menunode><menudescription><pre xml:space="preserve">Where to look for files, which file types. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Commands for graphics</menunode><menudescription><pre xml:space="preserve">The available commands. +</pre></menudescription></menuentry></menu> + + +<node name="Graphics-package-options" spaces=" "><nodename>Graphics package options</nodename><nodenext automatic="on">Graphics package configuration</nodenext><nodeup automatic="on">Graphics</nodeup></node> +<section spaces=" "><sectiontitle><code>graphics</code> package options</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="679">graphics package options</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="680">options, graphics package</indexterm></cindex> + +<para>Synopsis (must be in the document preamble): +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage[<var>comma-separated option list</var>]{graphics} +</pre></example> + +<noindent></noindent> +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage[<var>comma-separated option list</var>]{graphicx} +</pre></example> + +<para>The <code>graphicx</code> package has a format for optional arguments to the +<code>\includegraphics</code> command that is convenient (it is the key-value +format), so it is the better choice for new documents. When you load +the <file>graphics</file> or <file>graphicx</file> package with <code>\usepackage</code> +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 +<dfn>printer driver</dfn> file. Normally you should not specify the driver +option in the document, and instead rely on your system&textrsquo;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: <file>dvipdfmx</file>, <file>dvips</file>, <file>dvisvgm</file>, <file>luatex</file>, +<file>pdftex</file>, <file>xetex</file>. The two <file>xdvi</file> and <file>oztex</file> are +essentially aliases for <file>dvips</file> (and <file>xdvi</file> is monochrome). +Ones that should not be used for new systems are: <file>dvipdf</file>, +<file>dvipdfm</file>, <file>dviwin</file>, <file>dvipsone</file>, <file>emtex</file>, +<file>pctexps</file>, <file>pctexwin</file>, <file>pctexhp</file>, <file>pctex32</file>, +<file>truetex</file>, <file>tcidvi</file>, <file>vtex</file> (and <file>dviwindo</file> is an +alias for <file>dvipsone</file>). These are stored in files with a +<file>.def</file> extension, such as <file>pdftex.def</file>. +</para> +<para>The second kind of options are below. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">demo</itemformat></item> +</tableterm><tableitem><para>Instead of an image file, &latex; puts in a 150 pt by 100 pt +rectangle (unless another size is specified in the +<code>\includegraphics</code> command). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">draft</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">final</itemformat></item> +</tableterm><tableitem><para>(Default) Override any previous <code>draft</code> option, so that the +document shows the contents of the graphic files. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">hiderotate</itemformat></item> +</tableterm><tableitem><para>Do not show rotated text. (This allows for the possibility that a +previewer does not have the capability to rotate text.) +<!-- c what does it show? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">hidescale</itemformat></item> +</tableterm><tableitem><para>Do not show scaled text. (This allows for the possibility that a +previewer does not have the capability to scale.) +<!-- c what does it show? --> +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">hiresbb</itemformat></item> +</tableterm><tableitem><para>In a PS or EPS file the graphic size may be specified in two ways. The +<code>%%BoundingBox</code> 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 <code>%%HiResBoundingBox</code> lines. This +option has &latex; to read the size from the latter. +</para> +</tableitem></tableentry></table> + + +</section> +<node name="Graphics-package-configuration" spaces=" "><nodename>Graphics package configuration</nodename><nodenext automatic="on">Commands for graphics</nodenext><nodeprev automatic="on">Graphics package options</nodeprev><nodeup automatic="on">Graphics</nodeup></node> +<section spaces=" "><sectiontitle><code>graphics</code> package configuration</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="681">graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="682">graphics package</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="683">configuration, graphics package</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="684">EPS files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="685">JPEG files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="686">JPG files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="687">PDF graphic files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="688">PNG files</indexterm></cindex> + +<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 <file>grfguide.pdf</file>, or the &latex; source, or your +&tex; distribution&textrsquo;s documentation. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\graphicspath</menunode><menudescription><pre xml:space="preserve">Directories to search. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\DeclareGraphicsExtensions</menunode><menudescription><pre xml:space="preserve">File types, such as JPG or EPS. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\DeclareGraphicsRule</menunode><menudescription><pre xml:space="preserve">How to handle file types. +</pre></menudescription></menuentry></menu> + + +<node name="_005cgraphicspath" spaces=" "><nodename>\graphicspath</nodename><nodenext automatic="on">\DeclareGraphicsExtensions</nodenext><nodeup automatic="on">Graphics package configuration</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\graphicspath</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="877" mergedindex="cp">\graphicspath</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\graphicspath{<var>list of dir names inside curly brackets</var>} +</pre></example> + +<para>Declare a list of directories to search for graphics files. This allows +you to later say something like <code>\includegraphics{lion.png}</code> +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 +<file>pix</file>, and then <file>../pix</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{graphicx} % or graphics; put in preamble + ... +\graphicspath{ {pix/} {../pix/} } +</pre></example> + +<para>The <code>\graphicspath</code> declaration is optional. If you don&textrsquo;t include +it then &latex;&textrsquo;s default is to search all of the places that it +usually looks for a file (it uses &latex;&textrsquo;s <code>\input&arobase;path</code>). 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 +<samp><code>{pix}</code></samp>. Do this even if there is only one directory. +Each directory name must end in a forward slash, <file>/</file>. 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 <code>{"my docs/"}</code>. Getting one of these rules wrong +will cause &latex; to report <code>Error: File `<var>filename</var>' not +found</code>. +</para> +<para>Basically, the algorithm is that with this example, after looking in the +current directory, +</para> +<example endspaces=" "> +<pre xml:space="preserve">\graphicspath{ {pix/} {../pix/} } +... +\usepackage{lion.png} +</pre></example> + +<noindent></noindent> +<para>for each of the listed directories, &latex; concatenates it with the +file name and searches for the result, checking for <file>pix/lion.png</file> +and then <file>../pix/lion.png</file>. This algorithm means that the +<code>\graphicspath</code> command does not recursively search subdirectories: +if you issue <code>\graphicspath{{a/}}</code> and the graphic is in +<file>a/b/lion.png</file> then &latex; will not find it. It also means that +you can use absolute paths such as +<code>\graphicspath{{/home/jim/logos/}}</code> or +<code>\graphicspath{{C:/Users/Albert/Pictures/}}</code>. However, using +these means that the document is not portable. (You could preserve +portability by adjusting your &tex; system settings configuration file +parameter <code>TEXINPUTS</code>; see the documentation of your system.) +</para> +<para>You can use <code>\graphicspath</code> anywhere in the document. You can use +it more than once. Show its value with +<code>\makeatletter\typeout{\Ginput&arobase;path}\makeatother</code>. +</para> +<para>The directories are taken with respect to the base file. That is, +suppose that you are working on a document based on <file>book/book.tex</file> +and it contains <code>\include{chapters/chap1}</code>. If in +<file>chap1.tex</file> you put <code>\graphicspath{{plots/}}</code> then +&latex; will not search for graphics in <file>book/chapters/plots</file>, but +instead in <file>book/plots</file>. +</para> + +</subsection> +<node name="_005cDeclareGraphicsExtensions" spaces=" "><nodename>\DeclareGraphicsExtensions</nodename><nodenext automatic="on">\DeclareGraphicsRule</nodenext><nodeprev automatic="on">\graphicspath</nodeprev><nodeup automatic="on">Graphics package configuration</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\DeclareGraphicsExtensions</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="878" mergedindex="cp">\DeclareGraphicsExtensions</indexterm></findex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareGraphicsExtensions{<var>comma-separated list of file extensions</var>} +</pre></example> + +<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 +<code>\includegraphics{functionplot}</code>. +</para> +<para>In this example, &latex; will find files in the PNG format before PDF +files. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareGraphicsExtensions{.png,PNG,.pdf,.PDF} + ... +\includegraphics{lion} % will find <file>lion.png</file> before <file>lion.pdf</file> +</pre></example> + +<noindent></noindent> +<para>Because the file name <file>lion</file> does not have a period, &latex; uses +the extension list. For each directory in the graphics path +(<pxref label="_005cgraphicspath"><xrefnodename>\graphicspath</xrefnodename></pxref>), &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 <samp>! LaTeX Error: File `<file>lion</file>' +not found</samp>. 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 <code>\DeclareGraphicsExtensions</code> in +your document; the printer driver has a sensible default. For example, +the most recent <file>pdftex.def</file> has this extension list. +</para> +<example endspaces=" "> +<pre xml:space="preserve">.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2 +</pre></example> + +<para>You can use this command anywhere in the document. You can use it more +than once. Show its value with +<code>\makeatletter\typeout{\Gin&arobase;extensions}\makeatother</code>. +</para> + +</subsection> +<node name="_005cDeclareGraphicsRule" spaces=" "><nodename>\DeclareGraphicsRule</nodename><nodeprev automatic="on">\DeclareGraphicsExtensions</nodeprev><nodeup automatic="on">Graphics package configuration</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\DeclareGraphicsRule</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="879" mergedindex="cp">\DeclareGraphicsRule</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareGraphicsRule{<var>extension</var>}{<var>type</var>}{<var>size-file extension</var>}{<var>command</var>} +</pre></example> + +<para>Declare how to handle graphic files whose names end in <var>extension</var>. +</para> +<para>This example declares that all files with names have the form +<file>filename-without-dot.mps</file> will be treated as output from MetaPost, +meaning that the printer driver will use its MetaPost-handling code to +input the file. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareGraphicsRule{.mps}{mps}{.mps}{} +</pre></example> + +<para>This +</para> +<example endspaces=" "> +<pre xml:space="preserve">\DeclareGraphicsRule{*}{mps}{*}{} +</pre></example> + +<noindent></noindent> +<para>tells &latex; that it should handle as MetaPost output any file with an +extension not covered by another rule, so it covers <file>filename.1</file>, +<file>filename.2</file>, etc. +</para> +<para>This describes the four arguments. +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">extension</itemformat></item> +</tableterm><tableitem><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, +<code>*</code>, to denote the default behaviour for all undeclared extensions. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">type</itemformat></item> +</tableterm><tableitem><para>The type of file involved. This type is a string that must be defined +in the printer driver. For instance, files with extensions <file>.ps</file>, +<file>.eps</file>, or <file>.ps.gz</file> may all be classed as type <code>eps</code>. +All files of the same type will be input with the same internal command +by the printer driver. For example, the file types that <file>pdftex</file> +recognizes are: <code>jpg</code>, <code>jbig2</code>, <code>mps</code>, <code>pdf</code>, +<code>png</code>, <code>tif</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">size-file extension</itemformat></item> +</tableterm><tableitem><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 <var>extension</var> +but it may be different. +</para> +<para>As an example, consider a PostScript graphic. To make it smaller, it +might be compressed into a <file>.ps.gz</file> file. Compressed files are not +easily read by &latex; so you can put the bounding box information in a +separate file. If <var>size-file extension</var> is empty then you must +specify size information in the arguments of <code>\includegraphics</code>. +</para> +<para>If the driver file has a procedure for reading size files for +<code>type</code> then that will be used, otherwise it will use the procedure +for reading <file>.eps</file> files. (Thus you may specify the size of bitmap +files in a file with a PostScript style <code>%%BoundingBox</code> line if no +other format is available.) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">command</itemformat></item> +</tableterm><tableitem><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, +<code>\DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c +#1}</code> specifies that any file with the extension <file>.eps.gz</file> should +be treated as an <code>eps</code> file, with the BoundingBox information +stored in the file with extension <file>.eps.bb</file>, and that the command +<code>gunzip -c</code> 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> +</tableitem></tableentry></table> + +</subsection> +</section> +<node name="Commands-for-graphics" spaces=" "><nodename>Commands for graphics</nodename><nodeprev automatic="on">Graphics package configuration</nodeprev><nodeup automatic="on">Graphics</nodeup></node> +<section spaces=" "><sectiontitle>Commands for graphics</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="689">graphics package commands</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="690">commands, graphics package</indexterm></cindex> + +<para>These are the commands available with the <file>graphics</file> and +<file>graphicx</file> packages. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\includegraphics</menunode><menudescription><pre xml:space="preserve">Using a graphic in your document. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\rotatebox</menunode><menudescription><pre xml:space="preserve">Rotating boxes, including graphics. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\scalebox</menunode><menudescription><pre xml:space="preserve">Scaling boxes, including graphics. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\resizebox</menunode><menudescription><pre xml:space="preserve">Scaling boxes, including graphics, to a set size. +</pre></menudescription></menuentry></menu> + + +<node name="_005cincludegraphics" spaces=" "><nodename>\includegraphics</nodename><nodenext automatic="on">\rotatebox</nodenext><nodeup automatic="on">Commands for graphics</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\includegraphics</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="691">graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="692">graphics package</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="693">including graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="694">importing graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="695">EPS files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="696">JPEG files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="697">JPG files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="698">PDF graphic files</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="699">PNG files</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="880" mergedindex="cp">\includegraphics</indexterm></findex> + +<para>Synopses for <file>graphics</file> package: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics{<var>filename</var>} +\includegraphics[<var>urx</var>,<var>ury</var>]{<var>filename</var>} +\includegraphics[<var>llx</var>,<var>lly</var>][<var>urx</var>,<var>ury</var>]{<var>filename</var>} +\includegraphics*{<var>filename</var>} +\includegraphics*[<var>urx</var>,<var>ury</var>]{<var>filename</var>} +\includegraphics*[<var>llx</var>,<var>lly</var>][<var>urx</var>,<var>ury</var>]{<var>filename</var>} +</pre></example> + +<para>Synopses for <file>graphicx</file> package: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics{<var>filename</var>} +\includegraphics[<var>key-value list</var>]{<var>filename</var>} +\includegraphics*{<var>filename</var>} +\includegraphics*[<var>key-value list</var>]{<var>filename</var>} +</pre></example> + +<para>Include a graphics file. The starred form <code>\includegraphics*</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{graphicx} % in preamble + ... +\begin{center} + \includegraphics{plot.pdf} +\end{center} +</pre></example> + +<noindent></noindent> +<para>will incorporate into the document the graphic in <file>plot.pdf</file>, +centered and at its nominal size. You can also give a path to the file, +as with <code>\includegraphics{graphics/plot.pdf}</code>. To specify a list +of locations to search for the file, <pxref label="_005cgraphicspath"><xrefnodename>\graphicspath</xrefnodename></pxref>. +</para> +<para>If your filename includes spaces then put it in double quotes. An example +is <code>\includegraphics{"sister picture.jpg"}</code>. +</para> +<para>The <code>\includegraphics{<var>filename</var>}</code> command decides on the +type of graphic by splitting <var>filename</var> on the first dot. You can +use <var>filename</var> with no dot, as in <code>\includegraphics{turing}</code> +and then &latex; tries a sequence of extensions such as <code>.png</code> and +<code>.pdf</code> until it finds a file with that extension +(<pxref label="_005cDeclareGraphicsExtensions"><xrefnodename>\DeclareGraphicsExtensions</xrefnodename></pxref>). +</para> +<para>If your file name contains dots before the extension then you can hide +them with curly braces, as in +<code>\includegraphics{{plot.2018.03.12.a}.pdf}</code>. Or, if you use +the <file>graphicx</file> package then you can use the options <code>type</code> and +<code>ext</code>; see below. This and other filename issues are also handled +with the package <file>grffile</file>. +</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 +(<pxref label="figure"><xrefnodename>figure</xrefnodename></pxref>). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{figure} + \centering + \includegraphics[width=3cm]{lungxray.jpg} + \caption{The evidence is overwhelming: don't smoke.} \label{fig:xray} +\end{figure} +</pre></example> + +<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> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{caption} % in preamble + ... +\begin{center} + \includegraphics{pix/nix.png} + \captionof{figure}{The spirit of the night} \label{pix:nix} % optional +\end{center} +</pre></example> + +<para>This example puts a box with a graphic side by side with one having +text, with the two vertically centered. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand*{\vcenteredhbox}[1]{\begin{tabular}{&arobase;{}c&arobase;{}}#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} +</pre></example> + +<para>If you use the <file>graphics</file> package then the only options involve the +size of the graphic (but see <ref label="_005crotatebox"><xrefnodename>\rotatebox</xrefnodename></ref> and <ref label="_005cscalebox"><xrefnodename>\scalebox</xrefnodename></ref>). +When one optional argument is present then it is +<code>[<var>urx</var>,<var>ury</var>]</code> and it gives the coordinates of the top +right corner of the image, as a pair of &tex; dimensions (<pxref label="Units-of-length"><xrefnodename>Units +of length</xrefnodename></pxref>). If the units are omitted they default to <code>bp</code>. 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 +<code>[<var>llx</var>,<var>lly</var>]</code>, specifying the coordinates of the image&textrsquo;s +lower left. Thus, <code>\includegraphics[1in,0.618in]{...}</code> 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 <file>graphicx</file> package gives you many more options. Specify them +in a key-value form, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + \includegraphics[width=1in,angle=90]{lion} + \hspace{2em} + \includegraphics[angle=90,width=1in]{lion} +\end{center} +</pre></example> + +<noindent></noindent> +<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&textrsquo;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> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="includegraphics-width">includegraphics width</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">width</itemformat></item> +</tableterm><tableitem><para>The graphic will be shown so its bounding box is this width. An example +is <code>\includegraphics[width=1in]{plot}</code>. You can use the standard +&tex; dimensions (<pxref label="Units-of-length"><xrefnodename>Units of length</xrefnodename></pxref>) and also convenient is +<code>\linewidth</code>, or in a two-column document, <code>\columnwidth</code> +(<pxref label="Page-layout-parameters"><xrefnodename>Page layout parameters</xrefnodename></pxref>). An example is that by using the +<file>calc</file> package you can make the graphic be 1 cm narrow than +the width of the text with +<code>\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">height</itemformat></item> +</tableterm><tableitem><anchor name="includegraphics-height">includegraphics height</anchor> +<para>The graphic will be shown so its bounding box is this height. You can +use the standard &tex; dimensions (<pxref label="Units-of-length"><xrefnodename>Units of length</xrefnodename></pxref>), and also +convenient are <code>\pageheight</code> and <code>\textheight</code> (<pxref label="Page-layout-parameters"><xrefnodename>Page +layout parameters</xrefnodename></pxref>). For instance, the command +<code>\includegraphics[height=0.25\textheight]{godel}</code> will make the +graphic a quarter of the height of the text area. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">totalheight</itemformat></item> +</tableterm><tableitem><anchor name="includegraphics-totalheght">includegraphics totalheght</anchor> +<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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">keepaspectratio</itemformat></item> +</tableterm><tableitem><anchor name="includegraphics-keepaspectratio">includegraphics keepaspectratio</anchor> +<para>If set to <code>true</code>, or just specified as here +</para> +<example endspaces=" "> +<pre xml:space="preserve"><code>\includegraphics[...,keepaspectratio,...]{...}</code> +</pre></example> + +<noindent></noindent> +<para>and you give as options both <code>width</code> and <code>height</code> (or +<code>totalheight</code>), 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 <code>width</code> nor taller than <code>height</code> (or +<code>totalheight</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">scale</itemformat></item> +</tableterm><tableitem><para>Factor by which to scale the graphic. To make a graphic twice its +nominal size, enter <code>\includegraphics[scale=2.0]{...}</code>. This +number may be any value; a number between 1 and 0 will shrink the +graphic and a negative number will reflect it. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">angle</itemformat></item> +</tableterm><tableitem><para>Rotate the graphic. The angle is taken in degrees and counterclockwise. +The graphic is rotated about its <code>origin</code>; see that option. For a +complete description of how rotated material is typeset, +<pxref label="_005crotatebox"><xrefnodename>\rotatebox</xrefnodename></pxref>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">origin</itemformat></item> +</tableterm><tableitem><para>The point of the graphic about which the rotation happens. Possible +values are any string containing one or two of: <code>l</code> for left, +<code>r</code> for right, <code>b</code> for bottom, <code>c</code> for center, <code>t</code> +for top, and <code>B</code> for baseline. Thus, entering the command +<code>\includegraphics[angle=180,origin=c]{moon}</code> will turn the +picture upside down about that picture&textrsquo;s center, while the command +<code>\includegraphics[angle=180,origin=lB]{LeBateau}</code> will turn its +picture upside down about its left baseline. (The character <code>c</code> +gives the horizontal center in <code>bc</code> or <code>tc</code>, but gives the +vertical center in <code>lc</code> or <code>rc</code>.) The default is <code>lB</code>. +</para> +<para>To rotate about an arbitrary point, <pxref label="_005crotatebox"><xrefnodename>\rotatebox</xrefnodename></pxref>. +</para> +</tableitem></tableentry></table> + +<para>These are lesser-used options. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="includegraphics-viewport">includegraphics viewport</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">viewport</itemformat></item> +</tableterm><tableitem><para>Pick out a subregion of the graphic to show. Takes four arguments, +separated by spaces and given in &tex; dimensions, as with +<code>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</code>. The +dimensions default to big points, <code>bp</code>. They are taken +relative to the origin specified by the bounding box. See also the +<code>trim</code> option. +</para> +<anchor name="includegraphics-trim">includegraphics trim</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">trim</itemformat></item> +</tableterm><tableitem><para>Gives parts of the graphic to not show. Takes four arguments, separated +by spaces, that are given in &tex; dimensions, as with +<code>\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}</code>. +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 <code>viewport</code> option. +</para> +<anchor name="includegraphics-clip">includegraphics clip</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">clip</itemformat></item> +</tableterm><tableitem><para>If set to <code>true</code>, or just specified as here +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics[...,clip,...]{...} +</pre></example> + +<noindent></noindent> +<para>then the graphic is cropped to the bounding box. This is the same as +using the starred form of the command, +<code>\includegraphics*[...]{...}</code>. +</para> +<anchor name="includegraphics-page">includegraphics page</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">page</itemformat></item> +</tableterm><tableitem><para>Give the page number of a multi-page PDF file. The default is +<code>page=1</code>. +</para> +<anchor name="includegraphics-pagebox">includegraphics pagebox</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">pagebox</itemformat></item> +</tableterm><tableitem><para>Specifies which bounding box to use for PDF files from among +<code>mediabox</code>, <code>cropbox</code>, <code>bleedbox</code>, <code>trimbox</code>, or +<code>artbox</code>. 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&textrsquo;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 name="includegraphics-interpolate">includegraphics interpolate</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">interpolate</itemformat></item> +</tableterm><tableitem><para>Enable or disable interpolation of raster images by the viewer. Can be +set with <code>interpolate=true</code> or just specified as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics[...,interpolate,...]{...} +</pre></example> + +<anchor name="includegraphics-quiet">includegraphics quiet</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">quiet</itemformat></item> +</tableterm><tableitem><para>Do not write information to the log. You can set it with +<code>quiet=true</code> or just specified it with +<code>\includegraphics[...,quite,...]{...}</code>, +</para> +<anchor name="includegraphics-draft">includegraphics draft</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">draft</itemformat></item> +</tableterm><tableitem><para>If you set it with <code>draft=true</code> or just specify it with +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics[...,draft,...]{...} +</pre></example> + +<noindent></noindent> +<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> +</tableitem></tableentry></table> + +<para>These options address the bounding box for Encapsulated PostScript +graphic files, which have a size specified with a line +<code>%%BoundingBox</code> that appears in the file. It has four values, +giving the lower <math>x</math> coordinate, lower <math>y</math> coordinate, upper +<math>x</math> coordinate, and upper <math>y</math> coordinate. The units are +PostScript points, equivalent to &tex;&textrsquo;s big points, 1/72 inch. +For example, if an <file>.eps</file> file has the line <code>%%BoundingBox 10 +20 40 80</code> then its natural size is 30/72 inch wide by +60/72 inch tall. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="includegraphics-bb">includegraphics bb</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">bb</itemformat></item> +</tableterm><tableitem><para>Specify the bounding box of the displayed region. The argument is four +dimensions separated by spaces, as with <code>\includegraphics[.., bb= +0in 0in 1in 0.618in]{...}</code>. Usually <code>\includegraphics</code> 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 name="includegraphics-bbllx">includegraphics bbllx</anchor> +<anchor name="includegraphics-bblly">includegraphics bblly</anchor> +<anchor name="includegraphics-bburx">includegraphics bburx</anchor> +<anchor name="includegraphics-bbury">includegraphics bbury</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">bbllx, bblly, bburx, bbury</itemformat></item> +</tableterm><tableitem><para>Set the bounding box. These four are obsolete, but are retained for +compatibility with old packages. +</para> +<anchor name="includegraphics-natwidth">includegraphics natwidth</anchor> +<anchor name="includegraphics-natheight">includegraphics natheight</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">natwidth, natheight</itemformat></item> +</tableterm><tableitem><para>An alternative for <code>bb</code>. Setting +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics[...,natwidth=1in,natheight=0.618in,...]{...} +</pre></example> + +<noindent></noindent> +<para>is the same as setting <code>bb=0 0 1in 0.618in</code>. +</para> +<anchor name="includegraphics-hiresbb">includegraphics hiresbb</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">hiresbb</itemformat></item> +</tableterm><tableitem><para>If set to <code>true</code>, or just specified as with +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includegraphics[...,hiresbb,...]{...} +</pre></example> + +<noindent></noindent> +<para>then &latex; will look for <code>%%HiResBoundingBox</code> lines instead of +<code>%%BoundingBox</code> lines. (The <code>BoundingBox</code> lines use only +natural numbers while the <code>HiResBoundingBox</code> lines use decimals; +both use units equivalent to &tex;&textrsquo;s big points, 1/72 inch.) To +override a prior setting of <code>true</code>, you can set it to <code>false</code>. +</para> +</tableitem></tableentry></table> + +<para>These following options allow a user to override &latex;&textrsquo;s method of +choosing the graphic type based on the filename extension. An example +is that <code>\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}</code> +will read the file <file>lion.xxx</file> as though it were +<file>lion.png</file>. For more on these, <pxref label="_005cDeclareGraphicsRule"><xrefnodename>\DeclareGraphicsRule</xrefnodename></pxref>. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="includegraphics-type">includegraphics type</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">type</itemformat></item> +</tableterm><tableitem><para>Specify the graphics type. +</para> +<anchor name="includegraphics-ext">includegraphics ext</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">ext</itemformat></item> +</tableterm><tableitem><para>Specify the graphics extension. +Only use this in conjunction with the option <code>type</code>. +</para> +<anchor name="includegraphics-read">includegraphics read</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">read</itemformat></item> +</tableterm><tableitem><para>Specify the file extension of the read file. +Only use this in conjunction with the option <code>type</code>. +</para> +<anchor name="includegraphics-command">includegraphics command</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">command</itemformat></item> +</tableterm><tableitem><para>Specify a command to be applied to this file. Only use this in +conjunction with the option <code>type</code>. <xref label="Command-line-options"><xrefnodename>Command line options</xrefnodename></xref> +for a discussion of enabling the <code>\write18</code> functionality to run +external commands. +</para> +</tableitem></tableentry></table> + + +</subsection> +<node name="_005crotatebox" spaces=" "><nodename>\rotatebox</nodename><nodenext automatic="on">\scalebox</nodenext><nodeprev automatic="on">\includegraphics</nodeprev><nodeup automatic="on">Commands for graphics</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\rotatebox</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="700">rotation</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="701">rotating graphics</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="702">rotating text</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="881" mergedindex="cp">\rotatebox</indexterm></findex> + +<para>Synopsis if you use the <file>graphics</file> package: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\rotatebox{<var>angle</var>}{<var>material</var>} +</pre></example> + +<para>Synopses if you use the <file>graphicx</file> package: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\rotatebox{<var>angle</var>}{<var>material</var>} +\rotatebox[<var>key-value list</var>]{<var>angle</var>}{<var>material</var>} +</pre></example> + +<para>Put <var>material</var> in a box and rotate it <var>angle</var> degrees +counterclockwise. +</para> +<para>This example rotates the table column heads forty five degrees. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{tabular}{ll} + \rotatebox{45}{Character} &\rotatebox{45}{NATO phonetic} \\ + A &AL-FAH \\ + B &BRAH-VOH +\end{tabular} +</pre></example> + +<para>The <var>material</var> can be anything that goes in a box, including a graphic. +</para> +<example endspaces=" "> +<pre xml:space="preserve"> \rotatebox[origin=c]{45}{\includegraphics[width=1in]{lion}} +</pre></example> + +<para>To place the rotated material, the first step is that &latex; sets +<var>material</var> 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 <file>graphics</file> package then the rotation is about the +reference point of the box. If you use the <file>graphicx</file> package +then these are the options that can go in the <var>key-value list</var>, +but note that you can get the same effect without needing this +package, except for the <code>x</code> and <code>y</code> options +(<pxref label="_005cincludegraphics"><xrefnodename>\includegraphics</xrefnodename></pxref>). +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">origin</itemformat></item> +</tableterm><tableitem><para>The point of the <var>material</var>&textrsquo;s box about which the rotation happens. +Possible value is any string containing one or two of: <code>l</code> for +left, <code>r</code> for right, <code>b</code> for bottom, <code>c</code> for center, +<code>t</code> for top, and <code>B</code> for baseline. Thus, the first line here +</para> +<example endspaces=" "> +<pre xml:space="preserve">\rotatebox[origin=c]{180}{moon} +\rotatebox[origin=lB]{180}{LeBateau} +</pre></example> + +<noindent></noindent> +<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 +<code>c</code> gives the horizontal center in <code>bc</code> or <code>tc</code> but gives +the vertical center in <code>lc</code> or <code>rc</code>, and gives both in +<code>c</code>.) The default is <code>lB</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">x, y</itemformat></item> +</tableterm><tableitem><para>Specify an arbitrary point of rotation with +<code>\rotatebox[x=<var>&tex; dimension</var>,y=<var>&tex; +dimension</var>]{...}</code> (<pxref label="Units-of-length"><xrefnodename>Units of length</xrefnodename></pxref>). These give the offset +from the box&textrsquo;s reference point. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">units</itemformat></item> +</tableterm><tableitem><para>This key allows you to change the default of degrees counterclockwise. +Setting <code>units=-360</code> changes the direction to degrees clockwise and +setting <code>units=6.283185</code> changes to radians counterclockwise. +</para> +</tableitem></tableentry></table> + + +</subsection> +<node name="_005cscalebox" spaces=" "><nodename>\scalebox</nodename><nodenext automatic="on">\resizebox</nodenext><nodeprev automatic="on">\rotatebox</nodeprev><nodeup automatic="on">Commands for graphics</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\scalebox</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="703">graphics, scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="704">graphics, resizing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="705">scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="706">resizing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="707">text, scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="708">text, resizing</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="882" mergedindex="cp">\scalebox</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="883" mergedindex="cp">\reflectbox</indexterm></findex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\scalebox{<var>horizontal factor</var>}{<var>material</var>} +\scalebox{<var>horizontal factor</var>}[<var>vertical factor</var>]{<var>material</var>} +\reflectbox{<var>material</var>} +</pre></example> + +<para>Scale the <var>material</var>. +</para> +<para>This example halves the size, both horizontally and vertically, of the +first text and doubles the size of the second. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\scalebox{0.5}{DRINK ME} and \scalebox{2.0}{Eat Me} +</pre></example> + +<para>If you do not specify the optional <var>vertical factor</var> then it +defaults to the same value as the <var>horizontal factor</var>. +</para> +<para>You can use this command to resize a graphic, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\scalebox{0.5}{\includegraphics{lion}} +</pre></example> + +<noindent></noindent> +<para>If you use the <file>graphicx</file> package then you can accomplish the same +thing with optional arguments to <code>\includegraphics</code> +(<pxref label="_005cincludegraphics"><xrefnodename>\includegraphics</xrefnodename></pxref>). +</para> +<para>The <code>\reflectbox</code> command abbreviates +<code>\scalebox{-1}[1]{<var>material</var>}</code>. Thus, <code>Able was +I\reflectbox{Able was I}</code> will show the phrase <samp>Able was I</samp> +immediately followed by its mirror reflection. +</para> + +</subsection> +<node name="_005cresizebox" spaces=" "><nodename>\resizebox</nodename><nodeprev automatic="on">\scalebox</nodeprev><nodeup automatic="on">Commands for graphics</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\resizebox</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="709">graphics, scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="710">graphics, resizing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="711">scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="712">resizing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="713">text, scaling</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="714">text, resizing</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="884" mergedindex="cp">\resizebox</indexterm></findex> + +<para>Synopses: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\resizebox{<var>horizontal length</var>}{<var>vertical length</var>}{<var>material</var>} +\resizebox*{<var>horizontal length</var>}{<var>vertical length</var>}{<var>material</var>} +</pre></example> + +<para>Given a size, such as <code>3cm</code>, transform <var>material</var> to make it +that size. If either <var>horizontal length</var> or <var>vertical length</var> +is an exclamation point <code>!</code> 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> +<example endspaces=" "> +<pre xml:space="preserve">\resizebox{0.5in}{!}{\includegraphics{lion}} +</pre></example> + +<para>The unstarred form <code>\resizebox</code> takes <var>vertical length</var> to be +the box&textrsquo;s height while the starred form <code>\resizebox*</code> takes it to +be height+depth. For instance, make the text have a height+depth of a +quarter inch with <code>\resizebox*{!}{0.25in}{\parbox{1in}{This +box has both height and depth.}}</code>. +</para> +<para>You can use <code>\depth</code>, <code>\height</code>, <code>\totalheight</code>, and +<code>\width</code> to refer to the original size of the box. Thus, make the +text two inches wide but keep the original height with +<code>\resizebox{2in}{\height}{Two inches}</code>. +</para> + +</subsection> +</section> +</chapter> +<node name="Special-insertions" spaces=" "><nodename>Special insertions</nodename><nodenext automatic="on">Splitting the input</nodenext><nodeprev automatic="on">Graphics</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Special insertions</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="715">special insertions</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="716">insertions of special characters</indexterm></cindex> + +<para>&latex; provides commands for inserting characters that have a +special meaning do not correspond to simple characters you can type. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Reserved characters</menunode><menudescription><pre xml:space="preserve">Inserting <samp># $ % & { } _ ~ ^ \</samp> +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Upper and lower case</menunode><menudescription><pre xml:space="preserve">Make text upper or lower case. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Symbols by font position</menunode><menudescription><pre xml:space="preserve">Inserting font symbols by number. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Text symbols</menunode><menudescription><pre xml:space="preserve">Inserting other non-letter symbols in text. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Accents</menunode><menudescription><pre xml:space="preserve">Inserting accents. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Additional Latin letters</menunode><menudescription><pre xml:space="preserve">Inserting other non-English characters. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\rule</menunode><menudescription><pre xml:space="preserve">Inserting lines and rectangles. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\today</menunode><menudescription><pre xml:space="preserve">Inserting today&textrsquo;s date. +</pre></menudescription></menuentry></menu> + + +<node name="Reserved-characters" spaces=" "><nodename>Reserved characters</nodename><nodenext automatic="on">Upper and lower case</nodenext><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Reserved characters</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="717">reserved characters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="718">characters, reserved</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="719">special characters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="720">characters, special</indexterm></cindex> +<para>&latex; sets aside the following characters for special purposes. For +example, the percent sign <code>%</code> is for comments. They are +called <dfn>reserved characters</dfn> or <dfn>special characters</dfn>. +</para> +<example endspaces=" "> +<pre xml:space="preserve"># $ % & { } _ ~ ^ \ +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="885" mergedindex="cp">\#</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="886" mergedindex="cp">\$</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="887" mergedindex="cp">\%</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="888" mergedindex="cp">\&</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="889" mergedindex="cp">\_</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="890" mergedindex="cp">\{</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="891" mergedindex="cp">\}</indexterm></findex> +<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 <code>\</code> in front of the character. Thus, +typing <code>\$1.23</code> will produce <code>$1.23</code> in your output. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="892" mergedindex="cp">\~</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="893" mergedindex="cp">\^</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="894" mergedindex="cp">\textbackslash</indexterm></findex> +<para>As to the last three characters, to get a tilde in the text body font +use <code>\~{}</code> (omitting the curly braces would result in the next +character receiving a tilde accent). Similarly, to get a get a text +body font circumflex use <code>\^{}</code>. To get a backslash in the font +of the text body, enter <code>\textbackslash{}</code>. +</para> +<para>To produce the reserved characters in a typewriter font use +<code>\verb!!</code> as below (the double backslash <code>\\</code> is only +there to split the lines). +</para> +<example endspaces=" "> +<pre xml:space="preserve">\begin{center} + \# \$ \% \& \{ \} \_ \~{} \^{} \textbackslash \\ + \verb!# $ % & { } _ ~ ^ \! +\end{center} +</pre></example> + + +</section> +<node name="Upper-and-lower-case" spaces=" "><nodename>Upper and lower case</nodename><nodenext automatic="on">Symbols by font position</nodenext><nodeprev automatic="on">Reserved characters</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Upper and lower case</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="721">uppercase</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="722">lowercase</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="723">characters, case of</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\uppercase{<var>text</var>} +\lowercase{<var>text</var>} +\MakeUppercase{<var>text</var>} +\MakeLowercase{<var>text</var>} +</pre></example> + +<para>Change the case of characters. The &tex; primitives commands +<code>\uppercase</code> and <code>\lowercase</code> only work for American +characters. The &latex; commands <code>\MakeUppercase</code> and +<code>\MakeLowercase</code> commands also change characters accessed by +commands such as <code>\ae</code> or <code>\aa</code>. The commands +<code>\MakeUppercase</code> and <code>\MakeLowercase</code> are robust but they have +moving arguments (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>These commands do not change the case of letters used in the name of a +command within <var>text</var>. But they do change the case of every other +Latin letter inside the argument <var>text</var>. Thus, +<code>\MakeUppercase{Let $y=f(x)$</code>} produces <samp>LET Y=F(X)</samp>. Another +example is that the name of an environment will be changed, so that +<code>\MakeUppercase{\begin{tabular} ... \end{tabular}}</code> will +produce an error because the first half is changed to +<code>\begin{TABULAR}</code>. +</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 <var>text</var> +you need to do expansion. Here the <code>\Schoolname</code> produces +<samp>COLLEGE OF MATHEMATICS</samp>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\schoolname}{College of Mathematics} +\newcommand{\Schoolname}{\expandafter\MakeUppercase +<w> </w>\expandafter{\schoolname}} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="724"><r>package</r>, <code>textcase</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="725"><code>textcase</code> <r>package</r></indexterm></cindex> + +<para>The <file>textcase</file> package brings some of the missing feature of the +standard &latex; commands <code>\MakeUppercase</code> and +<code>\MakeLowerCase</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="726"><r>package</r>, <code>mfirstuc</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="727"><code>mfirstuc</code> <r>package</r></indexterm></cindex> + +<para>To uppercase only the first letter of words, you can use the package +<file>mfirstuc</file>. +</para> + +</section> +<node name="Symbols-by-font-position" spaces=" "><nodename>Symbols by font position</nodename><nodenext automatic="on">Text symbols</nodenext><nodeprev automatic="on">Upper and lower case</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Symbols by font position</sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="895" mergedindex="cp">\symbol</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="728">accessing any character of a font</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="729">font symbols, by number</indexterm></cindex> + +<para>You can access any character of the current font using its number with +the <code>\symbol</code> command. For example, the visible space character +used in the <code>\verb*</code> command has the code decimal 32, so it can be +typed as <code>\symbol{32}</code>. +</para> +<para>You can also specify numbers in octal (base 8) by using a <code>'</code> +prefix, or hexadecimal (base 16) with a <code>"</code> prefix, so the previous +example could also be written as <code>\symbol{'40}</code> or +<code>\symbol{"20}</code>. +</para> + +</section> +<node name="Text-symbols" spaces=" "><nodename>Text symbols</nodename><nodenext automatic="on">Accents</nodenext><nodeprev automatic="on">Symbols by font position</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Text symbols</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="730">text symbols</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="731">symbols, text</indexterm></cindex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="896" mergedindex="cp">textcomp <r>package</r></indexterm></findex> +<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 <code>textcomp</code> package. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="897" mergedindex="cp">\copyright</indexterm>\copyright</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="898" mergedindex="cp">\textcopyright</indexterm>\textcopyright</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="732">copyright symbol</indexterm></cindex> +<para>©right; The copyright symbol. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="899" mergedindex="cp">\dag</indexterm>\dag</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="733">dagger, in text</indexterm></cindex> +<para><U>2020</U> The dagger symbol (in text). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="900" mergedindex="cp">\ddag</indexterm>\ddag</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="734">double dagger, in text</indexterm></cindex> +<para><U>2021</U> The double dagger symbol (in text). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="901" mergedindex="cp">\LaTeX</indexterm>\LaTeX</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="735">&latex; logo</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="736">logo, &latex;</indexterm></cindex> +<para>The &latex; logo. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="902" mergedindex="cp">\LaTeXe</indexterm>\LaTeXe</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="737">&latex;2e logo</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="738">logo, &latex;2e</indexterm></cindex> +<para>The &latex;2e logo. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="903" mergedindex="cp">\guillemotleft <r>(«)</r></indexterm>\guillemotleft <r>(«)</r></itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="904" mergedindex="cp">\guillemotright <r>(»)</r></indexterm>\guillemotright <r>(»)</r></itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="905" mergedindex="cp">\guilsinglleft <r>(‹)</r></indexterm>\guilsinglleft <r>(‹)</r></itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="906" mergedindex="cp">\guilsinglright <r>(›)</r></indexterm>\guilsinglright <r>(›)</r></itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="739">double guillemets</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="740">single guillemets</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="741">left angle quotation marks</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="742">right angle quotation marks</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="743">double angle quotation marks</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="744">single angle quotation marks</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="745">French quotation marks</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="746">quotation marks, French</indexterm></cindex> +<para>«, », ‹, › +Double and single angle quotation marks, commonly used in French. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="907" mergedindex="cp">\ldots</indexterm>\ldots</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="908" mergedindex="cp">\dots</indexterm>\dots</itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="909" mergedindex="cp">\textellipsis</indexterm>\textellipsis</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="747">ellipsis</indexterm></cindex> +<para>&dots; An ellipsis (three dots at the baseline): <code>\ldots</code> +and <code>\dots</code> also work in math mode. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="910" mergedindex="cp">\lq</indexterm>\lq</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="748">left quote</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="749">opening quote</indexterm></cindex> +<para>&textlsquo; Left (opening) quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="911" mergedindex="cp">\P</indexterm>\P</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="912" mergedindex="cp">\textparagraph</indexterm>\textparagraph</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="750">paragraph symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="751">pilcrow</indexterm></cindex> +<para><U>00B6</U> Paragraph sign (pilcrow). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="913" mergedindex="cp">\pounds</indexterm>\pounds</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="914" mergedindex="cp">\textsterling</indexterm>\textsterling</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="752">pounds symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="753">sterling symbol</indexterm></cindex> +<para>£ English pounds sterling. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="915" mergedindex="cp">\quotedblbase <r>(„)</r></indexterm>\quotedblbase <r>(„)</r></itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="916" mergedindex="cp">\quotesinglbase <r>(‚)</r></indexterm>\quotesinglbase <r>(‚)</r></itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="754">double low-9 quotation mark</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="755">single low-9 quotation mark</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="756">low-9 quotation marks, single and double</indexterm></cindex> +<para>„ and ‚ +Double and single quotation marks on the baseline. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="917" mergedindex="cp">\rq</indexterm>\rq</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="757">right quote</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="758">closing quote</indexterm></cindex> +<para>&textrsquo; Right (closing) quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="918" mergedindex="cp">\S</indexterm>\S</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="919" mergedindex="cp">\textsection</indexterm>\textsection</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="759">section symbol</indexterm></cindex> +<para><U>00A7</U> Section sign. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="920" mergedindex="cp">\TeX</indexterm>\TeX</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="760">&tex; logo</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="761">logo, &tex;</indexterm></cindex> +<para>The &tex; logo. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="921" mergedindex="cp">\textasciicircum</indexterm>\textasciicircum</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="762">circumflex, ASCII, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="763">ASCII circumflex, in text</indexterm></cindex> +<para>^ ASCII circumflex. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="922" mergedindex="cp">\textasciitilde</indexterm>\textasciitilde</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="764">tilde, ASCII, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="765">ASCII tilde, in text</indexterm></cindex> +<para>~ ASCII tilde. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="923" mergedindex="cp">\textasteriskcentered</indexterm>\textasteriskcentered</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="766">asterisk, centered, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="767">centered asterisk, in text</indexterm></cindex> +<para>* Centered asterisk. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="924" mergedindex="cp">\textbackslash</indexterm>\textbackslash</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="768">backslash, in text</indexterm></cindex> +<para>\ Backslash. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="925" mergedindex="cp">\textbar</indexterm>\textbar</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="769">vertical bar, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="770">bar, vertical, in text</indexterm></cindex> +<para>| Vertical bar. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="926" mergedindex="cp">\textbardbl</indexterm>\textbardbl</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="771">vertical bar, double, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="772">bar, double vertical, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="773">double vertical bar, in text</indexterm></cindex> +<para><U>23F8</U> Double vertical bar. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="927" mergedindex="cp">\textbigcircle</indexterm>\textbigcircle</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="774">big circle symbols, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="775">circle symbol, big, in text</indexterm></cindex> +<para><U>25EF</U> Big circle symbol. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="928" mergedindex="cp">\textbraceleft</indexterm>\textbraceleft</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="776">left brace, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="777">brace, left, in text</indexterm></cindex> +<para>{ Left brace. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="929" mergedindex="cp">\textbraceright</indexterm>\textbraceright</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="778">right brace, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="779">brace, right, in text</indexterm></cindex> +<para>} Right brace. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="930" mergedindex="cp">\textbullet</indexterm>\textbullet</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="780">bullet, in text</indexterm></cindex> +<para>• Bullet. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="931" mergedindex="cp">\textcircled{<var>letter</var>}</indexterm>\textcircled{<var>letter</var>}</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="781">circled letter, in text</indexterm></cindex> +<para><U>24B6</U> Circle around <var>letter</var>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="932" mergedindex="cp">\textcompwordmark</indexterm>\textcompwordmark</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="933" mergedindex="cp">\textcapitalcompwordmark</indexterm>\textcapitalcompwordmark</itemformat></itemx> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="934" mergedindex="cp">\textascendercompwordmark</indexterm>\textascendercompwordmark</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="782">composite word mark, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="783">cap height</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="784">ascender height</indexterm></cindex> +<para>Used to separate letters that would normally ligature. For example, +<code>f\textcompwordmark i</code> produces <samp>fi</samp> without a ligature. This +is most useful in non-English languages. The +<code>\textcapitalcompwordmark</code> form has the cap height of the font +while the <code>\textascendercompwordmark</code> form has the ascender height. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="935" mergedindex="cp">\textdagger</indexterm>\textdagger</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="785">dagger, in text</indexterm></cindex> +<para><U>2020</U> Dagger. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="936" mergedindex="cp">\textdaggerdbl</indexterm>\textdaggerdbl</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="786">dagger, double, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="787">double dagger, in text</indexterm></cindex> +<para><U>2021</U> Double dagger. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="937" mergedindex="cp">\textdollar <r>(or <code>\$</code>)</r></indexterm>\textdollar <r>(or <code>\$</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="788">dollar sign</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="789">currency, dollar</indexterm></cindex> +<para>$ Dollar sign. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="938" mergedindex="cp">\textemdash <r>(or <code>---</code>)</r></indexterm>\textemdash <r>(or <code>---</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="790">em-dash</indexterm></cindex> +<para>&textmdash; Em-dash (used for punctuation, as in +<code>The playoffs --- if you are fortunate enough to make the playoffs --- +is more like a sprint.</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="939" mergedindex="cp">\textendash <r>(or <code>--</code>)</r></indexterm>\textendash <r>(or <code>--</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="791">e-dash</indexterm></cindex> +<para>&textndash; En-dash (used for ranges, as in <code>See pages 12--14</code>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="940" mergedindex="cp">\texteuro</indexterm>\texteuro</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="792">euro symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="793">currency, euro</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="794"><r>package</r>, <code>eurosym</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="795"><code>eurosym</code> <r>package</r></indexterm></cindex> + +<para>The Euro symbol: €. For an alternative glyph design, try the +<file>eurosym</file> package; also, most fonts nowadays come with their own +Euro symbol (Unicode U+20AC). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="941" mergedindex="cp">\textexclamdown <r>(or <code>!`</code>)</r></indexterm>\textexclamdown <r>(or <code>!`</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="796">exclamation point, upside-down</indexterm></cindex> +<para>¡ Upside down exclamation point. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="942" mergedindex="cp">\textgreater</indexterm>\textgreater</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="797">greater than symbol, in text</indexterm></cindex> +<para>> Greater than symbol. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="943" mergedindex="cp">\textless</indexterm>\textless</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="798">less than symbol, in text</indexterm></cindex> +<para>< Less than symbol. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="944" mergedindex="cp">\textleftarrow</indexterm>\textleftarrow</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="799">arrow, left, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="800">left arrow, in text</indexterm></cindex> +<para><U>2190</U> Left arrow. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="945" mergedindex="cp">\textordfeminine</indexterm>\textordfeminine</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="946" mergedindex="cp">\textordmasculine</indexterm>\textordmasculine</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="801">feminine ordinal symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="802">masculine ordinal symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="803">ordinals, feminine and masculine</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="804">Spanish ordinals, feminine and masculine</indexterm></cindex> +<para>ª, º Feminine and masculine ordinal symbols. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="947" mergedindex="cp">\textperiodcentered</indexterm>\textperiodcentered</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="805">period, centered, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="806">centered period, in text</indexterm></cindex> +<para><U>00B7</U> Centered period. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="948" mergedindex="cp">\textquestiondown <r>(or <code>?`</code>)</r></indexterm>\textquestiondown <r>(or <code>?`</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="807">question mark, upside-down</indexterm></cindex> +<para>¿ Upside down question mark. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="949" mergedindex="cp">\textquotedblleft <r>(or <code>``</code>)</r></indexterm>\textquotedblleft <r>(or <code>``</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="808">left quote, double</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="809">double left quote</indexterm></cindex> +<para>&textldquo; Double left quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="950" mergedindex="cp">\textquotedblright <r>(or <code>''</code>)</r></indexterm>\textquotedblright <r>(or <code>''</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="810">right quote, double</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="811">double right quote</indexterm></cindex> +<para>&textrdquo; Double right quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="951" mergedindex="cp">\textquoteleft <r>(or <code>`</code>)</r></indexterm>\textquoteleft <r>(or <code>`</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="812">left quote, single</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="813">single left quote</indexterm></cindex> +<para>&textlsquo; Single left quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="952" mergedindex="cp">\textquoteright <r>(or <code>'</code>)</r></indexterm>\textquoteright <r>(or <code>'</code>)</r></itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="814">right quote, single</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="815">single right quote</indexterm></cindex> +<para>&textrsquo; Single right quote. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="953" mergedindex="cp">\textquotesingle</indexterm>\textquotesingle</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="816">quote, single straight</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="817">straight single quote</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="818">single quote, straight</indexterm></cindex> +<para><U>0027</U> Straight single quote. (From TS1 encoding.) +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="954" mergedindex="cp">\textquotestraightbase</indexterm>\textquotestraightbase</itemformat></item> +<itemx spaces=" "><itemformat command="code"><indexterm index="fn" number="955" mergedindex="cp">\textquotestraightdblbase</indexterm>\textquotestraightdblbase</itemformat></itemx> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="819">quote, straight base</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="820">straight quote, base</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="821">double quote, straight base</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="822">straight double quote, base</indexterm></cindex> +<!-- c Unicode doesn't have these https://en.wikipedia.org/wiki/Quotation_mark --> +<para>Single and double straight quotes on the baseline. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="956" mergedindex="cp">\textregistered</indexterm>\textregistered</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="823">registered symbol</indexterm></cindex> +<para>®istered; Registered symbol. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="957" mergedindex="cp">\textrightarrow</indexterm>\textrightarrow</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="824">arrow, right, in text</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="825">right arrow, in text</indexterm></cindex> +<para><U>2192</U> Right arrow. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="958" mergedindex="cp">\textthreequartersemdash</indexterm>\textthreequartersemdash</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="826">three-quarters em-dash</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="827">em-dash, three-quarters</indexterm></cindex> +<para><U>FE58</U> &textldquo;Three-quarters&textrdquo; em-dash, between en-dash and em-dash. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="959" mergedindex="cp">\texttrademark</indexterm>\texttrademark</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="828">trademark symbol</indexterm></cindex> +<para><U>2122</U> Trademark symbol. +</para> +<!-- c ?? Diff from \textthreequartersemdash? In Unicode? --> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="960" mergedindex="cp">\texttwelveudash</indexterm>\texttwelveudash</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="829">two-thirds em-dash</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="830">em-dash, two-thirds</indexterm></cindex> +<para><U>FE58</U> &textldquo;Two-thirds&textrdquo; em-dash, between en-dash and em-dash. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="961" mergedindex="cp">\textunderscore</indexterm>\textunderscore</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="831">underscore, in text</indexterm></cindex> +<para>_ Underscore. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="962" mergedindex="cp">\textvisiblespace</indexterm>\textvisiblespace</itemformat></item> +</tableterm><tableitem><cindex index="cp" spaces=" "><indexterm index="cp" number="832">visible space symbol, in text</indexterm></cindex> +<para><U>2423</U> Visible space symbol. +</para> +</tableitem></tableentry></ftable> + + +</section> +<node name="Accents" spaces=" "><nodename>Accents</nodename><nodenext automatic="on">Additional Latin letters</nodenext><nodeprev automatic="on">Text symbols</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Accents</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="833">accents</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="834">characters, accented</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="835">letters, accented</indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="836"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="837"><code>babel</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="838"><r>package</r>, <code>polyglossia</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="839"><code>polyglossia</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="840">multilingual support</indexterm></cindex> +<para>&latex; has wide support for many of the world&textrsquo;s scripts and languages, +through the <code>babel</code> package and related support if you are using +pdf&latex;, or <file>polyglossia</file> if you are using Xe&latex; or +Lua&latex;. This section does not cover that support. It only lists +the core &latex; commands for creating accented characters. The +<code>\capital...</code> 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 <samp>o</samp>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="963" mergedindex="cp">\i <r>(dotless i)</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="841">dotless i</indexterm></cindex> +<para>Note that <code>\i</code> produces a dotless i, +<!-- c @dotless{i}, --> +<findex index="fn" spaces=" "><indexterm index="fn" number="964" mergedindex="cp">\j <r>(dotless j)</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="842">dotless j</indexterm></cindex> +and <code>\j</code> produces a dotless j. +<!-- c @dotless{j}. --> +These are often used in place of their dotted counterparts when they are +accented. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\"</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitaldieresis</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="965" mergedindex="cp">\" <r>(umlaut accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="966" mergedindex="cp">\capitaldieresis</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="843">umlaut accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="844">dieresis accent</indexterm></cindex> +<para><accent type="uml">o</accent> Umlaut (dieresis). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\'</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalacute</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="967" mergedindex="cp">\' <r>(acute accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="968" mergedindex="cp">\capitalacute</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="845">acute accent</indexterm></cindex> +<para><accent type="acute">o</accent> Acute accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\.</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="969" mergedindex="cp">\. <r>(dot-over accent)</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="846">dot accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="847">dot-over accent</indexterm></cindex> +<para><accent type="dotaccent">o</accent> Dot accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\=</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalmacron</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="970" mergedindex="cp">\= <r>(macron accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="971" mergedindex="cp">\capitalmacron</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="848">macron accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="849">overbar accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="850">bar-over accent</indexterm></cindex> +<para><accent type="macr">o</accent> Macron (overbar) accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\^</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalcircumflex</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="972" mergedindex="cp">\^ <r>(circumflex accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="973" mergedindex="cp">\capitalcircumflex</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="851">circumflex accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="852">hat accent</indexterm></cindex> +<para><accent type="circ">o</accent> Circumflex (hat) accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\`</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalgrave</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="974" mergedindex="cp">\` <r>(grave accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="975" mergedindex="cp">\capitalgrave</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="853">grave accent</indexterm></cindex> +<para><accent type="grave">o</accent> Grave accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\~</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitaltilde</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="976" mergedindex="cp">\~ <r>(tilde accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="977" mergedindex="cp">\capitaltilde</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="854">tilde accent</indexterm></cindex> +<para><accent type="tilde">n</accent> Tilde accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\b</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="978" mergedindex="cp">\b <r>(bar-under accent)</r></indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="855">bar-under accent</indexterm></cindex> +<para><accent type="ubaraccent">o</accent> Bar accent underneath. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="979" mergedindex="cp">\underbar</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="856">underbar</indexterm></cindex> +<para>Related to this, <code>\underbar{<var>text</var>}</code> produces a bar under +<var>text</var>. The argument is always processed in LR mode +(<pxref label="Modes"><xrefnodename>Modes</xrefnodename></pxref>). The bar is always a fixed position under the baseline, +thus crossing through descenders. See also <code>\underline</code> in +<ref label="Math-miscellany"><xrefnodename>Math miscellany</xrefnodename></ref>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\c</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalcedilla</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="980" mergedindex="cp">\c <r>(cedilla accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="981" mergedindex="cp">\capitalcedilla</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="857">cedilla accent</indexterm></cindex> +<para><accent type="cedil">c</accent> Cedilla accent underneath. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\d</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitaldotaccent</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="982" mergedindex="cp">\d <r>(dot-under accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="983" mergedindex="cp">\capitaldotaccent</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="858">dot-under accent</indexterm></cindex> +<para><accent type="udotaccent">o</accent> Dot accent underneath. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\H</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalhungarumlaut</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="984" mergedindex="cp">\H <r>(Hungarian umlaut accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="985" mergedindex="cp">\capitalhungarumlaut</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="859">hungarian umlaut accent</indexterm></cindex> +<para><accent type="doubleacute">o</accent> Long Hungarian umlaut accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\k</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalogonek</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="986" mergedindex="cp">\k <r>(ogonek)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="987" mergedindex="cp">\capitalogonek</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="860">ogonek</indexterm></cindex> +<para><accent type="ogon">o</accent> Ogonek. Not available in the OT1 encoding. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\r</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalring</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="988" mergedindex="cp">\r <r>(ring accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="989" mergedindex="cp">\capitalring</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="861">ring accent</indexterm></cindex> +<para><accent type="ring">o</accent> Ring accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\t</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitaltie</itemformat></itemx> +<itemx spaces=" "><itemformat command="code">\newtie</itemformat></itemx> +<itemx spaces=" "><itemformat command="code">\capitalnewtie</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="990" mergedindex="cp">\t <r>(tie-after accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="991" mergedindex="cp">\capitaltie</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="992" mergedindex="cp">\newtie</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="993" mergedindex="cp">\capitalnewtie</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="862">tie-after accent</indexterm></cindex> +<para><accent type="tieaccent">oo</accent> Tie-after accent. The <code>\newtie</code> form is centered in +its box. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\u</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalbreve</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="994" mergedindex="cp">\u <r>(breve accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="995" mergedindex="cp">\capitalbreve</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="863">breve accent</indexterm></cindex> +<para><accent type="breve">o</accent> Breve accent. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\v</itemformat></item> +<itemx spaces=" "><itemformat command="code">\capitalcaron</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="996" mergedindex="cp">\v <r>(breve accent)</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="997" mergedindex="cp">\capitalcaron</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="864">hacek accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="865">check accent</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="866">caron accent</indexterm></cindex> +<para><accent type="caron">o</accent> H<accent type="acute" bracketed="off">a</accent><accent type="caron">c</accent>ek (check, caron) accent. +</para> +</tableitem></tableentry></table> + + +</section> +<node name="Additional-Latin-letters" spaces=" "><nodename>Additional Latin letters</nodename><nodenext automatic="on">\rule</nodenext><nodeprev automatic="on">Accents</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle>Additional Latin letters</sectiontitle> + +<anchor name="Non_002dEnglish-characters">Non-English characters</anchor> +<cindex index="cp" spaces=" "><indexterm index="cp" number="867">Latin letters, additional</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="868">letters, additional Latin</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="869">extended Latin</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="870">special characters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="871">non-English characters</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="872">characters, non-English</indexterm></cindex> + +<para>Here are the basic &latex; commands for inserting letters beyond +A&textndash;Z that extend the Latin alphabet, used primarily in languages other +than English. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">\aa</itemformat></item> +<itemx spaces=" "><itemformat command="code">\AA</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="998" mergedindex="cp">\aa (å)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="999" mergedindex="cp">\AA (Å)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="873">aring</indexterm></cindex> +<para>å and Å. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ae</itemformat></item> +<itemx spaces=" "><itemformat command="code">\AE</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1000" mergedindex="cp">\ae (æ)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1001" mergedindex="cp">\AE (Æ)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="874">ae ligature</indexterm></cindex> +<para>æ and Æ. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\dh</itemformat></item> +<itemx spaces=" "><itemformat command="code">\DH</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1002" mergedindex="cp">\dh (ð)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1003" mergedindex="cp">\DH (Ð)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="875">Icelandic eth</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="876">eth, Icelandic letter</indexterm></cindex> +<para>Icelandic letter eth: ð and Ð. Not available with <sc>OT1</sc> +encoding, you need the <file>fontenc</file> package to select an alternate +font encoding, such as <sc>T1</sc>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\dj</itemformat></item> +<itemx spaces=" "><itemformat command="code">\DJ</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1004" mergedindex="cp">\dj</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1005" mergedindex="cp">\DJ</indexterm></findex> +<para>Crossed d and D, a.k.a.&noeos; capital and small letter d with stroke. Not +available with <sc>OT1</sc> encoding, you need the <file>fontenc</file> package to +select an alternate font encoding, such as <sc>T1</sc>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ij</itemformat></item> +<itemx spaces=" "><itemformat command="code">\IJ</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1006" mergedindex="cp">\ij (ij)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1007" mergedindex="cp">\IJ (IJ)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="877">ij letter, Dutch</indexterm></cindex> +<para>ij and IJ (except somewhat closer together than appears here). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\l</itemformat></item> +<itemx spaces=" "><itemformat command="code">\L</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1008" mergedindex="cp">\l (&lslash;)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1009" mergedindex="cp">\L (&Lslash;)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="878">polish l</indexterm></cindex> +<para>&lslash; and &Lslash;. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ng</itemformat></item> +<itemx spaces=" "><itemformat command="code">\NG</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1010" mergedindex="cp">\ng</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1011" mergedindex="cp">\NG</indexterm></findex> +<para>Lappish letter eng, also used in phonetics. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\o</itemformat></item> +<itemx spaces=" "><itemformat command="code">\O</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1012" mergedindex="cp">\o (ø)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1013" mergedindex="cp">\O (Ø)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="879">oslash</indexterm></cindex> +<para>ø and Ø. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\oe</itemformat></item> +<itemx spaces=" "><itemformat command="code">\OE</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1014" mergedindex="cp">\oe (œ)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1015" mergedindex="cp">\OE (Œ)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="880">oe ligature</indexterm></cindex> +<para>œ and Œ. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\ss</itemformat></item> +<itemx spaces=" "><itemformat command="code">\SS</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1016" mergedindex="cp">\ss (ß)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1017" mergedindex="cp">\SS (SS)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="881">es-zet German letter</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="882">sharp S letters</indexterm></cindex> +<para>ß and SS. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">\th</itemformat></item> +<itemx spaces=" "><itemformat command="code">\TH</itemformat></itemx> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1018" mergedindex="cp">\th (þ)</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1019" mergedindex="cp">\TH (Þ)</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="883">Icelandic thorn</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="884">thorn, Icelandic letter</indexterm></cindex> +<para>Icelandic letter thorn: þ and Þ. Not available with <sc>OT1</sc> +encoding, you need the <file>fontenc</file> package to select an alternate +font encoding, such as <sc>T1</sc>. +</para> +</tableitem></tableentry></table> + + +</section> +<node name="_005crule" spaces=" "><nodename>\rule</nodename><nodenext automatic="on">\today</nodenext><nodeprev automatic="on">Additional Latin letters</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle><code>\rule</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1020" mergedindex="cp">\rule</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\rule{<var>width</var>}{<var>thickness</var>} +\rule[<var>raise</var>]{<var>width</var>}{<var>thickness</var>} +</pre></example> + +<para>Produce a <dfn>rule</dfn>, a filled-in rectangle. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="885">Halmos symbol</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="886">tombstone</indexterm></cindex> +<para>This produces a rectangular blob, sometimes called a Halmos symbol, +often used to mark the end of a proof. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\qedsymbol}{\rule{0.4em}{2ex}} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="887"><r>package</r>, <code>amsthm</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="888"><code>amsthm</code> <r>package</r></indexterm></cindex> + +<noindent></noindent> +<para>The <file>amsthm</file> package includes this command, with a somewhat +different-looking symbol. +</para> +<para>The mandatory arguments give the horizontal <var>width</var> and vertical +<var>thickness</var> of the rectangle. They are rigid lengths +(<pxref label="Lengths"><xrefnodename>Lengths</xrefnodename></pxref>). The optional argument <var>raise</var> 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> +<example endspaces=" "> +<pre xml:space="preserve">\noindent\rule{\textwidth}{0.4pt} +</pre></example> + +<noindent></noindent> +<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. +<xref label="_005cstrut"><xrefnodename>\strut</xrefnodename></xref> for examples. +</para> + +</section> +<node name="_005ctoday" spaces=" "><nodename>\today</nodename><nodeprev automatic="on">\rule</nodeprev><nodeup automatic="on">Special insertions</nodeup></node> +<section spaces=" "><sectiontitle><code>\today</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1021" mergedindex="cp">\today</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="889">date, today&textrsquo;s</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="890">today&textrsquo;s date</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\today +</pre></example> + +<para>Produce today&textrsquo;s date in the format <samp><var>month</var> <var>dd</var>, +<var>yyyy</var></samp>. An example of a date in that format is <samp>July 4, +1976</samp>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="891"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="892"><code>babel</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="893"><r>package</r>, <code>polyglossia</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="894"><code>polyglossia</code> <r>package</r></indexterm></cindex> + +<para>Multilingual packages such as <file>babel</file> or <file>polyglossia</file>, or +classes such as <file>lettre</file>, will localize <code>\today</code>. For example, +the following will output <samp>4 juillet 1976</samp>: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\year=1976 \month=7 \day=4 +\documentclass{minimal} +\usepackage[french]{babel} +\begin{document} +\today +\end{document} +</pre></example> + +<noindent></noindent> +<para><code>\today</code> uses the counters <code>\day</code>, <code>\month</code>, and +<code>\year</code> (<pxref label="_005cday-_0026-_005cmonth-_0026-_005cyear"><xrefnodename>\day & \month & \year</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="895"><r>package</r>, <code>datetime</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="896"><code>datetime</code> <r>package</r></indexterm></cindex> + +<para>A number of package on CTAN work with dates. One is <file>datetime</file> 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> + +</section> +</chapter> +<node name="Splitting-the-input" spaces=" "><nodename>Splitting the input</nodename><nodenext automatic="on">Front/back matter</nodenext><nodeprev automatic="on">Special insertions</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Splitting the input</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="897">splitting the input file</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="898">input file</indexterm></cindex> + +<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 +<cindex index="cp" spaces=" "><indexterm index="cp" number="899">root file</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="900">file, root</indexterm></cindex> +<dfn>root file</dfn>, on which &latex; compilation starts. This shows such +a file with five included files. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>This will bring in material from <file>pref.tex</file>, <file>chap1.tex</file>, +<file>chap2.tex</file>, <file>append.tex</file>, and <file>bib.tex</file>. If you compile +this file, and then comment out all of the lines inside +<code>\includeonly{...}</code> except for <code>chap1,</code> and compile again, +then &latex; will only process the material in the first chapter. +Thus, your output will appear more quickly and be shorter to print. +However, the advantage of the <code>\includeonly</code> 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><xref label="Larger-book-template"><xrefnodename>Larger book template</xrefnodename></xref> for another example of <code>\includeonly</code>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\endinput</menunode><menudescription><pre xml:space="preserve">Stop including material from a file. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\include & \includeonly</menunode><menudescription><pre xml:space="preserve">Conditionally include files. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\input</menunode><menudescription><pre xml:space="preserve">Unconditionally include a file. +</pre></menudescription></menuentry></menu> + + + +<node name="_005cendinput" spaces=" "><nodename>\endinput</nodename><nodenext automatic="on">\include & \includeonly</nodenext><nodeup automatic="on">Splitting the input</nodeup></node> +<section spaces=" "><sectiontitle><code>\endinput</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1022" mergedindex="cp">\endinput</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\endinput +</pre></example> + +<para>When you <code>\include{filename}</code>, inside <file>filename.tex</file> the +material after <code>\endinput</code> will not be included. This command is +optional; if <file>filename.tex</file> has no <code>\endinput</code> then &latex; +will read all of the file. +</para> +<para>For example, suppose that a document&textrsquo;s root file has +<code>\input{chap1}</code> and this is <file>chap1.tex</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter{One} +This material will appear in the document. +\endinput +This will not appear. +</pre></example> + +<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 <code>\endinput</code> halfway through the included file and see if the +error disappears. Now, knowing which half contains the error, moving +<code>\endinput</code> to halfway through that area further narrows down the +location. This process rapidly finds the offending line. +</para> +<para>After reading <code>\endinput</code>, &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 <code>\if...</code> with a +<code>\fi</code>. +</para> + +</section> +<node name="_005cinclude-_0026-_005cincludeonly" spaces=" "><nodename>\include & \includeonly</nodename><nodenext automatic="on">\input</nodenext><nodeprev automatic="on">\endinput</nodeprev><nodeup automatic="on">Splitting the input</nodeup></node> +<section spaces=" "><sectiontitle><code>\include</code> & <code>\includeonly</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1023" mergedindex="cp">\include</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1024" mergedindex="cp">\includeonly</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\includeonly{ % in document preamble + ... + <var>filename</var>, + ... + } + ... +\include{<var>filename</var>} % in document body +</pre></example> + +<para>Bring material from the external file <file><var>filename</var>.tex</file> into a +&latex; document. +</para> +<para>The <code>\include</code> command does three things: it executes +<code>\clearpage</code> (<pxref label="_005cclearpage-_0026-_005ccleardoublepage"><xrefnodename>\clearpage & \cleardoublepage</xrefnodename></pxref>), then it +inputs the material from <file><var>filename</var>.tex</file> into the document, +and then it does another <code>\clearpage</code>. This command can only +appear in the document body. The <code>\includeonly</code> command controls +which files will be read by &latex; under subsequent <code>\include</code> +commands. Its list of filenames is comma-separated, and it can only +appear in the preamble. +</para> +<para>This example root document, <file>constitution.tex</file>, brings in +three files, <file>preamble.tex</file>, <file>articles.tex</file>, and +<file>amendments.tex</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\includeonly{ + preamble, + articles, + amendments + } +\begin{document} +\include{preamble} +\include{articles} +\include{amendments} +\end{document} +</pre></example> + +<noindent></noindent> +<para>The file <file>preamble.tex</file> contains no special code; you have just +excerpted the chapter from <file>consitution.tex</file> and put it in a +separate file just for editing convenience. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter{Preamble} +We the People of the United States, +in Order to form a more perfect Union, ... +</pre></example> + +<noindent></noindent> +<para>Running &latex; on <file>constitution.tex</file> makes the material from the +three files appear in the document but also generates the auxiliary +files <file>preamble.aux</file>, <file>articles.aux</file>, and +<file>amendments.tex</file>. These contain information such as page numbers +and cross-references (<pxref label="Cross-references"><xrefnodename>Cross references</xrefnodename></pxref>). If you now comment out +<code>\includeonly</code>&textrsquo;s lines with <code>preamble</code> and <code>amendments</code> +and run &latex; again then the resulting document shows only the +material from <file>articles.tex</file>, not the material from +<file>preamble.tex</file> or <file>amendments.tex</file>. 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 <code>\includeonly</code> then +&latex; will include all the files you call for with <code>\include</code> +commands. +</para> +<para>The <code>\include</code> command makes a new page. To avoid that, see +<ref label="_005cinput"><xrefnodename>\input</xrefnodename></ref> (which, however, does not retain the auxiliary +information). +</para> +<para><xref label="Larger-book-template"><xrefnodename>Larger book template</xrefnodename></xref> for another example using <code>\include</code> +and <code>\includeonly</code>. That example also uses <code>\input</code> for some +material that will not necessarily start on a new page. +</para> +<para>File names can involve paths. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\includeonly{ + chapters/chap1, + } +\begin{document} +\include{chapters/chap1} +\end{document} +</pre></example> + +<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 <samp>amo amas amat</samp>, +this works under &tex; Live on GNU/Linux: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\includeonly{ + "amo\space amas\space amat" + } +\begin{document} +\include{"amo\space amas\space amat"} +\end{document} +</pre></example> + +<para>and this works under MiK&tex; on Windows: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\includeonly{ + {"amo amas amat"} + } +\begin{document} +\include{{"amo amas amat"}} +\end{document} +</pre></example> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="901">nested <code>\include</code>, not allowed</indexterm></cindex> +<para>You cannot use <code>\include</code> inside a file that is being included or +you get <samp>LaTeX Error: \include cannot be nested.</samp> The +<code>\include</code> command cannot appear in the document preamble; you will +get <samp>LaTeX Error: Missing \begin{document}</samp>. +</para> +<para>If a file that you <code>\include</code> does not exist, for instance if you +<code>\include{athiesm}</code> but you meant <code>\include{atheism}</code>, +then &latex; does not give you an error but will warn you <samp>No file +athiesm.tex.</samp> (It will also create <file>athiesm.aux</file>.) +</para> +<para>If you <code>\include</code> the root file in itself then you first get +<samp>LaTeX Error: Can be used only in preamble.</samp> Later runs get +<samp>TeX capacity exceeded, sorry [text input levels=15]</samp>. To fix +this, you must remove the inclusion <code>\include{root}</code> but also +delete the file <file><var>root</var>.aux</file> and rerun &latex;. +</para> + +</section> +<node name="_005cinput" spaces=" "><nodename>\input</nodename><nodeprev automatic="on">\include & \includeonly</nodeprev><nodeup automatic="on">Splitting the input</nodeup></node> +<section spaces=" "><sectiontitle><code>\input</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1025" mergedindex="cp">\input</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\input{<var>filename</var>} +</pre></example> + +<para>&latex; processes the file as if its contents were inserted in the +current file. For a more sophisticated inclusion mechanism see +<ref label="_005cinclude-_0026-_005cincludeonly"><xrefnodename>\include & \includeonly</xrefnodename></ref>. +</para> +<para>If <var>filename</var> does not end in <samp>.tex</samp> then &latex; first tries +the filename with that extension; this is the usual case. If +<var>filename</var> ends with <samp>.tex</samp> then &latex; looks for the +filename as it is. +</para> +<para>For example, this +</para> +<example endspaces=" "> +<pre xml:space="preserve">\input{macros} +</pre></example> + +<noindent></noindent> +<para>will cause &latex; to first look for <file>macros.tex</file>. 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 <file>macros.tex</file> then +&latex; tries the name <file>macros</file>, 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 <samp>amo amas amat</samp>, +this works under &tex; Live on GNU/Linux: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\input{"amo\space amas\space amat"} +</pre></example> + +<para>and this works under MiK&tex; on Windows: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\input{{"amo amas amat"}} +</pre></example> + + +</section> +</chapter> +<node name="Front_002fback-matter" spaces=" "><nodename>Front/back matter</nodename><nodenext automatic="on">Letters</nodenext><nodeprev automatic="on">Splitting the input</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Front/back matter</sectiontitle> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Table of contents etc.</menunode><menudescription><pre xml:space="preserve">Table of contents, list of figures, list of tables. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Indexes</menunode><menudescription><pre xml:space="preserve">Generate an index. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Glossaries</menunode><menudescription><pre xml:space="preserve">Generate a glossary. +</pre></menudescription></menuentry></menu> + + +<node name="Table-of-contents-etc_002e" spaces=" "><nodename>Table of contents etc.</nodename><nodenext automatic="on">Indexes</nodenext><nodeup automatic="on">Front/back matter</nodeup></node> +<section spaces=" "><sectiontitle>Table of contents etc.</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="902">table of contents, creating</indexterm></cindex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1026" mergedindex="cp">\tableofcontents</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1027" mergedindex="cp">.toc <r>file</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1028" mergedindex="cp">\listoffigures</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1029" mergedindex="cp">\listoftables</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1030" mergedindex="cp">.lof <r>file</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1031" mergedindex="cp">.lot <r>file</r></indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\tableofcontents +\listoffigures +\listoftables +</pre></example> + +<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 <code>\chapter</code>, etc. +</para> +<para>This example illustrates the first command, <code>\tableofcontents</code>. +&latex; will produce a table of contents on the book&textrsquo;s first page. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +% \setcounter{tocdepth}{1} +\begin{document} +\tableofcontents\newpage + ... +\chapter{...} + ... +\section{...} + ... +\subsection{...} + ... +\end{document} +</pre></example> + +<noindent></noindent> +<para>Uncommenting the second line would cause that table to contain chapter +and section listings but not subsection listings, because the +<code>\section</code> command has level 1. <xref label="Sectioning"><xrefnodename>Sectioning</xrefnodename></xref> for level +numbers of the sectioning units. For more on the <code>tocdepth</code> +<pxref label="Sectioning_002ftocdepth"><xrefnodename>Sectioning/tocdepth</xrefnodename></pxref>. +</para> +<para>Another example of the use of <code>\tableofcontents</code> is in <ref label="Larger-book-template"><xrefnodename>Larger +book template</xrefnodename></ref>. +</para> +<para>If you want a page break after the table of contents, write a +<code>\newpage</code> command after the <code>\tableofcontents</code> command, as +above. +</para> +<para>To make the table of contents &latex; stores the information in an +auxiliary file named <file><var>root-file</var>.toc</file> (<pxref label="Splitting-the-input"><xrefnodename>Splitting the +input</xrefnodename></pxref>). For example, this &latex; file <file>test.tex</file> +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{article} +\begin{document} +\tableofcontents\newpage +\section{First section} +\subsection{First subsection} + ... +</pre></example> + +<noindent></noindent> +<para>writes the following line to <file>test.toc</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\contentsline {section}{\numberline {1}First section}{2} +\contentsline {subsection}{\numberline {1.1}First subsection}{2} +</pre></example> + +<noindent></noindent> +<para>The <code>section</code> or <code>subsection</code> is the sectioning unit. The +hook <code>\numberline</code> lets you to change how the information appears +in the table of contents. Of its two arguments, <code>1</code> or <code>1.1</code> +is the sectioning unit number and <code>First section</code> or <code>First +subsection</code> is the title. Finally, <code>2</code> 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 <samp>Contents</samp> header. Just run it again. +</para> +<para>The commands <code>\listoffigures</code> and <code>\listoftables</code> produce a +list of figures and a list of tables. They work the same way as the +contents commands; for instance, these work with information stored in +<file>.lof</file> and <file>.lot</file> files. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="903"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="904"><code>babel</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="905"><r>package</r>, <code>polyglossia</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="906"><code>polyglossia</code> <r>package</r></indexterm></cindex> + +<para>To change the header for the table of contents page do something like +the first line here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\renewcommand{\contentsname}{Table of contents} +\renewcommand{\listfigurename}{Plots} +\renewcommand{\listtablename}{Tables} +</pre></example> + +<noindent></noindent> +<para>Similarly, the other two lines will do the other two. +Internationalization packages such as <file>babel</file> or <file>polyglossia</file> +will change the headers depending on the chosen base language. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="907"><r>package</r>, <code>tocloft</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="908"><code>tocloft</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="909"><r>package</r>, <code>tocbibbind</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="910"><code>tocbibbind</code> <r>package</r></indexterm></cindex> + +<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 <file>tocloft</file>. And, <file>tocbibbind</file> +will automatically add the bibliography, index, etc. to the table of +contents. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\addcontentsline</menunode><menudescription><pre xml:space="preserve">Add an entry to table of contents, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\addtocontents</menunode><menudescription><pre xml:space="preserve">Add text directly to table of contents file, etc. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\nofiles</menunode><menudescription><pre xml:space="preserve">Prevent writing to auxiliary files. +</pre></menudescription></menuentry></menu> + + +<node name="_005caddcontentsline" spaces=" "><nodename>\addcontentsline</nodename><nodenext automatic="on">\addtocontents</nodenext><nodeup automatic="on">Table of contents etc.</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\addcontentsline</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1032" mergedindex="cp">\addcontentsline</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="911">table of contents entry, manually adding</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addcontentsline{<var>ext</var>}{<var>unit</var>}{<var>text</var>} +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1033" mergedindex="cp">\contentsline</indexterm></findex> +<para>Add an entry to the file specified by <var>ext</var>. Usually <var>ext</var> is +one of <code>toc</code> for the table of contents, <code>lof</code> for the list of +figures, or <code>lot</code> for the list of tables. +</para> +<para>The following will result in an <samp>Appendices</samp> line in the table of +contents. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addcontentsline{toc}{section}{\protect\textbf{Appendices}} +</pre></example> + +<noindent></noindent> +<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 <code>\addcontentsline</code> command writes information to the file +<file><var>root-name</var>.<var>ext</var></file>. It writes that information as the +text of the command +<code>\contentsline{<var>unit</var>}{<var>text</var>}{<var>num</var>}</code>, where +<code><var>num</var></code> is the current value of counter <code><var>unit</var></code>. The +most common case is the table of contents and there <var>num</var> is the +page number of the first page of <var>unit</var>. +</para> +<para>This command is invoked by the sectioning commands <code>\chapter</code>, +etc., and also by <code>\caption</code> inside a float environment. But it is +also used by authors. For example, in a book to have the preface +unnumbered, you may use the starred <code>\chapter*</code>. But that does not +put in table of contents information, so you can enter it manually, as +here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\chapter*{Preface} +\addcontentsline{toc}{chapter}{\protect\numberline{}Preface} +</pre></example> + +<noindent></noindent> +<para>In the <file>.toc</file> file &latex; will put the line <code>\contentsline +{chapter}{\numberline {}Preface}{3}</code>; note the page number +<samp>3</samp>. +</para> +<!-- c xx how hardwired are these values? other unit names? --> + +<para>All of the arguments for <code>\addcontentsline</code> are required. +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">ext</itemformat></item> +</tableterm><tableitem><para>Typically one of the strings <code>toc</code> for the table of contents, +<code>lof</code> for the list of figures, or <code>lot</code> for the list of +tables. The filename extension of the information file. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">unit</itemformat></item> +</tableterm><tableitem><para>A string that depends on the value of the <var>ext</var> argument: +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code">toc</itemformat></item> +</tableterm><tableitem><para>For the table of contents, this is the name of a sectional unit: +<code>part</code>, <code>chapter</code>, <code>section</code>, <code>subsection</code>, etc. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">lof</itemformat></item> +</tableterm><tableitem><para>For the list of figures: <code>figure</code>. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">lot</itemformat></item> +</tableterm><tableitem><para>For the list of tables: <code>table</code>. +</para></tableitem></tableentry></table> + +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">text</itemformat></item> +</tableterm><tableitem><para>The text of the entry. You must <code>\protect</code> any commands that are +fragile (<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para></tableitem></tableentry></table> + +<para>The <code>\addcontentsline</code> command has an interaction with +<code>\include</code> (<pxref label="_005cinclude-_0026-_005cincludeonly"><xrefnodename>\include & \includeonly</xrefnodename></pxref>). If you use them at +the same level, as with +<code>\addcontentsline{...}{...}{...}\include{...}</code> then lines +in the table of contents can come out in the wrong order. The solution +is to move <code>\addcontentsline</code> into the file being included. +</para> +<para>If you use a <var>unit</var> that &latex; does not recognize, as here +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addcontentsline{toc}{setcion}{\protect\textbf{Appendices}} +</pre></example> + +<noindent></noindent> +<para>then you don&textrsquo;t get an error but the formatting in the table of contents +will not make sense. +</para> + +</subsection> +<node name="_005caddtocontents" spaces=" "><nodename>\addtocontents</nodename><nodenext automatic="on">\nofiles</nodenext><nodeprev automatic="on">\addcontentsline</nodeprev><nodeup automatic="on">Table of contents etc.</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\addtocontents</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1034" mergedindex="cp">\addtocontents{<var>ext</var>}{<var>text</var>}</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\addtocontents{<var>ext</var>}{<var>text</var>} +</pre></example> + +<para>Add <var>text</var>, which may be text or formatting commands, directly to +the auxiliary file with extension <var>ext</var>. 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 +<samp>Contents</samp> header. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\tableofcontents\newpage +\addtocontents{toc}{\protect\vspace*{3ex}} +</pre></example> + +<para>The <code>\addtocontents</code> command has two arguments. Both are +required. +</para> +<table commandarg="var" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="var">ext</itemformat></item> +</tableterm><tableitem><para>Typically one of: <file>toc</file> for the table of contents, <file>lof</file> for +the list of figures, or <file>lot</file> for the list of tables. The +extension of the file holding the information. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="var">text</itemformat></item> +</tableterm><tableitem><para>The text, and possibly commands, to be written. +</para></tableitem></tableentry></table> + +<para>The sectioning commands such as <code>\chapter</code> use the +<code>\addcontentsline</code> command to store information. This command +creates lines in the <file>.toc</file> auxiliary file containing the +<code>\contentsline</code> command (<pxref label="_005caddcontentsline"><xrefnodename>\addcontentsline</xrefnodename></pxref>). In contrast, +the command <code>\addtocontents</code> puts material directly in that file. +</para> +<para>The <code>\addtocontents</code> command has an interaction with +<code>\include</code> (<pxref label="_005cinclude-_0026-_005cincludeonly"><xrefnodename>\include & \includeonly</xrefnodename></pxref>). If you use them at +the same level, as with +<code>\addtocontents{...}{...}\include{...}</code> then lines in the +table of contents can come out in the wrong order. The solution is to +move <code>\addtocontents</code> into the file being included. +</para> + +</subsection> +<node name="_005cnofiles" spaces=" "><nodename>\nofiles</nodename><nodeprev automatic="on">\addtocontents</nodeprev><nodeup automatic="on">Table of contents etc.</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\nofiles</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1035" mergedindex="cp">\nofiles</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\nofiles +</pre></example> + +<para>Prevent &latex; from writing any auxiliary files. The only output will +be the <file>.log</file> and <file>.pdf</file> (or <file>.dvi</file>) files. This command +must go in the preamble. +</para> +<para>Because of the <code>\nofiles</code> command this example will not produce a +<file>.toc</file> file. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{book} +\nofiles +\begin{document} +\tableofcontents\newpage +\chapter{...} + ... +</pre></example> + +<noindent></noindent> +<para>&latex; will not erase any existing auxiliary files, so if you insert +the <code>\nofiles</code> command after you have run the file and gotten +a <file>.toc</file> then the table of contents page will continue to show +the old information. +</para> + +</subsection> +</section> +<node name="Indexes" spaces=" "><nodename>Indexes</nodename><nodenext automatic="on">Glossaries</nodenext><nodeprev automatic="on">Table of contents etc.</nodeprev><nodeup automatic="on">Front/back matter</nodeup></node> +<section spaces=" "><sectiontitle>Indexes</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="912">indexes</indexterm></cindex> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1036" mergedindex="cp">\makeindex</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1037" mergedindex="cp">\index</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="913"><file>.idx</file> file</indexterm></cindex> + +<para>This document has an index. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 + ... +</pre></example> + +<noindent></noindent> +<para>The <code>\usepackage{makeidx}</code> and <code>\makeindex</code> 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 <code>\index</code> command +(<pxref label="_005cindex"><xrefnodename>\index</xrefnodename></pxref>). When you run &latex;, the <code>\index</code> writes its +information to an auxiliary file <file><var>root-name</var>.idx</file>. Next, to +alphabetize and to do other manipulations you run an external command, +typically <command>makeindex</command> or <command>xindy</command> (<pxref label="makeindex"><xrefnodename>makeindex</xrefnodename></pxref>). +These output a file <file><var>root-name</var>.ind</file>. Finally, you bring the +information back into your document and typeset it with the +<code>\printindex</code> command (<pxref label="_005cprintindex"><xrefnodename>\printindex</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="914"><r>package</r>, <code>showidx</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="915"><code>showidx</code> <r>package</r></indexterm></cindex> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="916"><r>package</r>, <code>multind</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="917"><code>multind</code> <r>package</r></indexterm></cindex> + +<para>There are many packages that apply to indexing commands. The +<code>showidx</code> package causes each index entries to be shown in the +margin on the page where the entry appears. This can help in preparing +the index. The <code>multind</code> package supports multiple indexes. See +also the &tex; FAQ entry on this topic, +<url><urefurl>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind</urefurl></url>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\index</menunode><menudescription><pre xml:space="preserve">Declare an index entry. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">makeindex</menunode><menudescription><pre xml:space="preserve">Alphabetize index entries. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\printindex</menunode><menudescription><pre xml:space="preserve">Put the index here. +</pre></menudescription></menuentry></menu> + + +<node name="_005cindex" spaces=" "><nodename>\index</nodename><nodenext automatic="on">makeindex</nodenext><nodeup automatic="on">Indexes</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\index</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="918">index entry</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1038" mergedindex="cp">\index</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\index{<var>index-entry-string</var>} +</pre></example> + +<para>Declare an entry in the index. This command is fragile +(<pxref label="_005cprotect"><xrefnodename>\protect</xrefnodename></pxref>). +</para> +<para>For example, as described in <ref label="Indexes"><xrefnodename>Indexes</xrefnodename></ref>, one way to get an index from +what&textrsquo;s below is to compile the document with <code>pdflatex test</code>, then +process the index entries with <code>makeindex test</code>, and then compile +again with <code>pdflatex test</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">W~Ackermann (1896--1962).\index{Ackermann} + ... +Ackermann function\index{Ackermann!function} + ... +rate of growth\index{Ackermann!function!growth rate} +</pre></example> + +<noindent></noindent> +<para>All three index entries will get a page number, such as <samp>Ackermann, +22</samp>. &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 +<code>\index{Ackermann!function!growth rate!comparison}</code> then +<command>makeindex</command> says <samp>Scanning input file test.idx....done (4 +entries accepted, 1 rejected)</samp> and nothing appears in the index). +</para> +<para>If you enter a second <code>\index</code> with the same +<var>index-entry-string</var> then you will get a single index entry with two +page numbers (unless they happen to fall on the same page). Thus, +adding <code>as for Ackermann.\index{Ackermann}</code> later in the same +document as above will give an index entry like <samp>Ackermann, 22, +151</samp>. Also, you can enter the index entries in any order, so for +instance <code>\index{Ackermann!function}</code> could come before +<code>\index{Ackermann}</code>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="919">index, page range</indexterm></cindex> +<para>Get a page range in the output, like <samp>Hilbert, 23--27</samp>, as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">W~Ackermann (1896--1962).\index{Ackermann} + ... +D~Hilbert (1862--1943)\index{Ackermann!Hilbert\(} + ... +disapproved of his marriage.\index{Ackermann!Hilbert\)} +</pre></example> + +<noindent></noindent> +<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 +<code>\index{Jones!program}</code> and <code>\index{Jones!results}</code>, then +the output is the item <samp>Jones</samp> with no comma or page number, +followed by two subitems, like <samp>program, 50</samp> and <samp>results, +51</samp>. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="920">&textlsquo;see&textrsquo; and &textlsquo;see also&textrsquo; index entries</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="921">index entries, &textlsquo;see&textrsquo; and &textlsquo;see also&textrsquo;</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1039" mergedindex="cp">\seename</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1040" mergedindex="cp">\alsoname</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="922"><r>package</r>, <code>babel</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="923"><code>babel</code> <r>package</r></indexterm></cindex> + <cindex index="cp" spaces=" "><indexterm index="cp" number="924"><r>package</r>, <code>polyglossia</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="925"><code>polyglossia</code> <r>package</r></indexterm></cindex> + + +<para>Generate a index entry that says <samp>See</samp> by using a vertical bar +character: <code>\index{Ackermann!function|see{P\'eter's +function}}</code>. You can instead get <samp>See also</samp> with <code>seealso</code>. +(The text <samp>See</samp> is defined by <code>\seename</code>, and <samp>See also</samp> +by <code>\alsoname</code>. You can redefine these either by using an +internationalization package such as <file>babel</file> or <file>polyglossia</file>, +or directly as with <code>\renewcommand{\alsoname}[1]{Also see +#1}</code>.) +</para> +<para>The <samp>See</samp> feature is part of a more general functionality. After +the vertical bar you can put the name of a one-input command, as in +<code>\index{group|textit}</code> (note the missing backslash on the +<code>\textit</code> command) and the system will apply that command to the +page number, here giving something like <code>\textit{7}</code>. You can +define your own one-input commands, such as +<code>\newcommand{\definedpage}[1]{{\color{blue}#1}}</code> and then +<code>\index{Ackermann!function|definedpage}</code> will give a blue page +number (<pxref label="Color"><xrefnodename>Color</xrefnodename></pxref>). Another, less practical, example is this, +</para> +<!-- c credit Ian Thompson https://tex.stackexchange.com/a/272572/121234 --> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand\indexownpage[1]{#1, \thepage} + ... Epimenides.\index{self-reference|indexownpage} +</pre></example> + +<noindent></noindent> +<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> +<example endspaces=" "> +<pre xml:space="preserve">\index{Ackermann!function|(definedpage} + ... +\index{Ackermann!function|)} +</pre></example> + +<noindent></noindent> +<para>which outputs an index entry like <samp>function, 23--27</samp> where the page +number range is in blue. +</para> +<para>Consider an index entry such as <samp><U>03B1</U>-ring</samp>. Entering +it as <code>$\alpha$-ring</code> will cause it to be alphabetized according to +the dollar sign. You can instead enter it using an at-sign, as +<code>\index{alpha-ring&arobase;$\alpha$-ring}</code>. If you specify an entry +with an at-sign separating two strings, <code><var>pos</var>&arobase;<var>text</var></code>, +then <var>pos</var> gives the alphabetical position of the entry while +<var>text</var> produces the text of the entry. Another example is that +<code>\index{Saint Michael's College&arobase;SMC}</code> produces an index entry +<samp>SMC</samp> alphabetized into a different location than its spelling +would naturally give it. +</para> +<para>To put a <code>!</code>, or <code>&arobase;</code>, or <code>|</code> character in an index +entry, preceding it with a double quote, <code>"</code>. (The double quote +gets deleted before alphabetization.) +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="926"><r>package</r>, <code>index</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="927"><code>index</code> <r>package</r></indexterm></cindex> + +<para>A number of packages on CTAN have additional functionality beyond that +provided by <file>makeidx</file>. One is <file>index</file>, which allows for +multiple indices and contains a command +<code>\index*{<var>index-entry-string</var>}</code> that prints the +<var>index-entry-string</var> as well as indexing it. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1041" mergedindex="cp">\indexentry</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="928">idx file</indexterm></cindex> +<para>The <code>\index</code> command writes the indexing information to the file +<file><var>root-name</var>.idx</file> file. Specifically, it writes text of the +command +<code>\indexentry{<var>index-entry-string</var>}{<var>page-num</var>}</code>, +where <var>page-num</var> is the value of the <code>\thepage</code> counter. On +occasion, when the <code>\printindex</code> 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 <code>\index</code> command then you get a +message like this. +</para> +<example endspaces=" "> +<pre xml:space="preserve">Runaway argument? {Ackermann!function +! Paragraph ended before \&arobase;wrindex was complete. +</pre></example> + + +</subsection> +<node name="makeindex" spaces=" "><nodename>makeindex</nodename><nodenext automatic="on">\printindex</nodenext><nodeprev automatic="on">\index</nodeprev><nodeup automatic="on">Indexes</nodeup></node> +<subsection spaces=" "><sectiontitle><command>makeindex</command></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="929">index, processing</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1042" mergedindex="cp">makeindex</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="930"><command>makeindex</command> program</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="931"><file>.ind</file> file</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="932"><file>.idx</file> file</indexterm></cindex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">makeindex <var>filename</var> +makeindex -s <var>style-file</var> <var>filename</var> +makeindex <var>options</var> <var>filename0</var> ... +</pre></example> + +<para>Sort, and otherwise process, the index information in the auxiliary file +<var>filename</var>. This is a command line program. It takes one or more +raw index files, <file><var>filename</var>.idx</file> files, and produces the +actual index file, the <file><var>filename</var>.ind</file> file that is input by +<code>\printindex</code> (<pxref label="_005cprintindex"><xrefnodename>\printindex</xrefnodename></pxref>). +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="933"><file>.isty</file> file</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1043" mergedindex="cp">index, style file</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1044" mergedindex="cp">makeindex, style file</indexterm></findex> +<para>The first form of the command suffices for many uses. The second allows +you to format the index by using an <dfn>index style file</dfn>, a +<file>.isty</file> file. The third form is the most general; see the full +documentation on CTAN. +</para> +<para>This is a simple <file>.isty</file> file. +</para> +<example endspaces=" "> +<pre xml:space="preserve">% 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}" +</pre></example> + +<para>The description here covers only some of the index formatting +possibilities in <var>style-file</var>. For a full list see the documentation +on CTAN. +</para> +<para>A style file consists of a list of pairs: <var>specifier</var> and +<var>attribute</var>. These can appear in the file in any order. All of the +<var>attributes</var> are strings, except where noted. Strings are +surrounded with double quotes, <code>"</code>, and the maximum length of a +string is 144 characters. The <code>\n</code> is for a newline and <code>\t</code> +is for a tab. Backslashes are escaped with another backslash, +<code>\\</code>. If a line begins with a percent sign, <code>%</code>, then it is a +comment. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><anchor name="makeindex-preamble">makeindex preamble</anchor> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1045" mergedindex="cp">preamble</indexterm>preamble</itemformat></item> +</tableterm><tableitem><para>Preamble of the output file. Defines the context in which the index is +formatted. Default: <code>"\\begin{theindex}\n"</code>. +</para> +<anchor name="makeindex-postamble">makeindex postamble</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1046" mergedindex="cp">postamble</indexterm>postamble</itemformat></item> +</tableterm><tableitem><para>Postamble of the output file. Default: <code>"\n\n\\end{theindex}\n"</code>. +</para> +<anchor name="makeindex-group-skip">makeindex group skip</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1047" mergedindex="cp">group_skip</indexterm>group_skip</itemformat></item> +</tableterm><tableitem><findex index="fn" spaces=" "><indexterm index="fn" number="1048" mergedindex="cp">\indexspace</indexterm></findex> +<para>Traditionally index items are broken into groups, typically a group for +entries starting with <samp>a</samp>, etc. This specifier gives what is +inserted when a new group begins. Default: <code>"\n\n \\indexspace\n"</code> +(<code>\indexspace</code> is a rubber length with default value <code>10pt +plus5pt minus3pt</code>). +</para> +<anchor name="makeindex-letheadflag">makeindex letheadflag</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1049" mergedindex="cp">lethead_flag</indexterm>lethead_flag</itemformat></item> +</tableterm><tableitem><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 <code>group_skip</code> nothing +will be inserted before the group. If it is positive then at a new +letter the <code>lethead_prefix</code> and <code>lethead_suffix</code> 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 name="makeindex-lethead-prefix">makeindex lethead prefix</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1050" mergedindex="cp">lethead_prefix</indexterm>lethead_prefix</itemformat></item> +</tableterm><tableitem><para>If a new group begins with a different letter then this is the prefix +inserted before the new letter header. Default: <code>""</code> +</para> +<anchor name="makeindex-lethead-suffix">makeindex lethead suffix</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1051" mergedindex="cp">lethead_suffix</indexterm>lethead_suffix</itemformat></item> +</tableterm><tableitem><para>If a group begins with a different letter then this is the suffix +inserted after the new letter header. Default: <code>""</code>. +</para> +<anchor name="makeindex-item-0">makeindex item 0</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1052" mergedindex="cp">item_0</indexterm>item_0 </itemformat></item> +</tableterm><tableitem><para>What is put between two level 0 items. Default: <code>"\n \\item +"</code>. +</para> +<anchor name="makeindex-item-1">makeindex item 1</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1053" mergedindex="cp">item_1</indexterm>item_1</itemformat></item> +</tableterm><tableitem><para>Put between two level 1 items. Default: <code>"\n \\subitem "</code>. +</para> +<anchor name="makeindex-item-2">makeindex item 2</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1054" mergedindex="cp">item_2</indexterm>item_2</itemformat></item> +</tableterm><tableitem><para>put between two level 2 items. Default: <code>"\n \\subsubitem "</code>. +</para> +<anchor name="makeindex-item-01">makeindex item 01</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1055" mergedindex="cp">item_01</indexterm>item_01</itemformat></item> +</tableterm><tableitem><para>What is put between a level 0 item and a level 1 item. +Default: <code>"\n \\subitem "</code>. +</para> +<anchor name="makeindex-item-x1">makeindex item x1</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1056" mergedindex="cp">item_x1</indexterm>item_x1</itemformat></item> +</tableterm><tableitem><para>What is put between a level 0 item and a level 1 item in the +case that the level 0 item doesn&textrsquo;t have any page numbers (as in +<code>\index{aaa|see{bbb}}</code>). Default: <code>"\n \\subitem "</code>. +</para> +<anchor name="makeindex-item-12">makeindex item 12</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1057" mergedindex="cp">item_12</indexterm>item_12</itemformat></item> +</tableterm><tableitem><para>What is put between a level 1 item and a level 2 item. +Default: <code>"\n \\subsubitem "</code>. +</para> +<anchor name="makeindex-item-x2">makeindex item x2</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1058" mergedindex="cp">item_x2</indexterm>item_x2</itemformat></item> +</tableterm><tableitem><para>What is put between a level 1 item and a level 2 item, if the +level 1 item doesn&textrsquo;t have page numbers. Default: <code>"\n +\\subsubitem "</code>. +</para> +<anchor name="makeindex-delim-0">makeindex delim 0</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1059" mergedindex="cp">delim_0</indexterm>delim_0</itemformat></item> +</tableterm><tableitem><para>Delimiter put between a level 0 key and its first page +number. Default: a comma followed by a blank, <code>", "</code>. +</para> +<anchor name="makeindex-delim-1">makeindex delim 1</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1060" mergedindex="cp">delim_1</indexterm>delim_1</itemformat></item> +</tableterm><tableitem><para>Delimiter put between a level 1 key and its first page +number. Default: a comma followed by a blank, <code>", "</code>. +</para> +<anchor name="makeindex-delim-2">makeindex delim 2</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1061" mergedindex="cp">delim_2</indexterm>delim_2</itemformat></item> +</tableterm><tableitem><para>Delimiter between a level 2 key and its first page number. Default: +a comma followed by a blank, <code>", "</code>. +</para> +<anchor name="makeindex-delim-n">makeindex delim n</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1062" mergedindex="cp">delim_n</indexterm>delim_n</itemformat></item> +</tableterm><tableitem><para>Delimiter between two page numbers for the same key (at any +level). Default: a comma followed by a blank, <code>", "</code>. +</para> +<anchor name="makeindex-delim-r">makeindex delim r</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1063" mergedindex="cp">delim_r</indexterm>delim_r</itemformat></item> +</tableterm><tableitem><para>What is put between the starting and ending page numbers of a range. +Default: <code>"--"</code>. +</para> +<anchor name="makeindex-line-max">makeindex line max</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1064" mergedindex="cp">line_max</indexterm>line_max</itemformat></item> +</tableterm><tableitem><para>An integer. Maximum length of an index entry&textrsquo;s line in the output, +beyond which the line wraps. Default: <code>72</code>. +</para> +<anchor name="makeindex-indent-space">makeindex indent space</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1065" mergedindex="cp">indent_space</indexterm>indent_space</itemformat></item> +</tableterm><tableitem><para>What is inserted at the start of a wrapped line. Default: +<code>"\t\t"</code>. +</para> +<anchor name="makeindex-indent-length">makeindex indent length</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1066" mergedindex="cp">indent_length</indexterm>indent_length</itemformat></item> +</tableterm><tableitem><para>A number. The length of the wrapped line indentation. The default +<code>indent_space</code> is two tabs and each tab is eight spaces so the +default here is <code>16</code>. +</para> +<anchor name="makeindex-page-precedence">makeindex page precedence</anchor> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1067" mergedindex="cp">page_precedence</indexterm>page_precedence</itemformat></item> +</tableterm><tableitem><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 <code>r</code>, and numeric +or arabic <code>n</code>, and lowercase alphabetic <code>a</code>, and uppercase +roman <code>R</code>, and uppercase alphabetic <code>A</code>. Default: +<code>"rnaRA"</code>. +</para> +</tableitem></tableentry></ftable> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1068" mergedindex="cp">xindy</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="934"><command>xindy</command> program</indexterm></cindex> +<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> + +</subsection> +<node name="_005cprintindex" spaces=" "><nodename>\printindex</nodename><nodeprev automatic="on">makeindex</nodeprev><nodeup automatic="on">Indexes</nodeup></node> +<subsection spaces=" "><sectiontitle><command>\printindex</command></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="935">index, printing</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1069" mergedindex="cp">\printindex</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\printindex +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1070" mergedindex="cp">\printindex</indexterm></findex> +<para>Place the index into the output. +</para> +<para>To get an index you must first include +<code>\usepackage{makeidx}\makeindex</code> in the document preamble and +compile the document, then run the system command <command>makeindex</command>, +and then compile the document again. <xref label="Indexes"><xrefnodename>Indexes</xrefnodename></xref> for further +discussion and an example of the use of <code>\printindex</code>. +</para> + +</subsection> +</section> +<node name="Glossaries" spaces=" "><nodename>Glossaries</nodename><nodeprev automatic="on">Indexes</nodeprev><nodeup automatic="on">Front/back matter</nodeup></node> +<section spaces=" "><sectiontitle>Glossaries</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="936">glossary</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="937">glossaries</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="938">acronyms, list of</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1071" mergedindex="cp">\makeglossary</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1072" mergedindex="cp">\printglossaries</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\usepackage{glossaries} \makeglossaries + ... +\newglossaryentry{<var>label</var>}{<var>settings</var>} + ... +\gls{<var>label</var>}. + ... +\printglossaries +</pre></example> + +<para>The <file>glossaries</file> 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 <code>pdflatex filename</code>), then run the command line command +<code>makeglossaries filename</code>, and then compile the document again. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>That gives two things. In the main text it outputs <samp>... definition +of a Turing machine</samp>. In addition, in a separate sectional unit headed +<samp>Glossary</samp> there appears a description list. In boldface it says +<samp>Turing machine</samp> and the rest of the item says in normal type +<samp>A model of a machine &dots; Computer Science</samp>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1073" mergedindex="cp">\makeglossary</indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1074" mergedindex="cp">\printglossaries</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="939"><file>.glo</file> file</indexterm></cindex> +<para>The command <code>\makeglossary</code> opens the file that will contain the +entry information, <file><var>root-file</var>.glo</file>. Put the +<code>\printglossaries</code> command where you want the glossaries to appear +in your document. +</para> +<para>The <file>glossaries</file> package is very powerful. For instance, besides +the commands <code>\newglossaryentry</code> and <code>\gls</code>, there are similar +commands for a list of acronyms. See the package documentations on +CTAN. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\newglossaryentry</menunode><menudescription><pre xml:space="preserve">Declare the content of a glossary entry. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\gls</menunode><menudescription><pre xml:space="preserve">Give a page reference for a glossary entry. +</pre></menudescription></menuentry></menu> + + +<node name="_005cnewglossaryentry" spaces=" "><nodename>\newglossaryentry</nodename><nodenext automatic="on">\gls</nodenext><nodeup automatic="on">Glossaries</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\newglossaryentry</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="940">glossary, entries</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1075" mergedindex="cp">\newglossaryentry</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newglossaryentry{<var>label</var>} +{ + name={<var>name</var>}, + description={<var>description</var>}, + <var>other options</var>, ... +} +</pre></example> + +<para>or +</para> +<example endspaces=" "> +<pre xml:space="preserve">\longnewglossaryentry{<var>label</var>} +{ + name={<var>name</var>}, + <var>other options</var> ..., +} +{<var>description</var>} +</pre></example> + +<para>Declare a new entry for a glossary. The <var>label</var> must be unique for +the document. The settings associated with the label are pairs: +<code><var>key</var>=<var>value</var></code>. +</para> +<para>This puts the blackboard bold symbol for the real numbers <U>211D</U> in the +glossary. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newglossaryentry{R} +{ + name={\ensuremath{\mathbb{R}}}, + description={the real numbers}, +} +</pre></example> + +<para>Use the second command form if the <var>description</var> spans more than one +paragraph. +</para> +<para>For a full list of <var>key</var>s see the package documentation on CTAN but +here are a few. +</para> +<ftable commandarg="code" spaces=" " endspaces=" "> +<tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1076" mergedindex="cp">name</indexterm>name</itemformat></item> +</tableterm><tableitem><para>(Required.) The word, phrase, or symbol that you are defining. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1077" mergedindex="cp">description</indexterm>description</itemformat></item> +</tableterm><tableitem><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> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1078" mergedindex="cp">plural</indexterm>plural</itemformat></item> +</tableterm><tableitem><para>The plural form of <var>name</var>. Refer to the plural form using +<code>\glspl</code> or <code>\Glspl</code> (<pxref label="_005cgls"><xrefnodename>\gls</xrefnodename></pxref>). +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1079" mergedindex="cp">sort</indexterm>sort</itemformat></item> +</tableterm><tableitem><para>How to place this entry in the list of entries that the glossary holds. +</para> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code"><indexterm index="fn" number="1080" mergedindex="cp">symbol</indexterm>symbol</itemformat></item> +</tableterm><tableitem><para>A symbol, such as a mathematical symbol, besides the name. +</para> +</tableitem></tableentry></ftable> + + +</subsection> +<node name="_005cgls" spaces=" "><nodename>\gls</nodename><nodeprev automatic="on">\newglossaryentry</nodeprev><nodeup automatic="on">Glossaries</nodeup></node> +<subsection spaces=" "><sectiontitle><code>\gls</code></sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="941">glossary, entry reference</indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1081" mergedindex="cp">\gls</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\gls{<var>label</var>} +\glspl{<var>label</var>} +\Gls{<var>label</var>} +\Glspl{<var>label</var>} +</pre></example> + +<para>Refer to a glossary entry. The entries are declared with +<code>\newglossaryentry</code> (<pxref label="_005cnewglossaryentry"><xrefnodename>\newglossaryentry</xrefnodename></pxref>). +</para> +<para>This +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newglossaryentry{N}{% + name={the natural numbers}, + description={The numbers $0$, $1$, $2$, $\ldots$\&arobase;}, + symbol={\ensuremath{\mathbb{N}}}, + } + ... +Consider \gls{N}. +</pre></example> + +<noindent></noindent> +<para>gives the output <samp>Consider the natural numbers</samp>. +</para> +<para>The second command form <code>\glspl{<var>label</var>}</code> produces the plural +of <var>name</var> (by default it tries adding an <samp>s</samp>). The third form +capitalizes the first letter of <var>name</var>, as does the fourth form, +which also takes the plural. +</para> + +</subsection> +</section> +</chapter> +<node name="Letters" spaces=" "><nodename>Letters</nodename><nodenext automatic="on">Terminal input/output</nodenext><nodeprev automatic="on">Front/back matter</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Letters</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="942">letters, writing</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="943">writing letters</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\documentclass{letter} +\address{<var>senders address</var>} % return address +\signature{<var>sender name</var>} +\begin{document} +\begin{letter}{<var>recipient address</var>} +\opening{<var>salutation</var>} + <var>letter body</var> +\closing{<var>closing text</var>} +\end{letter} + ... +\end{document} +</pre></example> + +<para>Produce one or more letters. +</para> +<para>Each letter is in a separate <code>letter</code> environment, whose argument +<var>recipient address</var> often contains multiple lines separated with a +double backslash, (<code>\\</code>). For example, you might have: +</para> +<example endspaces=" "> +<pre xml:space="preserve"> \begin{letter}{Ninon de l'Enclos \\ + l'h\^otel Sagonne} + ... + \end{letter} +</pre></example> + +<para>The start of the <code>letter</code> environment resets the page number to 1, +and the footnote number to 1 also. +</para> +<para>The <var>sender address</var> and <var>sender name</var> 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 <var>sender address</var> +contains multiple lines separated by a double +backslash (<code>\\</code>). &latex; will put the <var>sender name</var> +under the closing, after a vertical space for the traditional +hand-written signature. +</para> +<para>Each <code>letter</code> environment body begins with a required +<code>\opening</code> command such as <code>\opening{Dear Madam or Sir:}</code>. +The <var>letter body</var> text is ordinary &latex; so it can contain +everything from enumerated lists to displayed math, except that commands +such as <code>\chapter</code> that make no sense in a letter are turned off. +Each <code>letter</code> environment body typically ends with a +<code>\closing</code> command such as <code>\closing{Yours,}</code>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1082" mergedindex="cp">\\ <r>for letters</r></indexterm></findex> +<para>Additional material may come after the <code>\closing</code>. You can say who +is receiving a copy of the letter with a command like <code>\cc{the +Boss \\ the Boss's Boss}</code>. There&textrsquo;s a similar <code>\encl</code> command for +a list of enclosures. And, you can add a postscript with <code>\ps</code>. +</para> +<para>&latex;&textrsquo;s default is to indent the sender name and the closing above it +by a length of <code>\longindentation</code>. By default this is +<code>0.5\textwidth</code>. To make them flush left, put +<code>\setlength{\longindentation}{0em}</code> in your preamble. +</para> +<para>To set a fixed date use something like +<code>\renewcommand{\today}{1958-Oct-12}</code>. If put in your preamble +then it will apply to all the letters. +</para> +<para>This example shows only one <code>letter</code> environment. The three lines +marked as optional are typically omitted. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<para>These commands are used with the <code>letter</code> class. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\address</menunode><menudescription><pre xml:space="preserve">Sender&textrsquo;s return address. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\cc</menunode><menudescription><pre xml:space="preserve">Carbon copy list. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\closing</menunode><menudescription><pre xml:space="preserve">Saying goodbye. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\encl</menunode><menudescription><pre xml:space="preserve">List of enclosed material. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\location</menunode><menudescription><pre xml:space="preserve">Sender&textrsquo;s organizational location. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\makelabels</menunode><menudescription><pre xml:space="preserve">Make address labels. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\name</menunode><menudescription><pre xml:space="preserve">Sender&textrsquo;s name, for the return address. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\opening</menunode><menudescription><pre xml:space="preserve">Saying hello. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\ps</menunode><menudescription><pre xml:space="preserve">Adding a postscript. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\signature</menunode><menudescription><pre xml:space="preserve">Sender&textrsquo;s signature. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\telephone</menunode><menudescription><pre xml:space="preserve">Sender&textrsquo;s phone number. +</pre></menudescription></menuentry></menu> + + +<node name="_005caddress" spaces=" "><nodename>\address</nodename><nodenext automatic="on">\cc</nodenext><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\address</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1083" mergedindex="cp">\address</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\address{<var>senders address</var>} +</pre></example> + +<para>Specify the return address, as it appears on the letter and on the +envelope. Separate multiple lines in <var>senders address</var> with a +double backslash, <code>\\</code>. +</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 <code>letter</code> 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 <code>\address</code> declaration then it +is formatted as a personal letter. +</para> +<para>Here is an example. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\address{Stephen Maturin \\ + The Grapes of the Savoy} +</pre></example> + + +</section> +<node name="_005ccc" spaces=" "><nodename>\cc</nodename><nodenext automatic="on">\closing</nodenext><nodeprev automatic="on">\address</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\cc</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1084" mergedindex="cp">\cc</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="944">cc list, in letters</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cc{<var>name0</var> \\ + ... } +</pre></example> + +<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 +<code>\closing</code>. Put the names on different lines by separating them +with a double backslash, <code>\\</code>, as in: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\cc{President \\ + Vice President} +</pre></example> + + +</section> +<node name="_005cclosing" spaces=" "><nodename>\closing</nodename><nodenext automatic="on">\encl</nodenext><nodeprev automatic="on">\cc</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\closing</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1085" mergedindex="cp">\closing</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="945">letters, ending</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="946">closing letters</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\closing{<var>text</var>} +</pre></example> + +<para>Produce the letter&textrsquo;s closing. This is optional, but usual. It appears +at the end of a letter, above a handwritten signature. For example: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\closing{Regards,} +</pre></example> + + +</section> +<node name="_005cencl" spaces=" "><nodename>\encl</nodename><nodenext automatic="on">\location</nodenext><nodeprev automatic="on">\closing</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\encl</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1086" mergedindex="cp">\encl</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="947">enclosure list</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\encl{<var>first enclosed object</var> \\ + ... } +</pre></example> + +<para>Produce a list of things included with the letter. This command is +optional; when it is used, it typically is put after <code>\closing</code>. +Separate multiple lines with a double backslash, <code>\\</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\encl{License \\ + Passport} +</pre></example> + + +</section> +<node name="_005clocation" spaces=" "><nodename>\location</nodename><nodenext automatic="on">\makelabels</nodenext><nodeprev automatic="on">\encl</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\location</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1087" mergedindex="cp">\location</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\location{<var>text</var>} +</pre></example> + +<para>The <var>text</var> appears centered at the bottom of the page. It only +appears if the page style is <code>firstpage</code>. +</para> + +</section> +<node name="_005cmakelabels" spaces=" "><nodename>\makelabels</nodename><nodenext automatic="on">\name</nodenext><nodeprev automatic="on">\location</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\makelabels</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1088" mergedindex="cp">\makelabels</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\makelabels % in preamble +</pre></example> + +<para>Optional, for a document that contains <code>letter</code> environments. If +you just put <code>\makelabels</code> 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 <code>\startlabels</code>, +<code>\mlabel</code>, and <code>\returnaddress</code> (and perhaps <code>\name</code>) in +the preamble. The command <code>\startlabels</code> sets the width, height, +number of columns, etc., of the page onto which the labels are printed. +The command <code>\mlabel{<var>return address</var>}{<var>recipient +address</var>}</code> produces the two labels (or one, if you choose to ignore the +<var>return address</var>) for each letter environment. The first argument, +<var>return address</var>, is the value returned by the macro +<code>\returnaddress</code>. The second argument, <var>recipient address</var>, is +the value passed in the argument to the <code>letter</code> environment. By +default <code>\mlabel</code> ignores the first argument, the <var>return +address</var>, 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> +<example endspaces=" "> +<pre xml:space="preserve">\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} +</pre></example> + +<noindent></noindent> +<para>The first column contains the return address twice. The second column +contains the address for each recipient. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="948"><r>package</r>, <code>envlab</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="949"><code>envlab</code> <r>package</r></indexterm></cindex> + +<para>The package <code>envlab</code> makes formatting the labels easier, with +standard sizes already provided. The preamble lines +<code>\usepackage[personalenvelope]{envlab}</code> and <code>\makelabels</code> +are all that you need to print envelopes. +</para> + +</section> +<node name="_005cname" spaces=" "><nodename>\name</nodename><nodenext automatic="on">\opening</nodenext><nodeprev automatic="on">\makelabels</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\name</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1089" mergedindex="cp">\name</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\name{<var>name</var>} +</pre></example> + +<para>Optional. Sender&textrsquo;s name, used for printing on the envelope together +with the return address. +</para> + +</section> +<node name="_005copening" spaces=" "><nodename>\opening</nodename><nodenext automatic="on">\ps</nodenext><nodeprev automatic="on">\name</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\opening</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1090" mergedindex="cp">\opening</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="950">letters, starting</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\opening{<var>salutation</var>} +</pre></example> + +<para>Required. Follows the <code>\begin{letter}{...}</code>. The argument +<var>salutation</var> is mandatory. For instance: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\opening{Dear John:} +</pre></example> + + +</section> +<node name="_005cps" spaces=" "><nodename>\ps</nodename><nodenext automatic="on">\signature</nodenext><nodeprev automatic="on">\opening</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\ps</code></sectiontitle> +<findex index="fn" spaces=" "><indexterm index="fn" number="1091" mergedindex="cp">\ps</indexterm></findex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="951">postscript, in letters</indexterm></cindex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ps{<var>text</var>} +</pre></example> + +<para>Add a postscript. This command is optional and usually is used after +<code>\closing</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\ps{P.S. After you have read this letter, burn it. Or eat it.} +</pre></example> + + +</section> +<node name="_005csignature" spaces=" "><nodename>\signature</nodename><nodenext automatic="on">\telephone</nodenext><nodeprev automatic="on">\ps</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\signature</code></sectiontitle> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\signature{<var>first line</var> \\ + ... } +</pre></example> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1092" mergedindex="cp">\signature</indexterm></findex> + +<para>The sender&textrsquo;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, <code>\\</code>. For example: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\signature{J Fred Muggs \\ + White House} +</pre></example> + +<para>&latex;&textrsquo;s default for the vertical space from the <code>\closing</code> text +down to the <code>\signature</code> text is <code>6\medskipamount</code>, which is +six times <code>\medskipamount</code> (where <code>\medskipamount</code> is equal to +a <code>\parskip</code>, which in turn is defined by default here to +0.7<dmn>em</dmn>). +</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 +<code>letter</code> environment and before the <code>\closing</code>. +</para> +<para>You can include a graphic in the signature as here. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\signature{\vspace{-6\medskipamount}\includegraphics{sig.png}\\ + My name} +</pre></example> + +<noindent></noindent> +<para>For this you must put <code>\usepackage{graphicx}</code> in the preamble +(<pxref label="Graphics"><xrefnodename>Graphics</xrefnodename></pxref>). +</para> + +<!-- c I think this is not a user-level command; it is used to keep from breaking --> +<!-- c the page between the closing and the signature --> +<!-- c @node \stopbreaks and \startbreaks --> +<!-- c @section @code{\stopbreaks} and @code{\startbreaks} --> + +<!-- c @findex \startbreak --> +<!-- c @findex \stopbreaks --> + +<!-- c @example --> +<!-- c @code{\stopbreaks} --> +<!-- c text --> +<!-- c @code{\startbreaks} --> +<!-- c @end example --> + +<!-- c The @code{\stopbreaks} inhibits page breaking. The @code{\startbreaks} resumes --> +<!-- c normal page breaking. --> +<!-- c --> +<!-- c --> +</section> +<node name="_005ctelephone" spaces=" "><nodename>\telephone</nodename><nodeprev automatic="on">\signature</nodeprev><nodeup automatic="on">Letters</nodeup></node> +<section spaces=" "><sectiontitle><code>\telephone</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1093" mergedindex="cp">\telephone</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\telephone{<var>number</var>} +</pre></example> + +<para>The sender&textrsquo;s telephone number. This is typically in the preamble, where +it applies to all letters. This only appears if the <code>firstpage</code> +pagestyle is selected. If so, it appears on the lower right of the +page. +</para> + +</section> +</chapter> +<node name="Terminal-input_002foutput" spaces=" "><nodename>Terminal input/output</nodename><nodenext automatic="on">Command line</nodenext><nodeprev automatic="on">Letters</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Terminal input/output</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="952">input/output, to terminal</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="953">terminal input/output</indexterm></cindex> + +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">\typein</menunode><menudescription><pre xml:space="preserve">Read text from the terminal. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">\typeout</menunode><menudescription><pre xml:space="preserve">Write text to the terminal. +</pre></menudescription></menuentry></menu> + + +<node name="_005ctypein" spaces=" "><nodename>\typein</nodename><nodenext automatic="on">\typeout</nodenext><nodeup automatic="on">Terminal input/output</nodeup></node> +<section spaces=" "><sectiontitle><code>\typein</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1094" mergedindex="cp">\typein</indexterm></findex> + +<para>Synopsis, one of: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\typein{<var>prompt-msg</var>} +\typein[<var>cmd</var>]{<var>prompt-msg</var>} +</pre></example> + +<para>Print <var>prompt-msg</var> 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> +<example endspaces=" "> +<pre xml:space="preserve">As long as I live I shall never forget \typein{Enter student name:} +</pre></example> + +<noindent></noindent> +<para>coupled with this command line interaction +</para> +<example endspaces=" "> +<pre xml:space="preserve">Enter student name: + +\&arobase;typein=Aphra Behn +</pre></example> + +<noindent></noindent> +<para>gives the output <samp>... never forget Aphra Behn</samp>. +</para> +<para>The first command version, <code>\typein{<var>prompt-msg</var>}</code>, causes +the input you typed to be processed as if it had been included in the +input file in place of the <code>\typein</code> command. +</para> +<para>In the second command version the optional argument <code><var>cmd</var></code> +argument must be a command name &textmdash; 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> +<example endspaces=" "> +<pre xml:space="preserve">\typein[\student]{Enter student name:} +\typeout{Recommendation for \student .} +</pre></example> + +<noindent></noindent> +<para>gives this output on the command line, +</para> +<example endspaces=" "> +<pre xml:space="preserve">Enter student name: + +\student=John Dee +Recommendation for John Dee. +</pre></example> + +<noindent></noindent> +<para>where the user has entered <samp>John Dee.</samp> +</para> + +</section> +<node name="_005ctypeout" spaces=" "><nodename>\typeout</nodename><nodeprev automatic="on">\typein</nodeprev><nodeup automatic="on">Terminal input/output</nodeup></node> +<section spaces=" "><sectiontitle><code>\typeout</code></sectiontitle> + +<findex index="fn" spaces=" "><indexterm index="fn" number="1095" mergedindex="cp">\typeout</indexterm></findex> + +<para>Synopsis: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\typeout{<var>msg</var>} +</pre></example> + +<para>Print <code>msg</code> on the terminal and in the <code>log</code> file. +</para> +<para>This +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\student}{John Dee} +\typeout{Recommendation for \student .} +</pre></example> + +<noindent></noindent> +<para>outputs <samp>Recommendation for John Dee</samp>. Like what happens here with +<code>\student</code>, commands that are defined with <code>\newcommand</code> or +<code>\renewcommand</code> (among others) are replaced by their definitions +before being printed. +</para> +<para>&latex;&textrsquo;s usual rules for treating multiple spaces as a single space +and ignoring spaces after a command name apply to <code>msg</code>. As above, +use the command <code>\space</code> to get a single space, independent of +surrounding spaces. Use <code>^^J</code> to get a newline. Get a percent +character with <code>\csname &arobase;percentchar\endcsname</code>. +</para> +<para>This command can be useful for simple debugging, as here: +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newlength{\jhlength} +\setlength{\jhlength}{5pt} +\typeout{The length is \the\jhlength.} +</pre></example> + +<noindent></noindent> +<para>produces on the command line <samp>The length is 5.0pt</samp>. +</para> + +</section> +</chapter> +<node name="Command-line" spaces=" "><nodename>Command line</nodename><nodenext automatic="on">Document templates</nodenext><nodeprev automatic="on">Terminal input/output</nodeprev><nodeup automatic="on">Top</nodeup></node> +<chapter spaces=" "><sectiontitle>Command line</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="954">command line</indexterm></cindex> + +<para>Synopsis (from a terminal command line): +</para> +<example endspaces=" "> +<pre xml:space="preserve">pdflatex <var>options</var> <var>argument</var> +</pre></example> + +<para>Run &latex; on <var>argument</var>. In place of <command>pdflatex</command> you can +also use <command>xelatex</command>, or <code>lualatex</code>, or <code>dviluatex</code>, or +<code>latex</code>. +</para> +<para>For example, this will run &latex; on the file <file>thesis.tex</file>, +creating the output <file>thesis.pdf</file>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">pdflatex thesis +</pre></example> + +<noindent></noindent> +<para><findex index="fn" spaces=" "><indexterm index="fn" number="1096" mergedindex="cp">.tex, <r>default extension</r></indexterm></findex> +Note that <file>.tex</file> is the default file extension. +</para> +<para>pdf&tex; is a development of the original &tex; program, as are +Xe&tex; and Lua&tex; (<pxref label="TeX-engines"><xrefnodename>&tex; engines</xrefnodename></pxref>). 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 <code>dvilualatex</code>, then you will get DVI. The description here +assumes pdf&latex;. +</para> +<para><xref label="Command-line-options"><xrefnodename>Command line options</xrefnodename></xref>, for a selection of the most useful +command line options. As to <var>argument</var>, 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 <var>argument</var> begins with a +backslash then the system will interpret it as a line of &latex; +input, which can be used for special effects (<pxref label="Command-line-input"><xrefnodename>Command line +input</xrefnodename></pxref>). +</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 +<code><control>-D</code>. +</para> +<para>If &latex; finds an error in your document then by default it stops and +asks you about it. <xref label="Recovering-from-errors"><xrefnodename>Recovering from errors</xrefnodename></xref> for an outline of what +to do. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator=":: ">Command line options</menunode><menudescription><pre xml:space="preserve">Read text from the terminal. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Command line input</menunode><menudescription><pre xml:space="preserve">Write text to the terminal. +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator=":: ">Recovering from errors</menunode><menudescription><pre xml:space="preserve">When something goes wrong. +</pre></menudescription></menuentry></menu> + + +<node name="Command-line-options" spaces=" "><nodename>Command line options</nodename><nodenext automatic="on">Command line input</nodenext><nodeup automatic="on">Command line</nodeup></node> +<section spaces=" "><sectiontitle>Command line options</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="955">options, command line</indexterm></cindex> + +<para>These are the command-line options relevant to ordinary document +authoring. For a full list, try running <samp>latex --help</samp> from the +command line. +</para> +<para>With many implementations you can specify command line options by +prefixing them with <samp>-</samp> or <samp>--</samp>. This is the case for +both &tex; Live (and Mac&tex;) and MiK&tex;. We will use both +conventions interchangeably. +</para> +<table commandarg="code" spaces=" " endspaces=" "> +<beforefirstitem><findex index="fn" spaces=" "><indexterm index="fn" number="1097" mergedindex="cp">--version <r>command-line option</r></indexterm></findex> +</beforefirstitem><tableentry><tableterm><item spaces=" "><itemformat command="code">-version</itemformat></item> +</tableterm><tableitem><para>Show the current version, like <samp>pdfTeX 3.14159265-2.6-1.40.16 (TeX +Live 2015/Debian)</samp> along with a small amount of additional information, +and exit. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1098" mergedindex="cp">--help <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-help</itemformat></item> +</tableterm><tableitem><para>Give a brief usage message that is useful as a prompt and exit. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1099" mergedindex="cp">--interaction <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-interaction=<var>mode</var></itemformat></item> +</tableterm><tableitem><para>&tex; compiles a document in one of four interaction modes: +<code>batchmode</code>, <code>nonstopmode</code>, <code>scrollmode</code>, +<code>errorstopmode</code>. In <dfn>errorstop mode</dfn> (the default), &tex; +stops at each error and asks for user intervention. In <dfn>batch +mode</dfn> it prints nothing on the terminal, errors are scrolled as if the +user hit <code><return></code> at every error, and missing files cause the +job to abort. In <dfn>nonstop mode</dfn>, diagnostic message appear on the +terminal but as in batch mode there is no user interaction. In +<dfn>scroll mode</dfn>, &tex; only stops for missing files or keyboard +input. +</para> +<para>For instance, starting &latex; with this command line +</para> +<example endspaces=" "> +<pre xml:space="preserve">pdflatex -interaction=batchmode <var>filename</var> +</pre></example> + +<noindent></noindent> +<para>eliminates most terminal output. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1100" mergedindex="cp">--jobname <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-jobname=<var>string</var></itemformat></item> +</tableterm><tableitem><para>Set the value of &tex;&textrsquo;s <code>jobname</code> to the string. The log file +and output file will then be named <file><var>string</var>.log</file> and +<file><var>string</var>.pdf</file>. +</para> +<para>When you run <code><command>pdflatex</command> <var>options</var> <var>argument</var></code>, if +<var>argument</var> does not start with a backslash then &tex; considers it +the name of a file to input. Otherwise it waits for the first +<code>\input</code> instruction and the name of the input file will be the job +name. This is used to name the log file the output file. The +<code>jobname</code> option overrides that process and directly specifies the +name. <xref label="Command-line-input"><xrefnodename>Command line input</xrefnodename></xref> for an example of its use. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1101" mergedindex="cp">--output-directory <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-output-directory=<var>directory</var></itemformat></item> +</tableterm><tableitem><para>Write files in the directory <var>directory</var>. It must already exist. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1102" mergedindex="cp">--shell-escape <r>command-line option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1103" mergedindex="cp">--no-shell-escape <r>command-line option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1104" mergedindex="cp">--enable-write18 <r>command-line option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1105" mergedindex="cp">--disable-write18 <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">--shell-escape</itemformat></item> +<itemx spaces=" "><itemformat command="code">--no-shell-escape</itemformat></itemx> +<itemx spaces=" "><itemformat command="code">--enable-write18</itemformat></itemx> +<itemx spaces=" "><itemformat command="code">--disable-write18</itemformat></itemx> +</tableterm><tableitem><para>Enable or disable <code>\write18{<var>shell command</var>}</code>. The first two +options are for with &tex; Live or Mac&tex; while the second two are +for MiK&tex;. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="956"><r>package</r>, <code>sagetex</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="957"><code>sagetex</code> <r>package</r></indexterm></cindex> + +<para>Sometimes you want to run external system commands from inside a +&latex; file. For instance the package <file>sagetex</file> allows you to +have the mathematics software system <i>Sage</i> do calculations or draw +graphs and then incorporate that output in your document. For this +&tex; provides the <code>\write18</code> command. +</para> +<para>But with this functionality enabled, security issues could happen if you +compiled a &latex; file from the Internet. By default <code>\write18</code> +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 <code>no-shell-escape</code>, and in +your document you call <code>\write18{ls -l}</code>, then you do not get an +error but the log file says <samp>runsystem(ls -l)...disabled</samp>. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1106" mergedindex="cp">--halt-on-error <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-halt-on-error</itemformat></item> +</tableterm><tableitem><para>Stop processing at the first error. +</para> +<findex index="fn" spaces=" "><indexterm index="fn" number="1107" mergedindex="cp">--file-line-error <r>command-line option</r></indexterm></findex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1108" mergedindex="cp">--no-file-line-error <r>command-line option</r></indexterm></findex> +</tableitem></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-file-line-error</itemformat></item> +</tableterm></tableentry><tableentry><tableterm><item spaces=" "><itemformat command="code">-no-file-line-error</itemformat></item> +</tableterm><tableitem><para>Enable or disable <code><var>filename</var>:<var>lineno</var>:<var>error</var></code>-style +error messages. These are only available with &tex; Live or Mac&tex;. +</para></tableitem></tableentry></table> + + +</section> +<node name="Command-line-input" spaces=" "><nodename>Command line input</nodename><nodenext automatic="on">Recovering from errors</nodenext><nodeprev automatic="on">Command line options</nodeprev><nodeup automatic="on">Command line</nodeup></node> +<section spaces=" "><sectiontitle>Command line input</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="958">input, on command line</indexterm></cindex> + +<para>As part of the command line invocation <code>pdflatex <var>options</var> +<var>argument</var></code> you can specify arbitrary &latex; input by starting +<var>argument</var> with a backslash. This allows you to do some special +effects. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="959"><r>package</r>, <code>hyperref</code></indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="960"><code>hyperref</code> <r>package</r></indexterm></cindex> + +<para>For example, this file (which uses the <file>hyperref</file> package for +hyperlinks) can produce two kinds of output, one for paper and one for a +PDF. +</para> +<example endspaces=" "> +<pre xml:space="preserve">\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 + ... +</pre></example> + +<noindent></noindent> +<para>Compiling this document <file>book.tex</file> with the command line +<code>pdflatex book</code> will give the <samp>CTAN</samp> link in blue. But +compiling it with <code>pdflatex "\def\paperversion{}\input book.tex"</code> +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 <file>main.tex</file> you can compile +two different versions. +</para> +<!-- c credit Paul Gaborit: https://tex.stackexchange.com/a/220101/121234 --> +<example endspaces=" "> +<pre xml:space="preserve">pdflatex -jobname=students "\def\student{}\input{main}" +pdflatex -jobname=teachers "\def\teachers{}\input{main}" +</pre></example> + +<noindent></noindent> +<para>The <code>jobname</code> option is there because otherwise both files would be +called <file>main.pdf</file> and the second would overwrite the first. +</para> +<para>A final example. This loads the package <file>graphicx</file> with the option +<code>draft</code> +</para> +<!-- c credit Herbert Voss: https://tex.stackexchange.com/a/17236/121234 --> +<example endspaces=" "> +<pre xml:space="preserve">pdflatex -jobname=aa "\RequirePackage[draft]{graphicx}\input{aa.tex}" +</pre></example> + +<noindent></noindent> +<para>so the graphic files are read for their size information but not +incorporated into the PDF. (The <code>jobname</code> option is there because +otherwise the output file would be <file>graphicx.pdf</file>, as +<code>\RequirePackage</code> does an <code>\input</code> of its own.) +</para> + +</section> +<node name="Recovering-from-errors" spaces=" "><nodename>Recovering from errors</nodename><nodeprev automatic="on">Command line input</nodeprev><nodeup automatic="on">Command line</nodeup></node> +<section spaces=" "><sectiontitle>Recovering from errors</sectiontitle> + +<para>If &latex; finds an error in your document then it gives you an error +message and prompts you with a question mark, <code>?</code>. For instance, +running &latex; on this file +</para> +<example endspaces=" "> +<pre xml:space="preserve">\newcommand{\NP}{\ensuremath{\textbf{NP}}} +The \PN{} problem is a million dollar one. +</pre></example> + +<noindent></noindent> +<para>causes it show this, and wait for input. +</para> +<example endspaces=" "> +<pre xml:space="preserve">! Undefined control sequence. +l.5 The \PN + {} problem is a million dollar one. +? +</pre></example> + +<noindent></noindent> +<para>The simplest thing is to enter <samp>x</samp> and <code><return></code> and fix the +typo. You could instead enter <samp>?</samp> and <code><return></code> to see other +options. +</para> +<cindex index="cp" spaces=" "><indexterm index="cp" number="961"><samp>*</samp> prompt</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="962">prompt, <samp>*</samp></indexterm></cindex> +<findex index="fn" spaces=" "><indexterm index="fn" number="1109" mergedindex="cp">\stop</indexterm></findex> +<para>There are two other error scenarios. The first is that you forgot to +include the <code>\end{document}</code> or misspelled it. In this case +&latex; gives you a <samp>*</samp> prompt. You can get back to the command +line by typing <code>\stop</code> and <code><return></code>. +</para> +<para>The last scenario is that you mistyped the file name. For instance, +instead of <code>pdflatex test</code> you might type <code>pdflatex tste</code>. +</para> +<example endspaces=" "> +<pre xml:space="preserve">! I can't find file `tste'. +<*> tste + +(Press Enter to retry, or Control-D to exit) +Please type another input file name: +</pre></example> + +<noindent></noindent> +<para>The simplest thing is to enter <code><Control></code> and <samp>d</samp> (holding +them down at the same time), and then retype the correct command line. +</para> + +</section> +</chapter> +<node name="Document-templates" spaces=" "><nodename>Document templates</nodename><nodenext automatic="on">Index</nodenext><nodeprev automatic="on">Command line</nodeprev><nodeup automatic="on">Top</nodeup></node> +<appendix spaces=" "><sectiontitle>Document templates</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="963">document templates</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="964">templates, document</indexterm></cindex> + +<para>Although not reference material, perhaps these document templates will +be useful. Additional template resources are listed at +<url><urefurl>http://tug.org/interest.html#latextemplates</urefurl></url>. +</para> +<menu endspaces=" "> +<menuentry leadingtext="* "><menunode separator="::">beamer template</menunode><menudescription><pre xml:space="preserve"> +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator="::">article template</menunode><menudescription><pre xml:space="preserve"> +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator="::">book template</menunode><menudescription><pre xml:space="preserve"> +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator="::">Larger book template</menunode><menudescription><pre xml:space="preserve"> +</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode separator="::">tugboat template</menunode><menudescription><pre xml:space="preserve"> +</pre></menudescription></menuentry></menu> + + +<node name="beamer-template" spaces=" "><nodename>beamer template</nodename><nodenext automatic="on">article template</nodenext><nodeup automatic="on">Document templates</nodeup></node> +<section spaces=" "><sectiontitle><code>beamer</code> template</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="965"><code>beamer</code> template and class</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="966">template, <code>beamer</code></indexterm></cindex> + +<para>The <code>beamer</code> class creates presentation slides. It has a vast +array of features, but here is a basic template: +</para> +<verbatim xml:space="preserve"> +\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} +</verbatim> + +<para>One web resource for this: +<url><urefurl>http://robjhyndman.com/hyndsight/beamer/</urefurl></url>. +</para> + +</section> +<node name="article-template" spaces=" "><nodename>article template</nodename><nodenext automatic="on">book template</nodenext><nodeprev automatic="on">beamer template</nodeprev><nodeup automatic="on">Document templates</nodeup></node> +<section spaces=" "><sectiontitle><code>article</code> template</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="967">template, <code>article</code></indexterm></cindex> + +<verbatim xml:space="preserve"> +\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} +</verbatim> + + +</section> +<node name="book-template" spaces=" "><nodename>book template</nodename><nodenext automatic="on">Larger book template</nodenext><nodeprev automatic="on">article template</nodeprev><nodeup automatic="on">Document templates</nodeup></node> +<section spaces=" "><sectiontitle><code>book</code> template</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="968">template, <code>book</code></indexterm></cindex> + +<para>This is a straightforward template for a book. See <xref label="Larger-book-template"><xrefnodename>Larger book +template</xrefnodename></xref> for a more elaborate one. +</para> +<verbatim xml:space="preserve"> +\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} +</verbatim> + + +</section> +<node name="Larger-book-template" spaces=" "><nodename>Larger book template</nodename><nodenext automatic="on">tugboat template</nodenext><nodeprev automatic="on">book template</nodeprev><nodeup automatic="on">Document templates</nodeup></node> +<section spaces=" "><sectiontitle>Larger <code>book</code> template</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="969">template, <code>book</code></indexterm></cindex> + +<para>This is a more elaborate template for a book. It has +<code>\frontmatter</code>, <code>\mainmatter</code>, and <code>\backmatter</code> to +control the typography of the three main areas of a book +(<pxref label="_005cfrontmatter-_0026-_005cmainmatter-_0026-_005cbackmatter"><xrefnodename>\frontmatter & \mainmatter & \backmatter</xrefnodename></pxref>). The book has a +bibliography and an index. +</para> +<para>Notable is that it uses <code>\include</code> and <code>\includeonly</code> +(<pxref label="Splitting-the-input"><xrefnodename>Splitting the input</xrefnodename></pxref>). While you are working on a chapter you +can comment out all the other chapter entries from the argument to +<code>\includeonly</code>. That will speed up compilation without losing any +information such as cross-references. (Material that does not need to +come on a new page is brought in with <code>\input</code> instead of +<code>\include</code>. You don&textrsquo;t get the cross-reference benefit this way.) +</para> +<verbatim xml:space="preserve"> +\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} +</verbatim> + + +</section> +<node name="tugboat-template" spaces=" "><nodename>tugboat template</nodename><nodeprev automatic="on">Larger book template</nodeprev><nodeup automatic="on">Document templates</nodeup></node> +<section spaces=" "><sectiontitle><code>tugboat</code> template</sectiontitle> + +<cindex index="cp" spaces=" "><indexterm index="cp" number="970">template, TUGboat</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="971">TUGboat template</indexterm></cindex> +<cindex index="cp" spaces=" "><indexterm index="cp" number="972"><code>ltugboat</code> class</indexterm></cindex> + +<para><cite>TUGboat</cite> is the journal of the &tex; Users Group, +<url><urefurl>http://tug.org/TUGboat</urefurl></url>. +</para> +<verbatim xml:space="preserve"> +\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} +</verbatim> + + +</section> +</appendix> +<node name="Index" spaces=" "><nodename>Index</nodename><nodeprev automatic="on">Document templates</nodeprev><nodeup automatic="on">Top</nodeup></node> +<unnumbered spaces=" "><sectiontitle>Index</sectiontitle> + +<!-- c Keep `Command Index' working for ltx-help.el. --> +<anchor name="Command-Index">Command Index</anchor> + +<printindex value="cp" line=" cp"></printindex> + +</unnumbered> +<bye></bye> +</texinfo> |