diff options
author | Karl Berry <karl@freefriends.org> | 2017-08-08 20:38:58 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-08-08 20:38:58 +0000 |
commit | 75f529a8c99a457b98e31992cb965bbc447813c8 (patch) | |
tree | dc201d667d9cefaca2e3e2297e949a32daca2af3 /Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk | |
parent | bb5a582a3651ea6fe3c4fce9580cc248f5953f43 (diff) |
latex2e-help-texinfo (8aug17)
git-svn-id: svn://tug.org/texlive/trunk@44985 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk')
-rw-r--r-- | Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk | 2352 |
1 files changed, 1632 insertions, 720 deletions
diff --git a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk index dd1f9b3d58a..b282655c48e 100644 --- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk +++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk @@ -4,19 +4,20 @@ <!ENTITY latex "LaTeX"> ]> <book id="latex2e.dbk" lang="en"> -<title>&latex;2e unofficial reference manual (October 2015)</title> +<title>&latex;2e unofficial reference manual (November 2016)</title> <!-- %**end of header (This is for running Texinfo on a region.) --> <!-- latex 2.09 commands should all be present now, --> <!-- xx but latex2e stuff is missing. --> <!-- xx random list of a few of the missing items is at the end of this file --> <!-- --> +<!-- xx misc commands from clsguide.pdf --> <!-- xx ending a run with errors --> <!-- xx ctan, distributions, components of TeX --> <!-- xx classes and packages - required, additional, useful; oberdiek; fonts --> <!-- --> -<!-- xx merge http://mirror.ctan.org/info/latex-info/ (alt-latex-info) --> -<!-- xx merge http://mirror.ctan.org/latex2e-reference.tar.gz --> +<!-- xx merge http://ctan.org/pkg/latex-info (CTAN package latex-info) --> +<!-- xx merge http://ctan.org/pkg/latex2e-reference --> <!-- xx merge permuted-index --> <!-- xx merge latex-manual from savannah --> <!-- xx merge display style math --> @@ -28,7 +29,7 @@ <!-- xx See also http://ctan.org/pkg/macros2e. --> <bookinfo><legalnotice><para>This document is an unofficial reference manual for &latex;, a -document preparation system, version of October 2015. +document preparation system, version of November 2016. </para> <para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the VMS Help Library. The pre-translation version was written by @@ -43,12 +44,13 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n text was directly copied). </para> <para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, -2014, 2015 Karl Berry. +2014, 2015, 2016 Karl Berry. Copyright 1988, 1994, 2007 Stephen Gilmore. Copyright 1994, 1995, 1996 Torsten Martinsen. </para> +<!-- start of License --> <para>Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @@ -61,11 +63,12 @@ notice identical to this one. </para> <para>Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. +<!-- end of License --> </para></legalnotice></bookinfo> <para>This document is an unofficial reference manual for &latex;, a -document preparation system, version of October 2015. +document preparation system, version of November 2016. </para> <para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the VMS Help Library. The pre-translation version was written by @@ -80,12 +83,13 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n text was directly copied). </para> <para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, -2014, 2015 Karl Berry. +2014, 2015, 2016 Karl Berry. Copyright 1988, 1994, 2007 Stephen Gilmore. Copyright 1994, 1995, 1996 Torsten Martinsen. </para> +<!-- start of License --> <para>Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @@ -98,16 +102,19 @@ notice identical to this one. </para> <para>Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. +<!-- end of License --> </para> <!-- Best Effort Symbol --> + + <chapter label="" id="Top"> <title>&latex;2e: An unofficial reference manual</title> <para>This document is an unofficial reference manual (version of -October 2015) for &latex;2e, a document preparation system. +November 2016) for &latex;2e, a document preparation system. </para> @@ -264,7 +271,7 @@ it to a PostScript <literal>.ps</literal> file with <command>dvips</command> or Portable Document Format <literal>.pdf</literal> file with <command>dvipdfmx</command>. The contents of the file can be dumped in human-readable form with <command>dvitype</command>. A vast array of other DVI utility programs are -available (<ulink url="http://mirror.ctan.org/tex-archive/dviware">http://mirror.ctan.org/tex-archive/dviware</ulink>). +available (<ulink url="http://mirror.ctan.org/dviware">http://mirror.ctan.org/dviware</ulink>). </para> </listitem></varlistentry><varlistentry><term><literal>.pdf</literal> </term><listitem><indexterm role="fn"><primary>.pdf file</primary></indexterm> @@ -436,7 +443,7 @@ commands it covers (barring unintentional omissions, a.k.a. bugs). <para>Synopsis: </para> <screen>\begin{<replaceable>environment name</replaceable>} - .. + ... \end{<replaceable>environment name</replaceable>} </screen> <para>An area of &latex; source, inside of which there is a distinct @@ -444,10 +451,12 @@ behavior. For instance, for poetry in &latex; put the lines between <literal>\begin{verse}</literal> and <literal>\end{verse}</literal>. </para> <screen>\begin{verse} - There once was a man from Nantucket \\ - .. + There once was a man from Nantucket \\ + ... \end{verse} </screen> +<para>See <link linkend="Environments">Environments</link> for a list of environments. +</para> <para>The <replaceable>environment name</replaceable> at the beginning must exactly match that at the end. This includes the case where <replaceable>environment name</replaceable> ends in a star (<literal>*</literal>); both the <literal>\begin</literal> and <literal>\end</literal> texts must @@ -459,7 +468,7 @@ the table to be aligned on its top row) while the second argument is required (it specifies the formatting of columns). </para> <screen>\begin{tabular}[t]{r|l} - .. rows of table .. + ... rows of table ... \end{tabular} </screen> @@ -470,6 +479,68 @@ command or parameter. For instance, the <literal>\mainmatter</literal> command changes the setting of page numbers from roman numerals to arabic. </para> +<anchor id="_005cmakeatletter-and-_005cmakeatother"/> + +<para>Synopsis: +</para> +<screen>\makeatletter + ... definition of commands with @ in their name .. +\makeatother +</screen> +<para>Used to redefine internal &latex; commands. <literal>\makeatletter</literal> makes +the at-sign character <literal>@</literal> have the category code of a letter, +11. <literal>\makeatother</literal> sets the category code of <literal>@</literal> to 12, +its original value. +</para> +<para>As each character is read by &tex; for &latex;, it is assigned a +character category code, or +<indexterm role="cp"><primary>catcode</primary></indexterm> +<indexterm role="cp"><primary>character category code</primary></indexterm> +<indexterm role="cp"><primary>category code, character</primary></indexterm> +<firstterm>catcode</firstterm> for shorter. For instance, the backslash <literal>\</literal> is +assigned the catcode 0, for characters that start a command. These two +commands alter the catcode assigned to <literal>@</literal>. +</para> +<para>The alteration is needed because many of &latex;’s commands use +<literal>@</literal> in their name, to prevent users from accidentally defining a +command that replaces one of &latex;’s own. 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). +So under the default category codes, user-defined commands cannot +contain an <literal>@</literal>. But <literal>\makeatletter</literal> and <literal>\makeatother</literal> +allow users to define or redefine commands named with <literal>@</literal>. +</para> +<para>Use these inside a <filename>.tex</filename> file, in the preamble. Don’t use them +inside <filename>.sty</filename> or <filename>.cls</filename> files since the <literal>\usepackage</literal> +and <literal>\documentclass</literal> commands set the at sign to have the character +code of a letter. +</para> +<indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>macros2e</literal> package For a comprehensive list of macros with an at-sign</primary></indexterm> +<para>in their names, see document +<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. These macros are mainly useful +to package or class authors; examples that may be useful to document +authors are provided hereinafter. +</para> +<para>The example code below, if put in the preamble, redefines the +section command to center the section title, put it in bold type, +and adjust the spacing. +</para> +<!-- xxx TODO, make \@startsection a separate node, see latex2e-fr.texi --> +<!-- From http://zoonek.free.fr/LaTeX/LaTeX_samples_section/0.html --> +<screen>\makeatletter +\renewcommand\section{% + \@startsection{section}% Name + {1}% Level: 0=part, 1=chapter, etc. + {0pt}% Heading indent + {-3.5ex plus -1ex minus -.2ex}% Beforeskip (if neg, no head indent) + {2.3ex plus.2ex}% Afterskip (if neg, run-in heading) + {\centering\normalfont\Large\bfseries}} % Style of head +\makeatother +</screen> +<!-- xx TODO document \@ifstar, see latex2e-fr.texi --> + </sect1> </chapter> <chapter label="3" id="Document-classes"> @@ -553,22 +624,26 @@ options for selecting the typeface size (default is <literal>10pt</literal>): size (these show height by width): </para> <variablelist><varlistentry><term><literal>a4paper</literal> -</term><listitem><para>210 by 297 mm (about 8.25 by 11.75 inches) +</term><listitem><para>210 by 297mm (about 8.25 by 11.75 inches) +</para> +</listitem></varlistentry><varlistentry><term><literal>a5paper</literal> +</term><listitem><para>148 by 210mm (about 5.8 by 8.3 inches) </para> </listitem></varlistentry><varlistentry><term><literal>b5paper</literal> -</term><listitem><para>176 by 250 mm (about 7 by 9.875 inches) +</term><listitem><para>176 by 250mm (about 6.9 by 9.8 inches) </para> </listitem></varlistentry><varlistentry><term><literal>executivepaper</literal> -</term><listitem><para>7.25 by 10.5 inches +</term><listitem><para>7.25 by 10.5 inches </para> </listitem></varlistentry><varlistentry><term><literal>legalpaper</literal> -</term><listitem><para>8.5 by 14 inches +</term><listitem><para>8.5 by 14 inches </para> </listitem></varlistentry><varlistentry><term><literal>letterpaper</literal> -</term><listitem><para>8.5 by 11 inches (the default) +</term><listitem><para>8.5 by 11 inches (the default) </para></listitem></varlistentry></variablelist> <indexterm role="fn"><primary>\pdfpagewidth</primary></indexterm> <indexterm role="fn"><primary>\pdfpageheight</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm> <indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm> <para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex; (see <link linkend="TeX-engines">&tex; engines</link>), options other than <literal>letterpaper</literal> set @@ -618,7 +693,10 @@ black box in the margin; default is <literal>final</literal>. </listitem></varlistentry><varlistentry><term><literal>titlepage</literal> </term><term><literal>notitlepage</literal> </term><listitem><indexterm role="cp"><primary>title page, separate or run-in</primary></indexterm> -<para>Specifies whether the title page is separate; default depends on the class. +<para>Specifies whether there is a separate page for the title information and +for the abstract also, if there is one. The default for the +<literal>report</literal> class is <literal>titlepage</literal>, for the other classes it is +<literal>notitlepage</literal>. </para></listitem></varlistentry></variablelist> <para>The following options are not available with the <literal>slides</literal> class. </para> @@ -655,26 +733,449 @@ being 40% of the difference between <literal>\paperwidth</literal> and <para>The <literal>slides</literal> class offers the option <literal>clock</literal> for printing the time at the bottom of each note. </para> + +</sect1> +<sect1 label="3.2" id="Additional-packages"> +<title>Additional packages</title> + <indexterm role="cp"><primary>loading additional packages</primary></indexterm> <indexterm role="cp"><primary>packages, loading additional</primary></indexterm> <indexterm role="cp"><primary>additional packages, loading</primary></indexterm> <indexterm role="fn"><primary>\usepackage</primary></indexterm> -<para>Additional packages are loaded like this: +<para>Load a package <replaceable>pkg</replaceable>, with the package options given in the comma-separated +list <replaceable>options</replaceable>, as here. </para> -<screen>\usepackage[<replaceable>options</replaceable>]{<replaceable>pkg</replaceable>} +<screen>\usepackage[<replaceable>options</replaceable>]{<replaceable>pkg</replaceable>}. </screen> -<para>To specify more than one package, you can separate them with a comma, +<para>To specify more than one package you can separate them with a comma, as in <literal>\usepackage{<replaceable>pkg1</replaceable>,<replaceable>pkg2</replaceable>,...}</literal>, or use multiple <literal>\usepackage</literal> commands. </para> <indexterm role="cp"><primary>global options</primary></indexterm> <indexterm role="cp"><primary>options, global</primary></indexterm> <para>Any options given in the <literal>\documentclass</literal> command that are unknown -by the selected document class are passed on to the packages loaded with +to the selected document class are passed on to the packages loaded with <literal>\usepackage</literal>. </para> </sect1> +<sect1 label="3.3" id="Class-and-package-construction"> +<title>Class and package construction</title> + +<indexterm role="cp"><primary>document class commands</primary></indexterm> +<indexterm role="cp"><primary>commands, document class</primary></indexterm> +<indexterm role="cp"><primary>new class commands</primary></indexterm> + +<para>You can create new document classes and new packages. For instance, if +your memos must satisfy some local requirements, such as a +standard header for each page, then you could create a new class +<literal>smcmemo.cls</literal> and begin your documents with +<literal>\documentclass{smcmemo}</literal>. +</para> +<para>What separates a package from a document class is that the commands in a +package are useful across classes while those in a document class are +specific to that class. Thus, a command to set page headers is for a +package while a command to make the page headers say <literal>Memo from the +SMC Math Department</literal> is for a class. +<indexterm role="cp"><primary>class and package difference</primary></indexterm> +<indexterm role="cp"><primary>difference between class and package</primary></indexterm> +</para> +<para>Inside of a class or package file you can use the at-sign <literal>@</literal> as a +character in command names without having to surround that command with +<literal>\makeatletter</literal> and <literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and +\makeatother</link>. This allow you to create commands that users will not +accidentally redefine. Another technique is to preface class- or +package-specific commands with some string to prevent your class or +package from interacting with others. For instance, the class +<literal>smcmemo</literal> might have commands <literal>\smc@tolist</literal>, +<literal>\smc@fromlist</literal>, etc. +</para> + + + +<sect2 label="3.3.1" id="Class-and-package-structure"> +<title>Class and package structure</title> + +<indexterm role="cp"><primary>class and package structure</primary></indexterm> +<indexterm role="cp"><primary>class file layout</primary></indexterm> +<indexterm role="cp"><primary>package file layout</primary></indexterm> +<indexterm role="cp"><primary>options, document class</primary></indexterm> +<indexterm role="cp"><primary>options, package</primary></indexterm> +<indexterm role="cp"><primary>class options</primary></indexterm> +<indexterm role="cp"><primary>package options</primary></indexterm> + +<para>A class file or package file typically has four parts. (1) In the +identification part, the file says that it is a &latex; package or +class and describes itself, using the <literal>\NeedsTeXFormat</literal> and +<literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands. (2) The +preliminary declarations part declares some commands and can also load +other files. Usually these commands will be those needed for the code +used in the next part. For example, an <literal>smcmemo</literal> class might be +called with an option to read in a file with a list of people for the +to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and therefore +needs to define a command +<literal>\newcommand{\setto}[1]{\def\@tolist{#1}}</literal> used in that +file. (3) In the handle options part the class or package declares +and processes its options. Class options allow a user to start their +document as <literal>\documentclass[<replaceable>option list</replaceable>]{<replaceable>class +name</replaceable>}</literal>, to modify the behavior of the class. An example is when you +declare <literal>\documentclass[11pt]{article}</literal> to set the default +document font size. Finally, (4) in the more declarations part the +class or package usually does most of its work: declaring new variables, +commands and fonts, and loading other files. +</para> +<para>Here is a starting class file, which should be saved as <literal>stub.cls</literal> +where &latex; can find it, for example in the same directory as the +<literal>.tex</literal> file. +</para> +<screen>\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{stub}[2017/07/06 stub to start building classes from] +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} +\ProcessOptions\relax +\LoadClass{article} +</screen><indexterm role="cp"><primary>class file example</primary></indexterm> + +<para>It identifies itself, handles the class options via the default of +passing them all to the <literal>article</literal> class, and then loads the +<literal>article</literal> class to provide the basis for this class’s code. +</para> +<para>For more, see the official guide for class and package writers, the +Class Guide, at +<ulink url="http://www.latex-project.org/help/documentation/clsguide.pdf">http://www.latex-project.org/help/documentation/clsguide.pdf</ulink> (much +of the descriptions here derive from this document), or the tutorial +<ulink url="https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf">https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf</ulink>. +</para> +</sect2> +<sect2 label="3.3.2" id="Class-and-package-commands"> +<title>Class and package commands</title> +<indexterm role="cp"><primary>class and package commands</primary></indexterm> +<indexterm role="cp"><primary>commands, class and package</primary></indexterm> + +<para>These are the commands designed to help writers of classes or packages. +</para> +<variablelist><varlistentry><term><literal>\AtBeginDvi{specials}</literal> +</term><listitem><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm> +<para>Save in a box register things that are written to the <literal>.dvi</literal> file +at the beginning of the shipout of the first page of the document. +</para> +</listitem></varlistentry><varlistentry><term><literal>\AtEndOfClass{<replaceable>code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\AtEndOfPackage{<replaceable>code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\AtEndOfClass</primary></indexterm> +<indexterm role="fn"><primary>\AtEndOfPackage</primary></indexterm> +<para>Hook to insert <replaceable>code</replaceable> to be executed when &latex; finishes +processing the current class or package. You can use these hooks +multiple times; the <literal>code</literal> will be executed in the order that you +called it. See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageWarning{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassWarningNoLine{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageWarningNoLine{<replaceable>package name</replaceable>}{<replaceable>warning text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassInfo{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageInfo{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\ClassInfoNoLine{<replaceable>class name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PackageInfoNoLine{<replaceable>package name</replaceable>}{<replaceable>info text</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\ClassError</primary></indexterm> +<indexterm role="fn"><primary>\PackageError</primary></indexterm> +<indexterm role="fn"><primary>\ClassWarning</primary></indexterm> +<indexterm role="fn"><primary>\PackageWarning</primary></indexterm> +<indexterm role="fn"><primary>\ClassWarningNoLine</primary></indexterm> +<indexterm role="fn"><primary>\PackageWarningNoLine</primary></indexterm> +<indexterm role="fn"><primary>\ClassInfo</primary></indexterm> +<indexterm role="fn"><primary>\PackageInfo</primary></indexterm> +<indexterm role="fn"><primary>\ClassInfoNoLine</primary></indexterm> +<indexterm role="fn"><primary>\PackageInfoNoLine</primary></indexterm> +<para>Produce an error message, or warning or informational messages. +</para> +<para>For <literal>\ClassError</literal> and <literal>\PackageError</literal> the message is +<replaceable>error text</replaceable>, followed by &tex;’s <literal>?</literal> error prompt. If the +user then asks for help by typing <literal>h</literal>, they see the <replaceable>help +text</replaceable>. +</para> +<para>The four warning commands are similar except that they write +<replaceable>warning text</replaceable> on the screen with no error prompt. The four info +commands write <replaceable>info text</replaceable> only in the transcript file. The +<literal>NoLine</literal> versions do not show the number of the line generating the +message, while the other versions do show that number. +</para> +<para>To format the messages, including the <replaceable>help text</replaceable>: use +<literal>\protect</literal> to stop a command from expanding, get a line break with +<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal>. Note that +&latex; appends a period to the messages. +</para> +</listitem></varlistentry><varlistentry><term><literal>\CurrentOption</literal> +</term><listitem><indexterm role="fn"><primary>\CurrentOption</primary></indexterm> +<para>Expands to the name of the currently-being-processed option. Can only +be used within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> +or <literal>\DeclareOption*</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\DeclareOption</primary></indexterm> +<indexterm role="fn"><primary>\DeclareOption*</primary></indexterm> +<indexterm role="cp"><primary>class options</primary></indexterm> +<indexterm role="cp"><primary>package options</primary></indexterm> +<indexterm role="cp"><primary>options, class</primary></indexterm> +<indexterm role="cp"><primary>options, package</primary></indexterm> +<para>Make an option available to a user, for invoking in their +<literal>\documentclass</literal> command. For example, the <literal>smcmemo</literal> class +could have an option allowing users to put the institutional logo on the +first page with <literal>\documentclass[logo]{smcmemo}</literal>. The class file +must contain <literal>\DeclareOption{logo}{<replaceable>code</replaceable>}</literal> (and later, +<literal>\ProcessOptions</literal>). +</para> +<para>If you request an option that has not been declared, by default this +will produce a warning like <literal>Unused global option(s): [badoption].</literal> +Change this behaviour with the starred version +<literal>\DeclareOption*{<replaceable>code</replaceable>}</literal>. For example, many classes extend +an existing class, using a declaration such as +<literal>\LoadClass{article}</literal>, and for passing extra options to the +underlying class use code such as this. +</para> +<screen>\DeclareOption*{% +\PassOptionsToClass{\CurrentOption}{article}% +} +</screen> +<para>Another example is that the class <literal>smcmemo</literal> may allow users to keep +lists of memo recipients in external files. Then the user could invoke +<literal>\documentclass[math]{smcmemo}</literal> and it will read the file +<literal>math.memo</literal>. This code handles the file if it exists and otherwise +passes the option to the <literal>article</literal> class. +</para> +<screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{% + \PassOptionsToClass{\CurrentOption}{article}}} +</screen> +</listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\IfFileExists</primary></indexterm> +<indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm> +<para>Execute <replaceable>true code</replaceable> if &latex; can find the file and <replaceable>false +code</replaceable> otherwise. In the second case it inputs the file immediately +after executing <replaceable>true code</replaceable>. Thus +<literal>\IfFileExists{img.pdf}{\includegraphics{img.pdf}}{\typeout{WARNING: +img.pdf not found}}</literal> will include the graphic if it is found but +otherwise just give a warning. +</para> +<para>This command looks for the file in all search paths that &latex; uses, +not only in the current directory. To look only in the current +directory do something like <literal>\IfFileExists{./filename}{<replaceable>true +code</replaceable>}{<replaceable>false code</replaceable>}</literal>. If you ask for a filename without a +<literal>.tex</literal> extension then &latex; will first look for the file by +appending the <literal>.tex</literal>; for more on how &latex; handles file +extensions see <link linkend="_005cinput">\input</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\LoadClass[<replaceable>options list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\LoadClassWithOptions{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\LoadClass</primary></indexterm> +<indexterm role="fn"><primary>\LoadClassWithOptions</primary></indexterm> +<para>Load a class, as with <literal>\documentclass[<replaceable>options +list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release info</replaceable>]</literal>. An example is +<literal>\LoadClass[twoside]{article}</literal>. +</para> +<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The +<replaceable>release date</replaceable> is optional. If present it must have the form +<replaceable>YYYY/MM/DD</replaceable>. If you request a <replaceable>release date</replaceable> and the date of +the package installed on your system is earlier, then you get a warning +on the screen and in the log like <literal>You have requested, on input +line 4, version `2038/01/19' of document class article, but only version +`2014/09/29 v1.4h Standard LaTeX document class' is available.</literal> +</para> +<para>The command version <literal>\LoadClassWithOptions</literal> uses the list of +options for the current class. This means it ignores any options passed +to it via <literal>\PassOptionsToClass</literal>. This is a convenience command +that lets you build classes on existing ones, such as the standard +<literal>article</literal> class, without having to track which options were passed. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ExecuteOptions{<replaceable>options-list</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm> +<para>For each option in the <replaceable>options-list</replaceable>, in order, this command +executes the command <literal>\ds@</literal><replaceable>option</replaceable>. If this command is not +defined then that option is silently ignored. +</para> +<para>It can be used to provide a default option list before +<literal>\ProcessOptions</literal>. For example, if in a class file you want the +default to be 11pt fonts then you could specify +<literal>\ExecuteOptions{11pt}\ProcessOptions\relax</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm> +<para>Specifies the format that this class should be run under. Often issued +as the first line of a class file, and most often used as: +<literal>\NeedsTeXFormat{LaTeX2e}</literal>. The format that you specify must +exactly match the one installed on your system that you invoked, +including that the string is case sensitive. If it does not match then +execution stops with an error like ‘<literal>This file needs format `xxx' +but this is `LaTeX2e'.</literal>’ +</para> +<para>To specify a version of the format that you know to have certain +features, include the optional <replaceable>format date</replaceable> on which those features +were implemented. If present it must be in the form <literal>YYYY/MM/DD</literal>. +If the format version installed on your system is earlier than +<replaceable>format date</replaceable> then you get a warning like ‘<literal>You have requested +release `2038/01/20' of LaTeX, but only release `2016/02/01' is +available.</literal>’ (The &latex; kernel has been frozen for many years so you +probably do not not need to specify the format date.) +</para> +</listitem></varlistentry><varlistentry><term><literal>\OptionNotUsed</literal> +</term><listitem><indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm> +<para>Adds the current option to the list of unused options. Can only be used +within the <replaceable>code</replaceable> argument of either <literal>\DeclareOption</literal> or +<literal>\DeclareOption*</literal>. +</para> +<!-- I cannot reproduce this behavior as it is documented in clsguide. --> +<!-- In the absence of a @code{\DeclareOption*} declaration, @LaTeX{} issues --> +<!-- on the console a warning like @code{LaTeX Warning: Unused global --> +<!-- option(s): [unusedoption].} with the list of not-used options when it --> +<!-- reaches @code{\begin@{document@}}. --> + +</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>options list</replaceable>}{<replaceable>class name</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>options list</replaceable>}{<replaceable>package name</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm> +<indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm> +<para>Adds the options in the comma-separated list <replaceable>option list</replaceable> to the +options used by any future <literal>\RequirePackage</literal> or <literal>\usepackage</literal> +command for package <replaceable>package name</replaceable> or the class <replaceable>class name</replaceable>. +</para> +<para>The reason for these commands is: you may load a package any number of +times with no options but if you want options then you may only supply +them when you first load the package. Loading a package with options +more than once will get you an error like <literal>Option clash for package +foo.</literal> (&latex; throws an error even if there is no conflict between the +options.) +</para> +<para>If your code is bringing in a package twice then you can collapse that +to once, for example replacing the two +<literal>\RequirePackage[landscape]{geometry}\RequirePackage[margins=1in]{geometry}</literal> +with the single +<literal>\RequirePackage[landscape,margins=1in]{geometry}</literal>. But if you +are loading a package that in turn loads another package then you need +to queue up the options you desire. For instance, suppose the package +<literal>foo</literal> loads the package <literal>geometry</literal>. Instead of <literal> +\RequirePackage{foo}\RequirePackage[draft]{graphics}</literal> you must write +<literal>\PassOptionsToPackage{draft}{graphics} +\RequirePackage{foo}</literal>. (If <literal>foo.sty</literal> loads an option in conflict +with what you want then you may have to look into altering its source.) +</para> +<para>These commands are useful for general users as well as class and package +writers. For instance, suppose a user wants to load the <literal>graphicx</literal> +package with the option <literal>draft</literal> and also wants to use a class +<literal>foo</literal> that loads the <literal>graphicx</literal> package, but without that +option. The user could start their &latex; file with +<literal>\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\ProcessOptions</literal> +</term></varlistentry><varlistentry><term><literal>\ProcessOptions*<replaceable>\@options</replaceable></literal> +</term><listitem><indexterm role="fn"><primary>\ProcessOptions</primary></indexterm> +<indexterm role="fn"><primary>\ProcessOptions*</primary></indexterm> +<para>Execute the code for each option that the user has invoked. Include it +in the class file as <literal>\ProcessOptions\relax</literal> (because of the +existence of the starred command). +</para> +<para>Options come in two types. ‘Local’ options have been specified for this +particular package in the <replaceable>options</replaceable> argument of +<literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>, +<literal>\usepackage[<replaceable>options</replaceable>]</literal>, or +<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. ‘Global’ options are those given +by the class user in <literal>\documentclass[<replaceable>options</replaceable>]</literal> (If an option +is specified both locally and globally then it is local.) +</para> +<para>When <literal>\ProcessOptions</literal> is called for a package <literal>pkg.sty</literal>, the +following happens. (1) For each option <replaceable>option</replaceable> so far declared +with <literal>\DeclareOption</literal>, it looks to see if that option is either a +global or a local option for <literal>pkg</literal>. If so then it executes the +declared code. This is done in the order in which these options were +given in <literal>pkg.sty</literal>. (2) For each remaining local option, it +executes the command <literal>\ds@</literal><replaceable>option</replaceable> if it has been defined +somewhere (other than by a <literal>\DeclareOption</literal>); otherwise, it +executes the default option code given in <literal>\DeclareOption*</literal>. If no +default option code has been declared then it gives an error message. +This is done in the order in which these options were specified. +</para> +<para>When <literal>\ProcessOptions</literal> is called for a class it works in the same +way except that all options are local, and the default value for +<literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error. +</para> +<para>The starred version <literal>\ProcessOptions*</literal><replaceable>\@options</replaceable> executes the +options in the order specified in the calling commands, rather than in +the order of declaration in the class or package. For a package this +means that the global options are processed first. +</para> + +</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable><release date></replaceable> <replaceable><brief additional information></replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable><release date></replaceable> <replaceable><brief additional information></replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm> +<indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm> +<para>Identifies the class or package, printing a message to the screen and the log file. +</para> +<para>When a user writes <literal>\documentclass{smcmemo}</literal> then &latex; loads +the file <literal>smcmemo.cls</literal>. Similarly, a user writing +<literal>\usepackage{test}</literal> prompts &latex; to load the file +<literal>test.sty</literal>. If the name of the file does not match the declared +class or package name then you get a warning. Thus, if you invoke +<literal>\documentclass{smcmemo}</literal>, and the file <literal>smcmemo.cls</literal> has +the statement <literal>\ProvidesClass{xxx}</literal> then you get a warning like +<literal>You have requested document class `smcmemo', but the document +class provides 'xxx'.</literal> This warning does not prevent &latex; from +processing the rest of the class file normally. +</para> +<para>If you include the optional part then you must include the date, before +the first space, and it must have the form <literal>YYYY/MM/DD</literal>. The rest +of the optional part is free-form, although it traditionally identifies +the class, and is written to the screen during compilation and to the +log file. Thus, if your file <literal>smcmem.cls</literal> contains the line +<literal>\ProvidesClass{smcmem}[2008/06/01 SMC memo class]</literal> and your +document’s first line is <literal>\documentclass{smcmem}</literal> then you will +see <literal>Document Class: smcmemo 2008/06/01 SMC memo class</literal>. +</para> +<para>The date in the optional portion allows class and package users to ask +to be warned if the version of the class or package installed on their +system is earlier than <replaceable>release date</replaceable>, by using the optional calls +such as <literal>\documentclass{smcmem}[2018/10/12]</literal> or +<literal>\usepackage{foo}[[2017/07/07]]</literal>. (Note that package users only +rarely include a date, and class users almost never do.) +</para> +</listitem></varlistentry><varlistentry><term><literal>\ProvidesFile{<replaceable>file name</replaceable>}[<replaceable>additional information</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\ProvidesFile</primary></indexterm> +<para>Declare a file other than the main class and package files, such as +configuration files or font definition files. Put this command in that +file and you get in the log a string like <literal>File: test.config +2017/10/12 config file for test.cls</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>options list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\RequirePackageWithOptions{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term><listitem><indexterm role="fn"><primary>\RequirePackage</primary></indexterm> +<indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm> +<para>Load a package, like the author command <literal>\usepackage</literal>. +See <link linkend="Additional-packages">Additional packages</link>. An example is +<literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>. Note that the +&latex; development team strongly recommends use of these commands over +Plain &tex;’s <literal>\input</literal>; see the Class Guide. +</para> +<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The +<replaceable>release date</replaceable>, if present, must have the form <replaceable>YYYY/MM/DD</replaceable>. If +the release date of the package as installed on your system is earlier +than <replaceable>release date</replaceable> then you get a warning like <literal>You have +requested, on input line 9, version `2017/07/03' of package jhtest, but +only version `2000/01/01' is available</literal>. +</para> +<para>The <literal>\RequirePackageWithOptions</literal> version uses the list of options +for the current class. This means it ignores any options passed to it +via <literal>\PassOptionsToClass</literal>. This is a convenience command to allow +easily building classes on existing ones without having to track which +options were passed. +</para> +<para>The difference between <literal>\usepackage</literal> and <literal>\RequirePackage</literal> is +small. The <literal>\usepackage</literal> command is intended for the document file +while <literal>\RequirePackage</literal> is intended for package and class files. +Thus, using <literal>\usepackage</literal> before the <literal>\documentclass</literal> command +causes &latex; to give error like <literal>\usepackage before +\documentclass</literal>, but you can use <literal>\RequirePackage</literal> there. +</para></listitem></varlistentry></variablelist> + +</sect2> +</sect1> </chapter> <chapter label="4" id="Fonts"> <title>Fonts</title> @@ -880,6 +1381,7 @@ formulas. <literal>\mathversion{normal}</literal> restores the default. <indexterm role="cp"><primary>numerals, old-style</primary></indexterm> <indexterm role="cp"><primary>old-style numerals</primary></indexterm> <indexterm role="cp"><primary>lining numerals</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>textcomp</literal></primary></indexterm> <indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm> <para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset so-called “old-style” numerals, which have differing heights and @@ -1081,6 +1583,7 @@ takes effect when <literal>\selectfont</literal> (see below) is called. You can make line skip changes happen for the entire document by doing <literal>\renewcommand{\baselinestretch}{2.0}</literal> in the preamble. </para> +<indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm> <indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm> <indexterm role="cp"><primary>double spacing</primary></indexterm> <para>However, the best way to double-space a document is to use the @@ -1135,10 +1638,9 @@ followed by <literal>\selectfont</literal>. For example: <indexterm role="fn"><primary>\onecolumn</primary></indexterm> <indexterm role="cp"><primary>one-column output</primary></indexterm> -<para>The <literal>\onecolumn</literal> declaration starts a new page and produces -single-column output. If the document is given the class option -<literal>onecolumn</literal> then this is the default behavior (see <link linkend="Document-class-options">Document -class options</link>). +<para>Start a new page and produce single-column output. If the document is +given the class option <literal>onecolumn</literal> then this is the default +behavior (see <link linkend="Document-class-options">Document class options</link>). </para> <para>This command is fragile (see <link linkend="_005cprotect">\protect</link>). </para> @@ -1151,14 +1653,14 @@ class options</link>). <indexterm role="cp"><primary>multicolumn text</primary></indexterm> <indexterm role="cp"><primary>two-column output</primary></indexterm> -<para>Synopsis: +<para>Synopses: </para> -<screen>\twocolumn[<replaceable>prelim one column text</replaceable>] +<screen>\twocolumn +\twocolumn[<replaceable>prelim one column text</replaceable>] </screen> -<para>The <literal>\twocolumn</literal> declaration starts a new page and produces -two-column output. If the document is given the class option -<literal>twocolumn</literal> then this is the default (see <link linkend="Document-class-options">Document class -options</link>). +<para>Start a new page and produce two-column output. If the document is given +the class option <literal>twocolumn</literal> then this is the default +(see <link linkend="Document-class-options">Document class options</link>). </para> <para>If the optional <replaceable>prelim one column text</replaceable> argument is present, it is typeset in one-column mode before the two-column @@ -1199,7 +1701,7 @@ The following parameters control float behavior of two-column output. occupied by two-column wide floats. The default is 0.7, meaning that the height of a <literal>table*</literal> or <literal>figure*</literal> environment must not exceed <literal>0.7\textheight</literal> . If the height of your starred float -environment exceeeds this then you can take one of the following actions +environment exceeds this then you can take one of the following actions to prevent it from floating all the way to the back of the document: </para> <itemizedlist><listitem><para>Use the <literal>[tp]</literal> location specifier to tell LaTeX to try to put @@ -1238,24 +1740,24 @@ default is <literal>2</literal>. </para> </listitem></varlistentry></variablelist> <!-- From egreg at http://tex.stackexchange.com/a/142232/339 --> -<para>This example shows the use of the optional argument of <literal>\twocolumn</literal> -to create a title that spans the two-column article: +<para>This example uses <literal>\twocolumn</literal>’s optional argument of to create a +title that spans the two-column article: </para> <screen>\documentclass[twocolumn]{article} \newcommand{\authormark}[1]{\textsuperscript{#1}} \begin{document} \twocolumn[{% inside this optional argument goes one-column text - \centering - \LARGE The Title \\[1.5em] - \large Author One\authormark{1}, - Author Two\authormark{2}, - Author Three\authormark{1} \\[1em] - \normalsize - \begin{tabular}{p{.2\textwidth}@{\hspace{2em}}p{.2\textwidth}} - \authormark{1}Department one &\authormark{2}Department two \\ - School one &School two - \end{tabular}\\[3em] % space below title part -}] + \centering + \LARGE The Title \\[1.5em] + \large Author One\authormark{1}, + Author Two\authormark{2}, + Author Three\authormark{1} \\[1em] + \normalsize + \begin{tabular}{p{.2\textwidth}@{\hspace{2em}}p{.2\textwidth}} + \authormark{1}Department one &\authormark{2}Department two \\ + School one &School two + \end{tabular}\\[3em] % space below title part + }] Two column text here. </screen> @@ -1266,22 +1768,23 @@ Two column text here. <indexterm role="fn"><primary>\flushbottom</primary></indexterm> -<para>The <literal>\flushbottom</literal> command can go at any point in the document -body. It makes all later pages the same height, stretching the vertical -space where necessary to fill out the page. +<para>Make all pages in the documents after this declaration have the same +height, by stretching the vertical space where necessary to fill out the +page. This is most often used when making two-sided documents since the +differences in facing pages can be glaring. </para> <para>If &tex; cannot satisfactorily stretch the vertical space in a page then you get a message like ‘<literal>Underfull \vbox (badness 10000) has -occurred while \output is active</literal>’. You can change to -<literal>\raggedbottom</literal> (see below). Alternatively, you can try to adjust -the <literal>textheight</literal> to be compatible, or you can add some vertical -stretch glue between lines or between paragraphs, as in -<literal>\setlength{\parskip}{0ex plus0.1ex}</literal>. In a final editing -stage you can adjust the height of individual pages +occurred while \output is active</literal>’. If you get that, one option is to +change to <literal>\raggedbottom</literal> (see <link linkend="_005craggedbottom">\raggedbottom</link>). Alternatively, +you can adjust the <literal>textheight</literal> to make compatible pages, or you +can add some vertical stretch glue between lines or between paragraphs, +as in <literal>\setlength{\parskip}{0ex plus0.1ex}</literal>. Your last option +is to, in a final editing stage, adjust the height of individual pages (see <link linkend="_005cenlargethispage">\enlargethispage</link>). </para> -<para>This is the default only if you select the <literal>twoside</literal> document class -option (see <link linkend="Document-class-options">Document class options</link>). +<para>The <literal>\flushbottom</literal> state is the default only if you select the +<literal>twoside</literal> document class option (see <link linkend="Document-class-options">Document class options</link>). </para> </sect1> @@ -1291,11 +1794,10 @@ option (see <link linkend="Document-class-options">Document class options</link> <indexterm role="fn"><primary>\raggedbottom</primary></indexterm> <indexterm role="cp"><primary>stretch, omitting vertical</primary></indexterm> -<para>The <literal>\raggedbottom</literal> command can go at any point in the document -body. It makes all later pages the natural height of the material on -that page; no rubber lengths will be stretched. Thus, in a two-sided -document the facing pages may be different heights. See also -<literal>\flushbottom</literal> above. +<para>Make all later pages the natural height of the material on that page; no +rubber vertical lengths will be stretched. Thus, in a two-sided +document the facing pages may be different heights. This command can go +at any point in the document body. See <link linkend="_005cflushbottom">\flushbottom</link>. </para> <para>This is the default unless you select the <literal>twoside</literal> document class option (see <link linkend="Document-class-options">Document class options</link>). @@ -1487,14 +1989,14 @@ while the first table appears in the source before the first figure, it appears in the output after it. </para> <para>The placement of floats is subject to parameters, given below, that -limit the number of floats that can appear at the top of a page, and the -bottom, etc. If so many floats are queued up that the limits prevent +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 be typset far -from their place in the source. In particular, a float that is big can -migrate to the end of the document. But then because all floats in a -class must appear in sequential order, every subsequent float in that -class also appears at the end. +defers the rest to the next page. In this way, floats may end up +being typeset far from their place in the source. In particular, a +float that is big may migrate to the end of the document. In which +event, because all floats in a class must appear in sequential order, +every following float in that class also appears at the end. </para> <indexterm role="cp"><primary>placement of floats</primary></indexterm> <indexterm role="cp"><primary>specifier, float placement</primary></indexterm> @@ -1520,6 +2022,7 @@ appears. However, <literal>h</literal> is not allowed by itself; <literal>t</li automatically added. </para> <indexterm role="cp"><primary>here, putting floats</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>float</literal></primary></indexterm> <indexterm role="cp"><primary><literal>float</literal> package</primary></indexterm> <para>To absolutely force a float to appear “here”, you can <literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it @@ -1555,11 +2058,11 @@ use the <filename>afterpage</filename> package and issue is finished and then flush all outstanding floats. </para> <para>&latex; can typeset a float before where it appears in the source -(although on the same output page) if there is a <literal>t</literal> specifier in the -<replaceable>placement</replaceable> paramater. If this is not desired, and deleting the -<literal>t</literal> is not acceptable as it keeps the float from being placed at -the top of the next page, then you can prevent it by either using the -<filename>flafter</filename> package or using the command +(although on the same output page) if there is a <literal>t</literal> specifier in +the <replaceable>placement</replaceable> parameter. If this is not desired, and deleting +the <literal>t</literal> is not acceptable as it keeps the float from being placed +at the top of the next page, then you can prevent it by either using +the <filename>flafter</filename> package or using the command <indexterm role="fn"><primary>\suppressfloats</primary></indexterm> <literal>\suppressfloats[t]</literal>, which causes floats for the top position on this page to moved to the next page. @@ -1633,10 +2136,11 @@ default 2. <para>The principal &tex; FAQ entry relating to floats <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=floats</ulink> contains suggestions for relaxing &latex;’s default parameters to reduce the -problem of floats being pushed to the end. A full explaination of the -float placement algorithm is Frank Mittelbach’s article “How to -infuence the position of float environments like figure and table in -&latex;?” <ulink url="http://latex-project.org/papers/tb111mitt-float.pdf">http://latex-project.org/papers/tb111mitt-float.pdf</ulink>. +problem of floats being pushed to the end. A full explanation of the +float placement algorithm is in Frank Mittelbach’s article “How to +influence the position of float environments like figure and table in +&latex;?” +(<ulink url="http://latex-project.org/papers/tb111mitt-float.pdf">http://latex-project.org/papers/tb111mitt-float.pdf</ulink>). </para> </sect1> @@ -1708,8 +2212,38 @@ The setting <indexterm role="cp"><primary>cross references</primary></indexterm> -<para>One reason for numbering things like figures and equations is to refer -the reader to them, as in “See Figure 3 for more details.” +<para>One reason for numbering things such as figures and equations is to +refer the reader to them, as in “See Figure~3 for more details.” +</para> +<indexterm role="cp"><primary>label</primary></indexterm> +<para>Including the figure number in the source is poor practice since if that +number changes as the document evolves then you must remember to update +this reference by hand. Instead, &latex; has you write a <firstterm>label</firstterm> +like <literal>\label{eq:GreensThm}</literal> and refer to it with <literal>See +equation~\ref{eq:GreensThm}</literal>. +</para> +<para>&latex; writes the information from the labels to a file with the same +name as the file containing the <literal>\label{...}</literal> but with an +<filename>.aux</filename> extension. (The information has the format +<literal>\newlabel{<replaceable>label</replaceable>}{{<replaceable>currentlabel</replaceable>}{<replaceable>pagenumber</replaceable>}}</literal> +where <replaceable>currentlabel</replaceable> is the current value of the macro +<literal>\@currentlabel</literal> that is usually updated whenever you call +<literal>\refstepcounter{<replaceable>counter</replaceable>}</literal>.) +</para> +<indexterm role="cp"><primary>forward reference</primary></indexterm> +<indexterm role="cp"><primary>reference, forward</primary></indexterm> +<para>The most common side effect of the prior paragraph happens when your +document has a <firstterm>forward reference</firstterm>, a <literal>\ref{<replaceable>key</replaceable>}</literal> that +appears earlier than the associated <literal>\label{<replaceable>key</replaceable>}</literal>; see the +example in the <literal>\pageref{...}</literal> description. &latex; gets the +information for references from the <filename>.aux</filename> file. If this is the +first time you are compiling the document then you will get a message +<literal>LaTeX Warning: Label(s) may have changed. Rerun to get +cross references right.</literal> and in the output the reference will appear as +two question marks ‘<literal>??</literal>’, in boldface. Or, if you change some +things so the references change then you get the same warning and the +output contains the old reference information. The solution in either +case is just to compile the document a second time. </para> @@ -1722,35 +2256,22 @@ the reader to them, as in “See Figure 3 for more details.” </para> <screen>\label{<replaceable>key</replaceable>} </screen> -<para>A <literal>\label</literal> command appearing in ordinary text assigns to -<replaceable>key</replaceable> the number of the current sectional unit; one appearing -inside a numbered environment assigns that number to <replaceable>key</replaceable>. The -assigned number can be retrieved with the <literal>\ref{<replaceable>key</replaceable>}</literal> -command (see <link linkend="_005cref">\ref</link>). -</para> -<para>Thus, in the example below the key <literal>sec:test</literal> holds the number of -the current section and the key <literal>fig:test</literal> that of the figure. -(Incidentally, labels must appear after captions in figures and -tables.) +<para>Assign a reference number to <replaceable>key</replaceable>. In ordinary text +<literal>\label{<replaceable>key</replaceable>}</literal> assigns to <replaceable>key</replaceable> the number of the +current sectional unit. Inside an environment with numbering, such as a +<literal>table</literal> or <literal>theorem</literal> environment, <literal>\label{<replaceable>key</replaceable>}</literal> +assigns to <replaceable>key</replaceable> the number of that environment. Retrieve the +assigned number with the <literal>\ref{<replaceable>key</replaceable>}</literal> command +(see <link linkend="_005cref">\ref</link>). </para> -<screen>\section{section name} -\label{sec:test} -This is Section~\ref{sec:test}. -\begin{figure} - ... - \caption{caption text} - \label{fig:test} -\end{figure} -See Figure~\ref{fig:test}. -</screen> <para>A key name can consist of any sequence of letters, digits, or common punctuation characters. Upper and lowercase letters are distinguished, as usual. </para> -<para>Although the name can be more or less anything, a common convention is -to use labels consisting of a prefix and a suffix separated by a colon -or period. This helps to avoid accidentally creating two labels with -the same name. Some commonly-used prefixes: +<para>A common convention is to use labels consisting of a prefix and a suffix +separated by a colon or period. This helps to avoid accidentally +creating two labels with the same name, and makes your source more +readable. Some commonly-used prefixes: </para> <variablelist><varlistentry><term><literal>ch</literal> </term><listitem><para>for chapters @@ -1763,9 +2284,24 @@ the same name. Some commonly-used prefixes: </para></listitem></varlistentry><varlistentry><term><literal>eq</literal> </term><listitem><para>for equations </para></listitem></varlistentry></variablelist> -<para>Thus, a label for a figure would look like <literal>fig:test</literal> or -<literal>fig.test</literal>. +<para>Thus, <literal>\label{fig:Euler}</literal> is a label for a figure with a portrait +of the great man. +</para> +<para>In this example below the key <literal>sec:test</literal> will get the number of the +current section and the key <literal>fig:test</literal> will get the number of the +figure. (Incidentally, put labels after captions in figures and +tables.) </para> +<screen>\section{section name} +\label{sec:test} +This is Section~\ref{sec:test}. +\begin{figure} + ... + \caption{caption text} + \label{fig:test} +\end{figure} +See Figure~\ref{fig:test}. +</screen> </sect1> <sect1 label="7.2" id="_005cpageref"> @@ -1779,10 +2315,20 @@ the same name. Some commonly-used prefixes: </para> <screen>\pageref{<replaceable>key</replaceable>} </screen> -<para>The <literal>\pageref</literal>{<replaceable>key</replaceable>} command produces the page number of -the place in the text where the corresponding +<para>Produce the page number of the place in the text where the corresponding <literal>\label</literal>{<replaceable>key</replaceable>} command appears. </para> +<para>In this example the <literal>\label{eq:main}</literal> is used both for the +formula number and for the page number. (Note that the two references +are forward references, so this document would need to be compiled twice +to resolve those.) +</para> +<screen>The main result is formula~\ref{eq:main} on page~\pageref{eq:main}. + ... +\begin{equation} \label{eq:main} + \mathbf{P}=\mathbf{NP} +\end{equation} +</screen> </sect1> <sect1 label="7.3" id="_005cref"> @@ -1799,11 +2345,22 @@ the place in the text where the corresponding </para> <screen>\ref{<replaceable>key</replaceable>} </screen> -<para>The <literal>\ref</literal> command produces the number of the sectional unit, +<para>Produces the number of the sectional unit, equation, footnote, figure, …, of the corresponding <literal>\label</literal> command (see <link linkend="_005clabel">\label</link>). It does not produce any text, such as the word ‘Section’ or ‘Figure’, just the bare number itself. </para> +<para>In this example, the <literal>\ref{popular}</literal> produces ‘<literal>2</literal>’. Note +that it is a forward reference since it comes before +<literal>\label{popular}</literal>. +</para> +<screen>The most widely-used format is item number~\ref{popular}. +\begin{enumerate} +\item Plain \TeX +\item \label{popular} \LaTeX +\item Con\TeX t +\end{enumerate} +</screen> </sect1> </chapter> @@ -1814,19 +2371,30 @@ such as the word ‘Section’ or ‘Figure’, just the bare nu <indexterm role="fn"><primary>\begin</primary></indexterm> <indexterm role="fn"><primary>\end</primary></indexterm> -<para>&latex; provides many environments for marking off certain text. -Each environment begins and ends in the same manner: +<para>&latex; provides many environments for delimiting certain behavior. +An environment begins with <literal>\begin</literal> and ends with <literal>\end</literal>, +like this: </para> -<screen>\begin{<replaceable>envname</replaceable>} -... -\end{<replaceable>envname</replaceable>} +<screen>\begin{<replaceable>environment-name</replaceable>} + ... +\end{<replaceable>environment-name</replaceable>} </screen> +<para>The <replaceable>environment-name</replaceable> at the beginning must exactly match that at +the end. For instance, the input +<literal>\begin{table*}...\end{table}</literal> will cause an error like: +‘<literal>! LaTeX Error: \begin{table*} on input line 5 ended by +\end{table}.</literal>’ +</para> +<indexterm role="cp"><primary>group, and environments</primary></indexterm> +<para>Environments are executed within a group. +</para> <sect1 label="8.1" id="abstract"> <title><literal>abstract</literal></title> -<indexterm role="fn"><primary>abstract environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>abstract</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>abstract</literal> environment</primary></indexterm> <indexterm role="cp"><primary>abstracts</primary></indexterm> <para>Synopsis: @@ -1835,35 +2403,72 @@ Each environment begins and ends in the same manner: ... \end{abstract} </screen> -<para>Environment for producing an abstract, possibly of multiple paragraphs. +<para>Produce an abstract, possibly of multiple paragraphs. This environment +is only defined in the <literal>article</literal> and <literal>report</literal> document classes +(see <link linkend="Document-classes">Document classes</link>). +</para> +<para>Using the example below in the <literal>article</literal> class produces a displayed +paragraph. Document class option <literal>titlepage</literal> causes the abstract +to be on a separate page (see <link linkend="Document-class-options">Document class options</link>); this is the +default only in the <literal>report</literal> class. +</para> +<screen>\begin{abstract} + We compare all known accounts of the proposal made by Porter Alexander + to Robert E Lee at the Appomattox Court House that the army continue + in a guerrilla war, which Lee refused. +\end{abstract} +</screen> +<para>The next example produces a one column abstract in a two column document (for +a more flexible solution, use the package <filename>abstract</filename>). </para> +<!-- Adopted from http://www.tex.ac.uk/FAQ-onecolabs.html --> +<screen>\documentclass[twocolumn]{article} + ... +\begin{document} +\title{Babe Ruth as Cultural Progenitor: a Atavistic Approach} +\author{Smith \\ Jones \\ Robinson\thanks{Railroad tracking grant.}} +\twocolumn[ + \begin{@twocolumnfalse} + \maketitle + \begin{abstract} + Ruth was not just the Sultan of Swat, he was the entire swat + team. + \end{abstract} + \end{@twocolumnfalse} + ] +{ % by-hand insert a footnote at page bottom + \renewcommand{\thefootnote}{\fnsymbol{footnote}} + \footnotetext[1]{Thanks for all the fish.} +} +</screen> </sect1> <sect1 label="8.2" id="array"> <title><literal>array</literal></title> -<indexterm role="fn"><primary>array environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>array</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>array</literal> environment</primary></indexterm> <indexterm role="cp"><primary>arrays, math</primary></indexterm> <para>Synopsis: </para> <screen>\begin{array}{<replaceable>cols</replaceable>} -<replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ -... + <replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ + ... \end{array} </screen> <para>or </para> <screen>\begin{array}[<replaceable>pos</replaceable>]{<replaceable>cols</replaceable>} -<replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ -... + <replaceable>column 1 entry</replaceable> &<replaceable>column 2 entry</replaceable> ... &<replaceable>column n entry</replaceable> \\ + ... \end{array} </screen> <para>Produce a mathematical array. This environment can only be used in math mode, and normally appears within a displayed mathematics environment such as <literal>equation</literal> (see <link linkend="equation">equation</link>). Column entries are separated by an ampersand (<literal>&</literal>). Rows are terminated with -double-backslashes (<literal>\\</literal>) (see <link linkend="_005c_005c">\\</link>). +double-backslashes (see <link linkend="_005c_005c">\\</link>). </para> <para>The required argument <replaceable>cols</replaceable> describes the number of columns, their alignment, and the formatting of the intercolumn regions. See @@ -1872,24 +2477,24 @@ other common features of the two environments, including the optional <replaceable>pos</replaceable> argument. </para> <para>There are two ways that <literal>array</literal> diverges from <literal>tabular</literal>. The -first is that <literal>array</literal> entries are typeset in mathematics mode, in +first is that <literal>array</literal> entries are typeset in math mode, in textstyle (except if the <replaceable>cols</replaceable> definition specifies the column with -<literal>@p{..}</literal>, which causes the entry to be typeset in text mode). +<literal>p{...}</literal>, which causes the entry to be typeset in text mode). The second is that, instead of <literal>tabular</literal>’s parameter -<literal>\tabcolsep</literal>, &latex;’s intercolumn space in an array is governed +<literal>\tabcolsep</literal>, &latex;’s intercolumn space in an <literal>array</literal> is governed by <indexterm role="fn"><primary>\arraycolsep</primary></indexterm> -<literal>\arraycolsep</literal> which gives half the width between columns. The +<literal>\arraycolsep</literal>, which gives half the width between columns. The default for this is ‘<literal>5pt</literal>’. </para> <para>To obtain arrays with braces the standard is to use the <filename>amsmath</filename> package. It comes with environments <literal>pmatrix</literal> for an array -surrounded by parentheses <literal>(..)</literal>, <literal>bmatrix</literal> for an array -surrounded by square brackets <literal>[..]</literal>, <literal>Bmatrix</literal> for an -array surrounded by curly braces <literal>{..}</literal>, <literal>vmatrix</literal> for -an array surrounded by vertical bars <literal>|..|</literal>, and +surrounded by parentheses <literal>(...)</literal>, <literal>bmatrix</literal> for an array +surrounded by square brackets <literal>[...]</literal>, <literal>Bmatrix</literal> for an +array surrounded by curly braces <literal>{...}</literal>, <literal>vmatrix</literal> for +an array surrounded by vertical bars <literal>|...|</literal>, and <literal>Vmatrix</literal> for an array surrounded by double vertical -bars <literal>||..||</literal>, along with a number of other array constructs. +bars <literal>||...||</literal>, along with a number of other array constructs. </para> <para>Here is an example of an array: </para> @@ -1900,35 +2505,57 @@ bars <literal>||..||</literal>, along with a number of other array construc \end{array} \end{equation} </screen> +<para>The next example works if <literal>\usepackage{amsmath}</literal> is in the +preamble: +</para> +<screen>\begin{equation} + \begin{vmatrix}{cc} + a &b \\ + c &d + \end{vmatrix}=ad-bc +\end{equation} +</screen> </sect1> <sect1 label="8.3" id="center"> <title><literal>center</literal></title> -<indexterm role="fn"><primary>center environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>center</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>center</literal> environment</primary></indexterm> <indexterm role="cp"><primary>centering text, environment for</primary></indexterm> <para>Synopsis: </para> <screen>\begin{center} - .. text .. + ... text ... \end{center} </screen> -<para>Environment to create a sequence of lines that are centered within the -left and right margins on the current page. If the text in the -environment body is too long to fit on a line, &latex; will insert line -breaks that avoid hyphenation and avoid stretching or shrinking any -interword space. To force a line break at a particular spot use -double-backslash <literal>\\</literal> (see <link linkend="_005c_005c">\\</link>). +<para>Create a new paragraph consisting of a sequence of lines that are +centered within the left and right margins on the current page. Use +double-backslash to get a line break at a particular spot (see <link linkend="_005c_005c">\\</link>). <indexterm role="fn"><primary>\\ (for <literal>center</literal>)</primary></indexterm> +If some text environment body is too long to fit on a line, &latex; +will insert line breaks that avoid hyphenation and avoid stretching or +shrinking any interword space. </para> <para>This environment inserts space above and below the text body. See <link linkend="_005ccentering">\centering</link> to avoid such space, for example inside a <literal>figure</literal> environment. </para> -<para>In this example, depending on the line width, &latex; may choose a break -for the part before the double backslash, will center the line or two, -then will break at the double backslash, and will center the ending. +<para>This example produces three centered lines. There is extra vertical +space between the last two lines. +</para> +<screen>\begin{center} + A Thesis Submitted in Partial Fufillment \\ + of the Requirements of \\[0.5ex] + the School of Environmental Engineering +\end{center} +</screen> +<para>In this example, depending on the page’s line width, &latex; may choose +a line break for the part before the double backslash. If so, it will +center each of the two lines and if not it will center the single line. +Then &latex; will break at the double backslash, and will center the +ending. </para> <screen>\begin{center} My father considered that anyone who went to chapel and didn't drink @@ -1946,7 +2573,7 @@ then will break at the double backslash, and will center the ending. <indexterm role="fn"><primary>\centering</primary></indexterm> <indexterm role="cp"><primary>centering text, declaration for</primary></indexterm> -<para>Declaration that causes material in its scope to be centered. It is +<para>A declaration that causes material in its scope to be centered. It is most often used inside an environment such as <literal>figure</literal>, or in a <literal>parbox</literal>. </para> @@ -1982,7 +2609,8 @@ centered. <sect1 label="8.4" id="description"> <title><literal>description</literal></title> -<indexterm role="fn"><primary>description environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>description</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>description</literal> environment</primary></indexterm> <indexterm role="cp"><primary>labelled lists, creating</primary></indexterm> <indexterm role="cp"><primary>description lists, creating</primary></indexterm> @@ -1994,26 +2622,26 @@ centered. ... \end{description} </screen> -<indexterm role="fn"><primary>\item</primary></indexterm> <para>Environment to make a labelled list of items. Each item’s <replaceable>label</replaceable> is typeset in bold, flush-left. Each item’s text may contain multiple paragraphs. Although the labels on the items are optional there is no sensible default, so all items should have labels. </para> <indexterm role="fn"><primary>\item</primary></indexterm> -<para>The list consists of at least one item; see <link linkend="_005citem">\item</link> (having no -items causes the &latex; error ‘<literal>Something's wrong--perhaps a -missing \item</literal>’). Each item is produced with an <literal>\item</literal> command. +<para>The list consists of at least one item, created with the <literal>\item</literal> +command (see <link linkend="_005citem">\item</link>). Having no items causes the &latex; error +‘<literal>Something's wrong--perhaps a missing \item</literal>’). </para> <indexterm role="cp"><primary>bold typewriter, avoiding</primary></indexterm> <indexterm role="cp"><primary>typewriter labels in lists</primary></indexterm> <para>Since the labels are in bold style, if the label text calls for a font -change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will come -out bold. For instance, if the label text calls for typewriter with -<literal>\item[\texttt{label text}]</literal> then it will appear in bold -typewriter, if that is available. The simplest way to get non-bolded -typewriter is to use declaritive style <literal>\item[{\tt label text}]</literal>. -Similarly, get normal text use <literal>\item[{\rm label text}]</literal>. +change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will +come out bold. For instance, if the label text calls for typewriter +with <literal>\item[\texttt{label text}]</literal> then it will appear in bold +typewriter, if that is available. The simplest way to get non-bold +typewriter is to use declarative style: <literal>\item[{\tt label +text}]</literal>. Similarly, to get the standard roman font, use +<literal>\item[{\rm label text}]</literal>. </para> <para>For other major &latex; labelled list environments, see <link linkend="itemize">itemize</link> and <link linkend="enumerate">enumerate</link>. For information about customizing list layout, see @@ -2032,12 +2660,13 @@ and <link linkend="enumerate">enumerate</link>. For information about customizi <title><literal>displaymath</literal></title> <!-- http://tex.stackexchange.com/questions/40492/what-are-the-differences-between-align-equation-and-displaymath --> -<indexterm role="fn"><primary>displaymath environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> <para>Synopsis: </para> <screen>\begin{displaymath} - .. math text .. + ... math text ... \end{displaymath} </screen> <para>Environment to typeset the math text on its own line, in display style @@ -2080,7 +2709,8 @@ spacing, and because the <literal>displaymath</literal> environment honors the <sect1 label="8.6" id="document"> <title><literal>document</literal></title> -<indexterm role="fn"><primary>document environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>document</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>document</literal> environment</primary></indexterm> <para>The <literal>document</literal> environment encloses the entire body of a document. It is required in every &latex; document. See <link linkend="Starting-and-ending">Starting and ending</link>. @@ -2130,7 +2760,8 @@ will be executed in the order that you gave them. <sect1 label="8.7" id="enumerate"> <title><literal>enumerate</literal></title> -<indexterm role="fn"><primary>enumerate environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>enumerate</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>enumerate</literal> environment</primary></indexterm> <indexterm role="cp"><primary>lists of items, numbered</primary></indexterm> <para>Synopsis: @@ -2208,7 +2839,8 @@ period: <sect1 label="8.8" id="eqnarray"> <title><literal>eqnarray</literal></title> -<indexterm role="fn"><primary>eqnarray environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>eqnarray</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>eqnarray</literal> environment</primary></indexterm> <indexterm role="cp"><primary>equations, aligning</primary></indexterm> <indexterm role="cp"><primary>aligning equations</primary></indexterm> @@ -2277,7 +2909,8 @@ while the third line has not entry on the left side. <sect1 label="8.9" id="equation"> <title><literal>equation</literal></title> -<indexterm role="fn"><primary>equation environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> <indexterm role="cp"><primary>equations, environment for</primary></indexterm> <indexterm role="cp"><primary>formulas, environment for</primary></indexterm> @@ -2301,7 +2934,8 @@ new documents. <sect1 label="8.10" id="figure"> <title><literal>figure</literal></title> -<indexterm role="fn"><primary>figure</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>figure</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>figure</literal> environment</primary></indexterm> <indexterm role="cp"><primary>inserting figures</primary></indexterm> <indexterm role="cp"><primary>figures, inserting</primary></indexterm> @@ -2338,7 +2972,7 @@ in <link linkend="Floats">Floats</link>. <para>The figure body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal> and so it can contain text, commands, etc. </para> -<para>The label is optional; it is used for cross-references (see <link linkend="Cross-references">Cross +<para>The label is optional; it is used for cross references (see <link linkend="Cross-references">Cross references</link>). <indexterm role="fn"><primary>\caption</primary></indexterm> The optional <literal>\caption</literal> command specifies caption text for the @@ -2362,7 +2996,10 @@ end of the document, on a page of floats. <sect1 label="8.11" id="filecontents"> <title><literal>filecontents</literal>: Write an external file</title> -<indexterm role="fn"><primary>filecontents</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>filecontents</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>filecontents</literal> environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>filecontents*</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>filecontents*</literal> environment</primary></indexterm> <indexterm role="cp"><primary>external files, writing</primary></indexterm> <indexterm role="cp"><primary>writing external files</primary></indexterm> @@ -2419,7 +3056,8 @@ Article by \myname. <sect1 label="8.12" id="flushleft"> <title><literal>flushleft</literal></title> -<indexterm role="fn"><primary>flushleft environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>flushleft</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>flushleft</literal> environment</primary></indexterm> <indexterm role="cp"><primary>left-justifying text, environment for</primary></indexterm> <indexterm role="cp"><primary>ragged right text, environment for</primary></indexterm> @@ -2460,7 +3098,8 @@ command that ends the paragraph unit. <sect1 label="8.13" id="flushright"> <title><literal>flushright</literal></title> -<indexterm role="fn"><primary>flushright environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>flushright</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>flushright</literal> environment</primary></indexterm> <indexterm role="cp"><primary>ragged left text, environment for</primary></indexterm> <indexterm role="cp"><primary>right-justifying text, environment for</primary></indexterm> @@ -2501,7 +3140,8 @@ command that ends the paragraph unit. <sect1 label="8.14" id="itemize"> <title><literal>itemize</literal></title> -<indexterm role="fn"><primary>itemize environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>itemize</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>itemize</literal> environment</primary></indexterm> <indexterm role="fn"><primary>\item</primary></indexterm> <indexterm role="cp"><primary>lists of items</primary></indexterm> <indexterm role="cp"><primary>unordered lists</primary></indexterm> @@ -2516,7 +3156,7 @@ command that ends the paragraph unit. \end{itemize} </screen> <para>The <literal>itemize</literal> environment produces an “unordered”, “bulleted” -list. Itemizations can be nested within one another, up to four +list. Itemized lists can be nested within one another, up to four levels deep. They can also be nested within other paragraph-making environments, such as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). </para> @@ -2628,7 +3268,8 @@ see <link linkend="_005cparskip">\parskip</link>): <sect1 label="8.15" id="letter"> <title><literal>letter</literal> environment: writing letters</title> -<indexterm role="fn"><primary>letter environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>letter</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>letter</literal> environment</primary></indexterm> <para>This environment is used for creating letters. See <link linkend="Letters">Letters</link>. </para> @@ -2637,7 +3278,8 @@ see <link linkend="_005cparskip">\parskip</link>): <sect1 label="8.16" id="list"> <title><literal>list</literal></title> -<indexterm role="fn"><primary>list</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>list</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>list</literal> environment</primary></indexterm> <indexterm role="cp"><primary>lists of items, generic</primary></indexterm> <para>The <literal>list</literal> environment is a generic environment which is used for @@ -2664,7 +3306,8 @@ empty, i.e., <literal>{}</literal>, which leaves the default spacing. </para> -<anchor id="_005citem"/> +<sect2 label="8.16.1" id="_005citem"> +<title><literal>\item</literal>: An entry in a list.</title> <para>Synopsis: </para> @@ -2699,11 +3342,13 @@ not get a ‘<literal>3.</literal>’). </para> +</sect2> </sect1> <sect1 label="8.17" id="math"> <title><literal>math</literal></title> -<indexterm role="fn"><primary>math environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> <indexterm role="cp"><primary>in-line formulas</primary></indexterm> <para>Synopsis: @@ -2721,7 +3366,8 @@ See <link linkend="Math-formulas">Math formulas</link>. <sect1 label="8.18" id="minipage"> <title><literal>minipage</literal></title> -<indexterm role="fn"><primary>minipage environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>minipage</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>minipage</literal> environment</primary></indexterm> <indexterm role="cp"><primary>minipage, creating a</primary></indexterm> <screen>\begin{minipage}[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>} @@ -2760,7 +3406,8 @@ footnotes; they may wind up at the bottom of the wrong minipage. <sect1 label="8.19" id="picture"> <title><literal>picture</literal></title> -<indexterm role="fn"><primary>picture</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>picture</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>picture</literal> environment</primary></indexterm> <indexterm role="cp"><primary>creating pictures</primary></indexterm> <indexterm role="cp"><primary>pictures, creating</primary></indexterm> @@ -2783,6 +3430,14 @@ centimeters. <literal>\setlength</literal> command, outside of a <literal>picture</literal> environment. The default value is <literal>1pt</literal>. </para> +<indexterm role="cp"><primary>package, <literal>picture</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>picture</literal> package</primary></indexterm> +<para>The <literal>picture</literal> package redefine the <literal>picture</literal> environment so +that everywhere a number is used in a <replaceable>picture commands</replaceable> to specify +a coordinate, one can use alternatively a length. Be aware however that +this will prevent scaling those lengths by changing <literal>\unitlength</literal>. +</para> + <indexterm role="cp"><primary>position, in picture</primary></indexterm> <para>A <firstterm>position</firstterm> is a pair of coordinates, such as <literal>(2.4,-5)</literal>, specifying the point with x-coordinate <literal>2.4</literal> and y-coordinate <literal>-5</literal>. @@ -3106,11 +3761,13 @@ values must lie between −4 and +4, inclusive. <sect1 label="8.20" id="quotation-and-quote"> <title><literal>quotation</literal> and <literal>quote</literal></title> -<indexterm role="fn"><primary>quotation</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>quotation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>quotation</literal> environment</primary></indexterm> <indexterm role="cp"><primary>quoted text with paragraph indentation, displaying</primary></indexterm> <indexterm role="cp"><primary>displaying quoted text with paragraph indentation</primary></indexterm> <indexterm role="cp"><primary>paragraph indentations in quoted text</primary></indexterm> -<indexterm role="fn"><primary>quote</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>quote</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>quote</literal> environment</primary></indexterm> <indexterm role="cp"><primary>quoted text without paragraph indentation, displaying</primary></indexterm> <indexterm role="cp"><primary>displaying quoted text without paragraph indentation</primary></indexterm> <indexterm role="cp"><primary>paragraph indentations in quoted text, omitting</primary></indexterm> @@ -3145,7 +3802,7 @@ quotations. </para> <screen>\begin{quotation} \it Four score and seven years ago - .. shall not perish from the earth. + ... shall not perish from the earth. \hspace{1em plus 1fill}---Abraham Lincoln \end{quotation} </screen> @@ -3154,7 +3811,8 @@ quotations. <sect1 label="8.21" id="tabbing"> <title><literal>tabbing</literal></title> -<indexterm role="fn"><primary>tabbing environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>tabbing</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>tabbing</literal> environment</primary></indexterm> <indexterm role="cp"><primary>tab stops, using</primary></indexterm> <indexterm role="cp"><primary>lining text up using tab stops</primary></indexterm> <indexterm role="cp"><primary>alignment via tabbing</primary></indexterm> @@ -3259,7 +3917,8 @@ function \= fact(n : integer) : integer;\\ <sect1 label="8.22" id="table"> <title><literal>table</literal></title> -<indexterm role="fn"><primary>table</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>table</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>table</literal> environment</primary></indexterm> <indexterm role="cp"><primary>tables, creating</primary></indexterm> <indexterm role="cp"><primary>creating tables</primary></indexterm> @@ -3282,7 +3941,7 @@ float placement algorithm, see <link linkend="Floats">Floats</link>. <para>The table body is typeset in a <literal>parbox</literal> of width <literal>\textwidth</literal> and so it can contain text, commands, etc. </para> -<para>The label is optional; it is used for cross-references (see <link linkend="Cross-references">Cross +<para>The label is optional; it is used for cross references (see <link linkend="Cross-references">Cross references</link>). <indexterm role="fn"><primary>\caption</primary></indexterm> The optional <literal>\caption</literal> command specifies caption text for the @@ -3309,7 +3968,8 @@ unless it is pushed to a float page at the end. <sect1 label="8.23" id="tabular"> <title><literal>tabular</literal></title> -<indexterm role="fn"><primary>tabular environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>tabular</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>tabular</literal> environment</primary></indexterm> <indexterm role="cp"><primary>lines in tables</primary></indexterm> <indexterm role="cp"><primary>lining text up in tables</primary></indexterm> @@ -3356,7 +4016,7 @@ the width of the <literal>tabular*</literal> environment. The space between col should be rubber, as with <literal>@{\extracolsep{\fill}}</literal>, to allow the table to stretch or shrink to make the specified width, or else you are likely to get the <literal>Underfull \hbox (badness 10000) in alignment -..</literal> warning. +...</literal> warning. </para> </listitem></varlistentry><varlistentry><term><replaceable>pos</replaceable> </term><listitem><para>Optional. Specifies the table’s vertical position. The default is to @@ -3391,14 +4051,14 @@ column and intercolumn material. <replaceable>text or space</replaceable> material is typeset in LR mode. This text is fragile (see <link linkend="_005cprotect">\protect</link>). </para> -<para>This specifier is optional: unless you put in your own @-expression -then &latex;’s book, article, and report classes will put on either -side of each column a space of length <literal>\tabcolsep</literal>, which by -default is ‘<literal>6pt</literal>’. That is, by default adjacent columns are +<para>This specifier is optional: with no @-expression, &latex;’s +<literal>book</literal>, <literal>article</literal>, and <literal>report</literal> classes will put on +either side of each column a space of length <literal>\tabcolsep</literal>, which +by default is ‘<literal>6pt</literal>’. That is, by default adjacent columns are separated by 12pt (so <literal>\tabcolsep</literal> is misleadingly-named since it -is not the separation between tabular columns). Also by default a space -of 6pt comes before the first column as well as after the final column, -unless you put a <literal>@{..}</literal> or <literal>|</literal> there. +is not the separation between tabular columns). By implication, a +space of 6pt also comes before the first column and after the final +column, unless you put a <literal>@{...}</literal> or <literal>|</literal> there. </para> <para>If you override the default and use an @-expression then you must insert any desired space yourself, as in <literal>@{\hspace{1em}}</literal>. @@ -3409,7 +4069,7 @@ lines need to lie on the left margin. </para> <screen>\begin{flushleft} \begin{tabular}{@{}l} - .. + ... \end{tabular} \end{flushleft} </screen> @@ -3460,7 +4120,7 @@ ending the row. positive integer and <replaceable>cols</replaceable> is a list of specifiers. Thus <literal>\begin{tabular}{|*{3}{l|r}|}</literal> is equivalent to <literal>\begin{tabular}{|l|rl|rl|r|}</literal>. Note that <replaceable>cols</replaceable> may -contain another <literal>*-expression</literal>. +contain another <literal>*</literal>-expression. </para> </listitem></varlistentry></variablelist></listitem></varlistentry></variablelist> <para>Parameters that control formatting: @@ -3514,7 +4174,7 @@ spanned by the single heading ‘<literal>Name</literal>’. <screen>\begin{tabular}{lccl} \textit{ID} &\multicolumn{2}{c}{\textit{Name}} &\textit{Age} \\ \hline % row one 978-0-393-03701-2 &O'Brian &Patrick &55 \\ % row two - .. + ... \end{tabular} </screen> <para>What counts as a column is: the column format specifier for the @@ -3527,7 +4187,7 @@ and <literal>p{1.5in}|</literal>. <para>The <replaceable>cols</replaceable> argument overrides the <literal>array</literal> or <literal>tabular</literal> environment’s intercolumn area default adjoining this multicolumn entry. To affect that area, this argument can contain vertical bars -<literal>|</literal> indicating the placement of vertical rules, and <literal>@{..}</literal> +<literal>|</literal> indicating the placement of vertical rules, and <literal>@{...}</literal> expressions. Thus if <replaceable>cols</replaceable> is ‘<literal>|c|</literal>’ then this multicolumn entry will be centered and a vertical rule will come in the intercolumn area before it and after it. This table details the exact behavior. @@ -3538,7 +4198,8 @@ area before it and after it. This table details the exact behavior. &\multicolumn{1}{|r}{y} % entry three &z % entry four \end{tabular} -</screen><para>Before the first entry the output will not have a vertical rule because +</screen> +<para>Before the first entry the output will not have a vertical rule because the <literal>\multicolumn</literal> has the <replaceable>cols</replaceable> specifier ‘<literal>r</literal>’ with no initial vertical bar. Between entry one and entry two there will be a vertical rule; although the first <replaceable>cols</replaceable> does not have an ending @@ -3584,13 +4245,13 @@ vertical bar in the <replaceable>cols</replaceable> of either of the first row&# <title><literal>\vline</literal></title> <indexterm role="fn"><primary>\vline</primary></indexterm> - <para>Draw a vertical line in a <literal>tabular</literal> or <literal>array</literal> environment -extending the full height and depth of an entry’s row. Can also be used -in an @-expression, although its synonym vertical bar <literal>|</literal> is -more common. This command is rarely used; typically a table’s vertical -lines are specified in <literal>tabular</literal>’s <replaceable>cols</replaceable> argument and -overriden as needed with <literal>\multicolumn</literal>. +extending the full height and depth of an entry’s row. Can also be +used in an @-expression, although its synonym vertical +bar <literal>|</literal> is more common. This command is rarely used in the +body of a table; typically a table’s vertical lines are specified in +<literal>tabular</literal>’s <replaceable>cols</replaceable> argument and overridden as needed with +<literal>\multicolumn</literal>. </para> <para>This example illustrates some pitfalls. In the first line’s second entry the <literal>\hfill</literal> moves the <literal>\vline</literal> to the left edge of the @@ -3663,7 +4324,8 @@ is required. <sect1 label="8.24" id="thebibliography"> <title><literal>thebibliography</literal></title> -<indexterm role="fn"><primary>thebibliography environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>thebibliography</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>thebibliography</literal> environment</primary></indexterm> <indexterm role="cp"><primary>bibliography, creating (manually)</primary></indexterm> <para>Synopsis: @@ -3700,18 +4362,19 @@ less than 10 references, <literal>99</literal> for ones with less than 100, etc. </para> <screen>\bibitem[<replaceable>label</replaceable>]{<replaceable>cite_key</replaceable>} </screen> -<para>The <literal>\bibitem</literal> command generates an entry labelled by -<replaceable>label</replaceable>. If the <replaceable>label</replaceable> argument is missing, a number is -automatically generated using the <literal>enumi</literal> counter. The -<replaceable>cite_key</replaceable> is any sequence of letters, numbers, and punctuation -symbols not containing a comma. +<para>The <literal>\bibitem</literal> command generates an entry labelled by <replaceable>label</replaceable>. +If the <replaceable>label</replaceable> argument is missing, a number is automatically +generated using the <literal>enumi</literal> counter. The <replaceable>cite_key</replaceable> is a +<indexterm role="cp"><primary>citation key</primary></indexterm> +<firstterm>citation key</firstterm> consisting in any sequence of +letters, numbers, and punctuation symbols not containing a comma. </para> <para>This command writes an entry to the <filename>.aux</filename> file containing the -item’s <replaceable>cite_key</replaceable> and label. When the <filename>.aux</filename> file is read by -the <literal>\begin{document}</literal> command, the item’s <literal>label</literal> is +item’s <replaceable>cite_key</replaceable> and <replaceable>label</replaceable>. When the <filename>.aux</filename> file is +read by the <literal>\begin{document}</literal> command, the item’s <replaceable>label</replaceable> is associated with <literal>cite_key</literal>, causing references to <replaceable>cite_key</replaceable> -with a <literal>\cite</literal> command (see next section) to produce the -associated label. +with a <literal>\cite</literal> command (see <link linkend="_005ccite">\cite</link>) to produce the associated +<replaceable>label</replaceable>. </para> </sect2> @@ -3724,14 +4387,14 @@ associated label. </para> <screen>\cite[<replaceable>subcite</replaceable>]{<replaceable>keys</replaceable>} </screen> -<para>The <replaceable>keys</replaceable> argument is a list of one or more citation keys, -separated by commas. This command generates an in-text citation to -the references associated with <replaceable>keys</replaceable> by entries in the -<filename>.aux</filename> file. +<para>The <replaceable>keys</replaceable> argument is a list of one or more citation keys +(see <link linkend="_005cbibitem">\bibitem</link>), separated by commas. This command generates an +in-text citation to the references associated with <replaceable>keys</replaceable> by entries +in the <filename>.aux</filename> file. </para> <para>The text of the optional <replaceable>subcite</replaceable> argument appears after the citation. For example, <literal>\cite[p.~314]{knuth}</literal> might produce -‘[Knuth, p. 314]’. +‘<literal>[Knuth, p. 314]</literal>’. </para> </sect2> @@ -3740,8 +4403,10 @@ citation. For example, <literal>\cite[p.~314]{knuth}</literal> might produce <indexterm role="fn"><primary>\nocite</primary></indexterm> -<para><literal>\nocite{<replaceable>keys</replaceable>}</literal> +<para>Synopsis: </para> +<screen><literal>\nocite{<replaceable>keys</replaceable>}</literal> +</screen> <para>The <literal>\nocite</literal> command produces no text, but writes <replaceable>keys</replaceable>, which is a list of one or more citation keys, to the <filename>.aux</filename> file. </para> @@ -3769,7 +4434,7 @@ you include the lines its own. Rather, it defines the style in which the bibliography will be produced: <replaceable>bibstyle</replaceable> refers to a file <replaceable>bibstyle</replaceable><filename>.bst</filename>, which defines how your citations will look. -The standard <replaceable>style</replaceable> names distributed with Bib&tex; are: +The standard <replaceable>bibstyle</replaceable> names distributed with Bib&tex; are: </para> <variablelist><varlistentry><term><literal>alpha</literal> </term><listitem><para>Sorted alphabetically. Labels are formed from name of author and year of @@ -3787,7 +4452,8 @@ the demands of various publications. See </para> <para>The <literal>\bibliography</literal> command is what actually produces the bibliography. The argument to <literal>\bibliography</literal> refers to files -named <filename><replaceable>bibfile</replaceable>.bib</filename>, which should contain your database in +named <filename><replaceable>bibfile1</replaceable>.bib</filename>, <filename><replaceable>bibfile2</replaceable>.bib</filename>, …, +which should contain your database in Bib&tex; format. Only the entries referred to via <literal>\cite</literal> and <literal>\nocite</literal> will be listed in the bibliography. </para> @@ -3797,7 +4463,8 @@ Bib&tex; format. Only the entries referred to via <literal>\cite</literal> and <sect1 label="8.25" id="theorem"> <title><literal>theorem</literal></title> -<indexterm role="fn"><primary>theorem environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>theorem</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>theorem</literal> environment</primary></indexterm> <indexterm role="cp"><primary>theorems, typesetting</primary></indexterm> <para>Synopsis: @@ -3816,31 +4483,54 @@ possibilities for <replaceable>n</replaceable> are described under <literal>\new <sect1 label="8.26" id="titlepage"> <title><literal>titlepage</literal></title> -<indexterm role="fn"><primary>titlepage environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>titlepage</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>titlepage</literal> environment</primary></indexterm> <indexterm role="cp"><primary>making a title page</primary></indexterm> <indexterm role="cp"><primary>title pages, creating</primary></indexterm> <para>Synopsis: </para> <screen>\begin{titlepage} -<replaceable>text</replaceable> + ... text and spacing ... \end{titlepage} </screen> -<para>The <literal>titlepage</literal> environment creates a title page, i.e., a page -with no printed page number or heading. It also causes the following -page to be numbered page one. Formatting the title page is left to -you. The <literal>\today</literal> command may be useful on title pages -(see <link linkend="_005ctoday">\today</link>). +<para>Create a title page, a page with no printed page number or heading. The +following page will be numbered page one. </para> -<para>You can use the <literal>\maketitle</literal> command (see <link linkend="_005cmaketitle">\maketitle</link>) to -produce a standard title page without a <literal>titlepage</literal> environment. +<para>To instead produce a standard title page without a <literal>titlepage</literal> +environment you can use <literal>\maketitle</literal> (see <link linkend="_005cmaketitle">\maketitle</link>). </para> +<para>Notice in this example that all formatting, including vertical spacing, +is left to the author. +</para> +<screen>\begin{titlepage} +\vspace*{\stretch{1}} +\begin{center} + {\huge\bfseries Thesis \\[1ex] + title} \\[6.5ex] + {\large\bfseries Author name} \\ + \vspace{4ex} + Thesis submitted to \\[5pt] + \textit{University name} \\[2cm] + in partial fulfilment for the award of the degree of \\[2cm] + \textsc{\Large Doctor of Philosophy} \\[2ex] + \textsc{\large Mathematics} \\[12ex] + \vfill + Department of Mathematics \\ + Address \\ + \vfill + \today +\end{center} +\vspace{\stretch{2}} +\end{titlepage} +</screen> </sect1> <sect1 label="8.27" id="verbatim"> <title><literal>verbatim</literal></title> -<indexterm role="fn"><primary>verbatim environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>verbatim</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>verbatim</literal> environment</primary></indexterm> <indexterm role="cp"><primary>verbatim text</primary></indexterm> <indexterm role="cp"><primary>simulating typed text</primary></indexterm> <indexterm role="cp"><primary>typed text, simulating</primary></indexterm> @@ -3889,7 +4579,8 @@ verbatim text. The delimiter must not appear in <replaceable>literal-text</repl <sect1 label="8.28" id="verse"> <title><literal>verse</literal></title> -<indexterm role="fn"><primary>verse environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>verse</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>verse</literal> environment</primary></indexterm> <indexterm role="cp"><primary>poetry, an environment for</primary></indexterm> <para>Synopsis: @@ -3953,7 +4644,7 @@ particular, to start a new paragraph instead leave a blank line. This command is mostly used outside of the main flow of text such as in a <literal>tabular</literal> or <literal>array</literal> environment. </para> -<para>Under ordinary circumstances (e.g., outside of a <literal>p{..}</literal> column +<para>Under ordinary circumstances (e.g., outside of a <literal>p{...}</literal> column in a <literal>tabular</literal> environment) the <literal>\newline</literal> command is a synonym for <literal>\\</literal> (see <link linkend="_005cnewline">\newline</link>). </para> @@ -3992,7 +4683,7 @@ in the output. breaks a line, with no stretching of the text before it. </para> <para>Inside a <literal>tabular</literal> or <literal>array</literal> environment, in a column with a -specifier producing a paragraph box, like typically <literal>p{..}</literal>, +specifier producing a paragraph box, like typically <literal>p{...}</literal>, <literal>\newline</literal> will insert a line break inside of the column, that is, it does not break the entire row. To break the entire row use <literal>\\</literal> or its equivalent <literal>\tabularnewline</literal>. @@ -4024,9 +4715,20 @@ cases. hyphenated at those points and not at any of the hyphenation points that &latex; might otherwise have chosen. </para> +</sect1> +<sect1 label="9.5" id="_005cdiscretionary"> +<title><literal>\discretionary</literal> (generalized hyphenation point)</title> +<indexterm role="cp"><primary>hyphenation, discretionary</primary></indexterm> +<indexterm role="cp"><primary>discretionary hyphenation</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\discretionary{<replaceable>pre-break-text</replaceable>}{<replaceable>post-break-text</replaceable>}{<replaceable>no-break-text</replaceable>} +</screen> +<!-- xxx TODO, complete this node, see LaTeX-fr --> </sect1> -<sect1 label="9.5" id="_005cfussy"> +<sect1 label="9.6" id="_005cfussy"> <title><literal>\fussy</literal></title> <indexterm role="fn"><primary>\fussy</primary></indexterm> @@ -4036,11 +4738,11 @@ picky about line breaking. This usually avoids too much space between words, at the cost of an occasional overfull box. </para> <para>This command cancels the effect of a previous <literal>\sloppy</literal> command -(see <link linkend="_005csloppy">\sloppy</link>. +(see <link linkend="_005csloppy">\sloppy</link>). </para> </sect1> -<sect1 label="9.6" id="_005csloppy"> +<sect1 label="9.7" id="_005csloppy"> <title><literal>\sloppy</literal></title> <indexterm role="fn"><primary>\sloppy</primary></indexterm> @@ -4053,7 +4755,7 @@ interword spacing. </para> </sect1> -<sect1 label="9.7" id="_005chyphenation"> +<sect1 label="9.8" id="_005chyphenation"> <title><literal>\hyphenation</literal></title> <indexterm role="fn"><primary>\hyphenation</primary></indexterm> @@ -4074,7 +4776,7 @@ misses the hyphenations in these words): </screen> </sect1> -<sect1 label="9.8" id="_005clinebreak-_0026-_005cnolinebreak"> +<sect1 label="9.9" id="_005clinebreak-_0026-_005cnolinebreak"> <title><literal>\linebreak</literal> & <literal>\nolinebreak</literal></title> <indexterm role="fn"><primary>\linebreak</primary></indexterm> @@ -4338,7 +5040,8 @@ but nothing is set at the bottom of the page. \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.} + \textit{HMS Surprise} &A number of books\footnote{Starting with + HMS Surprise.} \end{tabular} \end{center} </screen> @@ -4347,7 +5050,7 @@ but nothing is set at the bottom of the page. </para> <screen>\begin{center} \begin{minipage}{.5\textwidth} - .. tabular material .. + ... tabular material ... \end{minipage} \end{center} </screen> @@ -4374,22 +5077,28 @@ sequence with other footnotes. <sect1 label="11.5" id="Footnotes-in-section-headings"> <title>Footnotes in section headings</title> -<para>Putting a footnote in a section heading +<indexterm role="cp"><primary>footnotes, in section headings</primary></indexterm> +<indexterm role="cp"><primary>table of contents, avoiding footnotes</primary></indexterm> +<para>Putting a footnote in a section heading, as in: </para> -<screen>\section{Full sets\protect\footnote{This material is due to R~Jones.}} +<screen>\section{Full sets\protect\footnote{This material due to ...}} </screen> -<para>causes the footnote to appear both at the bottom of the page where the -section starts and at the bottom of the table of contents page. To have -it not appear on the table of contents use the package <filename>footmisc</filename> -with the <literal>stable</literal> option. +<indexterm role="cp"><primary>package, <literal>footmisc</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>footmisc</literal> package</primary></indexterm> +<indexterm role="cp"><primary><literal>stable</literal> option to <literal>footmisc</literal> package</primary></indexterm> +<para>causes the footnote to appear at the bottom of the page where the +section starts, as usual, but also at the bottom of the table of +contents, where it is not likely to be desired. To have it not appear +on the table of contents use the package <filename>footmisc</filename> with the +<literal>stable</literal> option. </para> <screen>\usepackage[stable]{footmisc} - .. +... \begin{document} - .. -\section{Full sets\footnote{This material is due to R~Jones.}} +... +\section{Full sets\footnote{This material due to ...}} </screen> -<para>Note that the <literal>\protect</literal> is gone; putting it in causes the +<para>Note that the <literal>\protect</literal> is gone; including it would cause the footnote to reappear on the table of contents. </para> @@ -4405,12 +5114,12 @@ ways, including allow these two, as in this example. <screen>\usepackage{bigfoot} \DeclareNewFootnote{Default} \DeclareNewFootnote{from}[alph] % create class \footnotefrom{} - .. + ... \begin{document} - .. +... The third theorem is a partial converse of the second.\footnotefrom{First noted in Wilson.\footnote{Second edition only.}} - .. +... </screen> </sect1> @@ -4423,13 +5132,13 @@ uses the package <filename>cleverref</filename>. <!-- from SE user Jake http://tex.stackexchange.com/a/10116/339 --> <screen>\usepackage{cleveref}[2012/02/15] % this version of package or later \crefformat{footnote}{#2\footnotemark[#1]#3} - .. +... \begin{document} - .. +... The theorem is from Evers.\footnote{\label{fn:TE}Tinker and Evers, 1994.} The corollary is from Chance.\footnote{Evers and Chance, 1990.} But the key lemma is from Tinker.\cref{fn:TE} - .. +... </screen> <para>This solution will work with the package <filename>hyperref</filename>. See <link linkend="_005cfootnotemark">\footnotemark</link> for a simpler solution in the common case @@ -4483,75 +5192,80 @@ footnotes. This is ‘<literal>6.65pt</literal>’ for ‘<literal> <para><literal>\newcommand</literal> and <literal>\renewcommand</literal> define and redefine a command, respectively. Synopses: </para> -<screen> \newcommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} - \newcommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} -\renewcommand{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} -\renewcommand*{<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +<screen> \newcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} + \newcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} +\renewcommand*{\<replaceable>cmd</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>defn</replaceable>} </screen> -<para>The <literal>*</literal>-form of these two commands requires that the arguments -not contain multiple paragraphs of text (not <literal>\long</literal>, in plain -&tex; terms). +<indexterm role="cp"><primary>starred form, defining new commands</primary></indexterm> +<indexterm role="cp"><primary>*-form, defining new commands</primary></indexterm> +<para>The starred form of these two commands requires that the arguments not +contain multiple paragraphs of text (not <literal>\long</literal>, in plain &tex; +terms). </para> <variablelist><varlistentry><term><replaceable>cmd</replaceable> -</term><listitem><para>Required; the command name. It must begin with <literal>\</literal>. For -<literal>\newcommand</literal>, it must not be already defined and must not begin -with <literal>\end</literal>. For <literal>\renewcommand</literal>, it must already be -defined. +</term><listitem><para>Required; <literal>\<replaceable>cmd</replaceable></literal> is the command name. For <literal>\newcommand</literal>, it +must not be already defined and must not begin with <literal>\end</literal>. For +<literal>\renewcommand</literal>, it must already be defined. </para> </listitem></varlistentry><varlistentry><term><replaceable>nargs</replaceable> </term><listitem><para>Optional; an integer from 0 to 9, specifying the number of arguments -that the command will take. If this argument is not present, the -default is for the command to have no arguments. When redefining a -command, the new version can have a different number of arguments than -the old version. +that the command can take, including any optional argument. If this +argument is not present, the default is for the command to have no +arguments. When redefining a command, the new version can have a +different number of arguments than the old version. </para> </listitem></varlistentry><varlistentry><term><replaceable>optargdefault</replaceable> </term><listitem><para>Optional; if this argument is present then the first argument of defined -command <replaceable>\cmd</replaceable> is optional, with default value <replaceable>optargdefault</replaceable> +command <literal>\<replaceable>cmd</replaceable></literal> is optional, with default value <replaceable>optargdefault</replaceable> (which may be the empty string). If this argument is not present then -<replaceable>\cmd</replaceable> does not take an optional argument. -</para> -<para>That is, if <replaceable>\cmd</replaceable> is used with square brackets following, as in -<literal>\<replaceable>cmd</replaceable>[<replaceable>myval</replaceable>]</literal>, then within <replaceable>defn</replaceable> <literal>#1</literal> expands -<replaceable>myval</replaceable>. While if <replaceable>\cmd</replaceable> is called without square brackets -following, then within <replaceable>defn</replaceable> the <literal>#1</literal> expands to the default -<replaceable>optargdefault</replaceable>. In either case, any required arguments will be -referred to starting with <literal>#2</literal>. -</para> -<para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in the call is different from having the +<literal>\<replaceable>cmd</replaceable></literal> does not take an optional argument. +</para> +<indexterm role="cp"><primary>positional parameter</primary></indexterm> +<para>That is, if <literal>\<replaceable>cmd</replaceable></literal> is used with square brackets following, +as in <literal>\<replaceable>cmd</replaceable>[<replaceable>myval</replaceable>]</literal>, then within <replaceable>defn</replaceable> the first +<firstterm>positional parameter</firstterm> <literal>#1</literal> expands <replaceable>myval</replaceable>. On the +other hand, if <literal>\<replaceable>cmd</replaceable></literal> is called without square brackets +following, then within <replaceable>defn</replaceable> the positional parameter <literal>#1</literal> +expands to the default <replaceable>optargdefault</replaceable>. In either case, any +required arguments will be referred to starting with <literal>#2</literal>. +</para> +<para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in a call is different from having the square brackets with no contents, as in <literal>[]</literal>. The former results in <literal>#1</literal> expanding to <replaceable>optargdefault</replaceable>; the latter results in <literal>#1</literal> expanding to the empty string. </para> </listitem></varlistentry><varlistentry><term><replaceable>defn</replaceable> -</term><listitem><para>The text to be substituted for every occurrence of <literal>cmd</literal>; a -construct of the form <literal>#<replaceable>n</replaceable></literal> in <replaceable>defn</replaceable> is replaced by the -text of the <replaceable>n</replaceable>th argument. +</term><listitem><para>The text to be substituted for every occurrence of <literal>\<replaceable>cmd</replaceable></literal>; the +positional parameter <literal>#<replaceable>n</replaceable></literal> in <replaceable>defn</replaceable> is replaced by +the text of the <replaceable>n</replaceable>th argument. </para> </listitem></varlistentry></variablelist> -<para>A command with no arguments that is followed in the source by a space -will swallow that space. The solution is to type <literal>{}</literal> after the -command and before the space. +<para>&tex; ignores spaces in the source following an alphabetic control +sequence, as in ‘<literal>\cmd </literal>’. If you actually want a space there, one +solution is to type <literal>{}</literal> after the command (‘<literal>\cmd{} </literal>’; +another solution is to use an explicit control space (‘<literal>\cmd\ </literal>’). </para> <para>A simple example of defining a new command: -<literal>\newcommand{\JH}{Jim Hef{}feron}</literal> causes the abbreviation -<literal>\JH</literal> to be replaced by the longer text. +<literal>\newcommand{\RS}{Robin Smith}</literal> results in +<literal>\RS</literal> being replaced by the longer text. </para> -<para>Redefining a command is basically the same: +<para>Redefining an existing command is similar: <literal>\renewcommand{\qedsymbol}{{\small QED}}</literal>. </para> -<para>Here’s a command definition that uses arguments: +<para>Here’s a command definition with one required argument: </para> -<screen>\newcommand{\defreference}[1]{Definition~\ref{#1}} +<screen>\newcommand{\defref}[1]{Definition~\ref{#1}} </screen> -<para>Then, <literal>\defreference{def:basis}</literal> will expand to +<para>Then, <literal>\defref{def:basis}</literal> expands to +<literal>Definition~\ref{def:basis}</literal>, which will ultimately expand to something like ‘<literal>Definition~3.14</literal>’. </para> -<para>An example with two arguments: -<literal>\newcommand{\nbym}[2]{#1\!\times\!#2}</literal> is invoked as +<para>An example with two required arguments: +<literal>\newcommand{\nbym}[2]{$#1 \times #2$}</literal> is invoked as <literal>\nbym{2}{k}</literal>. </para> -<para>An example with optional arguments: +<para>An example with an optional argument: </para> <screen>\newcommand{\salutation}[1][Sir or Madam]{Dear #1:} </screen> @@ -4559,15 +5273,17 @@ something like ‘<literal>Definition~3.14</literal>’. <literal>\salutation[John]</literal> gives ‘<literal>Dear John:</literal>’. And <literal>\salutation[]</literal> gives ‘<literal>Dear :</literal>’. </para> -<para>The braces around <replaceable>defn</replaceable> do not delimit the scope of the result of -expanding <replaceable>defn</replaceable>. So <literal>\newcommand{\shipname}[1]{\it #1}</literal> -is wrong since in the sentence +<para>The braces around <replaceable>defn</replaceable> do not define a group, that is, they do +not delimit the scope of the result of expanding <replaceable>defn</replaceable>. So +<literal>\newcommand{\shipname}[1]{\it #1}</literal> is problematic; in this +sentence, </para> -<screen>The \shipname{Monitor} met the \shipname{Virginia}. +<screen>The \shipname{Monitor} met the \shipname{Merrimac}. </screen> -<para>the words ‘<literal>met the</literal>’ will incorrectly be in italics. An -extra pair of braces <literal>\newcommand{\shipname}[1]{{\it #1}}</literal> -fixes it. +<para>the words ‘<literal>met the</literal>’ would incorrectly be in italics. Another +pair of braces in the definition is needed, like this: +<literal>\newcommand{\shipname}[1]{{\it #1}}</literal>. Those braces are +part of the definition and thus do define a group. </para> </sect1> @@ -4599,19 +5315,22 @@ loaded more than once. <indexterm role="fn"><primary>\newcounter</primary></indexterm> <indexterm role="cp"><primary>counters, defining new</primary></indexterm> -<para>Synopsis: +<para>Synopsis, one of: </para> -<screen>\newcounter{<replaceable>countername</replaceable>}[<replaceable>supercounter</replaceable>] +<screen>\newcounter{<replaceable>countername</replaceable>} +\newcounter{<replaceable>countername</replaceable>}[<replaceable>supercounter</replaceable>] </screen> -<para>The <literal>\newcounter</literal> command globally defines a new counter named -<replaceable>countername</replaceable>. The name consists of letters only and does not begin -with a backslash (‘<literal>\</literal>’). The name must not already be used by -another counter. The new counter is initialized to zero. +<para>Globally defines a new counter named <replaceable>countername</replaceable> and initialize +the new counter to zero. +</para> +<para>The name <replaceable>countername</replaceable> must consists of letters only, and does not +begin with a backslash. This name must not already be in use by another +counter. </para> -<para>If the optional argument <literal>[<replaceable>supercounter</replaceable>]</literal> appears, then +<para>When you use the optional argument <literal>[<replaceable>supercounter</replaceable>]</literal> then <replaceable>countername</replaceable> will be numbered within, or subsidiary to, the existing counter <replaceable>supercounter</replaceable>. For example, ordinarily -<literal>subsection</literal> is numbered within <literal>section</literal>. Any time +<literal>subsection</literal> is numbered within <literal>section</literal> so that any time <replaceable>supercounter</replaceable> is incremented with <literal>\stepcounter</literal> (see <link linkend="_005cstepcounter">\stepcounter</link>) or <literal>\refstepcounter</literal> (see <link linkend="_005crefstepcounter">\refstepcounter</link>) then <replaceable>countername</replaceable> is reset to zero. @@ -4675,19 +5394,21 @@ be already defined. <indexterm role="cp"><primary>redefining environments</primary></indexterm> <para>These commands define or redefine an environment <replaceable>env</replaceable>, that is, -<literal>\begin{<replaceable>env</replaceable>} … \end{<replaceable>env</replaceable>}</literal>. Synopses: +<literal>\begin{<replaceable>env</replaceable>} <replaceable>body</replaceable> \end{<replaceable>env</replaceable>}</literal>. Synopses: </para> -<screen> \newenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} +<screen> \newenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} \newenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} -\renewenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} + \renewenvironment{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} \renewenvironment*{<replaceable>env</replaceable>}[<replaceable>nargs</replaceable>][<replaceable>optargdefault</replaceable>]{<replaceable>begdefn</replaceable>}{<replaceable>enddefn</replaceable>} </screen> -<para>Unlike <literal>\newcommand</literal> and <literal>\renewcommand</literal>, the <literal>*</literal>-forms -<literal>\newenvironment*</literal> and <literal>\renewcommand*</literal> have the same effect -as the forms with no <literal>*</literal>. +<indexterm role="cp"><primary><literal>*</literal>-form of environment commands</primary></indexterm> +<para>The starred form of these commands requires that the arguments not +contain multiple paragraphs of text. The body of these environments can +still contain multiple paragraphs. </para> <variablelist><varlistentry><term><replaceable>env</replaceable> -</term><listitem><para>Required; the environment name. It does not begin with backslash +</term><listitem><para>Required; the environment name. It consists only of letters or the +<literal>*</literal> character, and thus does not begin with backslash (<literal>\</literal>). It must not begin with the string <literal>end</literal>. For <literal>\newenvironment</literal>, the name <replaceable>env</replaceable> must not be the name of an already existing environment, and also the command <literal>\<replaceable>env</replaceable></literal> @@ -4696,8 +5417,8 @@ name of an existing environment. </para> </listitem></varlistentry><varlistentry><term><replaceable>nargs</replaceable> </term><listitem><para>Optional; an integer from 0 to 9 denoting the number of arguments of -that the environment will take. These arguments appear after the -<literal>\begin</literal>, as in +that the environment will take. When the environment is used these +arguments appear after the <literal>\begin</literal>, as in <literal>\begin{<replaceable>env</replaceable>}{<replaceable>arg1</replaceable>}…{<replaceable>argn</replaceable>}</literal>. If this argument is not present then the default is for the environment to have no arguments. When redefining an environment, the new version can have @@ -4709,16 +5430,16 @@ defined environment is optional, with default value <replaceable>optargdefault</ (which may be the empty string). If this argument is not present then the environment does not take an optional argument. </para> -<para>That is, when <literal>[<replaceable>optargdefault</replaceable>]</literal> is present in the environment -definition, if <literal>\begin{<replaceable>env</replaceable>}</literal> is used with square brackets -following, as in <literal>\begin{<replaceable>env</replaceable>}[<replaceable>myval</replaceable>]</literal>, then within -the environment <literal>#1</literal> expands <replaceable>myval</replaceable>. If -<literal>\begin{<replaceable>env</replaceable>}</literal> is called without square brackets following, -then within the environment the <literal>#1</literal> expands to the default -<replaceable>optargdefault</replaceable>. In either case, any required arguments will be -referred to starting with <literal>#2</literal>. +<para>That is, when <literal>[<replaceable>optargdefault</replaceable>]</literal> is present in the +environment definition, if <literal>\begin{<replaceable>env</replaceable>}</literal> is used with +square brackets following, as in +<literal>\begin{<replaceable>env</replaceable>}[<replaceable>myval</replaceable>]</literal>, then, within <replaceable>begdefn</replaceable>, +the positional parameter <literal>#1</literal> expands to <replaceable>myval</replaceable>. If +<literal>\begin{<replaceable>env</replaceable>}</literal> is called without square brackets +following, then, within within <replaceable>begdefn</replaceable>, the positional parameter +<literal>#1</literal> expands to the default <replaceable>optargdefault</replaceable>. In either case, +any required arguments will be referred to starting with <literal>#2</literal>. </para> - <para>Omitting <literal>[<replaceable>myval</replaceable>]</literal> in the call is different from having the square brackets with no contents, as in <literal>[]</literal>. The former results in <literal>#1</literal> expanding to <replaceable>optargdefault</replaceable>; the latter results in @@ -4726,22 +5447,24 @@ in <literal>#1</literal> expanding to <replaceable>optargdefault</replaceable>; </para> </listitem></varlistentry><varlistentry><term><replaceable>begdefn</replaceable> </term><listitem><para>Required; the text expanded at every occurrence of -<literal>\begin{<replaceable>env</replaceable>}</literal>; a construct of the form <literal>#<replaceable>n</replaceable></literal> in -<replaceable>begdef</replaceable> is replaced by the text of the <replaceable>n</replaceable>th argument. +<literal>\begin{<replaceable>env</replaceable>}</literal>. Within <replaceable>begdef</replaceable>, the <replaceable>n</replaceable>th +positional parameter (i.e., <literal>#<replaceable>n</replaceable></literal>) is replaced by the text +of the <replaceable>n</replaceable>th argument. </para> </listitem></varlistentry><varlistentry><term><replaceable>enddefn</replaceable> </term><listitem><para>Required; the text expanded at every occurrence of -<literal>\end{<replaceable>env</replaceable>}</literal>. Note that it may not contain any argument -parameters, so <literal>#<replaceable>n</replaceable></literal> cannot be used here. +<literal>\end{<replaceable>env</replaceable>}</literal>. This may not contain any positional +parameters, so <literal>#<replaceable>n</replaceable></literal> cannot be used here (but see the final +example below). </para> </listitem></varlistentry></variablelist> -<para>The environment <replaceable>env</replaceable> delimits the scope of the result of expanding -<replaceable>begdefn</replaceable> and <replaceable>enddefn</replaceable>. Thus, in the first example below, the -effect of the <literal>\small</literal> is limited to the quote and does not extend -to material following the environment. +<para>All environments, that is to say the <replaceable>begdefn</replaceable> code, the environment +body and the <replaceable>enddefn</replaceable> code, are processed within a group. Thus, in +the first example below, the effect of the <literal>\small</literal> is limited to +the quote and does not extend to material following the environment. </para> -<para>This example gives an environment like &latex;’s <literal>quotation</literal> except that -it will be set in smaller type. +<para>This example gives an environment like &latex;’s <literal>quotation</literal> +except that it will be set in smaller type: </para> <screen>\newenvironment{smallquote}{% \small\begin{quotation} @@ -4749,8 +5472,8 @@ it will be set in smaller type. \end{quotation} } </screen> -<para>This shows the use of arguments; it gives a quotation environment that -cites the author. +<para>This one shows the use of arguments; it gives a quotation environment +that cites the author: </para> <screen>\newenvironment{citequote}[1][Shakespeare]{% \begin{quotation} @@ -4759,15 +5482,15 @@ cites the author. \end{quotation} } </screen> -<para>The author’s name is optional, and defaults to Shakespeare. -In the document, use the environment as here: +<para>The author’s name is optional, and defaults to ‘<literal>Shakespeare</literal>’. +In the document, use the environment like this: </para> <screen>\begin{citequote}[Lincoln] - .. + ... \end{citequote} </screen> <para>The final example shows how to save the value of an argument to use in -<replaceable>enddefn</replaceable>. +<replaceable>enddefn</replaceable>, in this case in a box (see <link linkend="_005csbox">\sbox</link>): </para> <screen>\newsavebox{\quoteauthor} \newenvironment{citequote}[1][Shakespeare]{% @@ -4789,36 +5512,36 @@ In the document, use the environment as here: <indexterm role="cp"><primary>theorem-like environment</primary></indexterm> <indexterm role="cp"><primary>environment, theorem-like</primary></indexterm> -<para>Define a new <firstterm>theorem-like environment</firstterm>. Synopses: +<para>Define a new theorem-like environment. Synopses: </para> -<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] +<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>} +\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] \newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>} </screen> -<para>Both create a theorem-like environment <replaceable>name</replaceable>. Using the first -form, +<para>Using the first form, <literal>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}</literal> +creates an environment that will be labelled with <replaceable>title</replaceable>. See the +first example below. </para> -<screen>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>] -</screen> -<para>with the optional argument after the second required argument, +<para>The second form +<literal>\newtheorem{<replaceable>name</replaceable>}{<replaceable>title</replaceable>}[<replaceable>numbered_within</replaceable>]</literal> creates an environment whose counter is subordinate to the existing -counter <replaceable>numbered_within</replaceable>: it will be reset when +counter <replaceable>numbered_within</replaceable> (its counter will be reset when <replaceable>numbered_within</replaceable> is reset). </para> -<para>Using the second form, -</para> -<screen>\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>} -</screen> -<para>with the optional argument between the two required -arguments, will create an environment whose counter will share the -previously defined counter <replaceable>numbered_like</replaceable>. + +<para>The third form +<literal>\newtheorem{<replaceable>name</replaceable>}[<replaceable>numbered_like</replaceable>]{<replaceable>title</replaceable>}</literal>, +with optional argument between the two required arguments, will create +an environment whose counter will share the previously defined counter +<replaceable>numbered_like</replaceable>. </para> <para>You can specify one of <replaceable>numbered_within</replaceable> and <replaceable>numbered_like</replaceable>, or neither, but not both. </para> <para>This command creates a counter named <replaceable>name</replaceable>. In addition, unless -the optional argument <replaceable>numbered_like</replaceable> is used, the current -<literal>\ref</literal> value will be that of <literal>\the<replaceable>numbered_within</replaceable></literal> -(see <link linkend="_005cref">\ref</link>). +the optional argument <replaceable>numbered_like</replaceable> is used, inside of the +theorem-like environment the current <literal>\ref</literal> value will be that of +<literal>\the<replaceable>numbered_within</replaceable></literal> (see <link linkend="_005cref">\ref</link>). </para> <para>This declaration is global. It is fragile (see <link linkend="_005cprotect">\protect</link>). </para> @@ -4848,8 +5571,9 @@ new environment will be numbered in sequence with <replaceable>numbered_like</re </para> </listitem></varlistentry></variablelist> <para>Without any optional arguments the environments are numbered -sequentially. This example has a declaration in the preamble that -results in ‘<literal>Definition 1</literal>’ and ‘<literal>Definition 2</literal>’ in the output. +sequentially. The example below has a declaration in the preamble that +results in ‘<literal>Definition 1</literal>’ and ‘<literal>Definition 2</literal>’ in the +output. </para> <screen>\newtheorem{defn}{Definition} \begin{document} @@ -4863,7 +5587,7 @@ results in ‘<literal>Definition 1</literal>’ and ‘<litera Second def \end{defn} </screen> -<para>Because this example specifies the optional argument +<para>Because the next example specifies the optional argument <replaceable>numbered_within</replaceable> to <literal>\newtheorem</literal> as <literal>section</literal>, the example, with the same document body, gives ‘<literal>Definition 1.1</literal>’ and ‘<literal>Definition 2.1</literal>’. @@ -4880,8 +5604,8 @@ and ‘<literal>Definition 2.1</literal>’. Second def \end{defn} </screen> -<para>In this example there are two declarations in the preamble, the second -of which calls for the new <literal>thm</literal> environment to use the same +<para>In the next example there are two declarations in the preamble, the +second of which calls for the new <literal>thm</literal> environment to use the same counter as <literal>defn</literal>. It gives ‘<literal>Definition 1.1</literal>’, followed by ‘<literal>Theorem 2.1</literal>’ and ‘<literal>Definition 2.2</literal>’. </para> @@ -4944,7 +5668,7 @@ size, which is a value defined in the <filename>.tfm</filename> file. characters in each: </para> <screen>\newfont{\testfontat}{cmb10 at 11pt} -\newfont{\testfontscaled}{cmb10 scaled 11pt} +\newfont{\testfontscaled}{cmb10 scaled 1100} \testfontat abc \testfontscaled abc </screen> @@ -4956,23 +5680,25 @@ characters in each: <indexterm role="fn"><primary>\protect</primary></indexterm> <indexterm role="cp"><primary>fragile commands</primary></indexterm> <indexterm role="cp"><primary>robust commands</primary></indexterm> -<indexterm role="cp"><primary>moving arguments</primary></indexterm> <para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. Footnotes, line breaks, any command that has an optional argument, and many more, are fragile. A fragile command can break when it is used in the argument to certain commands. To prevent such commands from -breaking they must be preceded by the command <literal>\protect</literal>. +breaking one solution is to have them preceded by the command +<literal>\protect</literal>. </para> <para>For example, when &latex; runs the <literal>\section{<replaceable>section name</replaceable>}</literal> command it writes the <replaceable>section name</replaceable> text to the <filename>.aux</filename> auxiliary file, moving it there for use elsewhere in the document such as in the table of contents. Any argument that is internally expanded by &latex; without typesetting it directly is -referred to as a <firstterm>moving argument</firstterm>. A command is fragile if it can +referred to as a +<indexterm role="cp"><primary>moving arguments</primary></indexterm> +<firstterm>moving argument</firstterm>. A command is fragile if it can expand during this process into invalid &tex; code. Some examples of -moving arguments are those that appear in the <literal>\caption{..}</literal> -command (see <link linkend="figure">figure</link>), in the <literal>\thanks{..}</literal> command +moving arguments are those that appear in the <literal>\caption{...}</literal> +command (see <link linkend="figure">figure</link>), in the <literal>\thanks{...}</literal> command (see <link linkend="_005cmaketitle">\maketitle</link>), and in @-expressions in the <literal>tabular</literal> and <literal>array</literal> environments (see <link linkend="tabular">tabular</link>). </para> @@ -4985,12 +5711,12 @@ commands are robust and should not be preceded by a <literal>\protect</literal> command. Nor can a <literal>\protect</literal> command be used in the argument to <literal>\addtocounter</literal> or <literal>\setcounter</literal> command. </para> -<para>In this example the <literal>caption</literal> command gives a mysterious error +<para>In this example the <literal>\caption</literal> command gives a mysterious error about an extra curly brace. Fix the problem by preceding each <literal>\raisebox</literal> command with <literal>\protect</literal>. </para> <screen>\begin{figure} - .. + ... \caption{Company headquarters of A\raisebox{1pt}{B}\raisebox{-1pt}{C}} \end{figure} </screen> @@ -5001,9 +5727,9 @@ to <literal>\protect\(..\protect\)</literal>. </para> <screen>\begin{document} \tableofcontents - .. +... \section{Einstein's \( e=mc^2 \)} - .. +... </screen> </sect1> @@ -5016,11 +5742,13 @@ to <literal>\protect\(..\protect\)</literal>. <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 with no -backslash (<literal>\</literal>). Thus the <literal>\chapter</literal> command starts a -chapter and the <literal>chapter</literal> counter keeps track of the chapter -number. Below is a list of the counters used in &latex;’s standard -document classes to control numbering. +environment or command associated with the number, except that the +counter’s name has no backslash <literal>\</literal>. Thus, associated with +the <literal>\chapter</literal> command is the <literal>chapter</literal> counter that keeps +track of the chapter number. +</para> +<para>Below is a list of the counters used in &latex;’s standard document +classes to control numbering. </para> <screen>part paragraph figure enumi chapter subparagraph table enumii @@ -5029,11 +5757,9 @@ subsection equation mpfootnote enumiv subsubsection </screen> <para>The <literal>mpfootnote</literal> counter is used by the <literal>\footnote</literal> command -inside of a minipage (see <link linkend="minipage">minipage</link>). -</para> -<para>The <literal>enumi</literal> through <literal>enumiv</literal> counters are used in the -<literal>enumerate</literal> environment, for up to four nested levels -(see <link linkend="enumerate">enumerate</link>). +inside of a minipage (see <link linkend="minipage">minipage</link>). The counters <literal>enumi</literal> +through <literal>enumiv</literal> are used in the <literal>enumerate</literal> environment, for +up to four levels of nesting (see <link linkend="enumerate">enumerate</link>). </para> <para>New counters are created with <literal>\newcounter</literal>. See <link linkend="_005cnewcounter">\newcounter</link>. </para> @@ -5045,36 +5771,48 @@ inside of a minipage (see <link linkend="minipage">minipage</link>). <indexterm role="cp"><primary>counters, printing</primary></indexterm> +<para>Print the value of a counter, in a specified style. For instance, if +the counter <replaceable>counter</replaceable> has the value 1 then a +<literal>\alph{<replaceable>counter</replaceable>}</literal> in your source will result in a lower case +letter a appearing in the output. +</para> <para>All of these commands take a single counter as an argument, for instance, <literal>\alph{enumi}</literal>. Note that the counter name does not start with a backslash. </para> -<variablelist><varlistentry><term><indexterm role="fn"><primary>\alph</primary></indexterm><literal>\alph</literal> -</term><listitem><para>prints <replaceable>counter</replaceable> using lowercase letters: ‘a’, ‘b’, ... +<variablelist><varlistentry><term><indexterm role="fn"><primary>\alph{<replaceable>counter</replaceable>}</primary></indexterm><literal>\alph{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print the value of <replaceable>counter</replaceable> in lowercase letters: ‘a’, ‘b’, ... </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Alph</primary></indexterm><literal>\Alph</literal> -</term><listitem><para>uses uppercase letters: ‘A’, ‘B’, ... +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Alph{<replaceable>counter</replaceable>}</primary></indexterm><literal>\Alph{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in uppercase letters: ‘A’, ‘B’, ... </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arabic</primary></indexterm><literal>\arabic</literal> -</term><listitem><para>uses Arabic numbers: ‘1’, ‘2’, ... +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\arabic{<replaceable>counter</replaceable>}</primary></indexterm><literal>\arabic{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in Arabic numbers: ‘1’, ‘2’, ... </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\roman</primary></indexterm><literal>\roman</literal> -</term><listitem><para>uses lowercase roman numerals: ‘i’, ‘ii’, ... +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\roman{<replaceable>counter</replaceable>}</primary></indexterm><literal>\roman{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in lowercase roman numerals: ‘i’, ‘ii’, ... </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Roman</primary></indexterm><literal>\Roman</literal> -</term><listitem><para>uses uppercase roman numerals: ‘I’, ‘II’, ... +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Roman{<replaceable>counter</replaceable>}</primary></indexterm><literal>\Roman{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Print in uppercase roman numerals: ‘I’, ‘II’, ... </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\fnsymbol</primary></indexterm><literal>\fnsymbol</literal> -</term><listitem><para>prints the value of <replaceable>counter</replaceable> in a specific sequence of nine +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\fnsymbol{<replaceable>counter</replaceable>}</primary></indexterm><literal>\fnsymbol{<replaceable>counter</replaceable>}</literal> +</term><listitem><para>Prints the value of <replaceable>counter</replaceable> in a specific sequence of nine symbols (conventionally used for labeling footnotes). The value of <replaceable>counter</replaceable> must be between 1 and 9, inclusive. </para> -<para>Here are the symbols (as Unicode code points in ASCII output): -</para> -<literallayout>asterisk(*) dagger(‡) ddagger(‡) -section-sign(§) paragraph-sign(¶) parallel(∥) -double-asterisk(**) double-dagger(††) double-ddagger(‡‡) -</literallayout> +<para>Here are the symbols: +</para> +<informaltable><tgroup cols="3"><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><thead><row><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Equivalent Unicode symbol and/or numeric code point<!-- --> +</para></entry></row></thead><tbody><row><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!-- --> +</para></entry></row><row><entry><para>dagger</para></entry><entry><para><literal>\dagger</literal></para></entry><entry><para>† +</para></entry></row><row><entry><para>ddagger</para></entry><entry><para><literal>\ddagger</literal></para></entry><entry><para>‡ +</para></entry></row><row><entry><para>section-sign</para></entry><entry><para><literal>\S</literal></para></entry><entry><para>§ +</para></entry></row><row><entry><para>paragraph-sign</para></entry><entry><para><literal>\P</literal></para></entry><entry><para>¶ +</para></entry></row><row><entry><para>double-vert</para></entry><entry><para><literal>\parallel</literal></para></entry><entry><para>‖ +</para></entry></row><row><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!-- --> +</para></entry></row><row><entry><para>double-dagger</para></entry><entry><para><literal>\dagger\dagger</literal></para></entry><entry><para>†† +</para></entry></row><row><entry><para>double-ddagger</para></entry><entry><para><literal>\ddagger\ddagger</literal></para></entry><entry><para>‡‡ +</para></entry></row></tbody></tgroup></informaltable> </listitem></varlistentry></variablelist> </sect1> @@ -5160,6 +5898,11 @@ Other counter is \arabic{other}. to the <replaceable>value</replaceable> argument. Note that the counter name does not start with a backslash. </para> +<para>In this example the section value appears as ‘<literal>V</literal>’. +</para> +<screen>\setcounter{section}{5} +Here it is in Roman: \Roman{section}. +</screen> </sect1> <sect1 label="13.5" id="_005caddtocounter"> @@ -5170,6 +5913,12 @@ with a backslash. <para>The <literal>\addtocounter</literal> command globally increments <replaceable>counter</replaceable> by the amount specified by the <replaceable>value</replaceable> argument, which may be negative. </para> +<para>In this example the section value appears as ‘<literal>VII</literal>’. +</para> +<screen>\setcounter{section}{5} +\addtocounter{section}{2} +Here it is in Roman: \Roman{section}. +</screen> </sect1> <sect1 label="13.6" id="_005crefstepcounter"> @@ -5338,27 +6087,37 @@ math symbols family. See <link linkend="Spacing-in-math-mode">Spacing in math m </sect1> <sect1 label="14.2" id="_005csetlength"> -<title><literal>\setlength{\<replaceable>len</replaceable>}{<replaceable>value</replaceable>}</literal></title> +<title><literal>\setlength</literal></title> <indexterm role="fn"><primary>\setlength</primary></indexterm> <indexterm role="cp"><primary>lengths, setting</primary></indexterm> -<para>The <literal>\setlength</literal> sets the value of <replaceable>\len</replaceable> to the <replaceable>value</replaceable> -argument, which can be expressed in any units that &latex; -understands, i.e., inches (<literal>in</literal>), millimeters (<literal>mm</literal>), points -(<literal>pt</literal>), big points (<literal>bp</literal>, etc. +<para>Synopsis: +</para> +<screen>\setlength{<replaceable>\len</replaceable>}{<replaceable>amount</replaceable>} +</screen> +<para>The <literal>\setlength</literal> sets the value of <firstterm>length command</firstterm> +<indexterm role="cp"><primary>length command</primary></indexterm> +<literal>\<replaceable>len</replaceable></literal> to the <replaceable>value</replaceable> argument which can be expressed in any +units that &latex; understands, i.e., inches (<literal>in</literal>), millimeters +(<literal>mm</literal>), points (<literal>pt</literal>), big points (<literal>bp</literal>), etc. </para> </sect1> <sect1 label="14.3" id="_005caddtolength"> -<title><literal>\addtolength{<replaceable>\len</replaceable>}{<replaceable>amount</replaceable>}</literal></title> +<title><literal>\addtolength</literal></title> <indexterm role="fn"><primary>\addtolength</primary></indexterm> <indexterm role="cp"><primary>lengths, adding to</primary></indexterm> -<para>The <literal>\addtolength</literal> command increments a “length command” -<replaceable>\len</replaceable> by the amount specified in the <replaceable>amount</replaceable> argument, which -may be negative. +<para>Synopsis: +</para> +<screen>\addtolength{<replaceable>\len</replaceable>}{<replaceable>amount</replaceable>} +</screen> + +<para>The <literal>\addtolength</literal> command increments a length command <literal>\<replaceable>len</replaceable></literal> +by the amount specified in the <replaceable>amount</replaceable> argument, which may be +negative. </para> </sect1> @@ -5367,10 +6126,12 @@ may be negative. <indexterm role="fn"><primary>\settodepth</primary></indexterm> -<para><literal>\settodepth{\gnat}{text}</literal> +<para>Synopsis: </para> -<para>The <literal>\settodepth</literal> command sets the value of a <literal>length</literal> command -equal to the depth of the <literal>text</literal> argument. +<screen>\settodepth{\<replaceable>len</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>The <literal>\settodepth</literal> command sets the value of a length command +<literal>\<replaceable>len</replaceable></literal> equal to the depth of the <replaceable>text</replaceable> argument. </para> </sect1> @@ -5379,9 +6140,11 @@ equal to the depth of the <literal>text</literal> argument. <indexterm role="fn"><primary>\settoheight</primary></indexterm> -<para><literal>\settoheight{\gnat}{text}</literal> +<para>Synopsis: </para> -<para>The <literal>\settoheight</literal> command sets the value of a <literal>length</literal> command +<screen>\settoheight{\<replaceable>len</replaceable>}{text} +</screen> +<para>The <literal>\settoheight</literal> command sets the value of a length command <literal>\<replaceable>len</replaceable></literal> equal to the height of the <literal>text</literal> argument. </para> @@ -5392,6 +6155,10 @@ equal to the height of the <literal>text</literal> argument. <indexterm role="fn"><primary>\settowidth</primary></indexterm> +<para>Synopsis: +</para> +<screen>\settowidth{\<replaceable>len</replaceable>}{<replaceable>text</replaceable>} +</screen> <para>The <literal>\settowidth</literal> command sets the value of the command <replaceable>\len</replaceable> to the width of the <replaceable>text</replaceable> argument. </para> @@ -5417,12 +6184,12 @@ to the width of the <replaceable>text</replaceable> argument. </para> <para>These length parameters can be used in the arguments of the box-making commands (see <link linkend="Boxes">Boxes</link>). They specify the natural width, etc., of -the text in the box. <literal>\totalheight</literal> equals <literal>\height</literal> + -<literal>\depth</literal>. To make a box with the text stretched to double the +the text in the box. <literal>\totalheight</literal> equals <inlineequation><mathphrase><literal>\height</literal> + +<literal>\depth</literal></mathphrase></inlineequation>. To make a box with the text stretched to double the natural size, e.g., say </para> -<para><literal>\makebox[2\width]{Get a stretcher}</literal> -</para> +<screen>\makebox[2\width]{Get a stretcher} +</screen> </sect1> </chapter> @@ -5465,7 +6232,7 @@ mode, otherwise <literal>15pt</literal> for <literal>10pt</literal> documents, < <para>When used at the beginning of the paragraph, this command suppresses any paragraph indentation, as in this example. </para> -<screen>.. end of the prior paragraph. +<screen>... end of the prior paragraph. \noindent This paragraph is not indented. </screen> @@ -5554,9 +6321,12 @@ notes from falling off the bottom of the page. <indexterm role="cp"><primary>math formulas</primary></indexterm> <indexterm role="cp"><primary>formulas, math</primary></indexterm> <indexterm role="cp"><primary>math mode, entering</primary></indexterm> -<indexterm role="fn"><primary>math environment</primary></indexterm> -<indexterm role="fn"><primary>displaymath environment</primary></indexterm> -<indexterm role="fn"><primary>equation environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> +<indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> +<indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> <para>There are three environments that put &latex; in math mode: </para> @@ -5615,7 +6385,7 @@ below summations. For example: <indexterm role="fn"><primary>^</primary></indexterm> <para>In math mode, use the caret character <literal>^</literal> to make the -<replaceable>exp</replaceable> appear as a superscript, ie. type <literal>^{<replaceable>exp</replaceable>}</literal>. +<replaceable>exp</replaceable> appear as a superscript: <literal>^{<replaceable>exp</replaceable>}</literal>. Similarly, in math mode, underscore <literal>_{<replaceable>exp</replaceable>}</literal> makes a subscript out of <replaceable>exp</replaceable>. </para> @@ -5663,9 +6433,13 @@ the pi symbol π. <para>Below is a list of commonly-available symbols. It is by no means an exhaustive list. Each symbol here is described with a short phrase, and its symbol class (which determines the spacing around it) is given in -parenthesis. The commands for these symbols can be used only in math -mode. +parenthesis. Unless said otherwise, the commands for these symbols can +be used only in math mode. </para> +<para>To redefine a command so that it can be used whatever the current mode, +see <link linkend="_005censuremath">\ensuremath</link>. +</para> + <!-- xx Add Negation: @code{} for negations of relevant symbols --> <!-- Useful: http://www.w3.org/TR/WD-math-970515/section6.html --> @@ -5696,7 +6470,7 @@ five-pointed, and is sometimes used as a general binary operation, and sometimes reserved for cross-correlation. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\asymp</primary></indexterm><literal>\asymp</literal> -</term><listitem><para>≍ Asymptomatically equivalent (relation). +</term><listitem><para>≍ Asymptotically equivalent (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\backslash</primary></indexterm><literal>\backslash</literal> </term><listitem><para>\ Backslash (ordinary). Similar: set minus <literal>\setminus</literal>, and @@ -5748,16 +6522,15 @@ union <literal>\cup</literal>. </term><listitem><para>⋀ Variable-sized, or n-ary, logical-or (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bot</primary></indexterm><literal>\bot</literal> -</term><listitem><para>⊥ Up tack, bottom, least element of a poset, or a contradiction -(ordinary). See also <literal>\top</literal>. +</term><listitem><para>⊥ Up tack, bottom, least element of a partially ordered +set, or a contradiction (ordinary). See also <literal>\top</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bowtie</primary></indexterm><literal>\bowtie</literal> </term><listitem><para>⋈ Natural join of two relations (relation). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Box</primary></indexterm><literal>\Box</literal> -</term><listitem><para>□ Modal operator for necessity; square open box (ordinary). This -is not available in Plain &tex;. In &latex; you need to load the -<filename>amssymb</filename> package. +</term><listitem><para>□ Modal operator for necessity; square open box +(ordinary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. <!-- bb Best Unicode equivalent? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\bullet</primary></indexterm><literal>\bullet</literal> @@ -5785,8 +6558,7 @@ variable-sized operator <literal>\bigcirc</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\complement</primary></indexterm><literal>\complement</literal> </term><listitem><para>∁ Set complement, used as a superscript as in -<literal>$S^\complement$</literal> (ordinary). This is not available in Plain -&tex;. In &latex; you should load the <filename>amssymb</filename> package. Also +<literal>$S^\complement$</literal> (ordinary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. Also used: <literal>$S^{\mathsf{c}}$</literal> or <literal>$\bar{S}$</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cong</primary></indexterm><literal>\cong</literal> @@ -5816,8 +6588,7 @@ turnstile <literal>\vdash</literal>. </term><listitem><para>δ Greek lower case delta (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Diamond</primary></indexterm><literal>\Diamond</literal> -</term><listitem><para>◇ Large diamond operator (ordinary). This is not available in -Plain &tex;. In &latex; you must load the <filename>amssymb</filename> package. +</term><listitem><para>◇ Large diamond operator (ordinary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. <!-- bb Best Unicode equivalent? --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\diamond</primary></indexterm><literal>\diamond</literal> @@ -5846,15 +6617,15 @@ arrow <literal>\downarrow</literal>. </term><listitem><para>ℓ Lower-case cursive letter l (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\emptyset</primary></indexterm><literal>\emptyset</literal> -</term><listitem><para>∅ Empty set symbol (ordinary). Similar: reversed empty -set <literal>\varnothing</literal>. +</term><listitem><para>∅ Empty set symbol (ordinary). The variant form is +<literal>\varnothing</literal>. <!-- bb Why Unicode has \revemptyset but no \emptyset? --> -</para> +</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\epsilon</primary></indexterm><literal>\epsilon</literal> -</term><listitem><para>ϵ Lower case Greek-text letter (ordinary). More widely used in -mathematics is the curly epsilon -<literal>\varepsilon</literal> ε. Related: the set membership relation -<literal>\in</literal> ∈. +</term><listitem><para>ϵ Lower case lunate epsilon (ordinary). Similar to +Greek text letter. More widely used in mathematics is the script small +letter epsilon <literal>\varepsilon</literal> ε. Related: +the set membership relation <literal>\in</literal> ∈. <!-- src: David Carlisle http://tex.stackexchange.com/a/98018/339 and --> <!-- Unicode referenced there asserts varepsilon is much more widely used. --> </para> @@ -5918,8 +6689,8 @@ with a <literal>\thickmuskip</literal> on either side. </term><listitem><para>ℑ Imaginary part (ordinary). See: real part <literal>\Re</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\in</primary></indexterm><literal>\in</literal> -</term><listitem><para>∈ Set element (relation). See also: lower case Greek letter -epsilon <literal>\epsilon</literal>ϵ and rounded small +</term><listitem><para>∈ Set element (relation). See also: lower case lunate +epsilon <literal>\epsilon</literal>ϵ and small letter script epsilon <literal>\varepsilon</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\infty</primary></indexterm><literal>\infty</literal> @@ -5969,8 +6740,7 @@ shaved off (opening). Matches <literal>\rceil</literal>. for <literal>\leq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leadsto</primary></indexterm><literal>\leadsto</literal> -</term><listitem><para>⇝ Squiggly right arrow (relation). This is not available in -Plain &tex;. In &latex; you should load the <filename>amssymb</filename> package. +</term><listitem><para>⇝ Squiggly right arrow (relation). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. To get this symbol outside of math mode you can put <literal>\newcommand*{\Leadsto}{\ensuremath{\leadsto}}</literal> in the preamble and then use <literal>\Leadsto</literal> instead. @@ -6004,12 +6774,11 @@ double-line double headed arrow <literal>\Leftrightarrow</literal>. for <literal>\le</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lfloor</primary></indexterm><literal>\lfloor</literal> -</term><listitem><para>⌊ Left floor bracket (opening). +</term><listitem><para>⌊ Left floor bracket (opening). Matches: <literal>\floor</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\lhd</primary></indexterm><literal>\lhd</literal> -</term><listitem><para>◁ Arrowhead, that is, triangle, pointing left (binary). This is -not available in Plain &tex;. In &latex; you should load the -<filename>amssymb</filename> package. For the normal subgroup symbol you should load +</term><listitem><para>◁ Arrowhead, that is, triangle, pointing left (binary). +Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the normal subgroup symbol you should load <filename>amssymb</filename> and use <literal>\vartriangleleft</literal> (which is a relation and so gives better spacing). </para> @@ -6045,8 +6814,7 @@ Similar: longer version <literal>\longmapsto</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mho</primary></indexterm><literal>\mho</literal> </term><listitem><para>℧ Conductance, half-circle rotated capital omega (ordinary). -This is not available in Plain &tex;. In &latex; you should load the -<filename>amssymb</filename> package. +Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mid</primary></indexterm><literal>\mid</literal> </term><listitem><para>∣ Single-line vertical bar (relation). A typical use of @@ -6170,21 +6938,21 @@ ordinary. </term><listitem><para>± Plus or minus (binary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prec</primary></indexterm><literal>\prec</literal> -</term><listitem><para>≺ Preceeds (relation). Similar: less than <literal><</literal>. +</term><listitem><para>≺ Precedes (relation). Similar: less than <literal><</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\preceq</primary></indexterm><literal>\preceq</literal> -</term><listitem><para>⪯ Preceeds or equals (relation). Similar: less than or +</term><listitem><para>⪯ Precedes or equals (relation). Similar: less than or equals <literal>\leq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prime</primary></indexterm><literal>\prime</literal> -</term><listitem><para>′ Prime, or minute in a time expression (ordinary). Typically -used as a superscript <literal>$A^\prime$</literal>. Note that <literal>$f^\prime$</literal> -and <literal>$f'$</literal> produce the same result. An advantage of the second is -that <literal>$f'''$</literal> produces the the desired symbol, that is, the same -result as <literal>$f^{\prime\prime\prime}$</literal>, but uses somewhat less -typing. Note that you can only use <literal>\prime</literal> in math mode but you -can type right single quote <literal>'</literal> in text mode also, although it -resuts in a different look than in math mode. +</term><listitem><para>′ Prime, or minute in a time expression (ordinary). +Typically used as a superscript: <literal>$f^\prime$</literal>; <literal>$f^\prime$</literal> +and <literal>$f'$</literal> produce the same result. An advantage of the second +is that <literal>$f'''$</literal> produces the desired symbol, that is, the same +result as <literal>$f^{\prime\prime\prime}$</literal>, but uses rather less +typing. You can only use <literal>\prime</literal> in math mode. Using the right +single quote <literal>'</literal> in text mode produces a different character +(apostrophe). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\prod</primary></indexterm><literal>\prod</literal> </term><listitem><para>∏ Product (operator). @@ -6199,7 +6967,7 @@ resuts in a different look than in math mode. </term><listitem><para>ψ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rangle</primary></indexterm><literal>\rangle</literal> -</term><listitem><para>➹ Right angle, or sequence, bracket (closing). Similar: greater +</term><listitem><para>⟩ Right angle, or sequence, bracket (closing). Similar: greater than <literal>></literal>. Matches:<literal>\langle</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rbrace</primary></indexterm><literal>\rbrace</literal> @@ -6220,18 +6988,20 @@ this, load the <filename>amsfonts</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\restriction</primary></indexterm><literal>\restriction</literal> </term><listitem><para>↾ Restriction of a function -(relation). Synonym: <literal>\upharpoonright</literal>. Not available in -Plain &tex;. In &latex; you should load the <filename>amssymb</filename> package. +(relation). Synonym: <literal>\upharpoonright</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\revemptyset</primary></indexterm><literal>\revemptyset</literal> +</term><listitem><para>⦰ Reversed empty set symbol (ordinary). Related: +<literal>\varnothing</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>stix</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rfloor</primary></indexterm><literal>\rfloor</literal> </term><listitem><para>⌋ Right floor bracket, a right square bracket with the top cut off (closing). Matches <literal>\lfloor</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rhd</primary></indexterm><literal>\rhd</literal> -</term><listitem><para>◁ Arrowhead, that is, triangle, pointing right (binary). This is -not available in Plain &tex;. In &latex; you should load the -<filename>amssymb</filename> package. For the normal subgroup symbol you should -instead load <filename>amssymb</filename> and use <literal>\vartriangleright</literal> (which +</term><listitem><para>◁ Arrowhead, that is, triangle, pointing right (binary). +Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For the normal subgroup symbol you should instead +load <filename>amssymb</filename> and use <literal>\vartriangleright</literal> (which is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rho</primary></indexterm><literal>\rho</literal> @@ -6283,7 +7053,7 @@ right single-line arrow <literal>\rightarrow</literal>. display (operator). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\smile</primary></indexterm><literal>\smile</literal> -</term><listitem><para>⌣ Upward curving arc (ordinary). +</term><listitem><para>⌣ Upward curving arc, smile (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\spadesuit</primary></indexterm><literal>\spadesuit</literal> </term><listitem><para>♠ Spade card suit (ordinary). @@ -6299,8 +7069,7 @@ operator <literal>\bigsqcup</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubset</primary></indexterm><literal>\sqsubset</literal> </term><listitem><para>⊏ Square subset symbol (relation). Similar: -subset <literal>\subset</literal>. This is not available in Plain &tex;. In -&latex; you should load the <filename>amssymb</filename> package. +subset <literal>\subset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsubseteq</primary></indexterm><literal>\sqsubseteq</literal> </term><listitem><para>⊑ Square subset or equal symbol (binary). Similar: subset or @@ -6308,8 +7077,7 @@ equal to <literal>\subseteq</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupset</primary></indexterm><literal>\sqsupset</literal> </term><listitem><para>⊐ Square superset symbol (relation). Similar: -superset <literal>\supset</literal>. This is not available in Plain &tex;. In -&latex; you should load the <filename>amssymb</filename> package. +superset <literal>\supset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqsupseteq</primary></indexterm><literal>\sqsupseteq</literal> </term><listitem><para>⊒ Square superset or equal symbol (binary). Similar: superset or @@ -6348,7 +7116,7 @@ sigma <literal>\Sigma</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\surd</primary></indexterm><literal>\surd</literal> </term><listitem><para>√ Radical symbol (ordinary). The &latex; command -<literal>\sqrt{..}</literal> typesets the square root of the argument, with a bar +<literal>\sqrt{...}</literal> typesets the square root of the argument, with a bar that extends to cover the argument. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\swarrow</primary></indexterm><literal>\swarrow</literal> @@ -6370,8 +7138,8 @@ also <literal>\cdot</literal>. Synonym: <literal>\rightarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\top</primary></indexterm><literal>\top</literal> -</term><listitem><para>⊤ Top, greatest element of a poset (ordinary). See -also <literal>\bot</literal>. +</term><listitem><para>⊤ Top, greatest element of a partially ordered set +(ordinary). See also <literal>\bot</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangle</primary></indexterm><literal>\triangle</literal> </term><listitem><para>△ Triangle (ordinary). @@ -6383,36 +7151,39 @@ should load <filename>amssymb</filename> and use <literal>\vartriangleleft< is a relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\triangleright</primary></indexterm><literal>\triangleright</literal> -</term><listitem><para>▷ Not-filled triangle pointing right (binary). For the normal -subgroup symbol you should instead load <filename>amssymb</filename> and -use <literal>\vartriangleright</literal> (which is a relation and so gives -better spacing). +</term><listitem><para>▷ Not-filled triangle pointing right +(binary). For the normal subgroup symbol you should instead load +<filename>amssymb</filename> and use <literal>\vartriangleright</literal> (which is a +relation and so gives better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unlhd</primary></indexterm><literal>\unlhd</literal> -</term><listitem><para>⊴ Left-pointing not-filled arrowhead, that is, triangle, with a -line under (binary). This is not available in Plain &tex;. In &latex; -you should load the <filename>amssymb</filename> package. For the normal subgroup -symbol load <filename>amssymb</filename> and use <literal>\vartrianglelefteq</literal> (which -is a relation and so gives better spacing). +</term><listitem><para>⊴ Left-pointing not-filled underlined arrowhead, that +is, triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For +the normal subgroup symbol load <filename>amssymb</filename> and +use <literal>\vartrianglelefteq</literal> (which is a relation and so gives +better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\unrhd</primary></indexterm><literal>\unrhd</literal> -</term><listitem><para>⊵ Right-pointing not-filled arrowhead, that is, triangle, with a -line under (binary). This is not available in Plain &tex;. In &latex; -you should load the <filename>amssymb</filename> package. For the normal subgroup -symbol load <filename>amssymb</filename> and use <literal>\vartrianglerighteq</literal> -(which is a relation and so gives better spacing). +</term><listitem><para>⊵ Right-pointing not-filled underlined arrowhead, that +is, triangle, with a line under (binary). Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. For +the normal subgroup symbol load <filename>amssymb</filename> and +use <literal>\vartrianglerighteq</literal> (which is a relation and so gives +better spacing). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Uparrow</primary></indexterm><literal>\Uparrow</literal> -</term><listitem><para>⇑ Double-line upward-pointing arrow (relation). Similar: -single-line up-pointing arrow <literal>\uparrow</literal>. +</term><listitem><para>⇑ Double-line upward-pointing arrow +(relation). Similar: single-line up-pointing +arrow <literal>\uparrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\uparrow</primary></indexterm><literal>\uparrow</literal> -</term><listitem><para>↑ Single-line upward-pointing arrow, diverges (relation). Similar: -double-line up-pointing arrow <literal>\Uparrow</literal>. +</term><listitem><para>↑ Single-line upward-pointing arrow, diverges +(relation). Similar: double-line up-pointing +arrow <literal>\Uparrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Updownarrow</primary></indexterm><literal>\Updownarrow</literal> -</term><listitem><para>⇕ Double-line upward-and-downward-pointing arrow (relation). Similar: -single-line upward-and-downward-pointing arrow <literal>\updownarrow</literal>. +</term><listitem><para>⇕ Double-line upward-and-downward-pointing arrow +(relation). Similar: single-line upward-and-downward-pointing +arrow <literal>\updownarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\updownarrow</primary></indexterm><literal>\updownarrow</literal> </term><listitem><para>↕ Single-line upward-and-downward-pointing arrow (relation). Similar: @@ -6420,13 +7191,12 @@ double-line upward-and-downward-pointing arrow <literal>\Updownarrow</liter </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\upharpoonright</primary></indexterm><literal>\upharpoonright</literal> </term><listitem><para>↾ Up harpoon, with barb on right side -(relation). Synonym: <literal>\restriction</literal>. Not available in Plain -&tex;. In &latex; you should load the <filename>amssymb</filename> package. +(relation). Synonym: <literal>\restriction</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\uplus</primary></indexterm><literal>\uplus</literal> -</term><listitem><para>⊎ Multiset union, a union symbol with a plus symbol in the middle -(binary). Similar: union <literal>\cup</literal>. Related: variable-sized -operator <literal>\biguplus</literal>. +</term><listitem><para>⊎ Multiset union, a union symbol with a plus symbol in +the middle (binary). Similar: union <literal>\cup</literal>. Related: +variable-sized operator <literal>\biguplus</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Upsilon</primary></indexterm><literal>\Upsilon</literal> </term><listitem><para>Υ Upper case Greek letter (ordinary). @@ -6435,53 +7205,62 @@ operator <literal>\biguplus</literal>. </term><listitem><para>υ Lower case Greek letter (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varepsilon</primary></indexterm><literal>\varepsilon</literal> -</term><listitem><para>ε Rounded small epsilon (ordinary). This is more widely used in -mathematics than the non-variant lower case Greek-text letter form -<literal>\epsilon</literal> ϵ. Related: set membership <literal>\in</literal>. +</term><listitem><para>ε Small letter script epsilon (ordinary). This is +more widely used in mathematics than the non-variant lunate epsilon form +<literal>\epsilon</literal> ϵ. Related: set +membership <literal>\in</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vanothing</primary></indexterm><literal>\vanothing</literal> +</term><listitem><para>∅ Empty set symbol. Similar: +<literal>\emptyset</literal>. Related: <literal>\revemptyset</literal>. Not available in plain &tex;. In &latex; you need to load the <filename>amssymb</filename> package. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varphi</primary></indexterm><literal>\varphi</literal> -</term><listitem><para>φ Variant on the lower case Greek letter (ordinary). The -non-variant form is <literal>\phi</literal> ϕ. +</term><listitem><para>φ Variant on the lower case Greek letter (ordinary). +The non-variant form is <literal>\phi</literal> ϕ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varpi</primary></indexterm><literal>\varpi</literal> -</term><listitem><para>ϖ Variant on the lower case Greek letter (ordinary). The -non-variant form is <literal>\pi</literal> π. +</term><listitem><para>ϖ Variant on the lower case Greek letter (ordinary). +The non-variant form is <literal>\pi</literal> π. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varrho</primary></indexterm><literal>\varrho</literal> -</term><listitem><para>ϱ Variant on the lower case Greek letter (ordinary). The -non-variant form is <literal>\rho</literal> ρ. +</term><listitem><para>ϱ Variant on the lower case Greek letter (ordinary). +The non-variant form is <literal>\rho</literal> ρ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\varsigma</primary></indexterm><literal>\varsigma</literal> -</term><listitem><para>ς Variant on the lower case Greek letter (ordinary). The -non-variant form is <literal>\sigma</literal> σ. +</term><listitem><para>ς Variant on the lower case Greek letter +(ordinary). The non-variant form is +<literal>\sigma</literal> σ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vartheta</primary></indexterm><literal>\vartheta</literal> -</term><listitem><para>ϑ Variant on the lower case Greek letter (ordinary). The -non-variant form is <literal>\theta</literal> θ. +</term><listitem><para>ϑ Variant on the lower case Greek letter +(ordinary). The non-variant form is +<literal>\theta</literal> θ. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vdash</primary></indexterm><literal>\vdash</literal> -</term><listitem><para>⊢ Provable; turnstile, vertical and a dash (relation). Similar: -turnstile rotated a half-circle <literal>\dashv</literal>. +</term><listitem><para>⊢ Provable; turnstile, vertical and a dash +(relation). Similar: turnstile rotated a +half-circle <literal>\dashv</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vee</primary></indexterm><literal>\vee</literal> -</term><listitem><para>∨ Logical or; a downwards v shape (binary). Related: logical -and <literal>\wedge</literal>. Similar: variable-sized +</term><listitem><para>∨ Logical or; a downwards v shape (binary). Related: +logical and <literal>\wedge</literal>. Similar: variable-sized operator <literal>\bigvee</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\Vert</primary></indexterm><literal>\Vert</literal> </term><listitem><para>‖ Vertical double bar (ordinary). Similar: vertical single bar <literal>\vert</literal>. </para> -<para>For a norm you can use the <filename>mathtools</filename> package and add +<para>For a norm symbol, you can use the <filename>mathtools</filename> package and add <literal>\DeclarePairedDelimiter\norm{\lVert}{\rVert}</literal> to your -preamble. This gives you three command variants for double-line vertical -bars that are correctly horizontally spaced: if in the document body you -write the starred version <literal>$\norm*{M^\perp}$</literal> then the height of -the vertical bars will match the height of the argument, whereas with -<literal>\norm{M^\perp}</literal> the bars do not grow with the height of the -argument but instead are the default height, and <literal>\norm[<replaceable>size -command</replaceable>]{M^\perp}</literal> also gives bars that do not grow but are set to -the size given in the <replaceable>size command</replaceable>, e.g., <literal>\Bigg</literal>. +preamble. This gives you three command variants for double-line +vertical bars that are correctly horizontally spaced: if in the +document body you write the starred version <literal>$\norm*{M^\perp}$</literal> +then the height of the vertical bars will match the height of the +argument, whereas with <literal>\norm{M^\perp}</literal> the bars do not grow +with the height of the argument but instead are the default height, +and <literal>\norm[<replaceable>size command</replaceable>]{M^\perp}</literal> also gives bars that +do not grow but are set to the size given in the <replaceable>size command</replaceable>, +e.g., <literal>\Bigg</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vert</primary></indexterm><literal>\vert</literal> </term><listitem><para>| Single line vertical bar (ordinary). Similar: double-line @@ -6626,10 +7405,10 @@ spacing. </term><listitem><para><inlineequation><mathphrase>\sinh</mathphrase></inlineequation> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sup</primary></indexterm><literal>\sup</literal> -</term><listitem><para>sup -<!-- don't try to use \sup since that turned into a Texinfo command --> -<!-- and it's not worth hassling with different versions when it's --> -<!-- just three roman letters anyway. --> +</term><listitem><para><inlineequation><mathphrase>\sup</mathphrase></inlineequation> +<!-- don't try to use \sup with dvi/pdf output since that turned into a --> +<!-- Texinfo command and it's not worth hassling with different versions --> +<!-- when it's just three roman letters anyway. --> </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tan</primary></indexterm><literal>\tan</literal> </term><listitem><para><inlineequation><mathphrase>\tan</mathphrase></inlineequation> @@ -6750,7 +7529,7 @@ math symbols family (see <link linkend="Units-of-length">Units of length</link>) </term><listitem><indexterm role="fn"><primary>\,</primary></indexterm> <indexterm role="fn"><primary>\thinspace</primary></indexterm> <para>Normally <literal>3mu</literal>. The longer name is <literal>\thinspace</literal>. This can -be used in both math mode and text mode. +be used in both math mode and text mode. See <link linkend="_005cthinspace">\thinspace</link>. </para> </listitem></varlistentry><varlistentry><term><literal>\!</literal> </term><listitem><indexterm role="fn"><primary>\!</primary></indexterm> @@ -6784,8 +7563,29 @@ infinitesimal. <variablelist><varlistentry><term><indexterm role="fn"><primary>\*</primary></indexterm><literal>\*</literal> </term><listitem><indexterm role="cp"><primary>discretionary multiplication</primary></indexterm> <indexterm role="cp"><primary>multiplication symbol, discretionary line break</primary></indexterm> -<para>A “discretionary” multiplication symbol, at which a line break is -allowed. +<para>A <firstterm>discretionary</firstterm> multiplication symbol, at which a line break is +allowed. Without the break multiplication is implicitly indicated by a +space, while in the case of a break a × symbol is +printed immediately before the break. So +</para> +<screen>\documentclass{article} +\begin{document} +Now \(A_3 = 0\), hence the product of all terms \(A_1\) +through \(A_4\), that is \(A_1\* A_2\* A_3 \* A_4\), is +equal to zero. +\end{document} +</screen> +<para>will make that sort of output<!-- --> + <!-- /@w -->(the ellipsis ‘<literal>[…]</literal>’ is here to show the line break at +the same place as in a &tex; output)<!-- --> +: +</para> +<para>Now <inlineequation><mathphrase>A_3 = 0</mathphrase></inlineequation>, +[…] +<inlineequation><mathphrase>A_1</mathphrase></inlineequation> +through <inlineequation><mathphrase>A_4</mathphrase></inlineequation>, that is <inlineequation><mathphrase>A_1 A_2 \times</mathphrase></inlineequation> +<inlineequation><mathphrase>A_3 A_4</mathphrase></inlineequation>, is +equal to zero. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\cdots</primary></indexterm><literal>\cdots</literal> </term><listitem><para>A horizontal ellipsis with the dots raised to the center of the line. @@ -6793,47 +7593,64 @@ allowed. </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ddots</primary></indexterm><literal>\ddots</literal> </term><listitem><para>A diagonal ellipsis: <inlineequation><mathphrase>\ddots</mathphrase></inlineequation>. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\frac{num}{den}</primary></indexterm><literal>\frac{num}{den}</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\frac{<replaceable>num</replaceable>}{<replaceable>den</replaceable>}</primary></indexterm><literal>\frac{<replaceable>num</replaceable>}{<replaceable>den</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\frac</primary></indexterm> -<para>Produces the fraction <literal>num</literal> divided by <literal>den</literal>. +<para>Produces the fraction <replaceable>num</replaceable> divided by <replaceable>den</replaceable>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\left <replaceable>delim1</replaceable> ... \right <replaceable>delim2</replaceable></primary></indexterm><literal>\left <replaceable>delim1</replaceable> ... \right <replaceable>delim2</replaceable></literal> </term><listitem><indexterm role="fn"><primary>\right</primary></indexterm> <indexterm role="cp"><primary>null delimiter</primary></indexterm> -<para>The two delimiters need not match; ‘<literal>.</literal>’ acts as a null delimiter, +<para>The two delimiters need not match; ‘<literal>.</literal>’ acts as a <firstterm>null delimiter</firstterm>, producing no output. The delimiters are sized according to the math -in between. Example: <literal>\left( \sum_i=1^10 a_i \right]</literal>. +in between. Example: <literal>\left( \sum_{i=1}^{10} a_i \right]</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathdollar</primary></indexterm><literal>\mathdollar</literal> +</term><listitem><para>Dollar sign in math mode: $. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathellipsis</primary></indexterm><literal>\mathellipsis</literal> +</term><listitem><para>Ellipsis (spaced for text) in math mode: …. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathparagraph</primary></indexterm><literal>\mathparagraph</literal> +</term><listitem><para>Paragraph sign (pilcrow) in math mode: ¶. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathsection</primary></indexterm><literal>\mathsection</literal> +</term><listitem><para>Section sign in math mode. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathsterling</primary></indexterm><literal>\mathsterling</literal> +</term><listitem><para>Sterling sign in math mode: £. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overbrace{<replaceable>text</replaceable>}</primary></indexterm><literal>\overbrace{<replaceable>text</replaceable>}</literal> -</term><listitem><para>Generates a brace over <replaceable>text</replaceable>. -For example, <inlineequation><mathphrase>\overbrace{x+\cdots+x}^{k \rm\;times}</mathphrase></inlineequation>. +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\mathunderscore</primary></indexterm><literal>\mathunderscore</literal> +</term><listitem><para>Underscore in math mode: _. </para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\overbrace{<replaceable>math</replaceable>}</literal> +</term><listitem><para>Generates a brace over <replaceable>math</replaceable>. +For example, <literal>\overbrace{x+\cdots+x}^{k \;\textrm{times}}</literal>. +</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\overline{<replaceable>text</replaceable>}</primary></indexterm><literal>\overline{<replaceable>text</replaceable>}</literal> </term><listitem><para>Generates a horizontal line over <replaceable>tex</replaceable>. -For example, <inlineequation><mathphrase>\overline{x+y}</mathphrase></inlineequation>. +For example, <literal>\overline{x+y}</literal>. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqrt[<replaceable>root</replaceable>]{arg}</primary></indexterm><literal>\sqrt[<replaceable>root</replaceable>]{arg}</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\sqrt[<replaceable>root</replaceable>]{<replaceable>arg</replaceable>}</primary></indexterm><literal>\sqrt[<replaceable>root</replaceable>]{<replaceable>arg</replaceable>}</literal> </term><listitem><para>Produces the representation of the square root of <replaceable>arg</replaceable>. The optional argument <replaceable>root</replaceable> determines what root to produce. For example, the cube root of <literal>x+y</literal> would be typed as -<literal>$\sqrt[3]{x+y}$</literal>. +<literal>\sqrt[3]{x+y}</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\stackrel{<replaceable>text</replaceable>}{<replaceable>relation</replaceable>}</primary></indexterm><literal>\stackrel{<replaceable>text</replaceable>}{<replaceable>relation</replaceable>}</literal> </term><listitem><para>Puts <replaceable>text</replaceable> above <replaceable>relation</replaceable>. For example, <literal>\stackrel{f}{\longrightarrow}</literal>. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underbrace{math}</primary></indexterm><literal>\underbrace{math}</literal> -</term><listitem><para>Generates <replaceable>math</replaceable> with a brace underneath. +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underbrace{<replaceable>math</replaceable>}</primary></indexterm><literal>\underbrace{<replaceable>math</replaceable>}</literal> +</term><listitem><para>Generates <replaceable>math</replaceable> with a brace underneath. For example, <literal>\underbrace{x+y+z}_{>\,0}</literal> </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underline{text}</primary></indexterm><literal>\underline{text}</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\underline{<replaceable>text</replaceable>}</primary></indexterm><literal>\underline{<replaceable>text</replaceable>}</literal> </term><listitem><para>Causes <replaceable>text</replaceable>, which may be either math mode or not, to be underlined. The line is always below the text, taking account of descenders. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\vdots</primary></indexterm><literal>\vdots</literal> -</term><listitem><indexterm role="fn"><primary>\vdots</primary></indexterm> -<para>Produces a vertical ellipsis. +</term><listitem><para>Produces a vertical ellipsis. </para> </listitem></varlistentry></variablelist> @@ -6886,6 +7703,42 @@ be in “inner paragraph mode” (no page breaks). Its normal paragraph mode, which it starts out in, is called “outer paragraph mode”. </para> +<sect1 label="17.1" id="_005censuremath"> +<title><literal>\ensuremath</literal></title> + +<para>Synopsis: +</para> +<screen>\ensuremath{<replaceable>formula</replaceable>} +</screen> +<para>The <literal>\ensuremath</literal> command ensures that <replaceable>formula</replaceable> is typeset in +math mode whatever the current mode in which the command is used. +</para> +<para>For instance: +</para> +<screen>\documentclass{report} +\newcommand{\ab}{\ensuremath{(\delta, \varepsilon)}} +\begin{document} +Now, the \ab\ pair is equal to \(\ab = (\frac{1}{\pi}, 0)\), ... +\end{document} +</screen> +<para>One can redefine commands that can be used only in math mode so that +they ca be used in any mode like in the following example given for +<literal>\leadsto</literal>: +</para> +<!-- Vincent 2 Karl : "Tous les chemins mènent à Rome" is a French saying --> +<!-- meaning that there are many different ways to get the same result. I --> +<!-- am not sure whether in English the given example is also funny. --> +<screen>\documentclass{report} +\usepackage{amssymb} +\newcommand{\originalMeaningOfLeadsTo}{} +\let\originalMeaningOfLeadsTo\leadsto +\renewcommand\leadsto{\ensuremath{\originalMeaningOfLeadsTo}} +\begin{document} +All roads \leadsto\ Rome. +\end{document} +</screen> + +</sect1> </chapter> <chapter label="18" id="Page-styles"> <title>Page styles</title> @@ -7058,7 +7911,7 @@ space is like backspacing. <para>Normally when &tex; breaks a paragraph into lines it discards white space (glues and kerns) that would come at the start of a line, so you get an inter-word space or a line break between words but not both. This -command’s starred version <literal>\hspace*{..}</literal> puts a non-discardable +command’s starred version <literal>\hspace*{...}</literal> puts a non-discardable invisible item in front of the space, so the space appears in the output. </para> @@ -7106,7 +7959,7 @@ colon) more than the space between words sentence unless it is preceded by a capital letter, in which case it takes that period for part of an abbreviation. Note that if a sentence-ending period is immediately followed by a right parenthesis or -bracket, or right single or double quote, then the intersentence space +bracket, or right single or double quote, then the inter-sentence space follows that parenthesis or quote. </para> <para>If you have a period ending an abbreviation whose last letter is not a @@ -7115,60 +7968,44 @@ sentence, then follow that period with a backslash-space (<literal>\ </literal>) a tie (<literal>~</literal>). Examples are <literal>Nat.\ Acad.\ Science</literal>, and <literal>Mr.~Bean</literal>, and <literal>(manure, etc.)\ for sale</literal>. </para> -<para>For other use of <literal>\ </literal>, see also <link linkend="_005c_0028SPACE_0029-after-CS">\(SPACE) after CS</link>. +<para>For another use of <literal>\ </literal>, see <link linkend="_005c_0028SPACE_0029-after-control-sequence">\(SPACE) after control sequence</link>. </para> <para>In the opposite situation, if you have a capital letter followed by a -period that ends the sentence, then put <literal>\@</literal> on the left of that -period. For example, <literal>book by the MAA\@.</literal> will have intersentence +period that ends the sentence, then put <literal>\@</literal> before that period. +For example, <literal>book by the MAA\@.</literal> will have inter-sentence spacing after the period. </para> -<para>In contrast, putting <literal>\@</literal> on the right of a period tells &tex; -that the period does not end the sentence. In the example -<literal>reserved words (if, then, etc.\@) are different</literal>, &tex; will put -interword space after the closing parenthesis (note that <literal>\@</literal> is -before the parenthesis). +<para>In contrast, putting <literal>\@</literal> after a period tells &tex; that the +period does not end the sentence. In the example <literal>reserved words +(if, then, etc.\@) are different</literal>, &tex; will put interword space +after the closing parenthesis (note that <literal>\@</literal> is before the +parenthesis). </para> + </sect1> -<sect1 label="19.4" id="_005c_0028SPACE_0029-after-CS"> -<title><literal>\ </literal> after a control sequence</title> +<sect1 label="19.4" id="_005c_0028SPACE_0029-after-control-sequence"> +<title><literal>\ </literal> after control sequence</title> -<para>The <literal>\ </literal> command is often used after control sequences to keep them -from gobbling the space that follows, as in <literal>\TeX\ is a nice -system.</literal> And, under normal circumstances <literal>\</literal><keycap>tab</keycap> and -<literal>\</literal><keycap>newline</keycap> are equivalent to <literal>\ </literal>. For other use of +<para>The <literal>\ </literal> command is often used after control sequences to keep +them from gobbling the space that follows, as in ‘<literal>\TeX\ is nice</literal>’. +And, under normal circumstances, <literal>\</literal><keycap>tab</keycap> and +<literal>\</literal><keycap>newline</keycap> are equivalent to <literal>\ </literal>. For another use of <literal>\ </literal>, see also <link linkend="_005c_0028SPACE_0029-and-_005c_0040">\(SPACE) and \@</link>. </para> <para>Some people prefer to use <literal>{}</literal> for the same purpose, as in -<literal>\TeX{} is a nice system.</literal> This has the advantage that you can -always write it the same way, like <literal>\TeX{}</literal>, whether it is -followed by a space or by a punctuation mark. Please compare: +<literal>\TeX{} is nice</literal>. This has the advantage that you can always +write it the same way, namely <literal>\TeX{}</literal>, whether it is followed +by a space or by a punctuation mark. Compare: </para> <screen>\TeX\ is a nice system. \TeX, a nice system. \TeX{} is a nice system. \TeX{}, a nice system. </screen> - -<para>When you define user commands (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>) you -can prevent the space gobbling after the command by using the package -<literal>xspace</literal> and inserting <literal>\xspace</literal> at the end of the definition -For instance: -</para><screen>\documentclass{minimal} -\usepackage{xspace} -\newcommand*{\Loup}{Grand Cric\xspace} -\begin{document} -Que le \Loup me croque ! -\end{document} -</screen> -<para>A quick hack to use <literal>\xspace</literal> for existing command is as follows: -</para><screen>\documentclass{minimal} -\usepackage{xspace} -\newcommand*{\SansXspaceTeX}{} -\let\SansXspaceTeX\TeX -\renewcommand{\TeX}{\SansXspaceTeX\xspace} -\begin{document} -\TeX is a nice system. -\end{document} -</screen> +<indexterm role="cp"><primary>package, <literal>xspace</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>xspace</literal> package</primary></indexterm> +<para>Some individual commands, notably those defined with the <literal>xspace</literal>, +package do not follow the standard behavior. +</para> </sect1> <sect1 label="19.5" id="_005cfrenchspacing"> @@ -7176,10 +8013,10 @@ Que le \Loup me croque ! <indexterm role="fn"><primary>\frenchspacing</primary></indexterm> <indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm> -<indexterm role="cp"><primary>spacing, intersentence</primary></indexterm> +<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> <para>This declaration (from Plain &tex;) causes &latex; to treat -intersentence spacing in the same way as interword spacing. +inter-sentence spacing in the same way as interword spacing. </para> <para>In justifying the text in a line, some typographic traditions, including English, prefer to adjust the space between sentences (or after other @@ -7279,10 +8116,10 @@ then this command will not add more space than what is needed to make the natural length of the total vertical space equal to <replaceable>length</replaceable>. </para> <para>Use this command to adjust the vertical space above or below an -environment that starts a new paragraph. (For instance, a Theorem -environment is defined to begin and end in <literal>\addvspace{..}</literal> so -that two consecutive Theorem’s are separated by one vertical space, not -two.) +environment that starts a new paragraph. For instance, a Theorem +environment is defined to begin and end with <literal>\addvspace{...}</literal> +so that two consecutive Theorem’s are separated by one vertical space, +not two. </para> <para>This command is fragile (see <link linkend="_005cprotect">\protect</link>). </para> @@ -7298,23 +8135,20 @@ change that is to precede this command with a <literal>\par</literal> command. <para>These commands produce a given amount of space, specified by the document class. </para> -<variablelist><varlistentry><term><literal>\bigskip</literal> -</term><listitem><indexterm role="fn"><primary>\bigskip</primary></indexterm> -<indexterm role="fn"><primary>\bigskipamount</primary></indexterm> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\bigskip</primary></indexterm><literal>\bigskip</literal> +</term><listitem><indexterm role="fn"><primary>\bigskipamount</primary></indexterm> <para>The same as <literal>\vspace{\bigskipamount}</literal>, ordinarily about one line space, with stretch and shrink (the default for the <literal>book</literal> and <literal>article</literal> classes is <literal>12pt plus 4pt minus 4pt</literal>). </para> -</listitem></varlistentry><varlistentry><term><literal>\medskip</literal> -</term><listitem><indexterm role="fn"><primary>\medskip</primary></indexterm> -<indexterm role="fn"><primary>\medskipamount</primary></indexterm> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\medskip</primary></indexterm><literal>\medskip</literal> +</term><listitem><indexterm role="fn"><primary>\medskipamount</primary></indexterm> <para>The same as <literal>\vspace{\medskipamount}</literal>, ordinarily about half of a line space, with stretch and shrink (the default for the <literal>book</literal> and <literal>article</literal> classes is <literal>6pt plus 2pt minus 2pt</literal>). </para> -</listitem></varlistentry><varlistentry><term><literal>\smallskip</literal> -</term><listitem><indexterm role="fn"><primary>\smallskip</primary></indexterm> -<indexterm role="fn"><primary>\smallskipamount</primary></indexterm> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\smallskip</primary></indexterm><literal>\smallskip</literal> +</term><listitem><indexterm role="fn"><primary>\smallskipamount</primary></indexterm> <para>The same as <literal>\vspace{\smallskipamount}</literal>, ordinarily about a quarter of a line space, with stretch and shrink (the default for the <literal>book</literal> and <literal>article</literal> classes is <literal>3pt plus 1pt minus @@ -7370,9 +8204,13 @@ Lost Dog! <para>Add the vertical space <replaceable>length</replaceable>. This can be negative or positive, and is a rubber length (see <link linkend="Lengths">Lengths</link>). </para> -<para>&latex; removes the vertical space from <literal>\vfill</literal> at a page break, -that is, at the top or bottom of a page. The starred version -<literal>\vspace*{..}</literal> causes the space to stay. +<para>&latex; removes the vertical space from <literal>\vspace</literal> at a page +break, that is, at the top or bottom of a page. The starred version +<literal>\vspace*{...}</literal> causes the space to stay. +</para> +<para>If <literal>\vspace</literal> is used in the middle of a paragraph (i.e., in +horizontal mode), the space is inserted <emphasis>after</emphasis> the line with +the <literal>\vspace</literal> command. A new paragraph is not started. </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. @@ -7445,12 +8283,16 @@ argument. <!-- xxref --> <indexterm role="fn"><primary>lrbox</primary></indexterm> -<para><literal>\begin{lrbox}{cmd} text \end{lrbox}</literal> +<para>Synopsis: </para> -<para>This is the environment form of <literal>\sbox</literal>. +<screen>\begin{lrbox}{\<replaceable>cmd</replaceable>} + <replaceable>text </replaceable> +\end{lrbox} +</screen> +<para>This is the environment form of <link linkend="_005csbox"><literal>\sbox</literal></link>. </para> -<para>The text inside the environment is saved in the box <literal>cmd</literal>, which -must have been declared with <literal>\newsavebox</literal>. +<para>The <replaceable>text</replaceable> inside the environment is saved in the box <literal>\<replaceable>cmd</replaceable></literal>, +which must have been declared with <literal>\newsavebox</literal>. </para> </sect1> @@ -7508,9 +8350,13 @@ containing a paragraph-making environment, you should use a </para></listitem></varlistentry><varlistentry><term><replaceable>text</replaceable> </term><listitem><para>the text that goes inside the parbox. </para></listitem></varlistentry></variablelist> -<para>The optional <replaceable>position</replaceable> argument allows you to align either the -top or bottom line in the parbox with the baseline of the surrounding -text (default is top). +<para>By default &latex; will position vertically a parbox so its center +lines up with the center of the surrounding text line. When the +optional <replaceable>position</replaceable> argument is present and equal either to ‘<literal>t</literal>’ +or ‘<literal>b</literal>’, this allows you respectively to align either the top or +bottom line in the parbox with the baseline of the surrounding text. You +may also specify ‘<literal>m</literal>’ for <replaceable>position</replaceable> to get the default +behaviour. </para> <para>The optional <replaceable>height</replaceable> argument overrides the natural height of the box. </para> @@ -7536,16 +8382,16 @@ for this to work. <para>Synopsis: </para> -<screen>\raisebox{distance}[<replaceable>height</replaceable>][<replaceable>depth</replaceable>]{text} +<screen>\raisebox{<replaceable>distance</replaceable>}[<replaceable>height</replaceable>][<replaceable>depth</replaceable>]{<replaceable>text</replaceable>} </screen> <para>The <literal>\raisebox</literal> command raises or lowers <replaceable>text</replaceable>. The first mandatory argument specifies how high <replaceable>text</replaceable> is to be raised (or lowered if it is a negative amount). <replaceable>text</replaceable> itself is processed in LR mode. </para> -<para>The optional arguments <replaceable>height</replaceable> and <replaceable>depth</replaceable> are dimensions. -If they are specified, &latex; treats <replaceable>text</replaceable> as extending a -certain distance above the baseline (height) or below (depth), +<para>The optional arguments <replaceable>height</replaceable> and <replaceable>depth</replaceable> are dimensions. If +they are specified, &latex; treats <replaceable>text</replaceable> as extending a certain +distance above the baseline (<replaceable>height</replaceable>) or below (<replaceable>depth</replaceable>), ignoring its natural height and depth. </para> @@ -7614,11 +8460,13 @@ special meaning do not correspond to simple characters you can type. <indexterm role="cp"><primary>reserved characters</primary></indexterm> <indexterm role="cp"><primary>characters, reserved</primary></indexterm> - -<para>The following characters play a special role in &latex; and are called -“reserved characters” or “special characters”. +<indexterm role="cp"><primary>special characters</primary></indexterm> +<indexterm role="cp"><primary>characters, special</primary></indexterm> +<para>&latex; sets aside the following characters for special purposes (for +example, the percent sign <literal>%</literal> is for comments) so they are +called <firstterm>reserved characters</firstterm> or <firstterm>special characters</firstterm>. </para> -<screen># $ % & ~ _ ^ \ { } +<screen># $ % & { } _ ~ ^ \ </screen> <indexterm role="fn"><primary>\#</primary></indexterm> <indexterm role="fn"><primary>\$</primary></indexterm> @@ -7627,39 +8475,53 @@ special meaning do not correspond to simple characters you can type. <indexterm role="fn"><primary>\_</primary></indexterm> <indexterm role="fn"><primary>\{</primary></indexterm> <indexterm role="fn"><primary>\}</primary></indexterm> -<para>Whenever you write one of these characters into your file, &latex; -will do something special. If you simply want the character to be -printed as itself, include a <literal>\</literal> in front of the character. For -example, <literal>\$</literal> will produce <literal>$</literal> in your output. -</para> -<indexterm role="fn"><primary>\backslash</primary></indexterm> -<para>One exception to this rule is <literal>\</literal> itself, because <literal>\\</literal> has -its own special (context-dependent) meaning. A roman \ is produced by -typing <literal>$\backslash$</literal> in your file, and a typewriter <literal>\</literal> is -produced by using ‘<literal>\</literal>’ in a verbatim command (see <link linkend="verbatim">verbatim</link>). +<para>If you want a reserved character to be printed as itself, in the text +body font, for all but the final three characters in that list simply +put a backslash <literal>\</literal> in front of the character. Thus, +<literal>\$1.23</literal> will produce <literal>$1.23</literal> in your output. </para> <indexterm role="fn"><primary>\~</primary></indexterm> <indexterm role="fn"><primary>\^</primary></indexterm> -<para>Also, <literal>\~</literal> and <literal>\^</literal> place tilde and circumflex accents over -the following letter, as in õ and ô (see <link linkend="Accents">Accents</link>); to get -a standalone <literal>~</literal> or <literal>^</literal>, you can again use a verbatim -command. +<indexterm role="fn"><primary>\textbackslash</primary></indexterm> +<para>As to the last three characters, to get a tilde in the text body font +use <literal>\~{}</literal> (omitting the curly braces would result in the next +character receiving a tilde accent). Similarly, to get a get a text +body font circumflex use <literal>\^{}</literal>. A text body font backslash +results from <literal>\textbackslash{}</literal>. +</para> +<para>To produce the reserved characters in a typewriter font use +<literal>\verb!!</literal>, as below. </para> +<screen>\begin{center} + \# \$ \% \& \{ \} \_ \~{} \^{} \textbackslash \\ + \verb!# $ % & { } _ ~ ^ \! +\end{center} +</screen> +<para>In that example the double backslash <literal>\\</literal> is only there to +split the lines. +</para> + +</sect1> +<sect1 label="21.2" id="Symbols-by-font-position"> +<title>Symbols by font position</title> + <indexterm role="fn"><primary>\symbol</primary></indexterm> <indexterm role="cp"><primary>accessing any character of a font</primary></indexterm> +<indexterm role="cp"><primary>font symbols, by number</primary></indexterm> -<para>Finally, you can access any character of the current font once you -know its number by using the <literal>\symbol</literal> command. For example, the -visible space character used in the <literal>\verb*</literal> command has the code -decimal 32, so it can be typed as <literal>\symbol{32}</literal>. +<para>You can access any character of the current font using its number with +the <literal>\symbol</literal> command. For example, the visible space character +used in the <literal>\verb*</literal> command has the code decimal 32, so it can be +typed as <literal>\symbol{32}</literal>. </para> -<para>You can also specify octal numbers with <literal>'</literal> or hexadecimal numbers -with <literal>"</literal>, so the previous example could also be written as -<literal>\symbol{'40}</literal> or <literal>\symbol{"20}</literal>. +<para>You can also specify numbers in octal (base 8) by using a <literal>'</literal> +prefix, or hexadecimal (base 16) with a <literal>"</literal> prefix, so the previous +example could also be written as <literal>\symbol{'40}</literal> or +<literal>\symbol{"20}</literal>. </para> </sect1> -<sect1 label="21.2" id="Text-symbols"> +<sect1 label="21.3" id="Text-symbols"> <title>Text symbols</title> <indexterm role="cp"><primary>text symbols</primary></indexterm> @@ -7724,7 +8586,7 @@ and <literal>\dots</literal> also work in math mode. </term><term><indexterm role="fn"><primary>\textparagraph</primary></indexterm><literal>\textparagraph</literal> </term><listitem><indexterm role="cp"><primary>paragraph symbol</primary></indexterm> <indexterm role="cp"><primary>pilcrow</primary></indexterm> -<para>Paragraph sign (pilcrow). +<para>Paragraph sign (pilcrow): ¶. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\pounds</primary></indexterm><literal>\pounds</literal> </term><term><indexterm role="fn"><primary>\textsterling</primary></indexterm><literal>\textsterling</literal> @@ -7746,8 +8608,9 @@ and <literal>\dots</literal> also work in math mode. <para>Right (closing) quote: ’. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\S</primary></indexterm><literal>\S</literal> -</term><listitem><indexterm role="cp"><primary>section symbol</primary></indexterm> -<para>Section symbol. +</term><listitem><para>\itemx \textsection +<indexterm role="cp"><primary>section symbol</primary></indexterm> +Section sign: §. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\TeX</primary></indexterm><literal>\TeX</literal> </term><listitem><indexterm role="cp"><primary>&tex; logo</primary></indexterm> @@ -7808,8 +8671,8 @@ and <literal>\dots</literal> also work in math mode. <para><replaceable>letter</replaceable> in a circle, as in ®. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textcompwordmark</primary></indexterm><literal>\textcompwordmark</literal> -</term><term><indexterm role="fn"><primary>\textcapitalwordmark</primary></indexterm><literal>\textcapitalwordmark</literal> -</term><term><indexterm role="fn"><primary>\textascenderwordmark</primary></indexterm><literal>\textascenderwordmark</literal> +</term><term><indexterm role="fn"><primary>\textcapitalcompwordmark</primary></indexterm><literal>\textcapitalcompwordmark</literal> +</term><term><indexterm role="fn"><primary>\textascendercompwordmark</primary></indexterm><literal>\textascendercompwordmark</literal> </term><listitem><indexterm role="cp"><primary>composite word mark, in text</primary></indexterm> <indexterm role="cp"><primary>cap height</primary></indexterm> <indexterm role="cp"><primary>ascender height</primary></indexterm> @@ -7826,7 +8689,7 @@ has the ascender height. <indexterm role="cp"><primary>double dagger, in text</primary></indexterm> <para>Double dagger: <inlineequation><mathphrase>\ddag</mathphrase></inlineequation>. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textdollar (or <literal>$</literal>)</primary></indexterm><literal>\textdollar (or <literal>$</literal>)</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textdollar (or <literal>\$</literal>)</primary></indexterm><literal>\textdollar (or <literal>\$</literal>)</literal> </term><listitem><indexterm role="cp"><primary>dollar sign</primary></indexterm> <indexterm role="cp"><primary>currency, dollar</primary></indexterm> <para>Dollar sign: $. @@ -7872,7 +8735,7 @@ has the ascender height. </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textperiodcentered</primary></indexterm><literal>\textperiodcentered</literal> </term><listitem><indexterm role="cp"><primary>period, centered, in text</primary></indexterm> <indexterm role="cp"><primary>centered period, in text</primary></indexterm> -<para>Centered period: <inlineequation><mathphrase>\cdot</mathphrase></inlineequation>. +<para>Centered period: ·. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquestiondown (or <literal>?`</literal>)</primary></indexterm><literal>\textquestiondown (or <literal>?`</literal>)</literal> </term><listitem><indexterm role="cp"><primary>question mark, upside-down</primary></indexterm> @@ -7883,7 +8746,7 @@ has the ascender height. <indexterm role="cp"><primary>double left quote</primary></indexterm> <para>Double left quote: “. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotedblright (or <literal>'</literal>)</primary></indexterm><literal>\textquotedblright (or <literal>'</literal>)</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotedblright (or <literal>''</literal>)</primary></indexterm><literal>\textquotedblright (or <literal>''</literal>)</literal> </term><listitem><indexterm role="cp"><primary>right quote, double</primary></indexterm> <indexterm role="cp"><primary>double right quote</primary></indexterm> <para>Double right quote: ”. @@ -7898,6 +8761,12 @@ has the ascender height. <indexterm role="cp"><primary>single right quote</primary></indexterm> <para>Single right quote: ’. </para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotesingle</primary></indexterm><literal>\textquotesingle</literal> +</term><listitem><indexterm role="cp"><primary>quote, single straight</primary></indexterm> +<indexterm role="cp"><primary>straight single quote</primary></indexterm> +<indexterm role="cp"><primary>single quote, straight</primary></indexterm> +<para>Straight single quote. (From TS1 encoding.) +</para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\textquotestraightbase</primary></indexterm><literal>\textquotestraightbase</literal> </term><term><indexterm role="fn"><primary>\textquotestraightdblbase</primary></indexterm><literal>\textquotestraightdblbase</literal> </term><listitem><indexterm role="cp"><primary>quote, straight base</primary></indexterm> @@ -7922,7 +8791,7 @@ has the ascender height. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttrademark</primary></indexterm><literal>\texttrademark</literal> </term><listitem><indexterm role="cp"><primary>trademark symbol</primary></indexterm> -<para>Trademark symbol: <inlineequation><mathphrase>^{\hbox{TM}}</mathphrase></inlineequation>. +<para>Trademark symbol: ™. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\texttwelveudash</primary></indexterm><literal>\texttwelveudash</literal> </term><listitem><indexterm role="cp"><primary>two-thirds em-dash</primary></indexterm> @@ -7940,13 +8809,14 @@ has the ascender height. </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.3" id="Accents"> +<sect1 label="21.4" id="Accents"> <title>Accents</title> <indexterm role="cp"><primary>accents</primary></indexterm> <indexterm role="cp"><primary>characters, accented</primary></indexterm> <indexterm role="cp"><primary>letters, accented</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> <indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> <indexterm role="cp"><primary>multilingual support</primary></indexterm> <para>&latex; has wide support for many of the world’s scripts and @@ -8105,16 +8975,19 @@ See also <literal>\b</literal> above. </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.4" id="Non_002dEnglish-characters"> -<title>Non-English characters</title> +<sect1 label="21.5" id="Additional-Latin-letters"> +<title>Additional Latin letters</title> +<anchor id="Non_002dEnglish-characters"/><indexterm role="cp"><primary>Latin letters, additional</primary></indexterm> +<indexterm role="cp"><primary>letters, additional Latin</primary></indexterm> +<indexterm role="cp"><primary>extended Latin</primary></indexterm> <indexterm role="cp"><primary>special characters</primary></indexterm> <indexterm role="cp"><primary>non-English characters</primary></indexterm> <indexterm role="cp"><primary>characters, non-English</primary></indexterm> -<indexterm role="cp"><primary>letters, non-English</primary></indexterm> -<para>Here are the basic &latex; commands for inserting characters commonly -used in languages other than English. +<para>Here are the basic &latex; commands for inserting letters (beyond +A–Z) extending the Latin alphabet, used primarily in languages other +than English. </para> <variablelist><varlistentry><term><literal>\aa</literal> </term><term><literal>\AA</literal> @@ -8136,13 +9009,17 @@ used in languages other than English. <indexterm role="fn"><primary>\DH (Ð)</primary></indexterm> <indexterm role="cp"><primary>Icelandic eth</primary></indexterm> <indexterm role="cp"><primary>eth, Icelandic letter</primary></indexterm> -<para>Icelandic letter eth: ð and Ð. +<para>Icelandic letter eth: ð and Ð. Not available with OT1 +encoding, you need the <filename>fontenc</filename> package to select an alternate +font encoding, such as T1. </para> </listitem></varlistentry><varlistentry><term><literal>\dj</literal> </term><term><literal>\DJ</literal> </term><listitem><indexterm role="fn"><primary>\dj</primary></indexterm> <indexterm role="fn"><primary>\DJ</primary></indexterm> -<para>Crossed d and D, a.k.a. capital and small letter d with stroke. +<para>Crossed d and D, a.k.a. capital and small letter d with stroke. Not +available with OT1 encoding, you need the <filename>fontenc</filename> package to +select an alternate font encoding, such as T1. </para> </listitem></varlistentry><varlistentry><term><literal>\ij</literal> </term><term><literal>\IJ</literal> @@ -8162,7 +9039,7 @@ used in languages other than English. </term><term><literal>\NG</literal> </term><listitem><indexterm role="fn"><primary>\ng</primary></indexterm> <indexterm role="fn"><primary>\NG</primary></indexterm> -<para>Latin letter eng, also used in phonetics. +<para>Lappish letter eng, also used in phonetics. </para> </listitem></varlistentry><varlistentry><term><literal>\o</literal> </term><term><literal>\O</literal> @@ -8192,12 +9069,14 @@ used in languages other than English. <indexterm role="fn"><primary>\TH (Þ)</primary></indexterm> <indexterm role="cp"><primary>Icelandic thorn</primary></indexterm> <indexterm role="cp"><primary>thorn, Icelandic letter</primary></indexterm> -<para>Icelandic letter thorn: þ and Þ. +<para>Icelandic letter thorn: þ and Þ. Not available with OT1 +encoding, you need the <filename>fontenc</filename> package to select an alternate +font encoding, such as T1. </para> </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.5" id="_005crule"> +<sect1 label="21.6" id="_005crule"> <title><literal>\rule</literal></title> <indexterm role="fn"><primary>\rule</primary></indexterm> @@ -8220,18 +9099,30 @@ rectangles. The arguments are: </para></listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.6" id="_005ctoday"> +<sect1 label="21.7" id="_005ctoday"> <title><literal>\today</literal></title> <indexterm role="fn"><primary>\today</primary></indexterm> <indexterm role="cp"><primary>date, today’s</primary></indexterm> <para>The <literal>\today</literal> command produces today’s date, in the format -‘<literal><replaceable>month</replaceable> <replaceable>dd</replaceable>, <replaceable>yyyy</replaceable></literal>’; for example, ‘July 4, 1976’. +‘<literal><replaceable>month</replaceable> <replaceable>dd</replaceable>, <replaceable>yyyy</replaceable></literal>’; for example, ‘<literal>July 4, 1976</literal>’. It uses the predefined counters <literal>\day</literal>, <literal>\month</literal>, and <literal>\year</literal> (see <link linkend="_005cday-_005cmonth-_005cyear">\day \month \year</link>) to do this. It is not updated as the program runs. </para> +<para>Multilingual packages like <filename>babel</filename> or classes like <filename>lettre</filename>, +among others, will localize <literal>\today</literal>. For example, the following +will output ‘<literal>4 juillet 1976</literal>’: +</para> +<screen>\year=1976 \month=7 \day=4 +\documentclass{minimal} +\usepackage[french]{babel} +\begin{document} +\today +\end{document} +</screen> +<indexterm role="cp"><primary>package, <literal>datetime</literal></primary></indexterm> <indexterm role="cp"><primary><literal>datetime</literal> package</primary></indexterm> <para>The <literal>datetime</literal> package, among others, can produce a wide variety of other date formats. @@ -8248,7 +9139,10 @@ of other date formats. <para>A large document requires a lot of input. Rather than putting the whole input in a single large file, it’s more efficient to split it into several smaller ones. Regardless of how many separate files you use, -there is one that is the root file; it is the one whose name you type +there is one that is the +<indexterm role="cp"><primary>root file</primary></indexterm> +<indexterm role="cp"><primary>file, root</primary></indexterm> +<firstterm>root file</firstterm>; it is the one whose name you type when you run &latex;. </para> <para>See <link linkend="filecontents">filecontents</link>, for an environment that allows bundling an @@ -8272,7 +9166,7 @@ command executes <literal>\clearpage</literal> to start a new page </para> <para>Given an <literal>\includeonly</literal> command, the <literal>\include</literal> actions are only run if <replaceable>file</replaceable> is listed as an argument to -<literal>\includeonly</literal>. See the next section. +<literal>\includeonly</literal>. See <link linkend="_005cincludeonly">\includeonly</link>. </para> <indexterm role="cp"><primary>nested <literal>\include</literal>, not allowed</primary></indexterm> <para>The <literal>\include</literal> command may not appear in the preamble or in a file @@ -8291,9 +9185,9 @@ read by another <literal>\include</literal> command. </screen> <para>The <literal>\includeonly</literal> command controls which files will be read by subsequent <literal>\include</literal> commands. The list of filenames is -comma-separated. Each <replaceable>file</replaceable> must exactly match a filename -specified in a <literal>\include</literal> command for the selection to be -effective. +comma-separated. Each element <replaceable>file1</replaceable>, <replaceable>file2</replaceable>, … must +exactly match a filename specified in a <literal>\include</literal> command for the +selection to be effective. </para> <para>This command can only appear in the preamble. </para> @@ -8360,11 +9254,15 @@ as for the table of contents. <sect2 label="23.1.1" id="_005caddcontentsline"> <title><literal>\addcontentsline</literal></title> -<indexterm role="fn"><primary>\addcontentsline{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm> +<indexterm role="fn"><primary>\addcontentsline</primary></indexterm> <indexterm role="cp"><primary>table of contents entry, manually adding</primary></indexterm> -<para>The <literal>\addcontentsline</literal>{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>} -command adds an entry to the specified list or table where: +<para>Synopsis: +</para> +<screen>\addcontentsline{<replaceable>ext</replaceable>}{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>} +</screen> +<para>The <literal>\addcontentsline</literal> command adds an entry to the specified list +or table where: </para> <variablelist><varlistentry><term><replaceable>ext</replaceable> </term><listitem><para>The extension of the file on which information is to be written, @@ -8379,16 +9277,17 @@ following, matching the value of the <replaceable>ext</replaceable> argument: </term><listitem><para>The name of the sectional unit: <literal>part</literal>, <literal>chapter</literal>, <literal>section</literal>, <literal>subsection</literal>, <literal>subsubsection</literal>. </para></listitem></varlistentry><varlistentry><term><literal>lof</literal> -</term><listitem><para>For the list of figures. +</term><listitem><para>For the list of figures: <literal>figure</literal>. </para></listitem></varlistentry><varlistentry><term><literal>lot</literal> -</term><listitem><para>For the list of tables. +</term><listitem><para>For the list of tables: <literal>table</literal>. </para></listitem></varlistentry></variablelist> -</listitem></varlistentry><varlistentry><term><replaceable>entry</replaceable> +</listitem></varlistentry><varlistentry><term><replaceable>text</replaceable> </term><listitem><para>The text of the entry. </para></listitem></varlistentry></variablelist> <indexterm role="fn"><primary>\contentsline</primary></indexterm> -<para>What is written to the <filename>.<replaceable>ext</replaceable></filename> file is the -command <literal>\contentsline{<replaceable>unit</replaceable>}{<replaceable>name</replaceable>}</literal>. +<para>What is written to the <filename>.<replaceable>ext</replaceable></filename> file is the command +<literal>\contentsline{<replaceable>unit</replaceable>}{<replaceable>text</replaceable>}{<replaceable>num</replaceable>}</literal>, where +<literal><replaceable>num</replaceable></literal> is the current value of counter <literal><replaceable>unit</replaceable></literal>. </para> <!-- xx how hardwired are these values? other unit names? --> @@ -8450,7 +9349,7 @@ the preamble. <indexterm role="fn"><primary>\index</primary></indexterm> <indexterm role="cp"><primary><filename>.idx</filename> file</primary></indexterm> <para>The command <literal>\index{<replaceable>text</replaceable>}</literal> writes an index entry for -<replaceable>text</replaceable> to an auxiliary file with the <filename>.idx</filename> extension. +<replaceable>text</replaceable> to an auxiliary file named with the <filename>.idx</filename> extension. </para> <indexterm role="fn"><primary>\indexentry</primary></indexterm> <para>Specifically, what gets written is the command @@ -8479,22 +9378,25 @@ multi-lingual) <command>xindy</command> (<ulink url="http://xindy.sourceforge.ne This results in a <filename>.ind</filename> file, which can then be read to typeset the index. </para> -<indexterm role="fn"><primary>printindex</primary></indexterm> +<indexterm role="fn"><primary>\printindex</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>makeidx</literal></primary></indexterm> <indexterm role="cp"><primary><literal>makeidx</literal> package</primary></indexterm> <para>The index is usually generated with the <literal>\printindex</literal> command. This is defined in the <literal>makeidx</literal> package, so <literal>\usepackage{makeidx}</literal> needs to be in the preamble. </para> -<indexterm role="fn"><primary>indexspace</primary></indexterm> +<indexterm role="fn"><primary>\indexspace</primary></indexterm> <para>The rubber length <literal>\indexspace</literal> is inserted before each new letter in the printed index; its default value is ‘<literal>10pt plus5pt minus3pt</literal>’. </para> +<indexterm role="cp"><primary>package, <literal>showidx</literal></primary></indexterm> <indexterm role="cp"><primary><literal>showidx</literal> package</primary></indexterm> <para>The <literal>showidx</literal> package causes each index entries to be shown in the margin on the page where the entry appears. This can help in preparing the index. </para> +<indexterm role="cp"><primary>package, <literal>multind</literal></primary></indexterm> <indexterm role="cp"><primary><literal>multind</literal> package</primary></indexterm> <para>The <literal>multind</literal> package supports multiple indexes. See also the &tex; FAQ entry on this topic, @@ -8520,7 +9422,7 @@ preparing the index. <replaceable>letter body</replaceable> \closing{<replaceable>closing text</replaceable>} \end{letter} - ... more letters ... +... more letters ... \end{document} </screen> <para>Produce one or more letters. @@ -8546,13 +9448,13 @@ backslash (<literal>\\</literal>). &latex; will put the <replaceable>sende under the closing, after a vertical space for the traditional hand-written signature; it also can contain multiple lines. </para> -<para>Each letter environment begins with a required <literal>\opening</literal> command +<para>Each <literal>letter</literal> environment body begins with a required <literal>\opening</literal> command such as <literal>\opening{Dear Madam or Sir:}</literal>. The <replaceable>letter body</replaceable> -text is ordinary &latex; so it can contain everything from from +text is ordinary &latex; so it can contain everything from enumerated lists to displayed math, except that commands such as <literal>\chapter</literal> that make no sense in a letter are turned off. Each -letter environment typically ends with a <literal>\closing</literal> command such as -<literal>\closing{Yours,}</literal>. +<literal>letter</literal> environment body typically ends with a <literal>\closing</literal> +command such as <literal>\closing{Yours,}</literal>. </para> <indexterm role="fn"><primary>\\ for letters</primary></indexterm> <para>Additional material may come after the <literal>\closing</literal>. You can say who @@ -8629,12 +9531,12 @@ formatted as a personal letter. <para>Synopsis: </para> <screen>\cc{<replaceable>first name</replaceable> \\ - .. } + ... } </screen> <para>Produce a list of names to which copies of the letter were sent. This command is optional. If it appears then typically it comes after <literal>\closing</literal>. Separate multiple lines with a double -backslash <literal>\\</literal>. +backslash <literal>\\</literal>, as in: </para> <screen>\cc{President \\ Vice President} @@ -8650,7 +9552,7 @@ backslash <literal>\\</literal>. <para>Synopsis: </para> -<screen>\closing{text} +<screen>\closing{<replaceable>text</replaceable>} </screen> <para>Usually at the end of a letter, above the handwritten signature, there is a <literal>\closing</literal> (although this command is optional). For example, @@ -8668,7 +9570,7 @@ is a <literal>\closing</literal> (although this command is optional). For examp <para>Synopsis: </para> <screen>\encl{<replaceable>first enclosed object</replaceable> \\ - .. } + ... } </screen> <para>Produce a list of things included with the letter. This command is optional; when it is used, it typically is put after <literal>\closing</literal>. @@ -8718,6 +9620,8 @@ address</replaceable>). The <replaceable>sender address</replaceable> is the val in the argument to the <literal>letter</literal> environment. By default <literal>\mlabel</literal> ignores the first argument, the <replaceable>sender address</replaceable>. </para> +<!-- xxx TODO, align on latex2e-fr.texi, see https://mail.gna.org/public/latexrefman-discuss/2015-10/msg00000.html --> + </sect1> <sect1 label="24.7" id="_005cname"> <title><literal>\name</literal></title> @@ -8744,7 +9648,7 @@ return address. <screen>\opening{<replaceable>text</replaceable>} </screen> <para>This command is required. It starts a letter, following the -<literal>\begin{letter}{..}</literal>. The mandatory argument <replaceable>text</replaceable> is the +<literal>\begin{letter}{...}</literal>. The mandatory argument <replaceable>text</replaceable> is the text that starts your letter. For instance: </para> <screen>\opening{Dear John:} @@ -8763,7 +9667,7 @@ text that starts your letter. For instance: <para>Add a postscript. This command is optional and usually is used after <literal>\closing</literal>. </para> -<screen>\ps{P.S. After you have read this letter, burn it. Or eat it.} +<screen>\ps{P.S. After you have read this letter, burn it. Or eat it.} </screen> </sect1> @@ -8773,7 +9677,7 @@ text that starts your letter. For instance: <para>Synopsis: </para> <screen>\signature{<replaceable>first line</replaceable> \\ - .. } + ... } </screen> <indexterm role="fn"><primary>\signature</primary></indexterm> @@ -8853,13 +9757,13 @@ page. <para>Synopsis: </para> -<screen>\typein[<replaceable>\cmd</replaceable>]{<replaceable>msg</replaceable>} +<screen>\typein[\<replaceable>cmd</replaceable>]{<replaceable>msg</replaceable>} </screen> <para><literal>\typein</literal> prints <replaceable>msg</replaceable> on the terminal and causes &latex; to stop and wait for you to type a line of input, ending with return. If -the optional <replaceable>\cmd</replaceable> argument is omitted, the typed input is +the optional <literal>\<replaceable>cmd</replaceable></literal> argument is omitted, the typed input is processed as if it had been included in the input file in place of the -<literal>\typein</literal> command. If the <replaceable>\cmd</replaceable> argument is present, it +<literal>\typein</literal> command. If the <literal>\<replaceable>cmd</replaceable></literal> argument is present, it must be a command name. This command name is then defined or redefined to be the typed input. </para> @@ -9002,6 +9906,7 @@ The end. <ulink url="http://tug.org/TUGboat">http://tug.org/TUGboat</ulink>. </para> <screen>\documentclass{ltugboat} + \usepackage{graphicx} \usepackage{ifpdf} \ifpdf @@ -9010,6 +9915,8 @@ The end. \usepackage{url} \fi +%%% Start of metadata %%% + \title{Example \TUB\ article} % repeat info for each author. @@ -9018,51 +9925,56 @@ The end. \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, from +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 for active urls in the \acro{PDF} output. -Nowadays \TUB\ is produced using \acro{PDF} files exclusively. - -The \texttt{ltugboat} class provides these abbreviations and many more: +\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 -\Mc \mf \MFB \mtex \PCTeX \pcTeX -\PiC \PiCTeX \plain \POBox \PS -\SC \SGML \SliTeX \TANGLE \TB \TP +\mf \MFB +\plain \POBox \PS +\SGML \TANGLE \TB \TP \TUB \TUG \tug -\UG \UNIX \VAX \XeT \WEB \WEAVE +\UNIX \XeT \WEB \WEAVE -\Dash \dash \vellipsis \bull \cents \Dag -\careof \thinskip +\, \bull \Dash \dash \hyph \acro{FRED} -> {\small[er] fred} % please use! \cs{fred} -> \fred -\env{fred} -> \begin{fred} \meta{fred} -> <fred> \nth{n} -> 1st, 2nd, ... \sfrac{3/4} -> 3/4 \booktitle{Book of Fred} \end{verbatim} -For more information, see the ltubguid document at: -\url{http://mirror.ctan.org/macros/latex/contrib/tugboat} -(we recommend using \verb|mirror.ctan.org| for \CTAN\ references). +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. |